Server-to-Server Credit Card Implementation Guide

Transcription

1 Server-to-Server Credit Card Implementation Guide Merchant implementation instructions to integrate to the Setcom credit card processing platform. Covers: Fraud Screening, Verified by Visa, MasterCard SecureCode Integration, Card Authorisation, Settlement and Refund.

2 Setcom Server-to-Server Implementation Guide 2 Copyright and Trademark 2014 Setcom (Pty) Ltd. All Rights Reserved. Setcom and the Setcom logo are registered trademarks of Setcom (Pty) Ltd. Designated trademarks and brands are the property of their respective owners. Notice of Liability The information in this pack is distributed in an as is basis. All information provided in this document is provided with good will. The authors and publishers of this manual are not responsible for loss, or purported loss due to any contents of this publication.

3 Setcom Server-to-Server Implementation Guide 3 Summary of Revisions Version Date Changed By Changes Made January 2014 A. Shore Version 3 is created May 2014 V. Pestana August 2014 A. Vakalis General updates. Added Standard Bank / Absa different method. Small fixes. Updated Card Order Query.

4 Setcom Server-to-Server Implementation Guide 4 Contents Summary of Revisions... 3 Overview... 6 Merchant Requirements... 6 E-Commerce Merchant Account... 6 Valid SSL Certificate... 7 Verified by Visa and MasterCard SecureCode... 7 PCI-DSS (Payment Card Industry Data Security Standard)... 7 Merchant Admin Interface Commerce Manager... 8 Credit Card Settlement... 8 Credit Card Transaction Flow... 8 Open Source Modules... 9 Implementation... 9 Purchase Request... 9 Purchase Response... 9 Polling Your Transaction Status... 9 Remote Settlement and Refund Purchase Request Server URL Request Fields Consistent Field for Purchase Request Purchase Response FNB and Nedbank Merchants ABSA and Standard Bank Merchants Purchase Response for FNB and Nedbank Merchants Response OUTCOME Fields D Secure Handling Enrolled Responses Purchase Response for ABSA and Standard Bank Merchants Polling your Transaction Status Request Fields Sample XML Response String Response Fields Remote Settlement and Refund... 28

5 Setcom Server-to-Server Implementation Guide 5 Restrictions Request Format Response Format Response OUTCOME field Credit Card Fraud Screening Device Profiling for Fraud Screening Sample HTML Profiling Tags Testing Global Test Account Details Credit Card Test Details D Secure Testing Appendix A Error Codes Contact Information... 41

6 Setcom Server-to-Server Implementation Guide 6 Overview This document provides technical implementation instructions that will guide the merchant in integrating to the Setcom Server-to-Server platform. Before embarking on this implementation, please contact support@setcom.com to advise on your implementation selection and to ensure that the correct settings for Server-to-Server have been applied to your account. The following topics will be covered in this guide: 1. Processing credit cards. 2. Fraud screening. 3. Verified by Visa and MasterCard Secure Code integration. The Setcom Server-to-Server platform provides a solution for the merchant and developer to have full control over the payment process. The cardholder will not leave the merchant s website and developers are able to build their own API using a web server to communicate with Setcom s server. For more information on implementation requirements, please go to: Merchant Requirements E-Commerce Merchant Account Merchants need to apply for an E-Commerce Merchant Account with one of the following banks. ABSA First National Bank Standard Bank of South Africa Nedbank Setcom will assist where possible with the application process. The application process usually takes between 2 and 6 weeks to complete. Once the merchant account has been obtained, the merchant can process Visa and MasterCard transactions. In order to accept American Express and Diners cards, the merchant needs to contact these card institutions directly to apply for additional merchant facilities. Contact details are: American Express Merchant Department: Diners Merchant Department: Once the above institutions have issued you with merchant IDs, please submit them to both your bank and Setcom for loading.

7 Setcom Server-to-Server Implementation Guide 7 Valid SSL Certificate Merchants will need a valid SSL certificate in order to collect the card details on their website securely. A valid SSL certificate with a minimum key strength of 128 bits needs to be obtained by the merchant. Certificates can be obtained from VeriSign, Thawte, GoDaddy or any reputable certificate authority. Merchants will be responsible for all development, although Setcom will provide as much technical support as required. Communication via port 443 (SSL) on the merchant firewall needs to be allowed and configured. For security purposes the merchant can lock down outgoing SSL communication to the domain SSL version 2 is no longer supported by Setcom and we will only use SSL version 3 with high encryption ciphers. Verified by Visa and MasterCard SecureCode Setcom offers 3D Secure processing to all merchants. 3D Secure protects the merchant and cardholder by requiring the cardholder to complete an additional verification step during their online payment, prior to a transaction being processed. The Visa 3D Secure solution is called Verified-by-Visa and the solution from MasterCard is known as SecureCode. References to 3D Secure and the 3D Secure Programs refer to the Verified by Visa and MasterCard SecureCode programs combined. Both these programs apply to credit card processing only. PCI-DSS (Payment Card Industry Data Security Standard) PCI DSS was established in 2005 by a federation of companies led by MasterCard Worldwide and Visa International in an effort to curb online fraud and identity theft which stems from data breaches associated with credit cards. This standard provides a comprehensive set of requirements to merchants, banks, and service providers aimed at enhancing payment-account data security measures. As an online merchant, it is your responsibility to ensure that no credit card numbers, card expiration dates, CVV or CVV2 values are stored at any time. Storing any of these values could place you and your customers at serious risk of security breaches and will bring your implementation and integration into scope for a full PCI-DSS review and audit. Best practices dictate that card data is collected and transmitted to Setcom without ever being stored to a database, file or other permanent or semi-permanent storage medium. If the card data needs to be stored for business purposes; please contact us on the details at the end of this document to discuss your requirements. We will assist the merchant to start the PCI-DSS compliance process. For more information on PCI-DSS, please visit:

