PayTabs ios SDK Integration Guide

Transcription

1 PayTabs ios SDK Integration Guide INTEGRATION GUIDE VERSION 3.0

2 Table of Contents 1 Overview Test Merchant Account v/s Live Merchant Account Target Audience Assistance Documentation Feedback 5 2 Importing the SDK ios Project 6 3 Integrating the SDK with your application SDK Parameters Sample Code SDK Response Language Configuration Important Notes Verify Transaction Request Response Response Codes PayTabs IPN (Instant Payment Notification) How IPN Works Set up your IPN Listener IPN Events Contents / Data of the IPN Response Codes Sample IPN Response IPN sample response for successful SDK transactions IPN sample response for rejected SDK transactions IPN sample response for rejected SDK transactions by fraud monitoring IPN sample response for force accepted SDK transactions IPN sample response for refunded SDK transactions 25 6 Refund Transactions Request Response Response Codes Transactions Reports 27 2 PayTabs ios SDK Integration Guide Version 3.0

3 7.1 Request Response Error Codes 30 8 Tokenization in SDK Sample Code 31 9 Process Payment with Existing Token Request Response Response Codes Test Credit Card Numbers Screenshots of the application PayTabs Mobile Payment Page Successful Payment Result Page Frequently Asked Questions 39 3 PayTabs ios SDK Integration Guide Version 3.0

4 Revision History Rev Description of Change Date New Document 15/01/ Formatted Document - Added documentation feedback address. - Added important note for secret key and spaces. - Updated credit card expiry dates. - Added code on how to view response codes - Added the different response codes and their description. - Added important note on simulators. 29/06/ /08/ General Document Enhancements 21/01/ Updated Header files screenshot 25/01/ Add screenshots of the application 02/02/ Update SDK to Version Added section Frequently Asked Questions 21/03/ Added Tokenization feature 18/07/ Added parameter card_last_four_digits in verify transaction response - Added FAQ about hybrid frameworks & Swift Code 27/07/2016 -Added FAQs related to ios SDK -Added Sample Response Codes for Paytabs IPN 29/06/ Remove screenshots and details related to Scan To Pay 28/08/ Update Test Cards Expiry date 20/02/ Added New Refund API response for successful refund processed - Added New IPN response for rejected refund request - A complete revamp of SDK - New mechanism of initiating and integrating SDK - Callbacks added to handle transaction responses - SDK is upgraded to static ios framework with encrypted resources bundle - Added validations to minimize errors - New UI/UX of SDK and updated validation rules - Added theme customization - Removal of unnecessary parameters - Alignment with the updated system - Fixations and improvements in the flow 04/06/ /12/ /09/ PayTabs ios SDK Integration Guide Version 3.0

5 1 Overview At PayTabs, we are committed to providing the most secure, reliable and user-friendly payment processing solutions. By partnering with us for your payment processing needs, you can be confident that payment transactions will be processed quickly and efficiently, and your customers information will be safe. You ll enjoy our ios SDK s easy set-up and easy integration into the ios applications you develop. Our two-level fraud protection system protects transaction data throughout the payment process. With PayTabs as your payment processor, you ll benefit from the fastest, most secure, and costeffective payment processing system in the industry. It's important to note that the PayTabs APIs and SDKs are constantly evolving, and updates are usually done every quarter, if required. PayTabs will intimate any major change, so it s important that you check your merchant dashboard notifications or , frequently to be updated. 1.1 Test Merchant Account v/s Live Merchant Account PayTabs does not offer an explicit Sandbox / Testing environment. But using a demo account, you can freely test all the functionalities and integrate our API, SDK and Plugin without any hassle. In order to move to LIVE PRODUCTION environment, you will need to activate your LIVE MERCHANT ACCOUNT by clicking on GO LIVE through your PayTabs Merchant Account. PayTabs requires some personal information, documents and other details related to your business to validate your business. Once your Merchant Account is activated, you will have been moved to the LIVE PRODUCTION environment. 1.2 Target Audience This document is intended for third party ios developers who wish to develop ios applications that interact with PayTabs.com 1.3 Assistance If you require assistance, please check out our Frequently Asked Questions or chat live with our support staff or us at support@paytabs.com. 1.4 Documentation Feedback Help us improve the PayTabs ios SDK Integration Guide, by sending your feedback to support@paytabs.com. 5 PayTabs ios SDK Integration Guide Version 3.0

