amazon iOS Integration User Guide

User Guide for amazon models including: amazon, iOS Integration

Stephan Venter

iOS Integration Guide

iOS Integration. Guide. Version: 3.7. April, 2021 ... For more details review the transaction feedback instructions in this section. You need to.

Not Your Device? Search For Manuals / Datasheets:

File Info : application/pdf, 47 Pages, 672.52KB

Document

✖

PDF APS Integration Guide - iOS

iOS Integration Guide
Document Version: 3.7 April, 2021

Amazon Payment Services

iOS Integration Guide

Contents
1 About this Document _____________________________________ 5
1.1 Intended audience ________________________________________________________ 5 1.2 Note regarding PayFort / FORT ______________________________________________ 5
2 Before you start the integration ____________________________ 6
3 Mobile SDK transaction workflow __________________________ 7
4 Installing the Mobile SDK _________________________________ 8
4.1 Include the SDK in your Xcode project _________________________________________ 8 4.1.1 Manual installation ____________________________________________________ 8 4.1.2 Installation using CocoaPods: ____________________________________________ 8
4.2 Ensuring your application does not disconnect in background mode __________________ 9
5 Creating a mobile SDK token _____________________________ 10
5.1 Mobile SDK token URLs___________________________________________________ 10 5.2 Submitting token request parameters _________________________________________ 11
6 Processing transactions with the iOS SDK __________________ 13
6.1 Two routes for payment processing __________________________________________ 13 6.2 Steps for standard checkout________________________________________________ 14 6.3 iOS mobile SDK operations ________________________________________________ 17
6.3.1 Request parameters __________________________________________________ 17 6.3.2 Response parameters_________________________________________________ 21
7 Complete sample code for standard UI checkout: ____________ 25
8 Customizing the standard payment UI______________________ 27
8.1 Customizing the standard payment UI ________________________________________ 27 8.2 Hiding the Amazon Payment Service loading prompt _____________________________ 28 8.3 Changing the presentation style _____________________________________________ 29 8.4 iOS SDK response _______________________________________________________ 29

Amazon Payment Services

iOS Integration Guide

9 Using a custom payment processing UI ____________________ 30
9.1 Stage 1: Generate an SDK token ____________________________________________ 30 9.2 Stage 2: Create the card components ________________________________________ 30 9.3 Stage 3: Initiate the payment _______________________________________________ 35 9.4 Sample code ___________________________________________________________ 35
10 Using Direct Pay________________________________________ 37
10.1 Direct Pay sample code ___________________________________________________ 37
11 Amazon Payment Services iOS SDK transaction feedback ____ 39
11.1 Receiving transaction feedback _____________________________________________ 39 11.2 Registering Transaction Feedback URLs ______________________________________ 39 11.3 Transaction Feedback Implementation________________________________________ 40
12 Validate API____________________________________________ 41
13 Migrating from version 2.3 of the SDK ______________________ 42
14 Appendix: About the Software ____________________________ 47
14.1 About this software_______________________________________________________ 47 14.2 Supported Platforms _____________________________________________________ 47 14.3 Localization ____________________________________________________________ 47 14.4 Screen Orientation _______________________________________________________ 47 14.5 Supported Payment Methods _______________________________________________ 47 14.6 Supported Payment Options _______________________________________________ 47

Amazon Payment Services

iOS Integration Guide

Copyright Statement. All rights reserved. No part of this document may be reproduced in any form or by any means or used to make any derivative such as translation, transformation, or adaptation without the prior written permission from Amazon Payment Services.
Trademark
2014-2021 Amazon Payment Services ©, all rights reserved. Contents are subject to change without prior notice.
Contact Us
integration-ps@amazon.com https://paymentservices.amazon.com

Amazon Payment Services

iOS Integration Guide

1 About this Document
This document describes our Mobile SDK for iOS and includes information on how to integrate it with your mobile application.
1.1 Intended audience This document was created for iOS developers that integrate the Amazon Payment Services iOS mobile SDK with their merchant application.
1.2 Note regarding PayFort / FORT
Amazon Payment Services is the new name for PayFort. PayFort is a leading provider of payment processing services that was acquired by Amazon in 2017.
Throughout this section, and in our API reference and SDK guides, you will see references to PayFort. You may also see references to Fort or FORT.
We continue to use PayFort and Fort in our documentation for the simple reason that the code that powers Amazon Payment Services still contains references to PayFort.
To ensure ongoing stability, and to minimize the development overhead for our customers, we are slowly but steadily changing references to PayFort across our core code and our documentation.
In the meantime, when you see PayFort or Fort, you can safely assume that we are referring to Amazon Payment Services features and benefits.

Amazon Payment Services

iOS Integration Guide

2 Before you start the integration
Read through the following steps first to understand how the integration process works. This will help you to understand why these steps are required and why you need to follow a specific sequence.
Step 1: Access your test account
You need to make sure that you have access to a test account with Amazon Payment Services. It is a full test environment that allows you to fully simulate transactions.
Step 2: Choose between a standardized or custom payment UI
The Amazon Payment Services iOS SDK provides you with a standard payment UI that you can use to quickly integrate in-app payments. The standard UI offers limited customizability.
Alternatively, you can choose to build your own payment UI using Amazon Payment Services iOS SDK building blocks, we describe this in the section on custom-coding a payment processing UI.
Step 3: Make sure that you are using the correct integration type
Prior to building the integration, you need to make sure that you are selecting and using the proper parameters in the API calls as per the required integration type. All the mandatory parameters are mentioned under every section in the API document
Step 4: Install the Amazon Payment Services iOS SDK in your developer environment
You need to download our iOS SDK from the link provided. Next you need to include the iOS SDK in your Xcode project by following the steps in the next section. You are also required to install the library and to integrate the iOS SDK into your app.
Step 5: Create a test transaction request
You need to create a test transaction request. Processing a valid API request depends on the transaction parameters included, you need to check the documentation and review every parameter to reduce the errors in processing the transaction.
Step 6: Process a transaction response
After every payment, Amazon Payment Services returns the transaction response on the URL configured in your account under Technical Settings, Channel Configuration.
For more details review the transaction feedback instructions in this section. You need to validate the response parameters returned on this URL by calculating the signature for the response parameters using the SHA response phrase configured in your account under security settings.
Step 7: Test and Go Live
You can use our test card numbers to test your integration and simulate your test cases. The Amazon Payment Services team may need to test your integration before going live to assure your application integration.

