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 funds - Refund (if needed) — you call
signRefund()with the customer’s address and send the signed request to return 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 funds are returned to the customer’s wallet address automatically.
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 |
settled | Payment complete; funds transferred to your settlement address |
refunded | Full amount refunded to customer (two-step only) |
failed | Payment attempt failed (e.g., deposit lost to chain reorg) |
Available Endpoints
- Create Checkout — Create a direct or two-step payment
- Get Payment — Retrieve payment details
- List Payments — List all payments
- Capture Payment — Capture an authorized payment (two-step)
- Refund Payment — Refund a payment (two-step)
- Rescue Funds — Recover excess deposits (direct)
- Update Settlement — Change your settlement address
