iOS SDK and example app

Introduction

The native SDK for iOS helps you to communicate with the Client API. It offers

• convenient Objective-C wrappers for API responses,
• caching of payment product logos and caching of images used to offer additional information about payment products,
• localization of various labels and messages,
• user-friendly formatting of payment data such as card numbers and expiry dates,
• validation of input,
• a check to determine to which payment provider a card number is associated, and
• handling of all the details concerning the encryption of payment details.

Its use is demonstrated by an example app, which constructs the user interface elements used throughout the payment process from API responses on the fly. The source code of the SDK and the example app are available on GitHub . There you can find installation instructions.

The main payment steps

Setting up and completing a payment using the iOS SDK is done in a number of steps:

1. Initialize the iOS SDK for this payment. This is done using information such as session and customer identifiers, geographical information and payment information like currency and total amount.
2. Retrieve the payment items and accounts on file that can be used for this payment from the Client API. Your app uses this data to create the payment product selection screen.
3. Retrieve all the details about the payment product fields from the Client API that the customer needs to provide based on the selected payment product or account on file. Your app uses this information to create the payment product details screen.
4. Encrypt all the provided payment information using the Client API. Your app sends the encrypted result to your e-commerce server, which sends it to our Server API.
5. Use the response from the Server API call to guide the customer to the next step in the payment process. This can be a simple "payment successful" or "payment failed" screen or a redirect to a third party that completes the payment.

These steps are explained in more detail in the next couple of paragraphs.

Initialize the iOS SDK for this payment

By initializing the iOS SDK, you provide the SDK with all the information it needs to authenticate to the Client API and to make sure the Client API calls have all the context they need to return the correct data. It needs the following information:

• A client session identifier and a customer identifier, which the Client API needs for authentication purposes. These can be obtained by your e-commerce server using the Server SDKs or directly using the Server API.
• The client-api-url and asset-url that the SDK should connect to. The SDK communicates with two types of servers to perform its tasks. One type of server offers the Client API discussed above, and the other type of server stores the static resources used by the SDK, such as the logos of payment products. The urls of these servers can be obtained by your e-commerce server using the Server SDKs or directly using the Server API.
• The type of environment you want to connect to. This is either production, pre-production or our sandbox.
• Payment information. The payment products that the customer can choose from depends on payment information so the Client SDK needs this information to be able to do its job. What it needs is:
  • the total amount of the payment,
  • the country of the person that is performing the payment,
  • the currency that should be used, and
  • whether the payment is a single payment or a recurring payment.

Related SDK components are: ICSession and ICPaymentContext

Retrieve the payment items and accounts on file

After initialization, the iOS SDK offers easy access to all the payment items that can be used for this payment method. Payment items are either instances of ICBasicPaymentProduct or ICBasicPaymentProductGroup. Your app can use these items to create a screen that lists them all. For your convenience, the SDK comes with an example app that you can use as a basis for your own implementation. If you are fine with the look-and-feel of the example app, you do not need to make any changes at all. If you only have one payment item, you can of course skip this screen, but remember that you might also want to display the account(s) on file selection.

For some payment products, customers can indicate that they want the Worldline platform to store part of the data they enter while using such a payment product. For example, it is possible to store the card holder name and the card number for certain card-based payment products. The stored data is referred to as an account on file. When the customer wants to use the same payment product for another payment, it is possible to select one of the stored accounts on file for this payment. In such cases, the customer doesn't have to enter the information that is already stored in the account on file. The list of available payment items that the SDK receives from the Client API also contains the accounts on file for each payment product or payment product group. Your app can present this list of payment items and accounts on file to the customer.

Related SDK components are: ICPaymentItems, ICBasicPaymentProduct, ICBasicPaymentProductGroup, ICAccountsOnFile and ICAccountOnFile

Retrieve all the details about the payment product fields

Once the customer has selected a payment item or a stored account on file, the SDK can request which information needs to be provided by the customer to perform a payment. If a request for a single payment item (product or product group) is being done, the SDK provides a list of all the fields that should be rendered including display hints and validation rules. If the customer selected an account on file, information that is already in this account on file can be prefilled in the input fields, instead of requesting it from the customer. Again, the example app can be used as the starting point to create your screen. If there is no additional information that needs to be entered, this screen can of course be skipped.

