Redunicre MOTO (Mail Order / Telephone Order)

Transcription

1 Integration Guide Redunicre MOTO (Mail Order / Telephone Order) Version 0.5 (valid for Redunicre MOTO only)

2 Contents Page 1. Introduction Document aim Target user Restrictions Document Contents Reference document list Contacts 5 2. Step by Step integration process Step 1 - Create a test account Step 2 - Account settings Step 3 - Test using example pages Step 4 - Integrate into your backoffice Step 5 - Validate your integration Step 6 - Request activation of your account in production 8 3. Developement kits overview Introduction Presentation of the.php SDK Presentation of the.net SDK Presentation of the JAVA SDK SDK configuration SDK example code advice and limitations 13 4.Connection Security requirements Test environment URL (Homologation) Production environment URL 15 5.API functions Do Authorization Do Capture Do Refund Transaction Search GetTransaction Details 24 6.Appendices Test Cards Messages and return codes LCLF eeror messages and return codes 29 2/35

3 6.4. Timeout management Identifying duplicate requests Reminder of how authorization/validation works Card Type List List of mandatory fields by card type Action type list Countries list Languages list Amounts to send and return code simulation Glossary 33 3/35

4 1. Introduction 1.1. Document aim This document details the Redunicre MOTO (Mail Order / Telephone Order) payment solution integration procedure for your backoffice application. Redunicre MOTO interfaces with your backoffice and allows you to charge your costumers who have sent you their card details by fax, phone, , etc Target user This document is to be used by merchants and integrators who wish to integrate the Redunicre MOTO solution into their backoffice, in order to process payments Restrictions The current version of this manual is limited to MOTO (Mail Order / Telephone Order) and the only supported functions are: doauthorizationrequest docapture dorefund transactionssearchrequest (currently disabled - performance issues) gettransactiondetailsrequest 1.4. Document contents The Step by step integration process chapter details the steps you must take to create a merchant account, integrate Redunicre MOTO into your sales application and test it. The Development kit overview chapter presents the example codes that allow a faster installation of the payment solution in your sales application. The API functions chapter presents the complete library of payment functions. 4/35

5 The Appendices lists amongst other things the return codes and messages for the payment requests Reference document list The complete Redunicre MOTO documents are available on Contacts For assistance, advice or any other questions, please contact Redunicre: Tel.: Fax: If you encounter any errors in this document, please send us an with precise details of the error or problem. 5/35

6 2. Step by step integration process This chapter explains how to integrate the payment system quickly into your backoffice application. We recommend that you carry out each step in order to guarantee effective integration. It is essential to carry out payment requests in the test environment in order to progress to the production stage. The test environment is free. It works exactly like the production site except that no payment is sent to the buyer. The necessary data set to carry out a payment with a card is detailed in this document Step 1 Create a test account You must contact REDUNICRE in order to receive all the necessary data to start testing the system Step 2 Account settings This step allows you to change your test account settings using the merchant admin centre. Go to: Enter your merchant ID, your user ID and password, then click on Connect. In order to be able to use the payment system, you must contact REDUNICRE Step 3 Test using example pages This step allows you to ensure your account settings are correct using the downloadable example pages available on The example pages are suggested in a development kit available in PHP,.NET and JAVA. Once you have downloaded these pages, you can follow the readme.txt file instructions: Update your test platform and activate the required libraries. 6/35

7 Install and configure the example pages using the following: o merchantid: enter the merchant ID given to you when you signed up. o merchantaccesskey: enter the merchant access key given to you when you signed up. If you have lost your access key, you should contact REDUNICRE. o contractnumber: enter the contract number (terminal number) for your merchant account. o contractnumberlist: this variable must be void ( ). o proxyinternet: specify whether your internet connection requires internet proxy parameterisation. If you are testing from a computer connected to a business network, it is likely you are connected to the internet via an internet proxy. All you need to do is specify the DNS name and port: proxy = proxy.monentreprise.com port = 8080 Start server Go to If you use a port other than 80, specify the name: For example: port Click on Direct Payment on the homepage Test the integration functions Step 4 Integrate into your backoffice To integrate Redunicre MOTO into your backoffice you must be able to manage the customer interface development with secure web service standards Step 5 Validate your integration Check the validity of your integration at this step. Once the payment solution is integrated into your backoffice application, you must validate your integration by carrying out the following actions: Obtain the correct transaction for each payment method. 7/35

8 Simulate a declined payment. In the authorization environment, the buyer response is simulated. You can simulate the different potential responses: Accepted, Declined, etc. by using a transaction sum of 333,xx. You will find a table detailing the value of cents and the corresponding return result codes in the appendices. If you use any values different from the values listed on the tables, the system s response is unpredictable. Consult the merchant admin centre and validate your transaction records Step 6 Request activation of your account in production When you have validated the integration of the payment system into your backoffice, contact REDUNICRE in order to activate your account in the production environment. 8/35

