iOS

1. Create an instance for the checkout page. The instance contains the following parameters:
   • configuration: A required object belonging to the AMSCashierPaymentConfiguration type. The object must contain all configuration parameters.
2. Create the AMSCashierPaymentConfiguration class, 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 checkout 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: 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.
     • "showSubmitButton", "true": Configure the SDK component to render the card binding 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 of the card binding process.
     • "notRedirectAfterComplete", "true": The default value is false, which means it will redirect back to your page after the payment is completed. The same applies when the value is empty. true value means there will be no redirect after the payment is completed. You need to use the customer event code to control the card binding to complete the subsequent process. Please note that the payment result event code returned by the client is only used as a reference for the redirect operation of the client page. For transaction status updates, please refer to the results returned by the server's notifyPayment or inquiryPayment API.
     • "merchantAppointmentParam": Optional object used for setting custom features. It contains the following value:
       • storedCard: Optional object used for setting custom features of stored cards. It contains a value below:
         • needCVV: Optional Boolean. The default value is false, which indicates that the buyer does not need to input the CVV number during the payment process. The same applies when the value is empty. The true value means the buyer needs to input the CVV number during the payment process.
3. Create the AMSPaymentProtocol instance for handling corresponding events in subsequent processes, including the following method:
   • onEventCallback: A callback function that returns various types of data or values, including event codes, cardPaymentResultInfo parameter for card payment, and popRiskDecisionResultInfoparameter for risk control. See the References for further information.
4. Create an instance of the AMSLoggerProtocol protocol, which is used to manage log output:
   • logWithName: Optional. It is a callback method that is used to output logs by default.。

The merchant client monitors the click events of the Payment button itself. When the buyer selects the payment method and clicks the payment button, the merchant client initiates createPaymentSession request to the APO server. Once the response to the createPaymentSession request is received, the paymentSessionData value in the response is used in Step 4.

For card token payment mode with bound cards, you need to pass in the paymentMethod.paymentMethodId field to the card token returned to you by APO after the buyer binds the card. The way to obtain the card token is as follows:

• Independent card binding: Obtain the card token through the card.cardToken field in the asset binding result notification sent to you by APO.
• Non-independent card binding: Obtain the card token through the paymentResultInfo.cardToken field in the payment result notification sent to you by APO or the response to actively query the payment result.

• Use the MountComponent method in the instance object:
  • Create a configuration object using the vaultingSessionDataparameter: 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.

• Free resources of the SDK component by calling the unmount() method in the instance object. You need to unmount a component in the following cases:

  • When the user switches views to exit the checkout page, free the component resources created in the createPaymentSession API.
  • When the user initiates multiple payments, free the component resources created in the previous createPaymentSession API.
  • When the user completes the payment and sets notRedirectAfterComplete to true, free the component resources after obtaining specific payment result codes.

• SDK_PAYMENT_SUCCESSFUL: The payment was successful. Suggest redirecting buyers to the payment result page.
• SDK_PAYMENT_FAIL: The payment failed. We suggest that you check the value of paymentResultCode in the onEventCallback result data for details. Guide users to retry the payment based on the provided information.
• SDK_PAYMENT_PROCESSING: The payment is being processed. Your server can check the payment status or waits for the payment result notification.
• SDK_PAYMENT_ERROR: The payment status is abnormal. Your server can check the payment status or wait for the payment result notification.
• SDK_PAYMENT_CANCEL: The buyer did not proceed with the payment and closed the payment window. You can use the valid paymentSessionData to call the SDK again. If it has expired, new paymentSessionData must be requested.
• SDK_FORM_VERIFICATION_FAILED: After the form submission, the verification failed. The SDK will display the form error codes on the element page.

The SDK may return the following payment status (paymentStatus):

• SUCCESS: indicates that the payment is successful.
• FAIL: indicates that the payment failed.
• PROCESSING: indicates that the payment is being processed.
• CANCELLED: indicates that the payment is cancelled.
• PENDING: indicates that the payment is complete. Wait for the payment result notification.

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

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