SDK for iOS (legacy)

Capabilities

SDK for iOS also supports payment processing by using methods listed in the Methods section. For information about setup and configuration, contact your ecommpayaccount manager.

Contents

SDK for iOS contains the library which is used for developing applications and running them on Apple devices, and code samples in Swift and Objective-C.

Payment workflow

Figure: Interaction diagram

Using SDK for iOS

With any questions regarding usage of SDK for iOS contact ecommpay technical support service.

Payment form interface

Figure: Payment form with all supported payment methods

Figure: Payment by using the DOKU payment method

Figure: Card verification

Figure: Selecting saved card

Figure: Token generation

Figure: Using preselected card

Figure: Clarification of additional parameters required for payment

Figure: Support for additional attempts to perform payments

Importing libraries in Swift

Importing libraries in Objective-C

Listed below are the instructions on how to import a ecommpay 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

Listed below are the instructions on how to import the libraries via CocoaPods.

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

   target 'App' do
     # Pods for App
     pod 'Paymentpage-sdk-ios', '1.10.0'
   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.

Opening payment form in Swift

To open payment form, do the following:

Opening payment form in Objective-C

To open payment form, do the following:

Overview

When using SDK for iOS, the merchant can receive callbacks that are sent by the payment platform directly to merchant web service and callbacks that are first sent by the payment platform to SDK for iOS and then by SDK for iOS to merchant mobile application. In the former case, the parameters sent in callbacks may vary depending on the configurations (more). In the latter case, specific set of parameters is provided—the data about status, type and ID of the payment, currency and amount of the payment as well as the payment method that was used:

{
    "payment": {
        "status": "success",
        "type": "purchase",
        "id": "12345",
        "date": "2020-09-11T14:49:18+0000",
        "method": "card",
        "sum": 1000,
        "currency": "USD"
         }
}

The following sections provide information about these callback messages.

Callbacks sent by the payment platform

The payment platform sends all the callback messages to the callback URL you specify. You need to contact the ecommpay technical support and provide the URL to send callbacks. For more information about callbacks, see Callbacks.

Callbacks sent by SDK for iOS

Merchant mobile application can receive callback messages with information about purchase processing result from SDK for iOS as information about payment processing result is sent to SDK for iOS by the payment platform. The callback message is sent to the merchant before the page with information about the result is displayed to the customer on the payment form.

To obtain information about payment result, you need to use the ECMPCallback public protocol. This protocol involves the use of the onPaymentResult method which comes into action automatically as the final payment status is received and, as a result, the merchant receives information about the payment result. To obtain information about the purchase processing result, you can use the following examples of the code with no additional setup; if needed, you can also change the code.

class YourClass: ECMPCallback {
    func presentPaymentPage() {
        ecommpaySDK = EcommpaySDK(callback: self)
        ...
    }
 
    func onPaymentResult(paymentData: ECMPPaymentData) {
        // callback
    }
}

@interface YourClass() <ECMPCallback> { EcommpaySDK *ecommpaySDK; }
 
@implementation YourClass
 
...
 
- (void)presentPaymentPage {
    self.ecommpaySDK = [[EcommpaySDK alloc] callback: self];
    ...
}
 
- (void)onPaymentResult:(ECMPPaymentData *)paymentData {
    // callback
}

Checkout by using stored checkout credentials

You can offer your customers an option to save credentials of cards used for checkout. Your customers will be able to save one or more cards and reuse them for any further purchases without specifying the card details—the customer will be only asked to enter CVV for the current card.

To allow customer to save card credentials and use them later for checkout, you need to set the customerID parameter with ID of the card owner. All the saved cards will be associated with this customer ID and the list of all the saved cards will be shown to your customer during checkout procedure. If the customer decides to delete a saved card, the SDK for iOS library will send the corresponding request to the payment platform to remove the card from the list of saved cards.

Checkout by using tokens

By using the SDK for iOS library, you can implement token-based checkout. Before using the token-based checkout functionality, you need to implement storing payment card credentials and its token on your back end. Each time you initiate a token-based checkout, you need to set the token parameter of your payment object:

paymentInfo.setToken(token);

[paymentInfo setToken:token];

Do not forget to include the parameter in your signature generation procedure. You customer will see the payment form with the preselected card with all its credentials, except for CVV, entered in the corresponding fields.

Automatic token generation

"account": {
            "number": "541333******0019",
            "token": "7e12077a71faf915bc4bda60f059854c7df4a46e7573057e52ece0801245666b",
            "type": "mastercard",
            "card_holder": "JOHN SMITH",
            "id": 7279487,
            "expiry_month": "11",
            "expiry_year": "2021"
        },

Token generation by request