8 Setcom Server-to-Server Implementation Guide 8 Merchant Admin Interface Commerce Manager A secure web interface called the Setcom Commerce Manager is available to merchants for reporting, monitoring and account configuration. To access to the Setcom Commerce Manager please visit the below URL in your browser: Always ensure that you enter your login details on a secure URL starting with https. Login details for the Setcom Commerce Manager will be issued to you once the Setcom Subscription Agreement has been completed and the merchant account has been loaded on the system. The initial login created will be the account administrator. The account administrator will be able to create additional user accounts and control access to what each new account user can see and do. Credit Card Settlement The Setcom Server-to-Server platform can mark a credit card funded transaction for settlement in one of two ways. 1. Automatic Settlement ON: Any approved credit card transaction will automatically be marked for settlement. Merchants will see the money of credit card funded transactions in their bank account within 1 to 2 business days after settlement. 2. Automatic Settlement OFF: If a credit card transaction is approved, the funds will not be automatically marked for settlement. Funds for the transaction will be reserved on the buyer s credit card for 7 days. The cardholder will not be able to use the reserved funds on his credit card for 7 days after authorisation. It is up to the merchant to perform a manual settlement request to the Setcom server for partial or full settlement of the funds. Merchants will see the money of credit card funded transactions in their bank account within 1 to 2 business days after settlement. The default setting for automatic settling is ON. Please contact Setcom at support@setcom.com if you wish to change this. Merchants can use the Setcom Commerce Manager to manage payments and orders. The Commerce Manager allows the merchant to settle, refund and re-authorise orders. If the merchant requires remote settlement and refund of orders, please see the section entitled Remote Settlement and Refund in this document. Credit Card Transaction Flow 1. The buyer visits the merchant website to purchases goods or services. 2. The merchant collects the credit card details from the buyer using a SSL secured page, including the card number, expiration date and CVV.

9 Setcom Server-to-Server Implementation Guide 9 3. Optional for fraud screening. While the buyer enters the card details, profiling occurs on the payment page to uniquely identify the buyer s computer. 4. The merchant bundles the required message fields into a request message and sends the information to Setcom s Server-to-Server platform. 5. If the 3D Secure program is not enabled on the merchant account (for example MOTO merchants) or the buyer is not enrolled in the 3D Secure program (for example Diners and American Express cards), Setcom will perform an authorisation request to the bank and return the transaction result to the merchant. 6. If the 3D Secure program is enabled on the merchant account and the buyer is enrolled in the 3D Secure program, Setcom will return a URL to the merchant where the buyer needs to be redirected to. 7. The generated URL will redirect the buyer to a URL hosted by the issuing bank (cardholder s bank). The buyer can now securely complete authentication on the issuing bank s website without compromising his 3D Secure password. 8. Setcom will perform an authorisation request to the bank, and include the correct ECI, CAVV and XID parameters for 3D Secure. 9. Setcom will return the transaction result to the merchant. Open Source Modules Setcom currently provides open-source modules for a number of shopping cart systems, such as oscommerce and Zen Cart. For a complete list of supported shopping carts or to download any of our open-source modules, please visit our Getting Started section on If a module for your shopping cart is not listed here, please send through a request to support@setcom.com Implementation The Integration covers the following areas: Purchase Request Server URL Request fields Consistent field for initial request Purchase Response Purchase Response for FNB and Nedbank Merchants Purchase Response for ABSA and Standard Bank Merchants Polling Your Transaction Status Card Order Query Web Service

10 Setcom Server-to-Server Implementation Guide 10 Remote Settlement and Refund Restriction Request format Response format Response OUTCOME field Purchase Request Transaction messages need to be submitted to the Setcom Server-to-Server API via HTTPS calls. This can be facilitated in various forms depending on the merchant programming language used. The table below summarises the technologies used by some programming languages to perform HTTPS POST operations: Programming Language Classic ASP.NET Web Application ColdFusion PHP JSP Technologies to Use ASPTear.DLL C# HTTPWebRequest method CFHTTP method PHP/CURL HttpConnection If your programming language is not listed in the above table, please contact customer services for further assistance. Access to sample code is available from:

