Skip to content

secure-payments.mdx

Latest commit

 

History

History
396 lines (327 loc) · 10.7 KB

secure-payments.mdx

File metadata and controls

396 lines (327 loc) · 10.7 KB
title Secure Payments API Reference
description Generate secure payment URLs, retrieve payment metadata, and get executable calldata.

Endpoints

  • POST /v2/secure-payments — Create a secure payment
  • 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

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

Array of payment requests. One item creates a single payment. Multiple items create a batch payment. 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. Human-readable payment amount (e.g., `"10.50"`). Must be greater than 0. Optional fee percentage from `0` to `100` (e.g., `"2.5"` for 2.5%). Optional fee recipient address. Required when `feePercentage` is set. Optional merchant reference for reconciliation (max 255 chars). Optional payer identifier (max 255 chars). ```bash cURL 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" }' ``` ```json 201 Created { "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

GET /v2/secure-payments

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

Query parameters

The request ID to look up. ```json 200 OK { "token": "01ABC123DEF456GHI789JKL", "securePaymentUrl": "https://pay.request.network/?token=01ABC123DEF456GHI789JKL", "status": "pending", "paymentType": "single", "createdAt": "2026-03-15T10:00:00.000Z", "expiresAt": "2026-03-15T10:15: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

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

Query parameters

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 curl -X GET "https://api.request.network/v2/secure-payments/01ABC123DEF456GHI789JKL?wallet=0x1234567890123456789012345678901234567890" \ -H "x-api-key: YOUR_API_KEY" ``` ```json 200 Single payment { "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 { "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.

Path parameters

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

Query parameters

Payer wallet address. Used for approval and balance checks. Optional for Tron payments (the API uses a fallback address if omitted). Source chain for crosschain payments. Values: `BASE`, `OPTIMISM`, `ARBITRUM`, `ETHEREUM`. Must be provided together with the `token` query parameter. Source currency for crosschain payments. Values: `USDC`, `USDT`. Must be provided together with `chain`. ```bash cURL (same-chain) 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"
```json 200 Single payment calldata { "transactions": [ { "to": "0x370DE27fdb7D1Ff1e1BaA7D11c5820a324Cf623C", "data": "0x...", "value": 0 } ], "metadata": { "stepsRequired": 1, "needsApproval": false, "paymentTransactionIndex": 0, "hasEnoughBalance": true, "hasEnoughGas": true } } ``` ```json 200 Crosschain calldata { "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 { "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

Secure payment token.

Request fields

The source-chain transaction hash (66 characters: `0x` + 64 hex chars). The source chain. Values: `BASE`, `OPTIMISM`, `ARBITRUM`, `ETHEREUM`. The source token. Values: `USDC`, `USDT`. ```bash cURL 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 { "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