Smart Phone API Integration Guide

Smart Phone API Integration Guide Version 1.2 Jan 2014

Table of Contents About this Guide...3 Introduction...4 How does CashFlows work?...4 CashFlows Smart Phone API...4 Security Requirements...4 Submitting a Payment Request...5 Payment Request parameters...5 Example of a Payment Request...6 Submitting a VoicePay Payment Request...6 VoicePay Payment Request parameters...6 Example of a VoicePay Payment Request...7 Authorisation Request Response...8 CVV/AVS check values...8 VoicePay Request Response...8 Example of a response object...9 Testing and Verifying your Integration... 10 Verification of you Mobile App... 10 Appendix A: Payment System Response Codes... 11 Smart phone API Integration Guide Version 1.2 Jan 2014 2

About this Guide Welcome to the CashFlows Smart Phone API Integration Guide. This document is designed to provide you details on how to integrate your Mobile app into the CashFlows payment processing system and optionally take advantage of our m-commerce voice signature technology. This document assumes a working knowledge of HTTP(S), Objective C, Java or C++. Your will also need to become familiar with some of the restriction of the Payment Application Data Security Standards (PA-DSS) around the store and transferring or card details. In addition to this guide we have a team of specialists providing technical support during your integration with CashFlows. To receive support please visit our website - http://www.cashflows.com/support Copyright 2014 Voice Commerce Group While every effort has been made to ensure the accuracy of the information contained in this publication, the information is supplied without representation or warranty of any kind, is subject to change without notice and does not represent a commitment on the part of Voice Commerce Group. Voice Commerce Group, therefore, assumes no responsibility and shall have no liability, consequential or otherwise, of any kind arising from this material or any part thereof, or any supplementary materials subsequently issued by Voice Commerce Group. Voice Commerce Group has made every effort to ensure the accuracy of this material. Smart phone API Integration Guide Version 1.2 Jan 2014 3

Introduction Cashflows delivers a range of business to business financial services that are provided from a single account, designed to help businesses manage and maximise their cash flow. The CashFlows account enables businesses to offer their customers a full range of payment channels including, online, mobile and mail & telephone orders. The Cashflows account is fully integrated into the VoicePay m-commerce service which delivers guaranteed transactions. How does CashFlows work? 1. A consumer selects a product or a service to purchase from a merchant s mobile app store. 2. The consumer s payment card details are entered via the mobile app. 3. The payment card details are sent by us via the card schemes network to the consumer s card issuing bank for authorisation. 4. The card issuer checks the card details, that the cardholder's account has sufficient funds and that the card hasn't been reported lost or stolen. If everything is OK, the issuing bank authorise the amount requested and debits those funds from the consumers payment card account. 5. The authorisation results are returned to mobile app confirming the result of the transaction. 6. We receive the funds from the card schemes network and then remit them into merchant s bank account. CashFlows Smart Phone API The CashFlows Smart Phone API is a mechanism that allows you to collect cardholder and transaction details within your app and to submit them directly to CashFlows for processing. Security Requirements Using the Smart Phone API model to send payment data means that you will be capturing, transmitting, and possibly storing card data. The Card Schemes, Visa Europe and MasterCard International, have never permitted the storage of sensitive data (track data and/or CVV2) post-authorisation, and it is prohibited under the Payment Application Data Security Standard (PA-DSS). Merchants who store Sensitive Authentication Data (SAD) are being fined by the Card Schemes. Consequently, if you use the Smart Phone API model within a mobile app you understand the responsibility of handling this data securely and take full responsibility for its PA-DSS compliance. For further information on PCI security standard, please visit https://www.pcisecuritystandards.org/documents/pa-dss_v2.pdf Smart phone API Integration Guide Version 1.2 Jan 2014 4