9 3. Development kits overview 3.1. Introduction Development kits, also known as SDK, can be used on an early stage to understand how the Redunicre MOTO solution works and how the integration with your backoffice should be done. The development kits are presented only as an example and its correct configuration is not a required condition for a successful integration. Easy to use, they use the API payment functions. Classes allow requests to be sent, responses to be read, and data to be processed. These classes are produced using the WSDL file. For more information, please see the api functions chapter. Important Notice: There are only 5 API functions available to implement the Redunicre MOTO solution: doauthorizationrequest, docapture, dorefund, transactionsearchrequest, gettransactiondetailrequest. All the other functions presented in the Kits are not supported for Redunicre MOTO. SDKs are available in JAVA,.NET and PHP platforms, which are used by the vast majority of backoffice solutions Presentation of the PHP SDK Kit composition The SDK PHP is made up of the following: notice of development kit installation. a function library allowing the use of API functions an example of web application using the SDK. Structure and functions When you unzip the development kit, you will find: 1. the examples directory a. doauthorizationform.html This file presents a form you can use to carry out a debit authorization request. You can adjust settings for the doauthorizationrequest on this page. b. doauthorization.php 9/35

10 This file contains the PHP code which retrieves the information transmitted by the HTML form and uses the library to carry out an authorization request. c. docaptureform.html This file presents a form you can use to carry out a request to validate an accepted authorization. You can adjust settings for the docapturerequest on this page. d. docapture.php This file contains the PHP code which retrieves the information transmitted by the HTML form and uses the library to carry out a validation request. e. dorefundform.html This file presents a form you can use to carry out a refund request. You can adjust settings for the dorefundrequest on this page. f. dorefund.php This file contains the PHP code which retrieves the information transmitted by the HTML form and uses the library to carry out a refund request. 2. the lib directory groups the classes detailing the requests responses and objects of the API SOAP. a. paylinesdk.php This file contains the main class which allows the creation of SOAP messages as well as other specific classes that carry out and manage precise requests and responses. For example: doauthorizationrequest, docapture. b. lib_debug.php The debug library displays the return message of your API SOAP requests in the form of a table. 3. the settings directory groups the kit parameter files together. a. identification.php This file contains the parameters unique to your merchant account such as the merchant ID, the service access key, etc. b. options.php This file contains the default parameters to use in a transaction Presentation of the.net SDK Kit composition The SDK.NET is made up of the following: notice of development kit installation. 10/35

11 a function library allowing the use of The payment system API functions an example of web application using the SDK. Structure and functions When you unzip the development kit, you will find: 1. The example directory a. doauthorizationform.aspx This file presents a form you can use to carry out a debit authorization request. You can adjust settings for the doauthorizationrequest on this page. b. doauthorization.aspx.cs This file contains the ASP code which retrieves the information transmitted by the HTML form and uses the library to carry out an authorization request. c. docaptureform.aspx This file presents a form you can use to carry out a request to validate an accepted authorization. You can adjust settings for the docapturerequest on this page. d. docapture.aspx.cs This file contains the ASP code which retrieves the information transmitted by the HTML form and uses the library to carry out a validation request. e. dorefundform.aspx This file presents a form you can use to carry out a refund request. You can adjust settings for the dorefundrequest on this page. f. dorefund.aspx.cs This file contains the ASP code which retrieves the information transmitted by the HTML form and uses the library to carry out a refund request. 2. the Bin directory groups the classes detailing the requests, responses and objects of API SOAP. SDKpayline.dll This file contains the main class which allows the creation of SOAP messages as well as other specific classes that carry out and manage precise requests and responses. For example: doauthorizationrequest, docapture.the App_GlobalResources directory groups the kit parameter files together. Resource.resx This file contains the parameters unique to your merchant account such as the merchant ID, the service access key, etc Presentation of the JAVA SDK Kit contents 11/35

12 The SDK JAVA is made up of the following: notice of development kit installation. a function library allowing the use of API functions an example of web application using the SDK. Structure and functions When you unzip the development kit, you will find the following files: a. direct-doauthorization.html This file presents a form you can use to carry out a debit authorization request. You can adjust settings for the doauthorizationrequest on this page. b. doauthorization.jsp This file contains the JSP code which retrieves the information transmitted by the HTML form and uses the library to carry out an authorization request. c. direct-docapture.html This file presents a form you can use to carry out a request to validate an accepted authorization. You can adjust settings for the docapturerequest on this page. d. docapture.jsp This file contains the JSP code which retrieves the information transmitted by the HTML form and uses the library to carry out a validation request. e. direct-dorefund.html This file presents a form you can use to carry out a refund request. You can adjust settings for the dorefundrequest on this page. f. dorefund.jsp This file contains the JSP code which retrieves the information transmitted by the HTML form and uses the library to carry out a refund request. The KitPayline.zip archive groups the classes detailing the requests, responses and objects of the API SOAP. KitPayline.jar This file contains the main class which allows the creation of SOAP messages as well as other specific classes that carry out and manage precise requests and responses. For example: doauthorizationrequest, docapture. the messages.properties file which groups together the kit parameter files This file contains the parameters unique to your merchant account such as the merchant ID, the service access key, etc. 12/35