11 Setcom Server-to-Server Implementation Guide 11 Server URL Transaction data should be sent to the following URL: Request Fields The following fields are to be sent to Setcom with the POST method. # Field Name Required Max Length Description 1 CO_ID Yes 50 Value issued to merchant by Setcom used to identify company on system. 2 OUTLET Yes 50 Value issued to merchant by Setcom used to identify company on system. 3 Reference Yes 250 Value generated by the merchant system to keep track of this transaction. This value will be passed back to the merchant in the transaction response. This value will appear on all merchant reports and will be used by the merchant for reconciliation purposes. Setcom strongly urges merchants to use a unique value per transaction for this field. 4 CC_Amount Yes 21 Value of the transaction in decimal format, e.g CCName Yes 50 Name of cardholder. 6 CCNumber Yes 21 Credit card number. 7 ExYear Yes 4 Credit card expiry year. 8 ExMonth Yes 2 Credit card expiry month. 9 CCCVV Yes 10 Credit card verification value. 10 PayPeriod No 2 If value is set, this will define the budget period. Default value of 0 is for the straight facility. 11 Address No 250 Customer address. 12 MobileNumber No 12 Customer mobile number. 13 Consistent No 512 Generated Consistent Key, please refer to section below. 14 buyer_id No 100 Unique ID created for the buyer on the Merchant s system.

12 Setcom Server-to-Server Implementation Guide buyer_session_id No 512 The buyer's session id created by your system. 16 ship_title No 10 Title of the order recipient. 17 ship_first_name No 100 First name of the order recipient 18 ship_last_name No 100 Last name of the order recipient. 19 ship_street1 No 100 Street address 1 of the order recipient. 20 ship_street2 No 100 Street address 2 of the order recipient. 21 ship_city No 100 City or town of the order recipient. 22 ship_state No 100 State or province of the order recipient 23 ship_zip No 100 Zip or postal code of the order recipient 24 ship_country No 2 ISO 3166 Country code of the order recipient, see Appendix A: ISO 3166 Country Codes. 25 ship_phone No 50 Telephone number of the order recipient. 26 bill_title No 10 Title of the buyer. 27 bill_first_name No 100 First name of the buyer. 28 bill_last_name No 100 Last name of the buyer 29 bill_street1 No 100 Street address 1 of the buyer 30 bill_street2 No 100 Street address 2 of the buyer. 31 bill_city No 100 City or town of the buyer. 32 bill_state No 100 State or province of the buyer 33 bill_zip No 100 Zip or postal code of the buyer. 34 bill_country No 2 ISO 3166 Country code of the order billing Address. 35 bill_phone No 50 Telephone number of the buyer. 36 ip_address No 15 The IP address for the buyer in xxx.xxx.xxx.xxx format 37 redirect_url Yes (if 3DS enabled) 500 This field will be used to redirect the buyer back to the merchant web site after 3DS authentication has been completed.

13 Setcom Server-to-Server Implementation Guide 13 Consistent Field for Purchase Request An additional consistent field can be included in the transaction request in order to ensure that the request originated from the merchant and no fields were changed. Before implementing the consistent field, Setcom will generate a secret key for the merchant. This secret key must not be shared with anyone and must only be known to the merchant and Setcom. The consistent field is generated by concatenating selected message request fields. A merchant secret value, known only to the merchant and Setcom, is then appended to the newly created string. The combined string is then hashed and included in the transaction request message to Setcom. Please note that the consistent key is never included in the transaction message in the clear. After Setcom receives the transaction message request, Setcom will in turn build its own version of the consistent field, using the selected message request fields and the secret key from the Setcom database. If the merchant submitted consistent value matches the Setcom generated consistent value, Setcom will process the transaction request. If the two consistent values do not match, Setcom will reject the transaction request. Please ensure that your system uses unique merchant Reference values. How to generate the Consistent Field The consistent field to be sent in the Request (see above) is generated by hashing (using the SHA- 512 algorithm using UTF-8 encoding) the concatenated fields in the order specified below: 1. CO_ID 2. OUTLET 3. Reference 4. CC_Amount 5. CCName 6. CCNumber 7. ExYear 8. ExMonth 9. CCCVV 10. Merchant Secret Key Process to follow to generate the Consistent field: 1. Concatenate the above fields in the order specified. 2. Apply a SHA512 hashing algorithm to the newly generated string. Remember to use UTF-8 encoding. 3. Please ensure that the generated hash is always in uppercase.

14 Setcom Server-to-Server Implementation Guide 14 Example CO_ID: testaccount OUTLET: testaccount Reference: PRO_001 CC_Amount: 10 CCName: Mr Test Buyer CCNumber: 4XXXXXXXXXXXXXX2 (Replace X with 0) ExYear: 2015 ExMonth: 12 CCCVV: 402 Merchant Secret Key: Generated consistent key: AEFE710B6B18E07FBC043B82A94398B0BC220046AE F349ED FB72D64D75F4930B7 C953D69756A616F4D70723D6BDDD0A366AFBAB04C Purchase Response The purchase response will vary for bank specific merchants. FNB and Nedbank Merchants For FNB and Nedbank merchants, the flow of the response will be as follows: Merchant will receive a response from Setcom in the form of a 7 element comma separated list. (E.g. APPROVED,123456,16/09/2014,16:50:25 PM, ,INV , ) Each transaction outcome has a specific response indicator value returned. For example, for an APPROVED transaction, the bank authorisation number will be returned and for a DECLINED transaction, the decline error code will be returned. Refer to Response Outcome Fields for detailed information. For 3D Secure, the merchant will receive an outcome of ENROLLED followed by the ACS URL in the Response Indicator. The Buyer Authentication Request is sent by the merchant to authenticate the PARes. The Buyer Authentication Response will be sent back to the merchant s server. After a successful buyer authentication, the merchant sends a Post-Authentication Purchase Request to initiate bank authorisation. An HTTP response is sent back to the merchant for the bank authorisation response. Information on implementing this process is detailed under the purchase response section for FNB and Nedbank Merchants.