Related SDK components are: ICPaymentProduct, ICPaymentProductGroup, ICPaymentProductField, ICValidationError and Issuer identification number check

Encrypt all the provided payment information

Finally, the SDK can encrypt the information provided by the customer in a format that can be processed by the Server API. In most cases, your app will send this encrypted information to your e-commerce server, which in turn sends it to our servers using the Server API. All the heavy lifting, such as requesting a public key from the Client API, performing the encryption and BASE-64 encoding the result into one string, is done for you by the SDK. You only need to provide the SDK with the values the customer provided in your screens. The encrypted package needs to be sent to your e-commerce server where it can be forwarded to the Server API. The iOS SDK does not do this for you as it does not know how your app communicates with your own server.>

Related SDK components are: ICPaymentRequest and ICPreparedPaymentRequest

Use the response from the Server API call

It's up to you and your app to show the customer the correct screens based on the response of the Server API call. In some cases, the payment hasn't finished just yet as the customer must be redirected to a third party (such as a bank or PayPal) to do the actual payment. See the Server API documentation on what kind of responses the Server API can provide. The Client API has no part in the remainder of the payment.

Components of the iOS SDK

ICSession

The class ICSession is the main component of the SDK. Once configured, instances of this class can communicate with the Client API and convert the responses of the API into plain Objective-C objects. Additionally, they can encrypt Objective-C objects describing payment requests to a form that can be processed by the Server API. The following code fragment shows how ICSession is initialized. As explained above, a client session identifier, customer identifier, client-api-url, asset-base-url and application identifier are required to communicate with the Client API. The documentation of the Server SDKs and the Server API describes how to obtain a client session identifier, customer identifier and the two api connectors.

NSString *clientSessionId = @"1234";
NSString *customerId = @"5678";
NSString *baseURL = @"https://clientapi.com";
NSString *assetBaseURL = @"https://asset.com";
NSString *appIdentifier = @"Example Application/v1";
ICSession *session =
    [ICSession sessionWithClientSessionId:clientSessionId 
                               customerId:customerId
                                  baseURL:baseURL
                             assetBaseURL:assetBaseURL
                            appIdentifier:appIdentifier];

ICPaymentContext

Instances of the class ICPaymentContext contain the information needed to request a list of available payment products: a total amount, a country code, a currency code, and an indication of whether the payment is a single payment or a recurring payment. The code fragment below shows how an instance of this class is initialized and used to retrieve such a list.

NSInteger amountValue = 100;
NSString *countryCode = @"NL";
NSString *currencyCode = @"EUR";
BOOL isRecurring = NO;

// Indicate whether we want an ICPaymentItems object that includes groups,
// or just contains basic payment products
BOOL groupPaymentProducts = YES;

ICPaymentAmountOfMoney *amountOfMoney = [[ICPaymentAmountOfMoney alloc] initWithTotalAmount:amountValue currencyCode:currencyCode];

ICPaymentContext *context = [[ICPaymentContext alloc] initWithAmountOfMoney:amountOfMoney isRecurring:isRecurring countryCode:countryCode];

[session paymentItemsForContext:context groupPaymentProducts:groupPaymentProducts success:^(ICPaymentItems *paymentItems) {
    // Allow the customer to select a payment item and an optional
    // account on file from the list of payment items
    // represented by paymentItems.
} failure:^(NSError *error) {
    // Indicate that an error has occurred.
}];

ICBasicPaymentItems

Instances of ICPaymentProducts contain a list of instances of ICAccountOnFile, and another list of instances of ICBasicPaymentItem. Currently a ICBasicPaymentItem can either be a ICBasicPaymentProduct or a ICBasicPaymentProductGroup. The list of basic payment items does not contain any payment products that have a payment product group associated with them. The following code fragment shows how instances of ICBasicPaymentItem, ICBasicPaymentProduct and ICBasicPaymentProductGroup can be retrieved from an instance of ICPaymentItems.