6 2 Importing the SDK ios Project 1. Extract the PayTabs ios SDK.zip file which contains two folders, Framework and Resources along with samples. 2. Framework folder contains paytabs-ios.framework (static ios framework) and Resources.bundle (includes interface files, images, local files, etc). 3. Add paytabs-ios.framework into your workspace Frameworks folder by dragging and with Copy items if needed checked. Note: Please wipe out completely if you have any previous version already added in your codebase i.e. Delete it with "Move to trash" option and removing it from your Xcode project navigator. 4. Perform the same steps for Resources.bundle. 5. Add following pod dependencies in your podfile, don t add those which are already in the podfile. Make sure you have uncommented platform:ios, x.x. Your podfile should look like, 6 PayTabs ios SDK Integration Guide Version 3.0

7 6. Please add Pods in User Header Search Paths with Recursive option within your app target. 7 PayTabs ios SDK Integration Guide Version 3.0

8 7. If your application programming language is Swift, you will need to have Bridging Header for importing #import <paytabsios/paytabs_ios.h>. Also, give your bridging header path against Objective-C Bridging Header in your app target s build settings. 8. A d d t wo flags, -all_load and -ObjC in Build Settings/Other linker flags. 8 PayTabs ios SDK Integration Guide Version 3.0

9 3 Integrating the SDK with your application 3.1 SDK Parameters Element Description Format XIB name SDK initial.xib to invoke it. It s value should always be PTFWInitialSetupView. Bundle View frame Resources bundle of SDK which contains images, xibs, local data files, etc. CGRect (x, y, width, height) in which is sdk is intended to show. NSBundle/Bundle See example code to check how it is passed in SDK. CGRect E.g. self.view.frame Amount The amount of the transaction Float Up to 3 Decimal places E.g.: Customer Title Name of your customer. E.g.: Mr. John Doe Tax Amount The tax amount of the transaction Float Up to 3 Decimal places E.g.: Currency Code Currency of the amount stated. 3 character ISO currency code E.g.: USD for US dollar AED for Emirati Dirham BHD for Bahraini Dinar SAR for Saudi Riyal 9 PayTabs ios SDK Integration Guide Version 3.0

10 SDK Language Use to set language of SDK. Either ar or en Shipping Address Shipping address of the customer. In case you don t have physical goods, you can pass the same details as the billing details Up to 40 characters E.g.: Flat 11 Building 222 Block 333 Road 444 Manama Bahrain Shipping City Shipping City of the customer Up to 13 characters E.g.: Manama Shipping Country Shipping country of the customer 3 character ISO country code E.g.: BHR Shipping State Shipping State of the customer 2 characters ISO state code for US and Canada 32 characters E.g.: Manama E.g.: if state is New York then the state field should be NY 10 PayTabs ios SDK Integration Guide Version 3.0

11 Shipping ZIP code Shipping postal code of the customer From 5 to 9 characters E.g.: Billing Address Complete Address of the customer. Multiple address lines will be merged into one single line. Up to 40 characters E.g.: Flat 11 Building 222 Block 333 Road 444 Manama Bahrain Billing City Name of the billing city selected by customer Up to 13 characters E.g.: Manama Billing Country 3 character ISO Country of the customer 3 character ISO country code E.g.: BHR for Bahrain ARE for UAE SAU for Saudi Arabia Billing State Billing ZIP code Order ID Billing State entered by the customer. 2 characters ISO state code for US and Canada Billing Postal code provided by the customer. In case the country doesn t have a valid postal code, you can pass the country international dialing code (00973) The order id from your App to be able to map your order s to PayTabs transactions Up to 32 characters E.g.: Manama E.g.: if state is New York, then the state field should be NY From 5 to 9 characters E.g.: E.g.: PayTabs ios SDK Integration Guide Version 3.0

12 Phone Number Phone Number of the Customer E.g.: Customer of the Customer E.g. m Merchant Merchant that you use to sign up and/or login into PayTabs Merchant Dashboard Up to 128 characters E.g.: Secret Key Tokenization Assignee Code SECRET Key generated by merchant dashboard.this can be found by logging in to your Merchant Dashboard > Secret Key If true, SDK will return a token to use it for tokenized payments Its value should always be "SDK". Up to 128 characters E.g.: Mao8sdhasfyahosdap9sd Bool Either "true" or "false" Theme Color Light Theme Its value should be the color you want in the SDK If true, labels and buttons inside SDK will be in black colour else it will be in white color UIColor e.g. for White, it should be R: 255, G: 255, B: 255 Bool Either "true" or "false" 12 PayTabs ios SDK Integration Guide Version 3.0

13 3.2 Sample Code The following steps show what is needed to be able to integrate your application with the SDK, 1. Create instance variable for PTFWInitialSetupViewController in your UIViewController 2. Implement events for initiating and closing SDK. (follow the sample app for the examples) 3. Initiate SDK on the relevant action e.g. it is being initiated on the tap of hit test button after some basic validations. 4. Call custom init static function of PTFWIntialSetupViewController with the values and by keeping the above mentioned notes in consideration. 13 PayTabs ios SDK Integration Guide Version 3.0