15 Setcom Server-to-Server Implementation Guide 15 ABSA and Standard Bank Merchants For ABSA and Standard Bank merchants, the flow of the response will be as follows: Merchant will receive a Form post to the redirect_url that was sent in the Purchase Request which will include the response fields returned from Setcom. Merchant validates Consistent Key sent in response to confirm secure message sent by Setcom. Information on implementing this process is detailed under the purchase response section ABSA and Standard Bank Merchants. Purchase Response for FNB and Nedbank Merchants The Setcom Server-to-Server API response for FNB and Nedbank merchants will always be in the form of a 7 element comma separated list. Each element in the list contains the response variables as laid out in the below table: Element Field Name Description 1 Transaction outcome String value representing the transaction response outcome. See the below section called Response Outcome Fields for a more detailed explanation of what this field means. 2 Response Indicator The use of this field and the value populated in this field is determined by the value of the response outcome (element one in the response message). For example; if the response outcome is returned as APPROVED, then this field will contain the bank authorisation number. See the below section called Response Outcome Fields for a detailed explanation of this field and possible values associated with this field. 3 Transaction Date Transaction date as on the Setcom server in format dd/mm/yyyy e.g. 17/01/ Transaction Time Transaction time as on the Setcom server in format HH:mm:ss tt e.g. 08:22:33 AM 5 Transaction Order ID Unique numeric transaction ID created for the transaction. If an error occurs the field may contain a 0 (zero) value. 6 Merchant Reference The merchant reference for this transaction will be passed back to the merchant in this field. 7 Transaction Amount Amount of the transaction as recorded on the Setcom server. This field excludes any currency symbols, e.g

16 Setcom Server-to-Server Implementation Guide 16 Response OUTCOME Fields The table below describes the various response outcomes (The transaction response field returned in the request response by Setcom as discussed above). Always ensure when checking the first response element that your comparison is not case sensitive. # Outcome Response Indicator will Contain Description 1 APPROVED Authorisation number Authorisation number returned by the bank. 2 DECLINED Decline code Transaction decline code returned by the bank. See Appendix A Error Codes for more information. 3 ERROR Error Code Transaction error code returned by the processor. See Appendix A Error Codes for more information. 4 ENROLLED ACS (Access Control System) URL URL of ACS window used for buyer authentication. An enrolled response indicates that the buyer is in the process of completing authentication. 5 UNAVAILABLE The text Unavailable Secure 3D Authentication was unavailable on this credit card. Please try again and contact the merchant if this error persists. 6 ATTEMPTED The text Attempted Secure 3D Authentication was attempted but unsuccessful on this credit card. Please try again and contact the merchant if this error persists. 7 STOP Fraud screening score Fraud screening score of the transaction as returned from the Fraud Screening Engine, if merchant has signed up for Fraud Screening. 8 REVIEW Fraud screening score Fraud screening score of the transaction as returned from the Fraud Screening Engine, if merchant has signed up for Fraud Screening. 9 DUPLICATE Transaction order ID The transaction order ID of the previous duplicate transaction, if Duplicate Checking has been enabled for the merchant. Contact support@setcom.com to enable this option if required.

17 Setcom Server-to-Server Implementation Guide 17 A few sample response strings are included below for explanations purposes. The first sample is that of an Approved transaction. Note that element one contains the word APPROVED and the second element contains the bank authorisation number Please ensure that this field is not checked with case sensitivity. I.e.: "Approved" is the same as "APPROVED". # Outcome Sample Response 1 APPROVED APPROVED,123456,16/09/2014,16:50:25 PM, ,INV , DECLINED DECLINED,330T8,16/09/2014,16:51:25 PM, ,INV , ENROLLED ENROLLED, BA29 c=fc31d... F59&p= ,16/09/2013,16:54:25 PM, ,INV , ERROR ERROR,10203,16/09/2013,16:53:25 PM,0,INV , UNAVAILABLE UNAVAILABLE,UNAVAILABLE,16/09/2013,16:54:25 PM, ,INV , ATTEMPTED ATTEMPTED,ATTEMPTED,16/09/2013,16:55:25 PM, ,INV , DUPLICATE DUPLICATE, ,16/09/2013,16:56:25 PM, ,INV , D Secure Handling Enrolled Responses When a credit card is enrolled in the 3D Secure program, Setcom will return a response outcome of ENROLLED in the first response element to the merchant. The second response element will contain a URL where the buyer must be redirected to. This URL will redirect the buyer to the ACS (Access Control System), which is served off the credit card issuer s website. A sample buyer redirect URL is included below: CEFA5D47DBDA6FBBB B89113FA577E024174E8F518EF2C3AD2D2C6E4031EF08C73F059 1D&c=5979B67751B4EF2C8413C548E62EC840F8D0338D20FC43E29101F2E80311BB7EC30FFFBD4F3 AC6003F4F666C9AD355F557499F221360E A6FA1F41A63B&p= Once redirected to the ACS, the buyer will enter his credit card 3D Secure password or enter the 3D Secure OTP on the ACS window. If cardholder authentication fails on the ACS, the buyer will be redirected back to the merchant s website, and Setcom will include the error details in the redirect request. ACS URL Response HTTP request variables are passed back to the merchant server after the buyer completes authentication on the ACS URL.

