How to Integrate

In practice, the merchant usually creates the business order in its own system first. When payment is needed, the merchant calls either AinePay Hosted Checkout or the inline payment flow, presents the returned stablecoin payment details to the customer, and then uses AinePay webhooks together with order queries to keep the order payment status up to date and complete the full transaction flow.

1. Get the supported coins and chains

Before showing payment methods to the customer, the merchant should call the Supported Coins API to retrieve the coins and chains that are currently available in AinePay.

At the moment, AinePay supports USDT and USDC on Ethereum. More widely used stablecoins and the blockchains they support will be added over time.

2. Create the payment order after choosing a payment method

After a supported payment method is selected, the merchant should assemble the order on its own backend and send the payment request to the AinePay payment system through the appropriate API. The request should include the merchant's unique ID for that order, which AinePay uses to prevent the same order from being paid more than once.

AinePay currently supports two payment integration modes:

1. Hosted Checkout mode: call Create Checkout Order to receive the payment url for AinePay's hosted checkout page, then redirect the customer there to complete payment. The merchant does not need to define the payment flow or customer-facing UI because AinePay provides the payment page design.
2. AinePay Inline mode: call Create Inline Order to receive the payment address payload and render the payment experience inside your own product UI. Use this mode when you need to customize the payment flow and apply more complete validation in your own system.

Both modes create the order inside AinePay. The main difference is whether the customer is redirected to an AinePay-hosted page or the merchant displays the payment details inside its own interface.

3. Receive payment status changes by callback, and confirm the final status by query API

After the customer pays, AinePay sends asynchronous callbacks to the merchant notify URL to report order status changes. See Payment Notification for the callback payload and signature verification details.

When the blockchain confirmation count reaches the required threshold, the order status becomes PAID, indicating that the payment is complete. Callbacks serve as a fast notification channel for status transitions — merchants should always use the Query Orders API to confirm the order status.

PAID and EXPIRED are final states. Do not treat PENDING as a final business outcome — only proceed with your fulfillment flow once the queried order status is PAID.

4. Expired order handling

AinePay maintains a complete user account record. If an order becomes EXPIRED or another exceptional situation causes it to fail, but the user still sends funds afterwards, those funds are recorded in the user's account balance. When the merchant creates the next order for that same user, AinePay will first attempt to settle it using the user's available account balance. If the balance is sufficient, the order becomes PAID directly and the user does not need to pay again.