Payment Lifecycle

Understand how a payment moves from creation to settlement.

Complete Payment Flow

The payment flow involves three participants: the merchant's backend, the Unter API, and the customer's browser (checkout widget).

Merchant Creates Payment Request

Your backend calls POST /api/payment-requests with the amount, destination token, chain, and recipient address. The API returns a payment_url and shortcode.

Customer Opens Checkout

You redirect the customer to the payment_url (hosted at cdn.unter.tech/pay/{shortcode}). The checkout widget loads the payment details and merchant theme.

Wallet Connection & Balance Check

The customer connects their wallet. The widget calls the API to check wallet balances and discover available tokens.

POST /api/public/payment-requests/{id}/balances/essential
POST /api/public/discover-wallet-tokens

Route Selection

The customer selects which token to pay with. The widget fetches available swap/bridge routes with fees.

POST /api/public/payment-requests/{id}/routes

Transaction Building & Signing

The API builds an unsigned transaction. The customer reviews and signs it in their wallet.

POST /api/public/check-approval    # Check if ERC-20 approval needed
POST /api/public/build-transaction  # Build unsigned tx payload

Payment Submission

After the customer signs and broadcasts the transaction, the widget submits the transaction hash to the API.

POST /api/public/payment-requests/{id}/payments

Async Verification

The API asynchronously verifies the transaction on-chain. For direct transfers, it checks the transaction receipt. For cross-chain swaps, it monitors both the source and destination chains.

Verification retries up to 10 times with exponential backoff.

Payment Confirmed

Once verified, the payment is marked as completed. If the payment request is fully paid, it transitions to completed. A webhook is dispatched to the merchant's configured URL.

Webhook Delivery

The API sends a signed POST request to the merchant's webhook URL with the event payload. The customer is redirected to the merchant's redirect_url.

Payment Types

Direct Transfer (Same Chain, Same Token)

When the customer pays with the exact token on the same chain as requested. This is the simplest path — verified directly via on-chain transaction receipt (eth_getTransactionReceipt or equivalent).

Example Merchant requests 50 USDC on Polygon. Customer pays 50 USDC from their Polygon wallet. Single transaction, single chain.

Cross-Chain Swap (Different Chain or Token)

When the customer pays with a different token or from a different chain. Routed via the Rango Exchange aggregator. This involves:

Source transaction — Customer signs on their source chain (e.g. ETH on Ethereum)
Bridge/swap execution — Automated routing through DEXs and bridges
Destination transaction — Funds arrive as the requested token on the destination chain

Example Merchant requests 50 USDC on Polygon. Customer pays with ETH on Ethereum. Rango routes: ETH -> bridge -> USDC on Polygon. The API monitors both chains until the destination transaction confirms.

Status Transitions

Payment Request Status

A payment request tracks the overall lifecycle of a merchant's payment intent.

            active
             → 
            completed
               (fully paid)
            

            active
             → 
            expired
                 (past expiration time)
            

            active
             → 
            cancelled
               (merchant cancelled via API)
        

Payment Status

Each individual payment attempt (transaction) has its own status.

            pending
             → 
            processing
             → 
            completed
            

            pending
             → 
            processing
             → 
            failed
        

Failed payments can be retried up to 3 times.

Polling vs Webhooks

You can track payment status in two ways:

Method	Endpoint	When to Use
Webhooks (recommended)	Your configured webhook URL	Real-time notifications. Set up once, receive all events.
Polling	`GET /api/payment-requests/{id}`	Fallback or additional verification. Check status on demand.

Recommendation Use webhooks as your primary integration method. Use polling only as a fallback or for manual verification. Webhook delivery includes automatic retries with backoff.