//Get an ICBasicPaymentItem
NSObject *basicPaymentItem = [paymentItems paymentItemWithIdentifier:@"1"];

//Get an ICBasicPaymentProduct
NSObject *basicPaymentItem = [paymentItems paymentItemWithIdentifier:@"1"];
if ([basicPaymentItem isKindOfClass:[ICBasicPaymentProduct class]]) {
    ICBasicPaymentProduct *basicPaymentProduct = (ICBasicPaymentProduct *)basicPaymentItem;
}

//Get an ICBasicPaymentProductGroup
NSString *basicPaymentProductGroupId = @"cards"; //Currently this is the only available group
NSObject *basicPaymentItem = [paymentItems paymentItemWithIdentifier:basicPaymentProductGroupId];
if ([basicPaymentItem isKindOfClass:[ICBasicPaymentProductGroup class]]) {
    ICBasicPaymentProductGroup *basicPaymentProduct = (ICBasicPaymentProductGroup *)basicPaymentItem;
}

ICBasicPaymentItem

Instances of the interface ICBasicPaymentItem expose three methods that can primarily be used for easily rendering a ICBasicPaymentProduct and ICBasicPaymentProductGroup on the same page.

ICBasicPaymentProduct & ICBasicPaymentProductGroup

The SDK offers four classes to represent information about payment products: ICBasicPaymentProduct, its subclass ICPaymentProduct, ICBasicPaymentProductGroup and its subclass ICPaymentProductGroup. Practically speaking, instances of ICBasicPaymentProduct and ICBasicPaymentProductGroup contain the information required by users to distinguish a payment product (group) from others in a list of available options. The classes ICPaymentProduct, and ICPaymentProductGroup are described below.

Based on the information contained by an instance of ICPaymentItems and the instances of ICBasicPaymentProduct and ICBasicPaymentProductGroup it contains, a graphical representation of a list of available payment items can be automatically generated, from which a customer can select one. Each instance of ICBasicPaymentProduct contains

• an identifier,
• a field indicating the payment method of this product,
• a field indicating the payment product group this product belongs to,
• a field indicating whether payment data can be stored as an account on file,
• a field indicating whether payment data can be stored automatically as an account on file,
• a field indicating whether or not a recurring payment can be processed with this payment product,
• a list of accounts on file for this payment product,
• display hints that can be used to render the ICBasicPaymentProduct, containing:
  • an index indicating at which position the payment product belongs in a list of payment products, and
  • a logo.

Instances of ICBasicPaymentProductGroup contain

• an identifier,
• a list of accounts on file for payment products in this group,
• display hints that can be used to render the BasicPaymentProductGroup, containing:
  • an index indicating at which position the payment product belongs in a list of payment products, and
  • a logo.

In the code fragment below, the label and logo for a payment product are retrieved. The iOS SDK offers internationalization and localization, which is illustrated in this example. The localized label for the payment product is retrieved using a key based on the identifier of the payment item. Its value depends on the locale of the customer's device.

NSString *key =
    [NSString stringWithFormat:@"gc.general.paymentProducts.%@.name",
    basicPaymentProduct.identifier];
NSString *label = NSLocalizedStringFromTable(key, kICSDKLocalizable, nil);
UIImage *logo = basicPaymentProduct.displayHints.logoImage;

ICAccountOnFile

Instances of the class ICBasicPaymentProduct and ICBasicPaymentProductGroup have a list of accounts on file which are an instance of ICAccountOnFile. This represents information about an account on file for a certain payment product. It contains

• an identifier for the account on file,
• an identifier for the corresponding payment product,
• a collection of values that have been stored as part of the account on file,
• display hints that contain information about how the account on file should be rendered
• a method that produces a label that describes the account on file.

The code fragment below shows how the label for an account on file can be retrieved. This label can be shown to the customer, along with the logo of the corresponding payment product, to enable the user to distinguish one account on file from another.

NSString *label = [accountOnFile label];

ICPaymentProduct & ICPaymentProductGroup

