Build the Complete Payment Flow

This checklist combines the tutorial into one implementation sequence.

1. Initialize the integration

• Store the issued Base URL, API Key, and HMAC key in a secret manager.
• Confirm /health and /time; keep the caller clock synchronized.
• Discover USDT and Sepolia IDs from the reference-data APIs.
• Verify the asset/network combination is active.

2. Provision payment accounts

• Reuse or create one USER account per customer model.
• Reuse or create a BUSINESS account for the merchant payment role.
• Persist the two account IDs separately and validate their type and status.

3. Fund the customer

• Issue a deposit address for the selected asset and network.
• Detect the external deposit with an EXTERNAL deposit cursor.
• Poll every discovered non-final deposit by ID and confirm funding only at status: COMPLETED.
• Confirm the customer's available raw balance covers the payment amount.

4. Process the payment

customer USER account
  → POST /withdrawals/internal with a unique client_request_id
  → merchant BUSINESS account

• Persist the order ID and client_request_id before submission, then link withdrawal_id after receiving the response.
• Recover by the same client_request_id after a timeout.
• Mark the order paid only when the internal transaction is COMPLETED.
• Use balance changes only as a secondary consistency check.

5. Settle merchant funds

• Validate the external address for the selected asset.
• Request a quote and require transfer_type: EXTERNAL.
• Create an external withdrawal with a new globally unique client_request_id.
• Keep settlement pending through intermediate processing states.
• Complete it only when both statuses are COMPLETED and tx_hash is valid.

6. Reconcile continuously

• Read customer deposits and sent payments with separate cursors.
• Read merchant receipts from the INTERNAL_IN ledger.
• Read merchant external settlements from withdrawals and the WITHDRAW ledger.
• Poll non-final business records by ID; sync the append-only ledger by cursor.

Production rules

IMPORTANT

Apply these rules even if the proof of concept succeeds without them.

• Never reuse a client_request_id across internal or external withdrawals.
• Never resubmit a create operation solely because the HTTP response was lost.
• Never branch program logic on a localized error message; use HTTP status, error.code, and error.action.
• Use integer or decimal-safe math for asset amounts.
• Bound retries and use exponential backoff only where the error action permits it.
• Never expose API or HMAC keys in client applications, source control, logs, or support messages.

Use the Wallet API Reference for the complete request and response schemas.