14 3.3 SDK Response Implement two callbacks, didreceivebackbuttoncallback and didreceivefinishtransactioncallback to close the SDK and handle the SDK response respectively. The callback, didreceivefinishtransactioncallback contains seven values in the response after the transaction is processed: 14 PayTabs ios SDK Integration Guide Version 3.0

15 Value Variable Description Response Code responsecode Response code of the transaction. Result result Result or description of the transaction. Transaction ID transactionid Transaction identifier for tracking the transactions. Tokenized tokenizedcustomere mail address which has been tokenized if tokenization is enabled for future use. Tokenized Password tokenizedcustomerpa ssword Password which has been tokenized if tokenization is enabled for future use. Transaction State transactionstate State of the transaction, either true or false. Token token Token which is returned for future transactions. The possible values for the response code variable are as follows: Error Code Description 100 Payment is completed Successfully. This transaction may be suspicious, your bank holds for further confirmation. Payment Provider has rejected this transaction due to suspicious activity; Your bank will reverse the dedicated amount to your card as per their policy. 481 Important Note: These transactions are rejected by our fraud monitoring tools; however the transactions are only authorized (Not settled). In case you verify the transaction is genuine you can contact us to force accept the transaction after checking if it is not fraud and we might ask verification documents like ID card and front side of credit card used showing only name and last 4 digits, otherwise the transaction amount will be released back to the cardholder according to the issuing bank policy. In case you are using IPN, it will post the response once the transaction is force Accepted from our side 15 PayTabs ios SDK Integration Guide Version 3.0

16 Any other response code Any other response means that the transaction has been rejected and the rejection reason is the description of the corresponding response code ** The Complete list of response codes and their description can be found in Merchant Dashboard > Help > Reason Codes 3.4 Language Configuration In sdklanguage you can set the language preference. For Arabic, it will be ar and for English, it will be en. By default, it will be en. Currently PayTabs_SDK has only two languages English ( en ) Arabic ( ar ) 3.5 Important Notes 1 This ios SDK will not work on simulator devices. 2 There should be no spaces preceding or succeeding your Secret Key. 3 Merchant and Secret Key both should belong to the same merchant. 4. Verify Transaction This method verifies the result of the payment. When a payment is processed, you will receive transaction id in the response. When the customer completes a payment and is redirected back to your app, the transaction_id is used to verify the status of the payment whether it is a successful transaction or a failed transaction. PATH REQUEST METHOD PRODUCTION 4.1 Request POST LIVE Element Description Format merchant_ Merchant that you use to sign up and/or login into PayTabs Merchant Dashboard Up to128 characters E.g.: foof@foo.com 16 PayTabs ios SDK Integration Guide Version 3.0

17 secret_key transaction_id order_id SECRET Key generated by merchant dashboard This is the transaction_id that is returned in the response of the payment. Optional This is the order id from your system, you can use that instead of transaction_id parameter Up to128 characters E.g.: Mao8sdhasfyahosdap9sd Up to 12 characters E.g.: E.g.: Response Element Description Format result response_code pt_invoice_id The string representation for result, whether transaction has succeeded or failed and the reason why your transaction failed. The response code / error code of the API call. Complete list of response codes can be found in Merchant Dashboard > Help > Reason Codes The invoice/paypage ID of the transaction, this is available only for PayPage and API integration it will be null in case of mobile SDKS transactions E.g.: Payment is completed. Up to 4 characters E.g.: 4002 Up to 12 characters E.g.: null amount The transaction amount. Up to 3 Decimal places E.g.: currency The currency of the transaction amount. 3 character ISO country code E.g.: BHR transaction_id The ID of the latest transaction that occurred for this invoice Up to 12 characters E.g.: order_id This is the order id from your system. E.g.: 4578 card_last_four_digits This is the last four digits of the credit card used in the transaction E.g.: PayTabs ios SDK Integration Guide Version 3.0

