iOS

In this topic, you'll learn how to integrate the SDK into an iOS client so that you can render cashier pages in a mobile application. The integration process is the same for the seamless experience and the redirection experience.

Prerequisites

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.

Key integration steps

For first-time payments and subsequent payments, integrate the SDK by following these steps:

Import the SDK package

Client side

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

Display available payment methods

Client side

Use the tool to obtain available payment methods, customize their logos, and display them on your cashier pages.

For first-time payments, we recommend you display the names and logos of available payment methods. For subsequent payments, we recommend you display the names and logos of these payment methods as well as the desensitized buyer account.

Create an SDK instance by using the AMSEasyPay method:

Client side

Create an instance for cashier pages. The instance contains the following parameter:
- configuration: A required object belonging to the AMSEasyPayConfiguration type. The object must contain all configuration parameters.
Create the AMSEasyPayConfiguration class, which must contain the following parameters:
- locale: An optional string, 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
  - ms_MY: Malaysian
  - tl_PH: Filipino
  - ko_KR: Korean
  - vi_VN: Vietnamese
  - zh_HK: Traditional Chinese (Hong Kong, China)
- 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.
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.
Create an instance of the AMSLoggerProtocol interface used to manage log output. It contains the following method:
- logWithName: A callback function used to output logs by default.

Create an SDK instance:

Objective-C

Editor

Send a createPaymentSession 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 request. Get the paymentSesssionData value from the createPaymentSession response and use it in Step 5.

For the first-time payment or subsequent payments, you need to specify different parameters when calling the createPaymentSession API:

The first-time payment

paymentRedirectUrl: The URL of the merchant result page. We recommend that you pass in a scheme URL or H5-scheme URL.
authState: The unique ID generated by the merchant to initiate an EasySafePay authorization. Specify this parameter to obtain an access token for future password-free payments.
paymentNotifyUrl: The URL that is used to receive the payment result notification. It must be an HTTPS URL.
paymentSessionExpiryTime: The date and time when the payment session expires. It defaults to 1 hour and must not exceed 1 hour. The value follows the ISO 8601 standard format. For example, "2019-11-27T12:01:01+08:00".
userLoginId: The login ID that the user used to register in the wallet. The login ID can be the user's email address or phone number.
order.buyer.referenceBuyerId/buyerPhoneNo/buyerEmail: Pass in the buyer information for Alipay to provide risk control policies. Pass in one of the three parameters: referenceBuyerId, buyerPhoneNo, and buyerEmail.

The subsequent payments

paymentMethod.paymentMethodId: Pass in accessToken that you obtain from the notifyAuthorization API for the first-time payment.
paymentRedirectUrl: The URL of the merchant result page. We recommend that you pass in a scheme URL or H5-scheme URL.
paymentNotifyUrl: The URL that is used to receive the payment result notification. It must be an HTTPS URL.
paymentSessionExpiryTime: The date and time when the payment session expires. It defaults to 1 hour and must not exceed 1 hour. The value follows the ISO 8601 standard format. For example, "2019-11-27T12:01:01+08:00".
order.buyer.referenceBuyerId/buyerPhoneNo/buyerEmail: Pass in the buyer information for Alipay to provide risk control policies. Pass in one of the three parameters: referenceBuyerId, buyerPhoneNo, and buyerEmail.

First-time payment

JSON

Editor

Subsequent payment

JSON

Editor

Render the payment pages

Client side

Use the createComponent method in the configuration object.

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.
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

Objective-C

Editor

Obtain an authorization result or a payment result

Server side

Regardless of a seamless experience or a redirection experience, you can obtain an authorization result and a payment result for first-time payments, and a payment result only for subsequent payments:

Obtain an authorization result
When the authorization is successful, Alipay sends you the asynchronous notification through the notifyAuthorization notification. When you receive the notification, you must return a response as instructed in Requirements. Meanwhile, you must update the authorization status of the buyer in your system and display the buyer's desensitized account obtained from the notification on your authorization management page.
Obtain a payment result
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.

Note: If you call the inquiryPayment API and the cancel API after the buyer abandons the payment, you might receive a response indicating that the order does not exist, and you might not receive an asynchronous notification of the payment failure as well. We recommend that you take the following actions:

For orders that you have actively closed:

If you receive a payment success notification from Alipay, no further action is needed.
If you receive a notification from Alipay with an unknown order status, call the cancel API to cancel the corresponding order.

For duplicate payments (one merchant order corresponds to multiple Alipay orders), if you have received multiple payment success notifications for Alipay orders, keep only one Alipay order with a successful result and cancel the rest of the Alipay orders by using the cancel 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.
SDK_PAYMENT_CANCEL: The user cancels the payment on the account confirmation page or the large transaction confirmation page.

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 AMSEasyPay 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.