Amazon Payment Services

iOS Integration Guide

3 Mobile SDK transaction workflow
Below we describe the transaction workflow that occurs when you process a payment using the Amazon Payment Service iOS Mobile SDK.
1. Your customer clicks on the Pay button in your app. 2. Your merchant system (back-end) generates a mobile SDK token using the Amazon
Payment Services API. 3. Your app passes the parameters, including the SDK token, to the iOS mobile SDK. 4. The iOS mobile SDK starts a secure connection and sends the transaction request to the
Amazon Payment Services server to be validated. 5. The Amazon Payment Services API validates the SDK token, device_ID and other request
parameters and returns the validation response the iOS SDK. 6. Assuming validation is passed your merchant app displays a payment page to the
customer. 7. Your customer enters their payment details on the payment page in the iOS SDK prompt
on their device. 8. The Amazon Payment Services iOS SDK validates your customer's details and sends a
transaction (Authorization or Purchase) request to the relevant payment processor and issuing bank. 9. The payment processor processes the transaction request and returns a transaction response to the iOS SDK. 10. The Amazon Payment Services iOS SDK returns the transaction response to your merchant app. 11. Your merchant app displays the response to your customer.

Amazon Payment Services

iOS Integration Guide

4 Installing the Mobile SDK
These are the first steps you need to follow to install the Amazon Payment Services iOS SDK in your iOS application.
4.1 Include the SDK in your Xcode project You have two options for including the SDK in your Xcode project. You can do so manually, or you can include the SDK by using CocoaPods
4.1.1 Manual installation

1. Obtain the Amazon Payment Services iOS Mobile SDK by downloading it from the Amazon Payment Services website.
2. Extract the folder you downloaded in the previous step.
3. Drag PayFortSDK.xcframework into the Frameworks, Libraries, and Embedded Content section of your target.

4.1.2 Installation using CocoaPods:
NOTE: The PayFort SDK is distributed as an XCFramework, therefore you are required to use Cocoapods 1.9.0 or newer.
1. Add the following code to your Podfile (inside the target section):

pod 'PayFortSDK'

Amazon Payment Services 3. Run the following command:
pod install

iOS Integration Guide

NOTE: Ensure it is linked once in the Linked Framework and Libraries or just drag the PayFortSDK.xcframework to Embedded Binaries in the general tab in the project settings.
NOTE: In Xcode, secondary-click your project's .plist file and select Open As -> Source Code. Insert the following XML snippet into the body of your file just before the final, as below:
</dict>element <key>NSAppTransportSecurity</key> <dict> <key>NSAllowsArbitraryLoads</key><true/> </dict>

4.2 Ensuring your application does not disconnect in background mode
To ensure that your app does not disconnect from the SDK when it goes into the background make sure to add this code: Objective-C:

(void)applicationDidEnterBackground:(UIApplication *)application { block UIBackgroundTaskIdentifier backgroundTask; backgroundTask =
[application beginBackgroundTaskWithExpirationHandler: ^ { [application endBackgroundTask:backgroundTask]; backgroundTask = UIBackgroundTaskInvalid; }]; }
Swift

func applicationDidEnterBackground(_ application: UIApplication) { var bgTask: UIBackgroundTaskIdentifier = 0 bgTask = application.beginBackgroundTask(expirationHandler: { application.endBackgroundTask(bgTask) bgTask = UIBackgroundTaskInvalid }) }

Amazon Payment Services

iOS Integration Guide

5 Creating a mobile SDK token
A mobile SDK authentication token is required to authenticate every request sent to the SDK. The token is also significant to process payment operations with Amazon Payment Services through our iOS mobile SDK.
To get started with our iOS mobile SDK you must first establish the ability to generate a mobile SDK token.
NOTE: The creation and initiation of a mobile SDK token happens on your server your server must generate the token by sending a request to the Amazon Payment Services API.
NOTE: A unique authentication token must be created for each transaction. Each authentication token has a life-time of only one hour if no new request from the same device is sent.
5.1 Mobile SDK token URLs These are the URLs you need to use when you request a mobile SDK token for your iOS app:
Test Environment URL
https://sbpaymentservices.payfort.com/FortAPI/paymentApi
Production Environment URL
https://paymentservices.payfort.com/FortAPI/paymentApi

Amazon Payment Services

iOS Integration Guide

5.2 Submitting token request parameters You need to submit parameters as a REST POST request using JSON. Below we list the range of parameters for the iOS mobile SDK token request.
5.2.1.1 iOS Mobile SDK Token Request Parameters When you send your request for an iOS mobile SDK token you must send the following parameters to Amazon Payment Services:
Request Parameters

Parameter Name Type Mandatory Description Length Allowed Special Characters Possible/ Expected Values Example

service_command Alpha

Yes

Command 20

access_code

Alphanumeric Yes

Access

code

merchant_identifier Alphanumeric Yes

Your

merchant

language

Alpha

Yes

The

checkout

page and

messages

language.

device_id

Alphanumeric Yes

A unique 100

device

identifier.

signature

Alphanumeric Yes

A string

200

hashed

using the

Secure

Hash

Algorithm.

SDK_TOKEN
zx0IPmPy5j p1vAz8Kpg 7
CycHZxVj

ffffffffa9fa0b447b2729e70033 c587
7cad05f021 2ed933c9a 5d5dffa316 61acf2c827 a

