POST /signatures

  • Updated on Apr 17, 2025
  • Published on Mar 31, 2025
  • 7 minute(s) read
Prev Next

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.

This signature confirmation process is applicable solely for cards that require a signature for payment verification via a terminal. This can be triggered by a faulty card or card inserted incorrectly three times.

Guide

  1. Send across the sale request (signature confirmation).

  2. POSCloud sends a signature confirmation Input request to POS.

  3. For signature confirmation, POS needs to send a signature confirmation Input response. Until POS sends the signature confirmation, the terminal will keep on waiting. Once the signature confirmation is sent, POSCloud will send the final transaction response. Signature confirmation Input Response looks like ("ConfirmedFlag" true means signature is confirmed, false means not confirmed).

  4. After signature confirmation, POS Cloud will send back the response.

The signature process required two API requests. The steps are as follows:

  1. POS posts a sales requests, see: POST /sales

    1. Customer swipes card on the terminal

    2. Terminal requests signature (either printed or digital)

    3. Customer signs

    4. POS gets a response and asks for signature verification.

  2. POS posts a signatures request (accepting or rejecting the signature)

    1. POS gets a response with transaction details

Step 1 - Request

POST /v1/card-present/signatures 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": "284192",
    "original_transaction_id": "KN2ZXWL65Z9M69WP",
    "is_signature_confirmed": true,
    "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

original_transaction_id

varchar(50)

Original sale transaction id.

NO

is_signature_confirmed

boolean

Must be true or false.

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

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

{
    "result": "SUCCESS",
    "transaction_id": "Q5YLK2EGN9Y26EKX",
    "card_type": "MasterCard",
    "card_number": "546097******4213",
    "card_mode": "MAGSTRIPE",
    "data": {
        "site_branch_id": "London",
        "pos_location": "POS-25",
        "terminal_id": "T650M-451-962-212-MOHSIN",
        "operator_id": "284192",
        "original_transaction_id": "KN2ZXWL65Z9M69WP",
        "is_signature_confirmed": true,
        "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 sales.

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, magstripe).

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": "The Authorization header is required and must be provided in the format: Basic <encoded_api_key:secret_key>."
    }
}

Missing is_signature_confirmed

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

{
    "result": "FAILURE",
    "message": "Request validation failed",
    "errors": {
        "is_signature_confirmed": "The is_signature_confirmed 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 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 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 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 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 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": "Please check the terminal_id and try again."
    }
}

Invalid original_transaction_id

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

422 Unprocessable Entity

Invalid is_signature_confirmed

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

{
    "result": "FAILURE",
    "message": "Request validation failed",
    "errors": {
        "is_signature_confirmed": "The is_signature_confirmed must be true or false."
    }
}

Invalid metadata

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

{
    "result": "FAILURE",
    "message": "Sales request 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 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 shortly."
    }
}

500 Internal Server Error

Generic error

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

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