13 3.5. SDK Configuration Once the unzipped kit is on the server, the following parameters must be configured: MERCHANT_ID: Merchant account ID ACCESS_KEY: the access key associated with your merchant account, CONTRACT_NUMBER: the contract number identifying your point of sale and default payment method, PRODUCTION: indicator allowing you to go from the authorization environment to production easily. Optional parameters: PAYMENT_ACTION: the default payment method code, PAYMENT_METHOD: the default payment method, SECURITY_MODE: the default security mode code, LANGUAGE_CODE: the default language to be displayed ISO code, CONTRACT_NUMBER_LIST: this variable must be void ( ). PROXY_HOST: your internet proxy URL, PROXY_PORT: your internet proxy communication port, PROXY_LOGIN: user ID required by your internet proxy, PROXY_PASSWORD: user password required by your internet proxy SDK and example codes advice and limitations Redunicre suggests interface source code examples in the development kits (SDK). You can use these, adapting them to the technical restrictions specific to your application. Redunicre cannot be held responsible for the incorrect execution, integration or update of the interface used. In using this example code, you recognise and accept that you are responsible for the implementation of the interface, and accept all technical and financial risks linked to the partial or total use of the example code presented by Redunicre. Redunicre accepts and authorises you to use the interface as part of the service. 13/35

14 4. Connection 4.1. Security requirements 1. Please adhere to the rules below in order to maintain secure communication with the payment system. 2. You must use a HTTPS connection secured by SSL V3 (SSL V2 is not authorized). 3. When you request payment using the API, you are obliged to enter your Merchant ID and Access Key to carry out an http authentication. The payment system will decline the request if it is not correctly authenticated. 4. Never give out your Merchant Access Key to another person. The payment system uses your access key to identify you as the sender of payment requests. 5. We will also ask you to verify the authenticity of the server certificate presented to you at HTTPS connection before sending data or carrying out HTTP authentication. This involves ensuring that: o The certificate belongs to us, o The certificate is signed by a trustworthy certification authority, o The certificate is still valid (neither expired nor revoked). HTTP authentication methods We use the HTTP Basic Authentication mechanism to authenticate member merchants. This paragraph explains how HTTP authentication functions and how to implement it in the web services customer code. HTTP Basic Authentication Your merchant ID is and your access key is DJMESHXYou6LmjQFdH, you must encode in base64 the value of :DJMESHXYou6LmjQFdH. The chain obtained must be added to the HTTP header as in the example below: Authorization : Basic MTIzNDU2Nzg5MdpESk1FU0hYWW91NkxtalFGZEg= ID and access key are automatically encoded in base64 and added to the HTTP header according to the programming language. Thanks to this function, exchanges between your applications and the payment system are secured, and by way of the SSL V3 protocol, you ensure: authentication of all parties: your servers and our servers, the integrity of messages, data encryption. 14/35

15 4.2. Test environment URL (homologation) The free-access authorization environment allows you to carry out tests without proceeding to real payment. WSDL schema: The API WSDL schemas are accessible at the following addresses: Homologation Schema: o Homologation Web Service URL: o User interface: Merchant Admin centre: o Production environment URL This environment allows real transactions to be performed. WSDL schema: The API WSDL schemas are accessible at the following addresses: Production Schema: o Production Web Service URL: o User interface: Merchant Admin centre: o 15/35

16 5. API functions The payment system API is based on "Web Service" standard components, which include the SOAP protocol and the WSDL and XSD definition languages. These standards are supported by a large range of development tools on multiple platforms. The use of the Java Axis2 customer with XMLBeans is strongly advised as it guarantees service continuity if Web Services is developed. The use of Java Axis2 is not advised with ADB. The payment system API covers the following functions: Method doauthorization docapture dorefund transactionsearch gettransactiondetails Description Carry out payment authorization requests Validate an accepted payment request Refund a payment using an accepted authorization number Obtain a list of transactions corresponding to search criteria entered by the user. Obtain payment details of any nature Do Authorization The do Authorization function carries out a debit authorization request with your bank s authorization server. Request to send The doauthorizationrequest must have the following structure: REQUEST o PAYMENT o CARD o ORDER ORDER_DETAILS (occurrences 0 100) o BUYER o AUTHENTICATION3DSECURE o PRIVATE_DATA (occurrences 0 100) PRIVATE_DATA_LIST 16/35