Submitting a Payment Request The payment request takes the form of a HTTPS POST request containing a description of the goods or services being purchased, the total cost, your CashFlows profile Id and the credit card and cardholder details of the consumer. The POST request must be UTF-8 encoded and submitted to: https://secure.cashflows.com/gateway/remote_auth If the purchase consists of more than one item, your shopping cart system must total all the items into a single description and total cost and submit a single combined payment request. Payment Request parameters The following table lists the parameters that can be passed to the Smart Phone API to request a payment authorisation. Note: All payment request parameters are mandatory unless specified. Parameter auth_id auth_pass card_num card_cvv card_start card_issue card_expiry cust_name cust_address cust_postcode cust_country cust_ip cust_email cust_tel tran_ref tran_desc tran_amount tran_currency tran_testmode tran_type tran_class Description Your Profile Id Authentication password Customer s card number. (Must be numeric only with no separators.) Card security code. Card start date. Format is MMYY. (Optional) Card issue number. (Optional) Card expiry date, format is MMYY Customer s name Customer s address (Multiple lines can be separated using the new line break character (ASCII code 10)) Customer s post/zip/area code Customer s country (ISO3166 2 character code) Customer s IP address Customer s email address Customer s telephone number Your transaction reference (e.g. cart ID) Your transaction description (Max of 99 characters) (Optional) Transaction amount to 2 decimal places, e.g. 24.99. (The currency symbol must not be included.) Transaction currency, 3 character code. Transaction test mode. 0=Live, 1=Test Transaction type = Sale Transaction class = ecom Smart phone API Integration Guide Version 1.2 Jan 2014 5

Example of a Payment Request You can submit a POST request using a range of different mobile app programming languages, below is an example of how to submit a payment request using Objective C for the iphone: NSURL *orequesturl = [NSURL URLWithString:@" https://secure.cashflows.com/gateway/remote "]; NSMutableURLRequest *orequest = [[[NSMutableURLRequest alloc] init] autorelease]; [orequest setvalue:@"text/plain" forhttpheaderfield:@"content-type"]; [orequest sethttpmethod:@"post"]; [orequest seturl:orequesturl]; NSMutable ohttpbody = [NSMutableData data]; [ohttpbody appenddata:[@" auth_id=1234&auth_pass=password&card_num=4000000000000002&card_cvv=123&card_expiry=0116&c ust_name=testing&cust_address=my%20house%0amy%20street%0amy%20town&cust_postcode=cb22 %205LD&cust_country=GB&cust_ip=123.45.67.89&cust_email=test@test.com&tran_ref=abc123&tran_amo unt=9.99&tran_currency=gbp&tran_testmode=0&tran_type=sale&tran_class=ecom" datausingencoding:nsutf8stringencoding]]; [orequest setvalue:[ohttpbody length] forhttpheaderfield:@"content-length"]; The above example will send the following payment details to the Smart Phone API for authorisation. auth_id=1234&auth_pass=password&card_num=4000000000000002&card_cvv=123&card_expiry=0116&c ust_name=testing&cust_address=my%20house%0amy%20street%0amy%20town&cust_postcode=cb22 %205LD&cust_country=GB&cust_ip=123.45.67.89&cust_email=test@test.com&tran_ref=abc123&tran_amo unt=9.99&tran_currency=gbp&tran_testmode=0&tran_type=sale&tran_class=ecom Submitting a VoicePay Payment Request To submit a payment request to our VoicePay m-commerce facility you will be send a HTTPS POST request containing the email and mobile phone number of the VoicePay registered customer to be verified. The POST request must be UTF-8 encoded and submitted to: https://secure.voice-pay.com/gateway/remote_ivr VoicePay Payment Request parameters The following table lists the parameters that can be passed to the Smart Phone API to request a payment authorisation. Note: All VoicePay payment request parameters are mandatory. Parameter Description auth_id auth_pass cust_mobile cust_ip cust_email Your Profile Id Authentication password The VoicePay registered customer s mobile number in full international MSISDN format (i.e. prefix 00.) Customer s IP address Customer s email address Smart phone API Integration Guide Version 1.2 Jan 2014 6

