> ## Documentation Index
> Fetch the complete documentation index at: https://docs.request.network/llms.txt
> Use this file to discover all available pages before exploring further.

# Secure Payments API Reference

> Generate secure payment URLs, retrieve payment metadata, and get executable calldata.

## Endpoints

* `POST /v2/secure-payments` — Create a secure payment (incoming, single or batch on EVM; single only on Tron)
* `POST /v2/secure-payments/payouts` — Create a hosted secure payout link (outgoing payment to a recipient)
* `GET /v2/secure-payments` — Lookup by request ID
* `GET /v2/secure-payments/:token` — Get payment metadata
* `GET /v2/secure-payments/:token/pay` — Get payment calldata
* `POST /v2/secure-payments/:token/intent` — Record crosschain payment intent
* `POST /v2/secure-payments/multicall-payouts` — Combine multiple existing payout links into one multicall link
* `GET /v2/secure-payments/multicall-payouts/:token` — Get multicall payout details (operator/session auth)

> [!WARNING]
>
> Batch incoming and batch payouts are EVM-only. Tron requests with multiple `requests[]` items return a 400 with `Batch payments are not supported for TRON networks`.

## Authentication

| Endpoint | Supported auth |
| - | - |
| `POST /v2/secure-payments` | `x-api-key`, `x-client-id` + Origin, session, or orchestrator pair |
| `GET /v2/secure-payments` | Session only |
| `GET /v2/secure-payments/:token` | `x-client-id` (+ Origin) |
| `GET /v2/secure-payments/:token/pay` | `x-client-id` (+ Origin) |
| `POST /v2/secure-payments/:token/intent` | `x-client-id` (+ Origin) |
| `POST /v2/secure-payments/multicall-payouts` | `x-api-key`, `x-client-id` + Origin, session, or orchestrator pair |
| `GET /v2/secure-payments/multicall-payouts/:token` | Session only |

***

## POST /v2/secure-payments

Create a secure payment entry and return a hosted payment URL.

### Request fields

**requests** `array` *required*

Array of payment requests. One item creates a single payment. Multiple items create a batch payment.

**requests\[].destinationId** `string`

ERC-7828 composite destination ID encoding payee wallet, chain, and token. Format: `{interopAddress}:{tokenAddress}`. Optional when the authenticated client ID has a bound payee destination.

**requests\[].amount** `string` *required*

Human-readable payment amount (e.g., `"10.50"`). Must be greater than 0.

**feePercentage** `string`

Optional fee percentage from `0` to `100` (e.g., `"2.5"` for 2.5%).

**feeAddress** `string`

Optional fee recipient address. Required when `feePercentage` is set.

**reference** `string`

Optional merchant reference for reconciliation (max 255 chars).

**payerIdentifier** `string`

Optional payer identifier (max 255 chars).

**redirectUrl** `string`

