SDK for iOS

SDK for iOS is a software development kit for fast integration of the PSPHost payment solutions right in your mobile app for iOS. With SDK for iOS, you can quickly build and offer you customers a fast checkout experience from inside of your iOS app. In this section you will find information about using SDK for iOS as well as Swift and Objective-C code samples.

Within SDK for iOS 1.9 two versions are available: SDK for iOS 1.9.1 can be embedded in mobile applications running on iOS 11 or above and compatible with XCode 11 or above, while for mobile applications running on iOS 10 and compatible with Xcode 10 SDK for iOS 1.9.0 should be used.

You can also download SDK for iOS from GitHub. Use the following links to download SDK for iOS:

General information about SDK for iOS

What can I do with SDK for iOS?

SDK for iOS allows you to perform purchases by using payment cards and alternative payment methods. You may perform one-step and two-step purchases and COF purchases using payment cards, as well as card verification (more).

SDK for iOS also supports payment processing by using methods listed in the Payment methods section. For information about setup and configuration, contact your PSPHost Key Account Manager.

In terms of SDK for iOS, the PSPHost payment form is used and the following features are available:
  • Support for English and Russian. Default language is English; the payment form uses Russian only when Russian is selected as the user interface language in the mobile device settings. For the merchant it is also possible to select the language of the payment form.
  • Customization of payment form (more).
  • Support for different ways to enter card data (more):
    • manual input
    • card scan
    • saved card selection
    • preselected card usage
  • Gathering or passing additional customer data for further analysis (more).
  • Clarification of additional parameters required for payment (more).
  • Support for 3‑D Secure 2 authentication. 3‑D Secure 2 is a new version of 3‑D Secure (Three-Domain Secure) protocol, which is intended to secure e-commerce card payments. (For more information about 3‑D Secure, see Authentication by using 3‑D Secure 2.)
  • Support for additional attempts to perform payments (more).
  • Getting information about the payment. On all pages of the payment form there is an information button; when tapped, this button shows information about the ID, the amount, the date of the payment and payment description.
  • Sending receipts to the customer (more).

What's inside?

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

After you integrate an SDK for iOS library into your iOS app, checkout payment is processed as follows:
  1. Your client app creates an instance of payment object with all the necessary checkout details.
  2. On the basis of the payment object parameters, the back end part of you app generates the signature for checkout request.
  3. You call a special method of the payment object to have the client app initiate a checkout request and send it to the PSPHost payment platform.
  4. The PSPHost payment platform processes the checkout request and performs the payment.
  5. The payment platform sends the payment processing results to the client app.
  6. The payment platform sends a callback with the payment processing results to the callback URL you specified.
Figure 1. Interaction diagram

Using SDK for iOS

To start using SDK for iOS you need to complete the following tasks:
  1. Make sure you have you have ready your merchant ID and secret key obtained from PSPHost.
    1. If your company has never obtained any ID or secret key from PSPHost, you need to submit an application for connecting to the PSPHost payment platform.
    2. If your company already has an ID and a secret key to sign messages obtained from PSPHost, you need to notify PSPHost customer support that you want to use SDK for iOS and consult with the customer support on how to arrange a test run.
  2. Integrate the PSPHost payment solution in your app:
    1. Implement the checkout request signing functionality on the back end side of your mobile app.
    2. Download the SDK for iOS library.
    3. Import the SDK for iOS library into your client app and implement the following functionality: collection of payment details, preparation of data for signing checkout request, opening payment form, and submitting request to the payment platform for payment results.
  3. Test and put in production mode.
    1. Request test card numbers and test merchant ID from PSPHost and debug and test your app.
    2. Once testing is complete, request your production merchant ID from PSPHost and put your app in production mode.

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

Payment form interface

Figure 2. Payment form with all supported payment methods
Figure 3. Card verification
Figure 4. Selecting saved card
Figure 5. Token generation
Figure 6. Using preselected card
Figure 7. Clarification of additional parameters required for payment
Figure 8. Support for additional attempts to perform payments

Signature generation

