SDK Core for iOS

Actions with payment cards

For performing targeted actions with the direct use of cards, such as purchase processing (NewCardSaleRequest), authorisation holds on funds (CardAuthRequest), and card verification (CardVerifyRequest), the following data sets are used.

Tokenisation

SDK Core for iOS supports tokenisation of payment data. When the scenario of tokenisation (CardTokenizeRequest) is running, no financial operations are performed but a secure identifier associated with the data of a particular payment card is generated. The information about generating and using tokens is provided in the corresponding articles—Tokenization and Payments by using tokens.

For generating tokens via SDK Core for iOS, the following data sets are required.

Usage of saved payment data

SDK Core for iOS supports the capability of saving payment data on the customer initiative and by generating tokens. It also supports using this data for payment processing. With saved payment data and tokens, it is possible to process purchases and place authorisation holds on funds via certain scenarios. In case of saved data, these scenarios are: SavedCardSaleRequest (for processing purchases) and SavedCardAuthRequest (for placing holds on funds); in case of tokens, these scenarios are CardSaleTokenizeRequest (for processing purchases) and CardAuthTokenizeRequest (for placing holds on funds).

Purchases by using alternative methods

SDK Core for iOS supports processing purchases (ApplePaySaleRequest) and placing holds on funds (ApplePayAuthRequest) by using the Apple Pay method.

To process purchases with the use of the Apple Pay method, proceed as follows:

1. In the Apple service, register the merchant identifier (Merchant ID) which allows accepting payments by using the Apple Pay method. This identifier remains valid indefinitely and can be used for various web sites and iOS applications. The information about registering this identifier is provided in the Apple documentation: Create a merchant identifier.
2. Generate an Apple certificate for payment processing (Payment Processing Certificate). This certificate is used together with the merchant identifier and ensures the safety of payment data during payment processing via the Apple Pay method. The information about the certificate generation is provided in the Apple documentation: Create a payment processing certificate.
3. Provide the ecommpay technical support specialists with the payment processing certificate by using the coordinated methods of protection.
4. Set up the support of Apple Pay for the mobile application project in the development environment in use.

Usage of additional parameters

Besides the required minimum of parameters, the additional ones can be used in requests.

• recurrentInfo—object with the COF purchase information (details).
• paymentDescription (string)—payment description.
• regionCode (string)—country code in the format of ISO 3166 alpha-2.
• token (string)—payment data token.
• forcePaymentMethod (string)—code of the preselected payment method. The codes of payment methods are provided in the corresponding reference.
• hideSavedWallets (boolean)—parameter that allows setting whether the payment instruments are displayed or not displayed to the customer. Possible values:
  • true—saved payment instruments are not displayed to the customer.
  • false—saved payment instruments are displayed to the customer.

Saving payment data

During the work with SDK Core for iOS, it is possible to save customer payment data for further processing of payments, without this data being re-entered by customers. Payment data can be saved on the customer's initiative or with the use of the tokenisation scenario (CardTokenizeRequest). While tokenisation is the default capability within the project, the capability of saving payment data on the customer's initiative needs to be set up. To set up the capability of saving payment data address the ecommpay technical support specialists and ensure that the toggle switch for saving data is displayed in the user interface.

As a result of saving payment data on the customer's initiative, a separate identifier (account_id) is generated for each payment instrument. This identifier is associated with the identifier of a particular customer (customer_id). These payment instrument identifiers can be received in the notification from SDK Core for iOS about the payment session creation and used in the request for payment creation.