18 4.3 Response Codes Error Code Description 4001 Missing parameters 4002 Invalid Credentials 4003 There are no transactions available You don t have permissions 100 Payment is completed Successfully. 481 ** This transaction may be suspicious, your bank holds for further confirmation. Payment Provider has rejected this transaction due to suspicious activity; Your bank will reverse the dedicated amount to your card as per their policy. Important Note: These transactions are rejected by our fraud monitoring tools; however the transactions are only authorized (Not settled). In case you verify the transaction is genuine you can contact us to force accept the transaction after checking if it is not fraud and we might ask verification documents like ID card and front side of credit card used showing only name and last 4 digits, otherwise the transaction amount will be released back to the cardholder according to the issuing bank policy. In case you are using IPN, it will post the response once the transaction is force Accepted from our side The Complete list of response codes can be found in Merchant Dashboard > Help > Reason Codes 5. PayTabs IPN (Instant Payment Notification) 5.1 How IPN Works When a customer makes a payment on the mobile SDK, the transaction is processed by PayTabs and a confirmation is sent back to the customer on the merchant s application. Additionally, a notification will be sent to the merchant. This scenario, leave no scope for any related ERP or E-commerce or Accounting Systems to be updated. This is where IPN comes in. As soon as a transaction is created or altered, PayTabs IPN will instantly send a notification to the merchant s specified IPN Listener URL, which can have any code that will assist in updating ERP or dependent systems. Alternatively, the merchant may wish to save this information in his local database. 18 PayTabs ios SDK Integration Guide Version 3.0

19 5.2 Set up your IPN Listener 1. Create an IPN Listener that receives and processes the IPN messages sent by PayTabs. 2. Log into your PayTabs Merchant Account > Go to My Profile and click on Edit. 3. Enter the URL of your IPN Listener and click on Submit. IPN will not work with a local host IPN Listener URL. Testing the IPN Message Service is only possible on a publicly hosted URL. Now your IPN Service is ready to go! 5.3 IPN Events Your listener will be triggered on the following events: 1. Successful Transaction 2. Rejected Transaction 3. Transaction, Force Accepted by PayTabs 4. Refunded Transaction 19 PayTabs ios SDK Integration Guide Version 3.0

20 5.4 Contents / Data of the IPN The Instant Payment Notification will return the following information depending on the type of event that has occurred. Element Description Format transaction_id PayTabs Transaction ID E.g.: order_id response_code Merchant s Website order ID, this the same as reference_no value posted in Create PayPage call The same as response _code value returned in the response of verify_payment API call. A complete list of response codes can be found in Merchant Dashboard > Help > Reason Codes Up to 12 characters E.g.: Up to 4 characters E.g.: 100, 481 customer_name Name of the Customer E.g.: John customer_ of the customer E.g.:customer@domain.com transaction_amount The transaction amount. Up to 3 Decimal places E.g.: transaction_currency The currency of the amount stated. 3 character ISO currency code E.g.: BHD customer_phone Phone number of the customer Minimum 6 numbers up to 32 numbers E.g.: last_4_digits The last 4 digits of the credit card number used in the transaction. E.g.: 6908 first_4_digits The first 4 digits of the credit card number used in the transaction. E.g.: PayTabs ios SDK Integration Guide Version 3.0

21 card_brand The card brand of the credit card used in the transaction. E.g.: MasterCard datetime Date/Time of the transaction This value is returned in case of rejected or approved transactions dd-mm-yyyy hh:mm:ss :25:26 PM shipping_address Shipping address of the customer 64 characters E.g.: Flat abc road 123 shipping_city Shipping City of the customer E.g.: Manama shipping_country Shipping country of the customer 3 character ISO country code E.g.: BHR shipping_state Shipping State of the customer E.g.: Manama shipping_postalcode Shipping postal code of the customer Up to 9 characters E.g.: amount The transaction amount. Up to 3 Decimal places E.g.: currency The currency of the amount stated. 3 character ISO currency code E.g.: BHD detail force_accept_datetime refund_req_amount The string representation for the result, whether the transaction has succeeded or failed and the reason why your transaction failed. Optional Date/Time of when the transaction is force accepted. This value is returned instead of DateTime value for transactions when they are force accepted only Optional The refunded amount for an E.g.: Payment is completed. dd-mm-yyyy hh:mm:ss :25:26 PM Up to 3 Decimal places 21 PayTabs ios SDK Integration Guide Version 3.0