To verify data integrity and authenticate the messages your application exchange with the PSPHost payment platform, all the messages need to be signed. You must sign all your outgoing messages (for example, checkout request) and check signatures of all the incoming messages (for example, callbacks). Before generating signature, you need to prepare the payment data by packing all the payment parameters into a single string. The string is generated on the client side where you can use SDK for iOS for this purpose. The signing process requires the secret key provided by PSPHost therefore the signing procedure must be performed on the back end side of your app.

Figure 9. Data signing procedure
Once you generate the string to sign on the basis of all the payment parameters, do the following:
  1. Generate the HMAC value based on the SHA-512 hashing algorithm and your secret key.
  2. Encode the result of step1 using Base64.
Use the following example to test whether your code correctly generates signatures:
  • Input data
    • Sample string to sign:
      customer_id:5;payment_amount:30;payment_currency:RUB;payment_id:payment1;project_id:115
    • Sample secret key: 12345
  • Result: generated signature:
    pVmAtGFBQJD2NgLToP1B2elR4QROiYGi3IobPD9PFDfrkjBqdSCFgrVSEtebVJUzOUUHX5tPnHQq9RMn61679A==

The signature your back end generates based on the sample string and the secret key must be exactly the same as of the sample generated signature.

We recommend choose specific implementation of the signing algorithm based on the programming environment you use. For the detailed information about signature generation, see Signature generation and verification.

Adding library in your project

Importing libraries in Swift

Listed below are the instructions on how to import a PSPHost library into your iOS app.
  1. Copy the psphostSDK.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 psphostSDK.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 PSPHost libraries code does not request user location, if the request is not initiated by the host app, but 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

Listed below are the instructions on how to import a PSPHost library into your iOS app.

  1. Copy the psphostSDK.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 psphostSDK.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 PSPHost libraries code does not request user location, if the request is not initiated by the host app, but 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.

Opening payment form

This section contains samples of payment form invocation code in Swift and Objective-C.

Opening payment form in Swift

To open payment form, do the following:

  1. Import the library:
    import psphostSDK
  2. Declare the psphostSDK library in you app (for example, inside the viewDidLoad method):
    let psphostSDK = PsphostSDK()
  3. Create an object named PaymentInfo with all the required parameters and any number of optional parameters, for example (required parameters are highlighted with bold optional parameters highlighted with italic):
    let paymentInfo = PaymentInfo(projectID: 10,
                            paymentID: "internal_payment_id_1",
                            paymentAmount: 1999,
                            paymentCurrency: "USD",
                           paymentDescription: "T-shirt with dog print",
                            customerID: "10",
                            regionCode: "US")

    Here are the required parameters:

    • projectID—project (merchant) ID PSPHost assigned you
    • paymentID—payment ID, must be unique within the project
    • paymentAmount—payment amount in minor currency units
    • paymentCurrency—payment currency code according to ISO-4217 alpha-3

    Here are the optional parameters:

    • recurrentInfo—object with the details of COF purchase (more)
    • paymentDescription—payment description (this parameter is available not only to the merchant, but also to the customer; if paymentDescription is specified in the request, it is visible to the customer in the payment form (in the dialog box containing information about the payment); if this parameter is not specified in the request, it is not visible to the customer)
    • customerID—customer ID
    • regionCode—customer country
    • token—card token
    • action—action type (Sale (by default), Auth, Tokenize, or Verify)
    • forcePaymentMethod—the identifier of the payment method to opened on the payment form. If this parameter is specified, the payment method selection page is skipped. For the list of the payment method codes, see IDs of payment methods supported by Payment Page.
    • hideSavedWallets—hiding or displaying saved payment instruments in the payment form. Possible values:
      • true—saved payment instruments are hidden, they are not displayed in the payment form
      • false—saved payment instruments are displayed in the payment form
    • PsphostScreenDisplayMode—object to manage display of the final page of the payment form and hide the final page if necessary. The following parameters can be passed in the object:
      • hide_success_final_page—the final page with the message about the performed payment is not displayed in the payment form.
      • hide_decline_final_page—the final page with the message about the declined payment is not displayed in the payment form.

      The following is an example of specifying the hide_success_final_page and hide_decline_final_page parameters in the request:

      // Init PaymentInfo
 
