Implementation guide - PayZen · Implementation guide Document version 3.8. Contents 1. HISTORY OF...

Payment by token- Recurring payment

Implementation guide

Document version 3.8

Contents

1. HISTORY OF THE DOCUMENT...................................................................................................... 4

2. OBTAINING HELP.............................................................................................................................. 8Viewing online documentation...........................................................................................................................8Getting in touch with technical support.............................................................................................................8

3. MANAGING PAYMENTS BY TOKEN..............................................................................................9

4. COMPATIBLE PAYMENT METHODS......................................................................................... 10

5. TOKEN SHARING.............................................................................................................................12

6. MANAGING TOKENS VIA THE MERCHANT BACK OFFICE..................................................136.1. Signing in to the Merchant Back Office...................................................................................................136.2. Creating a token in Test mode..................................................................................................................136.3. Creating a token in Production mode....................................................................................................... 176.4. Updating a token....................................................................................................................................... 196.5. Canceling a token......................................................................................................................................216.6. Creating a recurring payment....................................................................................................................216.7. Canceling a recurring payment................................................................................................................. 24

7. MANAGING TOKENS VIA THE PAYMENT FORM................................................................... 257.1. Creating a token without payment............................................................................................................ 267.2. Updating information associated with the token...................................................................................... 277.3. Creating a token during a payment...........................................................................................................287.4. Creating a token during a recurring payment........................................................................................... 297.5. Creating a token during creation of a recurring payment with payment.................................................. 307.6. Payment by token......................................................................................................................................31

Payment by token and Liability shift...................................................................................................317.7. Using a token to create a recurring payment............................................................................................327.8. Updating information associated with the token during a payment......................................................... 33

8. LIFECYCLE OF A RECURRING PAYMENT.................................................................................34

9. LIFECYCLE OF A RECURRING PAYMENT WITH ANTICIPATEDAUTHORIZATION............................................................................................................................35

9.1. List of authorization request return codes................................................................................................ 379.2. E-mail notification in case of installment rejection..................................................................................38

10. ESTABLISHING INTERACTION WITH THE PAYMENT GATEWAY................................. 3910.1. Similarities with single payment.............................................................................................................3910.2. Differences with single payment.............................................................................................................3910.3. Setting up the payment page URL..........................................................................................................4010.4. Identifying yourself when exchanging with the payment gateway.........................................................4010.5. Choosing between Test and Production modes...................................................................................... 4110.6. Managing the interaction with the merchant website............................................................................. 4210.7. Managing security................................................................................................................................... 44

11. SETTING UP NOTIFICATIONS...................................................................................................4611.1. Setting up notifications............................................................................................................................4611.2. Setting up the Instant Payment Notification...........................................................................................4611.3. Instant Payment Notification URL on an operation coming from the Merchant Back Office................ 4711.4. Setting up a notification upon creating a recurring payment..................................................................4811.5. Setting up a notification on batch authorization.....................................................................................4911.6. Configuring e-mails sent to the buyer.................................................................................................... 50

11.7. Activating the automatic retry.................................................................................................................50

12. GENERATING A PAYMENT FORM........................................................................................... 5312.1. Creating a ‘Create a token without payment’ form................................................................................ 5512.2. Creating a form 'Edit information associated with the token'.................................................................5512.3. Creating a form 'Create a token during a payment'................................................................................ 5612.4. Creating a ‘Create a token when making a recurring payment’ form.................................................... 5712.5. ‘Creation of a token when a creating a recurring payment with payment’ form.................................... 5912.6. Creating a form 'Payment by token'....................................................................................................... 6112.7. Creating a ‘Use a token to create a recurring payment’ form................................................................ 6212.8. Creating a form 'Edit information associated with the token during a payment'.................................... 64

13. USING ADDITIONAL FEATURES.............................................................................................. 6513.1. Defining a different amount for the first n installments......................................................................... 6613.2. Defining the currency for creating or updating a token......................................................................... 66

14. CUSTOMIZING THE ELEMENTS OF THE PAYMENT PAGE............................................... 6814.1. Overriding the custom template..............................................................................................................6814.2. Managing the payment methods offered to the buyer............................................................................ 6914.3. Selecting a different language.................................................................................................................7014.4. Modifying the languages available to the buyer.....................................................................................7114.5. Modifying the name and the URL of the shop.......................................................................................7214.6. Changing the name of the "Return to shop" button................................................................................73

15. COMPUTING THE SIGNATURE................................................................................................. 74

16. SENDING THE PAYMENT REQUEST....................................................................................... 7616.1. Redirecting the buyer to the payment page............................................................................................ 7616.2. Processing errors......................................................................................................................................7616.3. Managing timeouts.................................................................................................................................. 78

17. ANALYZING THE PAYMENT RESULT..................................................................................... 7917.1. Retrieving data returned in the response................................................................................................ 8017.2. Computing the IPN signature..................................................................................................................8217.3. Comparing signatures.............................................................................................................................. 8317.4. Analyzing the nature of the notification................................................................................................. 8417.5. Processing the response data...................................................................................................................85

Creating a token without payment....................................................................................................... 85Updating token details.......................................................................................................................... 87Creating a token during a payment......................................................................................................89Creation of a token during a recurring payment..................................................................................92Creation of a token when a creating a recurring payment with payment............................................ 95Payment by token................................................................................................................................. 98Creating a recurring payment............................................................................................................. 100Updating information associated with the token during a payment...................................................102

18. APPENDIX.....................................................................................................................................10518.1. Automatically creating a recurring payment via Web services............................................................ 10518.2. Automatically canceling a recurring payment via Web services..........................................................105

19. DATA DICTIONARY................................................................................................................... 106

Payment by token- Recurring payment - Document version 3.8

All rights reserved - 4 / 219

1. HISTORY OF THE DOCUMENT

Version Author Date Comment

3.8 Lyra Network 21/10/2019 • Update of compatible payment methods.

• Addition of a chapter on the payment guarantee during apayment by token.

• Update of the description of the vads_sub_desc field in thechapter Generating a payment form.

3.7 Lyra Network 05/08/2019 • The hash algorithm is now available via Settings > Shop, Keystab.

• Addition of the vads_identifier field as an input parameterwhen creating a token.

• Addition of the Risk analysis details category in the Datadictionary.

• vads_threeds_auth_type: the field is always present in theresponse and can be empty.

• The hash algorithm is now available via Settings > Shop, Keystab.

• Clarification provided on the computation of the IPN signature.

• Clarification provided on the format of the vads_trans_dateand vads_presentation_date fields.

• Clarification provided on the format ofthe fields: vads_product_label, vads_cust_zip,vads_order_id, vads_cust_first_name, vads_cust_last_name,vads_cust_phone, vads_cust_cell_phone, vads_cust_id,vads_cust_city, vads_cust_address.

• vads_auth_result: correction of field format (an..11)

• vads_contracts: Possibility to force the Terminal ID to be used.

3.6 Lyra Network 22/05/2019 Clarifications provided on the methods of creation andtermination of recurring payments via web services.Data dictionary: update of vads_trans_date.

3.5 Lyra Network 26/03/2019 • Addition of a clarification on the deletion on data in the chapterManaging payments by identifier.

• Addition of the time of recurring payment creation in thechapter Managing payments by identifier.

• Update of screenshots in chapters Creating a token in Testmode and Creating a token in Production mode.

• Update of screenshots in Creating a recurring payment via theMerchant Back Office

• Addition of the chapter Defining the currency for creating orupdating a token.

• Data dictionary:

• Clarification added about the format of thevads_product_qty field.

• Addition of the vads_presentation_date field in theTransaction details section.

• Clarification added about the format of the vads_identifierfield.

• Clarification added about the format of thevads_subscription field.



Version Author Date Comment• Removal of the fields vads_ext_info_donation,

vads_ext_info_donation_recipient,vads_ext_info_donation_recipient_name,vads_ext_info_donation_merchant,vads_ext_info_donation_contribution andvads_risk_primary_warranty.

3.4 Lyra Network 19/12/2018 • Rewrite of chapter Analyzing the payment result

• Creation of a “Verification” transaction when requesting anupdate or creation tokens without payment.

• Data dictionary:

• Addition of the vads_bank_label field.

• Addition of the vads_tax_rate field.

• Addition of the vads_pretax_amount field.

• Addition of the vads_totalamount_vat field.

• Addition of the vads_wallet field.

• Update of the vads_ship_to_legal_name field description.

• Update of the vads_payment_src field description.

• Update of the values of the vads_bank_product field.

• Update of the vads_tax_amount field description.

• New value for the vads_trans_status : ACCEPTED field.

3.3 Lyra Network 27/11/2018 • Addition of dedicated chapter containing the list ofcompatible payment methods.

• Remove references to use cases S1, S2, S3, etc

• Use of the term Token instead of Buyer ID.

• Update of the vads_subscription field description.

3.2 Lyra Network 07/11/2018 • Addition of a note on taking into account 2 algorithms whenchanging an algorithm.

• Data dictionary

• vads_ext_info_bil_date_of_birth andvads_ext_info_ship_date_of_birth: update ofdescriptions.

• vads_iframe_options: addition of field description.

• vads_override_payment_cinematic: update of values.

• vads_operation_type: addition of the VERIFICATIONvalue.

• vads_product_ext_id: addition of field description.

• vads_requestor: addition of field description.

• vads_sequence_number: clarification provided on severalpayment attempts.

3.1 Lyra Network 17/08/2018 Addition of chapters

• Invalidating a token via the Merchant Back Office

• Instant Payment Notification URL on an operation comingfrom the Merchant Back Office

Update of the Identifying the use cases chapterUpdate of the titles of chapters S1 to S9Update of the Computing the signature chapter.Data dictionary



Version Author Date Comment• vads_payment_action: update of titles

• vads_payment_cards: update of values.

• vads_payment_error: addition of new codes.

• vads_theme_config: addition of the valuesREGISTER_ON_PAYMENT, 3DS_LOGOS and FORM_TARGET

• vads_contracts: update of description and possible values.

3.0 Lyra Network 27/06/2018 • Update of tables in chapters on creating a form (S1 to S9)

• Update of the Computing the signature chapter.

• Update of the chapter Managing errors: addition of messagesfor frequent errors

• Addition of the chapter Overriding the custom template.

• Data dictionary

• Update of the vads_product_label field format.

• Addition of the vads_token_id field.

• Update of the definition and the values of thevads_theme_config field

• Update of the vads_sequence_number field definition.

2.9 Lyra Network 26/06/2018 • Update of the chapter Identifying yourself when exchangingwith the payment gateway: alphanumeric key (certificate).

• Update of the chapter Computing the signature: computationalgorithm

• Update of the chapter Managing errors: addition of messagesfor frequent errors

• Data dictionary

• Addition of vads_avs_result

• Addition of vads_brand_management

• Format update of vads_acquirer_transient_data

• Format update of vads_payment_seq

• Addition of vads_url_post_wallet

• vads_currency: update of the list of supported currencies

• Addition of vads_avs_result

• vads_currency: update of the list of supported currencies

• vads_first_installment_delay: update of the definition

• vads_ext_info: improvement of field definition

• vads_risk_assessment_results: improvement of fielddefinition

• Correction of a field name error: vads_url_refused insteadof vads_url_refusal

• Addition of the vads_cust_address2 field

2.8 Lyra Network 16/01/2018 Addition of a note on rejected authorizations in chapters S1 to S9.

2.7 Lyra Network 03/07/2017 Update of “Defining a different amount for the first ninstallments” chapter.Data dictionary

• Update of the vads_sub_init_amount and vads_sub_amountfields

• Update of the vads_theme_config field



Version Author Date Comment

2.6 Lyra Network 08/03/2017 vads_payment_cards: addition of PAYPAL andPAYPAL_SB aspossible values

2.5 Lyra Network 23/11/2015 Clarification added about identifiers shared by several legalentities.

2.4 Lyra Network 28/08/2015 • Initial version in DITA format.

• Modification of payment pages (responsive).

• Addition of use case S9 – Update of card details withpayment.

Data dictionary

• vads_bank_product: update of the list list of product codesfor a card of CB type.

• vads_risk_analysis_result: addition of values.

2.3 Lyra Network 05/06/2014 Addition of use case S8 – Payment with optional subscription of theholder.

2.2c Lyra Network 02/07/2013 Initial version

This document and its contents are confidential. It is not legally binding. No part of this document may be reproduced and/or forwarded in whole or in part to a third party without the prior written consent of Lyra Network. All rights reserved.



2. OBTAINING HELP

Viewing online documentation

Looking for help? See our online documentation

Germany https://payzen.io/de-DE/faq/sitemap.htmlEurope https://payzen.io/en-EN/faq/sitemap.htmlLatin America (except Brazil) https://payzen.io/lat/faq/sitemap.htmlBrazil https://payzen.io/pt-BR/faq/sitemap.htmlIndia https://payzen.io/in/faq/sitemap.html

We are constantly improving the understanding and proper use of our technical documentation. Weappreciate any constructive remarks on your part.

Please send your comments and suggestions about the documentation to the e-mail [email protected].

Getting in touch with technical support

For technical inquiries or support, you can reach us from Monday to Friday, between 9 a.m. and 6 p.m.

By phone By e-mail

France [email protected]

Europe [email protected]

Latin America (except Brazil) N/A [email protected]

Brazil+55 (11) 3336-9217+55 (11) 3336-9209

[email protected]

India +91 (022) 33864910 / 932 [email protected] via your Merchant Back Office, Help > Contact support

In view of facilitating the processing of your demands, you will be asked to communicate your shop ID (an8-digit number).

This information is available in the “registration of your shop” e-mail or in the Merchant Back Office(Settings > Shop > Configuration).

https://payzen.io/de-DE/faq/sitemap.html

https://payzen.io/en-EN/faq/sitemap.html

https://payzen.io/lat/faq/sitemap.html

https://payzen.io/pt-BR/faq/sitemap.html

https://payzen.io/in/faq/sitemap.html

mailto:[email protected]








3. MANAGING PAYMENTS BY TOKEN

Management of payments by token

The service of Management of payments by token allows merchants to offer their clients the possibility toassociate a token with a payment method, which will facilitate their subsequent payments on the website(without having to re-enter the bank card number).

Tokens allow to:

• Make fast and secure payments.

Avoid filling in bank details when making subsequent payments (1-click payment) for the buyer.

The bank details are stored by the gateway in a highly secure environment, in accordance with the PCI-DSS requirements. Only the token is transferred during the exchange.

• Make recurring payments (subscription).

The service also allows:

• To identify cards that are due to expire, in order to notify the merchant via a file containing the tokenof the expiring card.

• To update the bank details associated with a token via the the payment page, or manually via theMerchant Back Office.

• To manage the update of other buyer details.

In compliance with the rules of security and protection of banking details implemented by PCI DSS, thepayment method details are destroyed after 15 months of non-use of the associated token.

The token will remain visible in the Merchant Back Office and can be updated with new details.

Recurring payment (subscription) management

The recurring payment management service allows merchants to create subscriptions, also known asrecurring payments, with or without an expiry date, within the limits of the card validity period.

When creating a recurring payment, the merchant defines the start date and the recurrence rule to apply.

In TEST mode, transactions are created every hour in order to allow the merchant to easily test the IPNprocessing.

In PRODUCTION mode, transactions are created once a day between midnight and 5:00 a.m.



4. COMPATIBLE PAYMENT METHODS

List of payment methods compatible with Payment by token Management Service:

Network code Payment methodCard types

(vads_payment_cards)Supports payment by token

AMEXGLOBAL American Express card AMEX

ANCV e-Chèque-Vacances E_CV

CARDCOMPLETE JCB card JCB

CARDCOMPLETE Maestro card MAESTRO

CARDCOMPLETE Mastercard card MASTERCARD

CARDCOMPLETE Visa card VISA

CARDCOMPLETE Visa Electron card VISA_ELECTRON

CARDCOMPLETE Visa Vpay card VPAY

CB CB bank card CB

CB Maestro card MAESTRO

CB Mastercard card MASTERCARD

CB Apetiz Meal Voucher card APETIZ

CB Chèque Déjeuner MealVoucher card

CHQ_DEJ

CB 1st generation MastercardMeal Voucher card

EDENRED

CB Sodexo Meal Voucher card SODEXO

CB e-Carte Bleue virtual card E-CARTEBLEUE

CB Visa card VISA

CB Visa Electron card VISA_ELECTRON

CB Visa Vpay card VPAY

GATECONEX Bancontact card BANCONTACT

GATECONEX Diners Club card DINERS

GATECONEX Discover card DISCOVER

GATECONEX Maestro card MAESTRO

GATECONEX Mastercard card MASTERCARD

GATECONEX e-Carte Bleue virtual card E-CARTEBLEUE

GATECONEX Visa card VISA

GATECONEX Visa Electron card VISA_ELECTRON

GATECONEX Visa Vpay card VPAY

GICC Bancontact card BANCONTACT

GICC Maestro card MAESTRO

GICC Mastercard MASTERCARD

GICC Visa VISA

GICC Visa Electron card VISA_ELECTRON

GICC_DINERS Diners Club card DINERS

GICC_DINERS Discover card DISCOVER

GICC_MAESTRO Bancontact card BANCONTACT

GICC_MAESTRO Maestro card MAESTRO

GICC_MASTERCARD Mastercard MASTERCARD

GICC_VISA Visa VISA



Network code Payment methodCard types

(vads_payment_cards)Supports payment by token

GICC_VISA Visa VPAY

GICC_VISA Visa Electron card VISA_ELECTRON

GIROPAY GIROPAY wire transfer GIROPAY

IDEAL iDEAL wire transfer IDEAL

JCB JCB card JCB

KLARNA Klarna invoice payment KLARNA

MASTERPASS Payment by Masterpass wallet MASTERPASS

PAYDIREKT_V2 Paydirekt wire transfer PAYDIREKT

PAYPAL Payment by PayPal PAYPAL

PAYPAL_SB Payment by PayPal - Sandboxmode

PAYPAL_SB

POSTFINANCEV2 Payment by PostFinance Card POSTFINANCE

POSTFINANCEV2 Efinance PostFinance wiretransfer

POSTFINANCE_EFIN

SECURETRADING American Express card AMEX

SECURETRADING Diners Club card DINERS

SECURETRADING Discover card DISCOVER

SECURETRADING JCB card JCB

SECURETRADING Maestro card MAESTRO

SECURETRADING Mastercard MASTERCARD

SECURETRADING Visa VISA

SECURETRADING Visa Electron card VISA_ELECTRON

SECURETRADING Visa Vpay card VPAY

SOFORT Sofort wire transfer SOFORT_BANKING

WIRECARD Maestro card MAESTRO

WIRECARD Mastercard MASTERCARD

WIRECARD Visa VISA

WIRECARD Visa Electron card VISA_ELECTRON

WIRECARD Visa Vpay card VPAY

WIRECARD Euro-Cheque card ECCARD

WIRECARD SEPA DIRECT DEBIT SDD

WIRECARD GIROPAY wire transfer GIROPAY



5. TOKEN SHARING

It is possible to share tokens between several legal entities.

Tokens shared between several legal entities have to be unique and must be generated by the paymentgateway.

However, this feature is subject to conditions. Please contact the customer service of your paymentgateway to know the details.



6. MANAGING TOKENS VIA THE MERCHANT BACK OFFICE

6.1. Signing in to the Merchant Back Office

Sign in the Back Office:

https://de.payzen.eu/vads-merchant/

1. Enter your login.