17 Element Payment.Amount Description Transaction amount in the smallest currency unit Require d Type E.g.: yes N12 The value 100 corresponds to 1 Payment.Currency Payment currency code yes N3 978 : Euros Payment.Action Payment function code yes N3 100 : Authorization 101 : Authorization + validation Payment.Mode Please use CPT yes AN3 CPT: Cash Payment.ContractNumber The code or number of your mail order yes AN50 contract which shows the method of payment you wish to use Payment.DifferedActionDate Please leave this field empty no AN8 Card.Number Card number yes N19 Card.Type Type of card used for the transaction yes AN40 MCVISA: visa / mastercard See Table: Payment Method List for a complete list in the appendix Card.ExpirationDate Card expiry date no 3 N4 Format to follow: mmyy Card.CVX Security code on the back of the credit no 3 N10 card Card.OwnerBirthdayDate Birthday of the card s owner no 3 N6 Format to follow: ddmmyy Card.Password Encrypted password: no 3 AN16 Order.Ref Order reference. This reference must be unique because it will be used to check for duplicate orders. Yes AN Order.Origin Order origin. No AN50 SVI_#12 Order.Country Order.Taxes Order.Amount The country code in which the order was placed. The amount of taxes added to the order in the smallest currency unit. Order total in the smallest currency unit Usually the same amount as Payment.Amount No AN3 PT No N12 The value 100 corresponds to 1 Yes N12 The value 100 corresponds to 1 Order.Currency The currency code used to place the Yes N3 978 : Euros order. Order.Date The date the order was placed with the merchant No AN18 Format to follow: dd/mm/yyyy HH24:MI Order.Details Details of articles ordered No -{}- OrderDetails table Buyer.LastName Buyer s surname No AN50 Buyer.FirstName Buyer s first name No AN50 Buyer. The buyer's address No AN150 Buyer.ShippingAddress. Building name or number No AN100 17/35

18 Name Buyer.ShippingAddress. Street name No AN100 Street1 Buyer.ShippingAddress. 2 nd line of address No AN100 Street2 Buyer.ShippingAddress. City No AN40 CityName Buyer.ShippingAddress. Post code No AN20 ZipCode Buyer.ShippingAddress. Country No AN2 Country Buyer.ShippingAddress. Telephone number No AN15 Phone Buyer.AccountCreateDate Date the buyer s account was created No AN8 Format to follow: dd/mm/yy AccountAverageAmount Average buyer amount No N10 Buyer.AccountOrderCount This buyer's order number No N10 Buyer.WalletId Please leave this field empty No² AN50 PrivateDataList Your personal info No The PrivateData table above Authentication3DSecure.md Sent back as POST by ACS No 4 AN20 Authentication3DSecure.pares Sent back as POST by ACS No 4 AN Authentication3DSecure.xid Unique transaction ID No AN20 Do not use, obsolete field Authentication3DSecure.eci Authentication3DSecure.cavv Authentication3DSecure.cavvAlg orithm Electronic Commerce Indicator. To pass in authorization Cardholder Authentication Verification Value determined by ACS. Positive integer specifying the formula used for CAVV generation. Possible values are: 0 = HMAC (SET TransStain), 1 = CVV, 2 = CVV with ATN, 3 = MasterCard AAV No AN2 Do not use, obsolete field No AN26-28 Do not use, obsolete field No AN20 Do not use, obsolete field Authentication3DSecure.vadsRes Summary of 3DSecure operations No AN4 Do not use, obsolete field ult 2 Do not fill in for this function. 3 Please refer to the Table: List of obligatory fields by card type in the appendix. 4 Mandatory for all 3DSecure transactions. For each order detail (OrderDetails): 18/35

19 Element Comment Required Format E.g.: Ref Article reference No AN50 Price Transaction amount in the smallest currency unit No N12 Quantity Number of articles No N5 Comment Comment No For all private data (PrivateData): Element Comment Required Format E.g.: Key The key allows you to filter your transactions Yes AN50 user Value Value associated with the key Yes AN50 dupond or durand, etc Return response The doauthorizationresponse" message is the reply given by the payment system for a debit authorization request. This will allow you to obtain the unique transaction number on the payment system and the debit authorization number issued by your bank. The response has the following structure: RESPONSE o RESULT o TRANSACTION o AUTHORIZATION Element Description Format E.g.: Result Code The Web service s return code: N5 For a complete list see the List of return codes table in : Transaction approved the appendix 023xx: Invalid Transaction 01xxx: Transaction refused 021xx: Internal Error Result.ShortMessage Short transaction result message AN50 Result.LongMessage Transaction result message AN255 Transaction.Id Unique transaction ID AN50 Transaction.IsPossibleFraud This indicator is calculated according to AN1 1 = There is a risk of fraud the criteria defined by the salesperson 0 = There is no detected fraud risk Transaction.isDuplicated This indicator is sent when a AN1 1 = There is a risk of fraud transaction is duplicated 0 = There is no detected fraud risk Transaction.Date Date and time of the transaction AN16 Format: dd/mm/yyyy HH24:MI Transaction.fraudResult Fraud code AN50 Transaction.explanation Refusal reason in case of fraud AN50 Transaction.ThreeDSecure This indicator is returned during AN1 Y = Transaction in 3DSecure mode 3DSecure transactions Y = Transaction in non 3DSecure mode Transaction.score Fraud scoring possibility N5 Score from 0 to 10 19/35

