Merchant payment terms
Distinguish your business order, collection session and actual payments before integrating. They govern fulfillment, payment interaction and funds reconciliation respectively.
| Term | Meaning and integration rule |
|---|---|
| Business order | Your purchase, invoice or service operation; the boundary for fulfillment deduplication. |
| Checkout (collection session) | One cashier payment interaction with its own ID, URL, amount and expiry. One order may have several Checkouts. order_id is not unique and does not replace Idempotency-Key. |
| Payment method | How payment is made, such as ipp or erc20_transfer. The payment-method response groups entries by method. |
| Currency/network pair | A method's supported {currency, chain}, such as USDC with an EIP-155 network ID. Do not combine independently listed currencies and networks or infer one method's support from another. |
Payment item (attempt_id) | One detected-payment record containing cumulative finalized receipts, refunded funds and current refundable amount. Select its attempt_id from payment details before refunding. |
| Payment Intent (refund scope) | Refund.payment_intent identifies the original payment. At most one Refund for the same Payment Intent may be requires_action or processing across all its payment items. Do not allow concurrent creation merely because attempt_id differs. Use returned identifiers rather than deriving them from other resource IDs. |
| Fulfillment | Merchant delivery of goods, content or service. Checkout success does not record delivery. Check the order association, amount, currency and exceptions, then deliver once per business order. |
| Webhook event | A notification with an event ID and related resource identifier, rather than a complete current resource snapshot. Verify, persist and deduplicate the event, then retrieve the resource for current state. |
| Settlement (fund collection) | Full collection of finalized IPP receipts to the wallet fixed by the original receipts, executed by the merchant wallet. It is not a bank payout or an arbitrary destination transfer. |
States belong to individual resources
Checkout has four primary statuses: open, processing, succeeded and failed. processing means payment is on chain but still awaits the required confirmation; do not request another payment. succeeded means the selected confirmation requirements were met; still inspect exception_status before fulfillment. Your business order's fulfilled flag is merchant-owned, not a Checkout status. Refunds and Settlements have their own state models.
Merchant API and native IPP
Here, Checkout means the hosted merchant API's collection session. Native IPP also uses Checkout, but organizes interaction through PaymentSession, option confirmation and an immutable Request. Their endpoints, authentication, amounts and success rules are defined separately. Follow the objects and interfaces of your chosen integration layer. See protocol terms.
Follow your first payment through creation, cashier delivery, retrieval and fulfillment, then use API availability to choose notification, refund and settlement capabilities.