paymentInfo.setAction(action: .Tokenize)

[paymentInfo setAction:ActionTypeTokenize];

The generated token and the time it was created at are returned in the token generation response.

One-step purchase

By default, SDK for iOS uses one-step purchases (action type Sale). This type of checkout works right out-of-the-box and requires no additional setup.

Two-step purchase

SDK for iOS supports two-step purchases in which payment is performed in two steps.

For more information about two-step purchases, see Authorisation hold.

COF purchases

ecommpay allows you to perform COF purchases. There are three types of COF purchases: OneClick, auto payments and regular payments. For more information about COF purchases, see Overview.

let recurrentInfo = RecurrentInfo(type: .Regular,
                    expiryDay: "20",
                    expiryMonth: "11",
                    expiryYear: "2030",
                    period: .Month,
                    time: "12:00:00",
                    startDate: "12-08-2021",
                    scheduledPaymentID: "your_recurrent_id")

RecurrentInfo *recurrentInfo = [[RecurrentInfo alloc]
                        initWithRecurrentType:RecurrentTypeRegular
                                          expiryDay:@"20"
                                        expiryMonth:@"11"
                                         expiryYear:@"2030"
                                             period:RecurrentPeriodMonth
                                              time:@"12:00:00"
                                          startDate:@"12-02-2021"
                                     scheduledPaymentID:@"pid624455712795"];

paymentInfo.setRecurrent(recurrent: recurrentInfo)

[paymentInfo setRecurret:recurrentInfo];

Card verification

The card verification is used when it is necessary to check the customer's card without debiting the funds, as well as to save the card data for future use. With card verification, a zero amount is debited from the card.

paymentInfo.setAction(action: .Verify)

[paymentInfo setAction:ActionTypeVerify];

Purchases by using alternative payment methods

General information

SDK for iOS supports the following alternative payment methods: Apple Pay, Skrill Wallet, DOKU Wallet, Malaysian Online Banking, Thai Online Banking, Alipay, Neteller and purchases by using online banking in European countries. Each of these payment methods is described in a separate topic. Payment processing flow through SDK for iOS using these payment methods can be divided into two types: the first type involves confirmation of payment processing by the alternative payment method service without redirecting the customer to this service (this is relevant only for Apple Pay), and the second type involves redirecting the customer to the alternative payment method service for payment confirmation and processing (this is relevant for other alternative payment methods). Diagrams showing both of these types are provided below along with the description of special features of using the Apple Pay.

To enable support for purchases by using alternative payment methods, contact the ecommpay technical support.

Apple Pay

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

1. Register merchant's identifier (Merchant ID) with Apple. Merchant ID allows the merchant to accept payments involving the Apple Pay method. This ID never expires, and can be used in multiple websites and iOS applications. For more information see Apple documentation: Create a merchant identifier.
2. Create Payment Processing Certificate. This certificate is associated with Merchant ID and is used to secure transaction data when processing payments that involve the Apple Pay method. For more information see Apple documentation: Create a payment processing certificate.
3. Send Payment Processing Certificate to the ecommpay technical support using the agreed 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

Once these steps are completed, it is possible to process payments involving the Apple Pay payment method. The main procedures, such as opening the payment form, processing response and callbacks, are performed the same way as when other alternative payment methods are used, but you also need to consider the following:

• Merchant's identifier (Merchant ID) must be specified. This can be done as follows:

  Swift

  paymentInfo.setApplePayMerchantID(merchantID: "merchant.example.com")

  Objective-C

  [paymentInfo setApplePayMerchantID:@"merchant.example.com"];

• The currency of purchase can be EUR, GBP, USD.
• For the Apple Pay payment session to start correctly, it is strongly recommended to set the country code for regionCode parameter (according to ISO 3166 alpha‑2). The specified country code must correspond to the customer's location.
• If needed, additional information about payment can be added to the authorization page of the Apple Pay payment sheet by using the applePayDescription parameter. The information to be added must be specified as the value of this parameter and will be displayed in the Pay field on the Apple Pay payment sheet (this is applicable to the sale, auth and verify operation modes of the payment form). For the correct display of information, it is recommended to specify the value of the applePayDescription parameter briefly. The usage of the applePayDescription parameter is optional, and if it is not specified in the request, in the Pay field the value of the paymentID parameter is displayed.

Payment involving the Apple Pay payment method is processed as follows.

Registration of COF purchases involving the Apple Pay method is also supported. For more information about the required parameters as well as Swift and Objective-C code samples see the COF purchases section.

Other alternative payment methods

The full sequence of the purchase process involving redirection to the alternative payment method service is provided below.

Figure: Purchase sequence by using the alternative payment methods