--- title: "POST /preauth-transactions" slug: "post-preauth-transactions" updated: 2025-09-19T14:18:20Z published: 2025-09-19T14:18:20Z canonical: "api-docs.blinkpayment.co.uk/post-preauth-transactions" --- > ## Documentation Index > Fetch the complete documentation index at: https://api-docs.blinkpayment.co.uk/llms.txt > Use this file to discover all available pages before exploring further. # POST /preauth-transactions 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. > [!NOTE] > ## 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 Code SnippetData Dictionary ```json 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 Code SnippetData Dictionary ```json 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** ```json 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 ."    } } ``` ### **Missing currency** ```json HTTP/1.1 400 Bad Request   Content-Type: application/json   {    "result": "FAILURE",    "message": "Field validation failed",    "errors": {        "currency": "The currency field is required and cannot be empty."    } } ``` ### **Missing POS_location** ```json 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** ```json 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 must be provided in ISO 8601 format (e.g., 2025-02-02T14:43:59+01:00)."    } } ``` ### **Missing requested_amount** ```json HTTP/1.1 400 Bad Request   Content-Type: application/json   {    "result": "FAILURE",    "message": "Field validation failed",    "errors": {        "requested_amount": "The requested_amount field is required and cannot be empty."    } } ``` ### **Missing requested_validity_date** ```json HTTP/1.1 400 Bad Request   Content-Type: application/json   {    "result": "FAILURE",    "message": "Field 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** ```json 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** ```json 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** ```json 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** ```json 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** ```json 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 ."    } } ``` ## **403 Forbidden** ### **API key or secret key is invalid** ```json 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** ```json 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."    } } ``` ### **422 Unprocessable Entity** ### **Invalid currency** ```json HTTP/1.1 422 Unprocessable Entity   Content-Type: application/json {    "result": "FAILURE",    "message": "Field validation failed",    "errors": {        "currency": "The currency must be a valid ISO 4217 code (e.g., GBP, USD, EUR)."    } } ``` ### **Invalid metadata** ```json 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** ```json 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 POS_location** ```json 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** ```json 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 datetime string (e.g., 2025-02-02T14:43:59+01:00)."    } } ``` ### **Invalid requested_amount** ```json HTTP/1.1 422 Unprocessable Entity   Content-Type: application/json {    "result": "FAILURE",    "message": "Field validation failed",    "errors": {        "requested_amount": "Requested amount must be between 0.01 and 999,999.99"    } } ``` ### **Invalid requested_validity_date** ```json HTTP/1.1 422 Unprocessable Entity   Content-Type: application/json {    "result": "FAILURE",    "message": "Field 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** ```json 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** ```json 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."    } } ``` ## **429 Too Many Request** ### **Terminal busy** ```json HTTP/1.1 429 Too Many Requests Content-Type: application/json {    "result": "FAILURE",    "message": "Terminal is busy",    "errors": {        "terminal_id": "The terminal is busy processing another request. Please try again later."    } } ``` ## **500 Internal Server Error** ### **Generic error** ```json 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** ```json 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** ```json 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** ```json 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."    } } ```