18 Setcom Server-to-Server Implementation Guide 18 Note: In order to determine the response outcome, merchant must refer to the ErrorCode field. # Field Name Comment Description 1 ErrorCode Response outcome. Error code of 0 indicates a successful payer authentication request and response. 2 OrderID Transaction order ID Unique numeric transaction ID created for the transaction by the processor. 3 Reference Merchant reference The merchant reference for this transaction will be passed back to the merchant in this field. 4 CC_Amount Transaction amount Amount of the transaction as recorded on the Setcom server. This field excludes any currency symbols, e.g PARes PARes Payer Authentication Response. 6 Consistent Consistent Refer to ACS Consistent section below on how to calculate this field. ACS Consistent The consistent field returned in the ACS URL Response (see above) is generated by concatenating the fields in the order specified below and applying SHA-512 hashing algorithm using UTF-8 encoding. 1. ErrorCode 2. OrderID 3. Reference 4. CC_Amount 5. PARes 6. Merchant Secret Key Please ensure that the resultant value generated is always in uppercase. After generating the consistent value, you can compare it to the consistent you received to verify that the values you have received are from Setcom.

19 Setcom Server-to-Server Implementation Guide 19 Buyer Authentication Request HTTP request variables sent by the merchant s server to authenticate the PARes (payer authentication response). This request must be sent to # Field Name Max Length Description 1 CO_ID 50 Value issued to merchant by Setcom used to identify company on system. 2 OUTLET 50 Value issued to merchant by Setcom used to identify company on system. 3 OrderID 10 Value automatically generated when client completed the payment. 4 Reference 100 Value that the merchant generates 5 CC_Amount (18,2) Amount of the transaction as recorded on the Setcom server. This field excludes any currency symbols, e.g PARes 2048 Payer Authentication Response. 7 Consistent 512 Hashed consistent value. Refer to section below on how to generate this field. Buyer Authentication Request Consistent Field The consistent field you need to send above is generated by concatenating the fields in the order specified below and applying SHA-512 hashing algorithm using UTF-8 encoding. 1. CO_ID 2. Outlet 3. OrderID 4. Reference 5. CC_Amount 6. PARes 7. Merchant Secret key Please ensure that the resultant value generated is always in uppercase. After generating the consistent value, you can compare it to the consistent you received to verify that the values you have received are from Setcom. Buyer Authentication Response Response received by the merchant server in response to the buyer authentication request. Note: In order to determine the response outcome, merchant must refer to the ErrorCode field.

20 Setcom Server-to-Server Implementation Guide 20 # Field Name Description 1 ErrorCode Indicates the outcome of the request. An error code of 0 indicates a successful request. 2 Signature Verification Status Y The verification of the buyer authentication signature was successful. N The verification of the buyer authentication signature failed. 3 Payer Authentication Status Y Buyer authentication was successful. N Buyer authentication failed. A Buyer authentication was Attempted but failed. U Buyer authentication is Unavailable. 4 Transaction order ID Unique numeric transaction ID created for the transaction. If an error occurs the field may contain a 0 (zero) value. 5 Merchant reference The merchant reference for this transaction will be passed back to the merchant in this field. 6 Transaction amount Amount of the transaction as recorded on the Setcom server. 7 ECI The relevant ECI indicator. This field excludes any currency symbols, e.g CAVV The Base64 encoded cardholder authentication verification value 9 XID The Base64 encoded transaction identifier. 10 Consistent Refer to Buyer Authentication Response Consistent section below. Buyer Authentication Response Consistent The consistent field you need to send above is generated by concatenating the fields in the order specified below and applying SHA-512 hashing algorithm using UTF-8 encoding. 1. ErrorCode 2. Signature Verification Status 3. Payer Authentication Status 4. Order ID 5. Reference 6. CC_Amount

21 Setcom Server-to-Server Implementation Guide ECI 8. CAVV 9. XID 10. Merchant Secret Key Please ensure that the resultant value generated is always in uppercase. After generating the consistent value, you can compare it to the consistent you received to verify that the values you have received are from Setcom. Post-Authentication Purchase Request This is an HTTP request sent by the merchant s server to initialise a bank authorisation after successful buyer authentication. This request must be sent to # Field Name Max Length Description 1 CO_ID 50 Value issued to merchant by Setcom used to identify company on system. 2 OUTLET 50 Value issued to merchant by Setcom used to identify company on system. 3 OrderID 10 Value issued to merchant by Setcom used to identify company on system. 4 Reference 100 Value generated by the merchant system to keep track of this transaction. This value will be passed back to the merchant in the transaction response. This value will appear on all merchant reports and will be used by the merchant for reconciliation purposes. Setcom strongly urges merchants to use a unique value per transaction for this field. 5 CC_Amount (18,2) Pay amount in numeric format excluding any decimal places,commas and currency e.g excluding 6 ECI 2 The Electronic Commerce Indicator (ECI) indicates the level of security used when the cardholder provided payment information to the merchant. This value will be returned to the merchant by

