Skip to main content

POS Remote Request

The POS Remote Request suite of APIs allows you to remotely invoke a payment on a POS terminal and requery for the status of the transaction.​
info

Environment base URL:

Base URL: https://api-d.squadco.com/softpos/

Authorization keys are to be passed via Headers as a Bearer token.

Example: Authorization: Bearer sandbox_sk_94f2b798466408ef4d19e848ee1a4d1a3e93f104046f.

Create Payment Request​

This endpoint enables you to send a payment request to a POS terminal. The terminal receives the request and processes the card payment.

POST
https://api-d.squadco.com/softpos/pos/remote-request

This endpoint allows you send a payment to a POS terminal.

Parameters

Header

Authorization*

String

API keys (Secret Key) that authorize your transactions and gotten from your squad dashboard

Body

terminal_id*

String

The ID of the POS terminal to invoke

amount*

Number

Amount to charge (in kobo). Must be greater than 0

account_type

String

Account type: default, savings, current, or credit

Sample POS Remote Request​

{
  "terminal_id": "2035AB01",
  "amount": 350000,
  "account_type": "default"
}

Responses

200:OK
Successful
{
  "status": 200,
  "success": true,
  "message": "Payment request created",
  "data": {
    "request_ref": "prq_01HV8M3K5R7XM6QEGG1YAEVF"
  }
}

400:Validation Error
Validation Error
{
    "status": "400",
    "message": "Validation error (missing fields, invalid amount)",
    "data": {}
  }
401:Invalid Token
Invalid Token
{
    "status": "401",
    "message": "Invalid or missing token",
    "data": {}
  }

Requery Payment Status​

This endpoint allows you to requery the terminal using the request reference to confirm if payment is completed or not.

GET
https://api-d.squadco.com/softpos/pos/remote-request/{request_ref}

This endpoint allows you requery the status of a request

Parameters

Header

Authorization*

String

API keys (Secret Key) that authorize your transactions and gotten from your squad dashboard

Body

request_ref*

String

The reference returned from the create endpoint

Sample Request​

GET https://api-d.squadco.com/softpos/pos/remote-request/prq_01HV8M3K5R7XM6QEGG1YAEVF

Responses

200 Success
Success
{
  "status": 200,
  "success": true,
  "message": "Success",
  "data": {
    "status": "success",
    "id": 12345,
    "merchant_request_ref": "prq_01HV8M3K5R7XM6QEGG1YAEVF",
    "merchant_id": "MER_001",
    "terminal_id": "2035AB01",
    "amount": 350000,
    "currency": "NGN",
    "payment_method": "card",
    "transaction_type": "Purchase",
    "payment_info": {
      "card_pan": "506100******1234",
      "card_exp": "2512",
      "card_type": "visa",
      "cardholder_name": "JOHN DOE"
    },
    "transaction_reference": "TXN_REF_001",
    "virtual_account_number": null,
    "rrn": "123456789012",
    "stan": "019283",
    "aid": "A0000000041010",
    "response_code": "00",
    "response_message": "Approved",
    "processor": null,
    "meta": "{}",
    "pc_code": "PC001",
    "created_at": "2026-02-20T09:15:48.901Z"
  }
}

200 Pending
Success
{
  "status": 200,
  "success": true,
  "message": "Success",
  "data": {
    "status": "pending"
  }
}
200 Failed
Success
{
  "status": 200,
  "success": true,
  "message": "Success",
  "data": {
    "status": "failed",
    "id": 12345,
    "merchant_request_ref": "prq_01HV8M3K5R7XM6QEGG1YAEVF",
    "merchant_id": "MER_001",
    "terminal_id": "2035AB01",
    "amount": 350000,
    "currency": "NGN",
    "payment_method": "card",
    "transaction_type": "Purchase",
    "payment_info": {
      "card_pan": "506100******1234",
      "card_exp": "2512",
      "card_type": "visa",
      "cardholder_name": "JOHN DOE"
    },
    "transaction_reference": "TXN_REF_002",
    "virtual_account_number": null,
    "rrn": "123456789013",
    "stan": "019284",
    "aid": "A0000000041010",
    "response_code": "51",
    "response_message": "Insufficient funds",
    "processor": null,
    "meta": "{}",
    "pc_code": "PC001",
    "created_at": "2026-02-20T09:15:48.901Z"
  }
}
404 Expired/Not Found
false
{
  "status": 404,
  "success": false,
  "message": "Request not found or expired",
  "data": {}
}

401:Invalid Token
Invalid Token
{
    "status": "401",
    "message": "Invalid or missing token",
    "data": {}
  }
info

Response — Expired / Not Found (404) Returned when the request_ref does not exist or has expired. Payment requests are stored with a 5-minute Time To Live (TTL). Once the TTL expires, the record is automatically deleted, as such the system returns a 404 response. Which can mean:

i.The request_ref was never valid

ii.The request expired because the POS terminal did not complete the payment within 5 minutes

Best Practises/Notes

The request_ref expires after 5 minutes.

If the terminal does not process the payment within that window, requery will return 404.

Call the requery endpoint every 2-3 seconds until you get a final status (success or failed) or a 404.

When status is pending, only status is returned. When success or failed, the full transaction fields are flattened into the response.