Payment Verify

After you receive a payment notification (callback or redirect), call Payment Verify to confirm status for your store and, when you need it, to read on-chain settlement data for that payment in one response.

You do not need a separate blockchain API for reconciliation: transaction hashes, explorer links, confirmations, deposit address, asset/network metadata, and credited amounts are returned in the settlement object (for valid, authorized requests).

Verify a Payment

POST https://api.paymento.io/v1/payment/verify

Headers

Name	Value
Api-key	Your Merchant API Key
Content-Type	application/json
Accept	application/json

The API key must belong to the same merchant that owns the payment. If the token is unknown or belongs to another store, the response is success: false with message: "Invalid Token" (same as an invalid token).

Body

Name	Type	Nullable	Description
token	string	false	Payment token from the payment request.

Response envelope

Field	Type	Description
success	boolean	true only when the order is in Approve status after this call (see below).
message	string	Error or auxiliary text (e.g. "Invalid Token").
body	object	Payment details and optional settlement.

body fields

Field	Type	Description
token	string	Payment token.
orderId	string	Your reference from additionalData with key OrderId (removed from additionalData in the response).
orderStatus	string	Current payment status (see Order status).
additionalData	array	Remaining { key, value } pairs from the order.
settlement	object	On-chain / settlement context. Present for every authorized verify; omitted when the token is invalid or unauthorized.

On-chain data (settlement)

Use settlement when you need blockchain context without calling your own node or explorer APIs.

Field	Type	Description
expectedCryptoAmount	number	Amount the customer was asked to pay (crypto).
requestedFiatAmount	number	Fiat amount quoted for the order, if set.
receivedCryptoAmount	number	Sum of normalized amounts already credited (Mempool, InBlock, Completed transactions).
pendingTxHash	string	Expected transaction hash before any tx is persisted (wallet-signed flow). Not duplicated inside transactions.
toAddress	string	Deposit address for this payment.
asset	string	Asset symbol (e.g. USDT, ETH).
network	string	Network name when configured.
standard	string	Token standard: Native, ERC20, TRC20, SPL, etc.
contractAddress	string	Token contract address when applicable.
transactions	array	Persisted on-chain transactions for this order (may be empty).

settlement.transactions[]

Field	Type	Description
txHash	string	On-chain transaction id.
explorerUrl	string	Block explorer link when configured.
amount	number	Normalized amount credited for this transaction.
confirmations	number	Confirmations vs chain tip when height data is available; otherwise null.
requiredConfirmations	number	Confirmations required for this asset.
status	string	Pending, Mempool, InBlock, Completed, or Revert.
blockHeight	number	Block height when known.
detectedAt	string	When Paymento first detected the transaction (ISO 8601).
confirmedAt	string	When the transaction reached Completed, if known.
fromAddresses	string	Sender address(es) as stored.
toAddress	string	Recipient / deposit address for this tx.

Fields may be null when the underlying data is not available. Paymento does not invent chain data.

success vs orderStatus

Situation	success	What to do
Order is Approve (verified by your store)	true	Fulfill the order.
Order is Paid but not yet verified	false	Check orderStatus; call verify again after you are ready to mark verified (first successful verify moves Paid → Approve).
Order is WaitingToConfirm, PartialPaid, Pending, etc.	false	Valid token; wait or show status using orderStatus and settlement.
Invalid or unauthorized token	false	message is Invalid Token; settlement is omitted.

Important: success: false does not always mean a bad token. Always read body.orderStatus and settlement.

Order status

Common orderStatus values:

Value	Meaning
Initialize	Payment request created.
Pending	Customer selected a coin.
PartialPaid	Paid less than the order amount.
WaitingToConfirm	Transaction seen on-chain; awaiting confirmations.
Paid	Required confirmations reached.
Approve	Verified by merchant (verify returned success: true).
Timeout	Payment window expired.
UserCanceled	Customer canceled at checkout.
Reject	Payment rejected / no longer monitored.
Revert	Chain reorg or reversal (when applicable).

Examples

200 — Approved

{
  "success": true,
  "message": "",
  "body": {
    "token": "3256e147c6fe4d36a9341a5112ed2214",
    "orderId": "5855",
    "orderStatus": "Approve",
    "additionalData": [
      { "key": "invoice-number", "value": "A-578" }
    ],
    "settlement": {
      "expectedCryptoAmount": 0.015,
      "requestedFiatAmount": 42.50,
      "receivedCryptoAmount": 0.015,
      "pendingTxHash": null,
      "toAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
      "asset": "ETH",
      "network": "Ethereum",
      "standard": "Native",
      "contractAddress": null,
      "transactions": [
        {
          "txHash": "0xabc123...",
          "explorerUrl": "https://etherscan.io/tx/0xabc123...",
          "amount": 0.015,
          "confirmations": 12,
          "requiredConfirmations": 3,
          "status": "Completed",
          "blockHeight": 19234567,
          "detectedAt": "2026-05-19T10:22:11Z",
          "confirmedAt": "2026-05-19T10:28:44Z",
          "fromAddresses": "[\"0xsender...\"]",
          "toAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb"
        }
      ]
    }
  }
}

200 — Waiting to confirm

200 — Invalid token

400

Integration notes

1. Callbacks + verify: Use webhooks or redirect for real-time events; call verify when you need authoritative status and on-chain details for fulfillment.

2. Idempotent verify: Calling verify again on an already Approve order still returns success: true.

3. Backward compatible: Older clients can ignore settlement and orderStatus; new clients should use them for reconciliation and UX.

4. Amounts: Use expectedCryptoAmount, requestedFiatAmount, and receivedCryptoAmount at order level; use each transaction’s amount for per-tx credited value.

Upon receiving the payment notification, make an API call to confirm the payment status with the token you received.