22 approved refund request. E.g.: This value is returned once a refund request for a transaction is approved secure_sign A secure sign key in order for the merchant to validate if the payment is returning from PayTabs This value is returned in case of force accepted or rejected transactions only transaction_response_code The same as response _code value returned in the response of verify_payment API call. A complete list of response codes can be found in Merchant Alphanumeric E.g.:1f074e6f8b61d4f0af30 42ce118e82535f8cb447 Up to 4 characters E.g.: 100, 481 Dashboard > Help > Reason Codes refund_request_id PayTabs Refund request ID E.g.: refund_reason Reason for request by merchant Eg : Test Refund 5.5 Response Codes Response Code Description 100 Payment has been accepted successfully 481 or 482 Transaction rejected by fraud monitoring tools. These transactions can be force accepted upon merchant s request 5002 Payment has been forcefully accepted 5003 Payment has been refunded 5004 Your refund request has been rejected 5.6 Sample IPN Response IPN sample response for successful SDK transactions Array ( [transaction_id] => [order_id] => [response_code] => 100 [customer_name] => John Doe 22 PayTabs ios SDK Integration Guide Version 3.0

23 ) [customer_ ] => [transaction_amount] => 1.00 [transaction_currency] => USD [customer_phone] => [last_4_digits] => 1111 [first_4_digits] => 4111 [card_brand] => Visa [datetime] => :21:19 PM [shipping_address] => Flat 1,Building 123, Road 2345 [shipping_city] => Juffair [shipping_country] => BHR [shipping_state] => Manama [shipping_postalcode] => [amount] => 1.00 [currency] => USD [detail] => Transaction has been Successful [transaction_response_code] =>100 [secure_sign] => 7ec0ac0890acbe33139efe989d32e97e061f93f IPN sample response for rejected SDK transactions Array ( ) [transaction_id] => [order_id] => [response_code] => 202 [customer_name] => John Doe [customer_ ] => John@gmail.com [transaction_amount] => 1.00 [transaction_currency] => USD [customer_phone] => [last_4_digits] => 1111 [first_4_digits] => 4111 [card_brand] => Visa [datetime] => :21:19 PM [shipping_address] => Flat 1,Building 123, Road 2345 [shipping_city] => Juffair [shipping_country] => BHR [shipping_state] => Manama [shipping_postalcode] => [amount] => 1.00 [currency] => USD [detail] => An expired card has been used in this transaction [transaction_response_code] =>202 [secure_sign] => 7ec0ac0890acbe33139efe989d32e97e061f93f4 23 PayTabs ios SDK Integration Guide Version 3.0

24 5.6.3 IPN sample response for rejected SDK transactions by fraud monitoring Array ( ) [transaction_id] => [order_id] => [response_code] => 481 [customer_name] => John Doe [customer_ ] => John@gmail.com [transaction_amount] => 1.00 [transaction_currency] => USD [customer_phone] => [last_4_digits] => 1111 [first_4_digits] => 4111 [card_brand] => Visa [datetime] => :21:19 PM [shipping_address] => Flat 1, Building 123, Road 2345 [shipping_city] => Juffair [shipping_country] => BHR [shipping_state] => Manama [shipping_postalcode] => [amount] => 1.00 [currency] => USD [detail] => This transaction may be suspicious, your bank holds for further confirmation. Payment Provider has rejected this transaction due to suspicious activity; your bank will reverse the dedicated amount to your card as per their policy. [transaction_response_code] =>481 [secure_sign] => 7ec0ac0890acbe33139efe989d32e97e061f93f IPN sample response for force accepted SDK transactions Array ( ) [transaction_id] => [order_id] => 25 [response_code] => 5002 [customer_name] => John Doe [customer_ ] => john@ .com [transaction_amount] => 1.00 [transaction_currency] => USD [customer_phone] => [last_4_digits] => 1111 [first_4_digits] => 4111 [card_brand] => Visa [secure_sign] => 7ec0ac0890acbe33139efe989d32e97e061f93f4 [force_accept_datetime] => :01:40 PM [transaction_response_code] => PayTabs ios SDK Integration Guide Version 3.0

25 5.6.5 IPN sample response for refunded SDK transactions Array ( ) [refund_request_id] =>21741 [refund reason] => test [transaction_id] => [order_id] => 25 [response_code] => 5003 [customer_name] => John Doe [customer_ ] => john@ .com [transaction_amount] => [transaction_currency] => USD [customer_phone] => [last_4_digits] => 1111 [first_4_digits] => 4111 [card_brand] => Visa [secure_sign] => 7ec0ac0890acbe33139efe989d32e97e061f93f4 [refund_req_amount] => 50 [transaction_response_code] => Refund Transactions This method enables you to submit the refund requests using the below API function. Refund requests will be processed in around 24 hours and if you are using IPN service the IPN will post a response once the refund request is approved or rejected. Partial refunds are available. You can submit a single refund request for the whole amount of Multiple Partial refunds for the same transactions. However, if your refund for a certain transaction is still pending for approval, you can t submit a second refund request for the same transaction. All refund requests submitted using the API is also available at the Merchant Dashboard. Note: This feature is also available from Merchant Dashboard > Bank Account > Refunds Note: This API can be used by Active accounts only; it s not available for Demo merchants PATH REQUEST METHOD PRODUCTION POST LIVE 6.1 Request Element Description Format 25 PayTabs ios SDK Integration Guide Version 3.0

