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

iOS

In this topic, you'll learn how to integrate the pop-up payment experience SDK into an iOS client, and it will allow you to render cashier pages in a mobile application.

 

Prerequisites

Before the integration, ensure that you have completed the following tasks:

  • Install Xcode 12 version or later.
  • Use iOS 11 version or later.

 

Key integration steps

Integrate the SDK by following these steps:

1

Integrate the SDK package

Merchant client

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

 

 

2

Create an SDK instance by using the AMSCashierPayment:

Merchant client
  • Create an instance for cashier pages. The instance contains the following parameters:
    • configuration: A required object belonging to the AMSCashierPaymentConfiguration type. The object must contain all configuration parameters.
  • Create the AMSCashierPaymentConfiguration class, which must contain the following parameters:
    • locale: Optional. NSString type. It is used by the merchant client to identify the browser language and pass in the language information. The SDK uses the information to provide cashier pages in the corresponding language. Valid values are listed as follows. If other values are passed, English is used by default:
      • en_US: English
      • es_ES: Spanish
      • fr_FR: French
      • nl_NL: Dutch
      • it_IT: Italian
      • de_DE: German
      • zh_CN: Simplified Chinese
    • 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 Environment.
      • "showLoading", "true": Use the default loading style.
      • "showLoading", "false": Do not use the default loading style.
      • "notRedirectAfterComplete", "true": The default value is false, which means it will redirect back to your page after the payment is completed. The same applies when the value is empty. true value means there will be no redirect after the payment is completed. You need to use the customer event code to control the card binding to complete the subsequent process. Please note that the payment result event code returned by the client is only used as a reference for the redirect operation of the client page. For transaction status updates, please refer to the results returned by the server's notifyPayment or inquiryPayment API.
      • "merchantAppointmentParam": Optional object used for setting custom features. It contains a value below:

        • storedCard: Optional object used for setting custom features of stored cards. It contains a value below:
          • ​​needCVV: Optional Boolean. The default value is false, which indicates that the user do not need to input CVV number during the payment process. The same applies when the value is empty. true value means the user need to input CVV number during the payment process.
  • Create the AMSPaymentProtocol instance for handling corresponding events in subsequent processes, including the following method:
    • onEventCallback: A callback function that returns various types of data or values, including event codes, cardPaymentResultInfo parameter for card payment, and popRiskDecisionResultInfo parameter for risk control. See the References for further information.
  • Create an instance of the AMSLoggerProtocol protocol, which is used to manage log output:
    • logWithName: Optional. It is a callback method that is used to output logs by default.
Interface example for creating SDK instance:
Objective-C
Editor
3

Initiate a createPaymentSession request

Merchant server

The merchant client monitors the click events of the Payment button itself. When the buyer selects the payment method and clicks the payment button, the merchant client initiates createPaymentSession request to the APO server. Once the response to the createPaymentSession request is received, the paymentSessionData value in the response is used in Step 4.

For card token payment mode with bound cards, you need to pass in the paymentMethod.paymentMethodId field to the card token returned to you by APO after the buyer binds the card. The way to obtain the card token is as follows:

  • Independent card binding: Obtain the card token through the card.cardToken field in the asset binding result notification sent to you by APO.
  • Non-independent card binding: Obtain the card token through the paymentResultInfo.cardToken field in the payment result notification sent to you by APO or the response to actively query the payment result。

Note: When calling the createPaymentSession API, the value of the request parameter paymentRedirectUrl needs to use the URL Scheme corresponding to the page you provide after the payment is completed.

The following createPaymentSession request example only includes the required fields and some optional fields:
JSON: No card bound
JSON: Token payment
Editor
Response example for createPaymentSession request:
JSON
Editor
4

Create a payment element collection component using the createComponent method in the instance object:

Merchant client
  • Create a configuration object using the sessionData parameter: Pass in the complete data of the paymentSessionData field obtained from the response of the asset binding session creation request into the sessionData parameter.
  • Call the createComponent() method and create a payment element collection component.
  • Free resources of the SDK component by calling the onDestroy() method in the instance object. You need to unmount a component in the following cases:

    • 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.
Call the createComponent() :
Objective-C
Editor
References

The References offers callback data and code samples for integration steps. For further details, refer to the References.