Alipay, China's leading third-party online payment solutionAlipay, China's leading third-party online payment solution


In this topic, you'll learn how to integrate the bank SDK into an iOS client so that you can payment cashier pages in a mobile application. 


Before integrating the SDK, ensure that you have completed the following tasks:

  • Install Xcode 12 or a higher version.
  • Use iOS 11 or a higher version.
  • The SDK security extension package does not support simulator compilation. Please integrate the SDK on a real device.
Key integration steps

Integrate the SDK by following these steps:


Integrate the SDK package

Client side

To integrate the SDK package, please refer to Integrate the SDK Package.




Display available payment methods

Client side

After you have obtained available payment methods by contacting Alipay Technical Support, you can display the payment methods in the following modes:

  • Single bank mode: Display the payment methods by bank.
  • Bank type mode: Display the payment method by bank type, such as mobile banking app, online banking, and bank transfer.
  • Bank country mode: Display the payment methods by bank country, such as Thailand and Indonesia.

Please refer to User experience for three types of payment method display.

Note: In the bank type mode, payment methods cannot be displayed under the mobile banking app type on web clients.


Create an SDK instance by using the AMSCashierPayment method:

Client side
  1. Create an instance for cashier pages. The instance contains the following parameter:
    • configuration: A required object belonging to the AMSCashierPaymentConfiguration type. The object must contain all configuration parameters.
  2. Create the AMSCashierPaymentConfiguration class, which must contain the following parameters:
    • locale: An optional string belonging to the NSString type, which is used by the merchant client to identify the language of the buyer's browser. Specify this parameter to ensure that the SDK displays pages in the correct language. The valid values are as follows. If any other values are passed, English will be used as the default language.
      • en_US: English
      • in_ID: Indonesian
      • th_TH: Thai
    • options: An optional parameter belonging to the NSDictionary type. It is used to specify whether to use the default loading pattern and the sandbox environment. Valid values are:
      • "sandbox", "true": Sandbox environment
      • "sandbox", "false": Production enviroment
      • "showLoading", "true": Use the default loading pattern.
      • "showLoading", "false": Do not use the default loading pattern.
  3. Create an instance of the AMSPaymentProtocol interface used for handling corresponding events in subsequent processes. It contains the following method:
    • onEventCallback: A callback function that monitors payment events on the checkout page, returning eventCode and eventResult.
  4. Create an instance of the AMSLoggerProtocol interface used to manage log output. It contains the following method:
    • logWithName: A callback function that is used to output logs by default.
Create an SDK instance:
Create a configuration object:

Send a createPaymentSession (Checkout Payment) request to the Alipay server.

Server side

After the user selects the payment method and your client detects the payment button click event, your server sends a createPaymentSession (Checkout Payment) request. Get the paymentSesssionData value from the createPaymentSession response and use it in Step 5.

Pass the following parameters in your createPaymentSession (Checkout Payment) request:

  • paymentRequestId: The unique ID assigned by a merchant to identify a payment request. 

  • productCode: Represents the payment product that is being used. The value is fixed as AGREEMENT_PAYMENT .  

  • paymentNotifyUrl: The URL that is used to receive the payment result notification.

  • paymentRedirectUrl: The merchant page URL that the user is redirected to after the payment is completed.
  • paymentAmount: The payment amount that the merchant requests to receive in the order currency.
  • order.orderAmount: The order amount on the merchant's part. During sales promotion, the orderAmount value may differ from the paymentAmount value.
  • order.orderDescription: The order description.
  • order.referenceOrderId: The order ID on the merchant's side. Alipay suggests using one referenceOrderId for multiple paymentRequestIds when there are multiple payment requests for a single order.
  • paymentMethod.paymentMethodType: Specify it as BANK.
  • paymentMethod.paymentMethodMetaData:
    • To display payment methods in the single bank mode, specify bankName as a bank name.
    • To display payment methods in the bank type mode, specify paymentMethodCaregory as a payment method type. Valid values are BANK_TRANSFERMOBILE_BANKING_APP, and ONLINE_BANKING.
    • To display payment methods in the bank country mode, specify paymentMethodRegion as a country. Valid values are TH and ID.
Single bank mode
Bank type mode
Bank country mode

Render the payment pages

    Client side

    Use the createComponent() method in the configuration object.

    1. Create a configuration object by using the sessionData parameter: Pass the paymentSessionData value obtained in Step 4 to the sessionData parameter of the createComponent method.
    2. Call the createComponent() method to initialize the SDK.


    Call the onDestroy() method to free SDK component resources in the following situations:

    • When the user exits the checkout page, free the component resources created in the createPaymentSession.
    • When the user initiates multiple payments, free the component resources created in the previous createPaymentSession.
    Use the createComponent method

    Obtain a payment result

    Server side

    When the payment reaches a final status of success or failure, Alipay sends an asynchronous notification through the notifyPayment API to paymentNotifyUrl that you pass through the createPaymentSession API. When you receive the notification from Alipay, you must return a response as instructed in Requirements. You can also obtain the payment result by calling the inquiryPayment API.


    Event codes

    The SDK provides the following status codes:

    • SDK_START_OF_LOADING: The loading animation starts to play during the payment component creation.

    • SDK_END_OF_LOADING: The loading animation ends during the payment component creation.


    The SDK provides the following error codes:

    • SDK_INTERNAL_ERROR: The internal error of the SDK occurs. Contact Alipay Technical Support to resolve the issue. 

    • SDK_CREATEPAYMENT_PARAMETER_ERROR: The parameters passed into the AMSCashierPayment method are incorrect. Ensure the parameters are passed correctly and send a new request.

    • SDK_CALL_URL_ERROR: The payment method client failed to be revoked. Contact Alipay Technical Support to resolve the issue. 

    • SDK_INTEGRATION_ERROR: Dependencies are not found. Ensure that the dependencies are added correctly and retry the integration process.