NOTE: device_id - This value to be generated from the UIDevice Class Reference, and you can generate this parameter by using the following command: [payFort getUDID]

Amazon Payment Services

iOS Integration Guide

5.2.1.2 iOS Mobile SDK Token Response Parameters These parameters will be returned in the Amazon Payment Services response:
Response Parameters

Parameter Nam e Type Mandatory Description Length Possible/ Expecte d Values Example

service_command Alpha

Yes Command

access_code

Alphanumeric Yes Access code

merchant_identifier Alphanumeric Yes

language

Alpha

Yes

device_id

Alphanumeric Yes

Your merchant ID 20

The

checkout page and

messages

language.

A unique

100

device

identifier.

sdk_token signature

Alphanumeric Yes Alphanumeric Yes

An SDK

100

authentication token

to enable using the

iOS

Mobile SDK.

A string hashed

200

using the Secure

Hash

Algorithm.

status

Numeric

A two-digit numeric 2

value that indicates

the status of the

transaction.

SDK_TOKEN

zx0IPmPy5j p1vAz8Kpg 7

CycHZxVj

ffffffffa9fa0b447b2729e70033 c587
Dwp78q3

7cad05f021 2ed933c9a 5d5dffa316 61acf2c827 a

NOTE: Every parameter the merchant sends in the request should be received by the merchant in the response - even the optional parameters.

Amazon Payment Services

iOS Integration Guide

6 Processing transactions with the iOS SDK
In this section we outline how you process a transaction using the iOS mobile SDK.

6.1 Two routes for payment processing As a merchant you have two ways in which you can process payments using the Amazon Payment Services iOS mobile SDK.
1. Standard payment screen. You can use the standard Amazon Payment Services iOS SDK interface to display a standard payment screen.
This standard payment view is customizable in three ways. You can hide the loading screen, and you can change the presentation style from full screen to OS default. You can also customize some of the UI elements. We address customizing the standard payment screen in Section 7.
2. Custom integration. You can choose to build your own payment processing screen by coding your own payment processing screen. With this mobile SDK feature, we allow merchants to integrate a native app checkout experience without displaying our standard payment screen while still using SDK features for rapid go-live.
With this integration route your customers can securely pay using a custom merchant checkout interface. The SDK provides card input fields and a pay button that merchants can encapsulate inside their checkout interface to match their own inline customer experience.
The Amazon Payment Services SDK will securely transmit the completed card details to the Amazon Payment Services API for processing in order to complete the transaction. We discuss the custom-coded payment UI in Section 5.

Amazon Payment Services

iOS Integration Guide

6.2 Steps for standard checkout These are the steps you need to follow to perform a checkout using our standard UI. See the next section for building your own customized payment UI. 1. Import the framework into your app
Start by importing the Amazon Payment Service iOS SDK library. You do so by using the following code:
Objective-C

#import <PayFortSDK/PayFortSDK-Swift.h>

Swift

import PayFortSDK

2. Initialize the controllers Initialize PayFortController at class level and only once within the targeted environment. You set the target environment by setting one of the two ENUM, either PayFortEnviromentSandBox or PayFortEnviromentProduction. Objective-C
PayFortController *payFort = [[PayFortController alloc]initWithEnviroment: PayFortEnviromentSandBox];
Swift
let payFort = PayFortController.init(enviroment: .sandBox)

Amazon Payment Services
3. Preparing Request Parameters Set a dictionary that contains all keys and values for the SDK Objective-C

iOS Integration Guide

NSMutableDictionary *request = [[NSMutableDictionary alloc]init]; [request setValue:@"10000" forKey:@"amount"]; [request setValue:@"AUTHORIZATION" forKey:@"command"]; [request setValue:@"USD" forKey:@"currency"]; [request setValue:@ "email@domain.com" forKey:@"customer_email"] [request setValue:@"en" forKey:@"language"]; [request setValue:@"112233682686" forKey:@"merchant_reference"] [request setValue:@"SDK TOKEN GOES HERE" forKey:@"sdk_token"]; [request setValue:@"" forKey:@"payment_option"]; [request setValue:@"gr66zzwW9" forKey:@"token_name"];
Swift

let request = ["amount" : "1000", "command" : "AUTHORIZATION", "currency" : "AED", "customer_email" : "rzghebrah@payfort.com", "installments" : "", "language" : "en", "sdk_token" : "token"]

4 . Response callback function
Amazon Payment Services allows you retrieve and receive the response parameters after processing a transaction once the transaction is completed. It only happens during the installation process. This is the code you need to use: Objective-C

[payFort callPayFortWithRequest:request currentViewController:self success:^(NSDictionary *requestDic, NSDictionary
*responeDic) { NSLog(@"Success"); NSLog(@"responeDic=%@",responeDic);
} canceled:^(NSDictionary *requestDic, NSDictionary
*responeDic) { NSLog(@"Canceled"); NSLog(@"responeDic=%@",responeDic);
} faild:^(NSDictionary *requestDic, NSDictionary
*responeDic, NSString *message) { NSLog(@"Faild"); NSLog(@"responeDic=%@",responeDic);
}];

Amazon Payment Services Swift

iOS Integration Guide

payFort.callPayFort(withRequest: request, currentViewController: self, success: { (requestDic, responeDic) in print("success")
}, canceled: { (requestDic, responeDic) in
print("canceled") }, faild: { (requestDic, responeDic, message) in print("faild") })

Amazon Payment Services

iOS Integration Guide

6.3 iOS mobile SDK operations 6.3.1 Request parameters
This is a list of the parameters you need to send when you send a request to the iOS SDK.
Request Parameters

Parameter Name Type Mandatory Description Length Allowed special characters Possible or Expected Values Example

command

Alpha

Yes Command 20

merchant_reference Alphanumeric Yes Your unique 40 - _ order ID

amount
currency language customer_email sdk_token

Numeric

Yes *Each

currency has

predefined

allowed

decimal

points that

should be

taken into

consideration

when

sending

