> 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 |
| ------------------ | ------------------------------------------------------- |
| `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
{% tabs %}
{% tab title="200 — Approved" %}
```json
{
"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"
}
]
}
}
}
```
{% 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.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.paymento.io/api-documention/payment-verify.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.