As explained above, ICBasicPaymentProduct and ICBasicPaymentProductGroup only contain the information required by a customer to distinguish one payment item from another. However, once a payment item or an account on file has been selected, the customer must provide additional information, such as an adress, a bank account number, a credit card number, or an expiry date, before a payment can be processed. Each payment item can have a number of fields that need to be completed to process a payment. Instances of ICBasicPaymentProduct and ICBasicPaymentProductGroup do not contain any information about these fields.

Information about the fields of payment items is represented by instances of ICPaymentProductField, which are contained in instances of ICPaymentProduct and ICPaymentProductGroup. The class ICPaymentProductField is described below. The session component can be used to retrieve instances of ICPaymentProduct, as shown in the following code fragment.

NSString *paymentProductId = @"xyz";
[session paymentProductWithId:paymentProductId context:context
    success:^(ICPaymentProduct *paymentProduct) {
        // Create a payment request using the payment product
        // represented by paymentProduct.
    } failure:^(NSError *error) {
        // Indicate that an error has occurred.
    }
];

Instances of PaymentProductGroup can be retrieved as shown in the fragment below.

NSString *paymentProductGroupId = @"cards";
[session paymentProductGroupWithId:paymentProductGroupId context:context
    success:^(ICPaymentProductGroup *paymentProductGroup) {
        // Create a payment request using the payment product group
        // represented by paymentProductGroup.
    } failure:^(NSError *error) {
        // Indicate that an error has occurred.
    }
];

ICPaymentProductField

The fields of payment items are represented by instances of ICPaymentProductField. Each field has an identifier, a type, a definition of restrictions that apply to the value of the field, and information about how the field should be presented graphically to the customer. Additionally, an instance of a field can be used to determine whether a given value is a valid value for the field.

In the code fragment below, the field with identifier “cvv” is retrieved from a payment product. The data restrictions of the field are inspected to see whether this field is a required field or an optional field. Additionally, the display hints of the field are inspected to see whether the values a customer provides should be obfuscated in a user interface. Finally, the value “123” is validated and the number of validation errors is inspected to see whether the provided value is valid.

ICPaymentProductField *field = [paymentProduct paymentProductFieldWithId:@"cvv"];
BOOL isRequired = field.dataRestrictions.isRequired;
BOOL obfuscate = field.displayHints.obfuscate;
[field validateValue:@"123"];
BOOL validValue = field.errors.count == 0;

ICValidationError and its subclasses

The class ICValidationError has a number of descendants, each representing a different type of validation error. These errors can be used to give customers feedback when there are issues with the information they provide.

• ICValidationErrorLength indicates that the supplied value has an invalid length. The minimal length is defined by the property minLength and the maximal length is defined by the property maxLength.
• ICValidationErrorRange indicates that the supplied value does not fall within the required range of values. The smallest value is defined by the property minValue and the largest value is defined by the property maxValue.
• ICValidationErrorExpirationDate indicates that the supplied value is not a valid expiration date.
• ICValidationErrorFixedList indicates that the supplied value is not one of the available options in a given fixed list of options.
• ICValidationErrorLuhn indicates that the supplied value does not pass the Luhn check for payment card numbers.
• ICValidationErrorRegularExpression indicates that the supplied value does not satisfy a given regular expression.
• ICValidationErrorIsRequired indicates that no value has been supplied for a required field.
• ICValidationErrorInteger indicates that the supplied value is not an integer.
• ICValidationErrorNumericString indicates that the supplied value is not a numeric string.
• ICValidationErrorEmailAddress indicates that the supplied value is not a valid e-mail address.
• ICValidationErrorAllowed indicates that the supplied value is not allowed in the current payment contect.

The code fragment below shows how a localized error message can be constructed for an instance of ICValidationErrorLength after casting an instance of ICValidationError.

ICValidationErrorLength *lengthError = (ICValidationErrorLength *)error;
NSString *format = @"gc.general.paymentProductFields.validationErrors.%@.label";
NSString *key = [NSString stringWithFormat:format, @"length"];
NSString *value = NSLocalizedStringFromTable(key, kICSDKLocalizable, nil);
NSString *errorMessage =
    [NSString stringWithFormat:value, lengthError.minLength, lengthError.maxLength];

ICPaymentRequest