20 Authorization.Number The authorization number issued by the buyer's authorization server. This field will be filled in if the authorization request is approved*. N Authorization.Date Date and time of the authorization AN16 Format: dd/mm/yyyy HH24:MI * - according to your account s settings, the payment system can approve payment without making an authorization request. In this case, the authorization number will be empty DoCapture The do Capture function requests validation of an accepted authorization. Once the validation is taken into account, the payment system carries out a payment request remittance with your bank. Request to send The docapturerequest request must have the following structure: REQUEST o PAYMENT o PRIVATE_DATA_LIST PRIVATE_DATA Element Description Require d Type E.g.: TransactionID Authorization transaction ID yes N50 Payment.Amount Payment.Currency Payment.Action Transaction amount in the smallest currency unit Payment currency code Please use 978 for Euros Payment function code Please use 201 for Validation. yes N12 The value 100 corresponds to 1 yes N3 978 : Euros Yes N3 201 : Validation Payment.Mode Please use CPT for Cash Yes AN3 CPT: Cash Payment.ContractNumber Please leave this field empty Yes AN50 Payment.DifferedActionDate Please leave this field empty no AN8 PrivateDataList Your personal info No The PrivateData table above Return response The docaptureresponse message is the response to a validation request for a debit authorization. The response has the following structure: RESPONSE 20/35

21 o o RESULT TRANSACTION Element Description Format E.g.: Result Code The Web service s return code: N5 For a complete list see the List : Transaction approved of return codes table in the 023xx: Invalid Transaction appendix 01xxx: Transaction refused 021xx: Internal Error Result.ShortMessage Short transaction result message AN50 Result.LongMessage Transaction result message AN255 Transaction.Id Unique transaction ID AN50 Transaction.IsPossibleFraud This indicator is calculated according to the AN1 1 = There is a risk of fraud criteria defined by the salesperson 0 = There is no detected fraud risk Transaction.isDuplicated This indicator is sent when a transaction is AN1 1 = There is a risk of fraud duplicated 0 = There is no detected fraud risk Transaction.Date Date and time of the transaction AN16 Format:dd/mm/yyyy HH24:MI 5.3. DoRefund The dorefund function is used to request a refund for a validated payment. For e-payments, a validated payment is an accepted and validated debit authorization. Send request The dorefundrequest request must have the following structure: REQUEST o PAYMENT o PRIVATE_DATA_LIST PRIVATE_DATA Element Description Required? Type E.g.: TransactionID Authorization transaction ID yes N50 Payment.Amount Transaction amount in the smallest currency unit yes N12 The value 100 corresponds to 1 Payment.Currency Please use 978 for Euros yes N3 978: Euros Payment.Action Please use 421 for Reimbursement yes N3 421: Reimbursement Payment.Mode Please use CPT yes AN3 CPT: Payment in full Payment.ContractNumber The same as in the Authorization call yes AN50 Payment.DifferedActionDate Please leave this field empty no AN8 21/35

22 Comment Description of reason for no AN255 reimbursement. May be consulted via the transaction statement which can be accessed through the Merchant Admin Centre. PrivateDataList Your personal info no The PrivateData table above Return response The dorefundresponse" message is the reply given for a reimbursement request. The response has the following structure: RESPONSE o RESULT o TRANSACTION Element Description Format E.g.: Result Code The Web service s return code: N5 See message and return code for : Transaction approved a complete list in appendix 023xx: Invalid Transaction 01xxx: Transaction refused 021xx: Internal Error Result.ShortMessage Short transaction result message AN50 Result.LongMessage Transaction result message AN255 Transaction.Id Unique transaction ID AN50 Transaction.IsPossibleFraud This indicator is calculated according to the criteria AN1 1 = There is a risk of fraud defined by the merchant. 0 = There is no detected fraud risk Transaction.isDuplicated This indicator is sent when a transaction is AN1 1 = There is a risk of fraud duplicated 0 = There is no detected fraud risk Transaction.Date Date and time of the transaction AN16 Format: dd/mm/yyyy HH24:MI 5.4. Transaction Search The transaction search function is used to obtain a list of transactions that correspond to search criteria entered by the user. Request to be sent The transactionssearchrequest request is used to search for one or more transactions. The request has the following structure: REQUEST 22/35

