Create Payment For Invoice
POST
/checkout/api/v1/invoices/{id}/checkoutRecommendedLocks the invoice to one blockchain/currency pair and returns the instructions the buyer needs to pay. For method "direct" the payment carries paymentAddress — a one-time address leased from the wallet pool; for "web3" and "havala_wallet" it carries contractAddress, externalId (the bytes32 form), externalIdUuid, treasuryWallet, tokenAddress (null for the chain native coin) and chainId instead, and "havala_wallet" adds requiresConfirmation: true. The payment window is min(now + 30 minutes, invoice expiry) and checkout always runs on MAINNET.
Authentication
Signature Pattern
None — public endpoint, no signature required.| Header | Value | Description |
|---|---|---|
Accept | application/json | No API key, signature or idempotency key — the checkout surface is public |
Content-Type | application/json | Request body is JSON |
Request Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | Path parameter — invoice CUID; must currently be OPEN and unexpired |
blockchain | string | Required | Lowercase chain key from availableBlockchains: ethereum, polygon, bsc, bitcoin, tron, solana, ton, arbitrum, optimism, base, avalanche |
cryptoCurrency | string | Required | Token symbol that the chosen chain supports (see availableCurrencies); rejected with INVALID_CURRENCY otherwise |
method | string | Required | direct | web3 | havala_wallet. web3 and havala_wallet are EVM-only (ethereum, polygon, bsc, arbitrum, optimism, base, avalanche) and fail with BLOCKCHAIN_NOT_SUPPORTED elsewhere |
Request Example
JSONRequest Body
{
"blockchain": "ethereum",
"cryptoCurrency": "USDT",
"method": "direct"
}Response Parameters
| Field | Type | Example |
|---|---|---|
payment | object | {…} |
payment.id | string | "clx7k2p9a0007qz8f1d0s9k2r" |
payment.referenceId | string | "PAY-260826-118A" |
payment.method | string | "direct" |
payment.paymentAddress | string | "0xe58b081006f7e3dfc967a64cb14028d512c9791e" |
payment.amount | string | "12500" |
payment.cryptoCurrency | string | "USDT" |
payment.blockchain | string | "ethereum" |
payment.network | string | "MAINNET" |
payment.decimals | integer | 6 |
payment.expiresAt | string | "2026-08-26T14:12:00.000Z" |
Response Example
JSONResponse
{
"success": true,
"data": {
"payment": {
"id": "clx7k2p9a0007qz8f1d0s9k2r",
"referenceId": "PAY-260826-118A",
"method": "direct",
"paymentAddress": "0xe58b081006f7e3dfc967a64cb14028d512c9791e",
"amount": "12500",
"cryptoCurrency": "USDT",
"blockchain": "ethereum",
"network": "MAINNET",
"decimals": 6,
"expiresAt": "2026-08-26T14:12:00.000Z"
}
},
"timestamp": "2026-08-26T13:41:02.477Z",
"requestId": "req_V1StGXR8_Z5j"
}Error shape
JSONError
{
"success": false,
"error": {
"code": "NOT_FOUND",
"message": "Resource not found"
},
"timestamp": "2026-08-26T13:41:02.477Z",
"requestId": "req_V1StGXR8_Z5j"
}Status Codes
200Success
201Created
400Bad Request
401Unauthorized
404Not Found
429Rate Limited
Try itMockapi2.havala.io
POSThttps://api2.havala.io