22 Setcom Server-to-Server Implementation Guide 22 Setcom after buyer authentication 7 CAVV 512 A unique value transmitted by an issuer (or Visa on behalf of an issuer), in response to an authentication request from a 3-D Secure merchant. 8 XID 512 Stands for extended ID. It is a type of user ID that can be used to access a subset of the online applications that work with the University PIN system. 9 Consistent 512 Refer to section below on how to generate this value. Post-Authentication Purchase Consistent The consistent field sent in the Post-Authentication Purchase Request above is generated by concatenating the fields in the order specified below and applying SHA-512 hashing algorithm using UTF-8 encoding. 1. CO_ID 2. Outlet 3. Order ID 4. Reference 5. CC_Amount 6. ECI 7. CAVV 8. XID 9. Merchant Secret Key Please ensure that the resultant value generated is always in uppercase. After generating the consistent value, you can compare it to the consistent you received to verify that the values you have received are from Setcom. Post-Authentication Purchase Response This is the HTTP response sent to the merchant s server containing the bank authorisation response. Field Position Field Name Description 1 Transaction Outcome String value representing the transaction response outcome. See Response Outcome below for detailed information. 2 Response Indicator See Response Outcome below for the possible values returned.

23 Setcom Server-to-Server Implementation Guide 23 3 Transaction Date E.g. 10/01/ Transaction Time E.g. 08:31:27 AM (GMT) 5 Transaction Order ID Unique numeric transaction ID created for the transaction by the processor. If an error occurs the field may contain a 0 (zero) value. 6 Merchant Reference The merchant reference for this transaction will be passed back to the merchant in this field. 7 Transaction Amount Amount of the transaction as recorded on the Setcom server. This field excludes any currency symbols, e.g Response Outcome # Outcome Response Indicator Will Contain Description 1 APPROVED Authorisation Number Authorisation number returned by the bank. 2 DECLINED Decline Code Transaction decline code returned by the bank. See Appendix A Decline and Error Codes for more information. 3 ERROR Error Code Transaction error code returned by the processor. See Appendix A Decline and Error Codes for more information. 4 DUPLICATE Transaction order ID The transaction order ID of the previous duplicate transaction. Purchase Response for ABSA and Standard Bank Merchants Setcom will submit a Form POST to the redirect_url sent in the Purchase Request. The fields that will be posted to the URL are listed in the table below: Field Position Field Name Description 1 Outcome String value representing the transaction response outcome. See the below section called Post-Authentication Purchase Response for a more detailed explanation of what this field means.

24 Setcom Server-to-Server Implementation Guide 24 2 ResponseIndicator See Post-Authentication Purchase Response below for the possible values returned 3 Date E.g. 10/01/ Time E.g. 08:31:27 AM (GMT) 5 OrderID Unique numeric transaction ID created for the transaction by the processor. If an error occurs the field may contain a 0 (zero) value. 6 MerchantReference The merchant reference for this transaction will be passed back to the merchant in this field. 7 Amount Amount of the transaction as recorded on the Setcom server. This field excludes any currency symbols, e.g Consistent Please see below on how to work this consistent out. Working out the Consistent Field 1. Concatenate the below field values in the following order. 1. Outcome 2. ResponseIndicator 3. Date 4. Time 5. OrderID 6. MerchantReference 7. Amount 8. Merchant Secret Key 2. Take the result of concatenating the fields and hash the string, using the SHA-512 method using UTF-8 encoding. The resultant value must yield the exact same value as the Consistent field.

25 Setcom Server-to-Server Implementation Guide 25 Post-Authentication Purchase Response # Outcome Response Indicator Will Contain Description 1 APPROVED Authorisation Number Authorisation number returned by the bank. 2 DECLINED Decline Code Transaction decline code returned by the bank. 3 ERROR Error Code Transaction error code returned by the processor. 4 DUPLICATE Transaction order ID The transaction order ID of the previous duplicate transaction. Polling your Transaction Status If a timeout or break in communication has occurred between the merchant and Setcom, the merchant can have a process in place to poll transaction statuses. Merchants can poll the transaction status using the card_order_query method in the Order Query Web Service. The web service WSDL file is located at the below URL: (If your programming language does not support web service implementations, please contact customer service to discuss different implementation options). Ensure that you always connect to the secure URL (https). This will ensure the communication between the merchant and the Setcom server is encrypted. When calling the card_order_query method the merchant needs to supply a XML request string to the method. The XML request string will contain the merchant s login details as well as a list of order reference numbers and amounts the merchant wants to query on the Setcom system.

