iOS

In this topic, you'll learn how to integrate the independent card binding SDK into an iOS client. This 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 independent card binding SDK by following these steps:

Integrate the SDK package

Merchant client

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

Create an SDK instance by using the AMSVaulting:

Merchant client

Create an instance for cashier pages. The instance contains the following parameters:
- configuration: A required object belonging to the AMSVaultingConfiguration type. The object must contain all configuration parameters.
Create AMSVaultingConfiguration, 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.
  - "showSubmitButton", "true": Configure the SDK component to render the binding card button.
  - "showSubmitButton", "false"Configure the merchant to render the card binding button, while also calling the submit method in the instance object to trigger the submission card binding process.
Create the AMSPaymentProtocol instance for handling corresponding events in subsequent processes, including the following methods:
- onEventCallback: Cashier payment event callback method, returning eventCode and eventResult.
Create the AMSLoggerProtocol instance, which is used to manage log output：
- logWithName: It is a callback method that is used to output logs by default

Interface example for creating SDK instance:

Objective-C

Editor

Initiate a createVaultingSession request

Merchant server

The merchant client monitors the click events of the Add Card button itself. When the buyer selects the payment method and clicks the card binding button, the merchant client initiates the createVaultingSession request to the Antom server. Once the response to the createVaultingSession request is received, the vaultingSessionData value in the response is used in Step 4.

If you need to automatically redirect buyers to your page after card value binding is complete, pass in the redirectUrl field in the createVaultingSession API. If you want to control the subsequent process of card binding completion yourself through client-side event codes, you do not need to pass in this field, and monitor the card binding result event code throughonEventCallback.

Note: The binding result event code returned by the client is only used as a reference for redirection operations on the client page. Please refer to the notifyVaulting API on the server for updates on the binding status.

JSON

Editor

Render card binding element collection components

Merchant client

Use the MountComponent method in the instance object:
- Create a configuration object using the vaultingSessionData parameter: Pass in the full data of the vaultingSessionData field obtained in Step 4 into the vaultingSessionData parameter of mountComponent.
- Call themountComponent() method in the instance object.
Call the submit() method in the instance object:
- Calling this method triggers the card-binding submission process, and the return value is a Promise that returns a specific event code. These event codes are also returned by events such as onError or onEventCallback.
- If you need to pass in pre-collected billing address information for AVS validation, you can configure the following parameters to be passed in via the submit() method.
  - billingAddress: Optional Object. Billing address information is used to identify and locate the payer. It contains the following parameters:
    - region: Required. String (2). ISO 3166 compliant 2-digit country code.
    - zipCode: Optional. String (32). Zip code.
    - address2: Optional. String (256). Address line 2, e.g., apartment, suite, unit, and building information.
    - address1: Optional. String (256). Address line 1, e.g., street address, P.O. Box, and company name.
    - city: Optional. String (32). Name of the city, region, suburb, town or village.
    - state: Optional. String (8). The name of the state, country, or province.

Call createComponent()

Objective-C

Editor

Uninstall components

Merchant client

Destroy a created component by calling the onDestroy() method in the instance object. You need to unmount a component in the following cases:

If your client has set a timeout when the set timeout is reached.
When the buyer exits the card binding page.
When you receive a callback for the card binding result.

Note: Only one component can be created at a time. If you need to use a different vaultingSessionData or recreate a component, you need to first execute the uninstall method.

Call onDestroy():

Objective-C

Editor

Obtain the result

Merchant server

When the card is successfully bound, Antom sends an asynchronous notification via the notifyVaulting API to the notification recipient address that you passed in the notifyVaulting API. If you receive an asynchronous notification from Antom, you need to return the response in the sample code format of Process the notification. At the same time, you need to update the card binding status of the buyer in your system, and it is recommended to display the corresponding desensitized card number on your card binding management page according to the card information in the notification.

Event codes

The SDK provides the following error codes:

SDK_INTERNAL_ERROR: SDK internal error. Please contact Ant Group technical support.
SDK_CREATEPAYMENT_PARAMETER_ERROR: mountComponent method passed in parameter abnormally, please check if the parameter is correct and retry the request by replacing the vaultingRequestId.
SDK_INIT_PARAMETER_ERROR: AMSVaulting method passed in parameter abnormally. Please check if the parameter is correct and retry the request by replacing the vaultingRequestId.
SDK_CREATECOMPONENT_ERROR: Component initialization exception. Please contact Ant Group technical support.
SDK_ABNORMAL_RENDERING_DATA: Rendering data exception. Please retry the initialization process or contact technical support for troubleshooting.
SDK_SUBMIT_NETWORK_ERROR: Interface call failed due to network reasons. It may occur in submit method submission. Please try to submit it again.

The SDK provides the following status codes:

SDK_START_OF_LOADING: The loading animation starts to be shown when the component is created. When configured to hide loading and use a custom animation, the custom animation can be rendered at this time.
SDK_END_OF_LOADING: The loading animation ends when the component is created. When configured to hide loading and use custom animation, the animation can be hidden at this time.
SDK_CALL_URL_ERROR: Fail to redirect to the merchant page. Check if the redirect merchant link can be accessed normally. If the URL can be accessed normally, please contact Ant Group technical support.
SDK_CALL_URL_SUCCESS: The merchant page was successful. No further action is required.
SDK_FORM_VERIFICATION_FAILED: The form validation fails after submitting the form. The SDK will display the form error on the element collection page. The merchant can also guide the user to enter the correct information through the text.
SDK_DUPLICATE_SUBMISSION_BEHAVIOR: The form is submitted repeatedly. The merchant can prompt the user with a toast so that they don't have to click submit repeatedly.

The card-binding result event codes and result codes provided by the SDK are as follows:

Result event codes (code):

SDK_ASSET_BINDING_FAIL: Card binding failed. We suggest that you follow the vaultingResultCode error code prompt and guide the user to bind the card again.
SDK_ASSET_BINDING_SUCCESSFUL: Card binding is successful, and SDK needs to be deregistered. Suggest redirecting to the binding result page.
SDK_ASSET_BINDING_ERROR: Card binding is abnormal. We suggest that you wait for the card binding result notification or redirect the user to bind the card.

Inquire about the card binding status on the server side (vaultingStatus):

SUCCESS: Indicates successful card binding.
FAIL: Indicates card binding failed.

Inquire about the result code on the server side (result.resultCode):

Result code	Value	Message	Suggestion
SUCCESS	S	Success	-
PROCESS_FAIL	F	A general business failure occurred.	It requires manual confirmation of the issue. We suggest that you contact Antom technical support to resolve the issue.
UNKNOWN_EXCEPTION	U	An API call has failed, which is caused by unknown reasons.	-

Inquire about the card binding result code on the server side (vaultingResultcode):

Result code	Value	Message	Suggestion
PROCESS_FAIL	F	A general business failure occurred.	It requires manual confirmation of the issue. We suggest that you contact Antom technical support to resolve the issue.

Example of card binding result event code processing:

Objective-C

Editor

Example of card binding result:

Successful

Failed

Editor