Payment methods
GET /retailer/v1/payment-methods lists every active method — crypto coins, Lightning, and the internal balance method. Each record carries display data (name, imageUrl, feeInfo), constraints (minAmountUSD, memoRequired), and refund policy fields.
When a method is returned with a checkout (availablePaymentMethods), it gains an eligible boolean: false means the checkout total is below the method’s minAmountUSD. Show ineligible methods greyed out with a tooltip rather than hiding them.
The payment invoice
Creating a payment (one-call checkout, POST /retailer/v1/checkouts/{id}/payment, or a deposit with paymentMethodId) returns an invoice object. The fields you render depend on the provider type:
When memo or destinationTag is present, your customer must include it in the transfer. Funds sent without it may not be credited.
Expired invoices
Crypto invoices expire. Call POST /retailer/v1/checkouts/{id}/payment again with the same method — the provider deduplicates and returns the same invoice refreshed (new expiry, same address where possible).
Aggregate payment state
GET /retailer/v1/checkouts/{id} (and the deposit detail endpoint) return a payment object summarizing all payments on the record:
partialPayment shows crypto under-payment progress (“30 of 50 USDT received”) so you can prompt the customer to send the remainder.
Prepaid balance payments
Both surfaces can pay with the internal balance method:
- B2B orders always pay with balance — that is the surface’s model.
- Retailer checkouts can pass the balance method id to prepay from your business balance instead of invoicing the customer.
Balance payments settle synchronously. If the deduction cannot confirm (typically insufficient balance), the call fails with 400 VALIDATION_ERROR and the reason in error.details.reason — no order is left half-paid.
Payment record statuses
Individual payment records move pending → confirming → confirmed or failed. confirming means the transaction is detected and awaiting network confirmations. The retailer webhook events payment.detected and payment.confirmed map to these transitions.
