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.
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 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 (direct).
- Update Settlement changes your settlement address.