26 merchant_ secret_key Merchant that you use to sign up and/or login into PayTabs Merchant Dashboard SECRET Key can be found at merchant dashboard Up to128 characters E.g.: Up to128 characters E.g.: Mao8sdhasfyahosdap9sd transaction_id order_id refund_amount Optional The transaction id of the successful payment that you wish to refund This is the pt_transaction_id that is returned in the SDK response of the payment. Optional The order id of the payment from your system You can either use this or use the transaction_id The amount you wish to refund, it can either be partial amount or full amount Up to 12 characters E.g.: Up to E.g.: 4578 Up to 3 Decimal places E.g.: refund_reason The reason for refunding the transaction Up to 256 Characters 6.2 Response Element Description Format result The string representation for result, whether transaction has succeeded or failed and the reason why your transaction failed. E.g.: Payment is completed. response_code The response code / error code of the API call. Complete list of response codes can be found in Merchant Dashboard > Help > Reason Codes Up to 4 characters E.g.: PayTabs ios SDK Integration Guide Version 3.0

27 6.3 Response Codes Error Code Description 4001 Missing parameters 4002 Invalid Credentials 810 You already requested Refund for this Transaction ID 811 Refund amount you requested is greater than transaction amount 812 Refund request is sent to Operation for Approval. You can track the Status on Merchant Dashboard 813 You are not authorized to view this transaction 814 Refund request is processed. 7. Transactions Reports This API call will post all transactions that have taken place within the specified time interval to a URL. Before calling this API, you will need to set the listener URL for the reports. Login to your merchant dashboard and edit your profile. Set up your IPN Listener 1. Create an IPN Listener that receives and processes the IPN messages sent by PayTabs. 2. Log into your PayTabs Merchant Account > Go to My Profile and click on Edit. 3. Enter the URL of your IPN Listener In the IPN Listener for Transactions Reports and click on Submit. IPN will not work with a local host IPN Listener URL. Testing the IPN Message Service is only possible on a publicly hosted URL. Once you call the transaction_reports API, all the transactions will be posted to the listener URL and the response will be contain the number of transactions that will be posted. 27 PayTabs ios SDK Integration Guide Version 3.0

28 PATH REQUEST METHOD PRODUCTION 7.1 Request POST LIVE Element Description Format merchant_id secret_key startdate enddate Merchant id as in merchant dashboard Secret Key is generated from merchant Dashboard. Start Date Format should be yyyy-mm-dd End Date Format should be yyyy-mm-dd E.g.: E.g.: Mao8sdhasfyahosdap9sd E.g.: E.g.: Response Element Description Format response_code transaction_count details status The response code of the API call The total number of transactions. The details of all the retrieved transactions Payment Status E.g.: 4001, 4090,4091 E.g.: 23 Details of the transaction E.g.: Approved/ Rejected Refunded / Force Accepted response_code Payment Result Response Code 100 for successful/ E.g.: PayTabs ios SDK Integration Guide Version 3.0

29 transaction_id order_id refunded payment 481: DM declined/ Force Accepted Payment other: Rejected PayTabs Transaction ID Merchant s Website order ID E.g.: E.g.: 1234 auth_code Authorization Code E.g.:AhjzbwSR8VsHlol4QVCEcgSegdUxd transaction_title Title of the transaction Eg : new transaction amount currency net_amount net_amount_currency net_amount_credited Transaction Amount Transaction Currency The equivalent of the original amount converted to merchant dashboard Currency Merchant Dashboard Currency Net Amount Credit to Merchant s Balance after deducting PayTabs fees E.g.: Character ISO country Code E.g.: AED E.g.: Character ISO country Code E.g.: AED E.g.: PayTabs ios SDK Integration Guide Version 3.0

30 net_amount_credited_currency transaction_datetime force_accept_datetime Merchant Dashboard Currency Date and time of the transaction Date and time of force accept (If applicable) 3 Character ISO country Code E.g.: AED E.g.: :39:16 pm E.g.: :39:16 am 7.3 Error Codes Error Code Description 4001 Missing parameters 4002 Invalid Credentials 4090 Data Found 4091 No Data 8 Tokenization in SDK The Tokenization feature gives you the option to create tokenization profiles to save credit card information for returning customers to your website. Please Note: Tokenization feature is not available for merchants registered or operating in the Kingdom of Saudi Arabia. 30 PayTabs ios SDK Integration Guide Version 3.0

31 In order to use tokenization in the SDK, you will need to pass additional parameters in the method. This will result in the creation of a normal Payment request, where the customer has to perform and authorize the first payment and receive the token for the credit card details that he has entered. The following parameters have to be added to the creation of payment request in order to create a token for the customer. Element Description Format andistokenization Set this value as true if you wish to create token for customer Bool either TRUE or FALSE 8.1 Sample Code To create a new token andistokenization: self.launcherview.tokenizationswitch.ison To use existing token which have been previously created, use the Rest API, prepare_transaction 31 PayTabs ios SDK Integration Guide Version 3.0