26 Setcom Server-to-Server Implementation Guide 26 A sample XML request string is included below: <?xml version="1.0" encoding="utf-8"?> <card_order_query_request> <merchant> <co_id>testaccount</co_id> <outlet>testaccount</outlet> <uname>testaccount</uname> <pword>testaccount</pword> </merchant> <orders> <transaction> <reference>auto_svr_tst_ _160000</reference> <amount>1.86</amount> </transaction> <transaction> <reference>auto_svr_tst_ _155500</reference> <amount>1.17</amount> </transaction> </orders> </card_order_query_request> Request Fields Below is a description for each field: XML Element Required Description card_order_query_request Yes Root element of the XML request string. merchant Yes Element containing the merchant login and account details. co_id Yes Value issued to merchant by Setcom used to identify company on system. outlet Yes Value issued to merchant by Setcom used to identify outlet on system. uname Yes Outlet username of user who has access to merchant reporting. pword Yes Outlet password of user who has access to merchant reporting. orders Yes Element containing transactions transaction Yes Element containing the order details of the order being queried. reference Yes The merchant reference number created and

27 Setcom Server-to-Server Implementation Guide 27 submitted by the merchant in the original transaction request. amount Yes The transaction request amount in decimal format excluding any currency symbol, e.g Sample XML Response String A sample XML response string is included below: <?xml version="1.0" encoding="utf-8"?> <card_order_query_response> <outcome> <error_code>0</error_code> <error_desc/> <error_solution/> </outcome> <merchant> <co_id>testaccount</co_id> <outlet>testaccount</outlet> </merchant> <query> <order> <reference>auto_svr_tst_ _160000</reference> <amount>1.86</amount> <cardtype>credit</cardtype> <status>completed</status> <error_code>0</error_code> <error_desc/> <error_solution/> <orderid> </orderid> <transkey>loopback</transkey> <authnumber>123456</authnumber> <datecreated> :56:39 PM</datecreated> <datecompleted> :57:00 PM</datecompleted> </order> </query> </card_order_query_response> Response Fields Below is a description of each field: XML Element card_order_query_response outcome Description Root element of the XML response string. Element containing the status of the call to card order query

28 Setcom Server-to-Server Implementation Guide 28 error_code error_desc error_solution merchant co_id outlet query order reference amount cardtype status error_code error_desc error_solution orderid transkey authnumber datecreated datecompleted Contains the error code of the request. 0 means no error. Contains the description for the error code. Contains a possible solution for solving the error. Element containing the merchant details. Value issued to merchant by Setcom used to identify company on system. Value issued to merchant by Setcom used to identify outlet on system. Contains all the queried transactions. Element containing the order details that was queried. The merchant reference number created and submitted by the merchant in the original transaction request. The transaction request amount in decimal format excluding any currency symbol, e.g The type of the card IE: Credit or Debit. The status of the order. IE: NEW, PENDING, INVALID, COMPLETED, CANCELLED, DECLINED, PARTIAL. The error code for this transaction, if there was an error. An error code of 0 means that there was no error. The description of the above mentioned error. A possible solution to the above mentioned error. Setcom generated unique order number for this transaction. A transaction key from the bank. The authorization number from the bank. Date the transaction was created EG: :56:39 PM Date the transaction was completed EG: :57:00 PM Remote Settlement and Refund Setcom provides a remote interface that merchants can use to remotely process settlement and refund messages on already authorised orders.

29 Setcom Server-to-Server Implementation Guide 29 Restrictions 1. A merchant can perform partial settlements, as long as the sum of all the partial settlements does not exceed the original authorisation amount. 2. A merchant can perform partial refunds, as long as the sum of all the partial refunds does not exceed the original authorisation amount. 3. An approved authorisation request will reserve the funds on the credit card for 7 days only. Any settlement requests need to be done within 7 days of the original authorisation. 4. Refunds can only be processed for 6 months after the original authorisation date. Request Format To perform a remote settlement or refund request the merchant has to perform a HTTPS POST operation to the below URL: The following fields are required to perform a remote settlement: Field Name Required TnxType Description CO_ID All Value issued to merchant by Setcom used to identify company on system. OUTLET All Value issued to merchant by Setcom used to identify outlet on system. OrderID All Unique Order ID generated by Setcom and returned to the merchant in the initial transaction response. TnxType All Text value indicating transaction request action: 1. SHIP 2. REFUND 3. CANCEL Only orders that have not been settled can be cancelled. This just marks the transaction as cancelled (unable to settle later) in the system. Amount All The transaction request amount. If this is a partial settlement or refund, the amount needs to be smaller than the original authorisation amount. If the full amount needs to be settled, populate the full authorisation amount in decimal format excluding any currency symbol, e.g Username All Merchant username as issued to the merchant on signup. The merchant can create additional user account in the Commerce Manager. Password All The password of the above username

30 Setcom Server-to-Server Implementation Guide 30 CardNumber Ship / Refund The credit card number of the buyer CardExYear Ship / Refund The credit card Expiry Year of the buyer CardExMonth Ship / Refund The credit card Expiry Month of the buyer CardCVV Ship / Refund The credit card CVV number of the buyer Response Format The Setcom response will always be in the form of a 9 element comma separated list. Each element in the list contains the response variables as laid out in the below table: Element Field Name Description 1 Outcome String value representing the transaction response outcome. See the below section called Response Outcome for a more detailed explanation of what this field means. 2 Error Code If the transaction request is not approved, this field will contain the error code. For approved transactions this field will simply contain the text APPROVED. Please ensure that this field is not checked with case sensitivity. I.e.: "Approved" is the same as "APPROVED". 3 Authorisation Number If this transaction request is approved, this field will contain the bank authorisation number. For transactions which have not been approved, this field will contain the text 0 (zero). 4 Date Transaction date as on the Setcom server in format ddmmm-yy. 5 Time Transaction time as on the Setcom server in format hh:mm:ss tt. E.g.: 08:53:12 PM (GMT) 6 Setcom Order ID Unique Setcom ID created for this order. In some cases this field will return a 0 (zero) if no order could be created on the Setcom system, e.g. when the CO_ID or OUTLET values are invalid. 7 Transaction Key Transaction key as generated by the bank. A unique transaction key is generated per auth/settlement pair and per refund. 8 Transaction Type This field will contain the below text depending on the transaction type submitted: 1. SHIP 2. REFUND

