POST /reversals

  • Updated on Sep 19, 2025
  • Published on Mar 31, 2025
  • 6 minute(s) read
Prev Next

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.

Guide

  1. Send a POST sales request

  2. Send a POST reversals request

Step 1 - Request

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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