Validate Payment

curl --request POST \
  --url https://secureapi.tender.cash/v1/api/payment/validate/{id} \
  --header 'x-access-id: <api-key>'

const options = {method: 'POST', headers: {'x-access-id': '<api-key>'}};

fetch('https://secureapi.tender.cash/v1/api/payment/validate/{id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://secureapi.tender.cash/v1/api/payment/validate/{id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_HTTPHEADER => [
    "x-access-id: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

{
  "status": "success",
  "message": "payment received",
  "data": {
    "_id": "<string>",
    "txId": "66aec7de809b7f45c42a49f9",
    "status": "completed",
    "type": "receive",
    "chain": "tron",
    "chainId": {
      "_id": "<string>",
      "id": "<string>",
      "name": "<string>",
      "icon": "<string>",
      "coin": "<string>",
      "chainType": "<string>",
      "explorer": "<string>"
    },
    "currency": {
      "_id": "<string>",
      "id": "<string>",
      "name": "<string>",
      "symbol": "<string>",
      "icon": "<string>",
      "isContract": true
    },
    "walletAddress": "<string>",
    "contractAddress": "<string>",
    "amount": "<string>",
    "coinAmount": "<string>",
    "usdAmount": "<string>",
    "amountReceived": "<string>",
    "amountReceivedUSD": "<string>",
    "balanceRequired": "<string>",
    "balanceRequiredUSD": "<string>",
    "fee": "<string>",
    "feeUSD": "<string>",
    "activationFee": "<string>",
    "activationFeeUSD": "<string>",
    "feeBreakdown": {
      "settlement": "pending",
      "charged": {
        "receive": {
          "coin": "0.1",
          "usd": 0.1
        },
        "activation": {
          "coin": "0.1",
          "usd": 0.1
        },
        "autoPayoutSwap": {
          "coin": "0.1",
          "usd": 0.1
        },
        "autoPayoutWithdrawal": {
          "coin": "0.1",
          "usd": 0.1
        },
        "gasFreeService": {
          "coin": "0.1",
          "usd": 0.1
        },
        "totalCoin": "0.1",
        "totalUSD": 0.1
      }
    },
    "rate": "<string>",
    "isPartialPayment": true,
    "isFulfilled": true,
    "partialPaymentAt": "2023-11-07T05:31:56Z",
    "fulfilledAt": "2023-11-07T05:31:56Z",
    "fulfilledBy": "expiry",
    "agentAmount": "<string>",
    "agentCurrency": "<string>",
    "agentRate": "<string>",
    "agentRateUSD": "<string>",
    "amountReceivedAgent": "<string>",
    "balanceRequiredAgent": "<string>",
    "referenceId": "<string>",
    "agentId": {
      "_id": "<string>",
      "name": "<string>",
      "agentId": "<string>"
    },
    "merchantId": {
      "_id": "<string>",
      "merchantName": "<string>"
    },
    "createdAt": "2023-11-07T05:31:56Z",
    "updatedAt": "2023-11-07T05:31:56Z"
  }
}

{
  "status": "error",
  "message": "INVALID_REQUEST_SIGNATURE",
  "data": {}
}

{
  "status": "error",
  "message": "Payment Not made yet",
  "data": {}
}

{
  "status": "error",
  "message": "Too many requests. Max 120 per 60s.",
  "data": null
}

POST

api

payment

validate

{id}

Validate Payment

curl --request POST \
  --url https://secureapi.tender.cash/v1/api/payment/validate/{id} \
  --header 'x-access-id: <api-key>'

const options = {method: 'POST', headers: {'x-access-id': '<api-key>'}};

fetch('https://secureapi.tender.cash/v1/api/payment/validate/{id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://secureapi.tender.cash/v1/api/payment/validate/{id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_HTTPHEADER => [
    "x-access-id: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

{
  "status": "success",
  "message": "payment received",
  "data": {
    "_id": "<string>",
    "txId": "66aec7de809b7f45c42a49f9",
    "status": "completed",
    "type": "receive",
    "chain": "tron",
    "chainId": {
      "_id": "<string>",
      "id": "<string>",
      "name": "<string>",
      "icon": "<string>",
      "coin": "<string>",
      "chainType": "<string>",
      "explorer": "<string>"
    },
    "currency": {
      "_id": "<string>",
      "id": "<string>",
      "name": "<string>",
      "symbol": "<string>",
      "icon": "<string>",
      "isContract": true
    },
    "walletAddress": "<string>",
    "contractAddress": "<string>",
    "amount": "<string>",
    "coinAmount": "<string>",
    "usdAmount": "<string>",
    "amountReceived": "<string>",
    "amountReceivedUSD": "<string>",
    "balanceRequired": "<string>",
    "balanceRequiredUSD": "<string>",
    "fee": "<string>",
    "feeUSD": "<string>",
    "activationFee": "<string>",
    "activationFeeUSD": "<string>",
    "feeBreakdown": {
      "settlement": "pending",
      "charged": {
        "receive": {
          "coin": "0.1",
          "usd": 0.1
        },
        "activation": {
          "coin": "0.1",
          "usd": 0.1
        },
        "autoPayoutSwap": {
          "coin": "0.1",
          "usd": 0.1
        },
        "autoPayoutWithdrawal": {
          "coin": "0.1",
          "usd": 0.1
        },
        "gasFreeService": {
          "coin": "0.1",
          "usd": 0.1
        },
        "totalCoin": "0.1",
        "totalUSD": 0.1
      }
    },
    "rate": "<string>",
    "isPartialPayment": true,
    "isFulfilled": true,
    "partialPaymentAt": "2023-11-07T05:31:56Z",
    "fulfilledAt": "2023-11-07T05:31:56Z",
    "fulfilledBy": "expiry",
    "agentAmount": "<string>",
    "agentCurrency": "<string>",
    "agentRate": "<string>",
    "agentRateUSD": "<string>",
    "amountReceivedAgent": "<string>",
    "balanceRequiredAgent": "<string>",
    "referenceId": "<string>",
    "agentId": {
      "_id": "<string>",
      "name": "<string>",
      "agentId": "<string>"
    },
    "merchantId": {
      "_id": "<string>",
      "merchantName": "<string>"
    },
    "createdAt": "2023-11-07T05:31:56Z",
    "updatedAt": "2023-11-07T05:31:56Z"
  }
}

{
  "status": "error",
  "message": "INVALID_REQUEST_SIGNATURE",
  "data": {}
}

{
  "status": "error",
  "message": "Payment Not made yet",
  "data": {}
}

{
  "status": "error",
  "message": "Too many requests. Max 120 per 60s.",
  "data": null
}

Auth method: Basic (Access ID) — this endpoint only requires your x-access-id header. No request signing is needed. See Authentication.

Checks the payment’s deposit address on-chain, updates the payment if funds have arrived, and returns its current state. You can only validate payments that belong to your merchant account. GET /v1/api/payment/validate/{id} is an alias of this endpoint and behaves identically. Payment endpoints share a limit of 120 requests per minute. See Rate limits.

A successful check returns HTTP 202. Every failure returns HTTP 406 with data: {}, including Payment Not made yet, which simply means no funds have arrived yet. When you poll, treat a 406 as “keep polling”, not as a failed payment.

Path Parameters

string

required

The txId returned when the payment was initiatedExample: "66aec7de809b7f45c42a49f9"

Headers

string

required

Your API access ID provided by TenderExample: "your-access-id-here"

Response

string

required

Status of the API requestExample: "success"

string

required

Result of the check. See Messages.Example: "payment received"

object

required

The payment. Additional fields may be present; ignore fields you don’t recognise.

Show data properties

string

The payment’s transaction ID (same as _id)Example: "66aec7de809b7f45c42a49f9"

string

The payment’s transaction IDExample: "66aec7de809b7f45c42a49f9"

string

Payment status after the check: completed, overpayment or partial-payment. A payment with no funds received returns 406 Payment Not made yet instead, whatever its stored status. See Payment status values.Example: "completed"

string

Transaction type. Always receive for payments.Example: "receive"

string

Chain identifierExample: "tron"

object

The chain

Show chainId properties

string

Internal ID of the chain recordExample: "64f782bb4278fc475eb30e29"

string

Chain identifierExample: "tron"

string

Chain display nameExample: "Tron"

string

Chain icon URLExample: "https://tender-store.s3.amazonaws.com/icons/tron.png"

string

Native coin of the chainExample: "TRX"

string

Chain familyExample: "tron"

string

Block explorer URLExample: "https://tronscan.org"

object

The cryptocurrency

Show currency properties

string

Internal ID of the currency recordExample: "64fc4cda43812c15552311d7"

string

Currency identifierExample: "usdt"

string

Currency nameExample: "Tether"

string

Currency symbolExample: "USDT"

string

Currency icon URLExample: "https://tender-store.s3.amazonaws.com/icons/usdt.png"

boolean

Whether the currency is a token contractExample: true

string

The deposit address the customer pays toExample: "TQn9Y2khDD9JHTfVE5oB2h8BKWWM4LxKLT"

string

Token contract address, or an empty string for a native coinExample: "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t"

string

The all-in cryptocurrency amount requestedExample: "10.15"

string

Same as amountExample: "10.15"

string

USD value of amountExample: "10.15"

string

Cryptocurrency amount received so farExample: "10.15"

string

USD value of amountReceivedExample: "10.15"

string

Cryptocurrency amount still owed. "0" once the payment is complete.Example: "0"

string

balanceRequired in USDExample: "0"

string

Fees charged on this payment, in the cryptocurrencyExample: "0.1"

string

fee in USDExample: "0.1"

string

Activation fee included in fee, if anyExample: "0"

string

activationFee in USDExample: "0"

object | null

Itemised fees charged to the customer, or null for older payments

Show feeBreakdown properties

string

Fee settlement stateExample: "pending"

object

Each fee leg as { coin, usd }, where coin is a string and usd a number: receive, activation, autoPayoutSwap, autoPayoutWithdrawal and gasFreeService, plus totalCoin (string) and totalUSD (number).

string

USD price of one unit of the cryptocurrency at initiationExample: "1"

boolean

Whether the customer paid less than the requested amountExample: false

boolean

true once the payment is fully paid, or once a partial payment has been accepted as finalExample: true

string | null

When a partial payment was first detectedExample: null

string | null

When a partial payment was accepted as finalExample: null

string | null

Who accepted a partial payment as final: expiry (automatically, 24 hours after the partial payment was detected), merchant or adminExample: null

string

The requested amount in the fiat currency the payment was priced inExample: "10.00"

string

The fiat currency the payment was priced inExample: "usd"

string

Price of one unit of the cryptocurrency in agentCurrency at initiationExample: "1"

string

USD price of one unit of the cryptocurrency at initiation, or the outlet’s manual rateExample: "1"

string

Amount received, in agentCurrencyExample: "10.15"

string

Amount still owed, in agentCurrencyExample: "0"

string

Your reference, or an empty stringExample: "ORDER-9821"

object

The outlet that received the payment

Show agentId properties

string

Outlet IDExample: "6538eaaebdec6d1a21978e6a"

string

Outlet nameExample: "Lagos Fashion Store"

string

Outlet referenceExample: "vbibtucm9ynq3k2x7p"

object

Your merchant account

Show merchantId properties

string

Merchant IDExample: "6538e8f9bdec6d1a21978a64"

string

Business nameExample: "Example Store"

string

ISO 8601 timestamp when the payment was createdExample: "2026-10-15T09:00:00.000Z"

string

ISO 8601 timestamp when the payment was last updatedExample: "2026-10-15T09:04:12.000Z"

Messages

HTTP 202 (status: "success", data is the payment):

Message	Meaning
`payment received`	The full amount arrived. `data.status` is `completed`, or `overpayment` if the customer paid well over the amount.
`partial payment received`	Less than the full amount arrived. `data.status` is `partial-payment`.
`partial payment fulfilled`	A partial payment has been accepted as final.
`Transaction already completed`	The payment was already complete.
`Transaction already Overpaid`	The payment was already marked as overpaid.
`Transaction payment state already updated`	Another check updated the payment at the same time; `data` is its current state.

HTTP 406 (status: "error", data: {}):

Message	Meaning
`Payment Not made yet`	No funds have arrived yet. Keep polling. This is also returned for an unpaid payment that has been cancelled.
`Transaction state changed; retry validation`	The payment changed during the check. Retry.
`Invalid tx id`	The ID is unknown or doesn’t belong to your merchant account.
`Invalid Chain` / `Invalid Currency` / `Invalid Agent` / `Invalid Merchant`	The payment’s chain, currency, outlet or merchant can no longer be found.
`Exchange Price Error`	No price is available for the currency right now. Retry later.

Example request

curl -X POST https://sandbox-api.tender.cash/v1/api/payment/validate/66aec7de809b7f45c42a49f9 \
  -H "x-access-id: your-access-id-here"

Example response

{
  "status": "success",
  "message": "payment received",
  "data": {
    "_id": "66aec7de809b7f45c42a49f9",
    "txId": "66aec7de809b7f45c42a49f9",
    "status": "completed",
    "type": "receive",
    "chain": "tron",
    "chainId": {
      "_id": "64f782bb4278fc475eb30e29",
      "id": "tron",
      "name": "Tron",
      "icon": "https://tender-store.s3.amazonaws.com/icons/tron.png",
      "coin": "TRX",
      "chainType": "tron",
      "explorer": "https://tronscan.org"
    },
    "currency": {
      "_id": "64fc4cda43812c15552311d7",
      "id": "usdt",
      "name": "Tether",
      "symbol": "USDT",
      "icon": "https://tender-store.s3.amazonaws.com/icons/usdt.png",
      "isContract": true
    },
    "walletAddress": "TQn9Y2khDD9JHTfVE5oB2h8BKWWM4LxKLT",
    "contractAddress": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
    "amount": "10.15",
    "coinAmount": "10.15",
    "usdAmount": "10.15",
    "amountReceived": "10.15",
    "amountReceivedUSD": "10.15",
    "balanceRequired": "0",
    "balanceRequiredUSD": "0",
    "fee": "0.1",
    "feeUSD": "0.1",
    "activationFee": "0",
    "activationFeeUSD": "0",
    "feeBreakdown": {
      "settlement": "pending",
      "charged": {
        "receive": { "coin": "0.1", "usd": 0.1 },
        "activation": { "coin": "0", "usd": 0 },
        "autoPayoutSwap": { "coin": "0", "usd": 0 },
        "autoPayoutWithdrawal": { "coin": "0", "usd": 0 },
        "gasFreeService": { "coin": "0.05", "usd": 0.05 },
        "totalCoin": "0.1",
        "totalUSD": 0.1
      }
    },
    "rate": "1",
    "isPartialPayment": false,
    "isFulfilled": true,
    "partialPaymentAt": null,
    "fulfilledAt": null,
    "fulfilledBy": null,
    "agentAmount": "10.00",
    "agentCurrency": "usd",
    "agentRate": "1",
    "agentRateUSD": "1",
    "amountReceivedAgent": "10.15",
    "balanceRequiredAgent": "0",
    "referenceId": "ORDER-9821",
    "agentId": {
      "_id": "6538eaaebdec6d1a21978e6a",
      "name": "Lagos Fashion Store",
      "agentId": "vbibtucm9ynq3k2x7p"
    },
    "merchantId": {
      "_id": "6538e8f9bdec6d1a21978a64",
      "merchantName": "Example Store"
    },
    "createdAt": "2026-10-15T09:00:00.000Z",
    "updatedAt": "2026-10-15T09:04:12.000Z"
  }
}

A payment that hasn’t been paid yet returns:

{
  "status": "error",
  "message": "Payment Not made yet",
  "data": {}
}

Authorizations

x-access-id

string

header

required

Basic (Access ID) authentication. Only the x-access-id header is required; no request signing.

Headers

x-access-id

string

required

Your API access ID provided by Tender

Path Parameters

string

required

The payment's txId

Response

Payment checked; funds have arrived

status

string

Example:

"success"

message

enum<string>

Available options:

payment received,

partial payment received,

partial payment fulfilled,

Transaction already completed,

Transaction already Overpaid,

Transaction payment state already updated

data

object

Additional fields may be present; ignore fields you don't recognise.

Show child attributes

Payment

Transactions

System

Agents

Conversions

Payouts

Subwallets

Webhooks

On-ramp

Validate Payment

Path Parameters

Headers

Response

Messages

Example request

Example response

Authorizations

Headers

Path Parameters

Response

​Path Parameters

​Headers

​Response

​Messages

​Example request

​Example response

Authorizations

Headers

Path Parameters

Response

Path Parameters

Headers

Response

Messages

Example request

Example response