31 Setcom Server-to-Server Implementation Guide CANCEL 9 Amount The transaction request amount in decimal format excluding any currency symbol, e.g Response OUTCOME field 1 st Response Element 2 nd Element Will Contain... Comment APPROVED Authorisation number Bank authorisation number as returned by the bank on the authorisation request. Please ensure that this field is not checked with case sensitivity. I.e.: "Approved" is the same as "APPROVED". DECLINED Decline code Decline code from bank; see Appendix A Error Codes for an explanation of the decline code. ERROR Error code Error code from Setcom or processor; see Appendix A Error Codes for an explanation of the decline code. A few sample response strings are included below for explanations purposes. The first sample is that of an approved settlement message. Note that element one contains the word APPROVED and the third element contains the bank authorisation number APPROVED,APPROVED,123456,2-Sep-2010,14:16PM, ,STK ,SHIP,12.95 The sample string below depicts a typical error, that of an invalid OrderID parameter. Note that element one of the response string contains the word ERROR and the second element thus contains the error code, in this case 614, meaning that the OrderID field is invalid. ERROR,614,0,3-Feb-2010,14:17 PM, ,0,SHIP, Credit Card Fraud Screening Setcom provides a rule based fraud screening engine to minimise the potential risk involved with trading online. Custom configuration of fraud rules per outlet is offered by Setcom as an additional service. Please contact Setcom at sales@setcom.com to activate this service. Please note that additional fees may apply.

32 Setcom Server-to-Server Implementation Guide 32 Fraud screening is done before any other process, e.g. Secure 3D or bank authorisation. This means that any potential security risk is minimised by stopping orders before they are processed. When Fraud Screening is initially enabled on your account, Setcom will configure a default rule set for your type of business and contact you with instructions on how to configure the fraud screening engine. Rules can be configured by contacting Setcom at support@setcom.com The fraud engine can perform the following tasks: 1. Black list: Black list fraudsters on any field in the payment message, e.g. card number, BIN range, common fraudulent billing address or shipping telephone number etc. 2. GeoBIN: scoring on the shipping and billing country related to where the credit or debit card was issued. 3. Velocity Checks: Buyer and credit and debit card velocity checks. 4. Limits: Enforce limits to minimise the impact of possible fraudsters trying to abuse your system. Enforce unique constraints on payment fields and stop duplication of orders based on the merchant reference and/or the payment amount per client for custom periods. 5. Alerting and Monitoring: Custom alerts let you proactively stop fraudsters. Monitoring helps you fine tune scoring and blocking and allows you to white list good business. 6. Device Identification to uniquely identify the computer. The Setcom Commerce Manager provides access to a user friendly interface from which transactions can be monitored. Device Profiling for Fraud Screening Device profiling significantly enhances the fraud screening system by uniquely identifying the buyer s computer. In order to deploy device profiling, the following steps need to be followed: 1. Insertion of HTML profiling tags into web pages that a buyer will load prior to submitting the card details (such as a checkout payment page or login). These tags will allow Setcom to profile the buyer s computer. 2. Submit the buyer_session_id in the payment message to Setcom.

33 Setcom Server-to-Server Implementation Guide 33 Sample HTML Profiling Tags <P STYLE="background:url( r_session_id&m=1)"></p> <IMG ID="tmIMG" SRC=" 2" ALT="" > <SCRIPT SRC=" TYPE="text/javascript"> </SCRIPT> <OBJECT TYPE="application/x-shockwave-flash" DATA=" WIDTH="1" HEIGHT="1" ID="obj_id"> <PARAM NAME="movie" VALUE=" /> <DIV></DIV> </OBJECT> Replace the buyer_session_id in the above code with the buyer s session id created by your system. Testing Setcom creates a live outlet and a test outlet for each merchant account. A separate set of test account details is also provided. The merchant test account outlet details and the separate test account details are for testing transactions e.g. during implementation. The live account outlet details are for live transactions. The test account outlet details will return an approved status for every transaction attempted. With this account, no real transactions will ever be processed. Global Test Account Details To test please use the below details or contact support@setcom.com for a test account: CO_ID: testaccount OUTLET: testaccount Username: testaccount Password: testaccount This is a public testing account so please refrain from using real credit or debit card details. For testing please use any of the below card numbers. These are test card numbers only, intended to be used by developers to test their implementation.

34 Setcom Server-to-Server Implementation Guide 34 Credit Card Test Details 3D Secure Testing Please contact to request the most recent 3D Secure test pack.