32 (refer API documentation). 9 Process Payment with Existing Token This method uses an existing token for a returning customer to process payment. You will need to pass the details (token, customer and customer password) of the token that you previously created in order to perform a transaction. PATH REQUEST METHOD PRODUCTION POST LIVE 9.1 Request You need to pass all the parameters as stated below: Element Description Format merchant_ secret_key title cc_first_name cc_last_name order_id product_name customer_ phone_number Merchant id used to login into PayTabs Merchant Dashboard. SECRET Key generated by merchant dashboard Description or title of the transaction done by the customer First Name of the Customer Last Name of the Customer Merchant s Website order ID, this is same as the reference_no value Product title of the product. of the customer Phone Number of the Customer E.g.: testing@test.com E.g.: Mao8sdhasfyahosdap9sd E.g.: Order # 3321 E.g.: John E.g.: Doe E.g.: Dx characters E.g.: SamsungS5 E.g.: customer@domain.com E.g.: PayTabs ios SDK Integration Guide Version 3.0

33 amount currency address_billing state_billing *** city_billing postal_code_billing country_billing address_shipping** city_shipping state_shipping *** postal_code_shipping Amount of the products and other charges, it should be equal to: amount = (sum of all products (unit_price * quantity)) + other_charges This field will be displayed in the invoice as the sub total field Currency of the amount stated. 3 character ISO currency code Complete Address of the customer. Multiple address lines will be merged into one single line. Billing State (part of the address) entered by the customer Name of the billing city selected by customer Billing Postal code provided by the customer Country of the customer Shipping address of the customer Shipping City of the customer Shipping State of the customer Shipping postal code of the customer Float Up to 3 Decimal places E.g.: E.g.: BHD 64 characters E.g.: Flat 11 Building 222 Block 333 Road 444 Manama Bahrain E.g.: Manama E.g.: Manama Up to 9 characters E.g.: character ISO country code E.g.: BHR 64 characters E.g.: Flat abc road 123 E.g.: Manama E.g.: Manama Up to 9 characters E.g.: PayTabs ios SDK Integration Guide Version 3.0

34 country_shipping pt_token pt_customer_ pt_customer_password Shipping country of the customer This pt_token is received in the API post response after completing the payment; it will be redirected to return_url. While returning back to that URL, it will send a POST request to that page The customer linked to the tokenization profile used, by default when the profile is created at the first successful payment, it will use customer_ value sent in the API to link it to the token This pt_ customer_password is received in the API post response after completing the payment; it will be redirected to return_url. While returning back to that URL, it will send a POST request to that page. 3 character ISO country code E.g.: BHR E.g.: R7ANsPK1q91fv5QObmQ3 E.g.: customer@domain.com E.g.: 1q91fv5QOb * The API requires that the requesting website be exactly the same as the website/url associated with your PayTabs Merchant Account. The merchant can see this SITE URL on his dashboard, under My Profile For Demo Users: You can edit your site URL by clicking going to My Profile and clicking on edit, enter your correct site URL and click on Save. For Live Merchants: You can use the website that you have submitted in the Go-Live application. If you need to edit/change the site URL, you can send a request to customercare@paytabs.com 34 PayTabs ios SDK Integration Guide Version 3.0

35 9.2 Response Element Description Format result response_code The string representation for result, whether transaction has succeeded or failed and the reason why your transaction failed. The response code / error code of the API call. Complete list of response codes can be found in Merchant Dashboard > Help > Reason Codes E.g.: Approved Up to 4 characters E.g.: 4002 transaction_id Transaction id of the token transaction. Up to 12 characters E.g.: Response Codes Code Any response code other than 100, 481, 482 Description Missing parameters Invalid Credentials You don t have permissions Invalid tokenization Credentials There are no transactions available. Payment is completed. This transaction may be suspicious. If this transaction is genuine, please contact PayTabs customer service to enquire about the feasibility of processing this transaction. Any other response than 100, 482, 481 means that the transaction has been rejected and the rejection reason is the description of the corresponding response code 35 PayTabs ios SDK Integration Guide Version 3.0

