iOS

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

Prerequisites

Before integrating the card payment SDK, familiarize yourself with the Integration guide and Overview. This will enable you to understand the steps for integrating server APIs and notes for calling the APIs. Also, ensure that you have completed the following tasks:

Obtain a client ID in Antom Dashboard.
Properly configure keys in Antom Dashboard
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 card payment SDK by following these steps:

Integrate the SDK package

Client side

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

Create an SDK instance by using the AMSCashierPayment method:

Client side

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.
Create the AMSCashierPaymentConfiguration class, which must contain the following parameters:
- locale: An optional parameter belonging to the 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
  - pt_BR: Portuguese
  - ko_KR: Korean
  - es_ES: Spanish
- 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, which is used to manage log output. It contains the following method:
- logWithName: A callback function used to output logs by default.

Create a configuration object:

Objective-C

Editor

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

Server side

After the buyer selects a card payment method for payment, your client starts monitoring the payment button click event. When your client detects that the payment button is clicked, your server needs to send a createpaymentSession (Checkout Payment) request to the Alipay server. After you receive the response from the API call, use the value of the paymentSessionData parameter to complete Step 4.

Note: In your createpaymentSession (Checkout Payment) request, specify paymentRedirectUrl as the URL Scheme that you provide to redirect buyers to the payment result page upon payment completion.

The following sample for calling the createPaymentSession API includes mandatory parameters and several optional parameters.

JSON

Editor

The response sample of the API call is shown as follows:

JSON

Editor

Create a component for collecting payment factors by using the createComponent method in the instantiated object

Client side

Create a configuration object by using the sessionData parameter: Pass the complete data in the paymentSessionData parameter obtained in the response through the createpaymentSession API to the sessionData parameter.
Call the createComponent() method to create a component for collecting payment factors.
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

Reference

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 createComponent method are incorrect. Ensure the parameters are passed correctly and send a new request.
SDK_CALL_URL_ERROR: Represents one of the following cases:
- The redirection to the merchant page failed to be executed.
- The parameter paymentRedirectUrl in your createpaymentSession (Cashier Payment) request is not passed or passed incorrectly.
SDK_INTEGRATION_ERROR: Dependencies are not found. Ensure that the dependencies are added correctly and retry the integration process.

Code sample in key steps

The following code sample shows the key steps during integration. The sample does not include the code used for calling the createpaymentSession (Cashier Payment) API.

Objective-C

Editor