POST /sales

This API endpoint processes card-present sales transactions for a POS system. It accepts payment details, including terminal and operator information, and returns a response with the transaction ID, payment status, and card details.

Guide
Enter the sale request
Perform the transaction on the terminal: insert/swipe/tap the card to complete the transaction
Based on the response from the terminal/external terminal simulator, the POS Cloud will send back the response

Step 1 - Request

Code Snippet

Data Dictionary

POST /v1/card-present/sales 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": "964566",
    "currency": "GBP",
    "requested_amount": "66.60",
    "request_timestamp": "2025-03-13T12:31:29+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
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

The POST /sales endpoint can return two types of responses:
(a) one that does not require signature verification and
(b) one that does require signature.

Response 1 - Card is used without the need for a signature.

Code Snippet

Data Dictionary

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

{
    "result": "SUCCESS",
    "transaction_id": "Q5YLK2EGN9Y26EKX",
    "card_type": "MasterCard",
    "card_number": "546097******4213",
    "card_mode": "CONTACTLESS",
    "data": {
        "site_branch_id": "London",
        "pos_location": "POS-25",
        "terminal_id": "T650M-451-962-212-MOHSIN",
        "operator_id": "964566",
        "currency": "GBP",
        "requested_amount": "66.60",
        "request_timestamp": "2025-03-13T12:31:29+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.
card_type	varchar(10)	Type of card used for the transaction.
card_number	varchar(20)	Masked card number for security.
card_mode	varchar(15)	Mode of transaction (e.g., chip, contactless).
data	json	Return the payload from the request.

Response 2 - Card is used but needs signature verification.

Code Snippet

Data Dictionary

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

{
    "result": "Verify signature",
    "transaction_id": "Q5YLK2EGN9Y26EKX",
    "data": {
        "site_branch_id": "London",
        "pos_location": "POS-25",
        "terminal_id": "T650M-451-962-212-MOHSIN",
        "operator_id": "964566",
        "currency": "GBP",
        "requested_amount": "66.60",
        "request_timestamp": "2025-03-13T12:31:29+01:00",
        "metadata": {
            "order_number": "7036171099"
        }
    }
}

Field Name	Type	Description
result	varchar(10)	`Verify signature`
transaction_id	varchar(50)	Unique identifier for the 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 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."
    }
}

404 Not Found

Invalid terminal_id

HTTP/1.1 404 Not Found
Content-Type: application/json  
{
    "result": "FAILURE",
    "message": "Device not found",
    "errors": {
        "terminal_id": "The terminal_id is invalid. Please 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 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."
    }
}

429 Too Many Request

Device busy

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

{
    "result": "FAILURE",
    "message": "Device is busy",
    "errors": {
        "terminal_id": "Device is busy processing another request. Please try again."
    }
}

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

503 Service Unavailable

Lost connection to the device

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

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

Device disconnected

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

{
    "result": "FAILURE",
    "message": "Device unreachable",
    "errors": {
        "terminal_id": "Device is currently offline or unreachable. Please try again."
    }
}