paymentInfo.addScreenDisplayMode(value: "hide_success_final_page")
           .addScreenDisplayMode(value: "hide_decline_final_page")
  4. Pack all the payment parameters into a string for signing:
    paymentInfo.getParamsForSignature();
  5. Send the string to your back end.
  6. Have your back end generate the signature on the basis of the string and your secret key.
  7. Add signature in your PaymentInfo object:
    paymentInfo.setSignature(value: signature)
  8. Open the payment form by using the following code:
    psphostSDK.presentPayment(at: self, paymentInfo: paymentInfo) { (result) in
   print("psphostSDK finished with status \(result.status.rawValue)")
   if let error = result.error {                     // if error occurred
      print("Error: \(error.localizedDescription)")
   }
   if let token = result.token {                    // if tokenize action
      print("Token: \(token)")
   }
 }

    Before opening the payment form, the library check 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 payment form in Objective-C

To open payment form, do the following:

  1. Import the library:
    #import <psphostSDK/PsphostSDK.h>
  2. Declare the psphostSDK library in you app (for example, inside the viewDidLoad method).
    psphostSDK *psphostSDK = [[psphostSDK.h alloc] init];
  3. Create an object named PaymentInfo with all the required parameters and any number of optional parameters, for example (required parameters are highlighted with bold optional parameters highlighted with italic):
    PaymentInfo *paymentInfo = [[PaymentInfo alloc] initWithProjectID:10
                            paymentID:@"internal_payment_id_1"
                        paymentAmount:1999
                      paymentCurrency:@"USD"
                   paymentDescription:@"T-shirt with dog print"
                           customerID:@"10"
                           regionCode:@"US"];

    Here are the required parameters:

    • projectID—project (merchant) ID PSPHost assigned you
    • paymentID—payment ID, must be unique within the project
    • paymentAmount—payment amount in minor currency units
    • paymentCurrency—payment currency code according to ISO-4217 alpha-3

    Here are the optional parameters:

    • recurrentInfo—object with the details of COF purchase (more)
    • paymentDescription—payment description (this parameter is available not only to the merchant, but also to the customer; if paymentDescription is specified in the request, it is visible to the customer in the payment form (in the dialog box containing information about the payment); if this parameter is not specified in the request, it is not visible to the customer)
    • customerID—customer ID
    • regionCode—customer country
    • ActionType—action type (Sale (by default), Auth, Tokenize, or Verify)
    • token—card token
    • forcePaymentMethod—the identifier of the payment method to opened on the payment form. If this parameter is specified, the payment method selection page is skipped. For the list of the payment method codes, see IDs of payment methods supported by Payment Page.
    • hideSavedWallets—hiding or displaying saved payment instruments in the payment form. Possible values:
      • true—saved payment instruments are hidden, they are not displayed in the payment form.
      • false—saved payment instruments are displayed in the payment form.
    • PsphostScreenDisplayMode—object to manage display of the final page of the payment form and hide the final page if necessary. The following parameters can be passed in the object:
      • hide_success_final_page—the final page with the message about the performed payment is not displayed in the payment form.
      • hide_decline_final_page—the final page with the message about the declined payment is not displayed in the payment form.

      The following is an example of specifying the hide_success_final_page and hide_decline_final_page parameters in the request:

      // Init PaymentInfo
 
[paymentInfo addScreenDisplayMode: hide_success_final_page];
[paymentInfo addScreenDisplayMode: hide_decline_final_page];
  4. Pack all the payment parameters into a string for signing:
    paymentInfo.getParamsForSignature();
  5. Send the string to your back end.
  6. Have your back end generate the signature on the basis of the string and your secret key.
  7. Add signature in your PaymentInfo object:
    [paymentInfo setSignature:signature];
  8. Open the payment form by using the following code:
    [self.psphostSDK presentPaymentAt:self paymentInfo:paymentInfo 
     completionHandler:^(psphostPaymentResult *result) {
     NSLog(@"psphostSDK finished with status %ld", (long)result.status);
     if(result.error != NULL) {                                  // if error occurred
         NSLog(@"Error: %@", result.error.localizedDescription);
     }
     if(result.token != NULL) {                               // if tokenize action
         NSLog(@"Token: %@", result.token);
     }
 }];

    Before opening the payment form, the library check 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.