If the payment data was saved as a result of the CardTokenizeRequest scenario, a token is generated for a certain card of the customer. This token can be received in the notification stating that the token has been generated in the Payment object and further specified in payment requests. For executing the tokenisation scenario, the request for creating a session in SDK Core for iOS (initiated on the merchant's side) should contain the project and customer identifiers, the rest of the details for token generation (the number and expiration date of the payment card and cardholder name) should be requested from the customer.

"SavedAccounts":
{
  "number": "541333******0019",
  "token": "0bd983f99878381dce27d20478829458d19df7c88f287ad8753092d...", // payment data token
  "id": 12353661,   // saved payment data identifier (accountId)
  "last_deposit_date": "2022-04-22 06:22:33",
  "last_tokenize_date": null,
  "type": "card",
  "additional": {
    "email": "john@example.com",
    "phone": "+440202267709",
    "country": "GB",
    "recurring_enable": false,
    "card": {
      "holder": "Jonh Doe",
      "country": "GB",
      "bank_name": "CIAGROUP",
      "type": "mastercard",
      "product_name": "PREPAID",
      "expiry": "02/24"
    }
  },

3‑D Secure authentication

When the customer 3‑D Secure authentication is required for payment processing, proceed as follows:

1. Receive the notification onThreeDSecure stating that displaying the authentication page to the customer is required. This notification contains the acsPage object with the parameters of displaying the authentication page and the link for redirecting the customer after the authentication.
2. Display the authentication page to the customer.
3. Wait for the customer to be redirected from the authentication page and call the threeDSecureHandled method.

func onThreeDSecure(acsPage: AcsPage, isCascading: Bool, payment: Payment)
{
    interactor.threeDSecureHandled()    // calling method
}

Cascade payment processing

In case of a payment attempt failure, the capability of cascade payment processing can be used (details). This capability implies a sequence of payment attempts via alternative providers without the payment method change and can be set up upon coordination with the ecommpay specialists.

With this capability set up for the project in use and after the first unsuccessful attempt, a notification is received from SDK Core for iOS. This notification contains the isCascading object with the value true which means that an additional attempt is available as part of the cascade payment processing. If the customer authentication is required for processing the payment, the merchant should display the error information to the customer, obtain the customer's confirmation to make another attempt, and retry the payment. If the authentication is not required, no additional actions are performed on the merchant's side.

func onThreeDSecure(acsPage: AcsPage, isCascading: true, payment: Payment)
{
    interactor.threeDSecureHandled()  
}

Submission of additional payment information

Generally, for processing a payment, it is enough to send a set of parameters that are mandatory for initiating this payment. Still in some cases, a payment system or a provider can require additional data necessary for processing a particular payment. This can be due to region-specific requirements, the need for an additional anti-fraud check, or other factors. The information about submitting additional payment data is provided in the separate article.

The final set of required parameters can vary depending on a particular provider or payment system. The list of parameters relevant for a particular payment is received in the notification from SDK Core for iOS after the request for payment creation (GetPayInteractor) has been sent. The merchant should ensure that the fields to be filled with the required data are displayed to the customer and then send the obtained values to SDK Core for iOS.

func onClarificationFields(clarificationFields: [ClarificationField], payment: Payment) { // receiving the list of required data
    interactor.sendClarificationFields(clarificationFields) // sending the data received from the customer
}

Collection of customer data

In some cases, alongside the mandatory parameters, it can be relevant to require the additional ones (such as phone numbers and email addresses) from the customers. To have this capability set up, the merchant should decide which data should be requested and mandatory to be specified by the customers, then provide this information to the technical support specialists. For more information about using the capability of collecting additional data, see the separate article.

After receiving the notification with the list of the required parameters from SDK Core for iOS, the merchant should display the fields to be filled by the customer in the payment form, send the obtained data to SDK Core for iOS, and continue payment processing.

func onCustomerFields(customerFields: [CustomerField]) { // receiving the list of required data
    interactor.sendCustomerFields(customerFields) // sending the data received from the customer
}

Informing about payment session

SDK Core for iOS supports sending notifications with the payment session information. Intermediate notifications which are sent during the payment session creation fall under the InitDelegate group and provide information about various events and possible errors that can happen before the request for payment creation is sent. Such notifications include the following ones:

• onInitReceived—the payment session has been created in the ecommpay payment platform.

  func onInitReceived(paymentMethods: [PaymentMethod], savedAccounts: [SavedAccount]) {
      let stringResourceManager = msdkSession.getStringResourceManager()
      let title = stringResourceManager?.payment.methodsTitle
           
      let secureLogoResourceManager = msdkSession.getSecureLogoResourceManager()
      let visaIconUrl = secureLogoResourceManager?.getLogoUrl(key: "visa")
           
      let paymentMethods = msdkSession.getPaymentMethods()
      let savedAccounts = msdkSession.getSavedAccounts() ?? []
  }

• onPaymentRestored—the payment session has been created with the use of a payment identifier used previously. If the payment has not been assigned a final status yet, you can use the PaymentRestoreRequest method and continue processing the previously initiated payment.

  override func viewDidLoad() {
          super.viewDidLoad()
          AppDelegate.msdkSession?.getPayInteractor().execute(request: PaymentRestoreRequest(), callback: self)
      }

• onError—an error has occurred.

  override fun onError(code: "Network & Server API", 
  message: "{"status":"validation","code":"501",
  "errors":{"sid":"Make payment before check status"}}")

Informing about payment

Intermediate and final notifications sent during payment creation fall under the PayDelegate group. Such notifications can contain the information about a payment status, the requirement of performing additional actions, and arising errors.

• onPaymentCreated—the payment has been created.
• onStatusChanged— the payment status has been changed.
• onCustomerFields—additional customer data is required.
• onThreeDSecure—3‑D Secure authentication is required.
• onClarificationFields—additional payment information is required.
• onCompleteWithSuccess—the payment has been completed.
• onCompleteWithFail—the payment has been rejected.
• onCompleteWithDecline—the payment has been declined.
• onError—an error has occurred.

  override fun onError(code: "Network & Server API", 
  message: "{"status":"validation","code":"501",
  "errors":{"sid":"Make payment before check status"}}")