the amount.

Alpha

Yes The currency 3 of the
transaction's amount in ISO code 3.

Alpha

Yes Language

used on the

checkout

page and for

messages

Alphanumeric Yes

Your
customer's email
address

254 _ - . @ +

Alphanumeric Yes The SDK

100

token you

generate for

AUTHORIZATION -PURCHASE
XYZ9239y u898 10000
AED
en ar
customer @domain. com Dwp78q3

Amazon Payment Services

iOS Integration Guide

token_name

Alphanumeric No

payment_option

Alpha

eci

Alpha

order_description

Alphan

umeric

customer_ip

Alphan

umeric

customer_ name

Alpha

phone_number

Alphan

umeric

settlement_reference Alphan

umeric

every SDK transaction

The token received from the tokenization process

100 . @ _

Op9Vmp

Payment

option

VISA MASTERCARD AMEX MADA (for Purchase operations and eci Ecommerce only).

E-commerce 16 indicator

ECOMMERCE

It holds the 150 description of the order

# ' / . _ - : $ Space

iPhone 12 Pro

It holds the 45 customer 's IP address. *It's Mandatory, if the fraud service is active.

192.178.1. 10

The
customer's name

40 _ \ / . '

John Smith

The
customer's phone number

19 + ( ) Space

00962797 219966

The

34 -

Merchant

submits this

value to

Amazon

Payment

Services.

The value is

then passed

to the

Acquiring

bank and

displayed to

the merchant

XYZ9239 yu898

Amazon Payment Services

merchant_ extra

Alphan umeric

merchant_ extra1

Alphan umeric

merchant_ extra2

Alphan umeric

merchant_ extra3

Alphan umeric

merchant_ extra4

Alphan umeric

merchant_ extra5

Alphan umeric

in the Acquirer settlement file.

No Extra data

999 ;

sent by

merchant

. Will be

received and

sent back as

received. Will

not be

displayed in

any report.

No Extra data

250 ;

sent by

merchant.

Will be

received and

sent back as

received. Will

not be

displayed in

any report.

No Extra data

250 ;

sent by

merchant.

Will be

received and

sent back as

received. Will

not be

displayed in

any report.

No Extra data

250 ;

sent by

merchant.

Will be

received and

sent back as

received. Will

not be

displayed in

any report.

No Extra data

250 ;

sent by

merchant.

Will be

received and

sent back as

received. Will

not be

displayed in

any report.

No Extra data

250 ;

sent by

merchant.

Will be

received and

iOS Integration Guide
JohnSmith JohnSmith JohnSmith JohnSmith JohnSmith JohnSmith
19

Amazon Payment Services

iOS Integration Guide

sent back as

received. Will

not be

displayed in

any report.

NOTE: Before sending the transaction value you must multiply the value by a factor that matches the ISO 4217 specification for that currency. Multiplication is necessary to accommodate decimal values. Each currency's 3-digit ISO code will have a specification for the number of digits after the decimal separator.
For example: If the transaction value is 500 AED; according to ISO 4217, you should multiply the value with 100 (to accommodate 2 decimal points). You will therefore send an AED 500 purchase amount as a value of 50000.
Another example: If the amount value was 100 JOD; according to ISO 4217, you should multiply the value with 1000 (to accommodate 3 decimal points). You therefore send a JOD 100 purchase amount as a value of 100000.

Amazon Payment Services

6.3.2 Response parameters

Request Parameters

iOS Integration Guide

Parameter Nam e Type Description Length Possible or Expecte d Values Example

command

Alpha

Command 20

merchant_reference Alphanumeric Your unique 40 order ID

amount
currency language customer_email fort_id sdk_token

Numeric

*Each

currency has

predefined

allowed

decimal

points that

should be

taken into

consideration

when

sending

the amount.

Alpha

The currency 3 of the
transaction's amount in ISO code 3.

Alpha

Language

used on the

checkout

page and for

messages

Alphanumeric Your

254

customer's

address

Numeric

The order's 20 unique reference returned by our system.

Alphanumeric The SDK

100

token you

generate for

every SDK

transaction

AUTHORIZATION -PURCHASE
XYZ9239y u898 10000
AED
en ar
customer @domain. com 14437968668 48
Dwp78q3

Amazon Payment Services

iOS Integration Guide

token_name payment_option

Alphanumeric The token

100

received

from the

tokenization

process

Alpha

Payment

option

eci

Alpha

authorization_code Alphanu meric

order_description

Alphan umeric

response_message Alphanu meric

response_code

Numeric

status

Numeric

customer_ip

Alphan umeric

E-commerce 16 indicator

The

100

authorization

code

returned

from the 3rd

party.

It holds the 150 description of the order

Message

150

description of

the response

code. It

returns

according to

the request

language.

Response

Code carries

the value of

our system's

response.

The code is

made up of

five digits.

A two-digit 2 numeric value that indicates the status of the transaction.

It holds the 45 customer 's IP address. *It's Mandatory, if the fraud service is active.

Op9Vmp

VISA MASTERCARD AMEX MADA (for Purchase operations and eci Ecommerce only).
ECOMMERCE

P100000000

0000372136

iPhone 12 Pro

Insufficient

funds

192.178.1. 10

Amazon Payment Services

expiry_date card_number

Numeric Numeric

customer_ name

Alpha

phone_number

Alphan umeric

settlement_refe rence

Alphan umeric

merchant_ extra

Alphan umeric

merchant_ extra1

Alphan umeric

The card's expiry date.

The masked 16 credit card number. Only the MEEZA payment option takes 19 digits card number. *AMEX payment option takes 15 digits card number. *Otherwise, they take 16 digits card number.

The

customer's

name

The

customer's

phone

number

The

Merchant

submits this

value to

Amazon

Payment

Services.

The value is

then passed

to the

Acquiring

bank and

displayed to

the merchant

in the

Acquirer

settlement

file.

Extra data

999

sent by

merchant

. Will be

