---
title: "POST /reversals"
slug: "post-reversals"
updated: 2025-09-19T14:29:15Z
published: 2025-09-19T14:29:15Z
canonical: "api-docs.blinkpayment.co.uk/post-reversals"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://api-docs.blinkpayment.co.uk/llms.txt
> Use this file to discover all available pages before exploring further.

# POST /reversals

This API endpoint reverses a sales transaction. It accepts the original transaction ID and reverses the **full amount** of the sale. The response shows a **new** transaction ID and the amount reversed.

> [!NOTE]
> ## Guide
> 
> 1. Send a **POST sales** request
> 2. Send a **POST reversals** request

## Step 1 - Request

Code SnippetData Dictionary

```json
POST /v1/card-present/reversals HTTP/1.1                         
Host: api.blinkpayment.co.uk                     
Content-Type: application/json
Authorization: Basic ACCESS_TOKEN    # from Blink pos_api_key:pos_api_secret
User-Agent: AcmeApp/1.2.0 (ReactNative; Android 11+; POS2.0+; Build/123)

{
    "site_branch_id": "London",
    "pos_location": "POS-25",
    "terminal_id": "T650M-451-962-212-MOHSIN",
    "operator_id": "137647",
    "original_transaction_id": "15JQWENNEREZ7MQX",
    "request_timestamp": "2025-03-05T10:28:38+01:00",
    "metadata": {
        "order_number": "7036171099"
    }
}
```

| **Field Name** | **Type** | **Description** | **Nullable** |
| --- | --- | --- | --- |
| **Authorization (header)** | varchar(512) | Authorization header for authenticating the request made up of **pos_api_key** and **pos_api_secret**. (e.g., `Basic ZjdkNDcxNjYtMThhYy00????`) | NO |
| **Content-type (header)** | varchar(50) | `application/json` | NO |
| **User-Agent (header)** | varchar(255) | A brief overview of the app or software, version and comments related to the software stack and minimum client specifications. e.g. `AcmeApp/1.2.0 (ReactNative; iOS 15+; iPhone 12+; Android 11+; Build/12345)` | NO |
| **site_branch_id** | varchar(16) | Site or branch ID (e.g., `London - Oxford Street`) | NO |
| **pos_location** | varchar(16) | POS identifier (e.g., `POS 5`) | NO |
| **terminal_id** | varchar(35) | Unique terminal ID made up of model and serial number. (e.g., `"T650m-451-962-212"`) | NO |
| **operator_id** | varchar(255) | ID of the operator (e.g., user, staff member) who processed the payment. (e.g., `440010051-Mohsin`, numeric (16)) | YES |
| **customer_order_details** | varchar(255) | Contains order-specific details in JSON format | YES |
| **original_transaction_id** | varchar(50) | Original Transaction ID of the sales API | NO |
| **original_transaction_timestamp** | datetime | Original Transaction timestamp of the sales API must be a valid ISO 8601 datetime string (e.g., `2025-02-02T14:43:59+01:00`) | NO |
| **request_timestamp** | datetime | The request_timestamp must be a valid ISO 8601 datetime string (e.g., `2025-02-02T14:43:59+01:00`) | NO |
| **metadata** | json(1024) | Optional field that can be used for debugging, filtering linking to other systems. It contains custom vendor, POS, customer or order details in JSON format. (e.g. `{"note": "Refund for overcharge"}`, `{"salesforce_id": "SF123456"}`, `{"server": "dev"}`, `{"partner": "Shopify", "order_id": "98765"}`) | YES |

## Step 2 - Response

Code SnippetData Dictionary

```json
HTTP/1.1 201 Created
Content-Type: application/json

{
    "result": "SUCCESS",
    "transaction_id": "Q5YLK2EGN9Y26EKX",
    "reversed_amount": "50.79",  
    "data": {
        "site_branch_id": "London",
        "pos_location": "POS-25",
        "terminal_id": "T650M-451-962-212-MOHSIN",
        "operator_id": "137647",
        "original_transaction_id": "15JQWENNEREZ7MQX",
        "request_timestamp": "2025-03-05T10:28:38+01:00",
        "metadata": {
            "order_number": "7036171099"
        }
    }
}
```

