Skip to main content
Each order (and each shipment) has its own Unifold Payment Intent for exactly its amount. Unifold accepts the payment, converts and bridges it, and tells us when it has settled.

The payment object

POST /orders, POST /shipments and POST /tokens/{tokenId}/shipment return it:
Your checkout either opens Unifold’s checkout with client_secret and publishable_key, or shows the customer deposit_addresses and amount.
GET /orders/{id} and GET /shipments/{id} don’t include payment. Replaying the create POST with the same Idempotency-Key returns it while the order or shipment is unpaid. Once an order is past awaiting_payment, a replay’s payment has no client_secret and no deposit addresses: there is nothing left to pay.

Rules

  • Chains: pay on Base or Solana. USDC is the simplest; Unifold converts other tokens it accepts, and conversion costs come off what arrives.
  • Tolerance: an intent counts as paid once at least 99% of the amount has arrived (swap slippage and wallet fees are absorbed). Payments toward one intent add up, so an underpaid customer can send the rest to the same address.
  • Underpayment: a payment more than 1% short opens nothing: the order goes to refund_due with failure_reason: "underpaid" and everything that arrived is refunded.
  • Overpayment is not returned automatically. Send exactly amount.
  • Payment window: an order must be paid within 24 hours of its creation, after which it becomes expired. A payment that lands after that is refunded in full (paid_after_expiry). An unpaid shipment never expires.
  • Refunds go out as USDC on Base to the order’s refund_address, for the amount received (a multi-pack unit gets its share). A refund that fails to send is retried automatically.
  • One payment per intent. Never reuse a deposit address for another order.
Payment Intents are live-mode only: in production every payment is real money. Use the sandbox to test.