received and

sent back as

received. Will

not be

displayed in

any report.

Extra data

250

sent by

merchant.

Will be

iOS Integration Guide
400555****** 0001
John Smith 00962797 219966 XYZ9239 yu898
JohnSmith
JohnSmith
23

Amazon Payment Services

iOS Integration Guide

merchant_ extra2

Alphan umeric

merchant_ extra3

Alphan umeric

merchant_ extra4

Alphan umeric

merchant_ extra5

Alphan umeric

received and sent back as received. Will not be displayed in any report.

Extra data

250

sent by

merchant.

Will be

received and

sent back as

received. Will

not be

displayed in

any report.

Extra data

250

sent by

merchant.

Will be

received and

sent back as

received. Will

not be

displayed in

any report.

Extra data

250

sent by

merchant.

Will be

received and

sent back as

received. Will

not be

displayed in

any report.

Extra data

250

sent by

merchant.

Will be

received and

sent back as

received. Will

not be

displayed in

any report.

JohnSmith JohnSmith JohnSmith JohnSmith

NOTE: Every parameter the Merchant sends in the Request should be received by the Merchant in the Response - even the optional ones.

Amazon Payment Services

iOS Integration Guide

7 Complete sample code for standard UI checkout:
The following sample code shows you how to process a payment using the standard view. The code sample illustrates how you send a request operation in the mobile SDK.

Objective-C
- (void)viewDidLoad { [super viewDidLoad]; payfort = [[PayFortController alloc]
initWithEnviroment:PayFortEnviromentSandBox]; }
NSMutableDictionary *requestDictionary = [[NSMutableDictionary alloc]init]; [requestDictionary setValue:@"10000" forKey:@"amount"]; [requestDictionary setValue:@"AUTHORIZATION" forKey:@"command"]; [requestDictionary setValue:@"USD" forKey:@"currency"]; [requestDictionary setValue:@"email@domain.com" forKey:@"customer_email"]; [requestDictionary setValue:@"en" forKey:@"language"]; [requestDictionary setValue:@"112233682686" forKey:@"merchant_reference"]; [requestDictionary setValue:@"" forKey:@"payment_option"]; [requestDictionary setValue:@"gr66zzwW9" forKey:@"token_name"];
[payFort callPayFortWithRequest:requestDictionary currentViewController:self success:^(NSDictionary *requestDic, NSDictionary *responeDic) {
} canceled:^(NSDictionary *requestDic, NSDictionary *responeDic) { } faild:^(NSDictionary *requestDic, NSDictionary *responeDic, NSString *message) {
}];

Amazon Payment Services

iOS Integration Guide

Swift
let request = ["amount" : "1000", "command" : "AUTHORIZATION", "currency" : "AED", "customer_email" : "rzghebrah@payfort.com", "installments" : "", "language" : "en", "sdk_token" : "token"]
payFort.callPayFort(withRequest: request, currentViewController: self, success: { (requestDic, responeDic) in print("success") print("responeDic=\(responeDic)") print("responeDic=\(responeDic)")
}, canceled: { (requestDic, responeDic) in
print("canceled") print("responeDic=\(responeDic)") print("responeDic=\(responeDic)")
}, faild: { (requestDic, responeDic, message) in
print("faild") print("responeDic=\(responeDic)") print("responeDic=\(responeDic)") })

Amazon Payment Services

iOS Integration Guide

8 Customizing the standard payment UI
When you use the standard payment UI you can customize the payment UI presented by our iOS SDK in a number of ways to better reflect your business. We outline your options below.

8.1 Customizing the standard payment UI
You can customize the standard payment user interface in your iOS app. This is an example of a customized payment UI:

Standard vs. Customized Mobile SDK Payment Page
Follow these steps to configure a customized payment UI: 1. Create your nibFile .xib and set the name of Arabic xib same name with English one with suffix -ar.
2. Link the xib with PayFortView and bind all the IBOutlets in interface section IBOutlet UILabel *titleLbl;

IBOutlet UIButton *BackBtn; IBOutlet UILabel *PriceLbl; IBOutlet JVFloatLabeledTextField *CardNameTxt; IBOutlet JVFloatLabeledTextField *CardNumberTxt; IBOutlet JVFloatLabeledTextField *CVCNumberTxt; IBOutlet JVFloatLabeledTextField *ExpDateTxt; IBOutlet UILabel *cardNumberErrorlbl;

Amazon Payment Services

iOS Integration Guide

IBOutlet UILabel *cVCNumberErrorlbl; IBOutlet UILabel *expDateErrorlbl; IBOutlet UISwitch *savedCardSwitch; IBOutlet UIButton *paymentBtn; IBOutlet UILabel *saveCardLbl; IBOutlet UIImageView *imageCard;
3. Assign new created xib file to Amazon Payment Services controller.
[payFort setPayFortCustomViewNib:@"PayFortView2"];

NOTE. If you call Arabic view and the Arabic view not existed the application will crash. Don't forget to set the custom view field in the identity inspector
8.2 Hiding the Amazon Payment Service loading prompt There is an option to hide the loading prompt when the iOS SDK initializes the connection request. You can disable the loading prompt by using following option: Objective-C
payFort.hideLoading = YES;

Swift
payFort.hideLoading = true

Amazon Payment Services

iOS Integration Guide

8.3 Changing the presentation style

It's easy to change the presentation style from full screen to default by using the following property:
Objective-C
payFort.presentAsDefault = YES;

Swift
payFort.presentAsDefault = true
NOTE: The default type is full screen when you set the value to false, when set to true it will appear according to the OS default.
8.4 iOS SDK response There is an option to show the response view more directly in an elegant view that shows the response results either as success or failed. You do so by activating the following option: Objective-C
payFort.isShowResponsePage = YES;
Swift
payFort.isShowResponsePage= true

Amazon Payment Services

iOS Integration Guide