| Field Name | Type | Description |
| --- | --- | --- |
| **result** | varchar(10) | `SUCCESS` or `FAILURE` |
| **transaction_id** | varchar(50) | Unique identifier for the pre-auth transaction. |
| **reversed_amount** | decimal(8,2) | Reversed amount between 0.01 and 999,999.99. This is the exact amount of the sale. The **full amount** of the sale will be reversed. |
| **data** | json | Return the payload from the request. |

## Errors

## **400 Bad Request**

### **Missing authorization header**

```json
HTTP/1.1 400 Bad Request  
Content-Type: application/json  

{
    "result": "FAILURE",
    "message": "Field validation failed",
    "errors": {
        "Authorization": "The Authorization header is required and must be provided in the format: Basic <encoded_api_key:secret_key>."
    }
}
```

### **Missing original_transaction_id**

```json
HTTP/1.1 400 Bad Request  
Content-Type: application/json  

{
    "result": "FAILURE",
    "message": "Field validation failed",
    "errors": {
        "original_transaction_id": "The original_transaction_id field is required and cannot be empty."
    }
}
```

### **Missing POS_location**

```json
HTTP/1.1 400 Bad Request  
Content-Type: application/json  

{
    "result": "FAILURE",
    "message": "Field validation failed",
    "errors": {
        "pos_location": "The pos_location field is required and cannot be empty."
    }
}
```

### **Missing request_timestamp**

```json
HTTP/1.1 400 Bad Request  
Content-Type: application/json  

{
    "result": "FAILURE",
    "message": "Field validation failed",
    "errors": {
        "request_timestamp": "The request_timestamp field is required and cannot be empty."
    }
}
```

### **Missing site_branch_id**

```json
HTTP/1.1 400 Bad Request  
Content-Type: application/json  

{
    "result": "FAILURE",
    "message": "Field validation failed",
    "errors": {
        "site_branch_id": "The site_branch_id field is required and cannot be empty."
    }
}
```

### **Missing terminal_id**

```json
HTTP/1.1 400 Bad Request  
Content-Type: application/json  

{
    "result": "FAILURE",
    "message": "Field validation failed",
    "errors": {
        "terminal_id": "The terminal_id field is required and cannot be empty."
    }
}
```

## **401 Unauthorized**

### **Acquirer token not found**

```json
HTTP/1.1 401 Unauthorized  
Content-Type: application/json  

{
    "result": "FAILURE",
    "message": "Field validation failed",
    "errors": {
        "acquirer_token": "The acquirers_token was not found in our system. Please contact the support team."
    }
}
```

### **Invalid acquirer token**

```json
HTTP/1.1 401 Unauthorized  
Content-Type: application/json  

{
    "result": "FAILURE",
    "message": "Field validation failed",
    "errors": {
        "acquirer_token": "The acquirers_token provided is invalid in our system. Please contact the support team."
    }
}
```

### **Invalid authorization header**

```json
HTTP/1.1 401 Unauthorized  
Content-Type: application/json  

{
    "result": "FAILURE",
    "message": "Field validation failed",
    "errors": {
        "Authorization": "The provided Authorization header is invalid. Ensure it follows the correct format: Basic <encoded api_key:secret_key>."
    }
}
```

## **403 Forbidden**

### **API key or secret key is invalid**

```json
HTTP/1.1 403 Forbidden  
Content-Type: application/json

{
    "result": "FAILURE",
    "message": "Field validation failed",
    "errors": {
        "Authorization": "The provided api_key or secret_key is invalid. Please ensure the credentials are correct and try again."
    }
}
```

## **404 Not Found**

### **Invalid terminal_id**

```json
HTTP/1.1 404 Not Found
Content-Type: application/json  
{
    "result": "FAILURE",
    "message": "Field validation failed",
    "errors": {
        "terminal_id": "The terminal_id provided is invalid in our system. Please contact the support team."
    }
}
```

### **Invalid original_transaction_id**

