# SDK UI & Core for iOS {#en_sdk_ui_and_core_ios}

An article about using SDK UI & Core for integrating a payment form with the interface from Ecommpay in iOS mobile applications.

**Parent topic:**[Integration using SDK](en_sdk_overview.md)

## Overview {#en_sdk_ui_and_core_ios_overview}

### Introduction {#section_lvb_4bk_lvb .section}

Mobile SDK UI & Core for iOS is a software development kit with open-source code that can be used to integrate iOS applications with the Ecommpay payment platform.

SDK UI & Core for iOS provides the functionality for interaction of customers with the user interface and for interaction of a mobile application with the payment platform which allows sending and receiving necessary information during payment processing. Additionally, the open-source code available with SDK UI & Core for iOS provides flexibility for configuring the user interface in accordance with the aspects of the application.

SDK UI & Core for iOS can be embedded in mobile applications developed for iOS version 15.6 or later. The libraries and code examples are available on GitHub. To access, use the following URLs:

-   List of SDK UI & Core for iOS releases: [https://github.com/ITECOMMPAY/mobile-sdk-ios-ui/releases](https://github.com/ITECOMMPAY/mobile-sdk-ios-ui/releases)
-   Code examples: [https://github.com/ITECOMMPAY/mobile-sdk-ios-ui/tree/master/IntegrationSamples](https://github.com/ITECOMMPAY/mobile-sdk-ios-ui/tree/master/IntegrationSamples)

This article describes how to work with SDK UI & Core for iOS and provides code examples in Swift and Objective-C.

### Capabilities {#section_gmj_bw1_nvb .section}

The following functional capabilities are supported by SDK UI & Core for iOS:

-   Processing different types of paymentsmade with cards and Apple Pay as well as other payment methods available for the merchant's project. Supported payment types include:

    -   One-time one-step purchases.
    -   One-time two-step purchases \(an authorisation hold can be placed via the SDK and subsequent debiting of the authorised amount is carried out via Gate or Dashboard\).
    -   COF purchases \(they can be registered via the SDK and then managed via Gate or Dashboard\).
    **Note:** In case of card and Apple Pay payments, the payment interface described in this article is used. With other payment methods, Payment Page is used during payment processing.

-   Performing payment card verification \(it involves debiting a zero amount from the customer's card\).
-   Checking current payment information.
-   Auxiliary procedures and additional capabilities to boost payment acceptance rates:
    -   Submission of additional payment information.
    -   Payment retries.
    -   Cascade payment processing.
    -   Collecting customer data.
-   Additional capabilities to improve user experience:
    -   Saving customer payment data.
    -   Payment interface language support.
    -   Sending email notifications with the list of purchased items to customers.
-   Customising the appearance of the payment interface including the colour scheme settings and the option to add the logo.

### Workflow {#section_fzd_1dk_lvb .section}

Generally, the following workflow is relevant when purchases are processed with the use of SDK UI & Core for iOS.

![](images/sdk/ios/en_sdk_ui_core_functional_ios.svg)

1.  In the user interface of a mobile application, the customer initiates a purchase by clicking the payment button or in a different fashion set up on the merchant side.
2.  In the mobile application, a set of parameters for creating a payment session is generated. Then, with the help of SDK UI & Core for iOS, this set is converted into a string for signing, and the string is sent to the server side of the merchant web service.
3.  On the server side of the merchant web service, the parameters can be checked and supplemented if necessary, and the signature to the final parameter set is generated, following which the prepared data is sent back to SDK UI & Core for iOS.
4.  With the help of SDK UI & Core for iOS, a payment session is initiated in the payment platform.
5.  On the payment platform side, the payment interface is prepared in accordance with the invocation parameters, and the data for opening the interface is passed to the customer's device.
6.  In the mobile application, the payment form is displayed to the customer.
7.  The customerselects a payment method \(if no method was selected when the payment session was initiated\), specifies the necessary information, and confirms the purchase.
8.  SDK UI & Core for iOS sends a purchase request to the payment platform.
9.  On the payment platform side, the payment is registered and all necessary technical actions are performed; these actions include sending the required data to the payment environment—to theproviders and payment systems.
10. The payment is processed in the payment environment. Then the payment result information is received in the payment platform.
11. In the payment platform, the information about the payment result is processed and a callback is sent to the server side of the web service.
12. The information about the purchase result is sent from the payment platform to SDK UI & Core for iOS.
13. The notification with the result information is displayed to the customer in the user interface.

### Interface {#section_aqm_ldk_lvb .section}

Whencard and Apple Pay payments are processed, the customer interacts with the user interface designed by the Ecommpay specialists. This user interface can be customised: you can change its colour and add your company's logo.

![](images/sdk/ios/all_sdk_ui_core_ios_design_color.svg "Customisation options")

![](images/sdk/ios/all_sdk_ui_core_ios_design_card_details.svg "Page to enter payment details")

![](images/sdk/ios/all_sdk_ui_core_ios_design_result.png "Payment result page")

## Setup {#en_sdk_ui_and_core_ios_setup}

### Integration steps {#section_sfv_cnk_lvb .section}

To integrate the web service with the Ecommpay payment platform by using SDK UI & Core for iOS:

1.  Address the following organisational issues of interaction with Ecommpay:
    1.  If your company has not obtained a project identifier and a secret key for interacting with Ecommpay, submit the application for connecting to the Ecommpay payment platform.
    2.  If your company has obtained a project identifier and a secret key for interacting with Ecommpay, inform the technical support specialists about the company's intention to integrate by using SDK UI & Core for iOS and coordinate the procedure of testing and launching the functionality.
2.  Complete the following preliminary technical steps:
    1.  Download and link the SDK UI & Core for iOS libraries.
    2.  Ensure the collection of data necessary for opening the payment form. The minimum data set needed in order to open the payment form consists of the project, payment, and customer identifiers as well as of the payment amount and currency.
    3.  Ensure signature generation for the data on the server side of the mobile application.
    4.  Ensure the receipt of and the response to the notifications from SDK UI & Core for iOS as well as the receipt of and the response to the callbacks from the payment platform on the web service side.
3.  With the technical support specialists, coordinate the timeline and the main steps of integrating, testing\(including testing available payment methods\), and launching the solution.
    1.  For testing, use the test project identifier and the details of [test cards](en_test_cards.md).
    2.  For switching to the production mode, change the value of the test project identifier to the value of the production project identifier received from Ecommpay.

If you have any questions about working with SDK UI & Core for iOS, contact the Ecommpay technical support specialists \([support@ecommpay.com](mailto:support@ecommpay.com)\).

### Importing libraries in Swift {#section_cjg_3nk_lvb .section}

To add a library into your iOS app:

1.  Copy the `ecommpaySDK.xcframework` file in the project folder of you iOS app.
2.  Add the library into your project. When using Xcode 12, you need to do the following:
    1.  Open the target of your project.
    2.  Select **General** \> **Embedded Binaries**.
    3.  Click **+**.
    4.  Click **Add Other**.
    5.  Select the `ecommpaySDK.xcframework` file and click **Add**.
3.  Add key **NSCameraUsageDescription** with value `permission is needed in order to scan card` to the **Info.plist** file.
4.  If your iOS app does not use user location information, add the **NSLocationWhenInUseUsageDescription** key with the `fraud prevention` value in the **Info.plist** file.

    The Ecommpay libraries code does not request user location if the request is not initiated by the host app, but the App Store requires that the **NSLocationWhenInUseUsageDescription** key value is not empty.

    If your iOS app requests user location information, you can skip this step.

5.  If the iOS app does not have permission to save data on the mobile device, add **Privacy - Photo Library Usage Description** and **Privacy - Photo Library Additions Usage Description** keys with values to the **Info.plist** file. The values specified are shown to the customer in the permission request message.

### Importing libraries in Objective-C {#section_elw_bpk_lvb .section}

To add a library into your iOS app:

1.  Copy the `ecommpaySDK.xcframework` file in the project folder of you iOS app.
2.  Add the library into your project. When using Xcode 12, you need to do the following:
    1.  Open the target of your project.
    2.  Select **General** \> **Embedded Binaries**.
    3.  Click **+**.
    4.  Click **Add Other**.
    5.  Select the `ecommpaySDK.xcframework` file and click **Add**.
    6.  Select **Build Settings**.
    7.  Set **Always embed swift embedded libraries** to **Yes**.
3.  Add key **NSCameraUsageDescription** with value `permission is needed in order to scan card` to the **Info.plist** file.
4.  If your iOS app does not use user location information, add the **NSLocationWhenInUseUsageDescription** key with the `fraud prevention` value in the **Info.plist** file.

    The Ecommpay libraries code does not request user location if the request is not initiated by the host app, but the App Store requires that the **NSLocationWhenInUseUsageDescription** key value is not empty.

    If your iOS app requests user location information, you can skip this step.

5.  If the iOS app does not have permission to save data on the mobile device, add **Privacy - Photo Library Usage Description** and **Privacy - Photo Library Additions Usage Description** keys with values to the **Info.plist** file. The values specified are shown to the customer in the permission request message.

### Importing libraries via Cocoapods {#section_bgb_cpk_lvb .section}

To add a library into your iOS app:

1.  Open the **Podfile** file and add the following strings:

    ``` {#codeblock_qgf_1hp_4fc}
    target 'App' do
      # Pods for App
      pod 'EcommpaySDK_UI'
    end
    ```

2.  Add key **NSCameraUsageDescription** with value `permission is needed in order to scan card` to the **Info.plist** file.
3.  If your iOS app does not use user location information, add the **NSLocationWhenInUseUsageDescription** key with the `fraud prevention` value in the **Info.plist** file.

    The Ecommpay libraries code does not request user location if the request is not initiated by the host app, but the App Store requires that the **NSLocationWhenInUseUsageDescription** key value is not empty.

    If your iOS app requests user location information, you can skip this step.

4.  If the iOS app does not have permission to save data on the mobile device, add **Privacy - Photo Library Usage Description** and **Privacy - Photo Library Additions Usage Description** keys with values to the **Info.plist** file. The values specified are shown to the customer in the permission request message.

### Signature generation {#section_cjs_1pk_lvb .section}

Make sure that the data is signed on the server side of the web service with the use of the secret key received from Ecommpay. To work with the signature, you can use ready-to-use components, such as language-specific SDKs for web services \([details](en_sdk_overview.md)\), or your own in-house solutions. The procedure of working with the signature is described in [Signature generation and verification](en_platform_signature.md).

## Testing {#en_sdk_ui_and_core_ios_testing}

If necessary, you can open the payment form in the test mode in order to get information about errors if there were any when payment parameters were specified or to test processing payments with a certain payment result. When creating the request to open the payment form, in the `PaymentOptions` object specify the following values for the `mockModeType` parameter \(the values are listed for Swift and Objective-C respectively\):

-   `MockModeType.success` / `MockModeTypeSuccess`—if you need to receive `Success` payment result.
-   `MockModeType.decline` / `MockModeTypeDecline`—if you need to receive `Decline` payment result.

If you need to switch to the production mode, pass `MockModeType.disabled` / `MockModeTypeDisabled` as a value for the `mockModeType` parameter.

You can also test payment processing in the test environment of the Ecommpay payment platform. In this case, you should get access to the Ecommpay test environment\(it can be done via [an application](https://ecommpay.com/sign-up/) on the company's main site\) and use the identifier and the secret key of the test project as values of the required parameters passed in the request to open the payment form.

The code samples that are provided on Github contain constants for these parameters

```language-c
 let secret = "your_secret" // secret key of the test project
    let project_id: Int32 = 10 // identifier of the test project
```

```language-c

#define SECRET @"your_secret" // secret key of the test project
#define PROJECT_ID 10 // identifier of the test project
```

To switch to the production mode, change the test values \(the identifier and the secret key of the test project\) to the production ones.

**Warning:** Do not test Apple Pay payments via SDK UI & Core for iOS on simulated iOS devices. Testing the flow of Apple Pay requires a physical device, as the simulator cannot generate a valid Apple Pay token, which results in payment failures. Any errors observed in a simulation environment are expected and do not reflect the behaviour of a production integration.

## Use {#en_sdk_ui_and_core_ios_use}

### Opening payment form {#en_sdk_ui_and_core_ios_openingpf}

SDK UI & Core for iOS supports such actions as performing one-time purchases and placing authorisation holds as part of executing two-step purchases, registering COF purchases and performing payment card verification. To initiate these actions, you need a certain parameter set. The required minimum of parameters is passed in the `PaymentOptions` object. Optional parameters can be passed in the same object. In addition, they can also be requested from the customer or received from the payment platform.

#### Opening the payment form in Swift {#section_if5_vxy_lvb .section}

To open the payment form:

1.  Import the library:

    ```language-c
    import ecommpaySDK
    ```

2.  Declare the EcommpaySDK library in you app \(for example, inside the `viewDidLoad` method\):

    ```language-c
    let ecommpaySDK = EcommpaySDK()
    ```

3.  Create an object named `PaymentOptions`. This object must contain the following required parameters:

    -   `projectId` \(integer\)—a project identifier assigned by Ecommpay
    -   `paymentId` \(string\)—a payment identifier unique within the project
    -   `paymentCurrency` \(string\)—the payment currency code in the ISO 4217 alpha-3 format
    -   `paymentAmount` \(integer\)—the payment amount in the smallest currency unit
    -   `customerId` \(string\)—a customer's identifier within the project
    For card payments, also pass the `additionalFields` parameter with at least one of the following parameters: `customer_email` or `customer_phone`.

    To specify the action you need, indicate the required operation type: `Sale`, `Auth`, or `Verify` in the `action` parameter. You can also add any other parameters listed in [the following section](en_sdk_ui_and_core_ios.md).

    The following is an example of the `PaymentOptions` object that includes optional parameters \(description of the payment and the customer's country\)

    ```language-c
    let paymentOptions = PaymentOptions(projectID: 10,
                                paymentID: "internal_payment_id_1",
                                paymentAmount: 1999,
                                paymentCurrency: "USD",
                                paymentDescription: "T-shirt with dog print",
                                customerID: "10",
                                regionCode: "US")
    ```

4.  Pack all payment parameters into a string for signing:

    ```language-c
    paymentOptions.paramsForSignature();
    ```

5.  Send the string to the server side of your web service.
6.  Have your web service generate the signature on the basis of the string and your secret key.
7.  Add signature in your `PaymentOptions` object:

    ```language-c
    paymentOptions.signature = signature;
    ```

8.  Open the payment form by using the following code:

    ```language-c
    ecommpaySDK.presentPayment(at: self, paymentOptions: paymentOptions) { result in
             print("ecommpaySDK finished with status \(result.status.rawValue)")
       ...
     }
    ```

    Before opening the payment form, the library checks for any errors and opens the payment form only if no errors occur. Otherwise, the payment form is not opened and the `presentPayment` method returns the error code.


#### Opening the payment form in Objective-C {#section_zqz_vxy_lvb .section}

To open the payment form:

1.  Import the library:

    ```language-c
    #import <EcommpaySDK/EcommpaySDK.h>
    ```

2.  Declare the EcommpaySDK library in you app \(for example, inside the `viewDidLoad` method\):

    ```language-c
    EcommpaySDK *self.EcommpaySDK = [[EcommpaySDK alloc] init];
    ```

3.  Create an object named `PaymentOptions`. This object must contain the following required parameters:

    -   `projectId` \(integer\)—a project identifier assigned by Ecommpay
    -   `paymentId` \(string\)—a payment identifier unique within the project
    -   `paymentCurrency` \(string\)—the payment currency code in the ISO 4217 alpha-3 format
    -   `paymentAmount` \(integer\)—the payment amount in the smallest currency unit
    -   `customerId` \(string\)—a customer's identifier within the project
    For card payments, also pass the `additionalFields` parameter with at least one of the following parameters: `customer_email` or `customer_phone`.

    To specify the action you need, indicate the required operation type: `Sale`, `Auth`, or `Verify` in the `action` parameter. You can also add any other parameters listed in [the following section](en_sdk_ui_and_core_ios.md).

    The following is an example of the `PaymentOptions` object that includes optional parameters \(description of the payment and the customer's country\)

    ```language-c
    PaymentOptions *paymentOptions = [[PaymentOptions alloc] initWithProjectID:10
                                paymentID:@"internal_payment_id_1"
                            paymentAmount:1999
                          paymentCurrency:@"USD"
                       paymentDescription:@"T-shirt with dog print"
                               customerID:@"10"
                               regionCode:@"US"];
    ```

4.  Pack all payment parameters into a string for signing:

    ```language-c
    paymentOptions.paramsForSignature();
    ```

5.  Send the string to the server side of your web service.
6.  Have your web service generate the signature on the basis of the string and your secret key.
7.  Add signature in your `PaymentOptions` object:

    ```language-c
    [paymentOptions setSignature:signature]
    ```

8.  Open the payment form by using the following code:

    ```language-c
    [self.EcommpaySDK presentPaymentAt:self paymentOptions:paymentOptions 
         completionHandler:^(PaymentResult *result) {
         NSLog(@"EcommpaySDK finished with status %ld", (long)result.status);
         ...
     }];
    ```

    Before opening the payment form, the library checks for any errors and opens the payment form only if no errors occur. Otherwise, the payment form is not opened and the `presentPayment` method returns the error code.


### Processing payments {#en_sdk_ui_and_core_ios_payments}

By default, SDK UI & Core for iOS allows processing one-step purchases \(action type `Sale`\). This type of checkout works right out-of-the-box and requires no additional setup.

In addition, SDK UI & Core for iOS supports processing two-step purchases \(which involves placing an authorisation hold via the SDK and subsequent debiting of the authorised amount\). To perform a two-step purchase:

1.  Open the payment form with `Auth` specified as a value for the action type parameter in the `paymentOptions` object:

    ```language-c
    paymentOptions.action = .Auth
    ```

    ```language-c
    [paymentOptions setAction: ActionTypeAuth];
    ```

2.  When needed, initiate debiting of the authorised amount via Dashboard \([details](en_dbl_payments.md)\) or Gate \(by sending the request to the [/v2/payment/card/capture](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-capture) endpoint\).

### Payment card verification {#en_sdk_ui_and_core_ios_verify}

Payment instrument verification can be used when you need to validate a card without withdrawing funds instantly \(for example, before performing a payout\) or when you need to save card details for subsequent use. It is essentially a payment that involves debiting a dummy \(zero\) amount from the customer's card.

To perform verification, open the payment form with `Verify` specified as a value for the action type parameter in the `paymentOptions` object:

```language-c
paymentOptions.action = .Verify
```

```language-c
[paymentOptions setAction: ActionTypeVerify];
```

### Payment status information {#en_sdk_ui_and_core_ios_status}

To receive payment result notifications, use requests with the following code included:

```language-c
ecommpaySDK.presentPayment(at: self, paymentOptions: paymentOptions) { result in
         print("ecommpaySDK finished with status \(result.status.rawValue)")
   if let error = result.error {      // if an error occurred
      print("ErrorCode: \(error.code) message: \(error.message)")
   }
 }
```

```language-c
[self.ecommpaySDK presentPaymentAt:self paymentOptions:paymentOptions 
     completionHandler:^(PaymentResult *result) {
     NSLog(@"EcommpaySDK finished with status %ld", (long)result.status);
        if(result.error != NULL) {    // if an error occurred
            NSLog(@"Error code: %@ with message: %@", error.codeString, error.message);
        }
 }];
```

Possible payment result codes passed in the `PaymentResult.status` parameter:

|Result code|Message|Description|
|-----------|-------|-----------|
|`0`|Success|Payment has been completed|
|`100`|Decline|Payment has been declined|
|`200`|Cancelled|Payment has been cancelled by the customer|
|`500`|Error|An error occurred when the payment was being processed|

### Processing payments made with Apple Pay {#en_sdk_ui_and_core_ios_applepay}

In order to implement payment processing which involves the Apple Pay payment method, it is necessary to do the following:

1.  Register the merchant's identifier \(Merchant ID\) with Apple. Merchant ID allows the merchant to accept payments made with the Apple Pay method. This identifier never expires and can be used in multiple websites and iOS applications. For more information see Apple documentation: [Create a merchant identifier](https://help.apple.com/developer-account/#/devb2e62b839?sub=dev103e030bb).
2.  Create Payment Processing Certificate. This certificate is associated with the Merchant ID and is used to secure transaction data when processing Apple Pay payments. For more information see Apple documentation: [Create a payment processing certificate](https://help.apple.com/developer-account/#/devb2e62b839?sub=devf31990e3f).
3.  Send Payment Processing Certificate to the Ecommpay technical support. Use the agreed upon security methods.
4.  Enable the Apple Pay capability for the mobile application in the programming environment. For information about enabling Apple Pay capability in Xcode environment, see Apple documentation: [Enable Apple Pay](https://help.apple.com/xcode/mac/9.3/#/deva43983eb7?sub=dev44ce8ef13)

Once these steps are completed, you can process Apple Pay payments. The main steps such as opening the payment form and processing the responses are performed according to the general procedure, which is the same for all payment methods. In addition, you need to pass the following data in the `applePayOptions` object

```language-c
setupApplePayparams(paymentOptions: PaymentOptions) {
        let applePayOptions = PaymentOptions.ApplePayOptions(applePayMerchantID: "merchant.example.com",
                                                             applePayDescription: "Shop",
                                                             countryCode: "US")
        paymentOptions.applePayOptions = applePayOptions
}
```

```language-c
setApplePaySettings:(PaymentOptions *)paymentOptions {
    PaymentOptionsForApplePay *applePayOptions = [[PaymentOptionsForApplePay alloc]
                                                  initWithApplePayMerchantID:@"merchant.example.com"
                                                  applePayDescription:@"Shop"
                                                  countryCode:@"US"];
}
```

All parameters passed in the `applePayOptions` object are mandatory and are necessary for the Apple Pay session to start correctly.

### Additional capabilities {#en_sdk_ui_and_core_ios_additional_capabilities}

#### Submitting additional payment information {#section_kq4_vcz_lvb .section}

Generally, for processing a payment, it is enough to send a set of parameters that are mandatory for its initiation. However, 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 following article](en_pp_clarification.md).

The final set of required parameters can vary depending on a specificprovider or a payment system. The list of parameters relevant for a particular payment is displayed to the customer on the payment form. The customer fills in the required data, confirms the payment, and receives the payment result information.

#### Cascade payment processing {#section_hrz_5cz_lvb .section}

In case of a payment attempt failure, the capability of cascade payment processing can be used \([details](en_pp_cascading.md)\). This capabilityimplies executing a sequence of payment attempts via alternative providers without the payment method change and can be set up upon coordination with the Ecommpay specialists.

If this capability is set up for the project in use, then after the first unsuccessful attempt, a notification is received from SDK UI & Core for iOS. This notification contains the `cascading_with_redirect = true` attribute-value pair. Along with that, the error page with the button to retry making the payment is shown to the customer. If the 3‑D Secure authentication is not required as part of the additional attempt, then the attempt is executed without any further interaction with the customer. Otherwise, a separate page opens for repeating the authentication process.

#### Collecting customer data {#section_pm5_vcz_lvb .section}

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 has to be mandatory to be specified by the customers and communicate data collection preferences to the technical support specialists. For more information about using the capability, see [the separate article](en_PP_Gathering_customer_data.md).

#### Payment interface language support {#section_uhh_k3t_xyb .section}

By default, during the work with SDK UI & Core, the payment interface is localised according either to the language of the customer's device—if this language is supported for the project in use—or to a language set as default for other cases \(generally, English\). Along with that, if relevant, you can localise the payment interface for particular sessions. For this, every request for opening the payment form must contain a corresponding language code in the `languageCode` \([details](en_sdk_ui_and_core_ios.md)\).

**Warning:** If the language is not supported for the project, the payment form is not opened and the error information is displayed to the customer.

The following languages are supported for the SDK interface and can be promptly set up in the projects of the payment platform.

|Language|Language code|
|--------|-------------|
|English|`en`|
|Estonian|`et`|
|French|`fr`|
|German|`de`|
|Italian|`it`|
|Latvian|`lv`|
|Lithuanian|`lt`|
|Portuguese|`pt`|
|Spanish|`es`|
|Ukrainian|`uk`|

#### Saving payment data {#section_ufq_5cz_lvb .section}

SDK UI & Core for iOS allows saving payment data of the customer for subsequent processing of payments without the need for the said customer to re-enter such data. This capability is set up individually for each project. The merchant has to let the technical support know which of the two options is preferable: *always save payment data* or *ask the customer to select the option*. For more information about this capability, refer to article [Saving customer payment data](en_PP_saved_data.md).

As a result of saving payment data, a separate identifier is generated for each payment instrument. This identifier is associated with the identifier of a certain customer \(`customerId`\). To display saved payment data to the customer, pass `false` in the `hideSavedWallets` parameter of the `PaymentOptions` object.

## Payment form opening parameters {#en_sdk_ui_and_core_ios_parameters}

When processing card payments, pass the `additionalFields` parameter in the `PaymentOptions` object with at least one of the following fields.

|Parameter|Description|
|:--------|:----------|
|`customer_email`  
 list

|Customer's email.

 Example: `AdditionalField(type: .customer_email, value: "Customer email")`

|
|`customer_phone`  
 list

|Customer's phone number.

 Example: `AdditionalField(type: .customer_phone, value: "Customer phone")`

|

In addition, when processing card payments, you are recommended to specify the customer's billing address information in the `additionalFields` parameter.

**Note:** [According to Visa](files_for_downloads/cc0a9603-8fcc-4ef3-9738-3ffa823d06bd.pdf), rigorous use of these parameters can significantly increase payment acceptance rates \(up to 6 %\) and drastically decrease the number of operations flagged as fraudulent after they have been processed \(up to 65 %\).

|Parameter|Description|
|:--------|:----------|
|`billing_country`  
 string

|Country of the customer's billing address in the ISO 3166-1 alpha-2 format \([learn more](en_country_codes.md)\).

 Example: `AdditionalField(type: .customer_billing_country, value: "SE")`

|
|`billing_city`  
 string

|City of the customer's billing address.

 Example: `AdditionalField(type: .customer_billing_city, value: "Stockholm")`

|
|`billing_postal`  
 string

|Postal code of the customer's billing address.

 Example: `AdditionalField(type: .customer_billing_postal, value: "10691")`

|
|`billing_address`  
 string

|Street of the customer's billing address.

 Example: `AdditionalField(type: .customer_billing_address, value: "Albanovaegen 28")`

|

When working with SDK UI & Core for iOS, you can pass the following optional parameters in the `PaymentOptions` object.

|Parameter|Description|
|:--------|:----------|
|`paymentDescription`  
 string

|Description of the payment. A string that contains between 1 and 255 characters.

 Example: `Cosmoshop purchase`

|
|`receiptData`  
 string

|Data to be included in the notification with the list of the purchased items, passed as a JSON object encoded using the Base64 scheme.

 Example: `eyAgCiAgICAgICJwb3NpdGlvbnMiOlsgIAogICAgICAgICB7ICAKICAgICAgI CAgICAgInF1YW50aXR5IjozLAogICAgICAgICAgICAiYW1vdW50IjoxMDAwMC wKICAgICAgICAgICAgInRheCI6MTgsCiAgICAg`

|
|`hideSavedWallets`  
 boolean

|Parameter to enable hiding or displaying saved payment instruments in the payment form.

 Possible values:

 -   `true`—saved payment data is hidden
-   `false`—saved payment data is displayed.

|
|`forcePaymentMethod`  
 string

|The identifier of the preselected payment method according to [the table](en_pm_codes.md).

 Example: `card`

|
|`threeDSecureInfo`  
 object

|Object that contains additional objects and parameters necessary for the 3‑D Secure 2 authentication.|
|`languageCode`  
 string

|Payment interface language code in the ISO 639-1 alpha-2 format. Must match one of the languages supported for the given project.

 Example: `IT`

|
|`regionCode  
`  
 string

|Code of the customer's country in the ISO 3166-1 alpha-2 format.

 Example: `GB`

|
|`applePayMerchantID`  
 string

|The Apple Pay identifier of the merchant.|
|`applePayDescription`  
 string

|The description of the merchant in the Apple Pay service.|
|`countryCode`  
 string

|Code of the customer's country in the ISO 3166-1 alpha-2 format. Passed when Apple Pay payments are processed.

 Example: `GB`

|
|`logoImage`  
 object

|A PNG or SVG file that contains the logo of the merchant.|
|`brandColor`  
 string

|Payment interface colour passed as a `UIColor` object.

 Example: `UIColor.green`

|
|`additionalFields`  
 list

|Additional fields that contain information about the customer. Includes a list of parameters with specified values.

 Example: `AdditionalField(type: .customer_first_name, value: "Arthur")`

|

To work with COF purchases, you should pass relevant parameters in the `recurrentInfo` object of the `PaymentOptions` object.

|Parameter|Description|
|:--------|:----------|
|`type`  
 string

|Type of the COF purchase to register.

 Possible values:

 -   `.OneClick`
-   `.Autopayment`
-   `.Regular`

|
|`period`  
 string

|Frequency of debits \(for a regular COF purchase\).

 Possible values:

 -   `.Day`— daily
-   `.Week`—weekly
-   `.Month`—monthly \(if the set day is not available in the next month, for example, 31, the payment is performed on the last day of the month\)
-   `.Quarter`— quarterly
-   `.Year`—yearly

|
|`expiryDay`  
 string

|Calendar day on which the specified duration period of the COF purchase will end \(the value should be provided as an integer from `1` to `31`, without a leading zero, in accordance with the Gregorian calendar\).|
|`expiryMonth`  
 string

|Month in which the specified duration period of the COF purchase will end \(the value should be provided as an integer from `1` to `12`, without a leading zero, in accordance with the Gregorian calendar\).|
|`expiryYear`  
 integer

|Year in which the specified duration period of the COF purchase will end \(in the `YYYY` format, in accordance with the Gregorian calendar\).|
|`scheduledPaymentID`  
 string

|Identifier assigned to the payment within which scheduled debits are performed \(for automatic debiting\). It must differ from the identifier of the payment made to register a COF purchase and must be unique within the project.

 Parameter must be passed together with the `startDate` parameter.

|
|`startDate`  
 string

|Date on which the first debit operation is performed \(for a COF regular purchase\). This parameter is used in conjunction with the `scheduled_payment_id` parameter and should be specified in the `DD-MM-YYYY` format.|
|`time`  
 string

|Time of performing subsequent debits \(for a regular purchase\) in `hh:mm:ss` format. The parameter is used if the `period` parameter is specified in the request.|
|`schedule`  
 object—schedule of debits performed as part of the COF purchase \(can be specified by the merchant\). Should contain parameters `amount` and `date`.

|
|`amount`  
 integer

|The amount to debit in the smallest currency unit.|
|`date`  
 string

|Date to perform the debit in the `DD-MM-YYYY` format.|

**Note:** If any of the parameters defining the expiry date of the COF purchase is not provided in the request, the following default values apply:

-   For standard card payments—the corresponding parameter value \(day, month, year\) is determined based on the expiry date of the specified payment card.
-   For other available methods—the corresponding parameter value is determined as follows:
    -   Calendar day—the last calendar day of the relevant month \(as specified in the `expiry_month` parameter or corresponding to the COF purchase registration date\).
    -   Month—the month in which the COF purchase was registered.
    -   Year—the year that is 10 years after the year in which the COF purchase was registered.

Accordingly, if only the year is specified, for standard card payments the day and month are taken from the expiry date of the relevant card and combined with the specified year. For an alternative payment method, the expiry date is set to the last calendar day of the month in which the COF purchase was registered and the specified year.

You can pass the following optional parameters in the `threeDSecureInfo` object. Including these parameters increases the possibility of frictionless flow selection.

|Parameter|Description|
|:--------|:----------|
|`threeDSecureInfo`—object of the `ThreeDSecureInfo` class containing additional objects and parameters used during the 3‑D Secure 2 authentication|
|`threeDSecurePaymentInfo`—object of the `ThreeDSecurePaymentInfo` class with information about the purchase details and indication of the preferable authentication flow|
|`challengeIndicator`  
 string

|This parameter indicates whether challenge flow is requested for this payment.

 Possible values:

-   `01`—no preferences
-   `02`—it is preferable not to use challenge flow
-   `03`—challenge flow preferred
-   `04`—always use challenge flow

|
|`challengeWindow`  
 string

|The dimensions of a window in which authentication page opens.

 Possible values:

-   `01`—250 x 400 px
-   `02`—390 x 400 px
-   `03`—500 x 600 px
-   `04`—600 x 400 px
-   `05`—full screen

|
|`preorderDate`  
 string

|The date the preordered merchandise will be available.

 Format: *dd-mm-yyyy*.

|
|`preorderPurchase`  
 string

|This parameter indicates whether cardholder is placing an order for merchandise with a future availability or release date.

 Possible values:

-   `01`—merchandise available in stock
-   `02`—future merchandise availability

|
|`reorder`  
 string

|This parameter indicates whether the cardholder is reordering previously purchased merchandise.

 Possible values:

-   `01`—first time order
-   `02`—reorder

|
|`threeDSecureGiftCardInfo`—object of the `ThreeDSecureGiftCardInfo` class with information about payment with prepaid card or gift card.|
|`amount`  
 integer

|Amount of payment with prepaid or gift card denominated in the smallest currency unit.|
|`currency`  
 string

|Currency of payment with prepaid or gift card in the ISO 4217 alpha-3 format, for example [GBP](references/en/currencies/GBP.md).|
|`count`  
 integer

|Total number of individual prepaid or gift cards/codes used in purchase.|
|`threeDSecureCustomerInfo`—object of the `ThreeDSecureCustomerInfo` class with information about the customer.|
|`addressMatch`  
 string

|The parameter indicates whether the customer billing address matches the address specified in the `threeDSecureShippingInfo` object.

 Possible values:

-   `Y`—Shipping Address matches Billing Address
-   `N`—Shipping Address does not match Billing Address

|
|`billingRegionCode`  
 string

|State, province, or region code in the ISO 3166-2 format. Example: `DOR` for Dorset.|
|`homePhone`  
 string

|Customer home phone number.

 Numeric, from 4 to 24 characters. Example: `44991234567`.

|
|`workPhone`  
 string

|Customer work phone number.

 Numeric, from 4 to 24 characters. Example `44997654321`.

|
|`threeDSecureAccountInfo`—object of the `ThreeDSecureAccountInfo` class with information about customer account details on record with the web service|
|`additional`  
 string

|Additional customer account information, for instance arbitrary customer ID.

 Maximum 64 characters.

|
|`activityDay`  
 integer

|Number of card payment attempts in the last 24 hours.Maximum 3 characters \(`999`\).

|
|`activityYear`  
 integer

|Number of card payment attempts in the last 365 days.Maximum 3 characters \(`999`\).

|
|`ageIndicator`  
 string

|Number of days since the customer account was created.

 Possible values:

-   `01`—guest check-out
-   `02`—customer account was created in this transaction
-   `03`—customer account was created less than 30 days ago
-   `04`—customer account was created 30 to 60 days ago
-   `05`—customer account was created over 60 days ago

|
|`authData`  
 string

|Any additional log in information in free text.

 Maximum 255 characters.

|
|`authMethod`  
 string

|Authentication type the customer used to log on to the account when placing the order.

 Possible values:

-   `01`—no authentication
-   `02`—log on by using authentication data on file with merchant
-   `03`—log on by using federated ID \(for example, Google Account or Facebook\)
-   `04`—log on by using a FIDO authenticator \(Fast IDentity Online\)

|
|`authTime`  
 string

|Account log on date and time.

 Format: *dd-mm-yyyyhh:mm*.

|
|`date`  
 string

|Account creation date.

 Format: *dd-mm-yyyy*.

|
|`changeDate`  
 string

|Last account change date except for password change or password reset.

 Format: *dd-mm-yyyy*.

|
|`changeIndicator`  
 string

|Number of days since last customer account update, not including password change or reset.

 Possible values:

-   `01`—updated in this transaction
-   `02`—updated less than 30 days ago
-   `03`—updated 30−60 days ago
-   `04`—updated over 60 days ago

|
|`passChangeDate`  
 string

|Last password change or password reset date.

 Format: *dd-mm-yyyy*.

|
|`passChangeIndicator`  
 string

|Number of days since the last password change or reset.

Possible values:-   `01`—password never changed
-   `02`—changed in this transaction
-   `03`—changed less than 30 days ago
-   `04`—changed 30−60 days ago
-   `05`—changed over 60 days ago

|
|`paymentAge`  
 string

|Card record creation date.

 Format: *dd-mm-yyyy*.

|
|`paymentAgeIndicator`  
 string

|Number of days since the payment card details were saved in a customer account.

 Possible values:

-   `01`—current payment uses no customer account \(guest checkout\)
-   `02`—card details were saved today
-   `03`—card details were saved less than 30 days ago
-   `04`—card details were saved 30 to 60 days ago
-   `05`—card details were saved more than 60 days ago

|
|`provisionAttempts`  
 integer

|Number of attempts to add card details in customer account in the last 24 hours.Maximum 3 characters \(`999`\).

|
|`purchaseNumber`  
 integer

|Number of purchases with this cardholder account in the previous six months.Maximum 4 characters \(`9999`\).

|
|`suspiciousActivity`  
 string

|Suspicious activity detection result.

 Possible values:

-   `01`—no suspicious activity detected
-   `02`—suspicious activity detected

|
|`threeDSecureShippingInfo`—object of the `ThreeDSecureShippingInfo` class with shipping details.|
|`address`  
 string

|Shipping address.

 Maximum 150 characters.

|
|`addressUsage`  
 string

|First shipping address usage date.Format: *dd-mm-yyyy*.

|
|`addressUsageIndicator`  
 string

|Number of days since the first time usage of the shipping address.

 Possible values:

-   `01`—this transaction
-   `02`—less than 30 days ago
-   `03`—30−60 days ago
-   `04`—more than 60 days ago

|
|`city`  
 string

|Shipping city.

 Maximum 50 characters.

|
|`country`  
 string

|Shipping country in the ISO 3166-1 alpha-2 format, for example [GB](references/en/countries/GB.md).|
|`deliveryEmail`  
 string

|The email for the digital content delivery.

 Maximum 255 characters.

|
|`deliveryTime`  
 string

|Shipment terms.

Possible values:-   `01`—digital delivery
-   `02`—same-day delivery
-   `03`—overnight delivery
-   `04`—longer than overnight delivery

|
|`nameIndicator`  
 string

|Shipment recipient flag.

 Possible values:

-   `01`—customer and shipment recipient are the same person
-   `02`—customer and shipment recipient are different persons

|
|`postal`  
 string

|Shipping postbox number.

 Maximum 16 characters.

|
|`regionCode`  
 string

|State, province, or region code in the ISO 3166-2 format. Example: `DOR` for Dorset.

 If you specify this parameter, you need also to specify and populate the `country` parameter in the `threeDSecureShippingInfo` object.

|
|`type`  
 string

|Shipment indicator.

 Possible values:

-   `01`—ship to cardholder billing address
-   `02`—ship to another verified address on file with merchant
-   `03`—ship to address that is different from the cardholder billing address or any verified address on file with merchant
-   `04`—ship to local store
-   `05`—digital goods shipment
-   `06`—no shipment, for instance for travel or event tickets
-   `07`—other, for example gaming or subscriptions

|
|`threeDSecureMpiResultInfo`—object of the `threeDSecureMpiResultInfo` class with information about previous customer authentication|
|`acsOperationId`  
 string

|The ID the issuer assigned to the previous customer operation. Maximum 36 characters.|
|`authenticationFlow`  
 string

|The flow the issuer used to authenticate the cardholder in the previous operation.

 Possible values:

-   `01`—frictionless flow
-   `02`—challenge flow

|
|`authenticationTimestamp`  
 string

|Date and time of the previous successful customer authentication|