tran_ref tran_desc tran_amount tran_currency tran_type Your transaction reference (e.g. cart ID) Your transaction description Transaction amount to 2 decimal places, e.g. 24.99. (The currency symbol must not be included.) Transaction currency, 3 character code. (For a list of currency that you can accept please contact support@cashflows.com) Transaction type = payment Example of a VoicePay Payment Request Example of the POST string sent in the VoicePay payment request to the Smart Phone API for authorisation. cust_mobile=00971501234567&cust_ip=80.227.148.106&cust_email=test@test.com&tran_ref=0000001&tra n_amount=5&tran_currency=usd&tran_desc=test-mobile-paymentrequest&auth_id=1234567&auth_pass=mypass&tran_type=payment Smart phone API Integration Guide Version 1.2 Jan 2014 7

Authorisation Request Response The response consists of the authorisation status code, transaction ID, CVV/AVS result, authorisation code and authorisation message. These fields are separated using the vertical bar character. An authorisation status of A indicates that the transaction was authorised, anything else indicates that it was not. Example Response A 01S00001724 232 031971 Authorised D 01S00001723 400 D102 Not Authorised V 01S00001722 000 V226 Invalid request B 01S00632BE2 000 D090 Not authorised Meaning Authorised: A Transaction Id: 01S00001724 CVV/AVS:232 Authorisation code: 031971 Not authorised: D Transaction Id: 01S00001723 CVV/AVS:400 Invalid request: V Transaction Id: 01S00001722 CVV/AVS:000 (please refer to Appendix A for further information.) Blocked: D Transaction Id: 01S00632BE2 CVV/AVS:000 (please refer to Appendix A for further information.) CVV/AVS check values The CVV/AVS result is a 3 digit value, each digit representing a different check. The first value is the CVV check, the second is the address and the third is the postcode. The possible values for each digit are as follows: Value Meaning 0 Not Checked 1 Check was not available 2 Full match 3 Partial match 4 Not matched 5 Error A partial match is only possible for the address or postcode data, not for CVV check. Not all acquirers or issuers support all of these checks, in which case the results will be either 0 or 1. Example Response CVV Address Postcode 232 Full match Partial match Full match 400 Not matched Not checked Not checked VoicePay Request Response Smart phone API Integration Guide Version 1.2 Jan 2014 8

The response you get when you send a VoicePay payment request consists of the authorisation status code, authorisation message, a transaction reference and the name and address details of the consumer who made the payment. An authorisation status of A indicates that the transaction was authorised, anything else indicates that it was not. Example Response auth_status=a auth_message=authorised auth_code=04516 tran_ref=01s01234567 cust_name=fred Smith cust_address=the house, The street, The town cust_postcode=abc123 cust_country=uk auth_status=d auth_message=not authorised auth_code=d101 tran_ref=01s01234567 auth_status=v auth_message=user details not valid Meaning Voice Signature successfully verified Transaction successfully authorised Transaction reference supplied Consumer details supplied Voice Signature unsuccessfully verified Transaction unsuccessful authorised Transaction reference supplied User detail not valid Example of a response object The following example shows how you will need to create a response object to receive the data of the authorisation request response. The example below again uses Objective C for the iphone: NSError *oerror = [[NSError alloc] init]; NSHTTPURLResponse *oresponsecode = nil; NSData *oresponsedata = [NSURLConnection sendsynchronousrequest:orequest returningresponse:oresponsecode error:oerror]; If ([oresponsecode statuscode] >= 200) { NSLog(@"Status code is greater than 200"); } NSString * strresult = [[NSString alloc] initwithdata:oresponsedata encoding:nsutf8stringencoding]; Smart phone API Integration Guide Version 1.2 Jan 2014 9

