> For the complete documentation index, see [llms.txt](https://docs.paymento.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.paymento.io/api-documention/payment-verify.md).
# 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`
#### 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 |
| -------------------------- | ------------------------------------------------------ |
| **(0) `Initialize`** | Payment request created. |
| **(1) `Pending`** | Customer selected a coin. |
| **(2) `PartialPaid`** | Customer paid less than the required amount. |
| **(3) `WaitingToConfirm`** | Transaction detected on-chain; awaiting confirmations. |
| **(4) `Timeout`** | Payment window expired. |
| **(5) `UserCanceled`** | Customer returned/canceled at checkout. |
| **(7) `Paid`** | Required blockchain confirmations reached. |
| **(8) `Approve`** | Payment verified by merchant. |
| **(9) `Reject`** | Payment rejected / address no longer monitored. |
### Examples
{% tabs %}
{% tab title="200 — Approved" %}
```json
{
"success": true,
"message": "",
"body": {
"token": "3256e147c6fe4d36a9341a5112ed2214",
"orderId": "5855",
"orderStatus": "8",
"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"
}
]
}
}
}
```
{% endtab %}
{% tab title="200 — Waiting to confirm" %}
```json
{
"success": false,
"message": "",
"body": {
"token": "3256e147c6fe4d36a9341a5112ed2214",
"orderId": "5855",
"orderStatus": "WaitingToConfirm",
"additionalData": [],
"settlement": {
"expectedCryptoAmount": 100.0,
"requestedFiatAmount": 100.0,
"receivedCryptoAmount": 100.0,
"pendingTxHash": null,
"toAddress": "TXyz...",
"asset": "USDT",
"network": "Tron",
"standard": "TRC20",
"contractAddress": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
"transactions": [
{
"txHash": "a1b2c3...",
"explorerUrl": "https://tronscan.org/#/transaction/a1b2c3...",
"amount": 100.0,
"confirmations": 1,
"requiredConfirmations": 19,
"status": "InBlock",
"blockHeight": 61234567,
"detectedAt": "2026-05-19T11:05:00Z",
"confirmedAt": null,
"fromAddresses": null,
"toAddress": "TXyz..."
}
]
}
}
}
```
{% endtab %}
{% tab title="200 — Invalid token" %}
```json
{
"success": false,
"message": "Invalid Token",
"body": {
"token": "",
"orderId": "",
"orderStatus": "Initialize",
"additionalData": []
}
}
```
{% endtab %}
{% tab title="400" %}
```json
{
"error": "Invalid request"
}
```
{% endtab %}
{% endtabs %}
### 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.