Skip to main content

Build your first checkout

This walkthrough connects your app to your backend and the Payment API. It uses Alipay App for a CNY 10.00 purchase. After the order is created, continue with the Alipay SDK steps. To use WeChat, choose wechat_app and follow the WeChat SDK steps.

Before you begin​

Have your platform application ID, an enabled payment entry, and a server-side Payment API key with payments:write and payments:read. For refunds, add refunds:write and refunds:read; include operations:read to follow asynchronous recovery and close operations. Obtain these from NextAppMarket and complete the native registration checklist in your payment method's guide.

Load PAYMENT_API_KEY from your server's secret store. The requests below target production; example IDs do not select a test environment. Arrange an approved live verification transaction before running them. You can build and test the app flow locally with fixtures first.

1. Your app asks your backend to start checkout​

The following is an example endpoint you implement, not a platform endpoint:

POST /api/checkout
Content-Type: application/json

{"cartId":"cart_1042","paymentEntry":"alipay_app"}

Authenticate the request with your application's normal session or access token. On your backend, load the customer's cart, calculate its price, and save business order shop_order_1042. Associate it with the signed-in customer. Ignore prices or customer IDs supplied by the client.

Create a durable payment-attempt record containing a unique idempotency key and the exact JSON request below. Commit that record before contacting the Payment API. Repeated taps must load that same attempt while it remains unresolved.

2. Your backend creates the platform order​

Save the request as payment.json. Replace app_demo with your platform application ID and use your own unique order reference.

{
  "app_id": "app_demo",
  "payment_entry": "alipay_app",
  "amount_minor": 1000,
  "currency": "CNY",
  "external_order_id": "shop_order_1042",
  "description": "100 app credits"
}
curl --fail-with-body --request POST \
  'https://pay.appconnect.cn/payment/v1/payment-sessions' \
  --header "Authorization: Bearer $PAYMENT_API_KEY" \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: create-shop-order-1042-v1' \
  --data-binary @payment.json

Read data.order and data.invocation. Persist data.order.id against your business order before returning a response to the app. The backend guide provides a Node.js HTTP client for this request and the recovery path if it times out.

3. Your backend returns instructions to the app​

Design your own response around the fields your client needs. For example:

{
  "businessOrderId": "shop_order_1042",
  "paymentOrderId": "ord_demo_001",
  "paymentStatus": "pending",
  "invocation": {
    "kind": "sdk_string",
    "sdk_string": "SIGNED_ORDER_STRING_FROM_THE_PAYMENT_API",
    "expires_at": "2030-01-01T10:15:00+08:00"
  }
}

This is your application's response shape. The string and timestamp above are illustrative. Forward the actual invocation unchanged; do not sign, decode, or rebuild it. Keep the business order ID in persistent app state so checkout can resume after a restart.

If the invocation is null, show Preparing payment. Your backend can retrieve GET /orders/{order_id}/payment-session for the same order. If the order is already paid, proceed to confirmation without launching the SDK again.

4. Open the payment SDK​

Check the invocation kind and expiry, then pass invocation.sdk_string to Alipay's SDK:

  • Android: call PayTask(activity).payV2(orderString, true) on a worker thread.
  • iOS: call payOrder:fromScheme:callback: and forward the return URL to the SDK.

Use the complete Android and iOS launch examples. The SDK result tells your app to refresh the order. It must not directly credit the customer's account.

5. Confirm payment on your backend​

When the SDK returns, or whenever your app resumes with an unfinished order, call your own authenticated endpoint:

GET /api/orders/shop_order_1042

Your backend checks that the signed-in customer owns the business order, loads its saved platform ID, and retrieves the authoritative order:

curl --fail-with-body \
  'https://pay.appconnect.cn/payment/v1/orders/ord_demo_001' \
  --header "Authorization: Bearer $PAYMENT_API_KEY"

Verify the order ID, application, external reference, currency, and amount against your saved purchase. If data.status is paid, deliver once and record fulfillment. Return a small application response such as:

{
  "businessOrderId": "shop_order_1042",
  "paymentStatus": "paid",
  "fulfillmentStatus": "delivered",
  "amountMinor": 1000,
  "currency": "CNY"
}

fulfillmentStatus belongs to your application. A paid order may still need delivery; in that case show Payment received. Preparing your purchase. See confirmation and fulfillment for the transaction and status handling.

6. Complete the lifecycle​

Add verified webhooks so payment confirmation also reaches your backend when the customer never returns to the app. Route both webhooks and status queries through the same fulfillment function.

Then implement refunds, safe retries and recovery, and closing unpaid orders. Run the integration checklist, including payment success while your app is closed.

Connect the app UI with Connect your app to checkout: Android and iOS HTTP helpers, browser Pay buttons, persistent order references, and the shared return/status page. Then follow the SDK or browser instructions in your selected payment-method guide.