POST /preauth-completions

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

This API endpoint completes a pre-authorised transaction for a POS system. It finalises the reserved amount on a customer's card, which may be lower than the originally authorised amount, and returns a response with the transaction ID, status, and card details.

Guide

  1. Use the method: POST

  2. For the Pre-Auth completion transaction we need to take SaleToPOIData from the Pre-Auth transaction response and need to pass the Pre-Auth completion request for Pre-Auth Completion. (Ex:"SaleToPOIData": {\"c\":\"31438\",\"p\":\"CREDIT\",\"r\":\"APPROVED\",\"rc\":\"5\",\"ts\":\"SUCCESS\",\"t\":\"4012563997\"}"). Send the pre auth completion 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-completions 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": "918304",
    "original_transaction_id": "KN2ZXWL65Z9M69WP",
    "currency": "GBP",
    "requested_amount": "53.50",
    "request_timestamp": "2025-03-13T16:33:14+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)

transaction_id received from preauth-transactions API response

NO

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

request_timestamp

datetime

Date and time of the transaction on the POS (e.g., "2025-02-2T14: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

Data Definition Table for Pre-Auth Completion Request

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

{
    "result": "SUCCESS",
    "transaction_id": "91VMWVLXY2XX4L61",
    "data": {
        "site_branch_id": "London",
        "pos_location": "POS-25",
        "terminal_id": "T650M-451-962-212-MOHSIN",
        "operator_id": "918304",
        "original_transaction_id": "KN2ZXWL65Z9M69WP",
        "currency": "GBP",
        "requested_amount": "53.50",
        "request_timestamp": "2025-03-13T16:33:14+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": "The Authorization header is required and must be provided in the format: Basic <encoded_api_key:secret_key>."
    }
}

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 must be provided in ISO 4217 format (e.g., GBP, USD, EUR)."
    }
}

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