Once a payment product has been selected and an instance of ICPaymentProduct has been retrieved, a payment request can be constructed. This class has a property tokenize, which is used to indicate whether a payment request should be stored as an account on file. The code fragment below shows how a payment request should be constructed when no account on file is selected and the request should not be stored as an account on file.

ICPaymentRequest *paymentRequest = [[ICPaymentRequest alloc] init];
paymentRequest.paymentProduct = paymentProduct;
paymentRequest.accountOnFile = nil;
paymentRequest.tokenize = NO;

If the customer selected an account on file, both the account on file and the corresponding payment product must be supplied while constructing the payment request, as shown below.

ICPaymentRequest *paymentRequest = [[ICPaymentRequest alloc] init];
paymentRequest.paymentProduct = paymentProduct;
paymentRequest.accountOnFile = accountOnFile;
paymentRequest.tokenize = NO;

Instances of ICAccountOnFile can be retrieved from instances of ICPaymentProduct or ICBasicPaymentProduct as follows.

NSString *paymentProductId = @"xyz";
NSString *accountOnFileId = @"abc";
ICBasicPaymentProduct *product = [paymentProducts paymentProductWithIdentifier:paymentProductId];
ICAccountOnFile *accountOnFile = [product accountOnFileWithIdentifier:accountOnFileId];

Once a payment request has been configured, the values for the payment product's fields can be supplied as follows. The identifiers of the fields, such as “cardNumber” and “cvv” in the example below, are used to set the values of the fields using the payment request.

[paymentRequest setValue:@"1234567890" forField:@"cardNumber"];
[paymentRequest setValue:@"123" forField:@"cvv"];

Some of the fields of the payment products are associated with a mask. These masks should be applied to the input provided by customers before the input is shown on the screen. In most apps, customers will be able to edit the values for payment product fields using a text field, which means that the cursor position should be updated while applying the mask. If a mask defines that characters should be inserted in a string and this insertion takes place at a position before the position of the cursor, the cursor position should be moved to the right. A payment request is able to compute the masked value and the new cursor position for each of the fields of the corresponding payment product, as shown in the following code fragment.

NSString *identifier = @"cardNumber";
NSInteger cursorPosition = 4;
NSString *formattedString =
    [paymentRequest maskedValueForField:identifier cursorPosition:&cursorPosition];

Once all values have been supplied, the payment request can be validated, as shown below. After validation, a list of errors is available, which indicates the problems that occurred during validation. If there are no errors, the payment request can be encrypted and sent to Worldline. If there are validation errors, the customer should be provided with feedback about these errors as explained above.

[self.paymentRequest validate];
if (self.paymentRequest.errors.count == 0) {
    // The payment request is valid, and can be encrypted and sent to
    // the Worldline platform via the merchant's server.
} else {
    // Notify the customer that some fields contain invalid data.
}

ICPreparedPaymentRequest

Once a payment request has been validated, it can be encrypted and sent to the Worldline platform. The code fragment below shows how an instance of ICSession can be used to encrypt a request. The result is an instance of the class ICPreparedPaymentRequest. It has two properties, encryptedFields and encodedClientMetaInfo, which are the strings that should be sent to the Worldline platform.

[session preparePaymentRequest:paymentRequest
    success:^(ICPreparedPaymentRequest *preparedPaymentRequest) {
        // Submit the information contained in the encrypted
        // payment request represented by preparedPaymentRequest
        // to the Worldline platform via your server.
    } failure:^(NSError *error) {
        // Indicate that an error has occurred.
    }
];

Issuer identification number check

The first six digits of a payment card number are known as the Issuer Identification Number (IIN). An instance of ICSession can be used to check which payment products are associated with an IIN. The check is performed asynchronously, which means that the result of the check is not available immediately. The result of this check is an instance of ICIINDetailsResponse. This class has a couple of properties, being:

• An ICIINStatus that indicates the result of the check. The different possible statusses are:
  • The value ICSupported indicates that the IIN is associated with a payment product that is supported by the Worldline platform.
  • The value ICUnknown indicates that the IIN is not recognized.
  • The value ICNotEnoughDigits indicates that fewer than six digits have been provided.
  • The value ICPending indicates that another request is already pending.
  • The value ICExistingButNotAllowed indicates that the IIN is recognised, but that it cannot be payed with in the current situation.