9 Using a custom payment processing UI
In this section we outline the key information you need to create your own payment processing screen using the tools in the iOS SDK.
9.1 Stage 1: Generate an SDK token You need to generate an SDK token before you can start processing payments using your custom payment processing UI. Refer to the SDK token section earlier in this document for instructions on creating an SDK token.
9.2 Stage 2: Create the card components You create your custom payment screen by using the following five components included in the Amazon Payment Services iOS SDK:
· CardNumberView · CVCNumberView · ExpiryDateView · CardHolderNameView · PayButton

Attributes textColor fontStyle backgroundColor
errorText errorFontStyle errorTextColor titleText titleTextColor titleErrorTextColor titleFontStyle

Attributes for custom payment UI

Type

Description

UIColor

The input text filed text color

UIFont

The input text filed font style

UIColor

The input text filed background color

String

The Error Label text

UIFont

The Error Label text Font Style

UIColor

The Error Label text Text Color

String

The Title Label text

UIColor

The Title Label text Color

UIColor

The Error Title Label text Color

UIFont

The Title Label Font style

Amazon Payment Services

iOS Integration Guide

Components Views Item property, all these properties are available for each component. Swift

let property = Property() property.textColor property.fontStyle property.backgroundColor property.errorFontStyle property.errorTextColor property.titleTextColor property.titleErrorTextColor property.titleFontStyle
Objective-c
Property *property = [[Property alloc] init] property.textColor property.fontStyle property.backgroundColor property.errorFontStyle property.errorTextColor property.titleTextColor property.titleErrorTextColor property.titleFontStyle
1. CardNumberView:
The CardNumberView inheritance from UIView, CardNumberView is used to validate the card number, card brand and card number length. Swift
@IBOutlet private weak var cardNumberView: CardNumberView! cardNumberView.property = property
Objective-c
@property (nonatomic, weak) IBOutlet CardNumberView *cardNumberView; cardNumberView.property = property

Amazon Payment Services

iOS Integration Guide

2. ExpiryDateView:
The ExpiryDateView inheritance from UIView, ExpiryDateView is used to check the expiry date for the credit card. Swift
@IBOutlet private weak var expiryDateView: ExpiryDateView! expiryDateView.property = property

Objective-c

@property (nonatomic, weak) IBOutlet ExpiryDateView *expiryDateView; expiryDateView.property = property

3. CVCNumberView The CVCNumberView inheritance from UIView, CVCNumberView used to check if cvc matches cardBrad.
Swift
@IBOutlet private weak var cvcNumberView: CVCNumberView! cvcNumberView.property = property
Objective-c
@property (nonatomic, weak) IBOutlet CVCNumberView *cvcNumberView; cvcNumberView.property = property

Amazon Payment Services

iOS Integration Guide

4. HolderNameView
The HolderNameView inheritance from UIView, HolderNameView is used to fill the card holder name.
Swift

@IBOutlet private weak var holderNameView: HolderNameView! holderNameView.property = property
Objective-c

@property (nonatomic, weak) IBOutlet holderNameView *holderNameView; holderNameView.property = property

5. ErrorLabel
It will show any error message for owner card view, you can set your custom UILabel, Example:
Swift

@IBOutlet private weak var cardNumberErrorLabel: ErrorLabel! cardNumberView.errorLabel = cardNumberErrorLabel
Objective-c

@property (nonatomic, weak) IBOutlet ErrorLabel *cardNumberErrorLabel; cardNumberView.errorLabel = cardNumberErrorLabel

Amazon Payment Services
Example of components views in Objective-C and Swift This is one example of how to customize the component: Swift
let property = Property() property.textColor = .yellow property.backgroundColor = .green property.errorTextColor = .green property.titleTextColor = .red cardNumberView.property = property
Objective-c
Property * property = [[Property alloc] init]; property.textColor = UIColor.yellowColor; property.backgroundColor = UIColor.greenColor; property.errorTextColor = UIColor.greenColor; property.titleTextColor = UIColor.redColor; cardNumberView.property = property;

iOS Integration Guide

Amazon Payment Services

iOS Integration Guide

9.3 Stage 3: Initiate the payment
PayButton
Used to collect the card data from card components above and to submit successful payment. With a few simple steps it also has the capability to perform Direct Pay without the need for the card component, see the next section.
PayfortPayButton methods
/** Update Request After doing Setup - Parameter request: a new request dictionary */
public func updateRequest(request: [String: String])
/** Responsible for Save token or not - Parameter enabled: a new bool value */
public func isRememberEnabled(_ enabled: Bool)

9.4 Sample code In this section we illustrate how you use the PayButton using sample code for Swift and Objective-C.
Swift