23 Element Description Require d? Type E.g.: TransactionID The transaction ID no AN50 OrderRef The merchant s order reference. no AN50 startdate Start date of the transaction search period. no Date7 enddate End date of the transaction search period. no Date7 ContractNumber The transaction s related contract number no AN50 AutorizationNumber Transaction authorization number no AN6 ReturnCode Result code sent to the user no AN5 PaymentMean The method of payment used no AN3 TransactionType The type of transaction no N3 Name The buyer's surname no AN50 FirstName The buyer's first name no AN50 The buyer's address no AN150 cardnumber The card number used for the transaction no AN20 Currency The currency code used for the transaction no N3 minamount The minimum transaction amount no N12 maxamount The maximum transaction amount no N12 walletid The wallet ID used for the transaction no AN50 sequencenumber The transaction sequence number no AN50 Return response The transactionssearchresponse message is the response received following a transaction search request. The response has the following structure: RESPONSE o RESULT o TRANSACTION Element Description Format E.g.: Result Code The Web service s return code N5 See the message and 02500: Operation Successful return code table for a complete list in appendix Result.ShortMessage Short transaction result message AN50 Result.LongMessage Transaction result message AN255 TransactionsList The list of transactions that correspond to the search criteria 5.5. Get Transaction Details The transaction search function is used to obtain details on a payment transaction whatever its status. 23/35

24 Request to be sent The gettransactiondetailsrequest message is used to search for details on a payment transaction. The request has the following structure: REQUEST Element Description Require d? Type E.g.: TransactionID The merchant s transaction reference. no N5 OrderRef The merchant s order reference. no AN50 Return response The message gettransactiondetailsresponse includes: RESPONSE o RESULT o TRANSACTION o PAYMENT o AUTHORIZATION o ORDER ORDER_DETAILS (occurrences 0 100) o BUYER o PRIVATE_DATA_LIST PRIVATE_DATA (occurrences 0 100) Element Description Format E.g.: Result Code The Web service s return code N5 See the message and return code 02500: Operation Successful table for a complete list in appendix Result.ShortMessage Short transaction result message AN50 Result.LongMessage Transaction result message AN255 Transaction.IsPossibleFraud This indicator is calculated according to the criteria AN1 1 = There is a risk of fraud defined by the merchant. 0 = There is no detected fraud risk Transaction.isDuplicated This indicator is sent when a transaction is AN1 1 = There is a risk of fraud duplicated 0 = There is no detected fraud risk Transaction.Date Date and time of the transaction AN16 Format: dd/mm/yyyy HH24:MI Payment.Amount The payment amount. The amount must be given in the smallest currency unit. N12 Payment.Currency ISO payment currency code N3 Payment.Action Payment function code N3 Payment.Mode Payment.ContractNumber You must enter the CPT value to register a scheduled payment. The payment contract number which represents a payment method AN3 AN50 24/35

25 Payment.DifferedActionDate Authorization.Number Date of the action. It must be earlier than today's date + 7 days. The authorization number issued by the buyer's authorization server. This field will be filled in if the authorization request is approved*. AN81 N6 Authorization.Date Date and time of the authorization AN16 Format: dd/mm/yyyy HH24:MI Order.Ref Order reference. This reference must be unique because it will be used to check for duplicate orders. AN50 Order.Origin Order origin. AN50 Order.Country The country code in which the order was placed. AN3 Order.Taxes The amount of tax added to the order in the smallest N12 currency unit. Order.Amount Order total in the smallest currency unit Usually the N12 same amount as Payment.Amount Order.Currency The currency code used to place the order. N3 Order.Date The date the order was placed with the merchant AN18 Order.Details Details of articles ordered Buyer.LastName Buyer s surname AN50 Buyer.FirstName Buyer s first name AN50 Buyer. Buyer's address AN150 Buyer.Phone Buyer s telephone number AN15 Buyer.ShippingAddress. Name Buyer.ShippingAddress. Street1 Building name or number Street name AN100 AN100 Buyer.ShippingAddress. Street2 2 nd line of address AN100 Buyer.ShippingAddress. CityName Buyer.ShippingAddress. ZipCode Buyer.ShippingAddress. Country Buyer.ShippingAddress. Phone City Post code Country Telephone number AN40 AN20 AN2 AN15 Buyer.AccountCreateDate Date the buyer s account was created AN8 Buyer.LastName Buyer s surname AN50 PrivateDataList The merchant's personal details. N50 25/35