Response processing

To receive and process response with the payment processing results you need to add the following code:

Figure 10. Receiving response in Swift
psphostSDK.presentPayment(at: self, paymentInfo: paymentInfo) { (result) in
   print("psphostSDK finished with status \(result.status.rawValue)")
   if let error = result.error {               // if error encountered
      print("Error: \(error.localizedDescription)")
   }
   if let token = result.token {               // if tokenize action performed
      print("Token: \(token)")
   }
 }
Figure 11. Receiving response in Objective-C
[self.psphostSDK presentPaymentAt:self paymentInfo:paymentInfo 
     completionHandler:^(psphostPaymentResult *result) {
     NSLog(@"psphostSDK finished with status %ld", (long)result.status);
                if(result.error != NULL) {         // if error encountered
         NSLog(@"Error: %@", result.error.localizedDescription);
     }
     if(result.token != NULL) {                    // if tokenize action performed
         NSLog(@"Token: %@", result.token);
     }
 }];

The result code is returned in the paymentStatus parameter.

The following table lists possible response codes returned in the paymentStatus parameter.

Value in paymentStatus Description
0 Checkout successfully completed.
100 Operation was declined, for example because of insufficient funds.
301 Operation was cancelled by the customer.
501 An internal error occurred. You may need to contact technical support.

Callbacks

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 PSPHost technical support and provide the URL to send callbacks. For more information about callbacks, see Callbacks in Payment Page.

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 PsphostCallback 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.

Figure 12. Swift
class YourClass: PsphostCallback {
    func presentPaymentPage() {
        psphostSDK = PsphostSDK(callback: self)
        ...
    }
 
    func onPaymentResult(paymentData: PsphostPaymentData) {
        // callback
    }
}
Figure 13. Objective-C
@interface YourClass() <PsphostCallback> { PsphostSDK *psphostSDK; }
 
@implementation YourClass
 
...
 
- (void)presentPaymentPage {
    self.psphostSDK = [[PsphostSDK alloc] callback: self];
    ...
}
 
- (void)onPaymentResult:(PsphostPaymentData *)paymentData {
    // callback
}

Managing card data

When paying with a payment card, the customer needs to enter the card data on the payment form. In addition to the traditional data entry method (manually), SDK for iOS allows you to scan a card, use a saved card or a card token for payment.

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:

