Skip to main content

Integration Workflow

Checkout integration is a process involving interactions between Client (Frontend), Merchant Server (Backend), and Payment Platform.

To ensure data consistency and security, we recommend following the standard sequence below for development.

Interaction Sequence Diagram​

Detailed Steps​

1. Create Session (Server-side)​

The interaction starts at the merchant backend. When a user is ready to checkout, your backend needs to call the API to create a Checkout Session.

  • Product Construction: You can pass productId (referencing product library) or directly define productData (ad-hoc product construction).
  • Metadata: It is strongly recommended that you pass a set of metadata in key-value pairs.
    • Example: {"order_id": "ORD-2025001", "user_id": "u_123456"}.
    • Purpose: This data will not be shown to the payer, but will be included as-is in subsequent Webhook callbacks, helping you associate payment results with internal orders.
  • Redirect Address: Set successUrl, which is the merchant page address the user will return to after successful payment.

2. Get URL and Redirect​

After the platform API responds successfully, it returns a JSON object containing the paymentUrl field.

  • This URL points to the secure hosted cashier page we generated for you.
  • Action: The merchant backend returns this URL to the frontend, and the frontend redirects the user to this page via window.location.href or HTTP 303 redirect.

3. User Payment​

The user views order details, connects a wallet, and completes the payment on the hosted page.

  • The platform automatically handles exchange rate conversion, cross-chain routing, and on-chain interactions.
  • During this period, the user stays under our Domain.

4. Payment Success Redirect​

When on-chain transaction confirmation is detected:

  • If the merchant configured successUrl, the system automatically redirects the user back to that address.
  • Merchants can display a "Payment Successful" prompt on that page.
Do Not Rely on Redirect for Fulfillment

Users may close or refresh the page before being redirected. Do NOT assume payment success or fulfill orders solely based on the user returning to your site.

5. Async Notification & Fulfillment (Webhook)​

The authoritative signal for payment success comes from Webhooks. The platform will send session.paid, session.completed, or related payment success events to the merchant's configured Webhook URL. For the complete list of notification events, please refer to Webhook Event List →

The callback payload will contain:

  • Complete Session Info: Including the metadata (internal order ID) you passed in Step 1.
  • On-chain Data: Including TxHash, payment currency, actual payment amount, network gas fee, and other details.

After receiving the Webhook, the merchant should verify the signature, update the local order status, and complete the final fulfillment (shipping).

Next Steps​

Now that you understand the full flow, let's create your first Checkout Session via API.

Create Hosted Payment Page →