@IBOutlet weak var payButton: PayButton!
let builder = PayComponents(cardNumberView: cardNumberView, expiryDateView: expiryDateView, cvcNumberView: cvcNumberView, holderNameView: holderNameView, rememberMe: saveCardSwitch.isOn)
payButton.setup(with: request, enviroment: enviroment, payComponents: builder, viewController: self) {
// Process started } success: { (requestDic, responeDic) in // Process success } faild: { (requestDic, responeDic, message) in // Process faild }

Amazon Payment Services Objective-C

iOS Integration Guide

@property (nonatomic, weak) IBOutlet PayButton *payButton;
PayComponents *builder = [[PayComponents alloc] initWithCardNumberView:cardNumberView expiryDateView: expiryDateView cvcNumberView: cvcNumberView, holderNameView: holderNameView rememberMe: saveCardSwitch.on];
[payButton setupWithRequest: request enviroment: enviroment
payComponents: builder currentViewController: self
Success:^(NSDictionary *requestDic, NSDictionary *responeDic) {
} Canceled:^(NSDictionary *requestDic, NSDictionary *responeDic) { } Faild:^(NSDictionary *requestDic, NSDictionary *responeDic, NSString *message) { }];

Amazon Payment Services

iOS Integration Guide

10 Using Direct Pay

The Direct Pay feature enables Amazon Payment Services merchants to securely process ecommerce transactions using tokenized payment card details.
For customers that already supplied their payment card details in a previous transaction and where a card token was generated, customers need to just provide the card_security_code to complete their purchase.
The card token and provided card security code can be sent to the Amazon Payment Services iOS mobile SDK to complete the customer purchase through Direct Pay operation to complete the order placement using eCommerce channel.
Note you can use Direct Pay both with the standard payment UI or with a customized payment UI.

10.1 Direct Pay sample code Swift

@IBOutlet weak var directPayButton: PayButton!
// request should has all mandatory params and also you need to send card_security_code, token_name
let request = ["amount" : "1000", "command" : "AUTHORIZATION", "currency" : "AED", "customer_email" : "test@payfort.com", "language" : "en", "card_security_code" : "123", "token_name" : "payfort", "merchant_reference" : "merchant reference", "sdk_token" : "token"]
directPayButton.setup(with: request, enviroment: enviroment, viewController: self) {
// Process started } success: { (requestDic, responeDic) in // Process success } faild: { (requestDic, responeDic, message) in // Process faild }

Amazon Payment Services Objective-c

iOS Integration Guide

@property (nonatomic, weak) IBOutlet PayButton *directPayButton;
NSMutableDictionary *requestDictionary = [[NSMutableDictionary alloc]init]; [requestDictionary setValue:@"10000" forKey:@"amount"]; [requestDictionary setValue:@"AUTHORIZATION" forKey:@"command"]; [requestDictionary setValue:@"USD" forKey:@"currency"]; [requestDictionary setValue:@"email@domain.com" forKey:@"customer_email"]; [requestDictionary setValue:@"en" forKey:@"language"]; [requestDictionary setValue:@"112233682686" forKey:@"merchant_reference"]; [requestDictionary setValue:@"payfort" forKey:@"token_name"]; [requestDictionary setValue:@"123" forKey:@"card_security_code"]; [requestDictionary setValue:@"token" forKey:@"sdk_token"];
[directPayButton setupWithRequest: request enviroment: enviroment
currentViewController: self Success:^(NSDictionary *requestDic, NSDictionary
*responeDic) { } Canceled:^(NSDictionary *requestDic, NSDictionary *responeDic) { } Faild:^(NSDictionary *requestDic, NSDictionary *responeDic, NSString
*message) { }];

Amazon Payment Services

iOS Integration Guide

11 Amazon Payment Services iOS SDK transaction feedback
While a transaction is processed, we will send a response directly to your direct transaction feedback URL. In theory, direct response feedback cannot be interrupted unless the URL you provided for responses is not functional at the time of the response.
We do this so that your server receives a response even if your customer does not successfully redirect to the return URL on your website, which may happen if your customer's browser or connection fails during the transaction.
11.1 Receiving transaction feedback
There are two ways in which you receive transaction feedback:
Direct transaction feedback. Amazon Payment Services sends an immediate payment processing response whenever a transaction is completed.
You can rely on this response for transaction feedback even where your user closed the browser before getting redirected successfully to the redirection URL or where your user was not redirected due to a drop in the internet connection.
Notification feedback. Were we need to provide you with the status of a transaction once it is received. In other words, we send notification feedback to alert you to any changes in the status of a transaction.
For example, if the transaction was pending due to the unavailability of any party to the transaction, the final update will be pushed to your notification feedback endpoint.
Notification feedback deals with a wide range of scenarios and it is critical that your website is configured to receive notification feedback correctly. For example, transaction feedback can alert you to any transactions that were stuck in "uncertain" status, but which have recovered to final status.
Direct feedback allows you to subscribe to transaction updates for uncertain transactions whenever you process a payment. It is a method for receiving the transaction response automatically once the transaction had completed or if there was an update.

11.2 Registering Transaction Feedback URLs To receive transaction feedback, you must register with Amazon Payment Services the transaction feedback URLs you set up on your server. Follow these steps: 1. Log in to your back-office account.
2. Select the active channel under Integration Settings > Technical Settings.
3. Enter your Direct Transaction Feedback URL and Notification Transaction Feedback URL.
4. Click the "Save Changes" button.

Amazon Payment Services

iOS Integration Guide

11.3 Transaction Feedback Implementation
We will send the response via HTTP POST request in POST form format to your webhook URL. The submission type can be changed from POST form to JSON or XML in your APS account settings. We only permit configuring URLs in HTTPS for direct feedback and for notification feedback.
To acknowledge receiving the direct feedback and notification successfully, the webhook URL must return a 2xx or 302 HTTP status. In case the URL returns different HTTP responses, our server will keep retrying up to 10 times until we receive a success response. We wait ten seconds between retries.
You can change and configure the retry mechanism attributes to increase or decrease the number of retries, time between retries and the grace period before we send the notifications.
You must create endpoints that accept direct transaction feedback and notification feedback from us via a webhook. You can customize how transaction feedback works -- for example, by including the grace period before a direct feedback notification is sent, and the time elapsed between retrying feedback submission.
To customize transaction feedback, email integration-ps@amazon.com. You can request to change the submission type to JSON or XML. You can also change the grace period or the time interval between the retries please contact us.
NOTE: You can check the direct and notification feedback logs in your back office account to check the details related to the submission like the Transaction Feedback URL which was triggered, The response which our system pushed, the response Code and Status retuned from your Transaction Feedback URL.
NOTE: The specifics of the data will differ based upon the financial operation that has been processed. Your code must be able to accommodate different data.

Amazon Payment Services

iOS Integration Guide

12 Validate API
Amazon Payment Services offers an API to request validation of the payment card details without performing an actual transaction.
ValidateAPI can help you to initiate an API request in order to validate the input parameters values, this will reduce the possibility of encountered API errors due to wrong user inputs before processing the actual payment card transaction.

Swift
let request = ["amount" : "1000", "command" : "AUTHORIZATION", "currency" : "AED", "customer_email" : "test@payfort.com", "language" : "en", "sdk_token" : "token"]
payFortController.callValidateAPI(with: request) { // Process started
} success: { // Process success
} faild: { (requestDic, responeDic, message) in // Process faild
})

Objective-c

NSMutableDictionary *request = [[NSMutableDictionary alloc]init]; [requestDictionary setValue:@"10000" forKey:@"amount"]; [requestDictionary setValue:@"AUTHORIZATION" forKey:@"command"]; [requestDictionary setValue:@"USD" forKey:@"currency"]; [requestDictionary setValue:@"email@domain.com" forKey:@"customer_email"]; [requestDictionary setValue:@"en" forKey:@"language"]; [requestDictionary setValue:@"112233682686" forKey:@"merchant_reference"]; [requestDictionary setValue:@"token" forKey:@"sdk_token"];
[payFortController callValidateAPIWithRequest: request ShowLoader:^() {
} Success:^(NSDictionary *requestDic, NSDictionary *responeDic) { } Faild:^(NSDictionary *requestDic, NSDictionary *responeDic, NSString *message) { }];

NOTE: When you make use of the Validate API call you still need to generate a mobile SDK token even though you are not processing a transaction.

Amazon Payment Services

iOS Integration Guide

13 Migrating from version 2.3 of the SDK
In this section we outline the steps you need to take to migrate from version 2.3 of the Amazon Payment Services iOS SDK to the latest release. To complete the migration follow these steps:
1. Remove PayFortSDK.framework and PayFortSDK.bundle
2. Use CocoaPods or manual integration by dragging the PayFortSDK.xcframework into your project
3. Import PayFortSDK.xcframework: Objective-C The replace import is shown below
//From #import <PayFortSDK/PayFortSDK> //To #import <PayFortSDK/PayFortSDK-Swift.h>

Swift import If you're using Swift you can import PayFortSDK directly on your controller, there is no need to use Bridging-Header any more
import PayFortSDK

Amazon Payment Services

iOS Integration Guide

4. Change callPayFortWithRequest method as below:
Objective-C
//From [payFort callPayFortWithRequest:myRequest currentViewController:self
Success:^(NSDictionary *requestDic, NSDictionary *responeDic) {
} Canceled:^(NSDictionary *requestDic, NSDictionary *responeDic) {
} Faild:^(NSDictionary *requestDic, NSDictionary *responeDic, }];
//TO [payFort callPayFortWithRequest:myRequest currentViewController:self
success:^(NSDictionary *requestDic, NSDictionary *responeDic) {
} canceled:^(NSDictionary *requestDic, NSDictionary *responeDic) {
} faild:^(NSDictionary *requestDic, NSDictionary *responeDic, }];

