Secure Payments API Reference - Request Network Docs

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)

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.

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"
  }'

{
  "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.

redirectLabel

string

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

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"
  }'

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"
  }'

{
  "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.

{
  "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).

curl -X GET "https://api.request.network/v2/secure-payments/01ABC123DEF456GHI789JKL?wallet=0x1234567890123456789012345678901234567890" \
  -H "x-api-key: YOUR_API_KEY"

{
  "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"
      }
    }
  }
}

{
  "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)
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.

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.

eoaWallet

string

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

curl -X GET "https://api.request.network/v2/secure-payments/01ABC123DEF456GHI789JKL/pay?wallet=0x1234..." \
  -H "x-api-key: YOUR_API_KEY"

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"

{
  "transactions": [
    {
      "to": "0x370DE27fdb7D1Ff1e1BaA7D11c5820a324Cf623C",
      "data": "0x...",
      "value": 0
    }
  ],
  "metadata": {
    "stepsRequired": 1,
    "needsApproval": false,
    "paymentTransactionIndex": 0,
    "hasEnoughBalance": true,
    "hasEnoughGas": true
  }
}

{
  "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"
  }
}

{
  "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. 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.

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"
  }'

{
  "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 (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).

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"
    ]
  }'

{
  "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:

400 Bad Request

{
  "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:

400 Bad Request (cap exceeded)

{
  "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.

{
  "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
  }
}

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

​Endpoints

​Authentication

​POST /v2/secure-payments

​Request fields

​Error responses

​POST /v2/secure-payments/payouts

​Request fields

​Error responses

​GET /v2/secure-payments

​Query parameters

​Error responses

​GET /v2/secure-payments/:token

​Path parameters

​Query parameters

​Error responses

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

​Path parameters

​Query parameters

​Error responses

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

​Path parameters

​Request fields

​Error responses

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

​Request fields

​Execution kinds

​Validation errors

​Paying a multicall link

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

​Path parameters

​Error responses

Endpoints

Authentication

POST /v2/secure-payments

Request fields

Error responses

POST /v2/secure-payments/payouts

Request fields

Error responses

GET /v2/secure-payments

Query parameters

Error responses

GET /v2/secure-payments/:token

Path parameters

Query parameters

Error responses

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

Path parameters

Query parameters

Error responses

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

Path parameters

Request fields

Error responses

POST /v2/secure-payments/multicall-payouts

Request fields

Execution kinds

Validation errors

Paying a multicall link

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

Path parameters

Error responses