Payments
A payment represents a completed on-chain transfer of stablecoins from a customer. Payments are created when a customer completes a checkout or when a subscription fee is charged.
Payment Modes
When creating a checkout or subscription, you can specify a payment_method:
| Mode | Description |
|---|---|
direct | Funds are sent directly to your settlement address when the customer pays. Requires a signed request at checkout creation. Refunds via signed rescue request. |
two_step | Funds are held until you capture them to your settlement address or refund them to the customer via signed requests. |
Both payment modes require a signing key. See Signed Requests for setup instructions.
Two-Step Payment Flow
- Customer pays. Funds are held securely until you decide what to do with them.
- Capture. You call
signCapture()from the SDK and send the signed request to collect the funds. - Refund (if needed). You call
signRefund()with the customer’s address and send the signed request to return the funds.
The API verifies your signature before executing any fund movement.
Refunds
How refunds work depends on the payment mode:
-
Direct mode. You send a signed rescue request via the API using
signRescue()from the SDK to recover excess deposits or return funds. -
Two-step mode. You send a signed refund request via the API using
signRefund()from the SDK, and the funds are returned to the customer’s wallet address automatically. Rescue also works on two-step payments once escrow is confirmed, settled, or refunded.
For expired payments, Recover returns funds to the customer’s recorded deposit source — the server delegates internally to a refund when the payment is escrow_confirmed, or a rescue of the detected token when it is settled.
Need partial captures or partial refunds? Contact your account manager to discuss options for partial fund movements.
Payment Statuses
| Status | Description |
|---|---|
client_deposit_pending | Checkout created; no deposit detected yet |
client_deposit_detected | Deposit seen on-chain; waiting for confirmations |
client_deposit_confirmed | Deposit confirmed; payment contract deploy queued |
client_deposit_expired | Checkout expired before a valid deposit arrived |
escrow_confirmed | TWO_STEP: funds held in escrow, awaiting capture or refund |
settlement_pending | Capture succeeded on-chain; fiat settlement to merchant in progress |
settled | Payment complete; funds transferred to your settlement address |
failed | Payment attempt failed (e.g., deposit lost to chain reorg) |
refunded | Full amount refunded to customer (two-step only) |
cancelled | Payment cancelled |
Available Endpoints
- Create Checkout creates a direct or two-step payment.
- Get Payment retrieves payment details.
- List Payments lists all payments.
- Capture Payment captures an authorized payment (two-step).
- Refund Payment refunds a payment (two-step).
- Rescue Funds recovers excess deposits or wrong tokens (direct and two-step).
- Recover Payment returns an expired payment to the customer (EVM only).
- List Settlement Addresses lists your on-chain settlement addresses.
- Update Settlement changes your settlement address.
