POST /preauth-transactions

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

This API endpoint initiates a pre-authorization transaction for a POS system. It reserves a specified amount on a customer's card and returns a response with the transaction ID, status, and card details.

Guide

  1. Use the method: POST

  2. Send the Pre-auth request

  3. Based on the response from the terminal, the POS Cloud will send back the response

Step 1 - Request

POST /v1/card-present/preauth-transactions 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": "706392",
    "currency": "GBP",
    "requested_amount": "22.66",
    "requested_validity_date": "2025-03-27T15:11:04+01:00",
    "request_timestamp": "2025-03-13T15:11:04+01:00",
    "metadata": {
        "order_number": "2271574099"
    }
}

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)

Currency code for the transaction (e.g., GBP).

NO

requested_amount

decimal(8,2)

Amount requested for the transaction (e.g., 26.02). Minimum 0.01 and maximum = 1,000,000.

NO

requested_validity_date

datetime

The date must be a valid ISO 8601 datetime string (e.g., 2025-02-02T14:43:59+01:00)

YES

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 used for debugging, filtering, or linking to external systems. Accepts a JSON object containing custom details such as vendor, POS, customer, or order information. (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": "91VMWVLXY2XX4L61",
    "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": "706392",
        "currency": "GBP",
        "requested_amount": "22.66",
        "requested_validity_date": "2025-03-27T15:11:04+01:00",
        "request_timestamp": "2025-03-13T15:11:04+01:00",
        "metadata": {
            "order_number": "2271574099"
        }
    }
}

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.

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 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 must be a valid string with a maximum length of 255 characters."
    }
}

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 must be provided in ISO 8601 format (e.g., 2025-02-02T14:43:59+01:00)."
    }
}

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 requested_validity_date

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

{
    "result": "FAILURE",
    "message": "Request validation failed",
    "errors": {
        "requested_validity_date": "The requested_validity_date field is required and must be provided in ISO 8601 format (e.g., 2025-02-02T14:43:59+01:00)."
    }
}

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": "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 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 datetime string (e.g., 2025-02-02T14:43:59+01:00)."
    }
}

Invalid requested_amount

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

{
    "result": "FAILURE",
    "message": "Request validation failed",
    "errors": {
        "requested_amount": "Requested amount must be between 0.01 and 999,999.99"
    }
}

Invalid requested_validity_date

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

{
    "result": "FAILURE",
    "message": "Request validation failed",
    "errors": {
        "requested_validity_date": "The requested_validity_date must be a valid ISO 8601 datetime string (e.g., 2025-02-02T14:43:59+01:00)."
    }
}

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