• A field that holds the identifier of the primary payment product that is associated with this IIN.
• A field that holds the country code of the primary payment product that is associated with this IIN.
• A field that indicates whether it is allowed to do a payment with the primary payment product based on the payment context.
• A list of instances of ICIINDetail, which depict co-brands for the current IIN.

It is possible that a single credit card has multiple brands associated to it. We call these co-brands. The details of the first payment product, that can be payed with in the current payment context, are always stored in the toplevel fields of the ICIINDetailsResponse. If a card is a multibranded card, the list of instances of ICIINDetail contains all brands associated with the card, including the payment product that is stored in the toplevel fields. This list can be used to show the customer he can chose what payment product he wants to be paying with. If there is only one payment product associated with the credit card the list of IIN Details is empty.

If the value of status is not ICSupported the other fields of ICIINDetailsResponse will all be nil (or false in case of the allowedInContext field).

The code fragment below shows how an instance of ICIINDetailsResponse can be obtained.

- (void)doIINLookup {
    NSString *unmasked = [paymentRequest unmaskedValueForField:@"cardNumber"];
    [session IINDetailsForPartialCreditCardNumber:unmasked context:context success:^(ICIINDetailsResponse *response) {
        if (response.status == ICSupported) {
            if (response.coBrands != nil) {
                if ([self isSelectedPaymentProductInCoBrands:response.coBrands] == NO) {
                    [self switchToPaymentProduct:response];
                }
                // EU legislation requires that, in the case of
                // a card with multiple brands, a customer can 
                // choose what brand he wants to do the payment
                // with.
                [self showCoBrandNotification];
            }
            else if ([response.paymentProductId isEqualToString:self.paymentProductIdentifier] == NO) {
                [self switchToPaymentProduct:response];
            }
        }
        else {
            //Handle other status codes
        }
    } failure:^(NSError *error) {
        // Indicate that an error has occurred.
    }];
}

-(BOOL)isSelectedPaymentProductInCoBrands:(NSArray *)cobrands {
    for (ICIINDetail *cobrand in cobrands) {
        if ([cobrand.paymentProductId isEqualToString:self.paymentItemIdentifier]) {
            return true;
        }
    }
    return false;
}

- (void)switchToPaymentProduct:(ICIINDetailsResponse *)response {
    if (response.isAllowedInContext) {
        // Switch to the payment product that actually is in the top level
        // Iin Details Response.
        self.paymentItemIdentifier = response.paymentProductId;
    }
    else {
        // Provide the customer with an error message that shows that the
        // credit card number he is entering can currently not be payed
        // with.
    }
}

- (void)showCoBrandNotification() {
    // Show the customer that he may choose
    // another brand to pay with.
}

Converting amounts

To help converting amounts from one currency to another, the SDK offers the convertAmount method of the ICSession class. This method takes an amount in cents, and a source and target currency, which are both three-letter ISO currency codes, and returns the converted amount in cents. The code fragment below shows how an amount can be converted.

NSInteger amountInCents = 10000;
NSString *source = @"EUR";
NSString *target = @"USD";

[session convertAmount:amountInCents withSource:source target:target
    success:^(NSInteger convertedAmountInCents) {
        // Use the converted amount.
    } failure:^(NSError *error) {
        // Indicate that an error has occurred.
    }
];

Retrieving a payment product directory

Certain payment products have directories that the consumer needs to pick from. An example is the list of banks for the Dutch iDeal payment product from which the consumer needs to select a bank. If you want to retrieve the directory information, you can use the directoryForPaymentProductId method of the ICSession class.

This method takes a payment product identifier, a three-letter ISO currency code, and an ISO 3166-1 alpha-2 country code and returns an instance of ICDirectoryEntries, as shown in the code fragment below.

NSString *paymentProductId = @"xyz";
NSString *countryCode = @"NL";
NSString *currencyCode = @"EUR";