Swift
Chane the callPayFortWithRequest request param from NSMutableDictionary to
Dictionary

Amazon Payment Services

iOS Integration Guide

5. Change callPayFortForApplePayWithRequest method as below:
Objective-C
//From [payFort callPayFortForApplePayWithRequest:myRequest
applePayPayment:payment currentViewController:self
Success:^(NSDictionary *requestDic, NSDictionary *responeDic) {
} Faild:^(NSDictionary *requestDic, NSDictionary
*responeDic, NSString *message) {
completion(PKPaymentAuthorizationStatusFailure);
}];
//To
[payFort callPayFortForApplePayWithRequest:myRequest applePayPayment:payment
currentViewController:self success:^(NSDictionary *requestDic, NSDictionary
*responeDic) {
} faild:^(NSDictionary *requestDic, NSDictionary
*responeDic, NSString *message) {
completion(PKPaymentAuthorizationStatusFailure);
}];

Swift
Change callPayFortForApplePay request param from NSMutableDictionary to Dictionary

Amazon Payment Services

iOS Integration Guide

6. Change callPayFortForApplePay method as below
Objective-C
//From paycontroller.callPayFortForApplePay(withRequest: ["":""],
applePay: payment, currentViewController: self) { (requestDic, responeDic) in } faild: { (requestDic, responeDic, message) in }
//To paycontroller.callPayFortForApplePay(withRequest: ["":""],
applePayPayment: payment, currentViewController: self) { (requestDic, responeDic) in } faild: { (requestDic, responeDic, message) in }

Swift No changes necessary

7. Change environment as follows: Objective-C From KPayFortEnviromentSandBox to PayFortEnviromentSandBox From KPayFortEnviromentProduction to PayFortEnviromentProduction
Swift From KPayFortEnviromentSandBox to .sandbox From KPayFortEnviromentProduction to .production

Amazon Payment Services
8. Modify the IsShowResponsePage property: Objective-C: From IsShowResponsePage to isShowResponsePage Swift No changes needed
9. HideLoading property: Objective-C: From HideLoading to hideLoading Swift No changes needed.

iOS Integration Guide

Amazon Payment Services

iOS Integration Guide

14 Appendix: About the Software
14.1 About this software The Amazon Payment Services iOS mobile SDK allows merchants to securely integrate payment functionality into a native iOS app. It allows merchants to easily accept in-app payments.
Instead of the traditional, time-consuming, and complex way of being redirected to the mobile browser to complete the payment, in-app payments can easily be offered thanks to the iOS Mobile SDK.
In turn, this gives the merchants' customers a smooth, pleasing user experience thanks to inapp payment functions through the native applications.
14.2 Supported Platforms The Amazon Payment Services iOS SDK supports IOS 12.2+ and Xcode 11.0 and above.

14.3 Localization You can use both English and Arabic when you implement the iOS SDK.
14.4 Screen Orientation Currently, portrait is the only orientation supported within the Amazon Payment Services mobile SDK unless you build a customized payment integration.

14.5 Supported Payment Methods Using the iOS SDK the merchant can process debit or credit card transactions only.

14.6 Supported Payment Options
The supported credit card payment options are VISA, MASTERCARD, American Express (AMEX), MADA and MEEZA.

Stephan Venter

iOS Integration Guide

References