Testing and Verifying your Integration You can test your integration to our Smart Phone API by setting your POST request to test mode. To send a test payment request you will need to set tran_testmode=1 and enter a valid Visa test card number as show below: Card Number Expiry Date CVV 4000000000000002 (VISA) Any valid expiry date (mm/yy) 123 4462030000000000 (VISA prepaid) Any valid expiry date (mm/yy) 444 5555555555554444 (MasterCard) Any valid expiry date (mm/yy) 321 5597507644910558 (MasterCard prepaid) Any valid expiry date (mm/yy) 888 Warning: Test card numbers will only work when the payment request is in test mode, if used in live mode the test will be subject to a payment authorisation charge. Verification of you Mobile App To verify that your Mobile App integration works fully with our payment gateway, please contact our technical support team at: support@cashflows.com. Our technical support team will then test your Mobile App and configure your account to allow mobile app transactions. When we are satisfied that you Mobile App fulfils our integration and PA-DSS requirements we will issue you with a certificate of compliance. Smart phone API Integration Guide Version 1.2 Jan 2014 10

Appendix A: Payment System Response Codes Status 'A' is authorised, anything else is not. The auth code and auth message for authorised transactions cannot be predicted (as they can change from one bank/issuer to the next). 'V' is a validation error (e.g. invalid card number) 'D' is a decline 'R' is a referral (has to be treated as a decline) B is a blocked transaction 'C' is a cancelled transaction (e.g. user pressed cancel on payment page) 'S' is a system error These will be followed by a 3 digit code, the first digit is an internal code which can be ignored. The second two digits are the actual error code for the given status. Attached is a list of the current error codes. (Please note this list is subject to change). The list is given as, for example, Vx01 which means it is the result for V101, V201, V301 etc. Code Vx01 Vx02 Vx03 Vx04 Vx05 Vx06 Vx07 Vx08 Vx09 Vx10 Vx11 Vx12 Vx13 Vx14 Vx15 Vx16 Vx17 Vx18 Vx19 Vx20 Vx21 Vx22 Vx23 Vx24 Vx25 Vx26 Vx27 Vx28 Vx29 Vx30 Vx31 Vx32 Vx33 Vx34 Vx35 Vx36 Reason Invalid merchant details Invalid expiry date Invalid start date Invalid issue number Invalid CVV Invalid card number Card holder name not set Insufficient address details Invalid country code Invalid cart ID Invalid email address Invalid phone number Invalid amount Invalid currency code Invalid customer IP Original trans not found Invalid merchant IP Unknown transaction type Card number changed Currency changed Original trans ref required Amount exceeds original Can not refund this type of transaction Amount changed User account details required Invalid request Original trans not pre-auth Transaction mode changed Card/Currency combination not supported Unknown card type Issue number required Issue number not required Duplicate transaction Unable to void transaction Original trans was not authorised Invalid PIN Smart phone API Integration Guide Version 1.2 Jan 2014 11

Vx37 Vx38 Vx39 Vx40 Vx41 Vx42 Vx43 Vx44 Vx48 Vx52 Vx53 Vx54 Dx01 Dx02 Dx03 Dx04 Dx05 Dx06 Dx07 Dx08 Dx90 Dx91 Dx10 Rx01 Ex01 Cx01 Cx02 Sx00 Sx01 Sx02 Sx03 Sx04 Sx05 Sx06 Unknown transaction class Original transaction type does not match Card expired CVV Required Original transaction already settled Original transaction already cancelled This card does not support the required transaction type Transaction details do not match original User Details not valid (VoicePay) 3DS Not Enabled 3DS Data Invalid Concurrent Authorisations Non-specific decline Declined due to funds (insufficient/limit exceeded) Retain card response VoicePrint not matched On our blacklist IVR call failed Live/test mismatch Refund: Insufficient merchant funds in account Pre-Authorisation anti-fraud block Post-Authorisation anti-fraud block Card authorisation attempt limit reached Not Authorised Transaction error Transaction cancelled Transaction expired Invalid transaction Request Connection failure Invalid response Response timeout Server error Server error No response from issuer Smart phone API Integration Guide Version 1.2 Jan 2014 12