Commerce, stores and payments

Clients and data conventions

On Android, use MobileSdk.commerce(context, activityHost, apiBase, language). On iOS, use [[IRCommerceClient alloc] initWithBaseURL:apiBase language:language]. Both invoke actions through execute and return a cancellable operation. Success returns a JSON string or null; decode before use.

The complete field declarations are in the package’s contracts/commerce.d.ts. IDs are strings, money is integer CNY cents and times are ISO 8601. Ignore new server fields and do not depend on field order. Clients capture the current account/token; recreate them after changes.

Browse products and stores

Fixed-manufacturer apps may omit vehicleId for these browsing actions. The official cross-manufacturer app queries for the selected vehicle. Store coordinates use GCJ-02. Use server enabled, purchasable and unavailableReason values to control entry points and purchase buttons; local manufacturer configuration is not sufficient.

Addresses, quotes and order creation

addresses and regions take an empty object. saveAddress takes body plus id for updates. deleteAddress takes id and version. Consult the public declarations for address fields.

Call quote with vehicleId and body={bindingVersion, skuId, quantity, addressId}. Show the returned price, shipping fee and payment method for user confirmation. Then call purchaseCreate with this body structure:

{
  "clientOrderKey": "<one UUID per purchase intent>",
  "vehicleId": "<vehicle ID>",
  "bindingVersion": 1,
  "skuId": "<SKU ID>",
  "quantity": 1,
  "addressId": "<address ID>",
  "addressVersion": 1,
  "expectedQuote": {
    "unitPriceCent": 100,
    "shippingFeeCent": 0,
    "paymentMethod": "ALIPAY"
  }
}

These are illustrative fields. Use current server values for all IDs, versions, amounts and payment methods. Generate clientOrderKey once per purchase intent as a UUID. Retrying after an unknown response must reuse that intent; do not create a new UUID and duplicate the order.

Explicit payment and recovery

1. Check SDK paymentAvailable and the order’s allowed actions. Call purchasePay({id, paymentMethod}) only after the user explicitly chooses to pay.
2. The SDK fetches the order and signed payment parameters, then invokes the provider. It does not expose orderInfo to the host.
3. Treat server financial state as authoritative. A provider success callback alone is not proof of settlement.
4. On startup or foreground return, call purchaseRecover({retry:false}) and, if needed, sync({id}). Recovery must not automatically invoke payment again.
5. After the user acknowledges the order, call purchaseAcknowledge({id}). The SDK re-fetches the user’s order and retains recovery markers for unconfirmed payments.

purchaseIntent only reads the current intent. purchaseRecover.retry defaults to false; set it to true only when the user explicitly retries order creation. Recovery can clear records once the server confirms PAID or CLOSED. Use a bounded number of status queries for WAIT_PAY orders with UNCONFIRMED payment.

Cancelling payment may still require waiting for the provider callback or timeout. Wait for the original operation to settle before starting another payment. Cancellation, leaving a screen or closing the app cannot undo a completed payment.

Orders and provider configuration

orders accepts optional page, status and clientOrderKey. order, sync and cancel take id; receive also takes version. Render buttons from allowedActions. Orders belong to the current account and remain constrained by application scope.

On iOS, include the package’s InfiniteRideMobile/Alipay subspec, configure paymentScheme and forward all payment URLs as described in iOS integration. Real payments also require host application and merchant registration. iOS supports production only; Android supports production/sandbox. Use the environment and parameters returned by the platform. SIMULATED is available only when explicitly enabled by the platform and is not evidence of a real payment.