26 6. Appendices 6.1. Test Cards Card number CVV Expiry Date: any in the future 6.2. Messages and return code The table below lists all the return messages and codes. The following codes and messages will be sent under the Result subject: Result code Short message Long message Transaction approved Transaction approved Transaction refused Do not honor Transaction refused Card expired Transaction refused Contact your bank for authorization Transaction refused Contact your bank for special conditions Transaction refused Invalid merchant Transaction refused Invalid amount Transaction refused Invalid card number Transaction refused Expenses not accepted Transaction refused This account does not exist Transaction refused This function does not exist Transaction refused Amount limit Transaction refused Invalid PIN code 26/35

27 01118 Transaction refused Card not registered Transaction refused This transaction is not authorized Transaction refused Transaction refused by terminal Transaction refused Debit limit exceeded Transaction refused Security violation Transaction refused Debit transaction frequency exceeded Transaction refused Inactive card Transaction refused Invalid PIN format Transaction refused Invalid ctrl PIN key Transaction refused Counterfeit suspected Transaction refused Invalid cvv Transaction refused Invalid bank Transaction refused Invalid currency Transaction refused Invalid currency conversion Transaction refused Max amount exceeded Transaction refused Max uses exceeded Transaction refused GTM Internal Error Transaction refused Do not honour Transaction refused Card expired Transaction refused Fraud suspected Transaction refused Maximum No. of attempts reached Transaction refused Special condition Transaction refused Card lost Transaction refused Card stolen Transaction refused Card bin not authorized Transaction refused Invalid transaction Transaction refused Bad format request Transaction refused Card provider server error Transaction refused Bank server Internal error Transaction refused Card provider server unknown or unavailable Transaction refused Transaction already exists Transaction refused Transaction cannot be found Transaction refused Transaction is refused Transaction refused Bank server unavailable Transaction refused Bank server communication error Transaction refused Invalid bank server response code Transaction refused Invalid format for bank server response Internal Error Internal Error Transaction refused External server communication error Transaction Refused Connection timeout, please try later Invalid Transaction Transaction ID is invalid Invalid Transaction Transaction is invalid. 27/35

28 02303 Invalid Transaction Invalid contract number Invalid Transaction No transaction found for this token Invalid Transaction Invalid field format Operation Refused Token is still valid Invalid Transaction Invalid custom page code Operation Refused Invalid value for payment mode Mass Transaction Successful Mass Transaction Successful Mass Transaction Warning Some transactions failed Mass Transaction Failed Waiting for processing Mass Transaction Failed No mass processing found Operation Successful Operation Successful Operation Successful with warning Operation Successful but wallet will expire Operation Refused Wallet with the same identifier exist Operation Refused Wallet does not exist Operation Refused Cannot update Surname and Firstname Operation Refused Wallet is disabled Operation Refused Wallet can not operate on scheduled date Operation Refused Cannot find payment record Operation Refused Payment record is disabled Operation Refused Invalid recurring option Operation Refused Cannot find payment record Operation Refused Wallet is not supported for this card Operation Refused Surname and Firstname required for wallet Operation Refused Wallet ID required for wallet Authentication Failed Username/Password is incorrect Authentication Failed Account is locked or inactive Authentication Failed Client certificate is disabled Access Refused You do not have permissions to make this API call 100xx Transaction refused Paypal authentification Failed. See more details in administration centre 101xx Transaction refused Paypal internal error. See more details in administration centre 102xx Transaction refused Paypal internal error. See more details in administration centre 103xx Transaction refused Paypal internal error. See more details in administration centre 104xx Transaction refused Paypal bank server error. See more details in administration centre 105xx Transaction refused Paypal fraud suspected. See more details in administration centre 106xx Transaction refused Paypal authorization or capture refused. See more details in administration centre 107xx Transaction refused Paypal address verification failed. See more details in administration centre 28/35

29 6.3. LCLF error messages and return codes The table below lists all the LCLF return messages and codes. The following codes and messages will be sent under the Result subject: Code Message OK Fraud suspected Fraud detected 041XX Input error Missing field Incorrect RuleName Duplicate data Field value must be null Incorrect field format 043XX Output error Data not found Empty list Configuration not found 049XX System error System error Unauthorized service access 6.4. Timeout management The maximum response time is 30 seconds. If you do not receive a response, you may make a new request. The payment system checks your requests and identifies duplicates. The response sent will refer to the first request Identifying duplicate requests The payment system checks your requests and identifies duplicates using the following information: Order Ref: your unique order reference number Payment Amount: the requested payment total Payment Currency: the requested payment currency Card Number: your customer s card number Card ExpirationDate: your customer s card expiry date Payment ContractNumber: your mail order contract No.(Optional) the specific details of private cards. 29/35

