Secure Payments API Reference

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

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. Please submit individual payment requests.

Authentication

Endpoint	Supported auth
`POST /v2/secure-payments`	`x-api-key`, `x-client-id` + Origin, or session
`GET /v2/secure-payments`	Session only
`GET /v2/secure-payments/:token`	`x-api-key` or `x-client-id`
`GET /v2/secure-payments/:token/pay`	`x-api-key` or `x-client-id`
`POST /v2/secure-payments/:token/intent`	`x-api-key` or `x-client-id`

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

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

curl -X GET "https://api.request.network/v2/secure-payments/01ABC123DEF456GHI789JKL/pay?wallet=0x1234..." \
  -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

required

The source-chain transaction hash (66 characters: 0x + 64 hex chars).

chain

string

required

The source chain. Values: BASE, OPTIMISM, ARBITRUM, ETHEREUM.

token

string

required

The source token. Values: USDC, USDT.

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

🔑 API Setup

⚙️ API Features

📚 API Reference

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

🔑 API Setup

⚙️ API Features

📚 API Reference

Documentation Index

​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

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