Figure 14. Swift
paymentInfo.setToken(token);
Figure 15. Objective-C
[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

Automatic generation procedure creates a token when the first successful purchase or payout is performed by using a card, as well as after holding the funds on a card. The generated token and the date when it was created are returned in the payment callback.
Figure 16. Callback part with token information
"account": {
            "number": "546942******3838",
            "token": "7e12077a71faf915bc4bda60f059854c7df4a46e7573057e52ece0801245666b",
            "type": "mastercard",
            "card_holder": "JOHN SMITH",
            "id": 7279487,
            "expiry_month": "11",
            "expiry_year": "2021"
        },

Token generation by request

Another way to generate a token is to send a request to generate a token. To generate a token set Tokenize as action type:
Figure 17. Swift
paymentInfo.setAction(action: .Tokenize)
Figure 18. Objective-C
[paymentInfo setAction:ActionTypeTokenize];

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

Checkout

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.

  1. Before opening the payment form, set the action type parameter in the payment object to Auth:
    Figure 19. Swift
    paymentInfo.setAction(action: .Auth)
    Figure 20. Objective-C
    [paymentInfo setAction:ActionTypeAuth];
  2. Capture payment by using Dashboard or sending payment capture request to the /v2/payment/card/capture endpoint.

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

COF purchases

PSPHost 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.

Note: COF purchase registration through SDK for iOS is performed in terms of the sale, auth and verify operations and is supported only for purchases by using payment cards.
To implement COF purchases, you need to create a RecurrentInfo object with the following parameters:
  • type—type of COF purchase (.OneClick, .Regular, or .Autopayment)
  • cardOperationType—type of operation in terms of which COF purchase is registered. Possible values:
    • sale—purchase with direct withdrawal of funds
    • auth—authorization hold which is a part of two-step purchase
    • verify—payment instrument verification
  • expiryDay—last day of the payment period
  • expiryMonth—last month of the payment period
  • expiryYear—last year of the payment period
  • period—payment period
  • time—time or COF purchases
  • startDate—date to initiate the first payment
  • scheduledPaymentID—payment ID, must be unique within your project
Figure 21. Swift
let recurrentInfo = RecurrentInfo(type: .Regular,
                    cardOperationType: "sale",
                    expiryDay: "20",
                    expiryMonth: "11",
                    expiryYear: "2020",
                    period: .Month,
                    time: "12:00:00",
                    startDate: "12-08-2019",
                    scheduledPaymentID: "your_recurrent_id")
Figure 22. Objective-C
RecurrentInfo *recurrentInfo = [[RecurrentInfo alloc] initWithRecurrentType:RecurrentTypeRegular
                    cardOperationType:@"sale"
                      expiryDay:@"20"
                    expiryMonth:@"11"
                     expiryYear:@"2020"
                         period:RecurrentPeriodMonth
                           time:@"12:00:00"
                      startDate:@"12-02-2019"
             scheduledPaymentID:@"pid624455712795"];
Additionally you may set:
  • Amount of COF purchase. By default the amount of COF purchase is equal to payment amount. To change it, set:
    Figure 23. Swift
    recurrentInfo.setAmount(amount: 1000)
    Figure 24. Objective-C
    [recurrentInfo setAmount:1000];
  • Data and amount of COF purchase. By default the debit of funds is strictly fixed in time and amount. To customize schedule for COF purchases, set:
    Figure 25. Swift
    recurrentInfo.setSchedule(schedule: [
           RecurrentInfoSchedule(date: "10-10-2020", amount: 1200),
           RecurrentInfoSchedule(date: "10-11-2020", amount: 1000),
           ...
])
    Figure 26. Objective-C
    [recurrentInfo setSchedule:@[
              [[RecurrentInfoSchedule alloc] initWithDate:@"10-10-2020" amount:1200],
              [[RecurrentInfoSchedule alloc] initWithDate:@"10-11-2020" amount:1000],
              ...
]];
And then, add your RecurrentInfo object into the PaymentInfo object.
Figure 27. Swift
paymentInfo.setRecurrent(recurrent: recurrentInfo)
Figure 28. Objective-C
[paymentInfo setRecurret:recurrentInfo];

Card verification

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

To perform card verification, set Verify as action type:
Figure 29. Swift
paymentInfo.setAction(action: .Verify)
Figure 30. Objective-C
[paymentInfo setAction:ActionTypeVerify];

Purchase by using alternative payment methods

General information

Payment processing flow through SDK for iOS using alternative 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 and the WebMoney payment methods.

To enable support for purchases by using alternative payment methods, contact the PSPHost 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 PSPHost 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, RUB, 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.

Figure 31. Purchase sequence by using the Apple Pay payment method
  1. The customer initiates a purchase.
  2. The mobile application sends request to SDK for iOS to open the payment form.
  3. The request to open the payment form is sent to the payment platform.
  4. The payment platform performs request processing that involves validation of the required parameters and signature.
  5. Response to the request is sent from the payment platform to SDK for iOS.
  6. The payment form, configured with account taken of invocation parameters and special features of the project, is displayed to the customer.
  7. The customer selects the Apple Pay method.
  8. The request for starting payment session is sent from SDK for iOS to the Apple Pay service.
  9. The request for starting payment session is processed and the session data is generated on the Apple Pay side.
  10. Payment session data is sent from the Apple Pay service to SDK for iOS.
  11. Apple Pay authentication form is displayed to the customer.
  12. The customer completes all required steps.
  13. On request of SDK for iOS, authentication is performed on the customer's device.
  14. Request for purchase processing is sent from SDK for iOS to the payment platform.
  15. The request is processed on the side of the payment platform.
  16. The request for purchase processing is sent to the card organisation service.
  17. The purchase request is processed on the card organisation side.
  18. The payment result notification is sent from the card organisation to the payment platform.
  19. The callback with the payment result information is sent from the payment platform to the back end side of the mobile application.
  20. The payment platform sends the payment result notification to SDK for iOS.
  21. Information about the payment result is displayed to the customer on the payment form.

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 32. Purchase sequence by using the alternative payment methods

Gathering customer data

Usually payment form requires a minimum of data to complete a request for payment. However, in order to gather more extensive data and statistics about customers you can send and/or request additional data about your customers, such as customer phone number or email. For more information, see Collecting customer data.

To pass additional information, set them in the paymentInfo object:
Figure 33. Swift
paymentInfo.setAdditionalFields(additionalFields: [
          AdditionalField(type: .customer_first_name, value: "Mark"),
          AdditionalField(type: .billing_country, value: "US"),
          AdditionalField.init(type: .aps_account_number, value: ""),
          AdditionalField.init(type: .aps_account_security_code, value: "")
          ....
])
Figure 34. Objective-C
[paymentInfo setAdditionalFields:@[
                 [[AdditionalField alloc] initWithType:customer_first_name value:@"Mark"],
                 [[AdditionalField alloc] initWithType:billing_country value:@"US"],
                 [[AdditionalField alloc] initWithType:aps_account_number value: ""],
                 [[AdditionalField alloc] initWithType:aps_account_security_code value: ""]
                 ...
]];

Customization

You may change design of the SDK for iOS payment form:
  • use pre-defined themes (light and dark)
    Figure 35. Light theme of the payment form
    Figure 36. Dark theme of the payment form
  • set the custom value to any available setting

Using pre-defined themes

SDK for iOS allows you to choose between two pre-defined themes (light and dark) of payment form. By default SDK for iOS uses light theme.

To set a dark theme:
Figure 37. Swift
let theme = PsphostTheme.getDarkTheme()
psphostSDK.setTheme(theme: theme)
Figure 38. Objective-C
PsphostTheme *theme = [PsphostTheme getDarkTheme];
[self.psphostSDK setTheme:theme];

Changing settings

Also you can set the custom value to any available setting. For example, for green background color and dark virtual keyboard, set:
Figure 39. Swift
theme.backgroundColor = UIColor.green
theme.showDarkKeyboard = true
Figure 40. Objective-C
theme.backgroundColor = UIColor.greenColor;
theme.showDarkKeyboard = true;
The list of available setting:
  • overlayColor—the color of the overlay
  • backgroundColor—the color of the background of the payment form
  • headingTextColor—the color of the heading
  • menuTextColor—the text color of the buttons in the heading of the modal window
  • fieldTextColor—the text color of additional fields, payment methods names, text on the page with information about the result
  • supportiveTextColor—the color of the additional text
  • fieldPlaceholderTextColor—the color of the placeholder texts
  • fieldImageTintColor—the color of the icons of the CVV field and payment data fields for payment with a new card
  • fieldTextCorrectColor—the color of the text if validation of the completed field is successful
  • fieldTextWrongColor—the color of the text if validation of the completed field fails
  • fieldBackgroundColor—the color of the buttons of payment systems and CVV field
  • primaryTintColor—the main color of buttons and icons of the payment form,
  • secondaryTintColor—the secondary color of the payment form,
  • lineColor—the color of the field borders on the page with fields for payment with a new card
  • actionButtonDisableBackgroundColor—the color of the disabled action button
  • actionButtonDisableTextColor— the color of the text on the disabled action button
  • actionButtonTextColor—the color of the text on the action button
  • showShadow—enables shadow for payment methods and saved cards on the page of payment method selection
  • showDarkKeyboard—enables dark theme for the keyboard
  • showDarkNavigationBar—enables dark theme for the navigation bar
  • showLightLogo—enables light logos when using dark theme