```json
HTTP/1.1 404 Not Found
Content-Type: application/json  
{
    "result": "FAILURE",
    "message": "Field validation failed",
    "errors": {
        "original_transaction_id": "The original_transaction_id is invalid. Please try again."
    }
}
```

## **409 Conflict**

### **Reversal on preauth completions not allowed**

```json
HTTP/1.1 409 Conflict  
Content-Type: application/json

{
    "result": "FAILURE",
    "message": "Field validation failed",
    "errors": {
        "original_transaction_id": "Reversal is not allowed for completed pre-auth transactions. Please issue a refund instead."
    }
}
```

### **422 Unprocessable Entity**

### **Invalid metadata**

```json
HTTP/1.1 422 Unprocessable Entity  
Content-Type: application/json

{
    "result": "FAILURE",
    "message": "Field validation failed",
    "errors": {
        "metadata": "The metadata must be a valid JSON-formatted string with a maximum length of 1024 characters."
    }
}
```

### **Invalid operator_id**

```json
HTTP/1.1 422 Unprocessable Entity  
Content-Type: application/json

{
    "result": "FAILURE",
    "message": "Field validation failed",
    "errors": {
        "operator_id": "The operator_id must be a valid string with a maximum length of 255 characters."
    }
}
```

### **Invalid original_transaction_id**

```json
HTTP/1.1 422 Unprocessable Entity  
Content-Type: application/json  

{
    "result": "FAILURE",
    "message": "Field validation failed",
    "errors": {
        "original_transaction_id": "The original_transaction_id must be a valid string with a maximum length of 255 characters."
    }
}
```

### **Invalid POS_location**

```json
HTTP/1.1 422 Unprocessable Entity  
Content-Type: application/json

{
    "result": "FAILURE",
    "message": "Field validation failed",
    "errors": {
        "pos_location": "The pos_location must be a valid string with a maximum length of 16 characters."
    }
}
```

### **Invalid request_timestamp**

```json
HTTP/1.1 422 Unprocessable Entity  
Content-Type: application/json

{
    "result": "FAILURE",
    "message": "Field validation failed",
    "errors": {
        "request_timestamp": "The request_timestamp must be a valid ISO 8601 date (e.g., '2024-02-18T12:34:56')."
    }
}
```

### **Invalid site_branch_id**

```json
HTTP/1.1 422 Unprocessable Entity  
Content-Type: application/json

{
    "result": "FAILURE",
    "message": "Field validation failed",
    "errors": {
        "site_branch_id": "The site_branch_id must be a valid string with a maximum length of 16 characters."
    }
}
```

### **Invalid terminal_id**

```json
HTTP/1.1 422 Unprocessable Entity  
Content-Type: application/json

{
    "result": "FAILURE",
    "message": "Field validation failed",
    "errors": {
        "terminal_id": "The terminal_id must be a valid string with a maximum length of 35 characters."
    }
}
```

## **500 Internal Server Error**

### **Lost connection to the terminal**

```json
HTTP/1.1 500 Internal Server Error  
Content-Type: application/json

{
    "result": "FAILURE",
    "message": "Something went wrong on our end.",
    "errors": {
        "We're experiencing an issue with our server, but rest assured our team is already working to resolve it. Please try again, and we apologize for the inconvenience."
    }
}
```

## **503 Service Unavailable**

### **Lost connection to the terminal**

```json
HTTP/1.1 503 Service Unavailable
Content-Type: application/json

{
    "result": "FAILURE",
    "message": "Lost connection",
    "errors": {
        "terminal_id": "The connection to the terminal was lost. Please try again."
    }
}
```

### **Transaction cancelled - operation timeout**

```json
HTTP/1.1 503 Service Unavailable
Content-Type: application/json

{
    "result": "FAILURE",
    "message": "Transaction cancelled - operation timeout",
    "errors": {
        "terminal_id": "The transaction was cancelled due to operation timeout. Please try again."
    }
}
```

### **Terminal disconnected**

```json
HTTP/1.1 503 Service Unavailable
Content-Type: application/json

{
    "result": "FAILURE",
    "message": "Terminal unreachable",
    "errors": {
        "terminal_id": "The terminal is currently offline or unreachable. Please try again."
    }
}
```