---
title: "POST /refunds"
slug: "post-refunds-1"
updated: 2025-09-19T14:33:57Z
published: 2025-09-19T14:33:57Z
canonical: "api-docs.blinkpayment.co.uk/post-refunds-1"
---

> ## 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 /refunds

> [!NOTE]
> ## Guide
> 
> 1. Send a sale request followed by the reversal request
> 2. Copy the data present under SaleToPOIData field from Sale response and paste under SaleToPOIData field in reversal request
> 3. Based on the response from the terminal, the POS Cloud will send back the response

## Step 1 - Request

Code SnippetData Dictionary

```json
POST /v1/card-present/refunds 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": "T650P-451-863-867-MADAN",
  "operator_id": "12345",
  "order_number": "5443246927",
  "metadata": {},
  "currency": "GBP",
  "requested_amount": "26.32",
  "request_timestamp": "2025-06-19T13:29:17+01:00"
}
```

| **Field Name** | **Type** | **Description** | **Nullable** |
| --- | --- | --- | --- |
| **Content-Type (header)** | varchar(50) | `application/json` | NO |
| **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 |
| **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; Android 11+; POS2.0+; Build/123)` | 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 |
| **order_number** | varchar(16) | Optional field that can be used by client to send a reference string value. (e.g,. 841754987AB) | YES |
| **currency** | varchar(3) | The currency must be a valid ISO 4217 code (e.g., `GBP`, `USD`, `EUR`). | NO |
| **requested_amount** | decimal(8,2) | Requested amount must be between `0.01` and `999,999.99` | 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": "5443246927",
    "card_type": "MasterCard",
    "card_number": "52993074****5859",
    "card_mode": "CONTACTLESS",
    "data": {
        "site_branch_id": "London",
        "pos_location": "POS-25",
        "terminal_id": "T650P-451-863-867-MADAN",
        "operator_id": "12345",
        "order_number": "5443246927",
        "metadata": {},
        "currency": "GBP",
        "requested_amount": "26.32",
        "request_timestamp": "2025-06-19T13:29:17+01:00"
    }
}
```

| Field Name | Type | Description |
| --- | --- | --- |
| **result** | varchar(10) | `SUCCESS` or `FAILURE` |
| **transaction_id** | varchar(50) | Unique identifier for the pre-auth transaction. |
| **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 currency**

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

{
    "result": "FAILURE",
    "message": "Field validation failed",
    "errors": {
        "currency": "The currency 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 requested_amount**

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

{
    "result": "FAILURE",
    "message": "Field validation failed",
    "errors": {
        "requested_amount": "The requested_amount 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."
    }
}
```

### **422 Unprocessable Entity**

### **Invalid currency**

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

{
    {
    "result": "FAILURE",
    "message": "Field validation failed",
    "errors": {
        "currency": "The currency must be a valid ISO 4217 code (e.g., GBP, USD, EUR)."
    }
}
```

### **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 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 requested_amount**

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

{
    "result": "FAILURE",
    "message": "Field validation failed",
    "errors": {
        "requested_amount": "The requested_amount must be between 0.01 and 999999.99."
    }
}
```

### **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."
    }
}
```

## **429 Too Many Request**

### **Terminal busy**

```json
HTTP/1.1 429 Too Many Requests 
Content-Type: application/json

{
    "result": "FAILURE",
    "message": "Terminal is busy",
    "errors": {
        "terminal_id": "The terminal is busy processing another request. Please try again later."
    }
}
```

## **500 Internal Server Error**

### **Generic error**

```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."
    }
}
```