POST /reversals

Guide
Send a sale request followed by the reversal request
Copy the data present under SaleToPOIData field from Sale response and paste under SaleToPOIData field in reversal request
Based on the response from the terminal, the POS Cloud will send back the response

Step 1 - Request

Code Snippet

Data Dictionary

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",
    "currency": "GBP",
    "requested_amount": "50.79",
    "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
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 Snippet

Data Dictionary

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

{
    "result": "SUCCESS",
    "transaction_id": "Q5YLK2EGN9Y26EKX",
    "data": {
        "site_branch_id": "London",
        "pos_location": "POS-25",
        "terminal_id": "T650M-451-962-212-MOHSIN",
        "operator_id": "573856",
        "requested_amount": "50.79",
        "currency": "GBP",
        "original_transaction_id": "15JQWENNEREZ7MQX",
        "original_transaction_timestamp": "2025-03-05T10:28:21+01:00",
        "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.
data	json	Return the payload from the request.

Errors

400 Bad Request

Missing authorization header

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

{
    "result": "FAILURE",
    "message": "Request validation failed",
    "errors": {
        "Authorization": "Authorization is required and cannot be empty."
    }
}

Missing currency

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

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

Missing original_transaction_id

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

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

Missing POS_location

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

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

Missing request_timestamp

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

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

Missing requested_amount

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

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

Missing site_branch_id

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

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

Missing terminal_id

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

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

401 Unauthorized

Acquirer token not found

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

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

Invalid acquirer token

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

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

Invalid authorization header

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

{
    "result": "FAILURE",
    "message": "Request 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

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

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

422 Unprocessable Entity

Invalid currency

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

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

Invalid metadata

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

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

Invalid operator_id

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

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

Invalid original_transaction_id

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

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

Invalid POS_location

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

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

Invalid request_timestamp

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

{
    "result": "FAILURE",
    "message": "Request 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

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

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

Invalid site_branch_id

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

{
    "result": "FAILURE",
    "message": "Request 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

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

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

500 Internal Server Error

Generic error

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