iOS

In this topic, you'll learn how to integrate the Apple Pay SDK for Apple Pay payment methods, allowing you to render iOS Apple Pay related cashier pages.

Prerequisites

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

Obtain the client ID on Antom Dashboard and complete the key configuration.
Install Xcode 12 or a higher version.
Ensure that the iOS system is iOS 11 or later.

Key integration steps

Integrate the SDK by following these steps:

Integrate the SDK package

Merchant client

Please refer to Integrate the SDK Package for iOS.

Obtain the Apple merchant identifier

1. Log in to the Apple Developer Center and create a new identifier to obtain the Apple Merchant Identifier.

2. Fill in the description and identifier in the form. Ensure that you accurately describe your application. It is recommended to use your app name as the identifier, for example, merchant.com.{{YOUR_APP_NAME}}

For more registration details, please refer to the Apple Developer.

Create a new Apple Pay certificate

Apple Pay certificates are used to encrypt payment data for your application. Follow the steps below to create a certificate for your application:

Contact Antom technical support to obtain a Certificate Signing Request (CSR) file for the Apple security certificate.
Open the Certificates, Identifiers & Profiles page on Apple Developer, click Identifiers, select the Merchant ID and merchant identifier to which you want to add the certificate.
Under the Apple Pay Payment Processing Certificate option, click Create Certificate.
On the Create a New Certificate page, click Choose File, select to upload the CSR file you obtained from Antom. After the CSR is successfully uploaded, Apple Pay will provide you with a downloadable certificate file.

For more operational details, please refer to the Apple Developer.

Notes：

The CSR file corresponds one-to-one with the certificate. If you switch your Apple Merchant ID, you must obtain a new CSR file and create a new Apple security certificate.
The first time you click Create Certificate, the following prompt will appear. Select No to continue.

iOS

Integrate XCode

Open Xcode, click Signing & Capabilities in the project settings, and add Apple Pay to your application. If prompted to log in to your developer account, select the Merchant ID for the certificate you created in step 3.2.

Check whether the buyer's device supports Apple Pay

Please use the code on the right to check if your buyer's device supports Apple Pay. If supported, you can display the Apple Pay payment option in your application.

Editor

Create an SDK instance through AMSCashierPayment

Merchant client

Initialize the checkout payment instance, which includes the following parameters:
- configuration: Required. An object of type AMSCashierPaymentConfiguration, which contains all configuration parameters.
Create AMSCashierPaymentConfiguration type, which includes the following parameters:
- options: Optional. NSDictionary type. It is used to specify whether to use the sandbox environment. Valid values include:
  - "sandbox", "true": Sandbox environment
  - "sandbox", "false": Production environment
Implement the AMSPaymentProtocol protocol for handling corresponding events in subsequent processes, including the following method:
- onEventCallback: Checkout payment event callback function, returning eventCode and eventResult.

Sample code of creating the SDK instance

Objective-C

Editor

Initiate a createPaymentSession request to the APO server

Merchant server

When the buyer selects Apple Pay on the payment method selection page, your client needs to implement the click event listener for the payment button. When the payment button is clicked by the buyer, your server needs to initiate a createPaymentSession request to the APO server. After receiving the response to the createPaymentSession request, use the paymentSessionData parameter value from the response for step eight.

Note：When calling the createPaymentSession API, the value of paymentRedirectUrl needs to use the URL scheme corresponding to the page you provided for redirection after payment completion.

Sample code of the createPaymentSession request

Request sample code

Response sample code

Editor

Use createComponent in the instance object to create the payment element collection component:

Merchant client

Use the sessionData parameter to create a configuration object: Pass the complete data of the paymentSessionData field obtained from the response of the createPaymentSession request into the sessionData parameter.
Call the createComponent() function to create the payment element collection component.
Free resources of the SDK component by calling the onDestroy() function in the instance object. You need to unmount the component in the following cases:
- When the buyer exits the payment page, free the component resources created in createPaymentSession.
- When the buyer initiates multiple payments, free the component resources previously created in createPaymentSession.

Sample code of calling createComponent()

Objective-C

Editor

Event codes

The payment event codes provided by the SDK are as follows:

SDK_PAYMENT_SUCCESSFUL: The payment is accepted. You can call the inquiryPayment API to query the payment result.
SDK_PAYMENT_FAIL: The payment failed. Please guide the buyer to retry the payment based on the errorCode information below.
SDK_PAYMENT_ERROR: The payment status is abnormal. Please investigate possible issues based on the data information in the message.
SDK_PAYMENT_CANCEL: The payment is cancelled. The buyer did not click to pay and has closed the payment window. You can re-invoke the SDK with paymentSessionData within its validity period. If it has expired, you need to request the paymentSessionData again.

The SDK may return the following result codes (result.errorCode):

Code	Value	Message	Further actions
SUCCESS	S	Success	No further action is required.
ORDER_NOT_EXIST	F	The order does not exist.	It is recommended to create a new order.
PAYMENT_IN_PROCESS	U	The payment is being processed.	Wait for the payment notifications or inquire about the payment results.
PROCESS_FAIL	F	A general business failure occurred.	Contact Antom technical support to resolve this issue.
UNKNOWN_EXCEPTION	U	An API call has failed, which is caused by unknown reasons.	Wait for the payment notifications or inquire about the payment results.
INQUIRY_PAYMENT_SESSION_FAILED	F	Failed to retrieve paymentSessionData, which may have expired or is in an unknown state.	The payment session has expired. Wait for the payment notifications or inquire about the payment results.
PAGE_ELEMENT_ILLEGAL	U	The payment information is incorrect.	The payment is declined due to incorrect payment details.