[session directoryForPaymentProductId:paymentProductId countryCode:countryCode
    currencyCode:currencyCode
    success:^(ICDirectoryEntries *directoryEntries) {
        // Use the directory entries.
    } failure:^(NSError *error) {
        // Indicate that an error has occurred.
    }
];

Each instance of ICDirectoryEntries consists of a list of instances of ICDirectoryEntry, which contain the following information:

• the identifier of the issuing bank,
• the name of the issuing bank,
• the list of countries of the issuing bank, and
• a string that indicates how the issuers should be sorted.

Additional information

The classes ICPaymentProducts, ICBasicPaymentProduct, ICPaymentProduct, ICAccountsOnFile, ICAccountOnFile, ICPaymentProductField, and ICDirectoryEntries are wrappers for responses from the Client API. Additional information about the data represented by these classes is available in the documentation of the Client API.

Example app

The example app illustrates the possibilities of the iOS SDK and the services offered by the Worldline platform. Its source code is available on GitHub . The example app consists of four screens:

• The first screen asks for the information necessary to communicate with the Client API and retrieves a list of payment items. This screen should not be part of an actual app in the app store. It is provided to illustrate which information is needed to initialize an instance of ICSession.
• The second screen is a dynamically generated payment item selection screen. Based on the input provided in the first screen, a list of available payment items and previously stored accounts on file is shown. This screen or a similar screen would typically be part of an actual app. It is described in more detail below.
• After selecting a payment item, the third screen is shown. This screen requests the information needed to complete the payment for the selected payment product. The provided information can only be submitted by the customer if it has been validated by the SDK. Also this screen or a similar screen would be part of an actual app and is described in further detail below.
• The fourth screen indicates that the initiated payment has been successfully processed by the SDK. This screen should not be part of an actual app in the app store.

Logging

In some cases, you may want to turn on logging of the requests and responses that make up the communication with Worldline. You can enable logging in the example app by uncommenting the lines in the file IngenicoConnectExample\ICAppDelegate.m of the example app containing the following two statements:

[[AFNetworkActivityLogger sharedLogger] startLogging];
[[AFNetworkActivityLogger sharedLogger] setLevel:AFLoggerLevelDebug];

Payment product selection screen

The payment product selection screen provides an example for one of the two screens that will appear in most apps that use the iOS SDK. It shows a list of available payment items and accounts on file. For each payment item, a localized name is shown, and for each account on file, a short description of the stored information is shown. If a logo is available for a payment item, this logo is also shown. The screenshot to the left shows the payment product selection screen. It contains a part of a list of available payment items, generated from the information contained in an instance of ICPaymentItems.

Payment product input form screen

The screen that shows the input activity for a selected payment item or account on file is another example of a screen that will appear in most apps that use the iOS SDK. It is shown after selecting a payment item or an account on file. If the customer has selected an account on file, some of the required values will already be filled in and cannot be changed. The screenshot to the left shows the payment item input screen. The input form is generated from an instance of ICPaymentProduct or ICPaymentProductGroup.

Form validation

The example app uses the SDK to validate the input provided by the customer when the pay button is pressed. If the provided data is invalid, error messages are shown below the invalid values. The screenshot below shows the payment product input form screen after validation.

Additional information

Some payment product fields might require some additional explanation. The information button next to the text field for the CVC code shown below indicates that additional information is available. The image shown when the customer presses the button is part of the display hints of the payment product field. The textual explanation is a localized string that is part of the SDK. The screenshot below shows the payment product input form screen after pressing the information button.

IIN check

The example application also demonstrates the use of the IIN check described above. For each of the card-based payment products, an IIN check is performed once the customer has entered six or more digits in the text field for the card number. If the IIN is associated to the selected payment product, the logo of this payment product appears on the right-hand side of the text field. If the IIN is associated to another payment product, the input fields are replaced with the input fields for the new payment product automatically. The IIN check can also be used to switch from an ICPaymentProductGroup to a specific ICPaymentProduct.

The screenshot to the left also shows how the co-brands that may be associated to a certain card may be rendered. The payment product logo and name of the co-brands are retrieved by doing specific calls for them.