30 If a request is considered to be a duplicate of a previous request, i.e. all the fields listed above are identical, the payment system will adopt the following procedure: will detect that the request is identical to a previous request (within a period of 24hrs) will register the request will generate the same results as for the first request (transaction ID, authorization number etc.) but the isduplicated field will have the value of Reminder of how authorization/validation works The authorization and validation functions provide merchants with a way of obtaining payment from their customers. A transaction authorization means that payment details are validated and that the transaction amount is available on the buyer's credit card. The transaction amount is reserved within the customer s available credit card limit until the transaction is captured, cancelled or the authorization period of 7 days expires. Validation confirms the debit order for a pre-accepted debit authorization from the buyer and informs bank servers of the transaction between the buyer and merchant. Once the authorization is issued, the following actions may be done throughout the 7 day period of its validity: An (overall) validation of the transaction authorization amount, A partial validation of the transaction authorization amount, This means that a part of the authorised amount may be validated. This action may be done as many times as wished so long as the total of partial captures does not exceed the transaction authorization amount. Once the payment is validated i.e. the transaction transferred to the merchant s bank; it is possible to request a reimbursement over the following 6 months Card Type List This table shows the possible values for the type field of the Card subject. Code Card name Parent network MCVISA Mastercard / Visa Mastercard / Visa 30/35

31 6.8. List of mandatory fields by card type This table shows the obligatory fields by the Card subject type. Code Card No. Max. length Oblig. Security code Max. Oblig. length Expiry date required Date of birth required Password required MCVISA 19 Y 4 Y Y N N 6.9. Action Type List This table shows the possible values for the action field of the Payment subject. Code Type 100 Authorization 101 Authorization + validation Countries List Country codes are defined by the ISO standard. This table presents a non-exhaustive list of the possible values for the "country" field in the Order subject. Country code FR DE GB ES IT PT Country name FRANCE GERMANY UNITED KINGDOM SPAIN ITALY PORTUGAL 31/35

32 6.11. Languages List Languages are defined by the ISO standard. This table presents an non-exhaustive list of the possible values for the "languagecode" field in the dowebpaymentrequest subject. Country code fra ger eng spa ita pt Country name FRENCH GERMAN ENGLISH SPANISH ITALIAN PORTUGUESE Amounts to send and return codes simulation This table presents the list of amounts to send to simulate a return code from your bank s authorization server. Not all return codes are simulated therefore: authentication errors, internal errors etc. You can use them in the accreditation environment. Amount to be sent Return code /35

33 Glossary The paragraph below details the monetary and technical terms used in this document. Job domain Merchant The term merchant is used to describe a private or public entity which produces or makes available goods or services, and "monetizes" the transaction. Merchants can be: an invoicer, a public organisation, an e-merchant, etc. Card accepter A merchant: the person who accepts the card and presents the buyer with the transaction details. Buyer The Client / Cardholder: the person who pays. Authorization Payment agreement by the card issuer (cardholder s bank or delegated organisation). Mail order contract Mail order contract linking a merchant to their bank. Card issuer Organisation (or agent) which has provided the card holder with a payment card. CPC Merchant Processing Centre to authorise and validate any particular merchant. 33/35

34 CVX2 The code CVC2 / CVV2 is the code made up of the three final numbers on the back of most bank cards. This number is checked by banks: it appears only on the back of bank cards, and avoids payments being made with a stolen card number. The code CVV2 is found on the back of all VISA cards. The CVC2 code is found on the back of all EuroCards / Mastercards issued after April 1 st FAF Fight against fraud. PCI Payment Card Industry: standardising organisation in the card payment sector. Amongst other things, it defines the regulations concerning storage, processing and transmission of cardholder information. Point of sale The point of sale is the entry point (website, svi, etc.) for which the merchant wants to install secure payment functions. The point of sale is described in the system using: Name, Currency, Language, Address, Bank code, Sort code, Account number, RIB, URL. Cardholder Customer with a payment card issued following a holder s agreement with their bank. Transfer Merchant / buyer account debit / credit. Transaction Credit, debit or cancellation operation. Homologation environment Also known as test environment, this free access environment allows tests to be carried out without passing to the official payment stage. Production environment Receipt This environment allows real transactions to be performed. Also known as till receipt, this receipt is just like a traditional receipt given at payment. Technical domain API Application Programming Interface. Interface for programming languages, allowing an application to access system programmes, in order to, for example, send, receive or extract data. Certificate The certificate is an electronic document used to authenticate the participants in the electronic transaction, such as merchants, cardholders, buyers and senders. SSL Date encrypting protocol verifying the integrity of messages and server authentication Authentication A verification process to identify individuals or organisations. Various authentication checks are carried out to accept the payment. 34/35

35 For example: - server level: checks if the server is authorised to contact us and exchange information with the payment system - new user: controls the customer s access key which uses a user ID and password. Authorization Check service access permission. User session Connection established between an internet browser and a web server. Allows the transfer of context data during internet browsing. Authentication token This token is delivered when a web payment initialization request is made. This allows the payment system to authenticate the user as they browse the payment pages. 35/35