Optional `http(s)` URL displayed as a button on the success screen. After a successful payment the payer can click the button to return to your site — there is no auto-redirect. Only safe URLs are accepted: scheme must be `http` or `https`, and the value must not contain HTML/script payload characters (`<`, `>`, `"`, `'`, `` ` ``, whitespace).

**redirectLabel** `string`

Optional button label for the redirect (1–255 chars). Defaults to **"Go Back and Close"** when omitted. Cannot include HTML control characters (`<`, `>`, `&`, `"`, `'`, `` ` ``). **Cannot be set without `redirectUrl`** — the API rejects with 400 `redirectLabel cannot be provided without redirectUrl`.

```bash cURL theme={null}
curl -X POST "https://api.request.network/v2/secure-payments" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "requests": [
      {
        "destinationId": "0x6923831ACf5c327260D7ac7C9DfF5b1c3cB3C7D7@eip155:11155111#80B12379:0x370DE27fdb7D1Ff1e1BaA7D11c5820a324Cf623C",
        "amount": "10"
      }
    ],
    "feePercentage": "2.5",
    "feeAddress": "0x6923831ACf5c327260D7ac7C9DfF5b1c3cB3C7D7",
    "reference": "ORDER-2024-001",
    "redirectUrl": "https://merchant.example.com/order/2024-001/thank-you",
    "redirectLabel": "Back to merchant"
  }'
```

```json 201 Created theme={null}
{
  "requestIds": [
    "01e273ecc29d4b526df3a0f1f05ffc59372af8752c2b678096e49ac270416a7cdb"
  ],
  "securePaymentUrl": "https://pay.request.network/?token=01ABC123DEF456GHI789JKL",
  "token": "01ABC123DEF456GHI789JKL"
}
```

### Error responses

* `400`: invalid body or unsupported secure payment configuration
* `401`: unauthorized
* `429`: rate limited

***

## POST /v2/secure-payments/payouts

Create a hosted **secure payout link** — an outgoing single-recipient payment URL the payer (you) opens to sign and broadcast the transaction. Useful for sending payments to contractors, vendors, or any external recipient when you want a hosted UI instead of executing calldata yourself.

### Request fields

**recipient** `string` *required*

Recipient wallet address. EVM `0x...` or Tron `T...` format.

**creatorWalletAddress** `string` *required*

Wallet that created the payout (typically the payer wallet).

**network** `string` *required*

Destination network. Values: `mainnet`, `arbitrum-one`, `optimism`, `base`, `matic`, `bsc`, `tron`, `sepolia`.

**currency** `string` *required*

Payment currency in `<symbol>-<network>` form, e.g. `USDC-base`, `USDT-tron`, `FAU-sepolia`.

**amount** `string` *required*

Human-readable amount (e.g., `"100"`).

**reference** `string`

Optional merchant reference (max 255 chars).

**recipientIdentifier** `string`

Optional recipient identifier (max 255 chars).

**feePercentage** `string`

Optional fee percentage from `0` to `100`.

**feeAddress** `string`

Optional fee recipient address. Required when `feePercentage` is set.

**redirectUrl** `string`

Optional `http(s)` URL rendered as a button on the success screen for the signer to return to your app. Same validation rules as on `POST /v2/secure-payments` — see [above](#post-v2secure-payments).

**redirectLabel** `string`

Optional button label (1–255 chars). Defaults to **"Go Back and Close"**. Cannot be set without `redirectUrl`.

```bash cURL (EVM payout) theme={null}
curl -X POST "https://api.request.network/v2/secure-payments/payouts" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "recipient": "0x6923831ACf5c327260D7ac7C9DfF5b1c3cB3C7D7",
    "creatorWalletAddress": "0x2e2E5C79F571ef1658d4C2d3684a1FE97DD30570",
    "network": "base",
    "currency": "USDC-base",
    "amount": "250",
    "reference": "INVOICE-2026-042",
    "redirectUrl": "https://merchant.example.com/payouts/done"
  }'
```

```bash cURL (Tron payout) theme={null}
curl -X POST "https://api.request.network/v2/secure-payments/payouts" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "recipient": "TJRabPrwbZy45sbavfcjinPJC18kjpRTv8",
    "creatorWalletAddress": "TKb9mFPjUgCbrQpenCm4Z3T7ELNrLWurfm",
    "network": "tron",
    "currency": "USDT-tron",
    "amount": "250",
    "reference": "INVOICE-2026-042"
  }'
```

```json 201 Created theme={null}
{
  "requestIds": [
    "01e273ecc29d4b526df3a0f1f05ffc59372af8752c2b678096e49ac270416a7cdb"
  ],
  "securePaymentUrl": "https://pay.request.network/?token=01PAYOUT123ABCDEF456",
  "token": "01PAYOUT123ABCDEF456"
}
```

### Error responses

* `400`: invalid body, unsupported network/currency, or batch attempt on Tron
* `401`: unauthorized
* `429`: rate limited

***

## GET /v2/secure-payments

Lookup a secure payment by request ID. Requires a SIWE wallet session.

### Query parameters

**requestId** `string` *required*

The request ID to look up.

```json 200 OK theme={null}
{
  "token": "01ABC123DEF456GHI789JKL",
  "securePaymentUrl": "https://pay.request.network/?token=01ABC123DEF456GHI789JKL",
  "status": "pending",
  "paymentType": "single",
  "createdAt": "2026-03-15T10:00:00.000Z",
  "expiresAt": "2026-03-22T10:00:00.000Z"
}
```

### Error responses

* `404`: secure payment not found for the given request ID

***

## GET /v2/secure-payments/:token

Retrieve payment metadata and display information. Returns amounts, destination info, status, and optionally crosschain payment options — but **not** executable transaction calldata. Use `/pay` for calldata.

### Path parameters

**token** `string` *required*

Secure payment token returned from `POST /v2/secure-payments`.

### Query parameters

**wallet** `string`

Payer wallet address. When provided, the response includes `paymentOptions` with balance information across supported chains. Optional for Tron payments (the API uses a fallback address if omitted).

```bash cURL theme={null}
curl -X GET "https://api.request.network/v2/secure-payments/01ABC123DEF456GHI789JKL?wallet=0x1234567890123456789012345678901234567890" \
  -H "x-api-key: YOUR_API_KEY"
```

```json 200 Single payment theme={null}
{
  "paymentType": "single",
  "payee": "0x6923831ACf5c327260D7ac7C9DfF5b1c3cB3C7D7",
  "network": "base",
  "amount": "10000000000000000000",
  "paymentCurrency": "USDC-base",
  "isNativeCurrency": false,
  "status": "pending",
  "destination": {
    "destinationId": "0x6923...C7D7@eip155:8453#ABCD1234:0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "payeeAddress": "0x6923...C7D7@eip155:8453",
    "tokenAddress": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "walletAddress": "0x6923831ACf5c327260D7ac7C9DfF5b1c3cB3C7D7",
    "network": "base"
  },
  "reference": "ORDER-2024-001",
  "paymentOptions": {
    "BASE": {
      "USDC": {
        "balance": "150.00",
        "hasEnoughBalance": true,
        "neededAmount": "10.00"
      }
    },
    "ARBITRUM": {
      "USDC": {
        "balance": "25.00",
        "hasEnoughBalance": true,
        "neededAmount": "10.02"
      }
    }
  }
}
```

```json 200 Batch payment theme={null}
{
  "paymentType": "batch",
  "payees": [
    "0xb07d2398d2004378cad234da0ef14f1c94a530e4",
    "0x6923831ACf5c327260D7ac7C9DfF5b1c3cB3C7D7"
  ],
  "network": "sepolia",
  "amounts": ["50", "10"],
  "paymentCurrencies": ["FAU-sepolia", "FAU-sepolia"],
  "isNativeCurrency": [false, false],
  "status": "pending",
  "destinations": [
    {
      "destinationId": "...",
      "payeeAddress": "...",
      "tokenAddress": "...",
      "walletAddress": "0xb07d2398d2004378cad234da0ef14f1c94a530e4",
      "network": "sepolia"
    }
  ],
  "reference": null
}
```

### Error responses

* `403`: token expired or not payable
* `404`: token not found
* `409`: secure payment already completed
* `423`: a Safe multisig payment is in progress — keep polling (see [Safe multisig payments](https://docs.request.network/api-features/safe-multisig-payments.md))
* `429`: rate limited

***

## GET /v2/secure-payments/:token/pay

Retrieve executable transaction calldata for the secure payment. For crosschain payments, provide `chain` and `token` query parameters to select the source route.

> [!NOTE]
>
> The `:token` in the URL path is the secure payment token (a ULID identifier). The `token` query parameter is the source currency symbol (`USDC` or `USDT`) for crosschain route selection. These are different values.
>
> For **Tron** secure payments, do not pass `chain` or `token` query parameters — the calldata is generated for the Tron network directly. Tron payments are single-recipient and same-chain only.

### Path parameters

**token** `string` *required*

Secure payment token (ULID returned from `POST /v2/secure-payments`).

### Query parameters

**wallet** `string`

Payer wallet address. Used for approval and balance checks. Optional for Tron payments (the API uses a fallback address if omitted).

**chain** `string`

Source chain for crosschain payments. Values: `BASE`, `OPTIMISM`, `ARBITRUM`, `ETHEREUM`, `POLYGON`, `BNB`. Must be provided together with the `token` query parameter. Crosschain swap-to-pay is EVM-source only.

**token** `string`

Source currency for crosschain payments. Values: `USDC`, `USDT`. Must be provided together with `chain`.

**isSafe** `boolean`

Set to `true` when the payer wallet is a Gnosis Safe multisig. Returns Safe-ready calldata; `wallet` must be the Safe address and `eoaWallet` must not be set. See [Safe multisig payments](https://docs.request.network/api-features/safe-multisig-payments.md).

**eoaWallet** `string`

Externally-owned account address used to fund a smart-account payment. Mutually exclusive with `isSafe`.

```bash cURL (same-chain) theme={null}
curl -X GET "https://api.request.network/v2/secure-payments/01ABC123DEF456GHI789JKL/pay?wallet=0x1234..." \
  -H "x-api-key: YOUR_API_KEY"
```

```bash cURL (crosschain) theme={null}
curl -X GET "https://api.request.network/v2/secure-payments/01ABC123DEF456GHI789JKL/pay?wallet=0x1234...&chain=ARBITRUM&token=USDT" \
  -H "x-api-key: YOUR_API_KEY"
```

```json 200 Single payment calldata theme={null}
{
  "transactions": [
    {
      "to": "0x370DE27fdb7D1Ff1e1BaA7D11c5820a324Cf623C",
      "data": "0x...",
      "value": 0
    }
  ],
  "metadata": {
    "stepsRequired": 1,
    "needsApproval": false,
    "paymentTransactionIndex": 0,
    "hasEnoughBalance": true,
    "hasEnoughGas": true
  }
}
```

```json 200 Crosschain calldata theme={null}
{
  "transactions": [
    {
      "to": "0xFd086bC7CD5C481DCC9C85ebE478A1C0b69FCbb9",
      "data": "0x095ea7b3...",
      "value": "0x0"
    },
    {
      "to": "0x1231DEB6f5749EF6cE6943a275A1D3E7486F4EaE",
      "data": "0xabcdef...",
      "value": "0x0"
    }
  ],
  "metadata": {
    "stepsRequired": 2,
    "needsApproval": true,
    "approvalTransactionIndex": 0,
    "paymentTransactionIndex": 1,
    "routeType": "crosschain",
    "quoteExpiresAt": 1742205771,
    "hasEnoughBalance": true,
    "sourceAmount": "10.02"
  }
}
```

```json 200 Batch payment calldata theme={null}
{
  "ERC20ApprovalTransactions": [],
  "batchPaymentTransaction": {
    "to": "0x399F5EE127ce7432E4921a61b8CF52b0af52cbfE",
    "data": "0x...",
    "value": 0
  },
  "metadata": {
    "hasEnoughBalance": true,
    "hasEnoughGas": true
  }
}
```

### Error responses

* `400`: invalid calldata request or unsupported crosschain configuration
* `403`: token expired or not payable
* `404`: token not found
* `409`: secure payment already completed
* `429`: rate limited

***

## POST /v2/secure-payments/:token/intent

Record a crosschain payment intent after the payer broadcasts the source-chain LiFi transaction. This allows the system to track the bridge execution and trigger payment detection on the destination chain.

### Path parameters

**token** `string` *required*

Secure payment token.

### Request fields

**txHash** `string`

The source-chain transaction hash (66 characters: `0x` + 64 hex chars). Provide **either** `txHash` **or** `safeTxHash` — exactly one.

**safeTxHash** `string`

A Gnosis Safe transaction hash to track instead of an already-broadcast `txHash`. Used for [Safe multisig payments](https://docs.request.network/api-features/safe-multisig-payments.md). Provide exactly one of `txHash` or `safeTxHash`.

**safePaymentDeadline** `number`

Unix timestamp (seconds) — the hard on-chain execution deadline for the Safe route. Only valid alongside `safeTxHash`.

**chain** `string` *required*

The source chain. Values: `BASE`, `OPTIMISM`, `ARBITRUM`, `ETHEREUM`, `POLYGON`, `BNB`.

**token** `string` *required*

The source token. Values: `USDC`, `USDT`.

**payerAddress** `string`

Optional address of the wallet making the payment. Echoed back on the response.

```bash cURL theme={null}
curl -X POST "https://api.request.network/v2/secure-payments/01ABC123DEF456GHI789JKL/intent" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "txHash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
    "chain": "ARBITRUM",
    "token": "USDT"
  }'
```

```json 200 OK theme={null}
{
  "intentId": "01HXEXAMPLE123",
  "paymentReference": "0xb3581f0b0f74cc61",
  "txHash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
  "isListening": true
}
```

### Error responses

* `400`: invalid or unsupported crosschain payload
* `403`: token expired or not payable
* `404`: token not found
* `409`: secure payment already completed
* `429`: rate limited

***

## POST /v2/secure-payments/multicall-payouts

Combine multiple existing **outgoing payout** secure-payment links into a single multicall link the payer settles as one bundle. You pass the child secure-payment tokens; the API returns a parent token and hosted URL.

This is a distinct mechanism from a [batch payment](#post-v2secure-payments) (multiple `requests[]` in one create call). Multicall composes already-created payout links and supports cross-chain and Tron execution.

### Request fields

**childTokens** `string[]` *required*

Ordered list of existing secure-payment tokens to combine. Minimum 2, maximum 1000 (the deployed default cap is 150 children). Duplicates are rejected.

**requestedExecutionKind** `string`

How the bundle executes: `evm_same_chain`, `evm_cross_chain`, or `tron_batch`. When omitted, the execution kind is derived at payment time from the payer's source selection (Tron-only children → `tron_batch`; a chosen source chain/token → `evm_cross_chain`; otherwise `evm_same_chain`).

```bash cURL theme={null}
curl -X POST "https://api.request.network/v2/secure-payments/multicall-payouts" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "childTokens": [
      "01JZ4PC7EXAMPLECHILD000001",
      "01JZ4PC7EXAMPLECHILD000002"
    ]
  }'
```

```json 201 Created theme={null}
{
  "type": "multicall",
  "token": "01JZ4PCMULTICALLPARENT0001",
  "securePaymentUrl": "https://pay.request.network/?token=01JZ4PCMULTICALLPARENT0001",
  "status": "pending",
  "expiresAt": "2026-06-22T10:00:00.000Z",
  "createdAt": "2026-06-15T10:00:00.000Z",
  "items": [
    { "securePaymentToken": "01JZ4PC7EXAMPLECHILD000001", "requestId": "01e273...", "position": 0 },
    { "securePaymentToken": "01JZ4PC7EXAMPLECHILD000002", "requestId": "02f384...", "position": 1 }
  ]
}
```

The parent's `expiresAt` is the earliest expiry among its children.

### Execution kinds

| Kind | When | Behavior |
| - | - | - |
| `evm_same_chain` | All children on one network and one currency | Settled as a single bundled batch transaction (plus any ERC-20 approvals) |
| `evm_cross_chain` | Children span chains/currencies, or the payer pays from a different source | One cross-chain (Li.Fi) route is fetched per child and aggregated into one bundle (default cap 20 children) |
| `tron_batch` | All children on Tron (same token) | Settled via the Tron batch payment contract |

Supported payer source chains for cross-chain selection: `BASE`, `OPTIMISM`, `ARBITRUM`, `ETHEREUM`, `POLYGON`, `BNB`. Supported source tokens: `USDC`, `USDT`.

### Validation errors

Eligibility failures return a structured envelope:

```json 400 Bad Request theme={null}
{
  "message": "Multicall validation failed",
  "code": "multicall_validation_failed",
  "failures": [
    { "securePaymentToken": "01JZ4PC7EXAMPLECHILD000099", "reason": "already_paid" }
  ]
}
```

`failures[].reason` includes values such as `already_paid`, `secure_payment_expired`, `not_outgoing`, `compliance_failed`, and `not_payable_child`. Each `failures[]` entry also carries `messageKey`, `context`, and `recoveryAction` to help you present and resolve the failure. When a count limit is exceeded, the envelope instead carries a `cap` object together with a `failures` entry whose reason is `too_many_children` (child-count cap) or `cap_exceeded`:

```json 400 Bad Request (cap exceeded) theme={null}
{
  "message": "Multicall validation failed",
  "code": "multicall_validation_failed",
  "failures": [
    { "securePaymentToken": "*", "reason": "too_many_children" }
  ],
  "cap": { "type": "child_count", "maximum": 150, "actual": 180, "reduceBy": 30 }
}
```

### Paying a multicall link

The payer settles the parent token through the standard payer routes:

* `GET /v2/secure-payments/:token` returns the multicall details (children, totals, per-child eligibility).
* `GET /v2/secure-payments/:token/pay` returns multicall calldata, including `executionKind`, the `children[]` (each with its own `paymentReference`), the top-level `references[]` array (one per child, in order), and — for cross-chain — a per-child `destinationCall`.

***

## GET /v2/secure-payments/multicall-payouts/:token

Retrieve passive details for a multicall payout parent — children, totals, and per-child eligibility. This endpoint does **not** return quotes, calldata, or execution data; use `GET /v2/secure-payments/:token/pay` for calldata. Requires a SIWE wallet session (operator/Dashboard-facing).

### Path parameters

**token** `string` *required*

Multicall parent token returned from `POST /v2/secure-payments/multicall-payouts`.

```json 200 OK theme={null}
{
  "paymentType": "multicall",
  "token": "01JZ4PCMULTICALLPARENT0001",
  "status": "pending",
  "canExecute": true,
  "expiresAt": "2026-06-22T10:00:00.000Z",
  "createdAt": "2026-06-15T10:00:00.000Z",
  "children": [
    {
      "securePaymentToken": "01JZ4PC7EXAMPLECHILD000001",
      "requestId": "01e273...",
      "position": 0,
      "executable": true,
      "blockReason": null,
      "amount": "50",
      "payee": "0xb07d2398d2004378cad234da0ef14f1c94a530e4"
    }
  ],
  "totals": {
    "childCount": 2,
    "blockedChildCount": 0
  }
}
```

> [!NOTE]
>
> The example is abbreviated. Each child also carries `messageKey`, `context`, `recoveryAction`, and `feePlan`, and `totals` also includes `byDestinationCurrency` and `amountSummary`.

### Error responses

* `403`: not authorized for this multicall parent
* `404`: token not found
* `429`: rate limited


## Related topics

- [Secure Payment Pages](https://docs.request.network/api-features/secure-payment-pages.md)
- [Secure Payment Integration Guide](https://docs.request.network/api-features/secure-payment-integration-guide.md)
- [Safe Multisig Payments](https://docs.request.network/api-features/safe-multisig-payments.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.