36 10 Test Credit Card Numbers To test your payment process, you can typically use any valid credit card number or you can use the ones listed below. Please do not use test cards in a live environment. This will cause your transactions to be rejected. Card Number Card Type Description CVV Expiry Date VISA VISA VISA MasterCard MasterCard MasterCard Without authentication window With authentication window (3D secure) Card enrollment option during purchase process With authentication window (3D secure) Without authentication window Card enrollment option during purchase process / / / / / /22 11 Screenshots of the application 11.1 PayTabs Mobile Payment Page The customer will be redirected to PayTabs payment page to enter the card details which will show as follows. 36 PayTabs ios SDK Integration Guide Version 3.0

37 The payment page will display the Logo you submitted at your PayTabs Merchant Account on the top left of the page and the Store Name submitted at your PayTabs Merchant Account on the top right. The required card information will be: o Card Number o Card Holder Name o Expiration Date (mm/yy) o CVV (Card Verification Code) 11.2 Successful Payment Result Page Once the customer submits the card information to process the payment, if the payment is successful, the customer will be redirected to the Successful result page that will return the successful transaction ID to the customer.. 37 PayTabs ios SDK Integration Guide Version 3.0

38 11.3 Unsuccessful Payment Result Page Once the customer submits the card information to process the payment, if the payment is unsuccessful, the customer will be redirected to the Unsuccessful result page. 38 PayTabs ios SDK Integration Guide Version 3.0

39 12 Frequently Asked Questions Q1. PayTabs ios SDK is not working on actual ios devices lesser than iphone 5S! Our SDK supports armv7, armv7s and arm 64. Q2. How do I get the response code from the ios SDK? To view transaction_id and response codes please add the following code in your application. NSLog(@"transaction Id %@", [[NSUserDefaults standarduserdefaults] objectforkey:@"pt_transaction_id"]); NSLog(@"Response Code %@", [[NSUserDefaults standarduserdefaults] objectforkey:@"pt_response_code"]); NSLog(@"Description %@", [[NSUserDefaults standarduserdefaults] objectforkey:@"pt_description"]); The possible values for the response code variable are as follows: Error Code Description 100 Payment is completed Successfully. This transaction may be suspicious, your bank holds for further confirmation. Payment Provider has rejected this transaction due to suspicious activity; Your bank will reverse the dedicated amount to your card as per their policy. 481 Any other response code Important Note: These transactions are rejected by our fraud monitoring tools; however the transactions are only authorized (Not settled). In case you verify the transaction is genuine you can contact us to force accept the transaction after checking if it is not fraud and we might ask verification documents like ID card and front side of credit card used showing only name and last 4 digits, otherwise the transaction amount will be released back to the cardholder according to the issuing bank policy. In case you are using IPN, it will post the response once the transaction is force Accepted from our side Any other response means that the transaction has been rejected and the rejection reason is the description of the corresponding response code ** The Complete list of response codes and their description can be found in Merchant Dashboard > Help > Reason Codes Q3. Is the IOS SDK compatible with Swift? We have an SDK specifically for Swift. 39 PayTabs ios SDK Integration Guide Version 3.0

40 Q4. Can I use the ios SDK in my hybrid framework like Cordova, Sencha, Titanium, Ionic? Unfortunately, our ios SDK does not support hybrid frameworks. Q5. Does your ios SDK work on simulators? No, it does not. You can test your SDK integration on actual devices only. Q6. How can I get the product names from Verify Payment API & IPN response from SDK? The product names can be stored in your database against your own invoice id/reference id/order Id. Once the payment is made, we will send the same id back to your server in the verify_payment / IPN response. You can then compare the IDs and retrieve the product names from your own database. Q7. May I know from which ios version it will work? The SDK is compatible with ios version 8,9,10. Q8. How can I remove the default card details/entries in the ios SDK? You can remove the default card details by replacing the files as given below to remove the default entries PayTabsViewController_iPhone.xib PayTabsViewControllerWideScreen.xib Q9. Why is the design of the 3DS page not centralized on the screen? This screen is coming directly from the bank. So the control over this page is very limited. We have added a scroll bar so that users will be able to scroll the page. Q10. During payment, the app waits on a page for a long time before proceeding to the next step. Can we add a loading image here? The loader has been added to the LIVE library only due to some restrictions in the test environment. So once you are LIVE you will be able to see the loader. Q11. While testing on test account, some credit card transactions seem to have an issue the loader keeps on loading. How can we fix this? On test environment, we have some limitations on amounts such as 6, 60, 66 etc. Kindly attempt different amounts that do not contain the digit 6. Q12. How can we test refund transactions in both Android and ios. Is there any way to test with one test card? Refund requests cannot be submitted for demo transactions. You will need to refund request for a LIVE transaction but kindly limit the same to 1 or 2 transactions. 40 PayTabs ios SDK Integration Guide Version 3.0

41 PayTabs ios SDK Version PayTabs ios SDK Integration Guide Version 3.0