The login is sent to the merchant’s e-mail address (the subject of the e-mail is Connection identifiers- [your shop name].

2. Enter your password.

The password is sent to the merchant’s e-mail address (the subject of the e-mail is Connectionidentifiers- [your shop name].

3. Click Validate.

After 3 password entry errors, the user’s account is locked. Click on the link Forgotten password orlocked account to reset.

6.2. Creating a token in Test mode

Prerequisites

• The shop must be associated with a distance sale agreement.

• The notification rules must be configured.




The configuration of notification rules allows to receive notifications once a token has been created (or updated). If you haveseveral shops, only one of the shops will receive the notifications, but the created token can be used for payments made in allof the shops of the same company (legal name).

1. Go to the following menu: Settings > Notification rules.

2. Make sure that the “Instant Payment Notification URL on an operation coming from the Back Office”rule is present and enabled.

3. If the rule is not enabled, make a right-click and select Enable the rule.

4. Double-click the rule and make sure that the URL in TEST mode and the URL in PRODUCTION mode arespecified.

For more information on configuring notification rules, see chapter Setting up notifications.

Once the configuration of the notification rule is complete, you can proceed to creating the token.

1. Display the Management > TEST recurring payments menu.

The Token tab appears by default.

2. Click the Create button.

3. Select the Shop to notify from the list if you have several shops.

The token creation window appears.

IMPORTANTIf the Notifications item appears on the display of the token creation window, make sure that the steps listed inPrerequisites have been completed correctly.

4. Enter the Buyer e-mail address.



5. A token is generated by default in the Token ID field. You can click on the button Generate a new IDif you wish.

You also can enter your own token. You must, however, make sure it is unique.

6. Select the payment method from the list.

The presented payment methods depend on the MIDs associated with your shop.

7. Click on the link Test payment method, then on the desired number to automatically enter thedetails of the test payment method.

8. If you wish, you can select the used currency when checking the payment method.

This choice is useful when you have a multi-currency agreement associated with several shops, whereeach shop only supports one currency.

It will always be possible to use the token for making payments in any currency supported by theagreement.

9. Click Next

The buyer details entry page appears.

The Token section reminds you of the specified e-mail and the created token.



10.Fill in the information about the buyer.

These details are useful for buyer identification.

Fields marked with an asterisk (*) are required.

11.Click Create to complete the process.

If all the payment method verification processes have been successfully completed, the token detailwindow appears.

It mentions the Token ID. It corresponds to the newly created token. It can be later used for anotherfinancial operation in your shop(s).

If the “Confirmation e-mail of recurring payment sent to the merchant” notification rule is configuredand enabled, you will also receive:

• the confirmation of registration of buyer’s banking details,

• the buyer’s token that they can later use for another financial operation,

These details can be sent to the buyer (see chapter Setting up notifications).

Warning :

The token will not be created if the authorization or information request is rejected.



You can also manage your recurring payments via the Merchant Back Office after creating the token.

6.3. Creating a token in Production mode

Prerequisites

Once the configuration of the notification rule is complete, you can proceed to creating the token.

1. Display the Management > Recurring payments menu.

The tab Token is displayed by default.

2. Click the Create button.

3. Select the Shop to notify from the list if you have several shops.

The token creation window appears.

IMPORTANTIf the Notifications item appears on the display of the token creation window, make sure that the steps listed inPrerequisites have been completed correctly.

4. Enter the Buyer e-mail address.

5. A token is generated by default in the Token ID field. You can click on the button Generate a new IDif you wish.

You also can enter your own token. You must, however, make sure it is unique.

6. Select the payment method from the list.

The presented payment methods depend on the MIDs associated with your shop.

7. Enter the buyer's card details.

• Card number

• Expiry date

• CVV code



8. If you wish, you can select the used currency when checking the payment method.

This choice is useful when you have a multi-currency agreement associated with several shops, whereeach shop only supports one currency.


9. Click Next

The buyer details entry page appears.

The Token section reminds you of the specified e-mail and the created token.

10.Fill in the information about the buyer.

These details are useful for buyer identification.

Fields marked with an asterisk (*) are required.


If all the payment method verification processes have been successfully completed, the token detailwindow appears.

It mentions the Token ID. It corresponds to the newly created token. It can be later used for anotherfinancial operation in your shop(s).

If the “Confirmation e-mail of recurring payment sent to the merchant” notification rule is configuredand enabled, you will also receive:



• the confirmation of registration of buyer’s banking details,

• the buyer’s token that they can later use for another financial operation,

These details can be sent to the buyer (see chapter Setting up notifications).

Warning :


You can also manage your recurring payments via the Merchant Back Office after creating the token.

6.4. Updating a token

There are two different operations for updating a token:

• Update buyer details

This operation allows to update information about the buyer. It also gives the possibility to update thetoken ID.

• Replace the payment method

This operation allows to update the buyer's payment method. It also gives the possibility to update thetoken ID.

In order to update buyer details

1. Via Management > Recurring payments, search for the token to update.

2. Right-click the token.

3. Click Modify.

4. Click Update buyer details.

The token update page appears. Only editable fields are available for input.

5. Edit the e-mail address, if needed.

6. Generate a new token if you wish to replace the old one.

7. Complete or edit the information about the buyer.

Only editable fields can be updated.

8. Click the Validate button to save the changes.

In order to replace the payment method

1. Via Management > Recurring payments, search for the token to update.


3. Click Replace the payment method

The token update page appears.

4. Generate a new token if you wish to replace the old one.



5. Enter the new information about the buyer’s payment method.

It is possible to replace the details of one payment card with the details of another payment card withinthe limits of the payment methods supported by the shop.

6. Click the Validate button to save the changes.

Warning :

The token will not be updated if the authorization or information request is rejected.

In any case, the merchant will be notified about this update if the Instant Payment Notification URL onan operation coming from the Back Office rule is enabled.



6.5. Canceling a token

IMPORTANT

• Canceling a token will result in canceling all the recurring payments that are currently associated with it.

• A canceled token will remain visible in the Merchant Back Office.

• The data related to the payment method associated with the token will be purged after 15 months of inactivity.

1. Via Management > Recurring payments, search for the recurring payment to cancel.


3. Click the Terminate button.

The token termination wizard opens.

4. Choose if you want to cancel the token immediately or later.

You will then be able to choose the date and time of the cancellation.

5. Click Terminate to complete the process.

6.6. Creating a recurring payment

To help you write the recurring payment rules, we have provided the possibility to create recurringpayments via the Merchant Back Office.

Recurring payments are created on the basis of an existing token.

1. Via Management > Recurring payments search for the token that will be used for creating therecurring payment.


3. Click Create a recurring payment.



4. Select the shop.

5. Select the Validation mode (Automatic or Manual).

6. Click Next.

7. Enter the start date.

8. Enter the fixed amount and the currency of the recurring payment.

It is possible to define additional optional parameters (Initial amount if it is different from the fixedamount and the number of installments with the initial amount).

9. Click Next.



10.Specify the recurrence rule in Simple mode or in Advanced mode.

Check the box Manual edition of the rule if you wish to enable the advanced mode and specify thedesired recurrence rule.

The rule must respect the iCalendar (Internet Calendar) specification, described in the RFC5545 (seehttp://tools.ietf.org/html/rfc5545).

Example of the rule in advanced mode:RRULE:FREQ=YEARLY;BYMONTHDAY=-1;BYMONTH=1,4,7,10;UNTIL=20221231

11.Click Next to display the summary of the recurring payment.


http://tools.ietf.org/html/rfc5545



6.7. Canceling a recurring payment

Note:

A recurring payment remains active until its expiration date.

In case of anticipated cancellation:

• On the day of installment, the merchant must proceed to cancel the automatically created transaction.

• Before or after the installment date, the recurring payment is canceled and no transactions will beautomatically created on the installment date.

• In case of an anticipated authorization, transactions are created 6 days before the installment date. Ifthe cancellation occurs within the 6 days preceding the installment date, the merchant must proceedto cancel the automatically created transaction.

Anticipated authorizations are available only within the CB networks.

1. Via Management > Recurring payments, search for the recurring payment to cancel.

2. Select the recurring payment with a right-click.

3. Click Terminate.

4. Choose if you wish to cancel the token immediately or later.

You will then be able to choose the date and time of the cancellation.

5. Click Terminate to complete the process.



7. MANAGING TOKENS VIA THE PAYMENT FORM

The payment form allows to make the following operations classified according to different cases.

Each of these cases corresponds to a different value of the vads_page_action field.

Use case Value of the vads_page_action field

Creation of a token without payment REGISTER

Update of information associated with the token REGISTER_UPDATE

Creation of a token during a payment REGISTER_PAY

Creation of a token during a recurring payment REGISTER_SUBSCRIBE

Creation of a token during creation of a recurring payment with payment REGISTER_ PAY_SUBSCRIBE

Payment by token PAYMENT

Using a token to create a recurring payment SUBSCRIBE

Update of information associated with the token during a payment REGISTER_UPDATE_PAY

Depending on the use case (value of the vads_page_action field), the payment process from the buyer'spoint of view will be different on the payment page.



7.1. Creating a token without payment

This case corresponds to a simple token creation.

The merchant website transmits buyer details to the payment gateway, in particular the e-mail address,which is mandatory.

1. The buyer verifies the information displayed on the payment page.

2. He or she clicks on the payment method that will be registered.

The payment page displays the buyer details once again and prompts to enter the banking details.

3. If the buyer has selected a bank card, he or she enters:

• the card number,

• the card expiry month,

• the card expiry year,

• the CVV code of the card if there is one.

4. The buyer clicks Validate.

If all the payment method verification processes have been successfully completed, the summaryappears.

It contains the newly created token. It can be later used for another financial operation.

It is possible to send these details to the buyer by e-mail and receive:

• the confirmation of the registration of these banking details on the payment gateway of the shop,

• the buyer's token that they can later use for another financial operation,

Note:

To find out how to send these details by e-mail, see chapter Configuring e-mails sent to the buyer.

Warning :




7.2. Updating information associated with the token

This case corresponds to updating, at the initiative of the buyer, the information related to his or herpayment method and/or his or her personal information.

The merchant website transmits to the payment gateway:

• new information, specifically the e-mail address, that is mandatory,

• the token for update.

The presented pages are identical to the previous case (Creating a token without payment).

Warning :




7.3. Creating a token during a payment

In this case, the parameters necessary for registration are completed by the parameters necessary for apayment request.


1. The buyer verifies the information displayed on the payment page (identity, amount and currency ofthe transaction).

2. He or she clicks on the payment method that will be registered and used.

The payment page appears:

• for the registration:

• information about the buyer's identity,

• entry of buyer's banking details.

• for the payment:

• transaction details (transaction number, amount...).











• confirmation of the payment.

Note:


Warning :




7.4. Creating a token during a recurring payment

In addition to the information used in the case of Creating a token without payment, this use case mustalso include information related to the recurring payment, such as:

• the initial amount of the recurring payment (amount used for the first installment/s) if it is different(optional),

• the amount of the recurring payment (amount of installments or the amount used for the followinginstallments when the first one is different).




The payment page appears. It contains the following information:




• for the recurring payment:

• the number of installments,

• the amount per installment.









The amounts of the recurring payment also appear in the payment summary when the paymentmethod number verification (example: bank card) has been successfully completed.



• confirmation of the registration of the recurring payment.

Note:


Warning :




7.5. Creating a token during creation of a recurring payment withpayment

In this use case, the following information must be visible:

• the buyer details,

• the transaction identifier,

• the recurring payment details (amounts).

Example: an recurring payment of X EUR/ over N months with commission fees to be paid upon takingthe order.




The payment page appears. It contains the following information:




• for the recurring payment:

• the number of installments,

• the amount per installment.


• the amount of commission fees.









The amounts of the recurring payment as well as the commission fees also appear in the paymentsummary when the payment method number verification (example: bank card) has been successfullycompleted.



• confirmation of the registration of the recurring payment,


Note:




Warning :


7.6. Payment by token

Payment by token allows to use a pre-registered token for making single or multiple payments withouthaving to select a payment method and enter banking details.

In this case, a simple confirmation step is presented with a summary of the transaction (number andamount).



An authorization request is made with the payment method associated to the token. If it issuccessfully completed, a summary appears.


• the buyer’s token that can be used later for another financial operation,

• the payment details.

Note:


Note:

When the token is associated with an expired payment method, the gateway automatically suggeststo the buyer to enter the new banking details in order to perform the payment and update theassociated token.


Payment by token and Liability shift

By default, the liability shift in case of a legal dispute cannot be applied to a payment by token.

Even if a 3D Secure authentication was successfully performed when the token was created, the paymentsmade with this token do not automatically benefit from the liability shift.

In order for the liability shift to be applied, the buyer must enter the CVV code of his or her card andproceed to 3D Secure authentication (or strong authentication in case of 3DS2).

Contact sales administration to request the activation of these options.

Note

By default (i.e. without the activation of the option “3D Secure for payments by token”), the details ofthe 3D Secure authentication (vads_threeds_xxxx field), are returned empty in the response, with theexception of the vads_threeds_exit_status field.



7.7. Using a token to create a recurring payment

Once a token has been created, it is possible to add one or several additional recurring payments that willuse this token.

After a new recurring payment has been created, no banking detail entry will be requested. Only aconfirmation on the buyer's part will be needed.



A summary of the created recurring payment appears.


• the buyer's token that they can later use for another financial operation,

• the recurring payment details.

Note:


Warning :




7.8. Updating information associated with the token during a payment

This case corresponds to updating, at the initiative of the buyer, of information related to his or herpayment method and/or of his or her personal information during a payment.


1. The buyer verifies the information displayed on the payment page (identity, amount and currency ofthe transaction, token).

2. The buyer clicks on the payment method that he or she wants to register and use.

The payment page appears:





• transaction details (transaction number, amount...).







If all the payment method verification processes have been successfully completed, the summaryappears with the following message:

Your token has been successfully updated and the payment request has been made.




Note:


Warning :




8. LIFECYCLE OF A RECURRING PAYMENT

The recurring payment starts on its effective date.

The payment gateway starts creating payments following the schedule determined by the recurringpayment rule sent in the form of recurring payment creation (vads_sub_desc field).

Upon each installment, if the Instant Payment Notification URL when creating recurring payments rule isenabled and correctly configured, the merchant website will receive the payment result in their notificationURL (IPN).

In case of failure:

• the merchant will not be notified by e-mail,

• the payment will not be automatically presented once again.



9. LIFECYCLE OF A RECURRING PAYMENT WITH ANTICIPATEDAUTHORIZATION

Thanks to this option, when a payment is rejected for a non-fraud related motive (see chapter List of returncodes of the authorization request), the payment gateway can automatically make another authorizationrequest until the expected capture date at the bank.

As soon as the option is enabled for the shop, recurring payments are created 6 days before the dateanticipated by the recurring payment rule.

It is necessary to enable the Instant Payment Notification URL on batch authorization rule via yourMerchant Back Office (see chapter Setting up a notification on batch authorization).

D-6: Creating a recurring payment

• The authorization request is accepted

• The payment will remain Waiting for capture until the initially scheduled date.

• A call to the notification URL will be triggered if the Instant Payment Notification URL when creatinga recurring payment rule is enabled. The request will contain the following values:

Field name Value

vads_url_check_src REC

vads_trans_status AUTHORISED

• The authorization request is rejected for a fraud-related reason

• The payment is definitively Declined.


Field name Value


vads_trans_status REFUSED

• The authorization request is rejected for a non fraud-related reason.

• The payment will remain Waiting for authorization.


Field name Value


vads_trans_status WAITING_AUTHORISATION

D-5, D-4, D-3: New authorization request triggered automatically

• The authorization request is accepted.


• A call to the notification URL will be triggered if the Instant Payment Notification URL on batchauthorization rule is enabled. In this case, the request will contain the following values:

Field name Value

vads_url_check_src BATCH_AUTO




• The authorization request is rejected for a fraud-related reason.



Field name Value



• The authorization request is rejected for a non fraud-related reason.

• The payment will remain Waiting for capture until the scheduled date.


Field name Value


vads_trans_status WAITING_AUTHORISATION

D-2: Last authorization request triggered automatically

• The authorization request is accepted.



Field name Value



• The authorization request is rejected (regardless of the reason).



Field name Value



D: Capture of the transaction

The payment is automatically captured.

No calls to the Notification URL will be triggered.

Notes

• Payment rejection between D-6 and D-2

When the payment is definitively rejected, you must make sure that the access to the service for whichthe recurring payment was created is canceled on the scheduled date and not on the day when thepayment rejection was received.

• Termination of a recurring payment

When the buyer cancels their recurring payment, the merchant must cancel the already scheduledpayments.



9.1. List of authorization request return codes

The return codes of the authorization request are returned by the issuing bank (if available).



9.2. E-mail notification in case of installment rejection

Case of the option "Anticipated authorization"

When a payment is declined, a notification e-mail is sent to the merchant.



10. ESTABLISHING INTERACTION WITH THE PAYMENTGATEWAY

The merchant website and the payment gateway interact by exchanging data.

To create a payment, this data is sent in an HTML form via the buyer’s browser.

At the end of the payment, the result is transmitted to the merchant website in two ways:

• Automatically by means of notifications called Instant Notification URLs (also called IPN or InstantPayment Notification), see chapter Setting up notifications.

• Via the browser, when the buyer clicks the button to return to the merchant website, see chapterManaging the return to the merchant website.

To guarantee the security of the exchange, the data is signed with a key known only to the merchant andthe payment gateway.

10.1. Similarities with single payment

All the functionalities available for single payments are also available for payments by token and forrecurring payments.

For more information, see the Implementation guide Hosted Payment Page

Here is a non-exhaustive list:

• Single payment, made in one operation, or split.

• Management of several currencies.

• Management of several payment methods and associated MIDs.

• Personalization of payment pages.

• Display in an iframe.

10.2. Differences with single payment

The main differences with single payment are:

• Different value of the vads_page_action parameter that depends on the desired operation (creationof a token, with or without an associated single payment, with or without a recurring payment).

• Additional parameters associated with these actions.



10.3. Setting up the payment page URL

The merchant website interacts with the payment gateway by redirecting the buyer to the following URL:

https://secure.payzen.eu/vads-payment/

10.4. Identifying yourself when exchanging with the payment gateway

To be able to interact with the payment gateway, the merchant needs to have:

• The shop ID: allows to identify the merchant website during the exchange. Its value is transmitted inthe vads_site_id field.

• The key: allows to compute the alphanumeric signature transmitted in the signature field.

To retrieve these values:

1. Sign in to the Merchant Back Office: https://de.payzen.eu/vads-merchant/

2. Enter your login.

The login is sent to the merchant’s e-mail address (the subject of the e-mail is Connection identifiers- [your shop name].

3. Enter your password.

The password is sent to the merchant’s e-mail address (the subject of the e-mail is Connectionidentifiers- [your shop name].

4. Click Validate.

After 3 password entry errors, the user’s account is locked. Click on the link Forgotten password orlocked account to reset.

5. Click Settings > Shop.

6. Select the Keys tab.

Figure 1: Keys tab

Two types of keys are available:

• The test key that allows to generate the form signature in test mode.

• The production key that allows to generate the form signature in production mode.

These keys can be numeric or alphanumeric.

For maximum security, it is recommended to use an alphanumeric key.

To change the format of your test key, click the Regenerate a test key button and select the format("ALPHANUMERIC" or "NUMERIC").





To change the format of your production key, click the Regenerate a production key button and select theformat ("ALPHANUMERIC" or "NUMERIC").

10.5. Choosing between Test and Production modes

The choice between TEST or PRODUCTION modes can be made using the vads_ctx_mode field (Seechapter Generating a payment form on page 53).

• The TEST mode allows to make test payments.

It is available at all times, even after the generation of the production key.

If you create a new merchant website (or have access to the acceptance testing environment), you canmake tests without impacting the website that is currently in production.

TEST transactions can be viewed in the Merchant Back Office via Management > TEST transactions

• The PRODUCTION mode will become available only once the production key has been generated.

It allows to make real payments.

PRODUCTION transactions can be viewed in the Merchant Back Office via Management > Transactions.



10.6. Managing the interaction with the merchant website

Two types of URL are used to manage dialog with the merchant website:

• Instant Payment Notification, also called the IPN,

• Return URL to the merchant website.

Instant Payment Notification - IPN

The payment gateway automatically informs the merchant website about the payment result. The datais sent via POST.

The gateway is able to contact the websites, regardless of the protocol (http or https) that was used.

Notifications are sent from an IP address in the 194.50.38.0/24 range in Test and Production modes.

To process these notifications, the merchant must create a page on their website that:

• analyzes the data received via POST,

• verifies the integrity of the received information by computing the signature,

• makes sure that the notification is not a duplicate notification (e.g. notification returned via theMerchant Back Office),

• triggers an update of their database (order status, stock, etc.),

• sends e-mails to the buyer (invoice, order tracking, etc.).

The processing time has a direct influence on the time it takes to display the payment summary page. Thelonger the processing takes, the more the summary display will be delayed.

To receive notifications, the merchant must set up the notification rules in his Merchant Back Office (seechapter Setting up notifications).

In case of an issue during interaction with the merchant website, the payment gateway sends an e-mail tothe shop administrator stating the reason of the error (HTTP error, etc.) and the instructions for returningthe notification via the Merchant Back Office.

Return URL to the merchant website

In the Merchant Back Office, the merchant can configure the “default” return URLs via the menu Settings> Shop > Configuration tab:

Figure 2: Setting up return URLs

The merchant can set up a different return URL for each mode.

By default, the buyer is redirected to the URL regardless of the payment result.

If no URL has been set up, the main URL of the shop will be used for redirection (URL parameter definedin the Details section of the shop).

The merchant will be able to override this setting in his/her payment form (see chapter Setting up returnURLs).



Note:

The status of the “Instant Payment Notification at the End of Payment” (IPN) rule is displayed in thiswindow. If the URL has not been set up, make sure to specify it (see chapter Setting up notifications).



10.7. Managing security

There are several ways to guarantee the security of online payments.

Ensuring interaction integrity

The integrity of exchanged information is preserved by the exchange of alphanumeric signatures betweenthe payment gateway and the merchant website.

The payment gateway and the merchant website interact via HTML forms.

A form contains a list of specific fields (see chapter Generating a payment form) used to generate a chain.

This chain is then converted to a smaller chain using a hash function (SHA-1, HMAC-SHA-256).

The merchant will be able to choose the hash algorithm in their Merchant Back Office (see chapter Choosingthe hash algorithm).

The resulting chain is referred to as the digest of the initial chain.

The digest must be transmitted in the signature field (see chapter Computing the signature).

Modeling security mechanisms:

Figure 3: Diagram of a security mechanism

1. The merchant website builds the form data and computes the signature

2. The merchant website submits the form to the gateway

3. The gateway receives the form data and computes the signature

4. The gateway compares the computed signature with the signature that was transmitted by themerchant website

5. If the signatures are different, the payment request is rejected

If not, the gateway proceeds to payment

6. The gateway builds the result data and computes the response signature

7. Depending on the shop configuration (see chapter Setting up notifications), the payment gatewaytransmits the payment result to the merchant website

8. The merchant website receives the data and computes the signature. It compares the computedsignature with the signature that was transmitted by the payment gateway

9. If the signatures are different, the merchant analyses the source of the error (computation error,attempted fraud, etc.)



If not, the merchant proceeds to update their database (stock status, order status, etc.)

Selecting the hash algorithm

In the Merchant Back Office, (Settings > Shop > Keys), the merchant can choose the hash function to usefor generating signatures.

HMAC-SHA-256 signature algorithm is applied by default.

Important

You can select a different signature algorithm for TEST mode and for PRODUCTION mode.

However, be sure to use the same method to generate your payment forms and to analyze the datatransmitted by the gateway during notifications.

In order to facilitate changing the algorithm, the SHA-1 or HMAC-SHA-256 signatures will be acceptedwithout generating rejections due to signature error for 24h.

Storing the production key

For security reasons, the production key will be masked after the first real payment made with a real card.

It is strongly recommended to store the key in a safe place (encrypted file, database etc.).

In case of losing the key, the merchant will be able to regenerate a new one via their Merchant Back Office.

Remember that the production key can be viewed in the Merchant Back Office via Settings > Shop > Keystab.

Managing sensitive data

Online payment transactions are regulated by strict rules (PCI-DSS certification).

As a merchant, you have to make sure to never openly transcribe data that could resemble a credit cardnumber. Your form will be rejected (code 999 - Sensitive data detected).

Special attention should be paid to order numbers containing between 13 and 16 numeric characters andbeginning with 3, 4 or 5.



11. SETTING UP NOTIFICATIONS

The Merchant Back Office allows to manage the events that will generate a notification to the merchantwebsite and to configure the URL of the contact page.

The following diagrams illustrate the transaction status sent in the notification for each event.

The following caption is used for each event:

Action required from the merchant - manual (Merchant Back Office) or automatic (via Web Services)

Action performed by the buyer

11.1. Setting up notifications

Several types of notifications are provided in the Merchant Back Office. They allow the configuration ofthe URL of the page to contact and the management of the events (payment abandoned by the buyer,payment canceled by the merchant, payment validated by the merchant, etc.) that will trigger a call tothe merchant website.

If the payment gateway is unable to access the URL of your page, an e-mail will be sent to the shopadministrator.

It contains:

• The HTTP code of the encountered error

• Parts of error analysis

• Its consequences

• Instructions to resend from the Merchant Back Office the notification to the URL already specifiedabove.

To access notification rule management:

Go to the following menu: Settings > Notification rules.

11.2. Setting up the Instant Payment Notification

This notification is required to communicate the result of a payment request.

In your Merchant Back Office, you must set up a URL that will be systematically called after a payment.It will inform the merchant website of the payment result even if your client has not clicked on return tothe shop.

This parameter is called Instant Payment Notification URL at the end of payment.

To set up this notification:

1. Right-click the Instant Payment Notification URL at the end of payment line.

2. Select Manage the rule.



3. Enter the URL of your page in the fields URL to call in TEST mode and URL to call in PRODUCTIONmode.

4. Enter the E-mail address(es) to notify in case of failure.

5. To specify several e-mail addresses, separate them with a semi-colon.

6. Set up the parameters for Automatic retry in case of failure.

This option allows to automatically send notifications to the merchant website in case of failure (upto 4 times).

For more information, see chapter Activating the automatic retry

7. Save the changes.

11.3. Instant Payment Notification URL on an operation coming from theMerchant Back Office

The payment gateway can systematically notify the merchant website if the following operations areperformed via the Merchant Back Office:

• Payment accepted

• Payment declined

• Transaction modified by the merchant or the acquirer

• Transaction duplicated by the merchant

• Transaction refunded by the merchant

• Transaction canceled at the initiative of the merchant

• Transaction validated by the merchant

• Token creation

• Token update

1. Right click Instant Payment Notification URL on an operation coming from the Back Office.

2. Select Enable the rule.

3. Make a right click on Instant Payment Notification URL on an operation coming from the Back Officeonce again.











11.4. Setting up a notification upon creating a recurring payment

This notification is required to communicate the result of a recurring payment request.


1. Right click Instant Payment Notification URL when creating a recurring payment.


3. Make a right click on Instant Payment Notification URL when creating a recurring payment onceagain.











11.5. Setting up a notification on batch authorization

If the shop has the Anticipated authorization option, it is necessary to enable the Instant PaymentNotification URL on batch authorization rule in order to receive the final payment result.


1. Right click Instant Payment Notification URL on batch authorization.


3. Make a right click on Instant Payment Notification URL on batch authorization once again.











11.6. Configuring e-mails sent to the buyer

The Merchant Back Office offers the possibility to the merchant to configure e-mails sent to the buyer:

• Confirmation e-mail of recurring payment.

• Confirmation e-mail of payment.

• Token creation and/or update confirmation e-mail.

• Pre-notification e-mail of SEPA direct debit to the buyer.

To configure these e-mails:

1. From the Merchant Back Office, go to the following menu: Settings > Notification rules.

2. Select the E-mail sent to the buyer tab.

3. Right click the label of an e-mail and select Enable the rule.

4. Right click the label of an e-mail with an enabled rule and select Manage the rule.

5. Customize the label of the rule and the address to be notified.

6. To customize the e-mail content:

a. Click on Buyer e-mail settings to view the “default text” of the e-mail provided for all themerchants using the payment gateway.

b. Select the tab corresponding to the language that you wish to customize.

c. Click on Customize default text values.

d. Modify the text of the e-mail.

e. Click on Fields to include to display the list of fields available for e-mail customization.

f. Select the fields that you wish to include into the e-mail. A detailed summary of the requestprocessing will be added to the contents of the e-mail.

7. In order to modify the events that trigger the notification:

a. Click Rule conditions

A condition is composed of a variable, a comparison operator and a reference value.

Example: "mode = TEST", "amount exceeding 1000". During the execution of a rule, the value of avariable is retrieved and compared to the reference value.

b. Double-click on an existing condition to modify it.

c. Click Add to create a new condition.

All the conditions must be validated for the rule to be executed.

8. Click Save.

11.7. Activating the automatic retry

This option allows to automatically send notifications to the merchant website in case of failure (up to 4times).

A notification will be considered as failed if the HTTP return code returned by the merchant server is noton the following list: 200, 201, 202, 203, 204, 205, 206, 301, 302.

The return codes are standardized by W3C in RFC 2616.



Automatic retry does not apply to manually triggered notifications from the Merchant Back Office.

To activate the automatic retry:

1. From the Merchant Back Office, go to the following menu: Settings > Notification rules.

2. Right click one of the displayed notification rules.





Call attempts are programmed at fixed intervals every 15 minutes (00, 15, 30, 45). After each failedattempt, a notification e-mail is sent to the e-mail address specified earlier.

The subject of the e-mail sent in such case contains the number corresponding to the notificationretry attempt. It is presented as attempt # followed by the attempt number.

Example of an e-mail subject following a first notification failure at the end of payment:

[MODE TEST] My Shop - Tr. ref. 067925 / FAILURE during the call to your IPN URL [unsuccessful attempt #1]

Example of an e-mail subject following a second failure:


Example of an e-mail subject following a third failure:


To notify the merchant website of the last notification attempt, the e-mail subject will contain themention attempt #last.

Example of an e-mail subject following the last failure:

[MODE TEST] My Shop - Tr. ref. 067925 / FAILURE during the call to your IPN URL [unsuccessful attempt #last]

Each e-mail will include the details of:

• The encountered problem,

• Parts of analysis depending on the error,

• Its consequences,



• Instructions from the Merchant Back Office for resending the request to the URL specified in step4.

Note :

After the fourth attempt, it is still possible to retry the IPN URL manually via the Merchant BackOffice..

Warning, during the automatic retry, any manual call to the IPN URL will affect the number ofautomatic attempts:

• a successful manual call will stop automatic retry

• a failed manual call will have no impact on the current automatic retry.


Note:

During the automatic retry, certain details are not stored in the database or are modified.

Examples of not available / not registered fields in the database:

• vads_page_action

• vads_payment_config

• vads_action_mode

Examples of fields sent with different values:

• vads_url_check_src set to RETRY

• vads_trans_status.The transaction status following this operation may be different depending on its status at the momentwhen the URL is called.

• vads_hash populated differently with regard to the new values.

• signature populated differently with regard to the new values.



12. GENERATING A PAYMENT FORM

To generate a payment request, you must create an HTML form as follows:

<form method="POST" action="https://secure.payzen.eu/vads-payment/"> <input type="hidden" name="parameter1" value="value1" /> <input type="hidden" name="parameter2" value="value2" /> <input type="hidden" name="parameter3" value="value3" /> <input type="hidden" name="signature" value="signature"/> <input type="submit" name="pay" value="Pay"/> </form>

It contains:

The following technical elements:

• The <form> and </form> tags that allow to create an HTML form.

• The method="POST" attribute that defines the method used for sending data.

• The action="https://secure.payzen.eu/vads-payment/" attribute that defines where to send the formdata.

Form data:

• The shop ID.

• Information about the payment depending on the use case.

• Additional information depending on your needs.

• The signature that ensures the integrity of the form.

This data is added to the form by using the <input> tag:

<input type="hidden" name="parameter1" value="value1" />

For setting the name and value attributes, see the Data dictionary chapter also available in the onlinedocument archive.

All the data in the form must be encoded in UTF-8.

Special characters (accents, punctuation marks, etc.) will then be correctly interpreted by the paymentgateway. Otherwise, the signature will not be computed correctly and the form will be rejected.

The Pay button that will allow to send data:

<input type="submit" name="pay" value="Pay"/>





Different use cases are presented in the chapters below. They will allow you to adapt your payment formto your needs.

The following table lists the different formats that you can encounter when building your form.

Notation Description

a Alphabetic characters (from ‘A’ to ‘Z’ and from ‘a’ to ‘z’)

n Numeric characters

s Special characters

an Alphanumeric characters

ans Alphanumeric and special characters (except ‘<’ and ‘>’)

3 Fixed length of 3 characters

..12 Variable length up to 12 characters

json JavaScript Object Notation.Object containing key/value pairs separated by commas.It starts with a left brace ‘{’ and ends with a right brace ‘}’.Each key / value pair contains the name of the key between double-quotes followed by “:”, followed by avalue.The name of the key must be alphanumeric.The value can be:

• a chain of characters (in this case it must be framed by double-quotes)

• a number

• an object

• a table

• a boolean

• empty

Example: {"name1":45,"name2":"value2", "name3"=false}

enum Characterizes a field with a complete list of values.The list of possible values is given in the field definition.

Enum list List of values separated by a “;”.The list of possible values is given in the field definition.Example: vads_payment_cards=VISA;MASTERCARD

map List of key/value pair separated by a “;”.Each key/value pair contains the name of the key followed by “=”, followed by a value.The value can be:

• a chain of characters

• a boolean

• a json object

• an xml object

The list of possible values for each key/value pair is provided in the field definition.Example: vads_theme_config=SIMPLIFIED_DISPLAY=true;RESPONSIVE_MODEL=Model_1



12.1. Creating a ‘Create a token without payment’ form

Use case: creation of a token for making fast payments in the future.

1. Use all the fields presented in the table below to create your form.

Field name Description Format Value

vads_page_action Action to perform enum REGISTER

vads_ctx_mode Operating mode. enum TEST or PRODUCTION

vads_cust_email Buyer's e-mail address. ans..150 E.g.: [email protected]

vads_action_mode Acquisition mode for payment method data. enum INTERACTIVE

vads_site_id Shop ID n8 E.g.: 12345678

vads_trans_date Date and time of the payment form in UTCformat.

n14E.g.: 20190501130025

vads_version Version of the exchange protocol. string V2

2. Use the vads_identifier field if you wish to generate the identifier of the token associated with thepayment method.

The token format must not be an..32. This format is reserved for tokens generated by the paymentgateway.

3. Add optional fields according to your requirements (see chapter Using additional features).

4. Compute the value of the signature field using all the fields of your form starting with vads_ (seechapter Computing the signature).

12.2. Creating a form 'Edit information associated with the token'

Use case: update of bank information associated with a token.



vads_page_action Action to perform enum REGISTER_UPDATE




vads_identifier Token (unique) associated with a paymentmethod.

ans..50

E.g.: MyTokenNote: two possible formats:

• an32: if the identifier isgenerated by the paymentgateway

• ans..50: if the identifier isgenerated by the merchant.



n14E.g.: 20190501130025






12.3. Creating a form 'Create a token during a payment'

Use case: creation of a token during a payment.



vads_page_action Action to perform enum REGISTER_PAY

vads_amount Payment amount (in the smallest currency unit) n..12 E.g.: 3000 for 30,00 EUR


vads_currency Code of the currency used for the payment. n3 E.g.: 978 for euro (EUR)



vads_payment_config Payment type enum SINGLE


vads_trans_date Date and time of the payment form in UTC format. n14 E.g.: 20190501130025

vads_trans_id Unique transaction ID. n6 E.g.: 123456








12.4. Creating a ‘Create a token when making a recurring payment’ form

Use case: subscription to a recurring payment with token creation.

IMPORTANT

No payments will be made during the subscription. Only a verification request will be made in order to validate thepayment method details.

The first payment will be made once the due date is reached, between 12 a.m. and 5 a.m.

If you want the buyer to make the first installment at the moment of creating the recurring payment, see the followingchapter: ‘Creation of a token when a creating a recurring payment with payment’ form on page 59.



vads_page_action Action to perform enum REGISTER_SUBSCRIBE


vads_cust_email Buyer’s e-mail address. ans..150 E.g.: [email protected]

vads_action_ mode Acquisition mode for paymentmethod data.

enumINTERACTIVE


vads_sub_amount Installment amount (in thesmallest currency unit)

n..12 E.g.: 3000 for 30,00 EUR

vads_sub_effect_date Recurring payment start date.n8

Attention, this date cannot be in the past.E.g.: 20210601

vads_sub_currency Code of the currency used for therecurring payment.

n3E.g.: 978 for euro (EUR)

vads_sub_desc Rule for recurring payments toapply according to the iCalendarRFC5545 specification.

string The recurring payments can be made daily,weekly or monthly.It is possible to specify the number of the dayor the month (e.g. “the 10th of the month”,“every 3 months”).Note: the string must not contain spacecharacters.Examples:

• In order to define a weekly recurringpayment:

RRULE:FREQ=WEEKLY

• In order to define a recurring paymentevery two weeks, on the same day andevery 7 days:

RRULE:FREQ=WEEKLY;INTERVAL=2

• To program installment payments for thelast day of each month for 12 months:

RRULE:FREQ=MONTHLY;BYMONTHDAY=28,29,30,31;BYSETPOS=-1;COUNT=12

• To program installment payments for the10th of each month during 12 months:

RRULE:FREQ=MONTHLY;COUNT=12;BYMONTHDAY=10

vads_trans_date Date and time of the paymentform in UTC format.

n14E.g.: 20190501130025




Note:

The vads_sub_effect_date time value must not have passed







12.5. ‘Creation of a token when a creating a recurring payment withpayment’ form

Use case: payment and creation of a recurring payment with token creation.



vads_page_action Action to perform enum REGISTER_PAY_SUBSCRIBE

vads_amount Payment amount (in the smallestcurrency unit)

n..12 E.g.: 3000 for 30,00 EUR


vads_currency Code of the currency used for thepayment.


vads_cust_email Buyer’s e-mail address. ans..150 E.g.: [email protected]

vads_action_mode Acquisition mode for paymentmethod data.

enumINTERACTIVE




n..12E.g.: 3000 for 30,00 EUR

vads_sub_currency Code of the currency used for therecurring payment.



string

The recurring payments can be made daily,weekly or monthly.It is possible to specify the number of the dayor the month (e.g. “the 10th of the month”,“every 3 months”).Note: the string must not contain spacecharacters.Examples:


RRULE:FREQ=WEEKLY







vads_sub_effect_date Recurring payment start date. n8 E.g.: 20210601


n14E.g.: 20190501130025



Note:



12.6. Creating a form 'Payment by token'

Use case: making one-click payment (using an existing token)



vads_page_action Action to perform enum PAYMENT

vads_amount Payment amount (in the smallest currencyunit)

n..12 E.g.: 3000 for 30,00 EUR





ans..50


• an32: if the identifier is generatedby the payment gateway





n14E.g.: 20190501130025







12.7. Creating a ‘Use a token to create a recurring payment’ form

Use case: using an existing and valid token to create a recurring payment.

IMPORTANT

No payments will be made during the subscription.

The first payment will be made once the due date is reached, between 12 a.m. and 5 a.m..



vads_page_action Action to perform enum SUBSCRIBE


vads_action_mode Acquisition mode for paymentmethod data.

enumINTERACTIVE

vads_identifier Token (unique) associated with apayment method.

ans..50


• an32: if the identifier is generated by thepayment gateway

• ans..50: if the identifier is generated by themerchant.



n..12 E.g.: 3000 for 30,00 EUR

vads_sub_effect_date Recurring payment start date. n8 E.g.: 20210601

vads_sub_currency Code of the currency used for therecurring payment



string The recurring payments can be made daily,weekly or monthly.It is possible to specify the number of the dayor the month (e.g. “the 10th of the month”,“every 3 months”).Note: the string must not contain spacecharacters.Examples:


RRULE:FREQ=WEEKLY











n14E.g.: 20190501130025


Note:






12.8. Creating a form 'Edit information associated with the token duringa payment'

Use case: updating a token during a payment made with an expired card.



vads_page_action Action to perform enum REGISTER_UPDATE_PAY





string


• an32: if the identifier isgenerated by the paymentgateway


vads_amount Payment amount (in the smallest currency unit) n..12 E.g.: 3000 for 30,00 EUR




n14E.g.: 20190501130025







13. USING ADDITIONAL FEATURES

To obtain a custom form adapted to your needs, you can use additional optional features from the listbelow:

IMPORTANTOther useful features are presented in the Hosted Payment Page Implementation guide.

• Defining the currency for creating or updating a token.

• Defining a different amount for the first n installments.

These features are described in the following chapters. They will allow you to easily build your paymentform.



13.1. Defining a different amount for the first n installments.

You wish to set up a recurring payment for which the amount of the first installment(s) would differ fromthe ones configured by the vads_sub_amount field.

Example: define a recurring payment with the first 3 installments equal to 25,00 EUR and the remaininginstallments equal to 30,00 EUR.

To do this:

1. Use the fields required for your use case to create your payment form.

2. Use the fields below:

Field name Description Value

vads_sub_init_amount_number Number of installments to which will be applied theamount defined by vads_sub_init_amount

3

vads_sub_init_amount Amount of the first installments. Thenumber of the first installments is defined byvads_sub_init_amount_number.

2500

vads_sub_amount Amount of each installment except theones that will be eventually defined byvads_sub_init_amount_number.

3000

vads_sub_currency Currency used for all of the installments. E.g.: 978 for euro (EUR)

Notes:

• The vads_sub_init_amount and vads_sub_amount fields cannot be set to 0.

• To define a recurring payment where the 3 first months are free, all you need to do is set the startdate (vads_sub_effect_date) to 3 months later.

Example of a payment form:

<form method="POST" action="https://secure.payzen.eu/vads-payment/"><input type="hidden" name="vads_action_mode" value="INTERACTIVE" /><input type="hidden" name="vads_capture_delay" value="0" /> <input type="hidden" name="vads_ctx_mode" value="TEST" /> <input type="hidden" name="vads_currency" value="978" /> <input type="hidden" name="vads_cust_country" value="FR" /> <input type="hidden" name="vads_cust_email" value="[email protected]" /><input type="hidden" name="vads_cust_first_name" value="John" /> <input type="hidden" name="vads_cust_last_name" value="Smith" /> <input type="hidden" name="vads_cust_title" value="Mr" /> <input type="hidden" name="vads_page_action" value="REGISTER_SUBSCRIBE" /> <input type="hidden" name="vads_payment_config" value="SINGLE" /> <input type="hidden" name="vads_site_id" value="91335531" /> <input type="hidden" name="vads_trans_date" value="20190716080441" /> <input type="hidden" name="vads_trans_id" value="362812" /> <input type="hidden" name="vads_validation_mode" value="0" /> <input type="hidden" name="vads_sub_currency" value="978" /> <input type="hidden" name="vads_sub_init_amount_number" value="3" /> <input type="hidden" name="vads_sub_init_amount" value="2500" /> <input type="hidden" name="vads_sub_amount" value="3000" /> <input type="hidden" name="vads_version" value="V2" /><input type="hidden" name="signature" value="86b2a17b9a5fcefb6c0120c57b25ec86ad1704ee"/><input type="submit" name="pay" value="Pay"/></form>

13.2. Defining the currency for creating or updating a token.

If:

• you have a MID that supports several currencies,

• you have several shops,




• your shops are all linked to the same MID,

• each shop generates payments in a different currency,

(e.g.: US dollar for the first shop, Euro for the second shop)

it is possible that the currency used when creating or updating a token is not supported by the shop.

By default, the payment gateway uses alphabetical order when selecting the currency for performing thenecessary checks with the payment method issuer.

In order to avoid IPN processing errors, you can transmit the information about the currency to use viathe form.

Note:


Nom du champ Description Format Valeur

vads_currency Code numérique de la monnaie àutiliser pour le paiement, selon lanorme ISO 4217 (code numérique)




14. CUSTOMIZING THE ELEMENTS OF THE PAYMENT PAGE

Allows to customize certain elements on the payment page:

• the payment methods offered at the moment of payment,

• the language used for displaying the payment pages,

• the languages offered to the buyer on the payment pages,

• the name and the URL of the shop,

• button labels.

Thanks to the advanced customization option, you also can:

• create different custom templates of the payment page in order to make it look more similar to yourmerchant website,

• create different custom templates of e-mails sent to the buyer,

• customize certain labels that appear on the payment pages.

This will result in a better user experience during redirection to proceed to payment.

Please see the Advanced customization - Back Office user manual for more details or contact salesadministration.

14.1. Overriding the custom template

The Merchant Back Office allows:

• to create several custom templates of payment pages,

• to define the template that will be used by default for all your transactions.

The payment form allows to dynamically override the template to be used thanks to thevads_theme_config field.

For this, you must use the keyword: RESPONSIVE_MODEL and indicate the name of the template to be used(Model_1, Model_2, ...).

Example of use:

<input type="hidden" name="vads_theme_config" value="RESPONSIVE_MODEL=Model_1" />

See Advanced customization - Back Office user manual for more details on template creation.

See the vads_theme_config chapter for more details on using this field.



14.2. Managing the payment methods offered to the buyer

It is possible to customize the payment methods offered to the buyer.

Set the vads_payment_cards field.

• with one single value, if you do not wish to show the page of payment method selection.

• with a list of values separated by ";" to show the page of payment method selection.

Example of a payment form with payment method selection:

<form method="POST" action="https://secure.payzen.eu/vads-payment/"><input type="hidden" name="vads_action_mode" value="INTERACTIVE" /><input type="hidden" name="vads_amount" value="30000" /><input type="hidden" name="vads_capture_delay" value="0" /><input type="hidden" name="vads_ctx_mode" value="PRODUCTION" /> <input type="hidden" name="vads_currency" value="978" /><input type="hidden" name="vads_page_action" value="PAYMENT" /><input type="hidden" name="vads_payment_cards" value="VISA;MASTERCARD" /><input type="hidden" name="vads_payment_config" value="SINGLE" /><input type="hidden" name="vads_site_id" value="12345678" /><input type="hidden" name="vads_trans_date" value="20190626101407" /><input type="hidden" name="vads_trans_id" value="239848" /><input type="hidden" name="vads_version" value="V2" /><input type="hidden" name="signature" value="qqpxF6z1+Ri5jtkHNVDCCJulxxpJYehrfP1OLwJ4Ysg="/><input type="submit" name="pay" value="Pay"/></form>




14.3. Selecting a different language

You can customize the language of the payment pages.

Populate vads_language with one the values presented in the table below.

Language ISO 639-1 standard

German de

English en

Chinese zh

Spanish es

French fr

Italian it

Japanese ja

Dutch nl

Polish pl

Portuguese pt

Russian ru

Swedish sv

Turkish tr

• If the value of the vads_language field is wrong, the form will be rejected.

• If the field has not been sent or is empty, the payment page will be shown in the language of thebuyer's browser

• The buyer will be able to change the language anytime by clicking on the flags at the bottom ofthe payment page.

Example of a payment form with a list of available languages:

<form method="POST" action="https://secure.payzen.eu/vads-payment/"><input type="hidden" name="vads_action_mode" value="INTERACTIVE" /><input type="hidden" name="vads_amount" value="3000" /><input type="hidden" name="vads_capture_delay" value="0" /><input type="hidden" name="vads_ctx_mode" value="PRODUCTION" /><input type="hidden" name="vads_currency" value="978" /><input type="hidden" name="vads_language" value="de" /><input type="hidden" name="vads_page_action" value="PAYMENT" /><input type="hidden" name="vads_payment_config" value="SINGLE" /><input type="hidden" name="vads_site_id" value="12345678" /><input type="hidden" name="vads_trans_date" value="20190626101407" /><input type="hidden" name="vads_trans_id" value="239848" /><input type="hidden" name="vads_version" value="V2" /><input type="hidden" name="signature" value="PAMdHJ8FJc2CqUJLXQLxz+e77K4k1YGJmI5mHqGN74g="/><input type="submit" name="pay" value="Pay"/></form>




14.4. Modifying the languages available to the buyer

You can customize the list of languages available to the buyer.

The last language selected by the buyer will be the default language for the payment confirmation e-mail.

Populate the vads_available_languages using the table below

• with one single value, if you do not wish to show the page of payment method selection,

• with a list of values separated by a ";" to show the available languages.

Language Value Flag shown by default

German de x

English en x

Chinese zh x

Spanish es x

French fr x

Italian it x

Japanese ja x

Dutch nl x

Polish pl

Portuguese pt x

Russian ru x

Swedish sv x

Turkish tr x

If the value of the vads_available_languages field is wrong, the form will be rejected.

Example of a payment form with a list of available languages:

<form method="POST" action="https://secure.payzen.eu/vads-payment/"><input type="hidden" name="vads_action_mode" value="INTERACTIVE" /><input type="hidden" name="vads_amount" value="3000" /><input type="hidden" name="vads_available_languages" value="fr;en;es" /><input type="hidden" name="vads_capture_delay" value="0" /><input type="hidden" name="vads_ctx_mode" value="PRODUCTION" /><input type="hidden" name="vads_currency" value="978" /><input type="hidden" name="vads_page_action" value="PAYMENT" /><input type="hidden" name="vads_payment_config" value="SINGLE" /><input type="hidden" name="vads_site_id" value="12345678" /><input type="hidden" name="vads_trans_date" value="20190626101407" /><input type="hidden" name="vads_trans_id" value="239848" /><input type="hidden" name="vads_version" value="V2" /><input type="hidden" name="signature" value="aEWutqzuHH6Q8ns3a6cj5XitZCuhYsDcsKjlLpL8flA="/><input type="submit" name="pay" value="Pay"/></form>




14.5. Modifying the name and the URL of the shop

If you have two domain names, you can modify the name and the URL of the shop to make the domainname visible.

1. Use the vads_shop_name field to override the name of the shop that appears on the summarypayment page, the receipt and the confirmation e-mail.

2. Use the vads_shop_url field to modify the shop URL that appears on the payment pages.

This value will be used for the confirmation e-mail.

If the value of the vads_shop_url field is wrong, the form will not be rejected. However, its value willbe used for 3D Secure . The payment might be declined if the URL is invalid.

Example of a payment form including the modification of the shop name and URL:

<form method="POST" action="https://secure.payzen.eu/vads-payment/"><input type="hidden" name="vads_action_mode" value="INTERACTIVE" /><input type="hidden" name="vads_amount" value="3000" /><input type="hidden" name="vads_capture_delay" value="0" /><input type="hidden" name="vads_ctx_mode" value="PRODUCTION" /><input type="hidden" name="vads_currency" value="978" /><input type="hidden" name="vads_page_action" value="PAYMENT" /><input type="hidden" name="vads_payment_config" value="SINGLE" /><input type="hidden" name="vads_shop_name" value="My Shop" /><input type="hidden" name="vads_shop_url" value="http://www.myshop.com" /><input type="hidden" name="vads_site_id" value="12345678" /><input type="hidden" name="vads_trans_date" value="20190626101407" /><input type="hidden" name="vads_trans_id" value="239848" /><input type="hidden" name="vads_version" value="V2" /><input type="hidden" name="signature" value="gV0f2HZzQ9BxttHM2W5ZM+AKQsxu0HjDvKy0NAE/G24="/><input type="submit" name="pay" value="Pay"/></form>




14.6. Changing the name of the "Return to shop" button

You can customize the text of the button "Return to the shop".

1. Use the vads_theme_config field to change the name of the "Return to shop" button.

2. Use the SUCCESS_FOOTER_MSG_RETURN keyword to change the name of the "Return to shop"button that appears if the payment has been accepted.

3. Use the CANCEL_FOOTER_MSG_RETURN keyword to change the name of the "Cancel and return toshop" button that appears on payment pages.

By subscribing to the advanced customization option, you will be able to change the names (e.g.: shop ID)of the buttons on the payment page.

Please see the Advanced customization - Back Office user manual for more details or contact salesadministration.

Example of payment form with modification of the name of the "Return to shop" button:

<form method="POST" action="https://secure.payzen.eu/vads-payment/"><input type="hidden" name="vads_action_mode" value="INTERACTIVE" /><input type="hidden" name="vads_amount" value="4000" /><input type="hidden" name="vads_capture_delay" value="0" /><input type="hidden" name="vads_ctx_mode" value="PRODUCTION" /><input type="hidden" name="vads_currency" value="978" /><input type="hidden" name="vads_order_id" value="CD100000858" /><input type="hidden" name="vads_page_action" value="PAYMENT" /><input type="hidden" name="vads_payment_config" value="SINGLE" /><input type="hidden" name="vads_site_id" value="12345678" /><input type="hidden" name="vads_theme_config" value="CANCEL_FOOTER_MSG_RETURN=Cancel;SUCCESS_FOOTER_MSG_RETURN=Return" /><input type="hidden" name="vads_trans_date" value="20190631092024" /><input type="hidden" name="vads_trans_id" value="408248" /><input type="hidden" name="vads_version" value="V2" /><input type="hidden" name="signature" value="ge5DHBbUGsq4cFfSIR1QyB/L/9qPNp2vhX9/G3kKJeQ="/><input type="submit" name="pay" value="Pay"/></form>




15. COMPUTING THE SIGNATURE

To be able to compute the signature, you must have:

• all the fields that start with vads_

• the signature algorithm chosen in the shop configuration

• the key

The value of the key is available in your Merchant Back Office via Settings > Shop > Keys tab.

The signature algorithm is defined in your Merchant Back Office via Settings > Shop > Configuration tab.

For maximum security, it is recommended to use HMAC-SHA-256 algorithm and an alphanumeric key.

The use of SHA-1 algorithm is deprecated but maintained for compliance reasons.

To compute the signature:

1. Sort the fields that start with vads_ alphabetically.

2. Make sure that all the fields are encoded in UTF-8.

3. Concatenate the values of these fields separating them with the "+" character.

4. Concatenate the result with the test or production key separating them with a "+".

5. According to the signature algorithm defined in your shop configuration:

a. if your shop is configured to use "SHA-1", apply the SHA-1 hash function to the chain obtainedduring the previous step. Deprecated.

b. if your shop is configured to use "HMAC-SHA-256", compute and encode in Base64 format themessage signature using the HMAC-SHA-256 algorithm with the following parameters:

• the SHA-256 hash function,

• the test or production key (depending on the value of the vads_ctx_mode field) as a sharedkey,

• the result of the previous step as the message to authenticate.

6. Save the result of the previous step in the signature field.



Example of parameters sent to the payment gateway:

<form method="POST" action="https://secure.payzen.eu/vads-payment/"><input type="hidden" name="vads_action_mode" value="INTERACTIVE" /><input type="hidden" name="vads_amount" value="5124" /><input type="hidden" name="vads_ctx_mode" value="TEST" /><input type="hidden" name="vads_currency" value="978" /> <input type="hidden" name="vads_page_action" value="PAYMENT" /><input type="hidden" name="vads_payment_config" value="SINGLE" /><input type="hidden" name="vads_site_id" value="12345678" /><input type="hidden" name="vads_trans_date" value="20170129130025" /><input type="hidden" name="vads_trans_id" value="123456" /><input type="hidden" name="vads_version" value="V2" /><input type="hidden" name="signature" value="ycA5Do5tNvsnKdc/eP1bj2xa19z9q3iWPy9/rpesfS0= " /> <input type="submit" name="pay" value="Pay"/></form>

This sample form is analyzed as follows:

1. The fields whose names start with vads_ are sorted alphabetically:

• vads_action_mode

• vads_amount

• vads_ctx_mode

• vads_currency

• vads_page_action

• vads_payment_config

• vads_site_id

• vads_trans_date

• vads_trans_id

• vads_version

2. The values of these fields are concatenated using the "+" character:

INTERACTIVE+5124+TEST+978+PAYMENT+SINGLE+12345678+20170129130025+123456+V2

3. The value of the test key is added at the end of the chain and separated with the "+" character. In thisexample, the test key is 1122334455667788

INTERACTIVE+5124+TEST+978+PAYMENT+SINGLE+12345678+20170129130025+123456+V2+1122334455667788

4. If you use the SHA-1 algorithm, apply it to the obtained chain.

The result that must be transmitted in the signature field is:59c96b34c74b9375c332b0b6a32e6deeec87de2b

5. If your shop is configured to use "HMAC-SHA-256", compute and encode in Base64 format the messagesignature using the HMAC-SHA-256 algorithm with the following parameters:


• the test or production key (depending on the value of the vads_ctx_mode field) as a shared key,


The result that must be transmitted in the signature field is:

ycA5Do5tNvsnKdc/eP1bj2xa19z9q3iWPy9/rpesfS0=




16. SENDING THE PAYMENT REQUEST

The buyer will be able to finalize his/her purchase once he/she is redirected to the payment page.

The buyer's browser must transmit the payment form data.

16.1. Redirecting the buyer to the payment page

The URL of the payment gateway is:


Example of parameters sent to the payment gateway:

<form method="POST" action="https://secure.payzen.eu/vads-payment/"><input type="hidden" name="vads_action_mode" value="INTERACTIVE" /> <input type="hidden" name="vads_amount" value="2990" /> <input type="hidden" name="vads_ctx_mode" value="TEST" /> <input type="hidden" name="vads_currency" value="978" /><input type="hidden" name="vads_cust_country" value="DE" /><input type="hidden" name="vads_cust_email" value="[email protected]" /><input type="hidden" name="vads_page_action" value="PAYMENT" /><input type="hidden" name="vads_payment_config" value="SINGLE" /> <input type="hidden" name="vads_site_id" value="12345678" /> <input type="hidden" name="vads_trans_date" value="20190626101407" /> <input type="hidden" name="vads_trans_id" value="362812" /> <input type="hidden" name="vads_version" value="V2" /><input type="hidden" name="signature" value="NM25DPLKEbtGEHCDHn8MBT4ki6aJI/ODaWhCzCnAfvY="/><input type="submit" name="payer" value="Payer"/></form>

16.2. Processing errors

If the payment gateway detects an error while receiving the form, an error message will appear and thebuyer will not be able to proceed to the payment.

In TEST mode

The message indicates the source of the error and provides a link to the error code description to helpyou fix it.

In PRODUCTION mode

The message simply indicates to the buyer that a technical problem occurred.

In both cases the merchant receives a notification e-mail.

It contains:

• the source of the error,

• a link to possible causes to facilitate its analysis,

• all the fields of the form.

A description of the error codes with their possible causes is available on our website

https://payzen.io/de-DE/error-code/error-00.html



https://payzen.io/de-DE/error-code/error-00.html



Other messages may appear during the payment process.

Here is a list of the most frequent messages:

Message Description

Your payment request has been declined by your financialinstitution

• The buyer’s bank has rejected the authorization orinformation request.

• The risk assessment rules have triggered the rejection ofthe transaction.

Your registration request has been declined by your financialinstitution

• The buyer’s bank has rejected the authorization orinformation request.

• The risk assessment rules have triggered the rejection ofthe transaction.

This payment order is expired. Please contact your shop.The buyer clicked on the payment link after the paymentorder expiry date.

This payment order has already been paidThe buyer clicked on the payment link once again after havingalready made the payment.

An error occurred during the payment request, themerchant website has been informed of the impossibility tofinalize the transaction

The payment form has been rejected. The shop administratorhas received an e-mail with the details of the error source.

The transaction has already been made

The merchant website sent a transaction identifier that hasalready been used for another transaction (accepted orrejected). The transaction identifier must be unique withinthe same day (00:00:00 at 23:59:59 UTC).

Sorry, you have been disconnected due to a long period ofinactivity

• The buyer attempts to validate the card number whilethe payment session has expired. The session is open forapproximately 10 minutes.

• The merchant website sends a transaction identifierthat has already been used but that did not result in atransaction (e.g. abandoned payment). The transactionidentifier must be unique within the same day (00:00:00at 23:59:59 UTC).

Cookies are blocked by your browser. Make sure youauthorize them before retrying the operation.

The buyer has disabled cookies in their browser. Cookies arenecessary for the payment to be processed correctly.



16.3. Managing timeouts

Payment session concept

A "payment session" is the time spent by a buyer on the payment page.

The payment session begins as soon as the payment gateway receives the payment form.

The delay of payment session is 10 minutes (except for certain payment methods).

This delay is:

• sufficient to enable each buyer to make his or her payment

• by the deadline: it is not reset to every action of the user

• non-modifiable: it is fixed by the payment gateway because of technical constraints.

After this delay, the payment session times out and the session data is purged.

Expiration of the payment session

It is possible that in some cases, the payment session will expire while the buyer has not completedpayment.

Most frequent cases:

1. Once redirected to the payment page for example, the buyer realizes that it is time to go to lunch.

An hour later, the buyer decides to continue his or her payment and clicks on the logo correspondingto his or her payment method.

The buyer's payment session has already expired, the payment gateway displays an error messageindicating that it was disconnected due to an extended period of inactivity.

The buyer then has the opportunity to click a button to return to the merchant website.

The return to the shop is done via the URL specified by the merchant:

• in the vads_url_return field transmitted in the payment form

• in the "Return URL to the merchant website" field in the buyer's Merchant Back Office, novads_url_return field is transmitted in his or her payment form.

2. Once redirected to the payment page, the buyer closes the browser (by mistake or because he or sheno longer wants to make the payment).

Notification in case of session expiration

It is possible to notify the merchant website in case of expiration of the payment session.

To do this, the merchant must set up and activate the notification on cancellation rule (see chapter Settingup notifications).



17. ANALYZING THE PAYMENT RESULT

After each payment (accepted or rejected) the gateway sends to the merchant site a notification containingthe payment result.

This notification is also called IPN.

To process the payment result, the merchant website must have a separate page that analyzes the datatransmitted in POST mode (URL e.g.: https://merchant-website.com/payment_analysis.php)

Depending on the result, this page must trigger different actions (changing the order status, updatingstocks, etc.)

Prerequisites:

• URL of the page that analyzes the payment result must be specified in the Merchant Back Office (seechapter Setting up notifications).

• The merchant has to make sure that this URL is available via the payment gateway without redirection.

Using redirection leads to losing data presented in POST.

• In case some restrictions are set up by the merchant website, the IP address range to be authorizedis: 194.50.38.0/24.

Notifications are sent from an IP address in the 194.50.38.0/24 range in Test and Production mode.

• HTML must not be visible on the page.

Access to images or CSS slows down the exchange between the payment gateway and the merchantwebsite.

• Avoid integrating time-consuming tasks, such as invoice generation or sending e-mails in the script.

The processing time has a direct influence on how long it takes to display the summary page to thebuyer. The longer the processing of the notification, the greater the delay for displaying the page.

After 35 seconds, the payment gateway considers that the call has failed (timeout).

Failed notification (IPN)

In case the call to IPN fails, a notification e-mail is sent to the address specified in the Merchant Back Office(see chapter Setting up notifications).

It contains:

• The HTTP code of the encountered error,

• Parts of analysis depending on the error,

• Instructions to resend the notification from the Merchant Back Office.

In order to help the merchant to identify the origin of the error, the gateway systematically analyzes thefirst 512 characters returned by the merchant site.

These characters can be viewed in the transaction details, Event log tab:



Writing the processing script

The processing script must include at least the following steps:

• Retrieve the field list sent with the response in POST mode

• Compute the signature taking into account the data received

• Compare the computed signature with the received signature

• Analyze the nature of the notification

• Retrieve the payment result

The script may check the order status (or any information of your choice) to see if it has not been alreadyupdated.

Once these steps are completed, the script can update the database (new order status, stock update,registration of payment information, etc.).

17.1. Retrieving data returned in the response

The data returned in the response depends on the parameters sent in the payment form, the paymenttype and the settings of your shop. This data constitutes a field list. Each field contains a response value.The field list can be updated.

The data is always sent by the payment gateway using the POST method.

The first step consists in retrieving the contents received via the POST method.

Examples:

• In PHP, data is stored in the super global variable $_POST,

• In ASP.NET (C#), you must use the Form property of the HttpRequest class.

• In Java, you must use the getParameter method of the HttpServletRequest interface.

The script will have to create a loop to retrieve all the transmitted fields.

Example of data sent during payment notification :

vads_amount = 3000vads_auth_mode = FULLvads_auth_number = 3fb0devads_auth_result = 00vads_capture_delay = 0vads_card_brand = VISAvads_card_number = 497010XXXXXX0000vads_payment_certificate = a50d15063b5ec6cb140043138b8d7576470b71a9vads_ctx_mode = TESTvads_currency = 978vads_effective_amount = 3000vads_site_id = 12345678vads_trans_date = 20140902094139vads_trans_id = 454058vads_validation_mode = 0vads_version = V2vads_warranty_result = YESvads_payment_src = ECvads_sequence_number = 1vads_contract_used = 5785350vads_trans_status = AUTHORISEDvads_expiry_month = 6vads_expiry_year = 2015vads_bank_code = 17807vads_bank_product = Avads_pays_ip = FRvads_presentation_date = 20140902094202vads_effective_creation_date = 20140902094202vads_operation_type = DEBIT



vads_threeds_enrolled = Yvads_threeds_cavv = Q2F2dkNhdnZDYXZ2Q2F2dkNhdnY= vads_threeds_eci = 05vads_threeds_xid = WXJsVXpHVjFoMktzNmw5dTd1ekQ= vads_threeds_cavvAlgorithm = 2vads_threeds_status = Yvads_threeds_sign_valid = 1vads_threeds_error_code = vads_threeds_exit_status = 10vads_trans_uuid= 1cd9994823334e31bbb579b4d716832dvads_risk_control = CARD_FRAUD=OK;COMMERCIAL_CARD=OKvads_result = 00vads_extra_result = 00vads_card_country = DEvads_language = frvads_hash = 299d81f4b175bfb7583d904cd19ef5e38b2b79b2373d9b2b4aab74e5753b10bcvads_url_check_src = PAYvads_action_mode = INTERACTIVEvads_payment_config = SINGLEvads_page_action = PAYMENTsignature = FxGvazgW0dgqOrVrx6bqKZSXh2y5Dp3bWC9HFn33t+Q=



17.2. Computing the IPN signature

The signature is computed by following the same procedure as for creating the payment form.

IMPORTANT

The data submitted by the payment gateway is encoded in UTF-8. Any alteration of received data will result in signaturecomputation error.

You must compute the signature with the fields received in the notification and not the ones that you transmitted in yourpayment form.

To compute the signature:

1. Take all the fields whose name starts with vads_.

2. Sort these fields alphabetically.

3. Concatenate the values of these fields separating them with the "+" character.

4. Concatenate the result with the test or production key separating them with a "+".

5. According to the signature algorithm defined in your shop configuration:

a. if your shop is configured to use "SHA-1", apply the SHA-1 hash function to the chain obtainedduring the previous step. Deprecated.

b. if your shop is configured to use "HMAC-SHA-256", compute and encode in Base64 format themessage signature using the HMAC-SHA-256 algorithm with the following parameters:


• the test or production key (depending on the value of the vads_ctx_mode field) as a sharedkey,




17.3. Comparing signatures

In order to make sure the response is complete, you must compare the value of the signature field receivedin the response with the one computed in the step “Computing the IPN signature”.

IMPORTANTYou must not compare the IPN signature with the signature that you transmitted in your form.

If the signatures match,

• You may consider the response as safe and proceed with the analysis.

• If they do not, the script will have to throw an exception and warn the merchant .

The signatures may not match because of:

• an implementation error (error in your calculation, problem with UTF-8 encoding, etc.),

• an error in the value of the key or in the vads_ctx_mode (field value - frequent issue when going tolive mode),

• a data corruption attempt.



17.4. Analyzing the nature of the notification

The vads_url_check_src field allows to differentiate the notifications based on their triggering event:

• token creation (with or without the subscription of a recurring payment),

• installment payment,

• new notification sent by the merchant via the Merchant Back Office.

It specifies the applied notification rule:

Value Applied rule

PAY The PAY value is sent in the following cases:

• registration request for a mandate or a token (REGISTER)

• registration request for a mandate or a token when subscribing to a recurring payment(REGISTER_SUBSCRIBE)

• immediate payment (or first installment payment of a recurring payment)

• payment abandoned or canceled by the buyeronly if the merchant has configured the rule Instant Payment Notification URL on cancellation

BO Execution of the notification via the Merchant Back Office (right-click a transaction > Send theInstant Payment Notification).Check whether the vads_recurrence_number field is present:

• if yes, the notification concerns the result of a recurring payment (retry of a REC typenotification),

• if not, the notification concerns a notification at the end of payment.

BATCH The BATCH value is sent in case of an update of a transaction status after its synchronization on theacquirer side.This is the case of payments with redirection to the acquirer.Only if the merchant has configured the rule Instant Payment Notification URL on batch change.

BATCH_AUTO The BATCH_AUTO value is sent in the following cases:

• payment deferred for more than 7 days

• installments of a recurring payment (except the first one)only if the merchant has configured the rule Instant Payment Notification URL on batchauthorization

The notification is sent with the authorization request for payments with "Waiting for authorization"status.

REC The REC value is sent only for recurring payments if the merchant has configured the InstantPayment Notification URL when creating recurring payments rule.

MERCH_BO The MERCH_BO value is sent:

• during operation made via the Merchant Back Office (refund, cancellation, modification,validation, duplication, creation and/or update of token), only if the merchant has configuredthe following notification rule: Instant Payment Notification URL on an operation coming fromthe Back Office

RETRY Automatic retry of the IPN.Check whether the vads_recurrence_number field is present:

• if yes, the notification concerns the result of a recurring payment (retry of a REC typenotification),

• if not, the notification concerns a notification at the end of payment.

Table 1: Values associated with the vads_url_check_src field

After checking its value, the script can process differently depending on the nature of the notification.

For example:

If vads_url_check_src is set to PAY or BATCH_AUTO, the script will update the order status, etc.



If vads_url_check_src is set to REC the script will retrieve the recurring payment reference and willincrement the number of the expired installment payments in case the payment has been accepted, etc.

In the context of a recurring payment (from a REGISTER_SUBSCRIBE), the payment gateway notifies thecreditor (merchant) when creating each transaction.

17.5. Processing the response data

Creating a token without payment

In order to understand the result, analyze the following fields:

Field name Description

vads_page_action Completed action.The returned value is REGISTER.

vads_identifier_status Token creation status.The possible values are:

• CREATED: the request for authorization or information, if supported by the acquirer isaccepted.The token has been successfully created and appears in the Merchant Back Office.

• NOT_CREATED: the authorization or information request has been declined. The token isnot created.

• ABANDONED: action abandoned by the buyer. The token is not created.

vads_identifier Token identifier.The returned value is:

• either the value transmitted in the request, regardless of the result of token creation,even in case of abandoned action,

• or the value generated by the payment gateway, if the field is not transmitted in therequest and the token has been successfully created (vads_identifier_status=CREATED).

The vads_identifier field is not returned:

• if it has not been transmitted in the request and the buyer abandons the action(vads_identifier_status=ABANDONED),

• if it has not been transmitted in the request and the token has not been created(vads_identifier_status=NOT_CREATED).

vads_cust_email Buyer’s e-mail address transmitted in the request.

vads_site_id Shop IDThe returned value is the same as the one submitted in the form.

vads_ctx_mode Operating mode.The returned value (TEST or PRODUCTION) is the same as the one submitted in the form.


vads_auth_mode Type of request made via authorization servers.Its value is MARK.

vads_auth_number Authorization number returned by the authorization server.Empty if the authorization has failed.

vads_auth_result Return code of the authorization request returned by the issuing bank.See chapter Managing the return codes of the authorization request.Empty if the error occurred before the authorization.

vads_risk_assessment_result List of actions performed for the transaction, following the activation of the advanced riskassessment rules.The possible values are:

• ENABLE_3DS: 3D Secure enabled.



Field name Description• DISABLE_3DS: 3D Secure disabled.

• REFUSE: The token creation request is rejected.

• RUN_RISK_ANALYSIS: Result of the external risk analyzer.See the description of the vads_risk_analysis_result field for more information.

• INFORM: A warning message appears.The merchant is notified that a risk has been identified via one or several notificationcenter rules.

Details of the used payment method.

Field name Note

vads_card_brand Used payment method.See chapter Compatible payment methods to see the list of possible values.

vads_card_number Truncated/masked card number.

vads_expiry_month Expiry month of the used card.

vads_expiry_year Expiry year of the used card.

vads_card_country Country code of the used card in compliance with the ISO 3166 standard.

vads_bank_label Name of the issuing bank of the used card.

vads_bank_product Product code of the used card.

Details of 3DS authentication

Field name Note

vads_threeds_enrolled Enrollment status of the buyer to the 3D Secure program.The possible values are:

• Y: Authentication available.

• N: Authentication not available.

• U: Enrollment status to the 3D Secure program unknown.

• empty: Incomplete 3DS authentication process (3DS disabled in the request, unregisteredmerchant or payment method not eligible for 3DS).

vads_threeds_status 3D Secure authentication result.The possible values are:

• Y: Cardholder authentication success.

• N: Cardholder authentication error.

• U: Authentication impossible.

• A: Authentication attempted but not completed.

• empty: Unauthorized 3DS authentication (3DS disabled in the request, unregisteredcardholder or payment method not eligible for 3DS).

The optional fields transmitted in the request are returned in the response with unmodified values.



Updating token details



vads_page_action Completed action.The returned value is REGISTER_UPDATE.

vads_identifier_status Token update status.The possible values are:

• UPDATED: The token has been successfully updated.

• NOT_UPDATED: the token has not been updated.

• ABANDONED: the action has been abandoned by the buyer.The token has not been created and does not appear in the Merchant Back Office.

vads_identifier Token ID to be updated.The returned value is identical to the one submitted in the form.










• DISABLE_3DS: 3D Secure disabled.





Field name Note











Field name Note















Creating a token during a payment



vads_page_action Completed action.The returned value is REGISTER_PAY.


• CREATED: the request for authorization or information, if supported by the acquirer isaccepted.Token has been successfully created.

• NOT_CREATED: the authorization or information request has been rejected.The token has not been created, and therefore cannot be viewed in the Merchant BackOffice.

• ABANDONED: the action has been abandoned by the buyer (debtor).The token has not been created, and therefore cannot be viewed in the Merchant BackOffice.

vads_trans_status Transaction status.The possible values are:

• AUTHORISEDThe authorization or information request has been accepted.The token has been created and is visible in the Merchant Back Office.

• AUTHORISED_TO_VALIDATEThe authorization or information request has been accepted.The merchant must manually validate the transaction.The token has been created and is visible in the Merchant Back Office.

• CAPTUREDThe authorization or information request has been accepted.The transaction is visible in the “Captured transactions” tab of the Back Office.The token has been created and is visible in the Merchant Back Office.

• WAITING_AUTHORISATIONThe capture delay in the bank exceeds the authorization validity period. Theauthorization request for the total amount has not yet taken place.The token has been created and is visible in the Merchant Back Office.

• WAITING_AUTHORISATION_TO_VALIDATETo be validated and authorizedThe capture delay in the bank exceeds the authorization validity period.An authorization of 1 EUR (or information request about the CB network if the acquirersupports it) has been accepted.The merchant must manually validate the transaction in order to trigger the authorizationrequest and capture.

• REFUSEDThe authorization or information request has been rejected.The token is not created.

• ABANDONEDOperation abandoned by the buyer.The transaction is then not visible via the Merchant Back Office.The token is not created.

vads_identifier Payment token.The returned value is:



The vads_identifier field will not be returned:



Field name Description• if it has not been transmitted in the request and the buyer abandons the action

(vads_identifier_status=ABANDONED),





To see the payment details, see the parameters below:

Transaction details:


vads_operation_type Transaction typeIts value is DEBIT.

vads_amount Transaction amount.The returned value is the same as the one submitted in the form.

vads_currency Code of the currency used for the payment.

vads_trans_id The transaction identifier.The returned value is the same as the one submitted in the form.

vads_trans_uuid Unique transaction ID.Its value is generated by the payment gateway.

vads_contract_used MID associated with the transaction.

vads_auth_mode Type of request made via authorization servers:

• MARK: corresponds to an authorization for 1 EUR (or information request about the CBnetwork if the acquirer supports it).Value used also if the period between the requested capture date and the current date isstrictly greater than the authorization validity period.

• FULL: corresponds to an authorization for the total amount of the transaction.Value used also if the period between the requested capture date and the current date isstrictly shorter than the authorization validity period.


vads_auth_result Return code of the authorization request returned by the issuing bank.See chapter Managing the return codes of the authorization request.Empty in case of an error prior to the authorization.

vads_risk_control Result of the risk assessment.If at least one verification process returns the ERROR value, the transaction is rejected.See the description of the vads_risk_analysis_result field for more information.

vads_risk_assessment_result List of actions made with the transaction, following the activation of the advanced riskassessment rules.The possible values are:


• DISABLE_3DS 3D Secure disabled.

• MANUAL_VALIDATION: The transaction has been created via manual validation.The payment capture is temporarily blocked to allow the merchant perform all thedesired verifications.

• REFUSE: Transaction is declined.


• INFORM: A warning message appears.



Field name DescriptionThe merchant is notified that a risk has been identified via one or several notificationcenter rules.


Field name Note



vads_expiry_month Expiry month of the card used for the payment.

vads_expiry_year Expiry year of the card used for the payment.

vads_card_country Country code of the card in compliance with the ISO 3166 standard.

vads_bank_label Name of the issuing bank of the payment card.

vads_bank_product Product code of the card used for the payment.

Details of strong authentication:

Field name Note



• N: Authentication not available






• U: Authentication impossible




See the Data dictionary to know the parameters returned in the response for the following categories:

Order details Order details on page 108Buyer details Buyer details on page 109Shipping details Shipping details on page 110



Creation of a token during a recurring payment



vads_page_action Completed action.The returned value is REGISTER_SUBSCRIBE.


• CREATED: the request for authorization or information, if supported by the acquirer isaccepted.Token has been successfully created.See the value of the vads_recurrence_status field to determine whether the subscriptionhas been created.

• NOT_CREATED: the authorization or information request has been rejected.The token has not been created, and therefore cannot be viewed in the Merchant BackOffice. The recurring payment is not created.

• ABANDONED: the action has been abandoned by the buyer (debtor).The token has not been created, and therefore cannot be viewed in the Merchant BackOffice.The recurring payment is not created.

vads_recurrence_status Recurrence creation status.The possible values are:

• CREATED: The recurring payment has been successfully created.

• NOT_CREATED: The recurring payment is not created.

• ABANDONED: the action has been abandoned by the buyer (debtor). The recurringpayment is not created.

vads_identifier Token identifier.The returned value is:



The vads_identifier field is not returned:



vads_subscription Recurring payment token.The returned value is:

• either the value transmitted in the request, regardless of the result of subscriptioncreation,

• or the value generated by the payment gateway, if the field has not beentransmitted in the request and the subscription has been successfully created(vads_recurrence_status=CREATED).

The vads_subscription field will not be returned:

• if it has not been transmitted in the request and the buyer abandons the action(vads_recurrence_status=ABANDONED),

• if it has not been transmitted in the request and the subscription has not been created(vads_recurrence_status=NOT_CREATED).



vads_ctx_mode Operating mode.



Field name DescriptionThe returned value (TEST or PRODUCTION) is the same as the one submitted in the form.







• DISABLE_3DS: 3D Secure disabled.





Field name Note









Field name Note













Field name Note• empty: Unauthorized 3DS authentication (3DS disabled in the request, unregistered

cardholder or payment method not eligible for 3DS).




Creation of a token when a creating a recurring payment with payment



vads_page_action Action complete.The returned value is REGISTER_PAY_SUBSCRIBE.


• CREATED: the request for authorization or information, if supported by the acquirer isaccepted.Token has been successfully created.See the value of the vads_recurrence_status field to determine whether the subscriptionhas been created.

• NOT_CREATED: the authorization or information request has been declined.The token has not been created, and therefore cannot be viewed in the Merchant BackOffice. The recurring payment is not created.

• ABANDONED: the action has been abandoned by the buyer (debtor).The token has not been created, and therefore cannot be viewed in the Merchant BackOffice.The recurring payment is not created.














Field name Description• ABANDONED: the action has been abandoned by the buyer (debtor). The recurring

payment is not created.

vads_identifier Payment token.The returned value is:



The vads_identifier field will not be returned:























• FULL: corresponds to an authorization for the total amount of the transaction.



Field name DescriptionValue used also if the period between the requested capture date and the current date isstrictly shorter than the authorization validity period.












Field name Note









Field name Note












Field name Note• A: Authentication attempted but not completed.




Recurring payment details Recurring payment details on page 117Order details Order details on page 108Buyer details Buyer details on page 109Shipping details Shipping details on page 110

Payment by token



vads_page_action Completed action.The returned value is PAYMENT.









vads_identifier Recurring payment token to debit.The returned value is the same as the one submitted in the form.

vads_cust_email E-mail address of the buyer associated with the token.





























Field name Note

vads_card_brand Used payment method.



Field name NoteSee chapter Compatible payment methods to see the list of possible values.








Field name Note















Creating a recurring payment



vads_page_action Completed action.The returned value is SUBSCRIBE.




• ABANDONED: the action has been abandoned by the buyer (debtor). The recurringpayment is not created.

vads_identifier Recurring payment token to debit.The returned value is the same as the one submitted in the form.










vads_cust_email E-mail address of the buyer associated with the token.




Field name Note



vads_expiry_month Expiry month of the card used for creating the token.

vads_expiry_year Expiry year of the card used for creating the token.

vads_card_country Country code of the card used for creating the token in compliance with the ISO 3166 standard.

vads_bank_label Name of the issuing bank of the card used for creating the token.

vads_bank_product Product code of the card used for creating the token.

Details of strong authentication performed when creating the token:

Field name Note















Updating information associated with the token during a payment



vads_page_action Completed action.The returned value is REGISTER_UPDATE_PAY.

vads_identifier_status Token update status.The possible values are:

• UPDATED: Token has been successfully created.

• NOT_UPDATED: the token has not been updated.

• ABANDONED: the action has been abandoned by the buyer (debtor).The token has not been created, and therefore cannot be viewed in the Merchant BackOffice.









vads_identifier Payment token to update.The returned value is the same as the one submitted in the form.





























Field name Note











18. APPENDIX

18.1. Automatically creating a recurring payment via Web services

• V5 SOAP Web Services

Use the createSubscription operation.

For more information, see the SOAP Web service API v5 Implementation guide available in our onlinedocumentation archive.

• RESTful payment Web Services

Use the Charge/CreateSubscription method to make recurring payments (subscription) using anexisting and valid token.

18.2. Automatically canceling a recurring payment via Web services

• V5 SOAP Web Services

Use the cancelSubscription operation to cancel a recurring payment on a given date.

For more information, see the SOAP Web service API v5 Implementation guide available in our onlinedocumentation archive.

• RESTful payment Web Services

Use the Subscription/Cancel method to terminate a recurring payment on a specific date.



19. DATA DICTIONARY

The data dictionary lists all the fields that can be used in a payment form.

First, is presents the main categories (such as technical information, order details, etc.). All the fields thatbelong to a category are presented.

These tables are presented as follows:

• Field name: indicates the name of the parameter as it appears in the HTTP request.

• Format: data format

• Description: description of the field

• Input: a field to be transmitted in the request

• Output: a field transmitted in the response

The data dictionary also presents the details for each field. Each field is presented as follows:

• Description: description of the field

• Format: data format (see the table List of fields and formats below)

• Possible values: expected values when the field must be populated with specific values

• Example: example of correct data encoding

• Error code: in case there is a error between the merchant website and the payment platform, thepayment platform indicates the incorrect parameter in the vads_extra_result field using a numeric code

• Note: additional information, elaboration

• Category: category to which the field belongs

Precisions on error codes:

An error code corresponds to the error number when an incorrect payment form is being submitted.

• In test mode this code will be displayed on the payment page.

• In production mode a warning e-mail will be sent specifying the error code and the name of theincorrect parameter.

Example: Error 09 corresponds to a payment amount error. The submitted amount does not respect therequired format



Viewing parameters sorted by category

Go to the desired category to obtain the list of related parameters

• 3DS Authentication

• Recurring payment details

• Buyer details

• Payment method details

• Order details

• Shipping details

• Technical details

• Transaction details

• Payment page customization

• Automatic redirection

Technical details

Field name Format Description Input Output

signature an40Signature garantissant l'intégrité desrequêtes échangées entre le site marchandet la plateforme de paiement.

x x

vads_action_mode enumMode d’acquisition des données du moyende paiement

x x

vads_override_payment_cinematic enumCinématique de paiement à appliquer.Surcharge la valeur enregistrée sur lecontrat.

x

vads_contrib ans..128Nom de la solution e-commerce utilisée surle site marchand ainsi que son numéro deversion.

x x

vads_ctx_mode enumMode de communication avec laplateforme de paiement

x x

vads_extra_result n2Optional code of the response. Itsmeaning depends on the value specified invads_result.

x

vads_hash an64A unique key returned only to the InstantPayment Notification (IPN).

x

vads_page_action enum Defines the action to be performed. x x

vads_payment_error n..3 Error codes for a declined payment. x

vads_result n2 General return code of the payment result. x

vads_site_id n8 Identifiant de la boutique x x

vads_url_check ans..1024URL de la page à notifier à la fin dupaiement. Surcharge la valeur saisie dans leparamétrage des règles de notification.

x

vads_url_check_src enumThis parameter defines the source of thecall to the notification URL (also called IPNURL).

x

vads_version enumVersion du protocole d’échange avec laplateforme de paiement

x x



Order details


vads_authent_paypal_protection_eligibilityenum

Type of merchant protection used for thetransaction.

x

vads_ext_infoans

Customizable fields allowing to add detailsto the confirmation e-mail sent to themerchant and in the IPN URL.

x x

vads_ext_info_soft_descriptor ans Allows to customize the brand name x

vads_nb_products n..12 Nombre d’articles présents dans le panier x

vads_order_id ans..64 Numéro de commande x x

vads_order_infoan..255

Informations supplémentaires sur lacommande

x x

vads_order_info2an..255


x x

vads_order_info3an..255


x x

vads_pretax_amount n..12 Tax-free amount of the entire order x

vads_product_amountNn..12

Montant de l’article. N correspond à l'indicede l'article (0 pour le premier, 1 pour lesecond...)

x

vads_product_ext_idN

an..100

Code barre du produit dans le site webdu marchand. N correspond à l'indice del'article (0 pour le premier, 1 pour lesecond...)

x

vads_product_labelNan..255

Libellé de l’article. N correspond à l'indicede l'article (0 pour le premier, 1 pour lesecond...)

x

vads_product_qtyNn..12

Quantité d’article. N correspond à l'indicede l'article (0 pour le premier, 1 pour lesecond...)

x

vads_product_refNan..64

Référence de l’article. N correspond àl'indice de l'article (0 pour le premier, 1 pourle second...)

x

vads_product_typeNenum

Type de l’article. N correspond à l'indicede l'article (0 pour le premier, 1 pour lesecond...)

x

vads_product_vatNn..12

TVA de l'article. N correspond à l'indicede l'article (0 pour le premier, 1 pour lesecond...)

x

vads_tax_amount n..12 Amount of taxes for the entire order x

vads_tax_rate enum VAT applied to the order x x

vads_totalamount_vat n..12 Total amount of taxes for the entire order x x



Buyer details


vads_avs_result a1 Address verification system (AVS) x

vads_cust_address ans..255 Adresse postale x x

vads_cust_address_number ans..64 Numéro de rue x x

vads_cust_address2 ans..255 Deuxième ligne d'adresse x x

vads_cust_cell_phone an..32 Numéro de téléphone mobile x x

vads_cust_city an..128 Ville x x

vads_cust_countrya2

Code pays suivant la norme ISO 3166alpha-2

x x

vads_cust_district ans..127 Quartier x x

vads_cust_email ans..150 Adresse e-mail de l’acheteur x x

vads_cust_first_name ans..63 Prénom x x

vads_cust_idan..63

Référence de l’acheteur sur le sitemarchand

x x

vads_cust_last_name ans..63 Nom x x

vads_cust_legal_name an..100 Raison sociale de l'acheteur x

vads_cust_name an..127Utilisez vads_cust_first_name etvads_cust_last_name.

x x

vads_cust_national_id ans..255 Identifiant national x x

vads_cust_phone an..32 Numéro de téléphone x x

vads_cust_state ans..127 Etat / Région x x

vads_cust_status enum Statut x x

vads_cust_title an..63 Civilité de l’acheteur x x

vads_cust_zip an..64 Code postal x x

vads_ext_info_bil_address_complementans..250

Second line of the address specified forbilling

x

vads_ext_info_bil_date_of_birth Datetime The buyer’s date of birth on the receipt x

vads_ext_info_bil_gender n1 The buyer’s gender on the receipt x

vads_ext_info_fingerprint_id string Unique session identifier x



Shipping details


vads_ext_info_deadlinen

Definition of the delivery delay in days (Ndays)

x

vads_ext_info_ship_address_complementans..250

Second line of the address specified for theshipping

x

vads_ext_info_ship_date_of_birthDatetime

The buyer’s date of birth specified for theshipping

x

vads_ext_info_ship_gendern1

The buyer’s gender specified for theshipping

x

vads_ship_to_city an..128 Ville x x

vads_ship_to_country a2 Code pays suivant la norme ISO 3166 x x

vads_ship_to_delayenum

Délai de livraison, obligatoire pour unelivraison prioritaire

x

vads_ship_to_delivery_company_name ans..127 Nom du transporteur x

vads_ship_to_district ans..127 Quartier x x

vads_ship_to_first_name ans..63 Prénom x

vads_ship_to_last_name ans..63 Nom x

vads_ship_to_legal_name an..100 Raison sociale x

vads_ship_to_nameans..63

Déprécié. Nom de l’acheteur.Utilisez vads_ship_to_first_name etvads_ship_to_last_name.

x x

vads_ship_to_phone_num ans..32 Numéro de téléphone x x

vads_ship_to_speed enum Rapidité de livraisondesc_ship_to x

vads_ship_to_state ans..127 Etat / Région x x

vads_ship_to_status enum Définit le type d'adresse de livraison x x

vads_ship_to_street ans..255 Adresse postale x x

vads_ship_to_street_number an..5 Numéro de rue x x

vads_ship_to_street2 ans..255 Deuxième ligne d’adresse x x

vads_ship_to_type enum Type de transport x

vads_ship_to_user_infoans..255

Informations sur l'acheteur (Identifiantlégal CPF/CNPJ)

x x

vads_ship_to_zip an..64 Code postal x x

vads_shipping_amount n..12 Shipping fee amount x



Payment method details


vads_bank_code n5 Code associated with the issuing bank. x

vads_bank_productan..3

Product code of the card used for thepayment.

x

vads_birth_day n..2 Date of birth of the cardholder. x

vads_birth_month n..2 Month of birth of the cardholder. x

vads_birth_year n4 Year of birth of the cardholder. x

vads_card_brand an..127 Type of card used for the payment. x x

vads_card_countrya2

Country code alpha-2 (ISO 3166) of the cardused for the payment.

x

vads_card_number n..36 Masked card number. x

vads_card_holder_name ans..255 Name of the cardholder. x

vads_expiry_monthn..2

Expiry month of the card used for thepayment.

x

vads_expiry_yearn4

Expiry year of the card used for thepayment.

x

vads_proof_of_id_numberan..13

Field reserved to the entry of the buyer’s IDnumber on the payment page.

x

vads_proof_of_id_typeenum

This field corresponds to the type of IDselected by the buyer.

x

vads_walletan..127

Allows the merchant to identify the type ofwallet that was used for the payment.

x



Transaction details


vads_acquirer_transient_data json Information specific to the acquirer. x

vads_amountn..12

Transaction amount expressed in thesmallest currency unit (cents for euro).

x x

vads_auth_mode enum Mode of the authorization request. x

vads_auth_numberan..6

Authorization number returned by the bankserver.

x

vads_auth_resultan..11

Return code of the authorization requestreturned by the issuing bank.

x

vads_authent_nsuans..255

Unique Sequence Number. Used in LatinAmerica.

x

vads_capture_delay n..3 Delay in days before capture in the bank. x x

vads_change_ratestring

Exchange rate used to calculate theeffective payment amount (multi-currencypayment).

x

vads_contract_used ans..250 Merchant ID used. x

vads_contracts map Merchant ID to be used. x

vads_currencyn3

Numeric code of the currency to be used forthe payment.

x x

vads_effective_amountn..12

The payment amount presented in thesmallest unit of the currency used for thecapture in the bank (cents for euro).

x

vads_effective_creation_daten14

Date of transaction registrationin UTC format (GMT+0, 24H)(YYYYMMDDHHMMSS).

x

vads_effective_currency n3 Currency used for the capture in the bank. x

vads_ext_trans_id enum External transaction reference. x

vads_first_installment_delayn..3

Number of deferred months to be usedfor the first installment of payment ininstallments.

x

vads_operation_typeenum

Type of operation: debit, credit (refund),verification.

x

vads_payment_cards listed'enum

List of payment methods to offer to thebuyer.

x

vads_payment_certificatean40

Field populated by the payment platformif the authorization has been successfullycompleted.

x

vads_payment_config enum Payment type: immediate or installment. x x

vads_payment_option_code an..5 Code of the used payment option. x x

vads_payment_seq json Split payment sequence. x

vads_payment_src enum Entry mode for payment method data. x x

vads_presentation_date n14 Requested capture date. x

vads_requestorenum

In order to modify the value of the "Aceite"field for a Boleto Bancario

x x

vads_sequence_numbern..3

Transaction sequence (installment)number.

x

vads_token_id an..32 Payment order ID associated with thetransaction.

x

vads_trans_daten14

Date and time in UTC format (GMT+0,24H) (YYYYMMDDHHMMSS).

x x

vads_trans_id n6 Unique transaction ID. x x

vads_trans_status enum Transaction status. x

vads_trans_uuidans32

Unique transaction ID generated by thepayment platform.

x

vads_validation_mode n1 Transaction validation mode. x x

vads_warranty_result enum Liability shift in case of accepted payment. x



3DS Authentication


vads_threeds_auth_type

enum

Indicates the authentication typeof the cardholder (CHALLENGE orFRICTIONLESS) . Returned only if the buyerhas correctly authenticated him/herself(vads_threeds_status is “Y” or “A”).

x

vads_threeds_cavv

ans..28

Indicates cardholder authentication via theACS.It is populated by the 3DSauthentication server (ACS) when the buyerhas correctly authenticated him/herself(vads_threeds_status equals "Y" or "A").

x

vads_threeds_cavvAlgorithm

n1

Algorithm used by the ACS to generate theCAVV value.It is populated by the 3DS authenticationserver (ACS) when the buyer hascorrectly authenticated him/herself(vads_threeds_status equals "Y" or "A").

x

vads_threeds_eci

n..2

Indicates the E-Commerce index.It is populated by the 3DSauthentication server (ACS) when the buyerhas correctly authenticated him/herself(vads_threeds_status equals "Y" or "A").

x

vads_threeds_enrolled

a1

Indicates the enrollment status of thecardholder.It is populated by the VISA andMASTERCARD (DS) servers during the 3DSecure authentication process.

x

vads_threeds_error_coden..2

Deprecated.Use vads_threeds_exit_status.

x

vads_threeds_exit_statusn..2

Indicates the final status of 3D Secureauthentication.It is populated by the payment gateway.

x

vads_threeds_mpin1

Enables/disables the 3DS authenticationprocess during an e-commerce payment.

x

vads_threeds_sign_validn1

Indicates the validity of the PAResmessage signature.It is populated by the payment gateway.

x

vads_threeds_status

a1

Indicates the authentication status of thecardholder.It is populated by the 3DS authenticationserver (ACS) during the 3D Secureauthentication process.

x

vads_threeds_xid

ans..28

Indicates the unique 3DS authenticationreference.It is populated by the authentication server(ACS) during the 3D Secure authenticationprocess.

x



Customizing the payment page


vads_available_languages Enum listAllows to specify the list of languagesavailable on the payment page.

x x

vads_language a2Defines the language of the payment page(ISO 639-1 standard).

x x

vads_iframe_options json Allows you to customize the backgroundcolor and the font of the input fields iniframe mode.

x

vads_shop_nameans..127

Allows to define the shop name as itappears in the payment confirmation e-mails.

x x

vads_shop_urlans..1024

Allows to override the shop URL thatappears on the payment page and inpayment confirmation e-mails.

x x

vads_theme_config mapAllows to customize certain elements onthe payment page.

x



Redirection to the merchant website


vads_redirect_error_message

ans..255

Automatic redirection:Message displayed on the payment pageprior to redirection after an accepted/declined payment.

x

vads_redirect_error_timeout

n..3

Automatic redirection:Delay (in seconds) before automaticredirection to the merchant website afteran accepted/declined payment.

x

vads_redirect_success_message

ans..255

Automatic redirection:Specifies the message that will appear uponautomatic redirection to the merchantwebsite at the end of an accepted payment.

x

vads_redirect_success_timeout

n..3

Automatic redirection:Allows to define a delay in seconds beforean automatic redirection to the merchantwebsite at the end of an accepted payment.Its value is between 0 and 600s.

x

vads_return_modeenum

Allows to specify the data transmissionmode to the URLs of return to the merchantwebsite.

x

vads_url_cancelans..1024

URL where the buyer will be redirectedafter clicking on “Cancel and return to shop”before proceeding to payment.

x

vads_url_checkans..1024

URL of the page to notify at the end ofpayment. Overrides the value entered inthe notification rule settings.

x

vads_url_check_src enumThis parameter defines the triggering eventof the instant notification (also called IPN).

x

vads_url_error ans..1024URL where the buyer will be redirected incase of an internal processing error.

x

vads_url_post_walletans..1024

URL using which the merchant will berecalled if a wallet is used during thepayment.

x x

vads_url_refused ans..1024URL where the buyer will be redirected incase of a rejected payment.

x

vads_url_returnans..1024

Default URL where the buyer will beredirected after clicking on “Return toshop”.

x

vads_url_success ans..1024URL where the buyer will be redirected incase of a successful transaction.

x



Recurring payment details


vads_identifier ans..50Unique identifier associated with apayment method.

x x

vads_identifier_status enum Mandate registration status. x

vads_recurrence_number n..2Recurrence number of the recurringpayment.

x

vads_recurrence_status enum Recurrence creation status.

vads_sub_amountn..12

Amount of each installment except theones that will be eventually defined by thevads_sub_init_amount_number.

x

vads_sub_currencyn3

Numeric code of the currency to be used forthe recurring payment in compliance withthe ISO 4217.

x x

vads_sub_descans..255

Rule for recurring payments to applyaccording to the iCalendar RFC5545specification.

x x

vads_sub_effect_date n8 Recurring payment start date. x x

vads_sub_init_amountn..12

Amount of the first installments of therecurring payment.

x x

vads_sub_init_amount_numbern..3

Number of installments for which theamount vads_sub_init_amount should beapplied.

x x

vads_subscription ans..50 Recurring payment ID. x x

Risk analysis details


vads_risk_analysis_resultenum

Result of risk assessment analysisperformed by an external system(ClearSale, CyberSource, etc.).

x

vads_risk_assessment_resultenum

Result of advanced risk assessment analysisperformed by the payment gateway.

x

vads_risk_control map Result of risk assessment. x



signature

Description Mandatory parameter.

Allows to verify the integrity of transmitted requests.

This value is computed:

• by the merchant website during the payment request,

• by the payment gateway during the of response.

Input and output field, returned in the response (IPN and Return URL).

Format an40

Error code 00 - signature Appears if the value of this field is incorrect,

70-empty params if the field is absent or empty.

Frequent errors:

• The fields of the form have not been encoded in UTF-8.

• The MODE (TEST or PRODUCTION) or the key used is incorrect.

• Line break or carriage return posted in the form.

• Quotation marks ["] posted in the form.

• The type of computation algorithm used is not the correct one.

• The transmitted signature does not respect the rule of signature computation.

Category Technical details

vads_acquirer_transient_data

Description Allows to transmit specific information to one or more networks.

Note

An error will be sent upon submission of the form if the specified value does notrespect the rules established by the acquirer.

Input field.

Format json

Error codes 130, 133, 134, 135, 136, 137

Category Transaction details.



vads_action_mode


Data acquisition mode of the credit card details.


Format enum

Error code 47

Possible values INTERACTIVE: entry of the card details on the payment page of the payment gateway.

IFRAME: entry of the card details on a simplified and streamlined payment page thatthe merchant can embed into the web page of their choice.


vads_amount

Description Transaction amount expressed in the smallest currency unit (cents for euro).

Example: for a transaction of 10 EUR and 28 cents, the value of the parameter is 1028.

The payment form will be rejected in the following cases:

• an amount equal to zero [vads_amount=0],

• a negative amount [vads_amount=-100],

• an amount with decimals or points |vads_amount=100.50],

• a form without the vads_amount field (amount absent).

A message notifying of a technical error will be associated with a 09 return code(vads_extra_result).


Format n..12

Error code 09




vads_auth_mode

Description Specifies the mode of the authorization request.

Output field, returned in the response (IPN and Return URL).

Format enum

Possible valuesFULL: corresponds to an authorization for the total amount of the transaction.

Value used for immediate payments if the period between the requested capturedate and the current date is strictly shorter than the authorization validity period.

MARK: corresponds to an authorization for 1 EUR (or information request about theCB network if the acquirer supports it).

Value used for deferred payments if the period between the requested capture dateand the current date is strictly greater than the authorization validity period.


vads_auth_number

Description Authorization number returned by the authorization server, if available (otherwise,empty).


Format an..6

Category Transaction details



vads_auth_result

Description Return code of the authorization request returned by the issuing bank, if available.


Format an..3

Possible values

Codes returned on the CB: network

Value DescriptionGrounds offraud

Value DescriptionGrounds offraud

00 Approved or successfully processedtransaction

38 Expired card

02 Contact the card issuer 41 Lost card YES

03 Invalid acceptor YES 43 Stolen card YES

04 Keep the card YES 51 Insufficient balance or exceededcredit limit

05 Do not honor YES 54 Expired card YES

07 Keep the card, special conditions YES 55 Incorrect secret code

08 Confirm after identification 56 Card absent from the file YES

12 Invalid transaction YES 57 Transaction not allowed for thiscardholder

YES

13 Invalid amount YES 58 Transaction not allowed for thiscardholder

14 Invalid cardholder number YES 59 Suspected fraud YES

15 Unknown issuer YES 60 The acceptor of the card mustcontact the acquirer

17 Canceled by the buyer 61 Withdrawal limit exceeded

19 Retry later 63 Security rules unfulfilled YES

20 Incorrect response (error on thedomain server)

68 Response not received or receivedtoo late

24 Unsupported file update 75 Number of attempts for entering thesecret code has been exceeded

25 Unable to locate the registeredelements in the file

76 The cardholder is already blocked,the previous record has been saved

YES

26 Duplicate registration, the previousrecord has been replaced

90 Temporary shutdown

27 File update edit error 91 Unable to reach the card issuer

28 Denied access to file 94 Duplicate transaction

29 Unable to update 96 System malfunction

30 Format error 97 Overall monitoring timeout.

31 Unknown acquirer company ID YES 98 Server not available, new networkroute requested

33 Expired card YES 99 Initiator domain incident

34 Suspected fraud YES



Codes returned by Amex Global acquirer:

Code Description

000 Approved

001 Approved with an ID

002 Partial approval (Prepaid Cards only)

100 Declined

101 Expired card / Invalid expiry date

106 Exceeded PIN entry attempts

107 Please Call Issuer

109 Invalid merchant

110 Invalid amount

111 Invalid account / Invalid MICR (Travelers Cheque)

115 Requested function not supported

117 Invalid PIN

119 Cardholder not enrolled / not allowed

122 Invalid card security code (a.k.a., CID, 4DBC, 4CSC)

125 Invalid effective date

181 Format error

183 Invalid currency code

187 Deny - New card issued

189 Deny - Account canceled

200 Deny - Pick up card

900 Accepted - ATC Synchronization

909 System malfunction (cryptographic error)

912 Issuer not available

Codes returned by Elavon Europe acquirer:

Code Description

0 Approved, success

1 Refer To Card Issuer Client

2 Refer To Card Issuer, Special Condition

3 Invalid Merchant

4 Pick-Up Card

5 Do Not Honour

6 Error

7 Pick-Up Card, Special Condition

8 Honour With Identification

9 Request In Progress

10 Approved, Partial

11 Approved, VIP

12 Invalid Transaction

13 Invalid Amount

14 Invalid Card Number

15 No Such Issuer

16 Approved, Update Track 3

17 Operator Cancelled

18 Customer Dispute

19 Re Enter Transaction

22 Suspected Malfunction

23 Unacceptable Transaction Fee

24 File Update Not Supported

25 Unable To Locate Record



Code Description

26 Duplicate Record

27 File Update Edit Error

28 File Update File Locked

30 File Update Failed

31 Bank Not Supported

32 Completed Partially

33 Expired Card, Pick-Up

34 Suspected Fraud, Pick-Up

35 Contact Acquirer, Pick-Up

36 Restricted Card, Pick-Up

37 Call Acquirer Security, Pick-Up

38 PIN Tries Exceeded, Pick-Up

39 No Credit Account

40 Function Not Supported

41 Lost Card (Contact Bank)

42 No Universal Account

43 Stolen Card

44 No Investment Account

51 Not Sufficient Funds (Client To Contact Bank)

52 No Check Account

53 No Savings Account

54 Expired Card (Contact Bank)

55 Incorrect PIN

56 No Card Record

57 Transaction Not Permitted To Cardholder

58 Transaction Not Permitted On Terminal

59 Suspected Fraud

60 Contact Acquirer

61 Exceeds Withdrawal Limit

62 Restricted Card

63 Security Violation

64 Original Amount Incorrect

65 Exceeds Withdrawal Frequency

66 Call Acquirer Security

67 Hard Capture

68 Response Received Too Late

75 PIN Tries Exceeded

77 Intervene, Bank Approval Required

78 Intervene, Bank Approval Required For Partial Amount

90 Cut-Off In Progress

91 Issuer Or Switch Inoperative

92 Routing Error

93 Violation Of Law

94 Duplicate Transaction

95 Reconcile Error

96 Communication System Malfunction

97 Communication Error - Cannot Connect To FNB

98 Exceeds Cash Limit

76 Approved Country Club

79 Approved Administrative Transaction

80 Approved National Negative File Hit OK

81 Approved Commercial



Code Description

82 No Security Module

83 Maximum Refund credit Limit exceeded

84 No PBF

85 PBF Update Error

86 Invalid Authorisation Type

87 Bad Track 2

88 PTLF Error

89 Invalid Route Service

Codes returned by the GICC network

Code Description

0 Approved or completed successfully

2 Call Voice-authorization number; Initialization Data

3 Invalid merchant number

4 Retain card

5 Authorization declined

10 Partial approval

12 Invalid transaction

13 Invalid amount

14 invalid card

21 No action taken

30 Format Error

33 Card expired

34 Suspicion of Manipulation

40 Requested function not supported

43 Stolen Card, pick up

55 Incorrect personal identification number

56 Card not in authorizer's database

58 Terminal ID unknown

62 Restricted Card

78 Stop payment order

79 Revocation of authorization order

80 Amount no longer available

81 Message-flow error

91 Card issuer temporarily not reachable

92 The card type is not processed by the authorization center

96 Processing temporarily not possible

97 Security breach - MAC check indicates error condition

98 Date and time not plausible

99 Error in PAC encryption detected

Other return codes For payment methods that are different from the ones presented below:

• see the technical documentation specific to the payment method

or

• contact the technical support for more information.




vads_authent_paypal_protection_eligibility

Description Type of merchant protection used for the transaction.

Three values are possible:

• ELIGIBLE

Merchant is protected by PayPal's Seller Protection Policy for unauthorizedpayments and Item Not Received.

• PARTIALLY_ELIGIBLE

Merchant is protected by PayPal's Seller Protection Policy for Item Not Received.

• INELIGIBLE

Merchant is not protected by PayPal's Seller Protection Policy for Item NotReceived.

Concerns only the PayPal payment method.


Format enum

Category Order details.

vads_authent_nsu

Description Unique sequence number (Latin America).


Format ans..255




vads_available_languages

Description Allows to specify the list of languages available on the payment page.

The elements of the list must be separated by a semi-colon ( ; ).

The languages on the payment page are represented by flags.


Format language1;language2;language3

Error code 71

Possible values Language Value Flag shown by default

German de x

English en x

Chinese zh x

Spanish es x

French fr x

Italian it x

Japanese ja x

Dutch nl x

Polish pl

Portuguese pt x

Russian ru x

Swedish sv x

Turkish tr x

E.g.: to show the flags for French and English, post vads_available_languages=fr;en

Category Customization of the payment page.

vads_avs_result

Description Transmits the result of the address verification performed by the buyer.

This verification only applies to the numeric part of the billing address.

The Address Verification Service is supported in the USA, Canada and UnitedKingdom.


Format a1

Possible values Code Visa MasterCard Discover American Express

Y Address & 5-digit or 9-digit ZIPmatch

Address & 5-digitZIP match

Address onlymatches

Address & ZIPmatch

A Address matches,ZIP does not

Address matches,ZIP does not


Address onlymatches

S AVS notsupported

AVS notsupported

AVS notsupported

AVS notsupported

R Systemunavailable, retry

Systemunavailable, retry

Not applicable Systemunavailable, retry

U Information notavailable

Information notavailable

Systemunavailable, retry




Code Visa MasterCard Discover American Express

Z Either 5-digit or9-digit ZIP match,address does not

5-digit ZIPmatches, addressdoes not

5-digit ZIPmatches, addressdoes not

ZIP code onlymatches

N Neither ZIP noraddress match

Neither ZIP noraddress match



W Not applicable For U.S., 9-digitZIP matches,address does not.For non-U.S., ZIPmatches, addressdoes not


Not applicable

X Not applicable For U.S., all digitsmatch. For non-U.S., ZIP andaddress match.


Not applicable

B Address matches,ZIP not verified

Not applicable Not applicable Not applicable

T Not applicable Not applicable 9-digit ZIPmatches, addressdoes not

Not applicable

P ZIP matches,address notverified


C Address and ZIPnot verified


D Address &ZIP match(Internationalonly)


G Addressnot verified(Internationalonly)


I Addressnot verified(Internationalonly)


M Address &ZIP match(Internationalonly)


F Address & ZIPmatch (UK only)





vads_bank_code

Description Code associated with the issuing bank.


Format n5

Category Payment method details.

vads_bank_label

Description Name of the issuing bank of the payment card.


Format ans..255

Note: alphanumeric and special character format that can contain accentedcharacters (except "<" and ">").


vads_bank_product

Description Product code of the card used for the payment.

Output field, returned in the response (IPN and return URL).

Format an..20

Possible values

VISA Title

A Visa Traditional

B Visa Traditional Rewards

C Visa Signature

D Visa Signature Preferred

E Proprietary ATM

F Visa Classic

G Visa Business

G1 Visa Signature Business

G2 Reserved

G3 Visa Business Enhanced

H Reserved

I Visa Infinite

J Reserved

J1 Reserved

J2 Reserved

J3 Visa Healthcare

J4 Reserved

K Visa Corporate T&E

K1 Visa GSA Corporate T&E

L Electron

N Visa Platinium

N1 TBA

P Visa Gold



VISA Title

Q Private Label

Q1 Reserved

R Proprietary

S Visa Purchasing

S1 Visa Purchasing

S2 Visa Purchasing

S3 Visa Purchasing

S4 Government Services Loan

S5 Commercial Transport EBT

S6 Business Loan

S7 Visa Distribution

T Reserved

U Visa TravelMoney

V Visa VPay

W Reserved

X Reserved

Y Reserved

Z Reserved

I2 VISA ULTRA HIGH NET WORTH

G5 VISA BUSINESS REWARDS

G4 VISA INFINITE BUSINESS

I1 VISA INFINITE PRIVILEGE

N2 VISA SELECT

Q2 PRIVATE LABEL BASIC

Q3 PRIVATE LABEL STANDARD

Q4 PRIVATE LABEL ENHANCED

Q5 PRIVATE LABEL SPECIALIZED

Q6 PRIVATE LABEL PREMIUM



MASTERCARD Title

BPD BUSINESS PREMIUM DEBIT

CIR CIRRUS

DAG GOLD DEBIT MASTERCARD SALARY

DAP PLATINUM DEBIT MASTERCARD SALARY

DAS STANDARD DEBIT MASTERCARD SALARY

DDB DOMESTIC DEBIT BRAND

DLG DEBIT GOLD DELAYED DEBIT

DLH DEBIT WORLD EMBOSSED DELAYED DEBIT

DLP DEBIT PLATINUM DELAYED DEBIT

DLS MASTERCARD CARD-DELAYED DEBIT

DOS STANDARD DEBIT MASTERCARD SOCIAL

DWF DEBIT MASTERCARD HUMANITARIAN PREPAID

M MASTERCARD

MAB WORLD ELITE MASTERCARD

MAC MASTERCARD CORPORATE WORLD ELITE

MBB MASTERCARD PREPAID CONSUMER

MBC MASTERCARD PREPAID VOUCHER

MBD MASTERCARD PROFESSIONAL DEBIT BUSINESS CARD

MBE MASTERCARD ELECTRONIC BUSINESS CARD

MBK MASTERCARD BLACK

MBP MASTERCARD UNKNOWN PRODUCT

MBS MASTERCARD B2B PRODUCT

MBT MASTERCARD CORPORATE PREPAID TRAVEL

MBW WORLD MASTERCARD BLACK EDITION – DEBIT

MCB MASTERCARD BUSINESS CARD

MCC MASTERCARD CREDIT MIXED BIN CARD

MCD MASTERCARD DEBIT CARD

MCE MASTERCARD ELECTRONIC CARD

MCF MASTERCARD FLEET CARD

MCG MASTERCARD GOLD CARD

MCH MASTERCARD PREMIUM CHARGE

MCO MASTERCARD CORPORATE CARD

MCP MASTERCARD PURCHASING CARD

MCS MASTERCARD STANDARD CARD

MCT TITANIUM MASTERCARD CARD

MCV MERCHANT BRANDED PROGRAM

MCW WORLD MASTERCARD CARD

MDB DEBIT MASTERCARD BUSINESSCARD CARD

MDG DEBIT GOLD MASTERCARD CARD

MDH DEBIT OTHER EMBOSSED

MDJ DEBIT OTHER 2 EMBOSSED

MDL BUSINESS DEBIT OTHER EMBOSSED

MDN BUSINESS DEBIT OTHER 2 EMBOSSED

MDO DEBIT OTHER CARD

MDP DEBIT PLATINUM CARD

MDR DEBIT BROKERAGE CARD

MDS DEBIT MASTERCARD CARD

MDT MASTERCARD BUSINESS DEBIT

MDW WORLD ELITE DEBIT MASTERCARD / MASTERCARD BLACK DEBIT

MEB MASTERCARD EXECUTIVE BUSINESS CARD

MEC MASTERCARD ELECTRONIC COMMERCIAL CARD

MEF ELECTRONIC PAYMENT ACCOUNT



MASTERCARD Title

MEO MASTERCARD CORPORATE EXECUTIVE CARD

MET TITANIUM DEBIT MASTERCARD

MFB FLEX WORLD ELITE

MFD FLEX PLATINUM

MFE FLEX CHARGE WORLD ELITE

MFH FLEX WORLD

MFL FLEX CHARGE PLATINUM

MFW FLEX CHARGE WORLD

MGF MASTERCARD GOUVERNMENT COMMERCIAL CARD

MHA MASTERCARD HEALTHCARE PREPAID NON-TAX

MHB MASTERCARD HSA SUBSTANTIATED

MHD HELOC DEBIT STANDARD

MHH MASTERCARD HSA NON-SUBSTANTIATED

MHL HELOC DEBIT GOLD

MHM HELOC DEBIT PLATINUM

MHN HELOC DEBIT PREMIUM

MIA PREPAID MASTERCARD UNEMBOSSED STUDENT CARD

MIP PREPAID DEBIT MASTERCARD STUDENT CARD

MIU DEBIT MASTERCARD UNEMBOSSED

MLA MASTERCARD CENTRAL TRAVEL SOLUTIONS AIR CARD

MLD MASTERCARD DISTRIBUTION CARD

MLL MASTERCARD CENTRAL TRAVEL SOLUTIONS LAND CARD

MNF MASTERCARD PUBLIC SECTOR COMMERCIAL CARD

MNW MASTERCARD NEW WORLD

MOC MASTERCARD UNKNOWN PRODUCT

MOG MAESTRO GOLD

MOP MAESTRO PLATINIUM

MOW MAESTRO WORLD

MPA MASTERCARD PREPAID DEBIT STANDARD-PAYROLL

MPB PREFERRED BUSINESS CARD

MPC MPC

MPF MASTERCARD PREPAID DEBIT STANDARD-GIFT

MPG MASTERCARD UNEMBOSSED PREPAID STUDENT CARD

MPH MASTERCARD CASH PREPAID

MPJ PREPAID DEBIT MASTERCARD CARD GOLD

MPK PREPAID MASTERCARD GOUVERNMENT COMMERCIAL CARD

MPL PLATINIUM MASTERCARD CARD

MPM MASTERCARD PREPAID DEBIT STANDARD-CONSUMER INCENTIVE

MPN MASTERCARD PREPAID DEBIT STANDARD-INSURANCE

MPO MASTERCARD PREPAID DEBIT STANDARD-OTHER

MPP PRE-PAID CARD

MPR MASTERCARD PREPAID DEBIT STANDARD-TRAVEL

MPT MASTERCARD PREPAID DEBIT STANDARD-TEEN

MPV MASTERCARD PREPAID DEBIT STANDARD-GOVERNMENT

MPW DEBIT MASTERCARD BUSINESS CARD PREPAID WORK B2B

MPX MASTERCARD PREPAID DEBIT STANDARD-FLEX BENEFIT

MPY MASTERCARD PREPAID DEBIT STANDARD-EMPLOYEE INCENTIVE

MPZ MASTERCARD PREPAID DEBIT STANDARD – GOVERNMENT CONSUMER

MRC MASTERCARD ELECTRONIC CONSUMER PREPAID

MRF STANDARD DEFERRED

MRG MASTERCARD STANDARD PREPAID

MRH MASTERCARD UNKNOWN PRODUCT



MASTERCARD Title

MRJ PREPAID MASTERCARD GOLD CARD

MRK PREPAID MASTERCARD PUBLIC SECTOR COMMERCIAL CARD

MRL MASTERCARD PREPAID BUSINESS PREFERRED

MRO MASTERCARD REWARDS ONLY

MRP STANDARD RETAILER CENTRIC PAYMENTS

MRW MASTERCARD CREDIT BUSINESS CARD PREPAID

MSA PREPAID MAESTRO PAYROLL CARD

MSB MAESTRO SMALL BUSINESS CARD

MSF PREPAID MAESTRO GIFT CARD

MSG PREPAID MAESTRO CONSUMER RELOADABLE CARD

MSI MAESTRO

MSJ PREPAID MAESTRO GOLD

MSM PREPAID MAESTRO CONSUMER PROMOTION CARD

MSN PREPAID MAESTRO INSURANCE CARD

MSO PREPAID MAESTRO OTHER CARD

MSQ RESERVED FOR FUTURE USE

MSR PREPAID MAESTRO TRAVEL CARD

MST PREPAID MAESTRO TEEN CARD

MSV PREPAID MAESTRO GOVERNMENT BENEFIT CARD

MSW PREPAID MAESTRO CORPORATE CARD

MSX PREPAID MAESTRO FLEX BENEFIT CARD

MSY PREPAID MAESTRO EMPLOYEE INSENTIVE CARD

MSZ PREPAID MAESTRO EMERGENCY ASSISTANCE CARD

MTP MASTERCARD PLATINUM PREPAID TRAVEL CARD

MUW WORLD DOMESTIC AFFLUENT

MWB WORLD MASTERCARD FOR BUSINESS

MWD WORLD DEFERRED

MWE MASTERCARD WORLD ELITE

MWF MASTERCARD HUMANITARIAN PREPAID

MWO MASTERCARD CORPORATE WORLD

MWR WORLD RETAILER CENTRIC PAYMENTS

OLB MAESTRO SMALL BUSINESS DELAYED DEBIT

OLG MAESTRO GOLD DELAYED DEBIT

OLP MAESTRO PLATINUM DELAYED DEBIT

OLS MAESTRO-DELAYED DEBIT

OLW MAESTRO WORLD DELAYED DEBIT

PVA PRIVATE LABEL A

PVB PRIVATE LABEL B

PVC PRIVATE LABEL C

PVD PRIVATE LABEL D

PVE PRIVATE LABEL E

PVF PRIVATE LABEL F

PVG PRIVATE LABEL G

PVH PRIVATE LABEL H

PVI PRIVATE LABEL I

PVJ PRIVATE LABEL J

PVL PRIVATE LABEL CARD

SAG GOLD MASTERCARD SALARY–IMMEDIATE DEBIT

SAL STANDARD MAESTRO SALARY

SAP PLATINUM MASTERCARD SALARY–IMMEDIATE DEBIT

SAS STANDARD MASTERCARD SALARY–IMMEDIATE DEBIT

SOS STANDARD MASTERCARD SOCIAL–IMMEDIATE DEBIT



MASTERCARD Title

SUR PREPAID MASTERCARD UNEMBOSSED (NON-US)

TBE MASTERCARD ELECTRONIC BUSINESS IMMEDIATE DEBIT

TCB MASTERCARD BUSINESS CARD-IMMEDIATE DEBIT

TCC MASTERCARD MIXED BIN-IMMEDIATE DEBIT

TCE MASTERCARD ELECTRONIC IMMEDIATE DEBIT

TCF MASTERCARD FLEET CARD IMMEDIATE DEBIT

TCG LD MASTERCARD CARD-IMMEDIATE DEBIT

TCO MASTERCARD CORPORATE IMMEDIATE DEBIT

TCP MASTERCARD PURCHASING CARD IMMEDIATE DEBIT

TCS MASTERCARD STANDARD CARD-IMMEDIATE DEBIT

TCW WORLD SIGNIA MASTERCARD CARD-IMMEDIATE DEBIT

TEB MASTERCARD EXECUTIVE BUSINESS CARD IMMEDIATE DEBIT

TEC MASTERCARD ELECTRONIC COMMERCIAL IMMEDIATE DEBIT

TEO MASTERCARD CORPORATE EXECUTIVE IMMEDIATE DEBITCARD

TIU TIU

TNF MASTERCARD PUBLIC SECTOR COMMERCIAL CARD IMMEDIATE DE

TNW MASTERCARD NEW WORLD-IMMEDIATE DEBIT

TPB PREFERRED BUSINESS CARD IMMEDIATE DEBIT

TPL PLATINUM MASTERCARD IMMEDIATE DEBIT

TWB WORLD MASTERCARD BLACK EDITION – IMMEDIATE DEBIT

WBE MASTERCARD UNKNOWN PRODUCT

WDR WORLD DEBIT MASTERCARD REWARDS

WMR WORLD MASTERCARD REWARDS

CB Title

1 National withdrawal card

2 National withdrawal and payment card

3 National payment card

4 National payment and withdrawal card with systematic authorization

5 National payment card with systematic authorization

Other product codes Title

AX AMERICAN EXPRESS

DI DISCOVER

DN DINERS

JC JCB


vads_birth_day

Description Date of birth of the cardholder.

Input field.

Format n..2

Error code 76




vads_birth_month

Description Month of birth of the cardholder.

Input field.

Format n..2

Error code 76


vads_birth_year

Description Year of birth of the cardholder.

Input field.

Format n4

Error code 76


vads_brand_management

Description Indicates to the merchant:

• whether the user has chosen a brand (userChoice attribute),

• the brand chosen by the buyer (brand attribute),

• the list of available brands (brandList attribute).

This field is returned only if brand selection is enabled for the CB contract used forthe payment.


Format json

Possible values Example:

vads_brand_management={"userChoice":true,"brand":"CB","brandList":"CB|VISA"}


vads_capture_delay

Description Indicates the delay (in days) before the capture.

If the parameter is not submitted, the default value specified in the Merchant BackOffice will be used. The default value can be configured in the Merchant Back Officeby all authorized persons.

Notes:

• The value of vads_capture_delay is not taken into account in the case ofpayment in installments MULTI_EXT.

• If the capture delay is higher than 365 days in the payment request, it will beautomatically reset to 365 days.



• If the card used for the payment is a debit card, the capture delay isautomatically reset to 0.

Input and output field.

Format n..3

Error code 06


vads_card_brand

Description Payment method used, if available (empty otherwise).

The value is derived from the BIN range files.


Format an..127

Possible values See the vads_payment_cards field.

The value CB will be returned for co-branded Visa and MasterCard CB cards.


vads_card_country

Description Country code of the card in compliance with the ISO 3166 standard


Format ISO 3166


vads_card_holder_name

Description Name of the cardholder.

In Latin America, this parameter is required for DECIDIR and VISANET.

Input field.

Format ans..255

Error code 45


vads_card_number

Description • Masked card number. Contains the 6 first digits of the number followed by"XXXXXX" and the 4 last numbers in the end.

• IBAN and BIC used for the payment separated by "_" in case of a direct debitpayment.

The BIC is optional so the number may just be the IBAN.



Output field , returned in the response (IPN and Return URL).

Format an..36


vads_change_rate

Description Exchange rate used to calculate the effective payment amount (multi-currencypayment).


Format string




vads_contracts

Description Allows to:

• specify a list with the Merchant ID (MID) to use for each acceptance network,

• exclude a network.

This parameter is optional and is only used when you have several e-commerceMerchant IDs (MID) within the same network and when you wish to select adifferent Merchant ID (MID) depending on the payment.

If this parameter is not specified or absent, the payment will be made with theMerchant ID(s) according to the priority order defined in the Merchant Back Office(Settings > Shop > MID association tab).

Input field.

Format map

Error code 62

Possible values To exclude a network you must use the syntax Network_name=NO.

Example: NETWORK1=contract1;NETWORK2=contract2;NETWORK3=NO

The possible networks are:

Network code Description

AMEXGLOBAL American Express network

ANCV ANCV (e-chèques vacances) network

CARDCOMPLETE CARDCOMPLETE network

CB CB Network

CERIDIAN Ceridian network (gift card)

GATECONEX GATECONEX Network

GICC GICC network

GICC_DINERS GICC network (Diners Club cards)

GICC_MAESTRO GICC network (Maestro cards)

GICC_MASTERCARD GICC network (Mastercard cards)

GICC_VISA GICC network (Visa cards)

GIROPAY GIROPAY network

HOBEX_DD Hobex Direct Debit network

IDEAL IDEAL network

JCB JCB Network

KLARNA Klarna Internet Banking network

MASTERPASS MasterPass network

PAYPAL PayPal network

PAYPAL_SB PayPal network - sandbox

POSTFINANCEV2 POSTFINANCE network

SECURETRADING Secure Trading network

SOFORT Sofort Banking network

WIRECARD WIRECARD network

Example for forcing a contract:

vads_contracts="CB=1231231;AMEXGLOBAL=949400444"

vads_contracts="GICC_VISA=1231231;AMEXGLOBAL=949400444"



Example for forbidding the payment within a specific network:

vads_contracts="CB=1231231;AMEXGLOBAL=NO"

vads_contracts="GICC_VISA=1231231;AMEXGLOBAL=NO"

For forcing the Terminal ID (TID):

The required syntax is: "SCHEME=MID:TID".

Example:

vads_contracts="PSE=123456789:123"


vads_contract_used

Description This field defines the value of the Merchant ID (MID) associated with thetransaction. It is populated with the Merchant ID (MID) registered by default in yourshop or it takes the value of the vads_contracts field sent in the payment request.


Format ans..250


vads_contrib

Description Optional information that indicates the name of the CMS used for the payment(Joomla, osCommerce, etc.). If you are developing your own software, this field caninclude your own module version for example.


Format ans..128

Error code 31




vads_ctx_mode


Defines the mode of interaction with the payment gateway.

Affects the choice of the key to be used (test or production) during signaturecomputation.

The TEST mode is available at all times, even after the generation of the productionkey.

If you create a new e-commerce website (or have access to the acceptance testingenvironment), you can make tests without impacting the website that is currentlyin production.

The input and output field, returned in the response (IPN and Return URL).

Format enum

Error code 11

Frequent errors:

• The mode has not been submitted to the payment platform.

• Do not use PROD instead of PRODUCTION

• Do not write the value in lowercase letters (test or production). This field expectsvalues only in uppercase letters without abbreviations.

Possible values TEST, PRODUCTION




vads_currency

Description Numeric currency code to be used for the payment, in compliance with the ISO4217 standard.

To use a currency other than euro (978), you must request the activation of the"currency conversion" option.

Note: All of the listed currencies are available, however, they are not presentedat the moment of contract creation. If the desired currency is not suggested whilecreating your MID, please contact the sales administration .

To use a currency during a payment, you must have a MID created in this currency.The acquirer provides the MID to the merchant with the supported currency(ies)and the gateway takes this information into account when creating a MID.


Format n3

Error code 10

Possible values Currency ISO 4217 encodingNumber of digits afterthe decimal point

Australian Dollar (AUD) 036 2

Cambodian Riel (KHR) 116 0

Canadian Dollar (CAD) 124 2

Chinese Yuan (Renminbi) (CNY) 156 1

Czech Crown (CZK) 203 2

Danish Crown (DKK) 208 2

Hong Kong Dollar (HKD) 344 2

Hungarian Forint (HUF) 348 2

Indian Rupee (INR) 356 2

Indonesian Rupiah (IDR) 360 2

Japanese Yen (JPY) 392 0

South Korean Won (KRW) 410 0

Kuwaiti Dinar (KWD) 414 3

Malaysian Ringgit (MYR) 458 2

Mexican Peso (MXN) 484 2

Moroccan Dirham (MAD) 504 2

New Zealand Dollar (NZD) 554 2

Norwegian Crown (NOK) 578 2

Philippine Peso (PHP) 608 2

Russian Ruble (RUB) 643 2

Singapore Dollar (SGD) 702 2

South-African Rand (ZAR) 710 2

Swedish Crown (SEK) 752 2

Swiss Franc (CHF) 756 2

Thai Baht (THB) 764 2

Tunisian Dinar (TND) 788 3

Pound Sterling (GBP) 826 2

US Dollar (USD) 840 2

Taiwan New Dollar (TWD) 901 2

New Turkish Lira (TRY) 949 2



Currency ISO 4217 encodingNumber of digits afterthe decimal point

Euro (EUR) 978 2

Polish Zloty (PLN) 985 2

Brazilian Real (BRL) 986 2


vads_cust_address

Description Buyer’s postal address.

Note:

Depending on the payment method, certain restrictions can change the format.Applies to FacilyPay and Oney payments for which the field is mandatory and theformat is ans..128. Only the following special characters are authorized:

• space

• slash ( / )

• dash ( - )

• apostrophe ( ' )

• comma ( , )

• dot ( . )

For SEPA Direct Debit payments, the field becomes mandatory if the client hasa bank account in the following regions, territories or countries: Switzerland,Monaco, San Marino, Mayotte, St. Pierre and Miquelon, Guernsey, Jersey, Isle ofMan.


Format ans..255

Note: the characters > and < are not authorized.

Error code 19

Category Buyer details.

vads_cust_address2

Description Second line of the address.


Format ans..255

Error code 19


vads_cust_address_number

Description Buyer's street number.




Format ans..64

Error code 112


vads_cust_cell_phone

Description Buyer’s cell phone number.

Note:

Depending on the payment method, certain restrictions can change the format.This is the case for FacilyPay and Oney payments for which the field is mandatoryand the format is n10.


Format an..32

Error code 77


vads_cust_city

Description Buyer’s city.

Note:

Depending on the payment method, certain restrictions can change the format.Applies to FacilyPay and Oney payments for which the field is mandatory and theformat is ans..128. Only the following special characters are authorized:

• space

• slash ( / )

• dash ( - )

• apostrophe ( ' )


Format an..128

Error code 21


vads_cust_country

Description Allows you to specify the buyer's country code in the ISO 3166 format.


Format a2

Error code 22



Examples ofpossible values

Code Country Code Country

AT Austria IN India

BR Brazil MQ Martinique

CI Ivory Coast NC New Caledonia

FR Corsica PF French Polynesia

FR France PM St. Pierre and Miquelon

GP Guadeloupe US United States of America




vads_cust_district

Description Buyer's district.


Format ans..127

Error code 113


vads_cust_email

Description Buyer's e-mail address, required if you want the payment gateway to send an e-mail to the buyer.

In order to make sure the buyer receives an e-mail, make sure to post thisparameter in the form when you generate a payment request.


Format ans..150

Error code 15


vads_cust_first_name

Description Buyer’s first name.

Note:

Depending on the payment method, certain restrictions can change the format.This is the case for FacilyPay and Oney payments for which the field is mandatoryand the format is an..63.


Format ans..63

Error code 104


vads_cust_id

Description Buyer ID on the merchant side.

Note:



Format an..63

Error code 16




vads_cust_last_name

Description Buyer’s last name.

Note:



Format ans..63

Error code 105




vads_cust_legal_name

Description Buyer's legal name.

Input field.

Format an..100

Error code 121


vads_cust_name

Description Buyer's name.

This field is deprecated. It is replaced by the vads_cust_first_name andvads_cust_last_name fields.


Format an..127

Error code 18


vads_cust_national_id

Description National identifier.

Allows each citizen to identify him/herself with a unique ID within a country.

For example, in Brazil, ClearSale requires this field to be populated with the CPF/CPNJ (in numeric format, between 11 and 20 digits long).


Format ans..255

Error code 124


vads_cust_phone

Description Buyer’s phone number.

Note:



Format an..32

Error code 23




vads_cust_state

Description Buyer's state/region.


Format ans..127

Error code 88




vads_cust_status

Description Buyer type.


Format enum

Error code 92

Possible values PRIVATE, COMPANY


vads_cust_title

Description Buyer's title (e.g. Mr., Mrs., Ms.).


Format an..63

Error code 17


vads_cust_zip

Description Buyer’s postal code.

Note:



Format an..64

Error code 20


vads_effective_amount

Description Payment amount in the currency used for the capture in the bank.


Format n..12

Examples EXAMPLE FOR A SHOP WITH CAPTURE IN EUR

Payment of 10,00 EUR

Parameters sent in the payment form

• vads_amount = 1000

• vads_currency = 978



Returned parameters



• vads_effective_amount = 1000

A payment of 10 US Dollars




Returned parameters



• vads_change_rate= 1.3118 (exchange rate)

• vads_effective_amount = 762 (vads_amount / vads_change_rate)

An installment payment of 90,00 EUR in 3 installments




• vads_payment_config=MULTI_EXT:date1=3000;date2=2000;date3=4000

Returned parameters for the first installment



• vads_effective_amount = 3000



A payment of 90 US dollars paid in 3 installments




• vads_payment_config=MULTI_EXT:20121025=3000;20121026=2000;20121027=4000

Returned parameters for the first installment



• vads_change_rate= 1.3118 (exchange rate)

• vads_effective_amount = 2287 (amount of the 1st installment, $30 / vads_change_rate)


vads_effective_creation_date

Description Date of transaction registration in UTC format (GMT+0, 24H)(YYYYMMDDHHMMSS).


Format n14


vads_effective_currency

Description Code of the currency used for the capture.


Format n3




vads_expiry_month

Description Expiry month of the card used for the payment.


Format n..2


vads_expiry_year

Description Expiry year of the card used for the payment.


Format n4


vads_ext_info

Description Allows to add an optional field to the confirmation e-mail sent to the merchant.

It can be viewed:

• in the Merchant Back Office in the transaction details section (Extras tab).

• in the data transmitted to the merchant website when returning to the shop

• in the data transmitted to the merchant website during the IPN

• by default in the payment confirmation e-mail sent to the merchant

• in the payment confirmation e-mail sent to the buyer if you specify it in thenotification.

Syntax to respect:

vads_ext_info_fieldname=value


Format ans

Error code 91


vads_ext_info_bil_address_complement

Description Specific to Brazil and to the ClearSale fraud analyzer.

Allows to specify additional information about the billing address.

Input field.

Format ans..250




vads_ext_info_bil_date_of_birth

Description Allows to transmit the birth date indicated on the bill to the risk analyzer.

Format : yyyymmdd

Input field.

Format n8


vads_ext_info_bil_gender


Allows to specify on the receipt whether the buyer is male or female.

Input field.

Format n1


vads_ext_info_deadline


Allows to specify the delivery delay in days (N days).

Input field.

Format n

Category Shipping details.

vads_ext_info_fingerprint_id


Unique session identifier.

• This identifier can be generated by the payment gateway.

In this case, this parameter must not be populated.

• The identifier may also be generated by the merchant website

In this case, this parameter must be populated with the desired value of theidentifier. The merchant website must make sure that each identifier is unique.Any registration request containing an existing identifier will be rejected and anerror message will appear.

Input field.

Format string

It is encoded as 128 bytes and can contain uppercase or lowercase characters,numbers or hyphens ([A-Z] [a-z], 0-9, _, -).




vads_ext_info_ship_address_complement


Allows to specify additional information about the shipping address.

Input field.

Format ans..250




vads_ext_info_ship_date_of_birth

Description Allows to specify the buyer's date of birth for the shipping.

Format: yyyymmdd

Input field.

Format n8


vads_ext_info_ship_gender


Allows to specify for the shipping whether the buyer is male or female.

Input field.

Format n1


vads_ext_info_soft_descriptor

Description Allows to customize the brand name.


Format ans..255

Category Order details

vads_ext_trans_id

Description External transaction reference.

Example: Klarna reservation number, PayPal reservation number.


Format ans..20




vads_extra_result

Description Optional code of the response. Its meaning depends on the value specified invads_result.

• If vads_result equals 30 (request error), then vads_extra_result contains thenumeric code of the field with an error in the value or the format. This valuecan be set to 99 in case of an unknown error in the request.

Example: if vads_extra_result contains the value 09, it means that the amountspecified in vads_amount is incorrect (for example, if the amount containsdecimals, as it would not have been converted to cents in advance).

• If vads_result equals 05 (declined) or 00 (accepted), vads_extra_result containsthe numeric code of the risk management result.

Code Description

Empty No verification completed.

00 All the verification processes have been successfully completed.

02 Credit card velocity exceeded.

03 The card is on the merchant's greylist.

04 The country of origin of the card is on the merchant's greylist.

05 The IP address is on the merchant's greylist.

06 The BIN code is on the merchant's greylist..

07 Detection of an e-carte bleue.

08 Detection of a national commercial card.

09 Detection of a foreign commercial card.

14 Detection of a card that requires systematic authorization.

20 Consistency check: countries do not match (country IP address, card country, buyer'scountry).

30 The country of the this IP address belongs to the greylist.

99 Technical issue encountered by the server during a local verification process.


Category Technical details.

vads_first_installment_delay

Description When the acquirer supports the parameter, this field allows to specify the numberof deferred months to be applied on the first due date of the payment ininstallments (ex: Webpay Completa).

The payment will be declined and the vads_payment_error field will be valued at171 in the following cases:

• the merchant is not allowed to defer payments

• the value transmitted in the request is not among the options authorized bythe acquirer.

Input field.

Format n..2

Error code N/A




vads_hash

Description A unique key returned only to the Instant Payment Notification (IPN).


Format an64


vads_identifier

Description Unique identifier (token or UMR) associated with a payment method.

• This identifier can be generated by the payment gateway.


• Otherwise, it can be generated by the merchant website.

In this case, this parameter must be populated with the desired value ofthe identifier. The merchant website must make sure that each identifieris unique. Any registration request containing an existing identifier will berejected and an error message will appear.


Format Two possible formats:

• an32: if the identifier is generated by the payment gateway. This format is onlyuse by the payment gateway.

• ans..50: if the identifier is generated by the merchant. Cannot be an32 in thiscase.

Error code 30

Category Recurring payment details.



vads_identifier_status

Description Appears only if the requested action concerns creating or updating:

• a token (subscription)

• a UMR (SEPA Unique Mandate Reference)


Format string

Possible values Value Description

CREATED The authorization request has been accepted.Token (or UMR for SEPA payment) has been successfully created.

NOT_CREATED The authorization request has been declined.The token (or UMR for SEPA payment) has not been created, andtherefore cannot be viewed in the Merchant Back Office.

UPDATED Token (or UMR for SEPA payment) has been successfully updated.

NOT_UPDATED The token (or UMR for SEPA payment) has not been updated.

ABANDONED The action has been abandoned by the buyer (debtor).The token (or UMR for SEPA payment) has not been created, andtherefore cannot be viewed in the Merchant Back Office.

Category Subscription details.

vads_iframe_options

Description Allows to customize certain elements on the payment page in iframe mode:

• fieldsBackgroundColor: background color of entry fields

• fieldsFontColor: font color in entry fields

Example of syntax:

vads_iframe_options = {"fieldsBackgroundColor":"#000000","fieldsFontColor":"#FFFFFF"}

The result will be:

Input field.

Format json

Error code In case of a format error, the field is ignored and the payment form is not rejected.

Category Payment page customization.



vads_insurance_amount

Description Insurance amount for the entire order.

Concerns only the PayPal payment method.

Input field.

Format n..12

Error code 110


vads_language

Description In the payment request:

Defines the language of the payment page (ISO 639-1 standard).

If the field has not been sent or is empty, the payment page will be shown in thelanguage of the buyer's browser.

In the response:

Returns the value specified in the form if the buyer has not changed the languageof the payment page.

Returns the language selected by the buyer if the buyer has changed it by clickingon a different flag.


Format a2

Error code 12

Possible values Language ISO 639-1 standard

German de

English en

Chinese zh

Spanish es

French fr

Italian it

Japanese ja

Dutch nl

Polish pl

Portuguese pt

Russian ru

Swedish sv

Turkish tr

Category Customizing the payment page



vads_nb_products

Description Allows to define the number of items in the cart.

Note:

This field becomes mandatory for the shopping cart to be taken into account.

When it is populated, the Shopping cart tab becomes available in the transactiondetails via the Merchant Back Office.

However, if the other fields starting with vads_product_ are not populated,the tab will not include any information. For this reason, when populating thevads_nb_products field, it becomes mandatory to populate the other fields startingwith vads_product_.

Input field.

Format n..12


vads_operation_type

Description Allows to identify the type of operation: debit, credit (refund) .


Note

The vads_operation_type field is not returned in the response when a payment iscanceled or abandoned.

Format enum

Possible values • DEBIT

• CREDIT




vads_order_id

Description Order ID. It is also included in the payment confirmation e-mail sent to the buyer.

Alphanumeric field. Only one special character, “-”, is allowed.

If any other special characters are used (&, ;, @, etc.), the payment gateway willreturn an error.

Note:

Depending on the payment method, certain restrictions can change the format.This is the case for FacilyPay, Oney, Illicado payments for which the field ismandatory and the format is an9.


Format ans..64

Error code 13


vads_order_info

Description Order description.


Format an..255

Error code 14


vads_order_info2



Format an..255

Error code 14


vads_order_info3



Format an..255

Error code 14


vads_override_payment_cinematic

Description Optional parameter.



Used by the merchant to request, on individual transactions, a payment workflowdifferent from that one specified in his or her contract ("Payment workflow" field).

Input field.

Note

Only certain contracts exploit this parameter. If a value is selected in a contract thatdoes not exploit the parameter, the data is ignored and no error message is raised.

Format enum

Error code 131

Possible values • (empty)

The MID value is used.

• IMMEDIATE_CAPTURE

Corresponds to a workflow of immediate capture: the capture is triggered bythe acquirer in the day of the transaction.

• DELAYED_CAPTURE

Corresponds to a workflow of deferred capture: the capture is triggered by thepayment gateway, always before the expiry of the authorization request.




vads_page_action


Defines the action to be performed.


Format enum

Error code 46

Possible values • PAYMENT

Payment (using token or not)

• REGISTER

Creation of a token without payment

• REGISTER_UPDATE

Update of information associated with the token

• REGISTER_PAY

Creation of a token during a payment

• REGISTER_SUBSCRIBE

Creation of a token during a recurring payment

• REGISTER_PAY_SUBSCRIBE

Creation of a token during creation of a subscription with payment

• SUBSCRIBE

Using a token to create a recurring payment

• REGISTER_UPDATE_PAY

Update of information associated with the token during a payment




vads_payment_cards

Description Contains the list of payment methods offered to the buyer, separated by “;”.

Example: "VISA;MASTERCARD".

If this list contains only one payment method, the detail entry page for this paymentmethod will directly appear. If not, the payment method selection page will appear.

If this parameter is empty (recommended), the eligible payment methods(currencies, technical constraints, etc.) associated with the shop will be presented.

Input field.

Format type 1;type 2;type 3

Error code 08

The form will be rejected in the following cases:

• the transmitted value does not appear on the list below.

• TOUTES, ALL are not accepted as values. To offer all payment methods, thisparameter should not be posted or be posted empty.

• the transmitted value does not correspond to the payment method availablefor your shop.

• your e-commerce contract was closed by your banking institution. Contact thecustomer service of your payment platform.

• the transmitted value is not eligible in the associated network.

Possible valuesPayment method Card types (vads_payment_cards)

American Express AMEX

Bancontact Mistercash BANCONTACT

CB CB

Diners Club card DINERS

Diners DINERS

Discover card DISCOVER

Discover DISCOVER

e-Chèque-Vacances E_CV

e-carte bleue E-CARTEBLEUE

Euro-Cheque card ECCARD

Hobex direct debit ELV

Giropay GIROPAY

iDeal Internet Banking IDEAL

JCB JCB

Klarna Internet Banking KLARNA

Maestro MAESTRO

Mastercard MASTERCARD

MasterPass MASTERPASS

PayPal PAYPAL

PayPal - Sandbox mode PAYPAL_SB

PostFinance POSTFINANCE

PostFinance E-finance POSTFINANCE_EFIN

SEPA DIRECT DEBIT SDD

Sofort Banking SOFORT_BANKING

Visa VISA

Visa Electron VISA_ELECTRON



Payment method Card types (vads_payment_cards)

Vpay VPAY


vads_payment_certificate

Description This field is populated by the payment gateway if the authorization has beensuccessfully completed.


Format an40




vads_payment_config

Description Defines the type of payment: immediate or installment.

• For a single payment, the value must be set to SINGLE.

• For an installment payment with fixed amounts and dates, the value must beset toMULTI: followed by key=value pairs separated by the ";" character .

The parameters are:

• "first" indicates the amount of the first installment (populated in thesmallest unit of the currency).

• "count" indicates the total number of installments.

• "period" indicates the number of days between 2 installments.

The field order associated with MULTI must be respected.

• For an installment payment with a customized installment schedule, the valuemust be set to MULTI_EXT: followed by the date=amount pairs separated bythe ";" character.

The dates must not be passed.

Using the MULTI_EXT value requires a subscription to the Advanced installmentpayment option.

Note: The value of vads_capture_delay is not taken into account in the case ofpayment in installments MULTI_EXT.


Format enum

Error code 07

Possible values • SINGLE

• MULTI:first= initial_amount;count=installments_nb ;period=interval_in_days

• MULTI_EXT:date1=amount1;date2=amount2;date3=amount3

Example 1 MULTI allows to define an installment payment.

The amount of each installment corresponds to the total amount divided by thenumber of installments.

The amount of the first installment can be different, it can be specified in firstparameter.

In case the remaining amount does not equal zero, it will be added up to theamount of the last installment.

Payment request:

• vads_capture_delay=2

• vads_currency=978

• vads_amount=20000

• vads_payment_config=MULTI:first=10000;count=4;period=30

Result:



A first payment of 100,00 EUR will be captured by the bank in 2 days(vads_capture_delay).

A second payment of 33,33 EUR will be made in 32 days (vads_capture_delay +period).

A third payment of 33,33 EUR will be made in 62 days.

A fourth payment of 33,34 EUR will be made in 92 days.

The total amount is 200,00 EUR (vads_amount= 20000). The remaining amount hasbeen added to the amount of the last installment.

This instruction allows to immediately create 4 payments with the sametransaction number but different sequence numbers (vads_sequence_number).

Example 2 MULTI_EXT allows to define a customized installment schedule. You will be ableto define the amount of each installment.

MULTI_EXT : payment request :

• vads_currency=978

• vads_amount=10000

• vads_payment_config= MULTI_EXT:20150601 =5000; 20150701 =2500;20150808 =2500

Result:

The first payment of 50,00 EUR is scheduled for June 1st 2015.

The second payment of 25,00 EUR is scheduled for July 1st 2015.

The last payment of 25,00 EUR is scheduled for August 8th 2015.

Note :

The total amount must be equal to the value of the vads_amount field. The dateof the last installment cannot be later than 12 months after the date of submissionof the form. If the last installment is scheduled later than the card expiry date, noinstallment will be registered and the buyer will be notified about this issue.




vads_payment_error

Description Error codes that may appear when a payment has been declined.


Format n..3

Possible values

Code Message

1 Transaction not found.

2 Transaction not found.

3 This action has not been authorized for a transaction with the {0} status.

4 This transaction is not authorized in this context.

5 This transaction already exists.

6 Invalid transaction amount.

7 This action is not possible anymore for a transaction created on that day

8 The card expiration date does not allow this action.

9 CVV mandatory for this card.

10 The refund amount is greater than the initial amount.

11 The refunds total amount is greater than the initial amount.

12 Credit duplication (refund) is not authorized.

13 Due to a technical problem, we are unable to process your request.




17 Aurore MID configuration has failed.

18 Cetelem response analysis has failed.

19 Unknown currency.

20 Invalid type card.

21 No MID has been found for this payment. Please modify the data or contact your manager in case the errorreoccurs.

22 Shop not found.

23 Ambiguous MID.

24 Invalid MID


26 Invalid card number.




30 Invalid card number (Luhn)

31 Invalid card number (length)

32 Invalid card number (not found)

33 Invalid card number (not found)

34 Failed verification of the card requiring systematic verification.

35 Failed e-Carte Bleue verification.

36 The transaction has been refused by risk management.

37 Interruption not processed during the payment.


39 3D Secure refusal for the transaction.



42 An internal error occurred while consulting the card number.

43 An internal error occurred while consulting the card number.



Code Message

44 This action is not allowed for proximity transactions.

45 Invalid currency for the modification.

46 The amount is greater than the authorized amount.

47 The desired capture date exceeds the authorization expiration date.

48 The requested modification is invalid.

49 Invalid definition of the installment payment.

50 Unknown shop.

51 Unknown exchange rate.

52 The MID has been terminated since {0}.

53 The shop {0} has been closed since {1}.

54 Rejected parameter that may contain sensitive data {0}.


57 An error occurred while retrieving the token.

58 The token status is not compatible with this operation.

59 An error occurred while retrieving the token.

60 This token already exists.

61 Invalid token

62 Token creation failed.

63 This recurring payment already exists.

64 This recurring payment is already terminated.

65 Invalid recurring payment.

66 Invalid recurrence rule.

67 Recurring payment creation failed.

68 Cancellation is not authorized.


70 Invalid country code.

71 Invalid web service parameter.

72 The authorization has been declined by Cofinoga.

73 The authorization for 1 EUR (or information request about the CB network if the acquirer supports it) has beendeclined.

74 Invalid payment configuration.

75 The operation has been declined by PayPal.

76 The cardholder's name is absent.


78 Transaction ID missing

79 This transaction ID is already used.

80 Transaction ID expired.

81 Invalid contents of the config theme.

82 The refund is not authorized.

83 The transaction amount does not respect the allowed values.



88 Refund impossible: transaction refunds are not forbidden by PayPal after a 60-day delay.

89 The modification is not authorized.

90 An error occurred during refund.

91 No payment options have been enabled for this MID

92 An error occurred while calculating the payment channel.

93 An error occurred during buyer redirection to the page of payment finalization.

94 A technical error has occurred.

96 An error occurred while capturing this transaction.

97 The capture date is too far.

98 Invalid transaction date.

99 An error occurred while calculating the payment source.



Code Message

100 Failed commercial card verification.

101 Declined due the refusal of the first installment.

103 The transaction status could not be synchronized with the external system.

104 An error occurred while capturing this transaction.

105 A security error occurred while processing 3DS authorization for this transaction.

106 Unsupported currency on this Merchant ID (MID) and/or shop.

107 The card associated with the token is not valid anymore.


109 The timeout has been exceeded during buyer redirection.

110 Payment card not supported by the MID.

111 The transactions have been refused without Liability shift.

112 Cancellation is not authorized.

113 Duplication is not authorized.

115 The refund is not authorized.

116 Manual payment not authorized for this card.

118 Manual installment payment not authorized for this card.

119 The submitted date is invalid.

120 The initial transaction option is not applicable.

124 Inactive card.

125 Payment refused by the acquirer.

126 This action is impossible as the payment sequence has not been completed.

128 Invalid payment method.

129 Invalid PIN.

130 Out of balance

131 Insufficient balance

136 The derivative transactions have been refused without Liability shift for the initial transaction.

137 Duplicate transaction.

138 Partial refund is impossible for this transaction.

139 Refund refused.


141 The transaction has been declined by the risk analyzer.

142 The card type used is not valid for the requested payment mode.


144 A transaction in production mode has been marked as in test mode by the acquirer.

145 A transaction in test mode has been marked as in production mode by the acquirer.

146 Invalid SMS code.

147 The risk management module has requested for this transaction to be declined.

148 Due to a technical problem, we are unable to process your request. Transaction has not been created.

149 The payment session has expired (the buyer has been redirected to the ACS and has not finalized the 3D Secureauthentication).

150 Due to a technical problem, we are unable to process your request. Transaction has not been created.

151 A Facily Pay transaction cannot be canceled/edited/refunded between 11.30pm and 5.30am.


153 A technical error occurred during the call to the Banque Accord service.

155 The Facily Pay transaction could not be canceled/edited/refunded: the transaction status does not allow toperform the requested action. Reminder regarding a Facily Pay transaction: a refund must be made within twodays after the capture, the delay between two refunds is one day, a partial refund is limited to 20 days, a fullrefund is limited to 6 months.

156 Operation not supported.


159 The amount is less than the minimum authorized amount (minimum={0} {1}).

160 It is impossible to refund an unpaid transaction.

164 Invalid payment option.



Code Message

165 The ID type is specified, but its number is missing.

166 The ID number is specified, but its type is missing.

167 The ID type is unknown.

168 The ID number is invalid.

169 The specific data that must be transmitted to the acquirer is invalid.

170 The deferred payment is not allowed.

171 The deferred payment is not allowed.

172 The selected payment process is invalid.

173 Error of Express Checkout service at PayPal.

174 Card issuer unavailable.

175 Cancellation impossible, please try a refund.

176 Refund impossible, please try a cancellation.

177 No response to the authorization request has been received within the required deadline.

178 Cancellation impossible, the transaction has already been canceled.

179 The transaction status is unknown.

182 The national client identifier is missing.

183 The format of the national client identifier is incorrect.


vads_payment_option_code

Description Code of the chosen option.


Format an..5

Error code 103




vads_payment_seq

Description Details of performed transactions.


Format json

The vads_payment_seq field (json format) describes the split payment sequence.It contains:

• "trans_id": transaction identifier used for the entire payment sequence.

• "transaction": table of sequence transactions. It contains:


amount Amount of the payment sequence.

operation_type Debit transaction.

auth_number Authorization number. Example: 949478

auth_result Return code of the authorization request.

capture_delay Delay before the capture (in days).

• For a payment by card, this parameter is the requested capture date(ISO 8601 format). If not sent in the payment form, the value defined inthe Merchant Back Office will be used.

card_brand Used payment method.For a payment by card (e.g. CB or Visa or MasterCard co-branded CB cards),this parameter is set to "CB".See the Payment Gateway Implementation Guide available in our onlinedocumentation archive to see the complete list of card types.

card_number Payment method number

expiry_month Expiry month of the payment method

expiry_year Expiry year of the payment method

payment_certificate Payment certificate.

contract_used Contract used for the payment

identifier Unique identifier (token) associated with a payment method.

identifier_status Only present if the requested action is a token creation or update.Possible values:

Value Description

CREATED The authorization request has been accepted.Token (or UMR for SEPA payment) has beensuccessfully created.

NOT_CREATED The authorization request has been declined.The token (or UMR for SEPA payment) has not beencreated, and therefore cannot be viewed in theMerchant Back Office.

UPDATED Token (or UMR for SEPA payment) has beensuccessfully updated.

NOT_UPDATED The token (or UMR for SEPA payment) has not beenupdated.

ABANDONED The action has been abandoned by the buyer (debtor).The token (or UMR for SEPA payment) has not beencreated, and therefore cannot be viewed in theMerchant Back Office.

presentation_date For card payments, this parameter is the requested capture date (ISO 8601format).

trans_id Transaction number.

ext_trans_id This field is not sent for credit card payments.

trans_uuid Unique reference generated by the payment gateway after the creation of apayment transaction.



Field name DescriptionGuarantees that each transaction is unique.

extra_result Numeric code of the risk controls result.

Code Description

Empty No verification completed.

00 All the verification processes have been successfully completed.

02 Credit card velocity exceeded.

03 The card is on the merchant's greylist.

04 The country of origin of the card is on the merchant's greylist.

05 The IP address is on the merchant's greylist.

06 The BIN code is on the merchant's greylist..

07 Detection of an e-carte bleue.

08 Detection of a national commercial card.

09 Detection of a foreign commercial card.

14 Detection of a card that requires systematic authorization.

20 Consistency check: countries do not match (country IP address,card country, buyer's country).

30 The country of the this IP address belongs to the greylist.

99 Technical issue encountered by the server during a localverification process.

sequence_number Sequence number.

trans_status Transaction status.

Table 2: JSON object content

Note: canceled transactions also appear in the table (information provided in theJSON trans_status parameter).


vads_payment_src

Description Allows to define the entry mode of payment method details.


Format enum

Error code 60


EC E-commerce: Data entry on the payment page by the cardholder.

MOTO MAIL OR TELEPHONE ORDER: Entry made by an operator following a MOTO order.

CC Call center: Entry made by a call center operator.

OTHER Other: Entry made via a different source, e.g. Merchant Back Office.

Only the EC value allows to create a transaction with 3D Secure.

The other values must only be used for distance sales, where 3D Secure is notapplicable.


vads_pays_ip

Description Buyer's country code and the IP address in the ISO 3166 format.




Format a2


vads_presentation_date

Description • Date and time in UTC format of requested capture in the bank, inYYYYMMDDhhmmss format.

or

• Date and time in UTC format of an installment requested as part of the SEPAdirect debit.


Format n14


vads_pretax_amount

Description Allows to define the pre-tax amount of the whole order.

The value must be specified in the smallest currency unit (cents for euro).


Format n..12


vads_product_amountN

Description Allows to define the amount of each item in the cart.

N corresponds to the reference of the article (0 for the first item, 1 for the seconditem, etc.).

The amount is expressed in the smallest currency unit (cents for euro).

Input field.

Format n..12

Error code 102


vads_product_ext_idN

Description Corresponds to the product barcode on the merchant's website.


Field transmitted to the Konduto fraud analyzer.

Input field.



Format an..100

Error code 120

Category Order details



vads_product_labelN

Description Allows to define the label of each item in the cart.


Note:


Input field.

Format ans..255

Error code 97


vads_product_qtyN

Description Allows to define the quantity of each item in the cart.

N is an integer that corresponds to the index of the item (0 for the first item, 1 forthe second item, etc.).

Input field.

Format n..12

Error code 101


vads_product_refN

Description Allows to define the reference of each item in the cart.


Input field.

Format an..64

Error code 100




vads_product_typeN

Description Allows to define the type of each item in the cart.


Input field.

Format enum

Error code 98


FOOD_AND_GROCERY Food and grocery

AUTOMOTIVE Cars / Moto

ENTERTAINMENT Entertainment / Culture

HOME_AND_GARDEN Home and gardening

HOME_APPLIANCE Household appliances

AUCTION_AND_GROUP_BUYING Auctions and group purchasing

FLOWERS_AND_GIFTS| Flowers and presents

COMPUTER_AND_SOFTWARE Computers and software

HEALTH_AND_BEAUTY Health and beauty

SERVICE_FOR_INDIVIDUAL Services for individuals

SERVICE_FOR_BUSINESS Services for companies

SPORTS Sports

CLOTHING_AND_ACCESSORIES Clothes and accessories

TRAVEL Travel

HOME_AUDIO_PHOTO_VIDEO Sound, image and video

TELEPHONY Telephony

Table 3: Values associated with vads_product_type0


vads_product_vatN

Description Allows to define the tax for each item in the cart.


Input field.

Format n..12

Error code 203

Possible values • An integer without a decimal separator

To display an amount in cents applied to the product in question.

Example in euros: 14520 (for an amount of 145 euros and 20 cents).

• An integer less than 100 with a decimal separator

To display a percentage applied to the payment amount for the product inquestion with maximum 4 digits after the decimal point.

Examples: 20.0 or 19.6532



Notes:

• The decimal separator is mandatory for displaying a percentage.

• The decimal separator is represented by the "." symbol.


vads_proof_of_id_number

Description Field reserved to the entry of the buyer's ID number on the payment page.

The format depends on the ID type and is between 7 and 13 characters, digits,letters and/or full stops.

In Latin America, this parameter is required for DECIDIR.

Input field.

Format an..13

Error code 129


vads_proof_of_id_type

Description This field corresponds to the ID type selected by the buyer during the entry of thepayment card details.

In Latin America, this parameter is required for DECIDIR.

Input field.

Format enum

Error code 128


vads_recurrence_number

Description Recurrence number of the subscription


Format n..2

Category Subscription details

vads_recurrence_status

Description Subscription status.

Appears only if the requested action concerns creating or updatinga subscription (REGISTER_SUBSCRIBE, SUBSCRIBE, REGISTER_PAY_SUBSCRIBE,REGISTER_UPDATE_PAY).


Format string




CREATED The subscription has been successfully createdThe subscription details are visible in the Merchant Back Office.

NOT_CREATED The recurring payment has not been created and cannot be viewed inthe Merchant Back Office.

ABANDONED The request for creating a subscription has been abandoned by thebuyer (debtor).The recurring payment has not been created and cannot be viewed inthe Merchant Back Office.

Category Subscription details.



vads_redirect_error_message

Description Allows to define the message that will appear before automatic redirection to themerchant website if the payment has been declined.

Input field.

Format ans..255

Error code 37

Category Redirection to the merchant website.

vads_redirect_error_timeout

Description Allows to define a delay in seconds before an automatic redirection to themerchant website at the end of a declined payment.

The value of the field is between 0 and 600s.

After this delay, the buyer will be redirected to the URL populated in thevads_url_refused field. If the parameter is not filled in, the buyer will be redirectedto the return URL entered in the vads_url_return field or to the return URL enteredin the Merchant Back Office. If the return URL is not set, the buyer will be redirectedto the merchant website.

Input field.

Format n..3

Error code 36




vads_redirect_success_message

Description Allows to specify the message that will appear upon automatic redirection to themerchant website.

Input field.

Format ans..255

Error code 35


vads_redirect_success_timeout

Description Allows to define a delay in seconds before an automatic redirection to themerchant website at the end of an accepted payment.

Its value is between 0 and 600s.

After this delay, the buyer will be redirected to the URL populated in thevads_url_success field. If the parameter is not filled in, the buyer will be redirectedto the return URL entered in the vads_url_return field or to the return URL enteredin the Merchant Back Office. If the return URL is not set, the buyer will be redirectedto the merchant website.

Input field.

Format n..3

Error code 34


vads_requestor

Description Allows to modify the value of the "Aceite" field for a Boleto Bancario.

The Aceite field can have two values:

• N (= No)

Default value

The boleto has been generated without an official authorization of the buyer bymeans of a signed document.

• S (= Yes)

The buyer's authorization is mandatory as the signed document will serve asevidence of debt.


Format enum

Possible values • BANK

Means that the S (= Yes) value will be applied in the Aceite field

• MERCHANT

Means that the N (= No) value will be applied in the Aceite field



vads_result

Description Return code of the requested action.


Format n2


00 Action successfully completed.

02 The merchant must contact the cardholder’s bank Deprecated.

05 Action rejected.

17 Action canceled by the buyer.

30 Request format error. To associate with the value of the vads_extra_result field.

96 Technical error.


vads_return_mode

Description Allows to specify the data transmission method used while returning to themerchant website.

Input field.

Format enum

Error code 48

Possible valuesField name Value Description

absent, emptyor NONE

No parameters will be transmitted to the ReturnURL.

GET The return fields will be transmitted to the returnURL in an HTTP GET form (in the "query string").

vads_return_mode POST The return fields will be transmitted to the returnURL in an HTTP POST form.If the return to the shop in done from anenvironment other than https, a security pop-upmessage will be displayed to the buyer.




vads_risk_analysis_result

Description Returns the result of the risk management process performed by an external system(Konduto, ClearSale, CyberSource, NOTO, etc.).


Format ans

Possible values

Values common to all risk analyzers

INVALID_CREDENCIAL Configuration problem of the risk management contract.

COMUNICATION_PROBLEM Impossible to connect to the risk analyzer.

DATA_PROCESSING_PROBLEM Problem occurred when processing the data being transmitted or theresponse of the risk management system.

MISSING_MANDATORY_ORDER_INFO Order details are missing.

MISSING_MANDATORY_SHIPPING_INFO Shipping details are missing.

MISSING_MANDATORY_SHIPPING_ADDRESS_INFO Shipping address details are missing.

MISSING_MANDATORY_BILLING_INFO Billing details are missing.

MISSING_MANDATORY_BILLING_ADDRESS_INFO Billing address details are missing.

MISSING_MANDATORY_CARD_INFO Payment method details are missing.

MISSING_MANDATORY_CUSTOMER_INFO Buyer details are missing.

Values returned by ClearSale

APA The transaction is automatically approved according to the defined parameters.

APM The transaction is manually approved by an analyst.

RPM The order is reproved due to missing information related to the buyer in conformity with the policy inforce.

AMA Waiting for manual analysis. The order is waiting to be analyzed.

ERR Error

NVO New order. Waiting to be processed and classified.

SUS Order manually suspended. The order is suspended for suspected fraud.

CAN Order is canceled. The order has been canceled by the buyer.

FRD Fraud confirmed by the credit card operator or the cardholder.

RPA Order automatically declined. The order has been automatically declined in accordance with theparameters of the external risk analyzer.

RPP Order automatically declined. The order is reproved based on the customer or ClearSale policy

Values returned by Cybersource

100 Transaction successfully completed.

101 Transaction is declined. One or more parameters are missing

102 Transaction is declined. One or more parameters have invalid data

150 Error.

151 Error. The request was received but the time limit has been exceeded. This error does not includetimeouts between the client and the server.

152 Error. The request was received but a service was not completed in time.

202 Declined. Card expired.

231 Declined. Invalid account number.

234 Declined. A problem occurred with the merchant CyberSource configuration.

400 Declined. The score of the fraud exceeds the tolerance.

480 The order is marked and needs to be reviewed by the Decision Manager.

481 The order has been rejected by the Decision Manager.

Values returned by Konduto/NOTO

APPROVE Konduto recommends to accept the transaction.If no rule refute this recommendation, the transaction status will be AUTHORISED.



Values returned by Konduto/NOTO

DECLINE Konduto recommends to decline the transaction.The transaction status will be REFUSED.

REVIEW Konduto recommends to check the transaction.Depending on the result of the 3D-Secure authentication, the transaction statuswill be:

• AUTHORISED_TO_VALIDATE if the cardholder has successfully authenticated.

• REFUSED in case of authentication failure of the cardholder.

THREE_DS NOTO has recommended strong authentication.

NONE No specific recommendations from NOTO.




vads_risk_assessment_result

Description Returns the list of actions performed on the transaction, following the activation ofthe advanced risk assessment activated in the Merchant Back Office.

When triggering multiple rules, the vads_risk_assessment_results field will consist ofmultiple keywords separated by a ";".

Example:

vads_risk_assessment_results="ENABLE_3DS;MANUAL_VALIDATION"


Format ans

Possible values

Values Description

ENABLE_3DS 3D Secure enabled.

DISABLE_3DS 3D Secure disabled.

MANUAL_VALIDATION The transaction has been created via manual validation.The payment capture is temporarily blocked to allow the merchant perform all thedesired verifications.

REFUSE Transaction is declined.

RUN_RISK_ANALYSIS Call for an external risk analyzer if the merchant has a contract.Refer to the description of the vads_risk_analysis_result field to identify the list ofpossible values and their description.

INFORM A warning message appears.The merchant is notified that a potential problem has been identified.The merchant is informed via one or several notification center rules (IPN, e-mail orSMS).




vads_risk_control

Description Allows to define the result of the risk management process.


Format control1=result1;control2=result2


CARD_FRAUD Verifies whether the cardholder's card number is on thecard greylist.

SUSPECT_COUNTRY Verifies whether the cardholder's card number is on thelist of forbidden countries.

IP_FRAUD Verifies whether the cardholder's IP address is on the IPgreylist.

CREDIT_LIMIT Verifies the purchase frequency and amounts for the samecard number, or the maximum amount of an order.

BIN_FRAUD Verifies whether the BIN code of the card is on the greylistfor BIN codes.

ECB Verifies whether the buyer's card is an "e-carte bleue".

COMMERCIAL_CARD Verifies whether the buyer's card is a corporate creditcard.

SYSTEMATIC_AUTO Verifies whether the buyer's card is a MAESTRO or VISAELECTRON credit card.

INCONSISTENT_COUNTRIES Verifies whether the country of the IP address, the countryof the payment card and the country of residence of thebuyer match.

NON_WARRANTY_PAYMENT Verifies the liability shift of the transaction.

SUSPECT_IP_COUNTRY Verifies whether the cardholder's country, identified byhis/her IP address, is on the list of forbidden countries.

The possible values for result are:

Value Description

OK OK

WARNING Informational control failed

ERROR Blocking control failed


vads_sequence_number

Description Transaction sequence number.

Case of single payment (vads_payment_config=SINGLE)

vads_sequence_number is populated with 1 in case of single payment.

However, if the merchant has authorized several payment attempts after arejected payment, the sequence number will be incremented upon each newattempt.

The number of additional attempts after a rejected payment can be configured viathe Merchant Back Office (menu Settings > Shop > Configuration).

If vads_payment_config = SINGLE:

vads_url_check_srcvads_sequence_numberDescription

PAY 1 Payment made in 1 attempt



vads_url_check_srcvads_sequence_numberDescription

2 Payment made in 2 attempts

3 Payment made in 3 attempts

1 Deferred Payment made in 1 attempt

2 Deferred Payment made in 2 attemptsBATCH_AUTO

3 Deferred Payment made in 3 attempts

Case of installment payment (vads_payment_config=MULTI)

For an installment payment, this field will take the "1" value for the first installment,"2" for the second installment, "3" for the third installment, etc.

Installment payments is not compatible with the functionality of additionalattempts in case of rejected payment.

Note:

vads_sequence_number field is not returned in the response when a payment iscanceled or abandoned.



vads_ship_to_city

Description Allows to specify the city for shipping.


Format an..128

Error code 83




vads_ship_to_country

Description Allows you to specify the buyer's country code in the ISO 3166 standard.


Format a2

Error code 86


Code Country Code Country

AT Austria IN India

BR Brazil MQ Martinique

CI Ivory Coast NC New Caledonia

FR Corsica PF French Polynesia

FR France PM St. Pierre and Miquelon

GP Guadeloupe US United States of America


vads_ship_to_delay

Description Allows to define the speed depending on the shipping method whenvads_ship_to_speed is set to PRIORITY.

Input field.

Format enum

Error code 127

Possible values • INFERIOR_EQUALS for a shipping delay inferior or equal to 1 hour.

• SUPERIOR for a shipping delay exceeding 1 hour.

• IMMEDIATE for an immediate shipping.

• ALWAYS for a 24/7 shipping delay.


vads_ship_to_delivery_company_name

Description Allows to define the name of the transporter.

Input field.

Format ans..127

Error code 96


vads_ship_to_district

Description Allows to define the shipping district.


Format ans..127



Error code 115


vads_ship_to_first_name

Description Allows to specify the buyer's first name

Input field.

Format ans..63

Error code 106


vads_ship_to_last_name

Description Allows to specify the buyer's last name

Input field.

Format ans..63

Error code 107


vads_ship_to_legal_name

Description Company name of the shipping location.


Format an..100

Error code 125


vads_ship_to_name

Description Allows to specify the buyer's last name

Deprecated. Please use vads_ship_to_first_name and vads_ship_to_last_namefields.


Format ans..63

Error code 80


vads_ship_to_phone_num

Description Allows to specify the buyer's phone number used for the shipping.




Format ans..32

Error code 87




vads_ship_to_speed

Description Allows to specify the shipping mode.

Input field.

Format enum

Error code 95

Possible values • STANDARD (reserved to FacilyPay)

• EXPRESS (reserved to FacilyPay)

• PRIORITY (reserved to FacilyPay)

• ELECTRONIC_DELIVERY

• SAME_DAY_SHIPPING

• OVERNIGHT_SHIPPING

• TWO_DAYS_OR_MORE_SHIPPING

Note:

The use of PRIORITY as a value implies that the vads_ship_to_delay field will beused.


vads_ship_to_status

Description Allows to specify the type of the shipping address.


Format enum

Error code 93

Possible values PRIVATE, COMPANY


vads_ship_to_state

Description Allows to specify the buyer's state for shipping.


Format ans..127

Error code 84




vads_ship_to_street

Description Allows to specify the buyer’s address.


Format ans..255


Error code 81


vads_ship_to_street2

Description Allows to specify the second line of the buyer’s address.


Format ans..255


Error code 82


vads_ship_to_street_number

Description Allows to specify the shipping street number.


Format ans..64

Error code 114


vads_ship_to_type

Description Allows to specify the shipping type.

Input field.

Format enum

Error code 94

Possible values • RECLAIM_IN_SHOP for picking up the item at the shop.

• RELAY_POINT for using a third-party pick-up network (Kiala, Alveol, etc.).

• RECLAIM_IN_STATION for picking up the item at an airport, a guard or a travelagency.

• PACKAGE_DELIVERY_COMPANY for shipping by the transporter (Colissimo,UPS, etc.).

• ETICKET for sending an electronic ticket, download.

• CARD_HOLDER_ADDRESS (3DS2)



• VERIFIED_ADDRESS (3DS2)

• NOT_VERIFIED_ADDRESS (3DS2)

• SHIP_TO_STORE (3DS2)

• DIGITAL_GOOD (3DS2)

• ETRAVEL_OR_ETICKET (3DS2)

• OTHER (3DS2)

• PICKUP_POINT (3DS2)

• AUTOMATED_PICKUP_POINT (3DS2)




vads_ship_to_user_info

Description Information about the user who made the payment.

This parameter will be returned with the response and will include the valuetransmitted in the request.

Note:

For backward compatibility, it is possible to use this field to set the CPF/CNPJ (legalidentifier in a numeric format between 11 and 20 digits long) required by theClearSale risk management module. However, vads_cust_national_id field can beused.


Format ans..255

Error code 116


vads_ship_to_zip

Description Allows to specify the buyer's postal code.


Format an..64

Error code 85


vads_shipping_amount

Description Allows to transmit the shipping fees for the whole order

Input field.

Format n..12

Error code 109


vads_shop_name

Description Allows to define the shop name as it appears in the summary at the end ofpayment, the receipt and the payment confirmation e-mails.


Format ans..127

Error code 72




vads_shop_url

Description URL that appears on the payment page and in payment confirmation e-mails.

This setting overrides the default value of your shop.


Format ans..1024

Error code 73


vads_site_id


Value generated during the subscription to the payment gateway.

Its value can be seen in the interface of the Merchant Back Office via Settings >Shop > Keys by all authorized individuals.

If the value is incorrect, the buyer will get an error message in their browser whenmaking the payment.

The payment is then not possible and the transaction is permanently interrupted.

A warning e-mail is then sent to the shop administrator. It contains the form thatthe gateway was unable to process with the value of the signature.


Format n8

Error code 02


vads_subscription

Description Optional parameter used for creating a recurring payment. It designates the ID ofthe recurring payment ID to create.

There are two choices:

• The payment gateway manages the IDs.


In case the subscription is successfully created, the response will contain thevalue generated by the payment gateway.

• The merchant website manages the IDs.

In this case, this parameter must be populated with the desired value of thesubscription ID.

There is no uniqueness check on the subscription ID.

When creating a subscription, the merchant site can fill vads_subscription withan already existing value.



It is possible to create multiple subscriptions, associated with the same token,with the same subscription ID.


Format Two possible formats:

• an32: when the identifier is generated by the gateway

• ans..50: when the identifier is generated by the merchant

Error code 63




vads_sub_amount

Description Mandatory parameter used for creating a recurring payment.

It refers to the amount of each installment except the ones that will be defined byvads_sub_init_amount_number.

The value cannot be negative, empty, or equal to 0.

The value must be expressed in the smallest currency unit (cent for euro).

Example: for a transaction of 10 EUR and 28 cents, the value of the parameter is1028.

Input field.

Format n..12

Error code 65


vads_sub_currency


It indicates the currency to use for the recurring payment, in compliance with theISO 4217 standard.


Format n3


The possible currencies are:


Australian Dollar (AUD) 036 2

Cambodian Riel (KHR) 116 0

Canadian Dollar (CAD) 124 2

Chinese Yuan (Renminbi) (CNY) 156 1

Czech Crown (CZK) 203 2

Danish Crown (DKK) 208 2

Hong Kong Dollar (HKD) 344 2

Hungarian Forint (HUF) 348 2

Indian Rupee (INR) 356 2

Indonesian Rupiah (IDR) 360 2

Japanese Yen (JPY) 392 0

South Korean Won (KRW) 410 0

Kuwaiti Dinar (KWD) 414 3

Malaysian Ringgit (MYR) 458 2

Mexican Peso (MXN) 484 2

Moroccan Dirham (MAD) 504 2

New Zealand Dollar (NZD) 554 2

Norwegian Crown (NOK) 578 2

Philippine Peso (PHP) 608 2

Russian Ruble (RUB) 643 2

Singapore Dollar (SGD) 702 2

South-African Rand (ZAR) 710 2

Swedish Crown (SEK) 752 2




Swiss Franc (CHF) 756 2

Thai Baht (THB) 764 2

Tunisian Dinar (TND) 788 3

Pound Sterling (GBP) 826 2

US Dollar (USD) 840 2

Taiwan New Dollar (TWD) 901 2

New Turkish Lira (TRY) 949 2

Euro (EUR) 978 2

Polish Zloty (PLN) 985 2

Brazilian Real (BRL) 986 2

Error code 67


vads_sub_desc


It designates the recurring payment rule to be applied.

The expected value for this parameter is a chain of characters that comply withthe iCalendar (Internet Calendar) specification, described in RFC5545 (see http://tools.ietf.org/html/rfc5545).

Among other aspects, this specification allows to define complex recurringpayment rules via the RRULE property.

For technical reasons, it is not possible to define recurring payment periods thatare shorter than one day.

The keywords "SECONDLY" / "MINUTELY" / "HOURLY" are not taken into account.

Examples:

• To program installment payments taking place on the last day of each monthfor 12 months, the rule is:


This rule means that if the current month does not have 31 days, the machinewill take the 30th into account. If there is no 30th day in a month, the machinewill take the 29th into account, and so on until the 28th.

Another version of this rule:RRULE:FREQ=MONTHLY;COUNT=5;BYMONTHDAY=-1

• To program installment payments on the 10th of each month for 12 months,the rule is: RRULE:FREQ=MONTHLY;COUNT=12;BYMONTHDAY=10

• To program installment payments every three months up to December 31st,2016.RRULE:FREQ=YEARLY;BYMONTHDAY=-1;BYMONTH=1,4,7,10;UNTIL=20161231

The installment payments will be due on the first day of January, April, July andOctober each year. The total number of installments depends on the recurringpayment start date (see vads_sub_effect_date parameter).





• In order to define a weekly recurring payment to be made every Monday:RRULE:FREQ=WEEKLY;BYDAY=MO

The installments will be made every Monday. Note that the first installment willoccur the nearest Monday.

• In order to define a weekly recurring payment: RRULE:FREQ=WEEKLY

The installments will occur on the same day if the due date is set to “today”,then every 7 days.

• In order to define a recurring payment every twoweeks on Monday, with maximum 4 installments:RRULE:FREQ=WEEKLY;INTERVAL=2;COUNT=4;BYDAY=MO

• In order to define a recurring payment every two weeks, on the same day andevery 7 days: RRULE:FREQ=WEEKLY;INTERVAL=2;

• For more information and examples, visit http://recurrance.sourceforge.net/.


Format string

Error code 64


http://recurrance.sourceforge.net/



vads_sub_effect_date

Description Mandatory parameter used for creating a recurring payment that allows to definethe recurring payment start date.

This parameter does not always match with the date of the first installment thatdepends only on the vads_sub_desc parameter.

The effective date indicates when the recurring payment starts. The format of thisdate is YYYYMMDD.

Example: for 1 February 2015, enter 20150201.


Format n8

Error code 69


vads_sub_init_amount

Description Optional parameter used for creating a subscription. Represents the amount of thefirst installments of the recurring payment.

The number of these first installments is defined by thevads_sub_init_amount_number parameter.

This amount is presented in the currency defined by the vads_sub_currencyparameter and is expressed in its smallest unit (cent for euro).

E.g.: for an amount of 10 euros and 28 cents, the value of the parameter is 1028.

The value may be empty but cannot be negative or equal to 0.


Format n..12

Error code 66

Category Subscription details

vads_sub_init_amount_number

Description Optional parameter used for creating a recurring payment. Number of installmentsfor which the vads_sub_init_amount should be applied.

Once these installments will have expired, the vads_sub_amount field will be used.

Example: to define a recurring payment with the first 3 installments of 25,00 EUR,and the rest of the installments of 30,00 EUR, the following values will be used:

• vads_sub_currency = 978

• vads_sub_init_amount_number = 3

• vads_sub_init_amount = 2500

• vads_sub_amount = 3000


Format n..3



Code erreur 68


vads_tax_amount

Description Parameter that allows to define the amount of taxes for the entire order.



Format n..12

Error code 108


vads_tax_rate

Description Allows to define the tax rate (VAT) applied to the order.

The value must be expressed in XX.X format, with a dot as the separator andwithout the % suffix.


Format XX.X

Error code 153


vads_theme_config

Description Allows to personalize certain elements on the payment page, such as the customtemplate to be used, the button labels and some messages.

This parameter provides a list of keywords (codes), each associated with a value,that correspond to elements on payment pages.

Example:

vads_theme_config="SUBMIT_BUTTON_LABEL=PAY;TICKET_LABEL=PAYMENT RECEIPT"

See Advanced customization - Back Office user manual for more details on paymentpage personalization.

Input field.

Format map

Error code 32

Possible values

Code Description

Features

RESPONSIVE_MODEL Allows to override the custom template to be applied to the paymentpages.



Code DescriptionExample of use:

vads_theme_config="RESPONSIVE_MODEL=Model_1"

The use of custom templates requires the activation of the "Advancedcustomization" option.

RESPONSIVE_MAIL_MODEL Allows to override the custom template to be used for e-mails.Example of use:

vads_theme_config="RESPONSIVE_MAIL_MODEL=Model_1"

The use of custom templates requires the activation of the "Advancedcustomization" option.

HIGH_CONTRAST_MODE Allows to enable the high contrast mode to enhance color contrast anddisplay the payment page in black and white.Possible values: "true" or "false".Example of use:

vads_theme_config="HIGH_CONTRAST_MODE=true"

SIMPLIFIED_DISPLAY Allows to reduce the volume of data to be loaded during the display ofthe payment page.Deletes the language and logo selector from the footer.Recommended for iframe and In-app integrations.Possible values: "true" or "false".Example of use:

vads_theme_config="SIMPLIFIED_DISPLAY=true"

FORM_TARGET Allows to define or display the return page at the end of payment.Possible values:

• _blank: in a new window or a new tab

• _self: in the current frame

• _parent: in the parent frame

• _top: on the whole page

• framename: in a specified frame.

Example of use:

vads_theme_config="FORM_TARGET=_top"

3DS_LOGOS Allows to mask the "Verified By Visa" and "Mastercard Secure Code"logos on the card detail entry page.Possible values: "true" or "false".Example of use:

vads_theme_config="3DS_LOGOS=false"

Button labels

SUBMIT_BUTTON_LABEL Allows to edit the label of the "VALIDATE" button.Example of use:

vads_theme_config="SUBMIT_BUTTON_LABEL=PAY"

CANCEL_FOOTER_MSG_RETURN The label of the "Cancel and return to the shop" button on the page ofpayment method selection, the card detail entry page, and the resultpage in case of payment failure.Example of use:

vads_theme_config="CANCEL_FOOTER_MSG_RETURN=CANCEL"

SUCCESS_FOOTER_MSG_RETURN The label of the "Return to the shop" button on the result page in case ofsuccessful payment.



Code DescriptionExample of use:

vads_theme_config="SUCCESS_FOOTER_MSG_RETURN=RETURN"

TICKET_LABEL The label of the "RECEIPT" button on the result page in case of successfulpayment.Example of use:

vads_theme_config="TICKET_LABEL=PAYMENT RECEIPT"

Messages

MERCHANT_ MESSAGE Allows to display a message above the transaction summary.Requires for the Display a custom message checkbox to be checked viaSettings > Customization > Payment pages tab > Logo group.Example of use:

vads_theme_config="MERCHANT_MESSAGE=Transaction summary"

SECURE_ MESSAGE Default value: The address of this payment website prefixed with httpsindicates that you are on a secure page and can safely proceed to yourpayment.Example of use:

vads_theme_config="SECURE_ MESSAGE=You are on a website secured by TLS1.2. You can safely proceed to payment."

SECURE_MESSAGE_REGISTER Default value: The address of this payment website prefixed with httpsindicates that you are on a secure page and can safely enter your bankdetails.

REGISTER_ON_PAYMENT Allows to customize the text of the checkbox that appears duringASK_REGISTER_PAY.Default value: I would like to register my payment method details for afuture purchase

Labels that appear on the receipt and the payment pages

SITE_ID_LABEL Default value: Merchant ID

ORDER_ID_LABEL Default value: Order reference

TRANSACTION_ID_LABEL Default value: Transaction number

TRANSACTION_AMOUNT_LABEL Default value: Amount

MULTI_DATE_LABEL Default value: Sale dateInformation displayed only during an installment payment.

CUST_ID_LABEL Default value: Buyer referenceInformation displayed only during a payment by token.

CUST_ADRESS_NUMBER_LABEL Default value: Street numberInformation displayed only during a payment by token.

CUST_ADRESS_LABEL Default value: AddressInformation displayed only during a payment by token.

CUST_ADRESS2_LABEL Default value: Second line of the addressInformation displayed only during a payment by token.

CUST_DISTRICT_LABEL Default value: DistrictInformation displayed only during a payment by token.

CUST_CITY_LABEL Default value: CityInformation displayed only during a payment by token.

CUST_COUNTRY_LABEL Default value: CountryInformation displayed only during a payment by token.

CUST_PHONE_LABEL Default value: PhoneInformation displayed only during a payment by token.

CUST_NAME_LABEL Default value: Buyer’s last nameInformation displayed only during a payment by token.

RECURRENCE_AMOUNT_LABEL Default value: Amount per installment



Code DescriptionInformation displayed only during a payment by token.

RECURRENCE_INIT_AMOUNT_NUMBER_LABEL

Default value: Number of installments of initial amountInformation displayed only during a payment by token.

RECURRENCE_INIT_AMOUNT_LABEL Default value: Initial amount of the recurring paymentInformation displayed only during a payment by token.

SHOP_LABEL Default value: SHOPInformation displayed only on the PDF receipt.

SITE_URL_LABEL Default value: URL addressInformation displayed only on the PDF receipt.

CUST_LANGUAGE Default value: LanguageInformation displayed only on the PDF receipt.

Category Payment page customization.

vads_threeds_auth_type

Description Indicates the authentication type of the cardholder.


Format enum

Possible values • "Empty" if the buyer is not correctly authenticated,

• FRICTIONLESS: buyer authentication without interaction with the ACS. Valuereturned only in 3DS v2.

• CHALLENGE: interactive authentication of the cardholder (OTP entry orresponse to a series of questions). Value returned in 3DS v1 and 3DS v2.

Category 3DS Authentication.

vads_threeds_cavv

Description Indicates cardholder authentication via the ACS. Its value is populated by 3DSauthentication server (ACS) when the buyer has been correctly authenticated(vads_threeds_status equals "Y" or "A").


Format ans..28


vads_threeds_cavvAlgorithm

Description Algorithm used by the ACS to generate the CAVV value.

Its value is populated by 3DS authentication server (ACS) when the buyer has beencorrectly authenticated (vads_threeds_status equals "Y" or "A").


Format n1

Possible valuesValue Description

0 HMAC

1 CVV



Value Description

2 CVV_ATN

3 MasterCard SPA


vads_threeds_eci

Description Indicates the E-Commerce index.

It is populated by the 3DS authentication server (ACS) when the buyer has correctlyauthenticated him/herself (vads_threeds_status equals "Y" or "A").

status =Y status = A status = U status =N

VISA andAMEX

5 6 7 -

MasterCard 02 01 - -


Format n..2


vads_threeds_enrolled

Description Indicates the enrollment status of the cardholder. Its value is populated by the VISAand MASTERCARD (DS) servers during 3D Secure authentication.


Format a1


Y Cardholder enrolled, 3DS authentication possible.Note: In the Merchant Back Office, the ENROLLED value is displayed (3D Secure tabin Transaction details).

N Cardholder not enrolled.Note: In the Merchant Back Office, the NOT_ENROLLED value is displayed (3DSecure tab in Transaction details).

U Unable to verify the cardholder's enrollment status.Note: In the Merchant Back Office, the UNAVAILABLE value is displayed (3D Securetab in Transaction details).


vads_threeds_error_code

Description Final status of 3D Secure authentication.

This field is deprecated. It is replaced by the vads_threeds_exit_status field.


Format n..2




vads_threeds_exit_status

Description Final status of 3D Secure authentication.

It is populated by the payment gateway.


Format n..2


0 Initial status

1 Status non-applicable (global, reason not detailed)

2 Status non-applicable (integrator disabled)

3 Not an e-commerce payment

4 Payment without 3DS

5 Merchant not enrolled, 3DS unavailable

6 A technical error has occurred during 3DS authentication, 3DS unavailable

7 Cardholder not enrolled, 3DS unavailable

8 Invalid signature

9 Problem caused by the ACS

10 The 3DS authentication has been successfully completed

11 The 3DS authentication has been completed via the integrator

12 Problem caused by DS

13 Timeout when connecting to DS

15 3DS disabled

16 Payment channel not available

98 Initialization of 3DS authentication OK

99 Unknown status

* These statuses concern 3DS payments without card detail entry (payment bytoken).




vads_threeds_mpi

Description • 3DS1: Enables/disables the 3DS1 process during an e-commerce payment.

IMPORTANTThis functionality will no longer be available after the implementation of 3DS2.

• 3DS2: Indicates the merchant’s desire to challenge the buyer with a strongauthentication during a payment.

Input field.

Format n1

Error code 50


missingoremptyor 0

Management of 3DS authentication delegated to the payment gateway (domain,provider, shop configuration)

1 Deprecated

2 • 3DS1: 3DS authentication disabled for the transaction.Requires the “Selective 3D Secure” option.

• 3DS2: NO CHALLENGE REQUESTED Allows to request authentication withoutinteraction (frictionless).The merchant loses the payment guarantee if the request is accepted.

3 • 3DS1: 3DS1 authentication.

• 3DS2: CHALLENGE REQUESTED: 3DS Requestor Preference Allows to request strongauthentication for the transaction.


• 3DS2: CHALLENGE REQUESTED: mandate Allows to indicate that strongauthentication is required for the transaction, for regulatory reasons.


• 3DS2: NO PREFERENCE: Allows to indicate to DS that the merchant does not have apreference. If the issuer decides to perform an authentication without interaction(frictionless), the payment will be guaranteed.

Category 3DS authentication.

vads_threeds_sign_valid

Description Indicates the validity of the PARes message signature. Its value is populated by thepayment gateway.


Format n1


empty 3DS unavailable.

0 Incorrect signature.

1 Correct signature.




vads_threeds_status

Description Indicates the authentication status of the cardholder. It is populated by the 3DSauthentication server (ACS) during the 3D Secure authentication process.


Format a1


Y Successful authentication.Note: In the Merchant Back Office, the SUCCESS value is displayed (3D Secure tab inTransaction details).

N Authentication error.Note: In the Merchant Back Office, the FAILED value is displayed (3D Secure tab inTransaction details).

U Authentication impossible.Note: In the Merchant Back Office, the UNAVAILABLE value is displayed (3D Secure tab inTransaction details).

A Authentication attemptNote: In the Merchant Back Office, the ATTEMPT value is displayed (3D Secure tab inTransaction details).


vads_threeds_xid

Description Indicates the unique 3DS authentication reference.

It is populated by the authentication server (ACS) during the 3D Secureauthentication process.


Format ans..28


vads_token_id

Description Payment order ID associated with the transaction.

Corresponds to the offerId field of the paymentOfferResponse object >offerEntities (see“SOAP Web service - Payment order API ” Implementation guide).


Format ans..255


vads_totalamount_vat

Description Allows to define the total amount of taxes applied to the whole order.





Format n..12

Error code 154




vads_trans_date


Corresponds to the timestamp in the YYYYMMDDHHMMSS format

The timestamp must necessarily correspond to the current date and time, in theGMT + 0 (or UTC) time zone in 24h format.

Note:

If you are using REST payment web services, the equivalent of the vads_trans_dateparameter is transactions[0].transactionDetails.cardDetails.legacyTransDate.


Format n14

Error code 04

Common errors:

• The date has not been submitted in the YYYYMMDDHHMMSS format (year,month, day, hour, minute, second).

• The date is not based on the UTC time zone (Coordinated Universal Time).

Make sure you use date functions in your programming language that willgenerate a UTC hour (e.g.: gmdate in PHP).

• The time must be calculated using the 24h format, not 12h.

• The buyer has waited for too long before clicking on Pay.

• The buyer was using browser history.




vads_trans_id


It consists of 6 numeric characters and must be unique for each transaction for agiven shop on the same day.

Note: the uniqueness of the transaction identifier is based on the universal time(UTC).

The merchant website must guarantee this uniqueness during same the day. Itmust be between 000000 and 899999.

The range between 900000 and 999999 is reserved to the payment gateway, forthe transactions made via:

• the Merchant Back Office (refunds, duplications, manual payment, etc.),

• the data collection form,

• a payment order,

• the JavaScript client,

• the REST payment web services.


Format n6

Error code 03

Frequent errors:

The form is rejected:

• if the transmitted value contains less than 6 digits

• if the value is null

• if the field is absent

• if an identical transaction number has already been sent on the same day.

If the buyer clicks “Cancel and return to the shop”, the transaction numbermust be different for the next attempt as the previous one will be consideredas already used.

Otherwise, the “The transaction has been canceled” message will appear.




vads_trans_status

Description Allows to set the status of the transaction.


Format enum

Possible values

Value Description

ABANDONED Abandonedpayment abandoned by the buyer.The transaction has not been created, and therefore cannotbe viewed in the Merchant Back Office.

AUTHORISED Waiting for captureThe transaction has been accepted and will be automaticallycaptured at the bank on the expected date.

AUTHORISED_TO_VALIDATE To be validatedThe transaction, created with manual validation, isauthorized. The merchant must manually validate thetransaction in order for it to be captured.The transaction can be validated as long as the expirationdate of the authorization request has not passed. If theauthorization validity period has passed, the payment statuschanges to EXPIRED. The Expired status is final.

CANCELLED CanceledThe transaction has been canceled by the merchant.

CAPTURED CapturedThe transaction has been captured by the bank.

CAPTURE_FAILED Capture failedContact the technical support.

EXPIRED ExpiredThe expiry date of the authorization request has passed andthe merchant has not validated the transaction. The accountof the cardholder will, therefore, not be debited.

INITIAL PendingThis status concerns all the payment methods that requireintegration via a payment form with redirection.This status is returned when:

• no response has been returned by the acquireror

• the delay of the response from the acquirer hasexceeded the payment session on the payment gateway.This status is temporary. The final status will be displayedin the Merchant Back Office immediately after thesynchronization has been completed.

NOT_CREATED Transaction not createdThe transaction has not been created, and therefore cannotbe viewed in the Merchant Back Office.

REFUSED DeclinedTransaction is declined.

SUSPENDED SuspendedThe capture of the transaction is temporarily blocked bythe acquirer (AMEX GLOBAL or SECURE TRADING). Once thetransaction has been correctly captured, its status changes toCAPTURED.

UNDER_VERIFICATION For PayPal transactions, this value means that PayPalwithholds the transaction for suspected fraud.The payment will remain in the Transactions is progresstab until the verification process has been completed. The



Value Descriptiontransaction will then take one of the following statuses:AUTHORISED or CANCELED.A notification will be sent to the merchant to warn themabout the status change (Instant Payment Notification onbatch change).

WAITING_AUTHORISATION Waiting for authorizationThe capture delay in the bank exceeds the authorizationvalidity period.

WAITING_AUTHORISATION_TO_VALIDATE To be validated and authorizedThe capture delay in the bank exceeds the authorizationvalidity period.An authorization of 1 EUR (or information request about theCB network if the acquirer supports it) has been accepted.The merchant must manually validate the transaction for theauthorization request and the capture to occur.

Table 4: Values associated with the vads_trans_status field


vads_trans_uuid

Description Unique transaction reference generated by the payment gateway when creatinga payment transaction.

Guarantees that each transaction is unique.


Format ans32


vads_url_cancel

Description URL where the buyer will be redirected after having clicked on Cancel and returnto shop before proceeding to payment.

Input field.

Format ans..1024

Error code 27


vads_url_check

Description URL of the page to notify at the end of payment. Overrides the value entered inthe notification rules settings.

Note

This field should be used only in exceptional cases since:

• this URL will only be used when calling the IPN URL,

• the override value will not be used if an automatic retry takes place.



It is not compatible with the execution of the request sent to the IPN from theMerchant Back Office. The called URL is the URL that has been set up in thenotification rule (see chapter Setting up notifications).

Input field.

Format ans..1024

Error code 33




vads_url_check_src

Description This parameter defines the source of the notification (also called IPN).


Format enum


PAY Payment creation by form

BO Execution of the notification URL from the Merchant Back Office.

BATCH_AUTO Authorization request for a payment that was awaiting authorization.

BATCH Update of the transaction status after its synchronization on the acquirerside (case of notification on batch change).

REC Payment resulting from a recurring payment.

MERCH_BO Operation made via the Merchant Back Office.

RETRY Automatic retry of the IPN.


vads_url_error

Description URL where the buyer will be redirected in case of an internal processing error.

Input field.

Format ans..1024

Error code 29


vads_url_post_wallet

Description This field allows the merchant to transmit the URL to which the buyer will beredirected during a payment via a wallet in two steps.

This URL is used for transmitting information relative to the buyer's choice (e-mail,shipping address, payment method, etc.).

Based on these elements, the merchant can decide what to do (adjust the shippingfees, register the payment method, etc.) before allowing the buyer to finalize hisor her payment.

The details will be transmitted to the merchant website via an html POST form.

Example: vads_url_post_wallet = https://mydomain-name.com/return_url

Note

If the URL is inaccessible, the transaction cannot be finalized. After thepayment session expires, a rejected transaction will be created. If the merchanthas configured the notification rule for abandoned/canceled transactions, themerchant website will be notified about the reason of rejection via thevads_payment_error field. This field will be set to 149 indicating that the paymentsession has expired.

It will then become visible in the Merchant Back Office, in the History tab




Format ans..1024

Error code 138


vads_url_referral

Description Deprecated field. Use the vads_url_refused field.

URL where the buyer will be redirected in case of a declined authorization (code02 Contact the card issuer) after having clicked on Return to shop.

Input field.

Format ans..127

Error code 26


vads_url_refused

Description URL where the buyer will be redirected in case of a declined payment after havingclicked on Return to shop.

Input field.

Format ans..1024

Error code 25




vads_url_return

Description Default URL to where the buyer will be redirected after having clicked on Return toshop, if vads_url_error, vads_url_refused, vads_url_success or vads_url_cancel isnot set.

If this field has not been transmitted, the Merchant Back Office configuration willbe taken into account.

It is possible to set up return URLs in TEST and PRODUCTION modes. These fieldsare called Return URL of the shop in test mode and Return URL of the shop inproduction mode; they can be viewed in Settings > Shop > Configuration.

If no URL has been specified in the Merchant Back Office and in the form, theReturn to shop button will redirect the buyer to the merchant website URL (URLfield in the shop configuration section).

Input field.

Format ans..1024

Error code 28


vads_url_success

Description URL where the buyer will be redirected in case of an accepted payment after havingclicked on Return to shop.

Input field.

Format ans..1024

Error code 24


vads_user_info

Description Information about the user who made the payment.

In the case of a form payment, this parameter will be resent with the response andwill include the value transmitted in the request.

In the case of a MOTO payment from the Merchant Back Office, this field will bevalued with the user account (login) who made the payment.

Note:

For backward compatibility, it is possible to use this field to set the CPF/CNPJ (legalidentifier in a numeric format between 11 and 20 digits long) required by theClearSale risk management module. However, vads_cust_national_id field can beused.


Format ans..255

Error code 61




vads_validation_mode

Description Specifies the validation mode of the transaction


Format enum

Error code 05


Absent orempty

Takes the value specified in the Merchant Back Office

0 Automatic validation by the payment gateway.

1 Manual validation by the merchant.


vads_version


Version of the exchange protocol with the payment gateway


Format enum

Error code 01

Possible value V2


vads_wallet

Description This field allows the merchant to identify the type of wallet that was used for thepayment.

Present only when a wallet was used for the payment.

List of existing Wallets

Value of the vads_wallet field Wallet type

MASTERPASS Masterpass by Mastercard

GOOGLEPAY Google pay

PAYLIB Paylib


Format an..127


vads_warranty_result

Description Liability shift in case of accepted payment.




Format enum


YES The payment is guaranteed.

NO The payment is not guaranteed.

UNKNOWN Due to a technical error, the payment cannot be guaranteed.

Not specified Liability shift not applicable


Implementation guide - PayZen · Implementation guide Document version 3.8. Contents 1. HISTORY OF...

Documents

Transcript of Implementation guide - PayZen · Implementation guide Document version 3.8. Contents 1. HISTORY OF...