iOS

In this topic, you'll learn how to integrate the pop-up card vaulting SDK with an iOS client. This will allow you to render the card vaulting page in a mobile application.

Prerequisites

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

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

Key integration steps

Integrate the independent card vaulting 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 AMSVaulting .

Merchant client

Create an instance for the cashier page. The instance contains the following parameters:
- configuration: Required. An object of type AMSVaultingConfiguration . 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 render the cashier page in the corresponding language. Valid values are listed as follows. If other values are passed, English is used:
  - en_US: English
  - pt_BR: Portuguese
  - ko_KR: Korean
  - es_ES: Spanish
  - fr_FR: French
  - nl_NL: Dutch
  - it_IT: Italian
  - de_DE: German
  - zh_CN: Simplified Chinese
  - zh_HK: Traditional Chinese
- options: Optional. NSDictionary type. It is used to specify whether to use the sandbox environment. Valid values are:
  - "sandbox", "true": Sandbox environment.
  - "sandbox", "false": Production Environment.
  - "notRedirectAfterComplete", "true": Optional, Boolean type. The default value is false , indicates that redirection to your page takes place after the card vaulting is complete. The same applies when the value is empty. When the value is true, redirection will not take place after the card vaulting is complete. You need to use the customer event code to control the card vaulting and complete the subsequent process. Please note that the card vaulting result event code returned by the client is only used as a reference for the redirection of the client page. For transaction status updates, please refer to the results returned by notifyVaulting or inquireVaulting.
Create the AMSPaymentProtocol instance for handling corresponding events in subsequent processes, including the following methods:
- onEventCallback: The card vaulting event callback function that returns eventCode and eventResult.
Create the AMSLogProtocol instance, which is used to manage log output. The function includes:
- logWithName: A default callback method that is used to output logs.

Sample code 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 a payment method and clicks the card vaulting button, the merchant server sends 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 vaulting is complete, pass in the redirectUrl field in the createVaultingSession API. If you want to control the subsequent process of card vaulting through client-side event codes, you do not need to pass in the redirectUrl field. You can monitor the card vaulting result event code through onEventCallback.

Note: The vaulting 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 vaulting status.

Sample code of the createVaultingSession request

Editor

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

Merchant client

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

Sample code of calling createComponent()

Objective-C

Editor

Obtain the vaulting result

Merchant server

When the card vaulting is successful, Antom sends an asynchronous notification via the notifyVaulting API to the notification recipient address that you passed in the createVaultingSession API.

If you receive an asynchronous notification from Antom, you need to return the response in the specific code format specified in Process the notification. At the same time, you need to update the card vaulting status of the buyer in your system, and it is recommended to display the corresponding desensitized card number on your card vaulting management page according to the card information in the notification.

Sample code of key integration steps

The following sample code demonstrates the key steps in the integration process. The code does not include examples of calling the createVaultingSession API. You need to handle the server API calls on your own.

Objective-C

Editor

Event codes

The SDK may return the following error codes:

SDK_INTERNAL_ERROR: SDK internal error. Please contact Antom technical support.
SDK_CREATEPAYMENT_PARAMETER_ERROR: The createComponent method passed in parameters abnormally, please check if the parameter is correct and retry the request by replacing the vaultingRequestId.
SDK_INIT_PARAMETER_ERROR: The AMSVaulting method passed in parameters abnormally. Please check if the parameter is correct and retry the request by replacing the vaultingRequestId.
SDK_CREATECOMPONENT_ERROR: Component initialization exception. Please contact Antom 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 the submit method submission. Please try to submit it again.

The SDK may return the following event codes:

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 Antom technical support.
SDK_CALL_URL_SUCCESS: Redirection to the merchant page is 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 prompt the buyer to enter the correct information.
SDK_DUPLICATE_SUBMISSION_BEHAVIOR: The form is submitted repeatedly. The merchant can prompt the buyer not to click submit repeatedly.

The SDK may return the following card-vaulting result event codes and result codes:

SDK_ASSET_BINDING_FAIL: Card vaulting failed. We suggest that you follow the vaultingResultCode error code prompt and guide the buyer to retry the card vaulting.
SDK_ASSET_BINDING_SUCCESSFUL: Card vaulting is successful, and the SDK needs to be revoked. It is recommended that you redirect to the vaulting result page.
SDK_ASSET_BINDING_ERROR: Card vaulting is abnormal. We suggest that you wait for the card vaulting result notification or redirect the buyer to retry card vaulting.

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

Code	Value	Message	Further actions
SUCCESS	S	Success	No further action is required.
PROCESS_FAIL	F	A general business failure occurred.	Do not retry. Human intervention is usually needed. It is recommended that you contact Antom Technical Support to troubleshoot the issue.
UNKNOWN_EXCEPTION	U	An API call has failed, which is caused by unknown reasons.	Wait for the card vaulting notifications or inquire about the card vaulting results.

The SDK may return the following card vaulting result codes (result.resultCode):

Code	Value	Message	Further actions
PROCESS_FAIL	F	A general business failure occurred.	Do not retry. Human intervention is usually needed. It is recommended that you contact Antom Technical Support to troubleshoot the issue.

Sample code of card vaulting result codes handling:

Objective-C

Editor

Sample code of card vaulting result:

Successful

Failed

Editor