0% found this document useful (0 votes)

268 views

Payment Gateway Implementation Guide

This document provides guidance on implementing a hosted payment page. It discusses different types of payments, choosing a brand, understanding the payment flow, establishing interaction with the payment gateway, setting up notifications, generating payment forms, using additional features, customizing payment pages, displaying payment pages in an iframe, sending payment requests, and analyzing payment results. The document contains detailed technical instructions for developers to integrate a payment solution using a hosted payment page.

Uploaded by

Rakib Chowdhury

Available Formats

Download as PDF, TXT or read online on Scribd

0% found this document useful (0 votes)

268 views

Payment Gateway Implementation Guide

Uploaded by

Rakib Chowdhury

Available Formats

Download as PDF, TXT or read online on Scribd

You are on page 1/ 221

Hosted Payment Page

Implementation guide

Document version 3.21

Contents

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

2. GETTING IN TOUCH WITH TECHNICAL SUPPORT................................................................. 8

3. DIFFERENT TYPES OF PAYMENT.................................................................................................9

3.1. Immediate payment..................................................................................................................................... 9
3.2. Deferred payment........................................................................................................................................ 9
3.3. Installment payment.................................................................................................................................. 10
3.4. Authorization request................................................................................................................................ 10

4. CHOOSING YOUR PREFERRED BRAND.................................................................................... 14

5. UNDERSTANDING THE PAYMENT FLOW................................................................................16

5.1. Defining the steps of the payment process - as seen by the buyer........................................................... 16
5.2. Defining the steps of the payment process - as seen by the merchant..................................................... 19
5.3. Transaction lifecycle..................................................................................................................................20

6. ESTABLISHING INTERACTION WITH THE PAYMENT GATEWAY....................................27

6.1. Setting up the payment page URL............................................................................................................27
6.2. Identifying yourself during data exchange................................................................................................27
6.3. Choosing between Test and Production mode..........................................................................................29
6.4. Managing the interaction with the merchant website............................................................................... 30
6.5. Managing security..................................................................................................................................... 32
6.6. Managing the shop settings via a configuration file.................................................................................34

7. SETTING UP NOTIFICATIONS..................................................................................................... 35
7.1. Notifications about the various statuses of an immediate payment..........................................................35
7.2. Notifications of the different statuses for a deferred payment................................................................. 36
7.3. Notifications about the various statuses of installments........................................................................... 37
7.4. Setting up notifications..............................................................................................................................38
Setting up the Instant Payment Notification........................................................................................ 38
Setting up notifications of the final result of a deferred payment....................................................... 40
Setting up notifications in case of abandoned or canceled payments.................................................. 41
Setting up a notification on batch change............................................................................................42
7.5. Activating the automatic retry...................................................................................................................43
7.6. Manual notification retry...........................................................................................................................45
7.7. Configuring e-mails sent to the buyer...................................................................................................... 46
7.8. Configuring e-mails sent to the merchant.................................................................................................47

8. GENERATING A PAYMENT FORM..............................................................................................48

8.1. Creating an immediate payment............................................................................................................... 50
8.2. Creating a deferred payment..................................................................................................................... 52
8.3. Creating an installment payment...............................................................................................................54
8.4. Creating an authorization without capture................................................................................................ 56

9. USING ADDITIONAL FEATURES................................................................................................. 58

9.1. Managing the return to the merchant website.......................................................................................... 59
9.2. Enabling an automatic return to the merchant website.............................................................................62
9.3. Defining the capture mode (automatic/manual)........................................................................................64
9.4. Transmitting buyer details.........................................................................................................................66
9.5. Transmitting shipping details.................................................................................................................... 67
9.6. Transmitting order details......................................................................................................................... 69
9.7. Enabling / disabling 3D Secure.................................................................................................................72
9.8. Overriding the IPN.................................................................................................................................... 73
9.9. Defining the Merchant ID (MID)............................................................................................................. 74
10. CUSTOMIZING THE PAYMENT PAGES................................................................................... 75
10.1. Overriding the custom template.............................................................................................................. 75
10.2. Managing the payment methods offered to the buyer............................................................................ 76
10.3. Modifying the language.......................................................................................................................... 77
10.4. Modifying the languages available to the buyer.....................................................................................78
10.5. Modifying the name and the URL of the shop.......................................................................................79
10.6. Modifying the name of the "Return to shop" button.............................................................................. 80

11. DISPLAYING THE PAYMENT PAGE IN AN IFRAME............................................................ 81

12. COMPUTING THE SIGNATURE................................................................................................. 83

12.1. Example of implementation with JAVA.................................................................................................85
12.2. Example of implementation with PHP................................................................................................... 88

13. SENDING THE PAYMENT REQUEST....................................................................................... 89

13.1. Redirecting the buyer to the payment page............................................................................................ 89
13.2. Processing errors......................................................................................................................................89
13.3. Managing timeouts.................................................................................................................................. 90

14. ANALYZING THE PAYMENT RESULT..................................................................................... 92

14.1. Retrieving data returned in the response................................................................................................ 94
14.2. Computing the signature......................................................................................................................... 95
14.3. Comparing signatures.............................................................................................................................. 95
14.4. Analyze the nature of the notification.................................................................................................... 96
14.5. Identifying the type of operation............................................................................................................ 97
14.6. Processing the response data...................................................................................................................98
14.7. Processing errors....................................................................................................................................105

15. RETURNING TO THE SHOP.....................................................................................................106

16. PROCEEDING TO TEST PHASE.............................................................................................. 107

17. TESTING THE IPN......................................................................................................................109

18. ACTIVATING THE SHOP TO PRODUCTION MODE.......................................................... 110

18.1. Generating the production key.............................................................................................................. 110
18.2. Shifting the merchant website to live mode......................................................................................... 110
18.3. Making a first production payment.......................................................................................................110
18.4. Regenerating the production key.......................................................................................................... 111

19. DATA DICTIONARY................................................................................................................... 112

1. HISTORY OF THE DOCUMENT

Version Author Date Comment

3.21 Lyra Network 07/11/2018
• Chapter Displaying the payment page in an iframe: addition of details about the
use of vads_iframe_options
• Chapter Processing the response data: addition of details about installment
payments
• Addition of a note on taking into account 2 algorithms during the change of an
algorithm
• Data dictionary
• vads_ext_info_bil_date_of_birth and vads_ext_info_ship_date_of_birth:
update of descriptions
• vads_iframe_options: addition of field description
• vads_override_payment_cinematic: update of values
• vads_operation_type: addition of the VERIFICATION value
• vads_payment_cards: correction of theTRUFFAUT_CDX value
• vads_product_ext_id: addition of field description
• vads_sequence_number: addition of details about installment payments

3.20 Lyra Network 07/08/2018

• Addition of the chapter Displaying the payment page in an iframe
• Update of the Computing the signature chapter
• Data dictionary
• 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 the description and possible values

3.19 Lyra Network 19/06/2018

• Update of the chapter Computing the signature.
• Update of the vads_product_label field format
• Addition of the vads_token_id field
• Addition of the chapter Overriding the custom template
• Update of the definition and the values of the vads_theme_config field
• Update of the definition of the vads_sequence_number field
• New value of the vads_trans_status field:SUSPENDED

3.18 Lyra Network 23/05/2018

• Update of the chapter Identifying yourself during data exchange: alphanumeric
key (certificate)
• Update of the chapter Computing the signature: computational algorithm
• Update of the chapter Managing errors: addition of messages for frequent errors
• Addition of the chapter Choosing the hash algorithm
• Data dictionary
• Addition of vads_avs_result
• Addition of vads_brand_management
• Format update of vads_acquirer_transient_data and vads_payment_seq
• Addition of vads_url_post_wallet

Hosted Payment Page - Document version 3.21

All rights reserved - 4 / 221
Version Author Date Comment
3.17 Lyra Network 21/03/2018
• Update of the Managing security chapter: SHA-256 is supported.
• Update of the Computing the signature chapter.
• Update of the Proceeding to testing chapter.
• Addition of the Manage timeouts chapter
• Data dictionary
• vads_currency: update of the list of supported currencies
• vads_first_installment_delay: update of the definition
• vads_ext_info: improvement of the definition
• vads_risk_assessment_results: improvement of the definition
• Correction of a field name error: vads_url_refused instead of vads_url_refusal
• Addition of the vads_cust_address2 field

3.16 Lyra Network 12/12/2017

• Addition of a note in Enabling an automatic return to the merchant website
chapter
• Update of the Processing errors chapter.
• FAQ chapter removed and the FAQ information added in the Getting in touch with
technical support chapter.
• Data dictionary
• Update of the vads_risk_analysis_result field: addition of Konduto values

3.15 Lyra Network 04/09/2017 Modification of the expiry of transactions: from now on, it depends on the
authorization validity period.
Data dictionary
• Update of the definition of "ans"
• Update of the vads_action_mode field: webview value suppressed

3.14 Lyra Network 17/07/2017 Data dictionary

• Format corrected for the field vads_cust_address_number
• Update of the vads_sub_init_amount and vads_sub_amount fields
• Update of the vads_theme_config field

3.13 Lyra Network 06/06/2017 Data dictionary

• Correction of the format of the fields vads_url_cancel,vads_url_error,
vads_url_refused and vads_url_success (up to 1025 alphanumeric and special
characters)
• Addition of the fields vads_first_installment_delay, vads_card_holder_name,
vads_proof_of_id_type and vads_proof_of_id_number
• Update of the vads_acquirer_transient_data field
• Format corrected for the field vads_order_id
• vads_url_check_src: addition of the BATCH value and its description
• vads_payment_cards: addition of the values VPAY, FULLCB3X and FULLCB4X

3.12 Lyra Network 03/04/2017 Data dictionary

• vads_action_mode: addition of the WEBVIEW and IFRAME values
• vads_theme_config: addition of the MODE_IFRAME value
• vads_currency: addition of precisions for currencies
• Addition of vads_acquirer_transient_data

3.11 Lyra Network 27/02/2017

• Chapter Managing errors: Addition of precisions concerning error codes
• Chapter Viewing parameters sorted by category : Addition of the Error Code
column to the tables

Hosted Payment Page - Document version 3.21

All rights reserved - 5 / 221
Version Author Date Comment
Data dictionary
• new field: vads_authent_paypal_protection_eligibility
• vads_currency: addition of the alpha encoding to tables.
Removal of the Icelandic Crown (ISK), update and addition of precisions for
currencies.

3.10 Lyra Network 30/01/2017

• vads_bank_product: Addition of new values for MasterCard cards
• Addition of the vads_effective_currency field
• Modification of the AMEX network by AMEXGLOBAL network as a result of
migration

3.9 14/09/2016
• vads_payment_cards: addition of the MASTERPASS value
• vads_product_label: correction of the format.

3.8 Lyra Network 16/08/2016 Details:

• Value of vads_trans_status: CANCELLED instead of CANCELED
• Value of vads_risk_control: COMMERCIAL_CARD instead of CARD_COMMERCIAL
• vads_url_check_src: addition of the VOICE_ORDER value
• Addition of the note on MULTI_EXT in vads_capture_delay and
vads_payment_config
• vads_contracts: addition of networks and precisions for the definition of the MID

3.7 Lyra Network 05/2016 Chapter improvements:

• Transmitting order details
• Activating the automatic retry
Data dictionary
• vads_payment_cards: addition of new values.
• vads_theme_config: addition of the values MERCHANT_MESSAGE,
RESPONSIVE_MODEL and RESPONSIVE_MAIL_MODEL.
• vads_ship_to_speed: addition of the PRIORITY value
• vads_ship_to_delay: new field.

3.6 Lyra Network 01/02/2016 Data dictionary

• vads_auth_result: addition of the AMEX values
• vads_currency: precisions added for multi-currency management
• vads_payment_cards: addition of the values EDENRED_TR (Ticket Restaurant)
and EDENRED_EC (Ticket EcoChèque)

3.5 Lyra Network 23/11/2015 Data dictionary

• vads_payment_cards and vads_contracts: addition of values
• Addition of details to field formats:
• vads_cust_address
• vads_ship_to_street
• vads_ship_to_street2
• vads_trans_status: addition of the INITIAL status to the list of possible values.
• vads_change_rate
• vads_recurrence_number

3.4 Lyra Network 01/10/2015 Data dictionary

• Format corrected for the field vads_product_labelN
• Correction of the vads_product_vatN field name

Hosted Payment Page - Document version 3.21

3.3a Lyra Network 24/07/2015 Addition of chapters

• Setting up a notification on batch change
Chapters updated:
• Using i-frames
• vads_trans_id

3.3 Lyra Network 07/07/2015 Addition of chapters

• Configuring e-mails sent to the buyer
• Configuring e-mails sent to the merchant
Additional information about using i-frames
Data dictionary
• Addition of fields:
• vads_trans_uuid
• vads_risk_assessment_result
• vads_product_vatN
• vads_bank_product: values added for pure CB cards.
• vads_risk_analyzis_result: values added.
• vads_payment_cards: values added.

3.2 Lyra Network 27/04/2015 Data dictionary

Correction of an error for the vads_ship_to_type field
3.1 Lyra Network 02/03/2015 Server URL renamed to Instant Payment Notification URL
Addition of chapters
• Managing the shop settings via a configuration file
• Activating the automatic retry
• Manual retry of the notification
Additional information about using i-frames.
Data dictionary
• Addition of fields:
• vads_payment_seq
• vads_cust_legal_name
• vads_ship_to_legal_name
• E_CV value added to the list of payment methods (ANCV network)
• Addition of details to the vads_url_check field

3.0 Lyra Network 21/11/2014 Complete overhaul of documentation.

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.

Hosted Payment Page - Document version 3.21

Looking for help? Check our FAQ on our website

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

For technical inquiries or support, you can reach us from Monday to Friday, between 9am and 6pm

by phone at:

by e-mail: [email protected]
via your Merchant Back Office: menu Help > Contact support

To facilitate the processing of your demands, you will be asked to communicate your shop ID (an 8-digit
number) .
This information is available in the "registration of your shop" e-mail or in the Merchant Back Office
(Settings > Shop > Configuration).

Hosted Payment Page - Document version 3.21

3.1. Immediate payment

A payment is considered as immediate payment if:
• the amount is debited once,
• the capture delay is of 0 days.
An authorization request for the total amount is sent. The payment is captured by the bank as soon as
possible.

3.2. Deferred payment

A payment is considered as deferred payment if:
• the amount is debited once,
• the capture delay is strictly more than 0 days,
the capture date cannot be programmed later than 12 months after the date of payment recording
date.

There are two types of deferred payments:

• Capture delay before the authorization expiration date (see the Authorization validity period section
below).
An authorization request for the total amount is sent. If the merchant has not made any modifications, the
payment is captured by the bank on the requested capture day.
• Capture delay after the authorization expiration date (see the Authorization validity period section
below).
An information request will be made if the capture delay is greater than the validity period of an
authorization request.
The information request is done in order to to check the card validity. For acquirers who do not support
information request, an authorization request for 1 EUR will be made.
If this authorization for 1 EUR is accepted, the payment is registered.
An authorization request for the total amount is made one day before the requested capture.
The payment might be accepted or declined. Therefore, the merchant must be extremely attentive with
this payment type and make sure to deliver the goods / services to the buyer.

Hosted Payment Page - Document version 3.21

A payment is considered as an installment payment if the buyer is debited with the amount for the
purchase in several installments
The first installment is similar to the immediate payment.
The next installment is similar to a deferred payment.
Only the first installment can be guaranteed to the merchant on the condition that the requested capture
date for the first installment is set before the authorization expiry date depending on the payment method.
(see Authorization validity period section below).

3.4. Authorization request

An authorization request is a message sent by the payment gateway to the card issuer to obtain the issuer's
approval for the transaction.
Usually, the debit is effective only after the transaction capture.
However, certain issuers of prepaid cards debit the authorization amount in real time. If the authorization
is not captured before its validity period expires, the amount is re-credited to the account holder's account
(see table below).

Authorization validity period

Authorization validity
Network code Payment method Card types
period (in days)
ACCORD Accord brand card ACCORD_STORE 255
ACCORD Alinéa brand card ALINEA 255
ACCORD Alinéa gift card ALINEA_CDX 0
ACCORD Allobébé gift card ALLOBEBE_CDX 0
ACCORD Auchan brand card AUCHAN 255
ACCORD BizzBee gift card BIZZBEE_CDX 0
ACCORD Boulanger brand card BOULANGER 255
ACCORD Brice gift card BRICE_CDX 0
ACCORD Illicado Gift Card ILLICADO 0
ACCORD Jouéclub Gift Card JOUECLUB_CDX 0
ACCORD Leroy-Merlin brand card LEROY-MERLIN 255
ACCORD Norauto brand card NORAUTO 255
ACCORD PicWic brand card PICWIC 0
ACCORD Villaverde brand card VILLAVERDE 0
ACCORD_SANDBOX Accord brand card - Sandbox ACCORD_STORE_SB 255
ACCORD_SANDBOX Alinéa gift card - Sandbox ALINEA_CDX_SB 0
ACCORD_SANDBOX Alinéa brand card - Sandbox ALINEA_SB 255
ACCORD_SANDBOX Allobébé gift card - Sandbox ALLOBEBE_CDX_SB 0
ACCORD_SANDBOX Auchan brand card - Sandbox AUCHAN_SB 255
ACCORD_SANDBOX BizzBee gift card - Sandbox BIZZBEE_CDX_SB 0
ACCORD_SANDBOX Boulanger brand card - BOULANGER_SB 255
Sandbox
ACCORD_SANDBOX Brice gift card - Sandbox BRICE_CDX_SB 0
ACCORD_SANDBOX Illicado gift cards - Sandbox ILLICADO_SB 0
ACCORD_SANDBOX JouéClub gift card - Sandbox JOUECLUB_CDX_SB 0
mode

Hosted Payment Page - Document version 3.21

All rights reserved - 10 / 221
Authorization validity
Network code Payment method Card types
period (in days)
ACCORD_SANDBOX Leroy-Merlin brand card - LEROY-MERLIN_SB 255
Sandbox mode
ACCORD_SANDBOX Norauto brand card - Sandbox NORAUTO_SB 255
mode
ACCORD_SANDBOX PicWic brand card - Sandbox PICWIC_SB 0
ACCORD_SANDBOX Villaverde brand card - VILLAVERDE_SB 0
Sandbox
AMEX American Express AMEX 7
AMEXGLOBAL American Express AMEX 7
ANCV e-Chèque-Vacances E_CV 0
AURORE Aurore Card AURORE_MULTI 29
CARDCOMPLETE JCB JCB 7
CARDCOMPLETE Maestro MAESTRO 30
CARDCOMPLETE Mastercard MASTERCARD 7
CARDCOMPLETE Visa VISA 7
CARDCOMPLETE Visa Electron VISA_ELECTRON 7
CARDCOMPLETE VPay VPAY 7
CB Bancontact BANCONTACT 30
CB CB CB 7
CB E-carte bleue (French virtual E-CARTEBLEUE 7
card)
CB Maestro MAESTRO 30
CB MasterCard MASTERCARD 7
CB Visa VISA 7
CB Visa Electron VISA_ELECTRON 7
CB VPay VPAY 7
CERIDIAN Truffaut Gift Card TRUFFAUT_CDX 7
COFINOGA Be Smart Cofinoga Card COFINOGA 7
COFINOGA Soficarte card SOFICARTE 30
CONECS Conecs electronic meal CONECS 30
vouchers
CONECS Apetiz electronic meal CONECS_APETIZ 30
vouchers
CONECS Chèque Déjeuner electronic CONECS_CHQ_DEJ 30
meal vouchers
CONECS Sodexo electronic meal CONECS_SODEXO 30
vouchers
EDENRED Edenred Eco Chèque voucher EDENRED_EC 7
EDENRED Culture Edenred voucher EDENRED_TC 7
EDENRED Edenred meal voucher EDENRED_TR 7
EPS EPS Online Überweisung EPS 0
EPS EPS Online Überweisung EPS_GIROPAY 0
EVO American Express AMEX 2
EVO Discover DISCOVER 2
EVO Maestro MAESTRO 0
EVO MasterCard MASTERCARD 14
EVO Visa VISA 2
EVO Visa Electron VISA_ELECTRON 0
FULLCB Payment in 3 installments with FULLCB_3X 7
no fees with BNPP PF
FULLCB Payment in 4 installments with FULLCB_4X 7
no fees with BNPP PF
GATECONEX Bancontact Mistercash BANCONTACT 30
GATECONEX Diners Club Card DINERS 3

Hosted Payment Page - Document version 3.21

All rights reserved - 11 / 221
Authorization validity
Network code Payment method Card types
period (in days)
GATECONEX Discover card DISCOVER 5
GATECONEX E-carte bleue (French virtual E-CARTEBLEUE 7
card)
GATECONEX Maestro MAESTRO 30
GATECONEX MasterCard MASTERCARD 7
GATECONEX Visa VISA 7
GATECONEX Visa Electron VISA_ELECTRON 7
GATECONEX VPay VPAY 7
GICC_DINERS Diners DINERS 3
GICC_DINERS Discover DISCOVER 5
GICC_MAESTRO Bancontact MisterCash BANCONTACT 30
GICC_MAESTRO Maestro MAESTRO 30
GICC_MASTERCARD MasterCard MASTERCARD 7
GICC_VISA Visa VISA 7
GICC_VISA Visa Electron VISA_ELECTRON 7
GICC_VISA VPay VPAY 7
GIROPAY Giropay GIROPAY 0
GOOGLEPAY Google Pay wallet payment GOOGLEPAY 0
HOBEX_DD Hobex direct debit ELV 0
IDEAL iDeal Internet Banking IDEAL 0
JCB JCB JCB 7
KLARNA Klarna Internet Banking KLARNA 7
PPRO Alipay ALIPAY 0
PPRO Bancontact Mistercash BANCONTACT 0
PPRO iDeal Internet Banking IDEAL 0
PPRO Multibanco MULTIBANCO 0
PPRO Sofort Banking SOFORT_BANKING 0
PPRO Union Pay UNION_PAY 0
PPRO WeChat WECHAT 0
MASTERPASS MasterPass MASTERPASS 0
ONEY FacilyPay Oney ONEY 255
ONEY_SANDBOX FacilyPay Oney - Sandbox ONEY_SANDBOX 255
mode
PAYDIREKT PayDirekt PAYDIREKT 7
PAYLIB Paylib Wallet PAYLIB 7
PAYPAL PayPal PAYPAL 3
PAYPAL_SB PayPal - Sandbox mode PAYPAL_SB 3
PAYSAFECARD Paysafecard Prepaid Card PAYSAFECARD 0
POSTFINANCEV2 PostFinance POSTFINANCE 1
POSTFINANCEV2 PostFinance E-finance POSTFINANCE_EFIN 1
REDSYS American Express AMEX 7
REDSYS Diners DINERS 3
REDSYS JCB JCB 7
REDSYS Maestro MAESTRO 30
REDSYS MasterCard MASTERCARD 7
REDSYS Visa VISA 7
REDSYS Visa Electron VISA_ELECTRON 7
REDSYS Vpay VPAY 7
SECURETRADING American Express AMEX 7
SECURETRADING Diners DINERS 3
SECURETRADING Discover DISCOVER 5
SECURETRADING JCB JCB 7

Hosted Payment Page - Document version 3.21

All rights reserved - 12 / 221
Authorization validity
Network code Payment method Card types
period (in days)
SECURETRADING Maestro MAESTRO 30
SECURETRADING MasterCard MASTERCARD 7
SECURETRADING Visa VISA 7
SECURETRADING Visa Electron VISA_ELECTRON 7
SECURETRADING VPay VPAY 7
SEPA SEPA CREDIT TRANSFER SCT 13
SEPA SEPA DIRECT DEBIT SDD 15
SOFORT Sofort Banking SOFORT_BANKING 0
WIRECARD Euro-Cheque card ECCARD 13
WIRECARD Giropay GIROPAY 0
WIRECARD Maestro MAESTRO 30
WIRECARD MasterCard MASTERCARD 7
WIRECARD SEPA DIRECT DEBIT SDD 15
WIRECARD Visa VISA 7
WIRECARD Visa Electron VISA_ELECTRON 7
WIRECARD VPay VPAY 7

Hosted Payment Page - Document version 3.21

Since 9 June 2016, the EU directive PSD 2 allows:

• the merchant to choose the brand that will be offered as a priority to buyers during the payment
• the cardholder to have the choice of card brand (i.e. the network used for the transaction)
Thus, for CB cards co-branded VISA or MASTERCARD for example, the buyer will have the choice
between the French CB network and the international VISA or MASTERCARD networks.

A co-branded card is a card that includes two payment companies.

Example
• CB + VISA or ELECTRON or VPAY
• CB + MASTERCARD or MAESTRO

Note
Each time an authorization uses international networks, the merchant may have to pay extra fees that will
be transferred to the used network (depending on the commissioning methods of the merchant's acquirer
contract).

What steps does the merchant need to take?

On PayZen, CB is configured as the default brand during the payment stages.
To choose or modify your preferred brand and to know your default brand, please contact sales
administration

What is the impact on the payment process?

While the buyer enters the card number, the payment gateway searches for brands associated with the
card.
The search is based on the BIN (Bank Identification Number) of the card. Once the list of brands has been
identified, there are several possibilities:

• The card is associated with one brand only

In this case, the logo of the corresponding brand is automatically
displayed.

• The card is associated with several brands

In this case, the logo of the merchant's preferred brand is
automatically displayed.
A drop-down list will appear to the right of the entry field to allow
the buyer to choose another brand.

• No brands detected
The buyer possibly made an error when entering the card number.

At the end of payment, the brand selected by the buyer will:

• appear on the transaction receipt,
• appear in the transaction history in the Merchant Back Office.
• be transmitted to the merchant website with the IPN, via the vads_card_brand and
vads_brand_management parameters.

Hosted Payment Page - Document version 3.21

All rights reserved - 14 / 221
Field name Format Description
This parameter is an output field. It indicates to the merchant:
• whether the buyer used a different brand than the one
defined by default by the merchant
• the brand chosen by the buyer
vads_brand_management json • the list of available brands
Example of a value:

vads_brand_management={"userChoice":true,
"brand":"CB","brandList":"CB|VISA"}

Table 1: Details of the vads_brand_management field

Hosted Payment Page - Document version 3.21

The online payment process appears differently when viewed from the point of view of the buyer or of
the merchant.

5.1. Defining the steps of the payment process - as seen by the buyer
The diagram below presents the exchange process from the point of view of the buyer.

1. The buyer validates the shopping cart.

2. The merchant website redirects the buyer to the payment gateway.
This redirection is done via an HTML POST form in HTTPS.
The parameters of the form are described in the chapter Generating a payment form.
3. When the parameters and their signature have been verified, the payment method selection page
appears.

Figure 1: Selecting a payment method

Hosted Payment Page - Document version 3.21

All rights reserved - 16 / 221
If the payment method has been specified in the form, the buyer moves on directly to step 6.
4. The buyer selects a payment method.
5. The buyer clicks Validate.
6. The buyer enters the number and the expiry date of his/her card.
If the card has a security (CVV) code, it must be specified.

Figure 2: Entering payment method details

7. During a payment by CB card co-branded VISA or MASTERCARD, the buyer chooses the logo of the
brand he or she wishes to use for the payment.
The payment gateway automatically detects the brand(s) associated with the number of the used
card.
If several brands are available, a drop-down list will appear to the right of the entry field. The logo
chosen by the merchant will appear first on the list.
If only one brand is available, the logo will appear automatically.
If you need help, you can click the ? icon to the right of the entry field.
8. He or she and confirms the entry by clicking Valid.
9. If the merchant and the buyer's card are subscribed to the 3D Secure authentication option, the
payment will be authenticated with 3D Secure.
10.An authorization request is sent to the buyer's bank, the issuer, in addition to internal fraud
verification on the payment gateway.
11.In case of success, a summary page is presented to the buyer resuming the transaction details.
The logo of the brand selected by the buyer will appear on the receipt.
A button allowing to return to the shop is presented.

Hosted Payment Page - Document version 3.21

In case of failure, a message is displayed. The buyer is informed of the rejection of the payment request.
A button allowing to cancel and return to the shop is presented.
If you have configured a number of additional attempts that is higher than 0 in your Merchant Back Office,
the buyer will be able to retry to finalize their payment. If he or she accepts, the payment process resumes
at the stage of payment method selection.
Once the additional attempts have been used, the payment is definitively rejected.

Figure 4: Summary page in case of a failed transaction

Hosted Payment Page - Document version 3.21

All rights reserved - 18 / 221
5.2. Defining the steps of the payment process - as seen by the merchant
Here is what the online payment process looks like from the merchant's point of view:

Figure 5: Payment process - as seen by the merchant

1. The buyer validates the shopping cart.

2. The merchant website creates a form using the data from the buyer's cart.
3. The merchant website redirects the buyer to the payment gateway. The redirection is done via an
HTML POST form using HTTPS. The parameters of the form are described in the chapter Generating
a payment form.
4. After the buyer enters the payment method details, the payment gateway proceeds to the payment.
5. Depending on the shop settings (see chapter Setting up notifications), the payment result is
automatically transmitted to the merchant website.
6. The merchant website analyzes and processes the payment result.
7. It updates the database (order/stock status, etc.).
8. The buyer sees the payment result on the payment gateway. If the buyer decides to return to the
merchant website, he/she sees a "thank you" message and the order status appears.

Hosted Payment Page - Document version 3.21

All rights reserved - 19 / 221
5.3. Transaction lifecycle
In all the following diagrams, the following caption is used:
Action required from the merchant - manual (Merchant Back Office) or automatic (Web Services)

Automatic validation mode

The life cycle of an immediate payment transaction

Once the payment request has been made, several verification processes start automatically:
• 3D Secure authentication.
• Various local verification processes made directly by the payment gateway (they potentially include
verification processes that concern subscription to the risk management option).
• An authorization request is also made by the buyer's bank on the day of payment independently of the
capture date at the desired bank
If one of the verification processes fails, the payment request will not be accepted. The buyer is
informed of the rejection on the screen. In the Merchant Back Office, the transaction appears with the
Refused status.
In case of a successful verification process, the transaction appears with the Waiting for capture status.
The buyer will see a notification message on the screen and by e-mail if the payment request has been
accepted. The transaction will be automatically sent for capture on the day requested by the buyer.
Before the capture date, the buyer can modify it together with the amount (only smaller amounts can
be entered in case of partial shipment by the merchant).
If necessary, the buyer can also cancel the transaction: the transaction will then appear with the
Canceled status.

Hosted Payment Page - Document version 3.21

Capture delay shorter than the authorization validity period

(see diagram "The life cycle of an immediate payment transaction").
Capture delay greater than the authorization validity period
All the transactions for deferred payments made in automatic validation mode with a successfully
completed authorization request for 1 EUR (or information request about the CB network if the acquirer
supports it) can be viewed in the Merchant Back Office with the Waiting for authorization status.
The authorization request is automatically sent:
• default option: on the desired capture date,
• option with an expected authorization: depending on the selected payment method, on the specified
day (see table that illustrates the authorization validity) before the expected capture date by the bank.
Contact sales administration if you wish to enable the anticipated authorization feature.
In case the authorization is declined for reasons unrelated to fraud (see table), it will be rerun daily
until two days before the capture. In the meantime, the buyer may cancel the transaction or modify its
amount (only smaller amounts can be entered) and/or the capture date.
A deferred payment goes through the steps in the diagram below:

Hosted Payment Page - Document version 3.21

All rights reserved - 21 / 221
The life cycle of an installment payment transaction
Depending on the capture date, the first installment will have exactly the same features as an immediate
payment or a deferred payment
By default, the following installments will have the Waiting for authorization status. The buyer's bank will
be able to reject the authorization request. The payment gateway will then inform the merchant by e-mail
that the transaction has been declined.
The authorization requests for the installments to come are automatically sent are automatically sent as
a transaction for a deferred payment, with two possible dates:
• default option: on the desired capture date,
• option with an expected authorization: depending on the selected payment method, on the specified
day (see table that illustrates the authorization validity) before the expected capture date by the bank.

The following installments go through the steps specified in the diagram below (in case of an authorization
request that will not be repeat):

By no means does canceling an installment imply that the installments to come will be canceled.

Hosted Payment Page - Document version 3.21

The life cycle of an immediate payment transaction

Following a payment request, the verification process starts automatically:
• 3D Secure authentication.
• Various local control processes performed directly by the payment gateway (they potentially include
verifications linked to the optional risk management service subscription).
• An authorization request is also made by the buyer's bank.
If one of the verification processes fails, the payment request will not be accepted. The buyer is informed of
the rejection on the screen. In the Merchant Back Office, the transaction appears with the Refused status.

In the opposite case, the payment is accepted and the transaction appears in the Merchant Back Office
with the To be validated status.
In this case, the merchant must validate the transaction before the expiry date of the authorization request.
If the validation is made after this date, the transaction appears as Expired and cannot be captured in the
bank.

As soon as a transaction is validated, its status changes to Waiting for capture.

The transaction can also be canceled, if necessary. In this case, the transaction takes the Canceled status.

Hosted Payment Page - Document version 3.21

Capture delay shorter than the authorization validity period

Hosted Payment Page - Document version 3.21

All rights reserved - 24 / 221
The life cycle of an installment payment transaction
Depending on the capture date, the first installment will have exactly the same features as an immediate
payment or a deferred payment.
By default, the installments to come have the To be validated and authorized status as long as the first
installment has not been validated by the merchant. The successful execution of the installments is not
guaranteed to the merchant. The buyer's bank may reject the authorization request

Validation of the first installment implies that all the installments will be validated as well. However,
canceling an installment does not cancel the installments to come.

Hosted Payment Page - Document version 3.21

All rights reserved - 25 / 221
Characteristics linked to anticipated authorizations
Contact sales administration if you wish to enable anticipated authorizations.
This process only applies to authorization requests:
• for deferred payments,
• for installments, other than the first one, in case of installment payments.
The authorization will be triggered on D-Δ (see authorization expiry for each payment method) before the
desired capture date.
In case of refusal by the authorization server of the buyer's bank, due to exclusively non fraud-related
reasons (see table), a process automatically reiterates authorization requests until D-2.
In case of refusal for fraud-related reasons, the transaction is considered as definitively rejected.

Hosted Payment Page - Document version 3.21

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 can be transmitted to the merchant website in two ways
• automatically by means of a notification called Instant Notification URL (also called IPN), see chapter
Setting up notifications.
• via the browser, when the buyer clicks on the button to return to the merchant website, see chapter
Managing the return to the merchant website.
To guarantee the security of the exchange, the data are signed with a key (formerly called "certificate")
only known to the merchant and the payment gateway.

6.1. 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/

6.2. Identifying yourself during data exchange

To be able to interact with the payment gateway, the merchant needs to have:
• The shop ID: allows to identify the merchant website during data exchange. Its value is transmitted in
the vads_site_id field.
• The key: formerly called "certificate", allows to compute the alphanumeric signature transmitted in the
signature field.
To retrieve these values:
1. Connect to the Merchant Back Office: https://secure.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 Connection
identifiers- [your shop name].

4. Click on Sign in.

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

5. Click on Settings > Shop.

6. Select the Certificates tab.

Hosted Payment Page - Document version 3.21

Two types of key (certificates) are available:

• The test key (certificate) for generating the form signature in test mode.
• The production key (certificate) for generating 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 certificate button and select the format
("ALPHANUMERIC" or "NUMERIC").

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

Hosted Payment Page - Document version 3.21

All rights reserved - 28 / 221
6.3. Choosing between Test and Production mode
The choice between TEST or PRODUCTION mode can be made using the vads_ctx_mode field (see chapter
Generating a payment form).
• The TEST mode allows to make test payments.
It is available at all times, even after the generation of the production key (certificate).
If you create a new merchant website (or have access to the acceptance testing environment), you can
make tests without impacting the website that is currently in production
TEST transactions can be viewed in the Merchant Back Office via the Management > Test Transactions
menu.
• PRODUCTION mode is only available once the production key (certificate) has been generated (see
chapter Activating the shop in PRODUCTION mode ).
It allows to make real payments.
PRODUCTION transactions can be viewed in the Merchant Back Office via the Management >
Transactions menu.

Hosted Payment Page - Document version 3.21

All rights reserved - 29 / 221
6.4. 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 data
is 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 mode.
To process these notifications, the merchant must create a page on its website that:
• analyze the data received via POST,
• checks that the received information is complete by computing the signature,
• checks that the notification is not duplicate (e.g. notification returned from the Merchant Back Office,
• triggers an update of its 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 taken to display the payment summary page. The
longer the processing takes, the later the summary will be shown.
To receive notifications, the merchant must set up the notification rules in his Merchant Back Office (see
chapter Setting up notifications).
In case of an issue during interaction with the merchant website, the payment gateway sends an e-mail to
the shop administrator stating the reason of the error (HTTP error, etc.) and the instructions for returning
the notification from the Merchant Back Office.

Return URL to the merchant website

The merchant can configure the "default" return URLs in the Merchant Back Office via the menu Settings
> Shop > Configuration tab:

Figure 7: 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 outcome.
If no URL has been set up, the main URL of the shop will be used for redirection (URL parameter defined
in the Details section of the shop).

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

Hosted Payment Page - Document version 3.21

All rights reserved - 30 / 221
Note:
The status of the rule "Instant payment notification at the end of payment" (IPN) is displayed in this view.
If the URL has not been set up, make sure to specify it (see chapter Setting up notifications).

Hosted Payment Page - Document version 3.21

All rights reserved - 31 / 221
6.5. Managing security
There are several ways to guarantee the security of online payments.

Guaranteeing the data interchanges integrity

The integrity of shared information is preserved by the exchange of alphanumeric signatures between the
payment platform 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 through a hash function (SHA-1, HMAC-SHA-256).
The merchant will be able to choose the hash algorithm in the Merchant Back Office (see chapter Choosing
the hash algorithm).
The outcome chain is called the digest (empreinte in French) of the initial chain.
The digest must be transmitted in the signature field (see chapter Computing the signature

Modeling of security mechanisms:

Figure 8: Diagram of a security mechanism

1. The merchant website build 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 the
merchant website.
5. If the signatures are different, the payment request is rejected.
If they are not, the gateway proceeds to the payment.
6. The gateway build the result data and computes the response signature.
7. Depending on the shop configuration (see chapter Setting up notifications), the payment gateway
submits the payment result to the merchant website.
8. The merchant website receives the data and computes the signature. It compares the computed
signature with the signature that was transmitted by the payment gateway.
9. If the signatures are different, the merchant analyses the origin of the error (computation error,
attempted fraud, etc.).

Hosted Payment Page - Document version 3.21

All rights reserved - 32 / 221
If they are not, the merchant proceeds to update his/her database (stock status, order status, etc.).

Selecting the hash algorithm

From the Merchant Back Office (Settings > Shop > Configuration menu) the merchant has the possibility
to choose the hash function he/she wants to use to generate signatures algorithms.

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 data
transmitted by the gateway during notifications.

In order to facilitate changing the algorithm, the SHA-1 or HMAC-SHA-256 signatures will be accepted
without 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 keep the key in a safe place (encrypted file, database etc.).

If you lose the key, you will be able to regenerate a new one via your Merchant Back Office.
Remember that the production key can be viewed in the Merchant Back Office by displaying the menu
Settings > Shop > Certificates tab.

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 card
number. 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 and
beginning with 3, 4 or 5.

Hosted Payment Page - Document version 3.21

All rights reserved - 33 / 221
6.6. Managing the shop settings via a configuration file
Using a configuration file allows to avoid including hard-coded values in the code.
The configuration files may contain:
• the payment page URL,
• the test and production keys,
• the shop ID,
• etc.
These files allow to sort the data to be saved.
The program that generates the payment form interrogates the configuration file to know the value of a
parameter.
It is the merchant's responsibility to do anything in his or her power to limit the access to the configuration
file (.htaccess file, rewrite the URL, etc...)

Example pf "conf.txt" configuration file:

vads_site_id = 11111111
TEST_key = 2222222222222222
PROD_key = 3333333333333333
vads_ctx_mode = TEST

Example of a call to configuration file in the payment form:

$conf_txt = parse_ini_file("conf.txt");
if ($conf_txt['vads_ctx_mode'] == "TEST") $conf_txt['key'] = $conf_txt['TEST_key'];
if ($conf_txt['vads_ctx_mode'] == "PRODUCTION") $conf_txt['key'] = $conf_txt['PROD_key'];

Hosted Payment Page - Document version 3.21

The Merchant Back Office allows to manage the events that will generate a the notification transfer to the
merchant website 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

7.1. Notifications about the various statuses of an immediate payment

Figure 9: Flowchart - Immediate payment

Event Notified status Name of the rule to configure

Instant Payment Notification URL on
Abandoned by the buyer ABANDONED
cancellation
Instant Payment Notification URL on an
Cancellation by the merchant CANCELLED
operation coming from the Back Office
AUTHORISED_TO_VALIDATE, Instant Payment Notification URL at the
Response to the authorization request
AUTHORISED, REFUSED end of payment
Table 2: Required notification rules for an immediate payment

Hosted Payment Page - Document version 3.21

Figure 10: Flowchart - Deferred payment

Δ : authorization validity period

Event Notified status Name of the rule to configure
Instant Payment Notification URL on
Abandoned by the buyer ABANDONED
cancellation
Instant Payment Notification URL on
Cancellation by the merchant CANCELLED an operation coming from the Back
Office
Instant Payment Notification URL on
Cancellation by the merchant WAITING_AUTHORISATION an operation coming from the Back
Office
Response to the authorization
request for 1 EUR (or information REFUSED, WAITING_AUTHORISATION, Instant Payment Notification URL at
request about the CB network if WAITING_AUTHORISATION_TO_VALIDATE the end of payment
the acquirer supports it)

Hosted Payment Page - Document version 3.21

All rights reserved - 36 / 221
Event Notified status Name of the rule to configure
Response to the authorization AUTHORISED, REFUSED, Instant Payment Notification URL on
request AUTHORISED_TO_VALIDATE batch authorization
Table 3: Notification rules to be activated for a deferred payment

7.3. Notifications about the various statuses of installments

Figure 11: Flowchart - Installment due dates

Δ : authorization validity period

Event Notified status Name of the rule to configure

Instant Payment Notification URL on an
Cancellation by the merchant CANCELLED
operation coming from the Back Office
Instant Payment Notification URL on
Response to the authorization request AUTHORISED, REFUSED
batch authorization
Table 4: Required notification rules for the installments

Hosted Payment Page - Document version 3.21

All rights reserved - 37 / 221
7.4. Setting up notifications
Several types of notifications are provided in the Merchant Back Office. They allow the configuration of
the 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 to
the merchant website.
To access notification rule management:
1. Go to the following menu: Settings > Notification rules.

Figure 12: Notification rules

Setting up the Instant Payment Notification

This notification is required to communicate the result of a payment request.
To set up this notification:
1. Right-click Instant Payment Notification URL at the end of payment.

2. Select Enable the rule.

3. Right-click again Instant Payment Notification URL at the end of payment.

4. Select Manage the rule.

5. Enter the URL of your page in the fields URL to call in TEST mode and URL to call in PRODUCTION
mode.

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

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

8. 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 (up
to 4 times).
For more information, see chapter Activating the automatic retry

Hosted Payment Page - Document version 3.21

If the payment gateway is unable to access the URL of your page, an e-mail will be sent to the shop
administrator.
It contains:
• The HTTP code of the encountered error
• Parts of analysis depending on the error
• Its consequences
• Instructions to resend from the Merchant Back Office the notification to the URL already specified
above.

Hosted Payment Page - Document version 3.21

All rights reserved - 39 / 221
Setting up notifications of the final result of a deferred payment
This notification is required to communicate the result of a deferred payment:
• if the payment has been accepted.
• if the payment has been declined.
It allows for the merchant website to be notified of an authorization request.
Example:
For a deferred payment with a capture delay of 60 days, the authorization request is not made at the
moment of the payment. The merchant website will be contacted at the moment of the authorization
request via the Instant Payment Notification URL on batch authorization rule.
This rule is disabled by default.

To set up this notification:

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

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 inPRODUCTION
mode.

Figure 13: Setting up a notification on batch authorization

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 (up
to 4 times).

7. Save the modifications.

8. Enable the rule by right-clicking on Instant Payment Notification URL on batch authorization and
select Enable the rule.

Hosted Payment Page - Document version 3.21

All rights reserved - 40 / 221
• Instructions to resend from the Merchant Back Office the notification to the URL already specified
above.

Setting up notifications in case of abandoned or canceled payments

The payment gateway can systematically notify the merchant website:
• When the buyer abandons/cancels a payment - via the Cancel and return to shop button.
• When the buyer has not completed the payment and the payment session has expired.
The maximum length of a payment session is 10 minutes.

To set up this notification:

1. Right-click Instant Payment Notification URL on cancellation.

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 PRODUCTION
mode.

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 (up
to 4 times).

7. Save the modifications.

Hosted Payment Page - Document version 3.21

All rights reserved - 41 / 221
Setting up a notification on batch change
The payment gateway can systematically notify the merchant website when a transaction with a To be
validated status expires. The expiry triggers the notification. The Expired status is final.
It is recommended to enable this notification for PayPal transactions (Order mode) in order to be notified
about the capture.
This rule is disabled by default.
To set up this notification:
1. Right-click Instant Payment Notification URL on batch change.

2. Select Manage the rule.

3. Enter the URL of your page into URL to notify in TEST mode and URL to notify in PRODUCTION
mode.

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 (up
to 4 times).

7. Save the modifications.

8. Enable the rule by right-clicking on Instant Payment Notification URL on batch change and select
Enable the rule.

Hosted Payment Page - Document version 3.21

All rights reserved - 42 / 221
7.5. Activating the automatic retry
This option allows to automatically send notifications to the merchant website in case of failure (up to 4
times).
A notification will be considered in failure if the HTTP return code returned by the merchant server is not
in 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.

3. Select Manage the rule.

Figure 14: Instant Payment Notification URL at the end of payment

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.

Call attempts are programmed at fixed intervals every 15 minutes (00, 15, 30, 45). After each failed
attempt, 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 notification
retry 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. réf. 067925 / FAILURE during the call to your IPN URL
[unsuccessful attempt #1]

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

[MODE TEST] My Shop - Tr. réf. 067925 / FAILURE during the call to your IPN URL
[unsuccessful attempt #2]

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

[MODE TEST] My Shop - Tr. réf. 067925 / FAILURE during the call to your IPN URL
[unsuccessful attempt #3]

Hosted Payment Page - Document version 3.21

All rights reserved - 43 / 221
To notify the merchant website of the last notification attempt, the e-mail subject will contain the
mention attempt #last.
Example of an e-mail subject following the last failure: :
[MODE TEST] My Shop - Tr. réf. 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 step
4.
Note:
After the fourth attempt, it is still possible to retry the IPN URL manually via the Merchant Back
Office..
Warning, during the automatic retry, any manual call to the IPN URL will affect the number of
automatic attempts:
• a successful manual call will stop automatic retry
• a failed manual call will have no impact on the current automatic retry.

7. Save the modifications.

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

Examples of fields that are unavailable / not stored 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 moment
when the URL is called.
• vads_hash populated differently with regard to the new values.
• signature populated differently with regard to the new values.

Hosted Payment Page - Document version 3.21

All rights reserved - 44 / 221
7.6. Manual notification retry
This option allows to manually retry the Instant Payment notification from the Merchant Back Office when
a transaction is in error.
1. Via the Merchant Back Office, search the transaction for which you wish to resend the notification.

2. Right-click on the transaction and select Send the Instant Payment Notification.
If your application becomes available once again, you will see a message confirming that the URL has
been successfully executed
You can, in any case, view the result of your action in the event history of the transaction and possibly
analyze error messages if the problem persists.

When the retry is done manually from the Merchant Back Office, some information may be not stored in
the database or are changes.

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 BO.
• vads_trans_status. The transaction status following this operation may be different depending on its
status at the moment when the URL is called (see chapter Transaction lifecycle
• vads_hash with a different value.
• signature with a different value.

Hosted Payment Page - Document version 3.21

All rights reserved - 45 / 221
7.7. 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:
• Recurring payment confirmation e-mail.
• Payment confirmation email.
• Token creation and/or update confirmation e-mail.

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 merchant 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 the
merchants using the payment gateway.
b. Select the tab corresponding to the language that you wish to customize.
c. Click on Customize some 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 request
processing 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 a
variable 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.

Hosted Payment Page - Document version 3.21

All rights reserved - 46 / 221
7.8. Configuring e-mails sent to the merchant
By default, the payment gateway can notify the merchant in the following cases:
• Payment confirmation e-mail
• Deferred payment rejection e-mail
• Buyer registration confirmation e-mail
• Installment rejection e-mail
• Recurring payment confirmation e-mail
• Production key regeneration e-mail

To configure these e-mails:

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

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

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 General Settings to specify the e-mail address to notify
b. Click on Buyer e-mail settings to view the "default text" of the e-mail.
c. Select the tab corresponding to the language of the e-mail that you wish to customize.
d. Click on Customize some default text values.
e. Modify the text of the e-mail.
f. Click on Fields to include to display the list of fields available for e-mail customization.
g. Select the fields that you wish to include into the e-mail. A detailed summary of the request
processing will be added to the contents of the e-mail.
Note:
To preview the applied changes, click on Preview the e-mail at the bottom of the dialog box.

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

8. Click Save.

Hosted Payment Page - Document version 3.21

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

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 form
data.

Form data:
• The shop ID.
• Information about the payment depending on the use case (see the chapters below).
• Additional information, depending on your requirements (see Using additional functionalities).
• Signature that certifies the integrity of the form (see Computing the signature).

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

For setting the name and value attributes, see chapter Data dictionary.

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 payment
gateway. Otherwise, the signature will not be computed correctly and the form will be rejected.

The Payer button that will allow to send data:

Hosted Payment Page - Document version 3.21

All rights reserved - 48 / 221
Different use cases are presented in the chapters below. They will allow you to adapt your payment form
to your needs.
The fields required to implement these use cases are presented in tables that indicates required format
(see the codification below).
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 Length fixed to 3 characters
..12 Variable length up to 12 characters
json JavaScript Object Notation.
Object that 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 a
value.
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 given in the field definition.
Example: vads_theme_config=SIMPLIFIED_DISPLAY=true;RESPONSIVE_MODEL=Model_1

Hosted Payment Page - Document version 3.21

All rights reserved - 49 / 221
8.1. Creating an immediate payment
In the immediate payment mode the buyer pays the total amount for the purchase at once.
The payment is captured by the bank on the same day.
1. Use all the fields presented in the table below to create your payment form.
Field name Description Format Value
vads_site_id Shop ID n8 E.g.: 12345678
vads_ctx_mode Defines the mode of interaction TEST or PRODUCTION
enum
with the payment gateway.
vads_trans_id Transaction number n6 E.g.: 123456
vads_trans_date Date and time of the payment E.g.: 20170701130025
n14
form in UTC format
vads_amount Payment amount in the smallest E.g.: 3000 for 30,00 EUR
n..12
currency unit (cents for euro).
vads_currency Numeric currency code to E.g.: 978 for euro (EUR)
be used for the payment, in
n3
compliance with the ISO 4217
standard (numeric code).
vads_action_mode Card data acquisition mode enum INTERACTIVE
vads_page_action Action to perform enum PAYMENT
vads_version Version of the exchange V2
protocol with the payment enum
gateway
vads_payment_config Payment type enum SINGLE
vads_capture_delay Capture delay n..3 0
vads_validation_mode Validation mode n1 0 (Automatic)
Table 5: Field list - Immediate payment

2. Set the vads_payment_config field to SINGLE.

3. Set the vads_capture_delay field to 0.

4. Set the vads_validation_mode field to 0 for automatic validation (the payment will be automatically
captured by the bank).

5. Fill in the vads_currency field with the code of the desired currency using the currency table (E.g.:
978 for euro (EUR)).

6. Add optional fields depending on your requirements (see chapter Using additional features).

7. Compute the value of the signature field using all the fields of your form that start with vads_ (see
chapter Computing the signature ).

Hosted Payment Page - Document version 3.21

All rights reserved - 50 / 221
Example of a form for an immediate payment:
<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="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="20140526101407" />
<input type="hidden" name="vads_trans_id" value="239848" />
<input type="hidden" name="vads_version" value="V2" />
<input type="hidden" name="signature" value="0WaYrONo3L0VZqMcvyVf8vT/g8KfZKJ+1jqiAs3Ehiw="/>
<input type="submit" name="pay" value="Pay"/>
</form>

Hosted Payment Page - Document version 3.21

All rights reserved - 51 / 221
8.2. Creating a deferred payment
A deferred payment is a payment debited all at once with a capture delay that is strictly greater than 0
days.
An information request will be made if the capture delay is greater than the validity period of an
authorization request (see table).
The information request is done in order to to check the card validity. For acquirers who do not support
information request, an authorization request for 1 EUR will be made (see table).
1. Use all the fields presented in the table below to create your payment form.
Field name Description Format Value
vads_site_id Shop ID n8 E.g.: 12345678
vads_ctx_mode Defines the mode of interaction TEST or PRODUCTION
enum
with the payment gateway.
vads_trans_id Transaction number n6 E.g.: 123456
vads_trans_date Date and time of the payment E.g.: 20170701130025
n14
form in UTC format
vads_amount Payment amount in the smallest E.g.: 3000 for 30,00 EUR
n..12
currency unit (cents for euro).
vads_currency Numeric currency code to E.g.: 978 for euro (EUR)
be used for the payment, in
n3
compliance with the ISO 4217
standard (numeric code).
vads_action_mode Card data acquisition mode enum INTERACTIVE
vads_page_action Action to perform enum PAYMENT
vads_version Version of the exchange V2
protocol with the payment enum
gateway
vads_payment_config Payment type enum SINGLE
vads_capture_delay Delay before capture in the E.g.: 3
bank, the value must be greater n..3
than 0
vads_validation_mode Specifies the validation mode of 0 or 1 or absent or empty
the transaction (manually by the
n1
merchant, or automatically by
the payment gateway).
Table 6: Field list - Deferred payment

2. Set the vads_payment_config field to SINGLE.

3. Set the vads_capture_delay field to greater than 0.

4. Set the vads_validation_mode field to 0 for an automatic validation (the payment will be
automatically captured by the bank) or to 1 for a manual validation (the payment will be captured by
the bank after a manual validation in the Merchant Back Office).

5. Fill in the vads_currency field with the code of the desired currency using the currency table (E.g.:
978 for euro (EUR)

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

7. Compute the value of the signature field using all the fields of your form starting with vads_ (see
chapter Computing the signature).

Example of a form for a deferred payment:

Hosted Payment Page - Document version 3.21

All rights reserved - 52 / 221
<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="3" />
<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="20140129130025" />
<input type="hidden" name="vads_trans_id" value="130025" />
<input type="hidden" name="vads_version" value="V2" />
<input type="hidden" name="signature" value="NrHSHyBBBc+TtcauudspNHQ5cYcy4tS4IjvdC0ztFe8="/>
<input type="submit" name="pay" value="Pay"/>
</form>

Hosted Payment Page - Document version 3.21

All rights reserved - 53 / 221
8.3. Creating an installment payment
This payment mode allows the merchant to make the payment process easier for the buyer.
The payment form defines the number of installments and the interval between them
The first installment is similar to the immediate payment.
The next installment is similar to a deferred payment.
Reminder :
Notifications rules have to be activated according the installment See chapter Setting up notifications for
more information.
Precisions:
On the payment day, the merchant is not credited with the total amount and the payment guarantee
cannot apply to the future installments.
The date of the last installment cannot be later than one year after the date of the submission of the form.
If it is, an error message will appear and the form will be rejected.
1. Use all the fields below to create your payment form.
Field name Description Format Value
vads_site_id Shop ID n8 E.g.: 12345678
vads_ctx_mode Defines the mode of interaction TEST or PRODUCTION
enum
with the payment gateway.
vads_trans_id Transaction number n6 E.g.: 123456
vads_trans_date Date and time of the payment E.g.: 20170701130025
n14
form in UTC format
vads_amount Payment amount in the smallest E.g.: 3000 for 30,00 EUR
n..12
currency unit (cents for euro).
vads_currency Numeric currency code to E.g.: 978 for euro (EUR)
be used for the payment, in
n3
compliance with the ISO 4217
standard (numeric code).
vads_action_mode Card data acquisition mode enum INTERACTIVE
vads_page_action Action to perform enum PAYMENT
vads_version Version of the exchange V2
protocol with the payment enum
gateway
vads_payment_config Payment type enum see step 2.
vads_capture_delay Capture delay n..3 0
vads_validation_mode Specifies the validation mode of 0 or 1 or absent or empty
the transaction (manually by the
n1
merchant, or automatically by
the payment gateway).
Table 7: Field list - Installment payment

2. Set the value of the vads_payment_config field using the following syntax:
• Fixed payment amounts and dates :
MULTI:first=1000;count=3;period=30 where:
"first" is the amount (in the smallest currency unit) of the first installment processed on the day of
payment,
"count" is the total number of installments,
"period" defines the period (in days) between each installment.
• Customized payment amounts and dates :

Hosted Payment Page - Document version 3.21

All rights reserved - 54 / 221
MULTI_EXT:date1=amount1;date2=amount2;date3=amount3 where:
date1=amount1 defines the date and the amount of the first installment.
The amounts are presented in the smallest currency unit. The total amount must be equal to the
value of the vads_amount field.
The dates are presented in the YYYYMMDD format.

3. Set the vads_capture_delay field to 0. The first payment will be captured by the bank on the same
day.

4. Set vads_validation_mode to 0 for an automatic validation (the payment will be automatically

captured by the bank) or to 1 for a manual validation (manual operation made from the Merchant
Back Office).
The validation mode is applied to each installment payment.

5. Fill in the vads_currency field with the code of the desired currency using the currency table (E.g.:
978 for euro (EUR)).

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

7. Compute the value of the signature field using all the fields of your form starting with vads_ (see
chapter Computing the signature)

Example of a payment form for an installment payment (fixed amounts and payment dates):
<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_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="MULTI:first=1000;count=3;period=30"/>
<input type="hidden" name="vads_site_id" value="12345678" />
<input type="hidden" name="vads_trans_date" value="20140129180150" />
<input type="hidden" name="vads_trans_id" value="180150" />
<input type="hidden" name="vads_version" value="V2" />
<input type="hidden" name="signature" value= "zrhUNkAciZSEl6mS4BbhV3qkYUBB9RYJQCdg1kU0ELU="/>
<input type="submit" name="pay" value="Pay" />
</form>

Example of a payment form for an installment payment (customized amounts and payment dates):
<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="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="
MULTI_EXT:20140201=1000;20140301=1000;20140401=1000" />
<input type="hidden" name="vads_site_id" value="12345678" />
<input type="hidden" name="vads_trans_date" value="20140129130025" />
<input type="hidden" name="vads_trans_id" value="130025" />
<input type="hidden" name="vads_version" value="V2" />
<input type="hidden" name="signature" value="7Sds6Z+R1Q1axRsblpChyQh5OU3oCle5FOirD4V/Bzk="/>
<input type="submit" name="pay" value="Pay"/>
</form>

Hosted Payment Page - Document version 3.21

All rights reserved - 55 / 221
8.4. Creating an authorization without capture
This payment mode allows to verify that the buyer's card data is correct without debiting it.
If needed, the merchant will be able to debit the card with the desired amount by using the Duplicate
function of the Merchant Back Office To do this:
• the manual validation mode must be used,
• the merchant must not validate transactions manually.
1. Use all the fields of the table below to create your payment form.
Field name Description Format Value
vads_site_id Shop ID n8 E.g.: 12345678
vads_ctx_mode Defines the mode of interaction TEST or PRODUCTION
enum
with the payment gateway.
vads_trans_id Transaction number n6 E.g.: 123456
vads_trans_date Date and time of the payment E.g.: 20170701130025
n14
form in UTC format
vads_amount Payment amount in the smallest E.g.: 3000 for 30,00 EUR
n..12
currency unit (cents for euro).
vads_currency Numeric currency code to E.g.: 978 for euro (EUR)
be used for the payment, in
n3
compliance with the ISO 4217
standard (numeric code).
vads_action_mode Card data acquisition mode enum INTERACTIVE
vads_page_action Action to perform enum PAYMENT
vads_version Version of the exchange V2
protocol with the payment enum
gateway
vads_payment_config Payment type enum SINGLE
vads_capture_delay Capture delay n..3 0
vads_validation_mode Validation mode n1 1 (Manual)
Table 8: Field list - Authorization without a capture

2. Set the value of the vads_amount field to a small amount. It will not affect the authorization limit of
the card.

3. Set the vads_validation_mode field to 1.

4. Fill in the vads_currency field with the code of the desired currency using the currency table (E.g.:
978 for euro (EUR)).

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

6. Compute the value of the signature field using all the fields of your form that start with vads_ (see
chapter Computing the signature).

Hosted Payment Page - Document version 3.21

All rights reserved - 56 / 221
Example of a payment form for an authorization without a capture:
<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="100" />
<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_page_action" value="PAYMENT" />
<input type="hidden" name="vads_validation_mode" value="1"/>
<input type="hidden" name="vads_site_id" value="12345678" />
<input type="hidden" name="vads_trans_date" value="20141008073753" />
<input type="hidden" name="vads_trans_id" value="346738" />
<input type="hidden" name="vads_version" value="V2" />
<input type="hidden" name="signature" value= "DvltInRYXRroOZ/KnNdJSlpVr++29ZGty4nj1Y7yczU="/>
<input type="submit" name="pay" value="Pay" />
</form>

Hosted Payment Page - Document version 3.21

To obtain a custom form adapted to your needs, you can use additional optional features from the list
below:
• Configure the capture mode (validation mode)
• Transmit buyer details (title/civil status, e-mail address, etc.)
• Transmit shipping details (address, etc.)
• Transmit order details (reference, shopping cart contents, etc.)
• Enable or disabling 3D Secure
• Define the Merchant ID (MID) to use for the payment
• Override the instant payment notification (IPN)
• Manage the URLs to return to the merchant website
• Enable an automatic return to the merchant website at the end of payment

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

Hosted Payment Page - Document version 3.21

All rights reserved - 58 / 221
9.1. Managing the return to the merchant website
At the end of payment, the buyer has the possibility to return to the merchant website via a return URL.
This URL is called Return URL.
It is not to be confused with Instant notification URL (IPN) (see chapter Managing the interaction with
the merchant website).

Defining the Return URLs

In the payment form, the merchant can override the configuration of the Merchant Back Office. To do so,
the merchant can:
• Use 4 different URLs depending on the payment result:
• Payment accepted
• Payment declined
• Payment abandoned
• Payment error
• Or use one single URL independently of the payment result.

Defining the return URLs depending on the payment result

1. Use the fields required for your use case (see chapter Generating a payment form) to create your
payment form.

2. Use the optional fields presented in the table below to create a customized payment form.
If no URL is specified in the form, the value populated in the Merchant Back Office will be used.
Field name Description Format Value
vads_url_cancel URL to which the buyer will be redirected upon E.g.: http://demo.com/cancel.php
clicking on "Cancel and return to shop" before ans..1024
proceeding to payment
vads_url_error URL to which the buyer will be redirected in E.g.: http://demo.com/error.php
case of a processing error on the payment ans..1024
gateway
vads_url_refused URL to which the buyer will be redirected in E.g.: http://demo.com/refused.php
case of a declined payment after having clicked ans..1024
son "Return to shop"
vads_url_success URL to which the buyer will be redirected in E.g.: http://demo.com/success.php
case of an accepted payment after having ans..1024
clicked on "Return to shop"

3. Compute the value of the signature field using all the fields of your form starting withvads_ (see
chapter Computing the signature).

Hosted Payment Page - Document version 3.21

All rights reserved - 59 / 221
Example of a payment form with configuration of a return URL depending on the payment result:
<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_site_id" value="12345678" />
<input type="hidden" name="vads_trans_date" value="20140526101407" />
<input type="hidden" name="vads_trans_id" value="239848" />
<input type="hidden" name="vads_url_cancel" value="http://demo.com/cancel.php" />
<input type="hidden" name="vads_url_error" value="http://demo.com/error.php" />
<input type="hidden" name="vads_url_refused" value="http://demo.com/refused.php" />
<input type="hidden" name="vads_url_success" value="http://demo.com/success.php" />
<input type="hidden" name="vads_version" value="V2" />
<input type="hidden" name="signature" value="lZIHzigiwCc6+uLStp8I5DQnbSqXu63Jtfo6Saeq3Mc="/>
<input type="submit" name="pay" value="Pay"/>
</form>

Setting up a unique return URL regardless of the payment outcome

1. Use the fields required for your use case (see chapter Generating a payment form) to create your
payment form.

2. Use the optional field vads_url_return to set up an redirection URL at the end of payment.
If no URL is specified in the form, the value populated in the Merchant Back Office will be used.

3. Compute the value of the signature field using all the fields of your form starting withvads_ (see
chapter Computing the signature).

Example of a payment form with a unique return URL regardless of the payment result:
<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_site_id" value="12345678" />
<input type="hidden" name="vads_trans_date" value="20140526101407" />
<input type="hidden" name="vads_trans_id" value="239848" />
<input type="hidden" name="vads_url_return" value="http://demo.com/return.php" />
<input type="hidden" name="vads_version" value="V2" />
<input type="hidden" name="signature" value="yXvSZnYvcMRORVGiapWaHT0euKDI0OGlrddYKc4XDZc="/>
<input type="submit" name="pay" value="Pay"/>
</form>

Hosted Payment Page - Document version 3.21

All rights reserved - 60 / 221
Defining the method for receiving data
For statistical purposes or to display customized pages, the merchant site must be able to analyze certain
data transmitted to the buyer's browser.
By default, the payment gateway does not transmit any data when redirecting to the return URL.
However, the merchant website may activate the sending of data to the return URL via the payment form.

1. Use the fields required for your use case (see chapter Generating a payment form) to create your
payment form.

2. Use the optional field vads_return_mode to specify the method for submitting data to the merchant
website.
Value Description
Absent, empty or NONE No data is transmitted.
GET The information are transmitted in the URL of the return page.
POST The information is transmitted via an HTTP in POST.

The GET method allows to keep a notification message from appearing when the return is done from
an insecure environment (http).

3. Compute the value of the signature field using all the fields of your form starting with vads_ (see
chapter Computing the signature).

Example of a payment form with definition of the mode for data transmission:
<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_return_mode" value="GET" />
<input type="hidden" name="vads_site_id" value="12345678" />
<input type="hidden" name="vads_trans_date" value="20140526101407" />
<input type="hidden" name="vads_trans_id" value="239848" />
<input type="hidden" name="vads_url_return" value="http://demo.com/return.php" />
<input type="hidden" name="vads_version" value="V2" />
<input type="hidden" name="signature" value="oTCT+7Oc+xttdGmcp9qa6/0pSSfNxoMtl8U1J1l+LtE="/>
<input type="submit" name="pay" value="Pay"/>
</form>

Hosted Payment Page - Document version 3.21

All rights reserved - 61 / 221
9.2. Enabling an automatic return to the merchant website
In the payment form, the merchant can indicate if he/she wishes to automatically redirect the buyer to
the merchant website at the end of payment.
If you use a tracking code (Google AnalyticsTM or other) on your website, you must implement this
function.
1. Use the fields required for your use case (see chapter Generating a payment form) to create your
payment form.

2. Use optional fields according to your requirements.

Field name Description
vads_redirect_success_timeout Defines the delay before the redirection that follows an accepted payment.
This delay is presented in seconds and must be between 0 and 300 sec.
vads_redirect_success_message Defines the message that appears before the redirection that follows a
successful payment.
vads_redirect_error_timeout Defines the delay before the redirection that follows a declined payment.
This delay is presented in seconds and must be between 0 and 300 sec.
vads_redirect_error_message Defines the message that appears before the redirection that follows a
declined payment.
Table 9: List of available optional fields

Note
If you choose a timeout to zero (= 0 delay) your redirection will be done as follows:
• For an accepted payment, the buyer will be redirected on vads_url_success
• For a canceled payment, the buyer will be redirected on vads_url_cancel if this parameter is defined,
• If the parameter is not filled in, the buyer will be redirected to the return URL entered in the
vads_url_return field or to the return URL entered in the Merchant Back Office.
• If the return URL is not set, it will be redirected to the merchant website.
• For a declined payment, the buyer will be redirected to vads_url_refused if the setting is set.
• If the parameter is not filled in, the buyer will be redirected to the return URL entered in the
vads_url_return field or to the return URL entered in the Merchant Back Office.
• If the return URL is not set, it will be redirected to the merchant website.

3. Set thevads_return_mode field toGET .

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

Hosted Payment Page - Document version 3.21

All rights reserved - 62 / 221
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_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_redirect_error_message" value="You will be redirected to your
merchant website" />
<input type="hidden" name="vads_redirect_error_timeout" value="0" />
<input type="hidden" name="vads_redirect_success_message" value="You will be redirected to your
merchant website" />
<input type="hidden" name="vads_redirect_success_timeout" value="0" />
<input type="hidden" name="vads_return_mode" value="GET" />
<input type="hidden" name="vads_site_id" value="12345678" />
<input type="hidden" name="vads_trans_date" value="20140526101407" />
<input type="hidden" name="vads_trans_id" value="239848" />
<input type="hidden" name="vads_url_return" value="http://demo.com/return.php" />
<input type="hidden" name="vads_version" value="V2" />
<input type="hidden" name="signature" value="AzTJmizS5N0muYzu63nVvCUWo0ixnMJfpqQmuEa4CSY="/>
<input type="submit" name="pay" value="Pay"/>
</form>

Hosted Payment Page - Document version 3.21

All rights reserved - 63 / 221
9.3. Defining the capture mode (automatic/manual)
In the Merchant Back Office, the merchant can configure the way of sending the payments to the bank
(Settings > Shop menu > Configuration tab):

Figure 15: Defining the capture mode

• Automatic: no action is necessary, the payments are captured by the bank once the capture delay is
elapsed.
• Manual: the merchant must validate each payment from the Merchant Back Office to enable the
capture before the desired capture date.

Each transaction that has not been validated by the expected date is considered as expired and will
never be captured by the bank.
By default, the Merchant Back Office is configured to capture all payments automatically.

The merchant can override this configuration in the payment form.

The merchant must implement the desired criteria (stock status, delay for stock replenishment, etc.)
allowing the buyer to decide whether the transaction must be captured automatically or not.
1. Use the fields required for your use case (see chapter Generating a payment form) to create your
payment form.

2. Use the vads_validation_mode field to configure the capture mode (manual or automatic).
This field will be resent with the response and will include the value transmitted in the form.
Value Description
Absent or empty Takes the value specified in the Merchant Back Office.
0 Automatic capture.
1 Manual capture.
Table 10: Values associated with the vads_validation_mode field

3. Compute the value of the signature field using all the fields of your form starting with vads_ (see
chapter Computing the signature).

Hosted Payment Page - Document version 3.21

All rights reserved - 64 / 221
Example of a payment form with a definition of the capture mode in SILENT mode:
<form method="POST" action="https://secure.payzen.eu/vads-payment/">
<input type="hidden" name="vads_action_mode" value="SILENT" />
<input type="hidden" name="vads_amount" value="4000" />
<input type="hidden" name="vads_capture_delay" value="0" />
<input type="hidden" name="vads_card_number" value="4970100000000000" />
<input type="hidden" name="vads_ctx_mode" value="TEST" />
<input type="hidden" name="vads_currency" value="978" />
<input type="hidden" name="vads_cvv" value="123" />
<input type="hidden" name="vads_expiry_month" value="5" />
<input type="hidden" name="vads_expiry_year" value="2017" />
<input type="hidden" name="vads_page_action" value="PAYMENT" />
<input type="hidden" name="vads_payment_config" value="SINGLE" />
<input type="hidden" name="vads_payment_cards" value="VISA" />
<input type="hidden" name="vads_site_id" value="12345678" />
<input type="hidden" name="vads_trans_date" value="20140326164147" />
<input type="hidden" name="vads_trans_id" value="164147" />
<input type="hidden" name="vads_version" value="V2" />
<input type="hidden" name="vads_validation_mode" value="1" />
<input type="hidden" name="signature" value="8oUTs2G8kjWnTmuccMobDyAISCSdM4WbxQTp9kchHwM= />
<input type="submit" name="pay" value="Pay"/>
</form>

Example of a payment form with a definition of the capture mode in INTERACTIVE mode:
<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="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="20140326164147" />
<input type="hidden" name="vads_trans_id" value="164147" />
<input type="hidden" name="vads_version" value="V2" />
<input type="hidden" name="vads_validation_mode" value="1" />
<input type="hidden" name="signature" value="cJFhNTLXQ4o6BgbW1pMMoM2yMilw90OIqmFjJ6DeUmA= />
<input type="submit" name="pay" value="Pay"/>
</form>

Note:
Required fields are different according to the capture mode (SILENT or INTERACTIVE).
When vads_action_mode field is set to SILENT, payment method details are mandatory.

Hosted Payment Page - Document version 3.21

All rights reserved - 65 / 221
9.4. Transmitting buyer details
The merchant can specify the buyer's billing details (e-mail address, title, phone number, etc.). This
information will be used to create the invoice.

All the data transmitted via the payment form can be viewed in the transaction details in the Merchant
Back Office (Buyer tab).
1. Use the fields required for your use case (see chapter Generating a payment form) to create your
payment form.

2. Use optional fields according to your requirements. These fields will be returned with the response
and will include the value transmitted in the form.
Field name Description Format Value
vads_cust_email Buyer's e-mail address ans..150 E.g.: [email protected]
vads_cust_id Buyer reference on the E.g.: C2383333540
an..63
merchant website
vads_cust_title Buyer's title an..63 E.g.: Mr.
vads_cust_status Status PRIVATE: for a private individual
enum
COMPANY: for a company
vads_cust_first_name First name ans..63 E.g.: Laurent
vads_cust_last_name Name ans..63 E.g.: Durant
vads_cust_legal_name Buyer's legal name an..100 E.g.: D. & Cie
vads_cust_cell_phone Cell phone number an..32 E.g.: 06 12 34 56 78
vads_cust_address_number Street number ans..64 E.g.: 109
vads_cust_address Postal address ans..255 E.g.: Rue de l'innovation
vads_cust_address2 Second line of the address ans..255 E.g.:
vads_cust_district District ans..127 E.g.: Downtown
vads_cust_zip Zip code an..64 E.g.: 31670
vads_cust_city City an..128 E.g.: Labège
vads_cust_state State / Region ans..127 E.g.: Occitanie
vads_cust_country Country code in compliance with E.g.: "FR" for France, "PF" for French
the ISO 3166 standard a2 Polynesia, "NC" for New Caledonia,
"US" for the United States

3. Compute the value of the signature field using all the fields of your form that start with vads_ (see
chapter Computing the signature).

Hosted Payment Page - Document version 3.21

All rights reserved - 66 / 221
9.5. Transmitting shipping details
The merchant can transmit the buyer's shipping details (e-mail address, title, phone number, etc.).
This information can be found in the transaction details in the Merchant Back Office (Shipping tab).
1. Use the fields required for your use case (see chapter Generating a payment form) to create your
payment form.

2. Use optional fields according to your requirements.

These fields will be returned with the response and will include the value transmitted in the form.
Field name Description Format Value
vads_ship_to_city City an..128 E.g.: Bordeaux
vads_ship_to_country Country code in compliance with E.g.: FR
a2
the ISO 3166 standard.
vads_ship_to_district District ans..127 E.g.: La Bastide
vads_ship_to_first_name First name ans..63 E.g.: Albert
vads_ship_to_last_name Name ans..63 E.g.: Durant
vads_ship_to_legal_name Legal name an..100 E.g.: D. & Cie
vads_ship_to_phone_num Phone number ans..32 E.g.: 0460030288
vads_ship_to_state State / Region ans..127 E.g.: Nouvelle aquitaine
vads_ship_to_status Allows to specify the type of the PRIVATE: for shipping to a private
shipping address. individual
enum
COMPANY: for shipping to a
company
vads_ship_to_street_number Street number ans..64 E.g.: 2
vads_ship_to_street Postal address ans..255 E.g.: Rue Sainte Catherine
vads_ship_to_street2 Second line of the address ans..255
vads_ship_to_zip Zip code an..64 E.g.: 33000
Table 11: Field list - Shipping details

3. Compute the value of the signature field using all the fields of your form that start with vads_ (see
chapter Computing the signature).

Hosted Payment Page - Document version 3.21

All rights reserved - 67 / 221
Example of the payment form with shipping details
<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_page_action" value="PAYMENT" />
<input type="hidden" name="vads_payment_config" value="SINGLE" />
<input type="hidden" name="vads_ship_to_city" value="shipping city" />
<input type="hidden" name="vads_ship_to_country" value="FR" />
<input type="hidden" name="vads_ship_to_name" value="the name of the shipping place" />
<input type="hidden" name="vads_ship_to_street" value="lshipping street" />
<input type="hidden" name="vads_ship_to_street_number" value="10" />
<input type="hidden" name="vads_ship_to_zip" value="31670" />
<input type="hidden" name="vads_site_id" value="12345678" />
<input type="hidden" name="vads_trans_date" value="20140327143509" />
<input type="hidden" name="vads_trans_id" value="561095" />
<input type="hidden" name="vads_version" value="V2" />
<input type="hidden" name="signature" value="bOIxHAgm4vYUq3oIDCdEPKOWgrB9bHzkfDBEAr1i10A="/>
<input type="submit" name="pay" value="Pay"/>
</form>

Hosted Payment Page - Document version 3.21

All rights reserved - 68 / 221
9.6. Transmitting order details
The merchant can transmit the order details (order reference, description, shopping cart contents, etc.).
This information can be found in the transaction details in the Merchant Back Office.
1. Use the fields required for your use case (see chapter Generating a payment form) to create your
payment form.

2. Use optional fields according to your requirements. These fields will be returned with the response
and will include the value transmitted in the form.
Field name Description Format Value
vads_order_id Order ID ans..64 E.g.: 2-XQ001
vads_order_info Additional order info an..255 E.g.: Door phone code 3125
vads_order_info2 Additional order info an..255 E.g.: No elevator
vads_order_info3 Additional order info an..255 E.g.: Express
vads_nb_products Number of items in the cart n..12 E.g.: 2
vads_product_ext_idN Product barcode in the E.g.:
merchant's website. N vads_product_ext_id0 =
corresponds to the index of the "0123654789123654789"
item (0 for the first one, 1 for an..100 vads_product_ext_id1 =
the second one, etc.). "0223654789123654789"
vads_product_ext_id2 =
"0323654789123654789"
vads_product_labelN Item name. N corresponds to E.g.:
the index of the item (0 for the vads_product_label0 = "tee-shirt"
first one, 1 for the second one, an..255
vads_product_label1 = "Biscuit"
etc.). vads_product_label2 = "sandwich"
vads_product_amountN Item amount. N corresponds to E.g.:
the index of the item (0 for the vads_product_amount0 = "1200"
first one, 1 for the second one, n..12
vads_product_amount1 = "800"
etc.). vads_product_amount2 = "950"
vads_product_typeN Item type. N corresponds to the E.g.:
index of the item (0 for the first vads_product_type0 =
one, 1 for the second one, etc.). "CLOTHING_AND_ACCESSORIES"
enum vads_product_type1 =
"FOOD_AND_GROCERY"
vads_product_type2 =
"FOOD_AND_GROCERY"
vads_product_refN Item reference. N corresponds E.g.:
to the index of the item (0 for vads_product_ref0 = "CAA-25-006"
the first one, 1 for the second an..64
vads_product_ref1 = "FAG-B5-112"
one, etc.). vads_product_ref2 = "FAG-S9-650"
vads_product_qtyN Quantity of items. N E.g.:
corresponds to the index of the vads_product_qty0 = "1"
item (0 for the first one, 1 for n..12
vads_product_qty1 = "2"
the second one, etc.). vads_product_qty2 = "2"
Table 12: Field list - Order details

3. Populate vads_nb_products with the number of items contained 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 transaction details 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 the vads_nb_products field, it becomes mandatory
to populate the other fields starting with vads_product_.

Hosted Payment Page - Document version 3.21

All rights reserved - 69 / 221
4. Populate vads_product_amountN with the amount of all the items in the cart in the smallest
currency unit.
N corresponds to the index of the item (0 for the first one, 1 for the second one, etc.).

5. Populate vads_product_typeN with the value corresponding to the item type.

N corresponds to the index of the item (0 for the first one, 1 for the second one, etc.).
Valeur Description
FOOD_AND_GROCERY Produits alimentaires et d'épicerie
AUTOMOTIVE Automobile / Moto
ENTERTAINMENT Divertissement / Culture
HOME_AND_GARDEN Maison et jardin
HOME_APPLIANCE Equipement de la maison
AUCTION_AND_GROUP_BUYING Ventes aux enchères et achats groupés
FLOWERS_AND_GIFTS Fleurs et cadeaux
COMPUTER_AND_SOFTWARE Ordinateurs et logiciels
HEALTH_AND_BEAUTY Santé et beauté
SERVICE_FOR_INDIVIDUAL Services à la personne
SERVICE_FOR_BUSINESS Services aux entreprises
SPORTS Sports
CLOTHING_AND_ACCESSORIES Vêtements et accessoires
TRAVEL Voyage
HOME_AUDIO_PHOTO_VIDEO Son, image et vidéo
TELEPHONY Téléphonie
Table 13: Valeurs associées à vads_product-type0

6. Populate vads_product_labelN with the name of each item contained in the cart.
N corresponds to the index of the item (0 for the first one, 1 for the second one, etc.).

7. Populate vads_product_qtyN with the quantity of each item contained in the cart.
N corresponds to the index of the item (0 for the first one, 1 for the second one, etc.).

8. Populate vads_product_refN with the reference of each item contained in the cart.
N corresponds to the index of the item (0 for the first one, 1 for the second one, etc.).

9. Verify the value of the vads_amount field. It must correspond to the total amount of the order.

10.Compute the value of the signature field using all the fields of your form that start with vads_ (see
chapter Computing the signature).

Hosted Payment Page - Document version 3.21

All rights reserved - 70 / 221
Example of the payment form with cart description:
<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="11000" />
<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_nb_products" value="2"/>
<input type="hidden" name="vads_product_amount0" value="5000" />
<input type="hidden" name="vads_product_label0" value="produit1" />
<input type="hidden" name="vads_product_qty0" value="2" />
<input type="hidden" name="vads_product_ref0" value="ref1" />
<input type="hidden" name="vads_product_amount1" value="1000" />
<input type="hidden" name="vads_product_label1" value="produit2" />
<input type="hidden" name="vads_product_qty1" value="1" />
<input type="hidden" name="vads_product_ref1" value="ref2" />
<input type="hidden" name="vads_order_id" value="CD100000857" />
<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="20140327145218" />
<input type="hidden" name="vads_trans_id" value="571381" />
<input type="hidden" name="vads_version" value="V2" />
<input type="hidden" name="signature" value="xYw1UnU3BACGhf3UEyqbQzpwuvZDEkCAWAE5fgbtfxI="/>
<input type="submit" name="pay" value="Pay"/></form>

Hosted Payment Page - Document version 3.21

All rights reserved - 71 / 221
9.7. Enabling / disabling 3D Secure
A subscription to Selective 3D Secure option is required for this feature.
In the payment form, the merchant can indicate if he/she wishes to enable or disable the 3D Secure or
Safekey authentication.
The merchant will have to implement the criteria of his or her choice (amount, country, shipping area, etc.)
which will allow to determine if the transaction must be subject to 3DS or not.

1. Use the fields required for your use case (see chapter Generating a payment form) to create your
payment form.

2. Use the vads_threeds_mpi field to enable or disable 3D Secure.

Value Description
Absent 3DS authentication managed by the payment gateway (configuration by the merchant).
or empty
0 3DS authentication managed by the payment gateway (configuration by the merchant).
1 3DS authentication completely managed by the merchant on the condition that the vads_card_number field is
populated (card data entered by the merchant).
In this case, the data produced by 3D Secure authentication initiated by the MPI must be submitted in
specific fields of the form (vads_threeds_enrolled, vads_threeds_cavv, vads_threeds_eci, vads_threeds_xid,
vads_threeds_cavvAlgorithm, vads_threeds_status).
2 3DS authentication disabled for the transaction independently of the usual configuration of the merchant.

3. Compute the value of the signature field using all the fields of your form starting with vads_ (see
chapter Computing the signature).

Example of enabling 3DS depending on the amount:

if (vads_amount < 75,90 EUR){
then vads_threeds_mpi = 2 // 3DS disabled
else vads_threeds_mpi = 0 // 3DS enabled
}

Example of enabling 3DS depending on the department:

if (vads_cust_zip > 92000 ) and (vads_cust_zip < 95000 ){
then vads_threeds_mpi = 0 // 3DS enabled
else vads_threeds_mpi = 2 // 3DS disabled
}

Example of a payment form with disabled 3DS:

Hosted Payment Page - Document version 3.21

All rights reserved - 72 / 221
9.8. Overriding the IPN
You can override the Instant Payment Notification (also called IPN) in the payment form in case you use
one shop for various sales channels, payment types, languages, etc.

This function is not compatible with the execution of the request sent to the IPN from the Merchant Back
Office. The called URL is the URL that has been set up in the notification rule (see chapter Setting up
notifications).
1. Use the fields required for your use case (see chapter Generating a payment form) to create your
payment form.

2. Use the vads_url_check field to override the URL of the page to notify.
If the value of the vads_url_check field is wrong, the form will be rejected.

3. Compute the value of the signature field using all the fields of your form starting with vads_ (see
chapter Computing the signature).

Example of a payment form with IPN override:

Hosted Payment Page - Document version 3.21

All rights reserved - 73 / 221
9.9. Defining the Merchant ID (MID)
In the payment form, the merchant must specify the value of the Merchant ID (MID).
This function is used only if you have several MIDs that accept the same currency within the same
acceptance network.

1. Use the fields required for your use case (see chapter Generating a payment form) to create your
payment form.

2. Use the optional vads_contracts field to define the Merchant ID (MID).

Example:
Value Description
Absent or empty Using the MID respecting the priority order as specified in
the Merchant Back Office (Settings > Shop > Merchant ID).
CB=12312312 CB Network
POSTFINANCE=contrat_yp PostFinance network
AMEXGLOBALAMEX=949400444000 American Express network
[email protected] PayPal

To define several MID, separate them by a semi-colon ";".

To exclude a network, add network name=NO

3. Compute the value of the signature field using all the fields of your form starting with vads_ (see
chapter Computing the signature).

Example:
You have:
• two CB MID: 1231230 and 1231231
• two AMEXGLOBAL MID: 949400444000 and 949400444001
To specify which MID to use for these two schemes, vads_contracts must be populated as follows:
vads_contracts=CB=1231231; AMEXGLOBAL=949400444000
To propose a payment only within the 1231231 MID and not within one of the AMEXGLOBAL MID, the
values of vads_contracts will be:
vads_contracts=CB=1231231; AMEXGLOBAL=NO

Example of a payment form defining the Merchant ID (MID) used for the payment:
<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="TEST" />
<input type="hidden" name="vads_currency" value="" />
<input type="hidden" name="vads_contracts" value="CB=1231231;AMEXGLOBAL=949400444000 />
<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="20140327145218" />
<input type="hidden" name="vads_trans_id" value="571381" />
<input type="hidden" name="vads_version" value="V2" />
<input type="hidden" name="signature" value="7mjGsUAcl4Ox6p5WZ8RNN7ROsxlJ0py3SMtSzdfbHEM="/>
<input type="submit" name="pay" value="Pay"/>
</form>

Hosted Payment Page - Document version 3.21

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 your
merchant 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 in order to proceed to payment.

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

10.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 the
vads_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.

Hosted Payment Page - Document version 3.21

All rights reserved - 75 / 221
10.2. Managing the payment methods offered to the buyer
It is possible to customize the payment methods offered to the buyer.
1. Use the fields required for your use case (see chapter Generating a payment form) to create your
payment form.

2. 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.

3. Compute the value of the signature field using all the fields of your form that start with vads_ (see
chapter Computing the signature).

Example of a payment form with payment method selection:

Hosted Payment Page - Document version 3.21

All rights reserved - 76 / 221
10.3. Modifying the language
You can customize the language of the payment pages.
1. Use the fields required for your use case (see chapter Generating a payment form) to create your
payment form.

2. 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 the
buyer's browser
• The buyer will be able to change the language anytime by clicking on the flags at the bottom of
the payment page.

3. Compute the value of the signature field using all the fields of your form starting with vads_(see
chapter Computing the signature).

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

Hosted Payment Page - Document version 3.21

All rights reserved - 77 / 221
10.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.
1. Use the fields required for your use case (see chapter Generating a payment form) to create your
payment form.

2. 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.

3. Compute the value of the signature field using all the fields of your form starting with vads_(see
chapter Computing the signature).

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

Hosted Payment Page - Document version 3.21

All rights reserved - 78 / 221
10.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 domain
name visible.
1. Use the fields required for your use case (see chapter Generating a payment form) to create your
payment form.

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

3. 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 will
be used for 3D Secure . The payment might be declined if the URL is invalid.

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

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="20140526101407" />
<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>

Hosted Payment Page - Document version 3.21

All rights reserved - 79 / 221
10.6. Modifying the name of the "Return to shop" button
You can customize the text of the button "Return to the shop".
1. Use the fields required for your use case (see chapter Generating a payment form) to create your
payment form.

2. Use the vads_theme_config field to modify the name of the "Return to shop" button.

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

4. Use the CANCEL_FOOTER_MSG_RETURN keyword to modify the name of the "Cancel and return to
shop" button that appears on payment pages.

5. Compute the value of the signature field using all the fields of your form starting with vads_ (see
chapter Computing the signature).

By subscribing to the advanced customization option, you will be able to modify 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 sales
administration.
Example of a 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=Annuler;SUCCESS_FOOTER_MSG_RETURN=Retour" />
<input type="hidden" name="vads_trans_date" value="20140331092024" />
<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>

Hosted Payment Page - Document version 3.21

1. Create an HTML <iframe> tag on the page where you would like to display the fill out form (this page
should correspond to the "Payment" stage of your purchase journey):

...
<body>
<iframe id="idFrame" name="nameFrame" src="https://www.mystore.com/payment/form.php"
/>
</body>
</html>

Populate the src attribute with your payment form URL.

In order to correctly display 3D Secure pages, we recommend a minimum size of 400px * 400px.

Example of an integrated payment page:

Example of an integrated 3D Secure page:

Hosted Payment Page - Document version 3.21

All rights reserved - 81 / 221
2. Edit your payment form:
• populate your vads_action_mode parameter with IFRAME to enable the iframe mode and obtain
a clean display of the payment page,
• add the target attribute to your <form> tag and populate it with the title of your iframe,
• in iframe mode, the buyer cannot view or download the payment receipt. The receipt must be sent
to the buyer by e-mail. Therefore, the vads_cust_email parameter is required.
• use the vads_iframe_options field if you would like to customize the background color and the font
of the entry fields.
vads_iframe_options = {"fieldsBackgroundColor":"#000000","fieldsFontColor":"#FFFFFF"}

...
<form method="POST" action="" target="nameFrame" >
<input type="hidden" name="vads_action_mode" value="IFRAME" />
...
...

3. Manage the end of payment.

In iframe mode, there is no button to cancel or return to the shop. You can however automatically
redirect the buyer to the order confirmation page.
For this, in your payment form, populate the parameters below:
• vads_redirect_success_timeout and vads_redirect_error_timeout with "0",
• vads_url_success with the URL of your order confirmation page,
• vads_url_return with the URL of your return page in case of rejected payment,
• vads_return_mode with the "POST" or "GET" value to retrieve the payment result and display them
on your order confirmation page if necessary,
• vads_theme_config with the "FORM_TARGET=_top" value in order to define the way the return
page will be displayed.
You can also use the following values depending on your needs: "_self", "_parent", "_framename".
Example of a confirmation page that displays payment details

Hosted Payment Page - Document version 3.21

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

• all the fields starting with vads_
• the signature algorithm chosen in the shop configuration
• the key (certificate)
The value of the key is available in your Merchant Back Office via the menu Settings > Shop > Certificates
tab.
The signature algorithm is defined in your Merchant Back Office via the menu Settings > Shop >
Configuration tab.

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

To compute the signature:

1. Sort the fields starting 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 on the chain obtained at
the previous step.
b. if your shop is configured to use "HMAC-SHA-256", compute and encode in Base64 format the
message 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 shared
key,
• the result of the previous step as the message to authenticate.

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

Hosted Payment Page - Document version 3.21

All rights reserved - 83 / 221
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 example of the form is analyzed as follows:

1. The field starting by vads_ are sorted in alphabetically order :
• 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 this
example, the key of test 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 message
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 shared key,
• the result of the previous step as the message to authenticate.
The result that must be transmitted in the signature field is:
ycA5Do5tNvsnKdc/eP1bj2xa19z9q3iWPy9/rpesfS0=

Hosted Payment Page - Document version 3.21

All rights reserved - 84 / 221
12.1. Example of implementation with JAVA
Definition of the utility class SHA that will include the elements required to process the HMAC-SHA-256
algorithm
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.io.UnsupportedEncodingException;
import java.security.InvalidKeyException;
import java.security.NoSuchAlgorithmException;
import java.util.Base64;
import java.util.TreeMap;

public class VadsSignatureExample {

/**
* Build signature (HMAC SHA-256 version) from provided parameters and secret key.
* Parameters are provided as a TreeMap (with sorted keys).
*/
public static String buildSignature(TreeMap<String, String> formParameters, String
secretKey) throws NoSuchAlgorithmException, InvalidKeyException, UnsupportedEncodingException
{
// Build message from parameters
String message = String.join("+", formParameters.values());
message += "+" + secretKey;
// Sign
return hmacSha256Base64(message, secretKey);
}
/**
* Actual signing operation.
*/
public static String hmacSha256Base64(String message, String secretKey) throws
NoSuchAlgorithmException, InvalidKeyException, UnsupportedEncodingException {
// Prepare hmac sha256 cipher algorithm with provided secretKey
Mac hmacSha256;
try {
hmacSha256 = Mac.getInstance("HmacSHA256");
} catch (NoSuchAlgorithmException nsae) {
hmacSha256 = Mac.getInstance("HMAC-SHA-256");
}
SecretKeySpec secretKeySpec = new SecretKeySpec(secretKey.getBytes("UTF-8"), "HmacSHA256");
hmacSha256.init(secretKeySpec);
// Build and return signature
return Base64.getEncoder().encodeToString(hmacSha256.doFinal(message.getBytes("UTF-8")));
}
}

Definition of the utility class SHA that will include the elements required to process the SHA-1 algorithm
import java.security.MessageDigest;
import java.security.SecureRandom;

public class Sha {

static public final String SEPARATOR = "+" ;
public static String encode(String src) {
try {
MessageDigest md;
md = MessageDigest.getInstance( "SHA-1" );
byte bytes[] = src.getBytes( "UTF-8" );
md.update(bytes, 0, bytes. length );
byte[] sha1hash = md.digest();
return convertToHex(sha1hash);
}
catch(Exception e){
throw new RuntimeException(e);
}
}
private static String convertToHex(byte[] sha1hash) {
StringBuilder builder = new StringBuilder();
for (int i = 0; i < sha1hash. length ; i++) {
byte c = sha1hash[i];
addHex(builder, (c >> 4) & 0xf);
addHex(builder, c & 0xf);
}
return builder.toString();
}
private static void addHex(StringBuilder builder, int c) {
if (c < 10)
builder.append((char) (c + '0' ));
else
builder.append((char) (c + 'a' - 10));
}

Hosted Payment Page - Document version 3.21

All rights reserved - 86 / 221
Function that computes the signature:
public ActionForward performCheck(ActionMapping actionMapping, Basivoirorm form,
HttpServletRequest request, HttpServletResponse response){
SortedSet<String> vadsFields = new TreeSet<String>();
Enumeration<String> paramNames = request.getParameterNames();

// retrieve and sort the fields starting with vads_* alphabetically

while (paramNames.hasMoreElements()) {
String paramName = paramNames.nextElement();
if (paramName.startsWith( "vads_" )) {
vadsFields.add(paramName);
}
}
// Compute the signature
String sep = Sha.SEPARATOR;
StringBuilder sb = new StringBuilder();
for (String vadsParamName : vadsFields) {
String vadsParamValue = request.getParameter(vadsParamName);
if (vadsParamValue != null) {
sb.append(vadsParamValue);
}
sb.append(sep);
}
sb.append( shaKey );
String c_sign = Sha.encode(sb.toString());
return c_sign;}

Hosted Payment Page - Document version 3.21

All rights reserved - 87 / 221
12.2. Example of implementation with PHP
Example of a signature computation using the HMAC-SHA-256 algorithm:
function getSignature ($params,$key)
{
/**
*Function that computes the signature.
* $params : table containing the fields to send in the payment form.
* $key : TEST or PRODUCTION key
*/
//Initialization of the variable that will contain the string to encrypt
$contenu_signature = "";

//sorting fields alphabetically

ksort($params);
foreach($params as $name=>$value){

//Recovery of vads_ fields

if (substr($nom,0,5)=='vads_'){

//Concatenation with "+"

$contenu_signature .= $value."+";
}
}
//Adding the key at the end
$contenu_signature .= $key;

//Encoding base64 encoded chain with SHA-256 algorithm

$signature = base64_encode(hash_hmac('sha256',$contenu_signature, $key, true));
return $signature;
}

Example of a signature computation using the SHA-1 algorithm:

function getSignature($params, $key)
{
/**
* Function that computes the signature.
* $params : table containing the fields to send in the payment form.
* $key : TEST or PRODUCTION key
*/
//Initialization of the variable that will contain the string to encrypt
$contenu_signature = "" ;

// Sorting fields alphabetically

ksort($params);
foreach ($params as $name =>$value)
{
// Recovery of vads_ fields
if (substr($nom,0,5)=='vads_') {
// Concatenation with "+"
$contenu_signature .= $value."+";
}
}
// Adding the key at the end
$contenu_signature .= $key;

// Applying SHA-1 algorithm

$signature = sha1($contenu_signature);
return $signature ;
}

Hosted Payment Page - Document version 3.21

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.

13.1. Redirecting the buyer to the payment page

The URL of the payment gateway is:
https://secure.payzen.eu/vads-payment/

Example of parameters sent to the payment gateway:

13.2. Processing errors

If the payment gateway detects an error while receiving the form, an error message will appear and the
buyer 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 help
you fix it.

In PRODUCTION mode
The message simply indicates to the buyer that a technical problem has 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/en-EN/error-code/error-00.html

Hosted Payment Page - Document version 3.21

All rights reserved - 89 / 221
Other messages may appear during the payment process.
Here is a list of the most frequent messages:
Message Description
"Seasonal service" is enabled in your shop. Payments are
only authorized during the defined period. If you want to
This website does not currently accept payments.
modify the opening period of your shop, please contact sales
administration.

• The buyer's bank has rejected the authorization or

Your payment request has been declined by your financial information request.
institution. • The risk management rules have triggered the rejection of
the transaction.

The buyer clicked on the payment link after the payment

This payment order is expired. Please contact your shop.
order expiration date.
The buyer clicked on the payment link one more time after
This payment order has already been paid.
having already made the payment.
An error occurred during the payment request, the The payment form has been rejected. The shop administrator
merchant website has been informed of the impossibility to has received an e-mail with the details about the origin of the
finalize the transaction. error.
The merchant website sends a transaction identifier that
has already been used for another transaction (accepted or
The transaction has already been made.
rejected). The transaction identifier must be unique within
the same day (00:00:00 at 23:59:59 UTC).

• The buyer attempts to validate the card number while the

payment session is expired. The session is open for about
10 minutes.
Sorry, you have been disconnected due to a long period of • The merchant website sends a transaction identifier
inactivity. that has already been used but that did not result in a
transaction (e.g. abandoned payment). The transaction
identifier must be unique within the same day (00:00:00
at 23:59:59 UTC).

Cookies are blocked by your browser. Make sure you The buyer has disabled cookies in his or her browser. Cookies
authorize them before retrying the operation. are necessary for the payment to be processed correctly.

13.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 will receive 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 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 completed
payment.
Most frequent cases:

Hosted Payment Page - Document version 3.21

All rights reserved - 90 / 221
1. Once redirected to the payment page for example, the buyer realizes that it is time to go to lunch.
An hour later, he decides to continue his payment and clicks on the logo corresponding to his payment
method.
His payment session has already expired, the payment gateway displays an error message indicating
that it was disconnected due to too long 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 his Merchant Back Office, no vads_url_return
field is transmitted in his payment form.
2. Once redirected to the payment page, the buyer closes his browser (by mistake or because he no
longer wants to make the payment).

Notification in case of session expiration

It's 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 Setting
up notifications).

Hosted Payment Page - Document version 3.21

After each payment (accepted or rejected) the gateway sends to the merchant site a notification containing
the payment result.
This notification is also called IPN.
To process the payment result, the merchant website must have a separate page that analyzes the data
transmitted in POST mode (URL e.g.: https://site-marchand.com/analyse_paiement.php)
Depending on the result, this page must trigger different actions (changing the order status, updating
stocks, etc.)

Prerequisites:
• URL of the page that analyzes the payment result must be specified in the Merchant Back Office (see
chapter 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 authorized
is: 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 merchant
website.
• 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 the
buyer. 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 identifying the origin of the error, the gateway systematically analyzes the
first 512 characters returned by the merchant site.
These characters can be viewed in the transaction details, Event log tab:

Hosted Payment Page - Document version 3.21

All rights reserved - 92 / 221
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 already
updated.
Once these steps are completed, the script can update the database (new order status, stock update,
registration of payment information, etc.).

Hosted Payment Page - Document version 3.21

All rights reserved - 93 / 221
14.1. Retrieving data returned in the response
The data returned in the response depends on the parameters sent in the payment form, the payment
type 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 = 3000
vads_auth_mode = FULL
vads_auth_number = 3fb0de
vads_auth_result = 00
vads_capture_delay = 0
vads_card_brand = VISA
vads_card_number = 497010XXXXXX0000
vads_payment_certificate = a50d15063b5ec6cb140043138b8d7576470b71a9
vads_ctx_mode = TEST
vads_currency = 978
vads_effective_amount = 3000
vads_site_id = 12345678
vads_trans_date = 20140902094139
vads_trans_id = 454058
vads_validation_mode = 0
vads_version = V2
vads_warranty_result = YES
vads_payment_src = EC
vads_sequence_number = 1
vads_contract_used = 5785350
vads_trans_status = AUTHORISED
vads_expiry_month = 6
vads_expiry_year = 2015
vads_bank_code = 17807
vads_bank_product = A
vads_pays_ip = FR
vads_presentation_date = 20140902094202
vads_effective_creation_date = 20140902094202
vads_operation_type = DEBIT
vads_threeds_enrolled = Y
vads_threeds_cavv = Q2F2dkNhdnZDYXZ2Q2F2dkNhdnY=
vads_threeds_eci = 05
vads_threeds_xid = WXJsVXpHVjFoMktzNmw5dTd1ekQ=
vads_threeds_cavvAlgorithm = 2
vads_threeds_status = Y
vads_threeds_sign_valid = 1
vads_threeds_error_code =
vads_threeds_exit_status = 10
vads_trans_uuid= 1cd9994823334e31bbb579b4d716832d
vads_risk_control = CARD_FRAUD=OK;COMMERCIAL_CARD=OK
vads_result = 00
vads_extra_result = 00
vads_card_country = FR
vads_language = fr
vads_hash = 299d81f4b175bfb7583d904cd19ef5e38b2b79b2373d9b2b4aab74e5753b10bc
vads_url_check_src = PAY
vads_action_mode = INTERACTIVE
vads_payment_config = SINGLE
vads_page_action = PAYMENT
signature = FxGvazgW0dgqOrVrx6bqKZSXh2y5Dp3bWC9HFn33t+Q=

Hosted Payment Page - Document version 3.21

All rights reserved - 94 / 221
14.2. Computing the signature
The signature is computed by following the same procedure as for creating the payment form.

The data submitted by the payment gateway is encoded in UTF-8.

Any alteration of received data will result in signature computation error.

To compute the signature:

1. Take all the fields starting 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:

14.3. Comparing signatures

To ensure the integrity of the response, you must compare the value of the signature field received in the
response with the one computed previously.

If the signatures match,

• you may consider the response as safe and proceed with the analysis.
• If they don't, 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 to
live mode),
• a data corruption attempt.

Hosted Payment Page - Document version 3.21

All rights reserved - 95 / 221
14.4. Analyze the nature of the notification
The vads_url_check_src field allows to differentiate the notifications based on their triggering event:
• creation of a transaction,
• new notification sent by the merchant via the Merchant Back Office
It specifies the applied notification rule:
Value Applied rule
PAY The PAY value will be sent in the following cases:
• immediate payment (or first installment payment of a recurring payment),
• payment deferred for less than 7 days,
only if the merchant has configured the rule for Instant Payment Notification URL at the end of
payment,
• payment abandoned or canceled by the buyer,
only if the merchant has configured the rule for Instant Payment Notification URL on
cancellation.

BO Execution of the notification via the Merchant Back Office (right-click a transaction > Execute the IPN
URL).
BATCH The BATCH value will be sent in case of an update of a transaction status after its synchronization on
the acquirer side.
This is the case of payments with redirection to the acquirer, such as FacilyPay, PayPal, etc.
Only if the merchant has configured the rule for Instant Payment Notification URL on BATCH
change.
BATCH_AUTO The BATCH_AUTO value will be 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 for Instant Payment Notification URL on batch
authorization.
The notification will be 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 rule for Instant
Payment Notification URL when creating recurring payments.
MERCH_BO The MERCH_BO value will be sent in the following cases:
• during operation made from the Merchant Back Office (refund, modification, validation,
duplication), only if the merchant has configured the following notification rule: Instant
Payment Notification URL on an operation coming from the Back Office

RETRY Automatic retry of the IPN.

Table 14: Values associated with the vads_url_check_src field

After checking its value, the script will be able to 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.s
If vads_url_check_src is set to REC the script will retrieve the recurring payment reference and will
increment the number of the expired installment payments in case the payment has been accepted, etc.

Hosted Payment Page - Document version 3.21

All rights reserved - 96 / 221
14.5. Identifying the type of operation
The vads_operation_type field allows to distinguish:
• a debit operation
• a refund operation
Value Description
DEBIT Debit operation
CREDIT Refund operation
Table 15: Value of the vads_operation_type field

For example:
If vads_operation_type is set to DEBIT, the script updates the order and registers the transaction details.
If vads_operation_type is set to CREDIT, the script updates the paid amount or adds a new transaction
line in the order.

Hosted Payment Page - Document version 3.21

All rights reserved - 97 / 221
14.6. Processing the response data
Here is an example of analysis to guide you through processing the response data.
1. Identify the mode (TEST or PRODUCTION) that was used for creating the transaction by analyzing the
value of the vads_ctx_mode field.

2. Identify the order by retrieving the value of the vads_order_id field if you have transmitted it to the
payment gateway.
Make sure that the order status has not already been updated.

3. Retrieve the payment result transmitted in the vads_trans_status field.

Its value allows you to define the order status.
Value Description
ABANDONED Abandoned
payment abandoned by the buyer.
The transaction has not been created, and therefore cannot
be viewed in the Merchant Back Office.
AUTHORISED Waiting for capture
The transaction has been accepted and will be
automatically captured at the bank on the expected date.
AUTHORISED_TO_VALIDATE To be validated
The transaction, created with manual validation, is
authorized. The merchant must manually validate the
transaction in order for it to be captured.
The transaction can be validated as long as the expiration
date of the authorization request has not passed. If the
authorization validity period has passed, the payment
status changes to EXPIRED. The Expired status is final.
CANCELLED Canceled
The transaction has been canceled by the merchant.
CAPTURED Captured
The transaction has been captured by the bank.
CAPTURE_FAILED The transaction capture has failed.
Contact the technical support.
EXPIRED Expired
The expiry date of the authorization request has passed
and the merchant has not validated the transaction. The
account of the cardholder will, therefore, not be debited.
INITIAL Pending
This status concerns all the payment methods that require
integration via a payment form with redirection.
This status is returned when:
• no response has been returned by the acquirer
or
• the delay of the response from the acquirer has
exceeded the payment session on the payment
gateway.
This status is temporary. The final status will be
displayed in the Merchant Back Office immediately after
the synchronization has been completed.

NOT_CREATED Transaction not created

The transaction has not been created, and therefore cannot
be viewed in the Merchant Back Office.
REFUSED Rejected
Transaction is declined.
SUSPENDED Suspended

Hosted Payment Page - Document version 3.21

All rights reserved - 98 / 221
Value Description
The capture of the transaction is temporarily blocked by
the acquirer (AMEX GLOBAL or SECURE TRADING). Once the
transaction has been correctly captured, its status changes
to CAPTURED.
UNDER_VERIFICATION For PayPal transactions, this value means that PayPal
withholds the transaction for suspected fraud.
The payment will remain in the Transactions in progress
tab until the verification process has been completed. The
transaction will then take one of the following statuses:
AUTHORISED or CANCELED.
A notification will be sent to the merchant to warn them
about the status change (Instant Payment Notification on
batch change).
WAITING_AUTHORISATION Waiting for authorization
The capture delay exceeds the authorization validity period.
WAITING_AUTHORISATION_TO_VALIDATE To be validated and authorized
The capture delay exceeds the authorization validity period.
An authorization of 1 EUR (or information request about the
CB network if the acquirer supports it) has been accepted.
The merchant must manually validate the transaction for
the authorization request and the capture to occur.
Table 16: Values associated with the vads_trans_status field

4. Retrieve the payment reference transmitted in the vads_trans_id field.

5. Analyze the vads_payment_config field to determine whether it is an immediate payment or an

installment payment.
Field name Value for an immediate payment Value for an installment payment
vads_payment_config SINGLE MULTI
(the exact syntax is MULTI:first=X;count=Y;period=Z)
Table 17: vads_payment_config analysis

For an installment payment, identify the installment number by retrieving the value of the
vads_sequence_number field.
Value Description
1 First installment
2 Second installment
3 Third installment
n Installment number
Table 18: vads_sequence_number analysis

6. Analyze the vads_sequence_number field to know the number of payment attempts made.
vads_payment_config = SINGLE:
vads_url_check_src vads_sequence_number Description
1 Payment made in 1 attempt
PAY 2 Payment made in 2 attempts
3 Payment made in 3 attempts
1 Deferred Payment made in 1 attempt
BATCH_AUTO 2 Deferred Payment made in 2 attempts
3 Deferred Payment made in 3 attempts

Note
Installment payments is not compatible with the functionality of additional attempts in case of rejected
payment.

Hosted Payment Page - Document version 3.21

8. Analyze the vads_payment_option_code field to determine whether it is an installment payment.

Value Description
1 Payment in one installment
2 Payment in two installment
3 Payment in three installment
n Payment in n installment
Table 19: vads_payment_option_code analysis

9. Retrieve the value of the vads_capture_delay field to identify the number of days before the
payment is captured by the acquirer.
It will allow you to identify whether it is an immediate or a deferred payment.

10.Retrieve the payment amount and currency. To do this, retrieve the values of the following fields:
Field name Description
vads_amount Payment amount in the smallest currency unit.
vads_currency Code of the currency used for the payment.
vads_change_rate Exchange rate used to calculate the effective payment amount (seevads_effective_amount).
vads_effective_amount Payment amount in the currency used for the capture.
vads_effective_currency Code of the currency used for the capture.
Table 20: Analysis of the payment amount and currency.

11.Retrieve the value of the vads_auth_result field to identify the result of the authorization request.
The complete list of returned codes can be viewed in the Data Dictionary.
Here is a list of frequently returned codes to help you understand the reason of the rejection:
Value Description
03 Invalid acceptor
This code is sent by the card issuer. Refers to a problem with settings on authorization servers. (E.g. closed
contract, incorrect MCC declared, etc.).
To find out the specific reason for the rejection, the buyer must contact his or her bank.
05 Do not honor
This code is sent by the card issuer. This code is used in the following cases:
• Invalid expiration date
• Invalid CVV
• Exceeded credit limit
• Insufficient balance (etc.)
To find out the specific reason for the rejection, the buyer must contact his or her bank.
51 Insufficient balance or exceeded credit limit
This code is sent by the card issuer. This code appears if the balance on the buyer's account is insufficient to
make the purchase.
To find out the specific reason for the rejection, the buyer must contact his or her bank.
56 Card absent from the file
This code is sent by the card issuer.
The entered card number is incorrect or the combination of the card number + expiration date does not exist.
57 Transaction not allowed for this cardholder
This code is sent by the card issuer. This code is used in the following cases:
• The buyer attempts to make an online payment with a cash withdrawal card,
• The authorized payment limit is exceeded.
To find out the specific reason for the rejection, the buyer must contact his or her bank.
59 Suspected fraud

Hosted Payment Page - Document version 3.21

All rights reserved - 100 / 221
Value Description
This code is sent by the card issuer. This code appears when an incorrect CVV code or expiration date has been
entered several times.
To find out the specific reason for the rejection, the buyer must contact his or her bank.
60 The acceptor of the card must contact the acquirer
This code is sent by the card issuer. Refers to a problem with settings on authorization servers. Appears usually
when the merchant ID does not correspond to the sales channel used. (E.g.: an online transaction with a distant
sale contract with - manual entry of contract data).
Contact the customer service to resolve the problem.
Table 21: Values associated with the vads_auth_result field

12.Retrieve the 3D Secure authentication result. To do this:

a. Retrieve the value of the vads_threeds_enrolled field to identify the status of the card
enrollment.
Value Description
Empty The 3DS authentication is not accomplished (3DS disabled in the request, the merchant is not enrolled or
3DS is not available for the payment method).
Y Authentication available, cardholder enrolled.
N Cardholder not enrolled.
U Impossible to identify the cardholder or authentication is not available for the card (e.g. corporate or
prepaid credit cards).
Table 22: Values of the vads_threeds_enrolled field

b. Retrieve the result of 3D Secure authentication by retrieving the value of the vads_threeds_status
field.
Value Description
Empty The 3DS authentication is not accomplished (3DS disabled in the request, the cardholder is not enrolled or
3DS is not available for the payment method).
Y Cardholder successfully authenticated.
N Cardholder authentication error.
U Authentication impossible.
A Authentication attempted but not accomplished.
Table 23: Values of the vads_threeds_status field

13.Retrieve the result of the fraud verification by identifying the value of the vads_risk_control field.
This field is sent only if the merchant has:
• subscribed to the "Risk management" service
• enabled at least one verification process in the Merchant Back Office (Settings > Risk
management menu).
It is populated with the list of values separated by a ";" with the following syntax: vads_risk_control =
control1=result1;control2=result2
the possible values for control are:
Value Description
CARD_FRAUD Verifies whether the cardholder's card number is in the card greylist.
SUSPECT_COUNTRY Verifies whether the cardholder's card number is in the list of forbidden countries.
IP_FRAUD Verifies whether the cardholder's IP address is in the IP greylist.
CREDIT_LIMIT Verifies the purchase frequency and amounts for the same card number, or the
maximum amount of an order.
BIN_FRAUD Verifies whether the BIN code of the card is in the greylist for 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 credit card.
SYSTEMATIC_AUTO Verifies whether the buyer's card is a MAESTRO or VISA ELECTRON credit card.

Hosted Payment Page - Document version 3.21

All rights reserved - 101 / 221
Value Description
INCONSISTENT_COUNTRIES Verifies whether the country of the IP address, the country of the payment card and the
country of residence of the buyer match.
NON_WARRANTY_PAYMENT Liability shift.
SUSPECT_IP_COUNTRY Verifies whether the cardholder's country, identified by his/her IP address, is in the list of
forbidden countries.
Table 24: List of fraud verification processes

The possible values for result are:

Value Description
OK OK.
WARNING Informational control failed.
ERROR Blocking control failed.
Table 25: List of fraud verification processes

14.Retrieve the type of the card used for the payment.

Two scenarios are possible:
• For a payment processed with only one card. The fields to process are:
Field name Description
vads_card_brand Brand of the card used for the payment. E.g.: CB, VISA, VISA_ELECTRON,
MASTERCARD, MAESTRO, VPAY
vads_brand_management Permits to know the brand used when paying, the list of available brands and
also if the buyer has changed the default brand chosen by the merchant.
vads_card_number Masked number of the card used for the payment.
vads_expiry_month Expiration month between 1 and 12 (e.g.: 3 for March, 10 for October).
vads_expiry_year Expiration year in 4 digits (e.g.: 2023).
vads_bank_code Code of the issuing bank
vads_bank_product Product code of the card
vads_card_country Country code for the country where the card was issued (alpha ISO 3166-2
code, e.g.: "FR" for France, "PF" for French Polynesia, "NC" for New
Caledonia, "US" for the United States).
Table 26: Analysis of the card used for payment

• For a split payment (that is to say a transaction using several payment methods), the fields to
process are:
Field name Value Description
vads_card_brand MULTI Several types of payment card are used for the payment.
vads_payment_ Json format, see details below. Details of performed transactions.
seq

The vads_payment_seq field (json format) describes the split payment sequence. It contains:
1. "trans_id" : global transaction identifier to the payment sequence.
2. "transaction" : transaction table of the sequence. It contains the following elements:
Field name Description
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 in the Merchant Back Office will be used.

card_brand Used payment method.

Hosted Payment Page - Document version 3.21

All rights reserved - 102 / 221
Field name Description
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 online documentation
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 been successfully created.
NOT_CREATED The authorization request has been declined.
The token (or UMR for SEPA payment) has not been created, and
therefore 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, and
therefore cannot be viewed in the Merchant Back Office.

presentation_date For a payments by card, this parameter is the requested capture date (ISO 8601 format).
trans_id Transaction number.
ext_trans_id This field is not sent for payments by credit cards.
trans_uuid Unique reference generated by the payment gateway after the creation of a payment transaction.
Guarantees 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 in 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 Relevance verification: countries do not match (country IP address, card country,
buyer's country).
30 The country of the IP address is on the greylist.
99 Technical issue encountered by the server during a local verification process.

sequence_number Sequence number.

trans_status Transaction status.
Table 27: JSON object content

Note : canceled transactions are also displayed in the table.

15.Save the value of the vads_trans_uuid field. It will allow you to identify uniquely the transaction if
you use the Web Services APIs.

Hosted Payment Page - Document version 3.21

All rights reserved - 103 / 221
16.Retrieve all the information about the purchase, the buyer and the shipping.
These details will be provided in the response only of they have been transmitted in the payment
form.
Their values is identical to the values submitted in the form.

17.Proceed to the order update.

Hosted Payment Page - Document version 3.21

All rights reserved - 104 / 221
14.7. Processing errors
Setting up a log file
During the implementation phase, it is important to have logs especially in case of difficulties with signature
computation.
It is recommended to set up a daily log file even after shifting the merchant website to live mode.
It will allow you to analyze data in case any problem occurs.
Ideally, a log file should contain the sent or received data, the chain obtained during signature computation
before applying the hash function.
HTTP error code
In case an error occurs during notifications, the sent warning e-mail will specify the return code of the
HTTP protocol.
There are 5 categories of return codes:
Code categories Description
1XX Information
2XX Success
3XX Redirection
4XX Client error
5XX Server error

A description of the error codes with their possible causes is available on our website
https://payzen.io/en-EN/error-code/server-url-error.html

Frequent error:
An .htaccess file might block the call to the IPN.
.htaccess files are Apache web server configuration files. They can be stored in any folder of the merchant
website (the configuration applies to the folder and all the contained folders with no .htaccess files).

Hosted Payment Page - Document version 3.21

By default, when the buyer returns to the merchant website, no parameter will be transmitted by the
buyer's browser.
However, if the vads_return_mode field has been transmitted in the payment form (see chapter Managing
the return to the merchant website) it will be possible to retrieve the data:
• either in GET mode: the data is presented in the URL as follows : ?field1=value1&field2=value2
• or in POST: the data is sent in a POST form.

The data transmitted to the browser is the same as during notifications (IPN).
The vads_url_check_src and vads_hash fields will be sent only in the instant notification.

To analyze this data, see chapter Analyzing the payment result.

Note : the return to the shop will allow you to show only the visual context to the buyer. Do not use the
received data for its processing in the database.

Hosted Payment Page - Document version 3.21

Before proceeding to production mode, it is necessary to run tests to make sure that there are no
interaction problems between the merchant website and the payment gateway.
The test payment requests must:
• contain the vads_ctx_mode field set to TEST.
• use the test key for signature computation.
Different cases of payments can be simulated by using test card numbers specified on the payment page.
The merchant will be able to test all 3D Secure authentication results (if the merchant is enrolled and 3DS
is not disabled).
The list of the tests to perform to generate the production key is provided in the Merchant Back Office,
via the menu Settings > Shop > Certificates.

Each row of the list contains card numbers associated with the same scenario (i.e. 2 accepted payments
and 2 refused payments).
Each column corresponds to a different card type: CB/VISA, MASTERCARD, MAESTRO, VISA ELECTRON).

To perform the test phase:

1. Make an order on your merchant website as if you were one of your buyers.

2. Once redirected to the payment page, select the card type of your choice.

3. Refer to the list of tests to identify the card number to use.

4. Once a test has been validated, its status is updated in the list. Click on Refresh the table button if
the status has not been updated automatically.

5. Once the 4 tests have been validated, the Generate the production certificate button becomes
available.

Hosted Payment Page - Document version 3.21

All rights reserved - 107 / 221
6. Click the Generate the production certificate button and accept the notification messages that will
appear.

The production key is now available.

Hosted Payment Page - Document version 3.21

First of all, check the status of the IPN URL in the Merchant Back Office.
To do this:
1. Select a transaction with a right-click.
2. Select Display transaction details.
3. Check the status of the IPN.
• In case the status is Sent, it means that you have correctly specified the URL in the Merchant Back
Office.
• In case the status is Undefined URL, it means that you have not specified the URL in the Merchant
Back Office.
1. Check the address of the IPN URL entered in TEST and PRODUCTION mode.
2. Click Settings > Notification rules.
3. Enter the IPN URL (Instant Payment Notification URL at the end of payment).
Do not enter an address in "localhost". The call to this URL is made from one server to another.
4. Click Save.
• In case the status is Failed, see chapter Processing errors.

Hosted Payment Page - Document version 3.21

This chapter explains how you can:

• Generating the production key.
• Shift your merchant website to live mode.
• Make a first payment in production mode.
• Generate a new production key (in case a problem occurs).

18.1. Generating the production key

You can generate the production key via the menu Settings > Shop > Certificates tab > Generate the
production certificate button.
Once the production key has been generated, its value appears in the Certificates tab.
An e-mail is sent to the administrator to confirm that the production key has been generated.

18.2. Shifting the merchant website to live mode

1. Set the vads_ctx_mode field to PRODUCTION.
2. Change the value of the test key to the value of your production key for calculating the signature.
You will find this value in Settings > Shop > Certificates tab.
3. Enter the correct IPN in PRODUCTION mode via Settings > Notification rules.

18.3. Making a first production payment

We recommend checking the two following points:
• The correct end-to-end functioning of the production environment.
To do this, make a real transaction.
This transaction can later be canceled via the Merchant Back Office inManagement > Transactions >
Transactions in progress. This transaction will not be captured in the bank.
• The correct functioning of the IPN URL (Instant Payment Notification URL at the end of payment)
specified in the Merchant Back Office.
To do this, do not click on Return to the shop after a payment.
View the transaction details in the Merchant Back Office and make sure that the IPN URL status is Sent.

Hosted Payment Page - Document version 3.21

All rights reserved - 110 / 221
18.4. Regenerating the production key
In case the production key is lost or corrupted, the merchant can generate a new one in the Merchant
Back Office. To do this:
1. Select Settings > Shop > Certificates tab, from the Merchant Back Office.

2. Click on Regenerate.

Hosted Payment Page - Document version 3.21

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 that
belong 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

Then, the data dictionary 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, the
payment 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 the
incorrect parameter.

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

Hosted Payment Page - Document version 3.21

All rights reserved - 112 / 221
Viewing parameters sorted by category
Go to the desired category to obtain the list of related parameters
• 3DS Authentication
• Subscription details
• Buyer details
• Payment method details
• Order details
• Shipping details
• Technical details
• Transaction details
• Donation details
• Payment page customization
• Automatic redirection

Technical details
Field name Format Description Input Output
Signature guaranteeing the requests
signature an40 integrity exchanged between the merchant x x
website and the payment gateway.
vads_action_mode enum Card data acquisition mode x x
Payment process to apply. Overrides the
vads_override_payment_cinematic enum x
recorded value on the MID
Name of the e-commerce solution used
vads_contrib ans..128 on the merchant web site and its version x x
number.
Defines the mode of interaction with the
vads_ctx_mode enum x x
payment gateway.
Optional code of the response. Its
vads_extra_result n2 meaning depends on the value entered in x
vads_result.
A unique key returned only to the Instant
vads_hash an64 x
Payment Notification (IPN).
vads_page_action enum Defines the action to be performed. x x
vads_payment_error n..3 Error code for declined payments x
vads_result n2 General return code of the payment result. x
vads_site_id n8 Shop ID x x
URL of the page to notify at the end of
vads_url_check ans..1024 payment. Overrides the value entered in x
the notification rules settings.
This parameter defines the source of the
vads_url_check_src enum call to the notification URL (also called IPN x
URL).
Version of the exchange protocol with the
vads_version enum x x
payment gateway
Table 28: Parameter list - Technical details

Hosted Payment Page - Document version 3.21

All rights reserved - 113 / 221
Order details
Field name Format Description Input Output
vads_authent_paypal_protection_eligibility Type of merchant protection used for the
enum x
transaction.
vads_ext_info Customizable fields allowing to add
ans additional details to the confirmation e-mail x x
sent to the merchant and to the IPN URL.
vads_nb_products n..12 Number of items in the cart x
vads_order_id ans..64 Order ID x x
vads_order_info an..255 Additional order info x x
vads_order_info2 an..255 Additional order info x x
vads_order_info3 an..255 Additional order info x x
vads_product_amountN Item amount. N corresponds to the index of
n..12 the item (0 for the first one, 1 for the second x
one, etc.).
vads_product_ext_idN Product barcode in the merchant's website.
an..100 N corresponds to the index of the item (0 x
for the first one, 1 for the second one, etc.).
vads_product_labelN Item name. N corresponds to the index of
an..255 the item (0 for the first one, 1 for the second x
one, etc.).
vads_product_qtyN Quantity of items. N corresponds to the
n..12 index of the item (0 for the first one, 1 for x
the second one, etc.).
vads_product_refN Item reference. N corresponds to the index
an..64 of the item (0 for the first one, 1 for the x
second one, etc.).
vads_product_typeN Item type. N corresponds to the index of the
enum item (0 for the first one, 1 for the second x
one, etc.).
vads_product_vatN n..12 x
vads_tax_amount n..12 Tax amount for the entire order. x

Table 29: Parameter list - Order details

Hosted Payment Page - Document version 3.21

All rights reserved - 114 / 221
Buyer details
Field name Format Description Input Output
vads_avs_result a1 Address verification system (AVS) x
vads_cust_address ans..255 Postal address x x
vads_cust_address2 ans..255 Second line of the address x x
vads_cust_address_number ans..64 Street number x x
vads_cust_cell_phone an..32 Cell phone number x x
vads_cust_city an..128 City x x
vads_cust_country Country code in compliance with the ISO
a2 x x
3166 standard
vads_cust_district ans..127 District x x
vads_cust_email ans..150 Buyer's e-mail address x x
vads_cust_first_name ans..63 First name x x
vads_cust_id an..63 Buyer reference on the merchant website x x
vads_cust_last_name ans..63 Name x x
vads_cust_legal_name an..100 Buyer's legal name x
Buyer's legal name. Use vads_cust_first_name and
an..127 x x
vads_cust_last_name.
vads_cust_national_id ans..255 National identifier x x
vads_cust_phone an..32 Phone number x x
vads_cust_state ans..127 State / Region x x
vads_cust_status enum Status x x
vads_cust_title an..63 Buyer's title x x
vads_cust_zip an..64 Zip code x x
vads_ext_info_fingerprint_id string Session unique identifier x
vads_ext_info_bil_address_complement ans..250 Address supplement for billing 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
Table 30: Parameter list - Buyer details

Hosted Payment Page - Document version 3.21

All rights reserved - 115 / 221
Shipping details
Field name Format Description Input Output
vads_shipping_amount n..12 Shipping fee amount x
vads_ext_info_deadline Precision of the delivery delay in days (N
n x
days).
vads_ext_info_ship_address_complement ans..250 Address supplement for shipping x
vads_ext_info_ship_date_of_birth Datetime The buyer's date of birth for the shipping. x
vads_ext_info_ship_gender n1 The buyer's gender for the shipping. x
vads_ship_to_city an..128 City x x
vads_ship_to_country Country code in compliance with the ISO
a2 x x
3166 standard
vads_ship_to_delay Shipping delay, mandatory for priority
enum x
shipping
vads_ship_to_delivery_company_name ans..127 Transporter's name x
vads_ship_to_district ans..127 District x x
vads_ship_to_first_name ans..63 First name x
vads_ship_to_last_name ans..63 Name x
vads_ship_to_legal_name an..100 Legal name x
vads_ship_to_name Deprecated. Buyer's last name.
ans..63 Use vads_ship_to_first_name and x x
vads_ship_to_last_name.
vads_ship_to_phone_num ans..32 Phone number x x
vads_ship_to_speed enum Shipping speeddesc_ship_to x
vads_ship_to_state ans..127 State / Region x x
vads_ship_to_status Allows to specify the type of the shipping
enum x x
address.
vads_ship_to_street ans..255 Postal address x x
vads_ship_to_street_number an..5 Street number x x
vads_ship_to_street2 ans..255 Second line of the address x x
vads_ship_to_type enum The shipping type x
vads_ship_to_user_info ans..255 Buyer details (CPF/CNPJ legal identifier) x x
vads_ship_to_zip an..64 Zip code x x
Table 31: Parameter list - Shipping details

Hosted Payment Page - Document version 3.21

All rights reserved - 116 / 221
Payment method details
Field name Format Description Input Output
vads_bank_code n5 Code associated with the issuing bank. x
vads_bank_product an..3 Product code of the payment card. 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 payment card. x x
vads_card_country Country code alpha-2 (ISO 3166) of the
a2 x
payment card.
vads_card_number n..36 Masked card number. x x
vads_card_holder_name ans..255 Name of the cardholder. x
vads_cvv n..4 3 or 4-digit card security code. x
vads_expiry_month Expiry month of the card used for the
n..2 x x
payment.
vads_expiry_year Expiry year of the card used for the
n4 x x
payment.
vads_proof_of_id_number Field reserved to the entry of the buyer's ID
an..13 x
number on the payment page.
vads_proof_of_id_type This field corresponds to the type of ID
enum x
selected by the buyer.
vads_brand_management This field indicates to the merchant:
• whether the buyer used a different
brand than the one defined by default
json by the merchant x
• the brand chosen by the buyer
• the list of available brands

Table 32: Parameter list - Payment method details

Hosted Payment Page - Document version 3.21

All rights reserved - 117 / 221
Transaction details
Field name Format Description Input Output
vads_acquirer_transient_data json Specific information proper to the acquirer. x
vads_amount Transaction amount expressed in the
n..12 x x
smallest currency unit (cents for euro).
vads_auth_mode Specifies the mode of the authorization
enum x
request
vads_auth_number Authorization number returned by the bank
an..6 x
server.
vads_auth_result Return code of the authorization request
n..3 x
returned by the issuing bank.
vads_capture_delay Delay (in days) before the payment is
n..3 x
captured.
vads_change_rate Exchange rate used to calculate the
string effective payment amount (multi-currency x
payment).
vads_contract_used ans..250 Merchant ID used. x
vads_contracts map The Merchant ID to be used. x
vads_currency Code of the currency to use for the
n3 x x
payment.
vads_effective_amount The amount of the payment presented in
n..12 the smallest unit of the currency used for x
the capture (cents for euro).
vads_effective_creation_date Date of transaction registration
n14 in UTC format (GMT+0, 24H) x
(YYYYMMDDHHMMSS).
vads_effective_currency n3 Code of the currency used for the capture. x
vads_ext_trans_id enum External transaction reference. x
vads_first_installment_delay Number of deferred months to be used
n..3 for the first installment of the payment in x
installments.
vads_operation_type Allows to differentiate a debit from a credit
enum x
(refund).
vads_payment_cards liste List of the payment methods proposed to
x
d'enum the buyer.
vads_payment_certificate The value of this field is populated by the
an40 payment platform if the authorization has x
been successfully completed.
vads_payment_config enum Payment type: immediate or installment. x x
vads_payment_option_code an..5 The code of the payment option in use. x x
vads_payment_seq json Split payment sequence. x
vads_payment_src enum Payment source. x
vads_requestor In order to modify the value of the "Aceite"
enum x x
field for a Boleto Bancario
vads_risk_analysis_result Result of the risk management process
enum performed by an external system x
(ClearSale, CyberSource, etc.).
vads_risk_assessment_result Result of the risk assessment performed by
enum x
the payment gateway.
vads_risk_control map List of risk management processes. x
vads_sequence_number Sequence (installment) number of the
n..3 x
transaction.
vads_token_id an..32 Payment order ID associated with the
x
transaction.
vads_trans_date Date and time in UTC format (GMT+0,
n14 x x
24H) (YYYYMMDDHHMMSS).
vads_trans_id n6 Unique transaction ID. x x
vads_trans_status enum Transaction status. x

Hosted Payment Page - Document version 3.21

All rights reserved - 118 / 221
Field name Format Description Input Output
vads_trans_uuid Unique transaction ID generated by the
ans32 x
payment platform.
vads_validation_mode n1 Transaction validation mode. x x
vads_warranty_result enum Liability shift in case of accepted payment. x
Table 33: Parameter list - Transaction details

Hosted Payment Page - Document version 3.21

All rights reserved - 119 / 221
3DS Authentication
Field name Format Description Input Output
vads_threeds_cavv Indicates cardholder authentication via the
ACS.
Its value is populated by 3DS authentication
ans..28 x x
server (ACS) when the buyer has been
correctly identified (vads_threeds_status
equals "Y" or "A").
vads_threeds_cavvAlgorithm Algorithm used by the ACS to generate the
value of the CAVV
Its value is populated by 3DS
n1 x x
authentication server (ACS) when the
buyer has been correctly identified
(vads_threeds_status equals "Y" or "A").
vads_threeds_eci Indicates the e-commerce index.
Its value is populated by 3DS authentication
n..2 server (ACS) when the buyer has been x x
correctly identified (vads_threeds_status
equals "Y" or "A").
vads_threeds_enrolled Indicates the enrollment status of the
cardholder.
a1 Its value is populated by the VISA and x x
MASTERCARD (DS) servers during 3D
Secure authentication
vads_threeds_error_code Deprecated.
n..2 x
Use the vads_threeds_exit_status field.
vads_threeds_exit_status Indicates the final status of 3D Secure
authentication.
n..2 x
Its value is populated by the payment
gateway.
vads_threeds_mpi Enables / disables 3DS authentication for an
n1 x
e-commerce payment.
vads_threeds_sign_valid Indicates the validity of the PARes
message signature.
n1 x
Its value is populated by the payment
gateway.
vads_threeds_status Indicates the authentication status of the
cardholder.
a1 Populated by the 3DS authentication x x
server (ACS) during the 3D Secure
authentication.
vads_threeds_xid Indicates the unique 3DS authentication
reference.
ans..28 Its value is populated by the authentication x x
server (ACS) during the 3D Secure
authentication
Table 34: Parameter list - 3DS Authentication

Hosted Payment Page - Document version 3.21

All rights reserved - 120 / 221
Donation details
Field name Format Description Input Output
vads_ext_info_donation Transaction amount expressed in the
n..12 smallest currency unit E.g.: 978 for euro x
(EUR)
vads_ext_info_donation_contribution Transaction amount expressed in the
n..12 smallest currency unit E.g.: 978 for euro x
(EUR).
vads_ext_info_donation_merchant n8 ID of the shop that performed the donation. x
vads_ext_info_donation_recipient n..20 HelloAsso ID of the donation recipient. x
vads_ext_info_donation_recipient_name Name of the organization that received the
ans..255 x
donation.
vads_risk_primary_warranty Allows to override the risk management
enum configuration Verification of transfer of x
responsibility for primary transactions.
Table 35: Parameter list - Donation details

Customization of the payment page

Field name Format Description Input Output

vads_available_languages Allows to specify the list of languages
Enum list x x
available on the payment page.
vads_language Defines the language of the payment page
a2 x x
(ISO 639-1 standard).
vads_iframe_options json Allows you to customize the background
color and the font of the input fields in x
iframe mode.
vads_shop_name Allows to define the shop name as it
ans..127 appears in the payment confirmation e- x x
mails.
vads_shop_url Allows to override the shop URL that
ans..1024 appears on the payment page and in x x
payment confirmation e-mails.
vads_theme_config Allows to customize certain elements on
map x
the payment page.
Table 36: Parameter list - Customizing the payment page

Hosted Payment Page - Document version 3.21

All rights reserved - 121 / 221
Redirection to the merchant website
Field name Format Description Input Output
vads_redirect_error_message Automatic redirection: x
Message displayed on the payment page
ans..255
prior to redirection after an accepted / a
declined payment
vads_redirect_error_timeout Automatic redirection: x
Delay (in seconds) before automatic
n..3
redirection to the merchant website after
an accepted / a declined payment
vads_redirect_success_message Automatic redirection: x
Specifies the message that will appear upon
ans..255
automatic redirection to the merchant
website if the payment has been accepted.
vads_redirect_success_timeout Automatic redirection: x
Allows to define a delay in seconds before
n..3 an automatic redirection to the merchant
website at the end of an accepted payment.
Its value is between 0 and 600s.
vads_return_mode Allows to specify the data transmission x
enum mode to the URLs of return to the merchant
website.
vads_url_cancel URL where the buyer will be redirected x
ans..1024 after having clicked on Cancel and return to
shop before proceeding to payment.
vads_url_check URL of the page to notify at the end of x
ans..1024 payment. Overrides the value entered in
the notification rules settings.
vads_url_check_src This parameter defines the triggering event x
enum
of the instant notification (also called IPN).
vads_url_error URL where the buyer will be redirected in x
ans..1024
case of an internal processing error.
vads_url_post_wallet URL on which the merchant will be recalled
ans..1024 x x
if a wallet is used during payment.
vads_url_refused URL where the buyer will be redirected in x
ans..1024
case of an internal processing error.
vads_url_return Default URL where the buyer will be x
ans..1024 redirected after having clicked on "Return
to shop".
vads_url_success URL where the buyer will be redirected in x
ans..1024
case of a successful transaction.
Table 37: Parameter list - Redirection to the merchant website

Hosted Payment Page - Document version 3.21

All rights reserved - 122 / 221
Recurring payment details
Field name Format Description Input Output
vads_identifier Unique identifier associated with a
ans..50 x x
payment method.
vads_identifier_status enum Mandate registration status. x
vads_recurrence_number Recurrence number of the recurring
n..2 x
payment
vads_recurrence_status enum Recurring payment status.
vads_sub_amount Amount of each installment except the
n..12 ones that will be eventually defined by the x
vads_sub_init_amount_number
vads_sub_currency Numeric code of the currency to be used for
n3 the recurring payment in compliance with x x
the ISO 4217
vads_sub_desc Rule for recurring payments to apply
ans..255 according to the iCalendar RFC5545 x x
specification.
vads_sub_effect_date n8 Recurring payment start date. x x
vads_sub_init_amount Amount of the first installments of the
n..12 x x
recurring payment.
vads_sub_init_amount_number Number of installments for which the
n..3 amount vads_sub_init_amount should be x x
applied.
vads_subscription ans..50 Recurring payment ID. x x
Table 38: Parameter list - Recurring payment details

Hosted Payment Page - Document version 3.21

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.Warning :
• 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 not
respect the rules established by the acquirer.
For a Conecs transaction, this field allows to transmit the amount eligible for Meal
Voucher (Titre-Restaurant) payment.

Input field.

Format json
Possible values Pour une transaction par titre-restaurant Conecs, le format JSON attendu est le
suivant :vads_acquirer_transient_data ={"CONECS":{"eligibleAmount":"1725"}}

Error codes 130, 133, 134, 135, 136, 137

Category Transaction details.

Hosted Payment Page - Document version 3.21

Description Mandatory parameter.

Data acquisition mode of the credit card details.

Input and output field, returned in the response (IPN and Return URL).
Format enum
Error code 47
Possible values INTERACTIVE: entry of the card details on the payment page of the payment gateway.

SILENT: entry of the card details on the merchant website (subject to the commercial
option provided by your bank).

IFRAME: entry of the card details on a simplified and streamlined payment page that
the merchant can embed into the web page of their choice.
Category Technical details

vads_amount

Description Transaction amount expressed in the smallest currency unit (cents for euro).
Example: for a transaction of 10 EURand 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).

Input and output field, returned in the response (IPN and Return URL).

Format n..12
Error code 09
Category Transaction details.

vads_auth_mode

Description Specifies the mode of the authorization request.

Output field, returned in the response (IPN and Return URL).

Format enum

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

Possible values
Value used in case of immediate payments, if the period between the requested
capture date and the current date is strictly shorter than the authorization validity
period.

Hosted Payment Page - Document version 3.21

All rights reserved - 125 / 221
MARK : corresponds to an authorization for 1 EUR (or information request about the
CB network if the acquirer supports it).
Value used for deferred payments if the period between the requested capture date
and the current date is strictly greater than the authorization validity period.

Category Transaction details.

vads_auth_number

Description Authorization number returned by the authorization server, if available (otherwise,

empty).

Output field, returned in the response (IPN and Return URL).

Format an..6
Category Transaction details

Hosted Payment Page - Document version 3.21

Description Return code of the authorization request returned by the issuing bank, if available.

Output field, returned in the response (IPN and Return URL).

Format n..3
Possible values

Grounds of Grounds of
Value Description Value Description
fraud fraud
00 Approved or successfully processed 38 Expired card
transaction
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 exceeded
credit 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 this YES
cardholder
13 Invalid amount YES 58 Transaction not allowed for this
cardholder
14 Invalid cardholder number YES 59 Suspected fraud YES
15 Unknown issuer YES 60 The acceptor of the card must
contact the acquirer
17 Canceled by the buyer 61 Withdrawal limit exceeded
19 Retry later 63 Security rules unfulfilled YES
20 Incorrect response (error on the 68 Response not received or received
domain server) too late
24 Unsupported file update 75 Number of attempts for entering the
secret code has been exceeded
25 Unable to locate the registered 76 The cardholder is already blocked, YES
elements in the file the previous record has been saved
26 Duplicate registration, the previous 90 Temporary shutdown
record has been replaced
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 network
route requested
33 Expired card YES 99 Initiator domain incident
34 Suspected fraud YES
Table 39: Return codes specific to the CB network

Hosted Payment Page - Document version 3.21

All rights reserved - 127 / 221
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
Table 40: Codes returned by the GICC network

Code Description
000 Approved
001 Approved with an ID
002 Partial approval (Prepaid Cards only)
100 Rejected
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

Hosted Payment Page - Document version 3.21

All rights reserved - 128 / 221
Code Description
900 Accepted - ATC Synchronization
909 System malfunction (cryptographic error)
912 Issuer not available
Table 41: Codes returned by AMEX Global acquirer

Code Description
0 Approved or successfully processed transaction
2 Limit exceeded
4 Keep the card
5 Do not honor
96 System malfunction
97 Overall monitoring timeout.
Table 42: Codes returned by Amex acquirer

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.

Category Transaction details.

Hosted Payment Page - Document version 3.21

Description Type of merchant protection used for the transaction.

Three values are possible:
• ELIGIBLE
Merchant is protected by PayPal's Seller Protection Policy for unauthorized
payments 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 Not
Received.
Concerns only the PayPal payment method.

Output field, returned in the response (IPN and Return URL).

Format enum
Category Order details.

Hosted Payment Page - Document version 3.21

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.

Input and output field, returned in the response (IPN and Return URL).
Format language1;language2;language3
Error code 71

Language Value Flag shown by default

Possible values
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 United
Kingdom.

Output field, returned in the response (IPN and Return URL).

Format a1

Code Visa MasterCard Discover American Express

Possible values
Y Address & 5- Address & 5-digit Address only Address & ZIP
digit or 9-digit ZIP ZIP match matches match
match
A Address matches, Address matches, Address & 5-digit Address only
ZIP does not ZIP does not ZIP match matches
S AVS not AVS not AVS not AVS not
supported supported supported supported
R System System Not applicable System
unavailable, retry unavailable, retry unavailable, retry
U Information not Information not System Information not
available available unavailable, retry available

Hosted Payment Page - Document version 3.21

All rights reserved - 131 / 221
Code Visa MasterCard Discover American Express
Z Either 5-digit or 5-digit ZIP 5-digit ZIP ZIP code only
9-digit ZIP match, matches, address matches, address matches
address does not does not does not
N Neither ZIP nor Neither ZIP nor Neither ZIP nor Neither ZIP nor
address match address match address match address match
W Not applicable For U.S., 9-digit Information not Not applicable
ZIP matches, available
address does not.
For non-U.S., ZIP
matches, address
does not
X Not applicable For U.S., all digits Address & 9-digit Not applicable
match. For non- ZIP match
U.S., ZIP and
address match.
B Address matches, Not applicable Not applicable Not applicable
ZIP not verified
T Not applicable Not applicable 9-digit ZIP Not applicable
matches, address
does not
P ZIP matches, Not applicable Not applicable Not applicable
address not
verified
C Address and ZIP Not applicable Not applicable Not applicable
not verified
D Address & Not applicable Not applicable Not applicable
ZIP match
(International
only)
G Address not Not applicable Not applicable Not applicable
verified for
International
(International
only)
I Address Not applicable Not applicable Not applicable
not verified
(International
only)
M Address & Not applicable Not applicable Not applicable
ZIP match
(International
only)
F Address & ZIP Not applicable Not applicable Not applicable
match (UK only)

Category Transaction details.

Hosted Payment Page - Document version 3.21

Description Code associated with the issuing bank.

Output field, returned in the response (IPN and Return URL).

Format n5
Category Payment method details.

vads_bank_product

Description Product code of the payment card.

Output field, returned in the response (IPN and Return URL).

Format an..3
Possible values

VISA Designation
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
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

Hosted Payment Page - Document version 3.21

All rights reserved - 133 / 221
VISA Designation
U Visa TravelMoney
V Visa VPay
W Reserved
X Reserved
Y Reserved
Z Reserved

Hosted Payment Page - Document version 3.21

All rights reserved - 134 / 221
MASTERCARD Designation
MPN MASTERCARD PREPAID DEBIT STANDARD-INSURANCE
MPO MASTERCARD PREPAID DEBIT STANDARD-OTHER
MPP MASTERCARD PREPAID CARD
MPR MASTERCARD PREPAID DEBIT STANDARD-TRAVEL
MPT MASTERCARD PREPAID DEBIT STANDARD-TEEN
MPV MASTERCARD PREPAID DEBIT STANDARD-VERNMENT
MPW DEBIT MASTERCARD BUSINESS CARD PREPAID WORK B2B
MPX MASTERCARD PREPAID DEBIT STANDARD-FLEX BENEFIT
MPY MASTERCARD PREPAID DEB STANDARD-EMPLOYEE INCENTIVE
MRG MASTERCARD PREPAID CARD
MRH MASTERCARD UNKNOWN PRODUCT
MRW PREPAID MASTERCARD BUSINESS CARD
MSG PREPAID MAESTRO CONSUMER RELOADABLE CARD
MSI MAESTRO CARD
MWB WORLD MASTERCARD FOR BUSINESS CARD
MWE WORLD ELITE MASTERCARD CARD
DLS DEBIT MASTERCARD CARD-DELAYED DEBIT
MCB MASTERCARD BUSINESSCARD CARD
MCC MASTERCARD CREDIT CARD (MIXED BIN)
MVOIR MASTERCARD FLEET CARD
MCG LD MASTERCARD CARD
MCO MASTERCARD CORPORATE CARD
MCP MASTERCARD PURCHASING CARD
MCS STANDARD MASTERCARD CARD
MCW WORLD MASTERCARD CARD
MDG LD DEBIT MASTERCARD CARD
MDH WORLD DEBIT EMBOSSED MASTERCARD CARD
MDP PLATINUM DEBIT MASTERCARD CARD
MDS DEBIT MASTERCARD CARD
MIU DEBIT MASTERCARD UNEMBOSSED
MNW MASTERCARD WORLD CARD
MOC MASTERCARD UNKNOWN PRODUCT
MPG DEBIT MASTERCARD STANDARD PREPAID-GENERAL SPEND
MPC MASTERCARD PROFESSIONAL CARD
MPL PLATINUM MASTERCARD CARD
MPP MASTERCARD PREPAID CARD
MRG MASTERCARD PREPAID CARD
MRO MASTERCARD REWARDS ONLY
MRW PREPAID MASTERCARD BUSINESS CARD
MSB MAESTRO SMALL BUSINESS CARD
MSI MAESTRO CARD
MSO MAESTRO PREPAID OTHER CARD
MSW PREPAID MAESTRO CORPORATE CARD
OLS MAESTRO-DELAYED DEBIT
TCB MASTERCARD BUSINESS CARD-IMMEDIATE DEBIT
TCC MASTERCARD (MIXED BIN)-IMMEDIATE DEBIT
TCG LD MASTERCARD CARD-IMMEDIATE DEBIT
TCS MASTERCARD STANDARD CARD-IMMEDIATE DEBIT
TCW WORLD SIGNIA MASTERCARD CARD-IMMEDIATE DEBIT
TIU MASTERCARD UNEMBOSSED — IMMEDIATE DEBIT
TNW MASTERCARD NEW WORLD-IMMEDIATE DEBIT
TPL PLATINUM MASTERCARD-IMMEDIATE DEBIT

Hosted Payment Page - Document version 3.21

CB Designation
1 National cash withdrawal card
2 National cash withdrawal and payment card
3 National payment card
4 National payment and cash withdrawal card requiring systematic authorization
5 National payment card requiring systematic authorization

Category Payment method details.

vads_birth_day

Description Date of birth of the cardholder.

Input field.

Format n..2
Error code 76
Category Payment method details.

vads_birth_month

Description Month of birth of the cardholder.

Input field.

Format n..2
Error code 76
Category Payment method details.

vads_birth_year

Description Year of birth of the cardholder.

Input field.

Format n4
Error code 76
Category Payment method details.

vads_brand_management

Description Indicates to the merchant:

• if the buyer has used a brand that is different from the one defined by default
by the merchant (userChoiceattribute),
• the brand chosen by the buyer (brand attribute),
• the list of available brands (brandList attribute).

Hosted Payment Page - Document version 3.21

All rights reserved - 136 / 221
This field is returned only if brand selection is enabled for the CB contract used for
the payment.
Output field, returned in the response (IPN and Return URL).

Format json
Possible values Example:
vads_brand_management={"userChoice":true,"brand":"CB","brandList":"CB|VISA"}

Category Payment method details.

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 Back
Office will be used. The default value can be configured in the Merchant Back Office
by all authorized persons.
Note:
• The value of vads_capture_delay is not taken into account in the case of
payment in installments MULTI_EXT.
• If the capture delay is higher than 365 days in the payment request, it will be
automatically reset to 365 days.

Input field.

Format n..3
Error code 06
Category Transaction details.

vads_card_brand

Description Payment method used, if available (empty otherwise).

The value is derived from the BIN range files.

Output field, returned in the response (IPN and Return URL).

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.

Category Payment method details.

vads_card_country

Description Country code of the card in compliance with the ISO 3166 standard

Output field, returned in the response (IPN and Return URL).

Format ISO 3166

Category Payment method details.

Hosted Payment Page - Document version 3.21

Description Name of the cardholder.

In Latin America, this parameter is required for DECIDIR and VISANET.

Input field.

Format ans..255
Error code 45
Category Payment method details.

vads_card_number

Description In the payment request

Card number (in case of a silent payment).
In the response
• Masked card number. 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 debit
payment.
The BIC is optional so the number may just be the IBAN.

Input and output field, returned in the response (IPN and Return URL).

Format an..36
Error code 40
Category Payment method details.

vads_change_rate

Description Exchange rate used to calculate the effective payment amount (multi-currency
payment).

Output field, returned in the response (IPN and Return URL).

Format string
Category Transaction details

Hosted Payment Page - Document version 3.21

Description Allows to:

• specify a list with a 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-commerce
Merchant IDs (MID) within the same network and when you wish to select a
different Merchant ID (MID) depending on the payment.
If this parameter is blank or missing, then the payment will be recorded with the
merchant IDs (MID) according to the priority order defined in the Merchant Back
Office (Settings > Shops > MID menu).

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
ACCORD Oney network (private and gift cards)
ACCORD_SANDBOX Oney network (private and gift cards) - sandbox mode
AMEX American Express network
AMEXGLOBAL American Express network
ANCV ANCV (e-chèques vacances) network
AURORE Cetelem Aurore network (Brand cards and universal Aurore card)
CARDCOMPLETE CARDCOMPLETE network
CB CB Network
CERIDIAN Ceridian network (gift card)
COFINOGA Cofinoga network (Be Smart and brand cards)
CONECS Titre-Restaurant Conecs network
EDENRED Edenred network (Tickets Restaurant, Tickets EcoChèque, Tickets
Compliments)
EPS EPS network
EVO EVO network
FULLCB FULL CB Network (Payment in 3 or 4 times without fees by BNPP PF)
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
GOOGLEPAY Google Pay network
HOBEX_DD Hobex Direct Debit network
IDEAL IDEAL network
JCB JCB Network
KLARNA Klarna Internet Banking network
MASTERPASS MasterPass network
ONEY Oney Network (Payment in 3 or 4 installments by FacilyPay)

Hosted Payment Page - Document version 3.21

All rights reserved - 139 / 221
Network code Description
ONEY_SANDBOX Oney Network (Payment in 3 or 4 installments by FacilyPay) - sandbox
mode
PAYDIREKT PayDirekt network
PAYLIB Paylib network
PAYPAL PayPal network
PAYPAL_SB PayPal network - sandbox
PAYSAFECARD Paysafecard network
POSTFINANCE POSTFINANCE Network
POSTFINANCEV2 POSTFINANCE Network
PPRO PPRO network
REDSYS RedSys network
SECURETRADING Secure Trading network
SEPA SEPA network (SDD and SCT)
SOFINCO Sofinco network
SOFORT Sofort Banking network
WIRECARD WIRECARD Network

Example to force the contract to use:

vads_contracts="CB=1231231;AMEXGLOBAL=949400444"

Example to forbid the payment within a specific network:

vads_contracts="CB=1231231;AMEXGLOBAL=NO"

Category Transaction details.

vads_contract_used

Description This field defines the value of the Merchant ID (MID) associated with the
transaction. It is populated with the Merchant ID (MID) registered by default in your
shop or it takes the value of the vads_contracts field sent in the payment request.

Output field, returned in the response (IPN and Return URL).

Format ans..250
Category Transaction details

vads_contrib

Description Optional information that indicates the name of the CMS used for the payment
(Joomla, osCommerce, etc.). If you are developing our own software, this field can
include the number of platform internal developer version

Input and output field, returned in the response (IPN and Return URL).

Format ans..128
Error code 31
Category Technical details

Hosted Payment Page - Document version 3.21

Description Mandatory parameter.

Defines the mode of interaction with the payment gateway.
Affects the choice of the key to be used (test or production) during signature
computation.
The TEST mode is available at all times, even after the generation of the production
key.
If you create a new e-commerce website (or have access to the acceptance testing
environment), you can make tests without impacting the website that is currently
in 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 code PROD instead of PRODUCTION
• Do not code the value in lowercase letters (test or production). This field expects
values only in uppercase letters without abbreviations.

Possible values TEST, PRODUCTION

Category Technical details

Hosted Payment Page - Document version 3.21

Description Numeric currency code to be used for the payment, in compliance with the ISO
4217 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 presented at
the moment of Merchant ID (MID) creation. If the desired currency is not suggested
at the moment of creation of your MID, please contact 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.

Input and output field, returned in the response (IPN and Return URL).
Format n3
Error code 10

Number of digits after

Possible values Currency ISO 4217 encoding
the 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
Turkish Lira (TRY) 949 2

Hosted Payment Page - Document version 3.21

All rights reserved - 142 / 221
Number of digits after
Currency ISO 4217 encoding
the decimal point
Euro (EUR) 978 2
Polish Zloty (PLN) 985 2
Brazilian Real (BRL) 986 2

Category Transaction details.

vads_cust_address

Description Buyer's postal address.

Note
The buyer's postal address is required if the purchaser has a bank account in the
following departments, territories or countries: Switzerland, Monaco, San Marino,
Mayotte, St. Pierre and Miquelon, Guernsey, Jersey, Isle of Man.

Input and output field, returned in the response (IPN and Return URL).

Format ans..255
Note:> and < are not authorized.

Error code 19
Note Mandatory parameter for 3xCB Cofinoga.
Category Buyer details.

vads_cust_address2

Description Second line of the address.

Input and output field, returned in the response (IPN and Return URL).

Format ans..255
Error code 19
Category Buyer details.

vads_cust_address_number

Description Buyer's street number.

Input and output field, returned in the response (IPN and Return URL).

Format ans..64
Error code 112
Category Buyer details.

vads_cust_cell_phone

Description Buyer's mobile phone number

Hosted Payment Page - Document version 3.21

Format an..32
Error code 77
Category Buyer details.

vads_cust_city

Description Buyer's city.

Input and output field, returned in the response (IPN and Return URL).

Format an..128
Error code 21
Note Mandatory parameter for 3xCB Cofinoga.
Category Buyer details.

vads_cust_country

Description Allows you to specify the buyer's country code in the ISO 3166 format.

Input and output field, returned in the response (IPN and Return URL).

Format a2
Error code 22
Examples of Code Country Code Country
possible values 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

Category Buyer details.

Hosted Payment Page - Document version 3.21

Description Buyer's district.

Input and output field, returned in the response (IPN and Return URL).

Format ans..127
Error code 113
Category Buyer details.

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 this
parameter in the form when you generate a payment request.

Input and output field, returned in the response (IPN and Return URL).

Format ans..150
Error code 15
Category Buyer details.

vads_cust_first_name

Description Buyer's first name.

Input and output field, returned in the response (IPN and Return URL).

Format ans..63
Error code 104
Note Mandatory parameter for 3xCB Cofinoga.
Category Buyer details.

vads_cust_id

Description Buyer ID (identification by the merchant).

Input and output field, returned in the response (IPN and Return URL).

Format an..63
Error code 16
Category Buyer details.

vads_cust_last_name

Description Buyer's last name.

Input and output field, returned in the response (IPN and Return URL).

Format ans..63

Hosted Payment Page - Document version 3.21

Description Buyer's legal name.

Input field.

Format an..100
Error code 121
Category Buyer details.

vads_cust_name

Description Buyer's name.

This field is deprecated. It is replaced by the vads_cust_first_name et
vads_cust_last_name fields

Input and output field, returned in the response (IPN and Return URL).

Format an..127
Error code 18
Category Buyer details.

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).

Input and output field, returned in the response (IPN and Return URL).

Format ans..255
Error code 124
Category Buyer details.

vads_cust_phone

Description Buyer's phone number.

Input and output field, returned in the response (IPN and Return URL).

Format an..32
Error code 23
Note Mandatory parameter for 3xCB Cofinoga.
Category Buyer details.

vads_cust_state

Description Buyer's state/region.

Hosted Payment Page - Document version 3.21

Format ans..127
Error code 88
Category Buyer details.

Hosted Payment Page - Document version 3.21

Description Buyer type.

Input and output field, returned in the response (IPN and Return URL).

Format enum
Error code 92
Possible values PRIVATE, COMPANY
Category Buyer details.

vads_cust_title

Description Buyer's title (e.g. Mr., Mrs., Ms.).

Input and output field, returned in the response (IPN and Return URL).

Format an..63
Error code 17
Category Buyer details.

vads_cust_zip

Description Buyer's postal code.

Input and output field, returned in the response (IPN and Return URL).

Format an..64
Error code 20
Category Buyer details.

vads_cvv

Description In the payment request

The card security code (in case of a silent payment).
In the response
Masked security number.

Its length can vary between 3 and 4 digits depending on the card type.

Input field.

Format n..4
Error code 43
Category Payment method details.

vads_effective_amount

Description Payment amount in the currency used for the capture.

Hosted Payment Page - Document version 3.21

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_amount = 1000
• vads_currency = 978
• vads_effective_amount = 1000

A payment of 10-US Dollar

Parameters sent in the payment form

• vads_amount = 1000
• vads_currency = 840

Returned parameters

• vads_amount = 1000
• vads_currency = 840
• 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

Parameters sent in the payment form

• vads_amount = 9000
• vads_currency = 978
• vads_payment_config=MULTI_EXT:date1=3000;date2=2000;date3=4000
Note : The MULTI_EXT value is not available for SEPA payment.

Returned parameters for the first installment

• vads_amount = 9000
• vads_currency = 978
• vads_effective_amount = 3000

Hosted Payment Page - Document version 3.21

• vads_amount = 9000
• vads_currency = 840
• vads_payment_config=MULTI_EXT:20121025=3000;20121026=2000;20121027=4000
Note : The MULTI_EXT value is not available for SEPA payment.

Returned parameters for the first installment

• vads_amount = 9000
• vads_currency = 840
• vads_change_rate= 1.3118 (exchange rate)
• vads_effective_amount = 2287 (amount of the 1st installment, 30$ / vads_change_rate)

Category Transaction details.

vads_effective_creation_date

Description Date of transaction registration in UTC format (GMT+0, 24H)

(YYYYMMDDHHMMSS).

Output field, returned in the response (IPN and Return URL).

Format n14
Category Transaction details

vads_effective_currency

Description Code of the currency used for the capture.

Output field, returned in the response (IPN and Return URL).

Format n3
Category Transaction details

Hosted Payment Page - Document version 3.21

Description Expiry month of the card used for the payment.

Input and output field, returned in the response (IPN and Return URL).

Format n..2
Error code 41
Category Payment method details.

vads_expiry_year

Description Expiry year of the card used for the payment.

Input and output field, returned in the response (IPN and Return URL).

Format n4
Error code 42
Category Payment method details.

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 the
setting up notification.

Syntax to respect:
vads_ext_info_fieldname=value

Input and output field, returned in the response (IPN and Return URL).

Format ans
Error code 91
Category Order details.

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

Hosted Payment Page - Document version 3.21

Description Allows to transmit the birth date indicated on the bill to the risk analyzer.
Format : yyyymmdd

Input field.

Format n8
Category Buyer details.

vads_ext_info_bil_gender

Description Specific to Brazil and to the ClearSale fraud analyzer.

Allows to specify on the receipt whether the buyer is male or female.

Input field.

Format n1
Category Buyer details.

vads_ext_info_deadline

Description Specific to Brazil and to the ClearSale fraud analyzer.

Allows to specify the delivery delay in days (N days).

Input field.

Format n
Category Shipping details.

vads_ext_info_donation

Description Parameter returned only in the instant notification URL (also called IPN) in case of
a donation
Transaction amount expressed in the smallest currency unit (cents for euro)

Output field, returned in the response (IPN and Return URL).

Format n..12
Category Donation details.

vads_ext_info_donation_recipient

Description Parameter returned only in the instant notification URL (also called IPN) in case of
a donation
HelloAsso ID of the donation recipient.

Output field, returned in the response (IPN and Return URL).

Format n..20

Hosted Payment Page - Document version 3.21

Description Parameter returned only in the instant notification URL (also called IPN) in case of
a donation
Name of the organization that received the donation.

Output field, returned in the response (IPN and Return URL).

Format string
Category Donation details

vads_ext_info_donation_merchant

Description Parameter returned only in the instant notification URL (also called IPN) in case of
a donation
ID of the shop that performed the donation.

Output field, returned in the response (IPN and Return URL).

Format n8
Category Donation details

vads_ext_info_donation_contribution

Description Parameter returned only in the instant notification URL (also called IPN) in case of
a donation
Transaction amount expressed in the smallest currency unit (cents for euro)

Output field, returned in the response (IPN and Return URL).

Format n..12
Category Donation details.

vads_ext_info_fingerprint_id

Description Specific to Brazil and to the ClearSale fraud analyzer.

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 the
identifier. The merchant website must make sure that each identifier is unique.
Any registration request containing an existing identifier will be rejected and an
error message will appear.

Input field.

Format string

Hosted Payment Page - Document version 3.21

All rights reserved - 156 / 221
It is encoded as 128 bytes and can contain uppercase or lowercase characters,
numbers or hyphens ([A-Z] [a-z], 0-9, _, -).

Category Buyer details.

vads_ext_info_ship_address_complement

Description Specific to Brazil and to the ClearSale fraud analyzer.

Allows to specify additional information about the shipping address.

Input field.

Format ans..250
Category Shipping details.

Hosted Payment Page - Document version 3.21

Description Allows to specify the buyer's date of birth for the shipping.
Format: yyyymmdd

Input field.

Format n8
Category Shipping details.

vads_ext_info_ship_gender

Description Specific to Brazil and to the ClearSale fraud analyzer.

Allows to specify for the shipping whether the buyer is male or female.

Input field.

Format n1
Category Shipping details.

vads_ext_trans_id

Description External transaction reference.

Example: Klarna reservation number, PayPal reservation number.

Output field, returned in the response (IPN and Return URL).

Format ans..20
Category Transaction details

Hosted Payment Page - Document version 3.21

Description Optional code of the response. Its meaning depends on the value entered in
vads_result.
• If vads_result equals 30 (request error), then vads_extra_result contains the
numeric code of the field with an error in the value or the format. This value
can 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 amount
specified in vads_amount is incorrect(for example, if the amount contains
decimals, as it would not have been converted to cents in advance).
• If vads_result equals 05 (declined) or 00 (accepted), vads_extra_result contains
the 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 in 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 Relevance verification: countries do not match (country IP address, card country,
buyer's country).
30 The country of the IP address is on the greylist.
99 Technical issue encountered by the server during a local verification process.

Output field, returned in the response (IPN and Return URL).

Category Technical details

vads_first_installment_delay

Description When the acquirer supports the parameter, this field allows to specify the number
of deferred months to be applied on the first due date of the payment in
installments (ex: Webpay Completa).
The payment will be declined and the vads_payment_error field will be valued at
171 in the following cases:
• the merchant is not allowed to defer payments
• the value transmitted in the request is not among the options authorized by
the acquirer.

Input field.

Format n..2
Error code N/A
Category Transaction details

Hosted Payment Page - Document version 3.21

Description A unique key returned only to the Instant Payment Notification (IPN).

Output field, returned in the response (IPN and Return URL).

Format an64
Category Technical details

vads_identifier

Description Unique identifier (token or Unique Mandate Reference) associated with a payment
method.
• Either this identifier is generated by the payment gateway.
In this case, this parameter must not be populated.
• Or it is generated by the merchant website.
In this case, this parameter must be populated with the desired value of the
identifier. Caution, it is the responsibility of the merchant website to make
sure the identifiers are unique. Any registration request containing an existing
identifier will be rejected and an error message will appear.

The input and output field, returned in the response (IPN and Return URL).

Format ans..50
Error code 30
Category Recurring payment details.

Hosted Payment Page - Document version 3.21

Description Appears only if the requested action concerns creating or updating:

• a token (subscription)
• a UMR (SEPA Unique Mandate Reference)

Output field, returned in the response (IPN and Return URL).

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, and
therefore 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, and
therefore 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 the 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 codes En cas d'erreur de format, le champ est ignoré et le formulaire de paiement n'est
pas refusé.
Category Customization of the payment page.

Hosted Payment Page - Document version 3.21

Description Insurance amount for the entire order.

Concerns only the PayPal payment method.

Input field.

Format n..12
Error code 110
Category Order details.

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 the
language of the buyer's browser.

In the response:
Returns the value specified in the form if the buyer has not changed the language
of the payment page.
Returns the language selected by the buyer if the buyer has changed it by clicking
on a different flag.

Input and output field, returned in the response (IPN and Return URL).

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

Hosted Payment Page - Document version 3.21

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 transaction
details 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 the
vads_nb_products field, it becomes mandatory to populate the other fields starting
with vads_product_.

Input field.

Format n..12
Category Order details.

vads_operation_type

Description Allows to distinguish debit, credit (refund) or verification operations when creating
or updating a token without the transaction.

Output field, returned in the response (IPN and Return URL).

Note
vads_operation_type field is not returned in the response when a payment is
canceled or abandoned.

Format enum
Possible values • DEBIT
• CREDIT
• VERIFICATION

Note
The vads_operation_type field is set to VERIFICATION in the following cases where
there is not transaction:
• vads_page_action = REGISTER
Creation of a token without payment
• vads_page_action = REGISTER_UPDATE
Update of information associated with the alias
• vads_page_action = REGISTER_SUBSCRIBE
Creation of a token during a subscription

Category Transaction details.

Hosted Payment Page - Document version 3.21

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 will
return an error.

Input and output field, returned in the response (IPN and Return URL).

Format ans..64
Error code 13
Category Order details.

vads_order_info

Description Order description.

Input and output field, returned in the response (IPN and Return URL).

Format an..255
Error code 14
Category Order details.

vads_order_info2

Description Order description.

Input and output field, returned in the response (IPN and Return URL).

Format an..255
Error code 14
Category Order details.

vads_order_info3

Description Order description.

Input and output field, returned in the response (IPN and Return URL).

Format an..255
Error code 14
Category Order details.

vads_override_payment_cinematic

Description Optional parameter.

Used by the merchant to request, on individual transactions, a payment workflow
different from that one specified in his contract. ("Payment workflow" field)

Input field.

Hosted Payment Page - Document version 3.21

All rights reserved - 164 / 221
Note
Only certain contracts exploit this parameter. If a value is selected in a contract that
does 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 by
the acquirer in the day of the transaction.
• DELAYED_CAPTURE
Corresponds to a workflow of deferred capture: the capture is triggered by the
payment gateway, always before the expiry of the authorization request.

Category Technical details

Hosted Payment Page - Document version 3.21

Description Mandatory parameter.

Defines the action to be performed.

Input and output field, returned in the response (IPN and Return URL).

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 alias
• REGISTER_PAY
Creation of a token during a payment
• REGISTER_SUBSCRIBE
Creation of a token during a subscription
• 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
• ASK_REGISTER_PAY
Payment with option for the cardholder to create an alias

Category Technical details

Hosted Payment Page - Document version 3.21

Description Contains the list of payment methods offered to the buyer, separated by ";".
If this list contains only one type of payment method, the data entry page for this
payment method will directly appear. If there is more than one payment method,
the payment method selection page will appear.
If this parameter is empty (recommended), the available payment methods
(currencies, technical constraints, etc.) associated with the shop will be offered.

Input field.

Format type1;type2;type3
Error code 08
The form will be rejected in the following cases:
• the transmitted value does not appear in the list below.
• the values TOUTES, ALL are not accepted. To provide all payment methods, this
parameter should not be posted or be posted empty.
• The transmitted value does not correspond to the payment method available
for your shop.
• Your e-commerce contract was closed by your banking institution. Contact the
customer service of your payment platform.
• The transmitted value is not eligible in the associated network.

Payment method Card types

Possible values
Accord brand card ACCORD_STORE
Accord brand card - Sandbox ACCORD_STORE_SB
Alinéa brand card ALINEA
Alinéa gift card ALINEA_CDX
Alinéa gift card - Sandbox ALINEA_CDX_SB
Alinéa brand card - Sandbox ALINEA_SB
Alipay ALIPAY
Allobébé gift card ALLOBEBE_CDX
Allobébé gift card - Sandbox ALLOBEBE_CDX_SB
American Express AMEX
Auchan brand card AUCHAN
Auchan brand card - Sandbox AUCHAN_SB
Aurore Card AURORE_MULTI
Bancontact Mistercash BANCONTACT
BizzBee gift card BIZZBEE_CDX
BizzBee gift card - Sandbox BIZZBEE_CDX_SB
Boulanger brand card BOULANGER
Boulanger brand card - Sandbox BOULANGER_SB
Brice gift card BRICE_CDX
Brice gift card - Sandbox BRICE_CDX_SB
CB CB
Be Smart Cofinoga Card COFINOGA
Conecs electronic meal vouchers CONECS
Apetiz electronic meal vouchers CONECS_APETIZ
Chèque Déjeuner electronic meal vouchers CONECS_CHQ_DEJ
Sodexo electronic meal vouchers CONECS_SODEXO

Hosted Payment Page - Document version 3.21

All rights reserved - 167 / 221
Payment method Card types
"CORA Blanche" Aurore card CORA_BLANCHE
"CORA Premium" Aurore card CORA_PREM
"CORA VISA" Aurore card CORA_VISA
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
Edenred Eco Chèque voucher EDENRED_EC
Culture Edenred voucher EDENRED_TC
Edenred meal voucher EDENRED_TR
Hobex direct debit ELV
EPS Online Überweisung EPS
EPS Online Überweisung/giropay EPS_GIROPAY
Payment in 3 installments with no fees with BNPP PF FULLCB_3X
Payment in 4 installments with no fees with BNPP PF FULLCB_4X
Giropay GIROPAY
Google Pay wallet payment GOOGLEPAY
iDeal Internet Banking IDEAL
Illicado Gift Card ILLICADO
JouéClub gift card - Sandbox mode ILLICADO_SB
JCB JCB
Jouéclub Gift Card JOUECLUB_CDX
JouéClub gift card - Sandbox mode JOUECLUB_CDX_SB
Jules gift card JULES_CDX
Jules gift card - Sandbox mode JULES_CDX_SB
Klarna Internet Banking KLARNA
Leroy-Merlin brand card LEROY-MERLIN
Leroy-Merlin brand card - Sandbox mode LEROY-MERLIN_SB
Maestro MAESTRO
Mastercard MASTERCARD
MasterPass MASTERPASS
Multibanco MULTIBANCO
Norauto brand card NORAUTO
Norauto brand card - Sandbox mode NORAUTO_SB
FacilyPay Oney ONEY
FacilyPay Oney - Sandbox mode ONEY_SANDBOX
PayDirekt PAYDIREKT
Wallet Paylib PAYLIB
PayPal PAYPAL
PayPal - Sandbox mode PAYPAL_SB
Paysafecard Prepaid Card PAYSAFECARD
PicWic brand card PICWIC
PicWic brand card - Sandbox PICWIC_SB
PostFinance POSTFINANCE
PostFinance E-finance POSTFINANCE_EFIN
SEPA CREDIT TRANSFER SCT
SEPA DIRECT DEBIT SDD
SEPA DIRECT DEBIT SDD
Soficarte card SOFICARTE

Hosted Payment Page - Document version 3.21

All rights reserved - 168 / 221
Payment method Card types
Sofort Banking SOFORT_BANKING
Truffaut Gift Card TRUFFAUT_CDX
Union Pay UNION_PAY
Villaverde brand card VILLAVERDE
Villaverde brand card - Sandbox VILLAVERDE_SB
Visa VISA
Visa Electron VISA_ELECTRON
Vpay VPAY
WeChat WECHAT

Category Transaction details.

vads_payment_certificate

Description This field is populated by the payment gateway if the authorization has been
successfully completed.

Output field, returned in the response (IPN and Return URL).

Format an40
Category Transaction details

Hosted Payment Page - Document version 3.21

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 be
set toMULTI: followed by key=value pairs separated by the ";" character .
The parameters are:
• "first" indicates the amount of the first installment (populated in the
smallest 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.

Note : The MULTI value is not available for SEPA payment.

• For an installment payment with a customized installment schedule, the value
must be set toMULTI_EXT: followed by the date=amount pairs separated by the
";" character.
The dates must not be passed

Note : The MULTI_EXT value is not available for SEPA payment.

The MULTI_EXT value requires a recurring payment to the Advanced installment
payment.
Note: The value of vads_capture_delay is not taken into account in the case of
payment in installments MULTI_EXT.

Input and output field, returned in the response (IPN and Return URL).

Format enum
Error code 07
Possible values • SINGLE
• MULTI:first= initial_amount;count=installments_nb ;period=interval_in_days
Note : The MULTI value is not available for SEPA payment.
• MULTI_EXT:date1=amount1;date2=amount2;date3=amount3
Note : The MULTI_EXT value is not available for SEPA payment.

Example 1 MULTI allows to define an installment payment.

The amount of each installment corresponds to the total amount divided by the
number of installments.
The amount of the first installment can be different, it can be specified in first
parameter.
In case the remaining amount does not equal zero, it will be added up to the
amount of the last installment.
Payment request:
• vads_capture_delay=2
• vads_currency=978

Hosted Payment Page - Document version 3.21

All rights reserved - 170 / 221
• 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 has
been added to the amount of the last installment.
This instruction allows to immediately create 4 payments with the same
transaction number but different sequence numbers (vads_sequence_number).

Example 2 MULTI_EXT allows to define a customized installment schedule. You will be able
to 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 date
of the last installment cannot be later than 12 months after the date of submission
of the form. If the last installment is scheduled later than the card expiry date, no
installment will be registered and the buyer will be notified about this issue.

Category Transaction details.

Hosted Payment Page - Document version 3.21

Description Error codes that may appear when a payment has been declined.

Output field, returned in the response (IPN and Return URL).

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.
14 Due to a technical problem, we are unable to process your request.
15 Due to a technical problem, we are unable to process your request.
16 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 error
reoccurs.
22 Shop not found.
23 Ambiguous MID.
24 Invalid MID
25 Due to a technical problem, we are unable to process your request.
26 Invalid card number.
27 Invalid card number.
28 Invalid card number.
29 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.
38 Due to a technical problem, we are unable to process your request.
39 3D Secure refusal for the transaction.
40 Due to a technical problem, we are unable to process your request.
41 Due to a technical problem, we are unable to process your request.
42 An internal error occurred while consulting the card number.
43 An internal error occurred while consulting the card number.

Hosted Payment Page - Document version 3.21

All rights reserved - 172 / 221
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}.
55 Due to a technical problem, we are unable to process your request.
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.
69 Due to a technical problem, we are unable to process your request.
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 been
declined.
74 Invalid payment configuration.
75 The operation has been declined by PayPal.
76 The cardholder's name is absent.
77 Due to a technical problem, we are unable to process your request.
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.
85 Due to a technical problem, we are unable to process your request.
87 Due to a technical problem, we are unable to process your request.
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.

Hosted Payment Page - Document version 3.21

All rights reserved - 173 / 221
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.
108 Due to a technical problem, we are unable to process your request.
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.
140 Due to a technical problem, we are unable to process your request.
141 The transaction has been declined by the risk analyzer.
142 The card type used is not valid for the requested payment mode.
143 Due to a technical problem, we are unable to process your request.
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 Secure
authentication).
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.
152 Due to a technical problem, we are unable to process your request.
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 to
perform the requested action. Reminder regarding a Facily Pay transaction: a refund must be made within two
days after the capture, the delay between two refunds is one day, a partial refund is limited to 20 days, a full
refund is limited to 6 months.
156 Operation not supported.
158 Due to a technical problem, we are unable to process your request.
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.

Hosted Payment Page - Document version 3.21

All rights reserved - 174 / 221
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.

Category Technical details

vads_payment_option_code

Description Code of the chosen option.

Input and output field, returned in the response (IPN and Return URL).

Format an..5
Error code 103
Category Transaction details

Hosted Payment Page - Document version 3.21

Description Details of performed transactions.

Output field, returned in the response (IPN and Return URL).

Format json
The vads_payment_seq field (json format) describes the split payment sequence.
It contains:
• "trans_id" : global transaction identifier to the payment sequence.
• "transaction" : transaction table of the sequence. It contains:
Field name Description
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 in
the 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 online
documentation 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 been
successfully created.
NOT_CREATED The authorization request has been declined.
The token (or UMR for SEPA payment) has not been
created, and therefore 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, and therefore cannot be viewed in the
Merchant Back Office.

presentation_date For a payments by card, this parameter is the requested capture date (ISO
8601 format).
trans_id Transaction number.
ext_trans_id This field is not sent for payments by credit cards.
trans_uuid Unique reference generated by the payment gateway after the creation of a
payment transaction.

Hosted Payment Page - Document version 3.21

Code Description
Empty No verification completed.
00 All the verification processes have been successfully completed.
02 Credit card velocity exceeded.
03 The card is in 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 Relevance verification: countries do not match (country IP
address, card country, buyer's country).
30 The country of the IP address is on the greylist.
99 Technical issue encountered by the server during a local
verification process.

sequence_number Sequence number.

trans_status Transaction status.
Table 43: JSON object content

Note: canceled transactions also appear in the table (information provided in the
JSONtrans_status parameter).

Category Transaction details.

vads_payment_src

Description Allows to define the payment source.

Output field, returned in the response (IPN and Return URL).

Format enum
Error code 60
Possible values Value Description
EC E-commerce: payment made on the payment page.
MOTO MAIL OR TELEPHONE ORDER: payment processed by an operator following a MOTO
order.
CC Call center: payment made through a call center
OTHER Other: payment made through a different source, e.g. Merchant Back Office

Category Transaction details.

vads_pays_ip

Description Buyer's country code and the IP address in the ISO 3166 format.

Output field, returned in the response (IPN and Return URL).

Format a2

Hosted Payment Page - Document version 3.21

vads_presentation_date

Description • Requested capture date.

or
• Requested presentation date for a SEPA Direct Debit.

Output field, returned in the response (IPN and Return URL).

Format n14
Category Transaction details

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 second
item, etc.)
The amount is expressed in the smallest currency unit. Cents for Euro.

Input field.

Format n..12
Error code 102
Category Order details.

vads_product_ext_idN

Description Corresponds to the product barcode on the merchant's website.

N corresponds to the reference of the article. (0 for the first item, 1 for the second
item, etc.)
Field transmitted to the Konduto fraud analyzer

Input field.

Format an..100
Error code 120
Category Order details

Hosted Payment Page - Document version 3.21

Description Allows to define the label of each item in the cart.

N corresponds to the reference of the article. (0 for the first item, 1 for the second
item, etc.)

Input field.

Format ans..255
Error code 97
Category Order details.

vads_product_qtyN

Description Allows to define the quantity of each item in the cart.

N corresponds to the reference of the article. (0 for the first item, 1 for the second
item, etc.)

Input field.

Format n..12
Error code 101
Category Order details.

vads_product_refN

Description Allows to define the reference of each item in the cart.

N corresponds to the reference of the article. (0 for the first item, 1 for the second
item, etc.)

Input field.

Format an..64
Error code 100
Category Order details.

Hosted Payment Page - Document version 3.21

Description Permet de définir le type de l'article contenu dans le panier.

N correspond à l'indice de l'article. (0 pour le premier, 1 pour le deuxième etc.)

Champ d'entrée.

Format enum
Code d'erreur 98

Valeurs possibles Valeur Description

FOOD_AND_GROCERY Produits alimentaires et d'épicerie
AUTOMOTIVE Automobile / Moto
ENTERTAINMENT Divertissement / Culture
HOME_AND_GARDEN Maison et jardin
HOME_APPLIANCE Equipement de la maison
AUCTION_AND_GROUP_BUYING Ventes aux enchères et achats groupés
FLOWERS_AND_GIFTS Fleurs et cadeaux
COMPUTER_AND_SOFTWARE Ordinateurs et logiciels
HEALTH_AND_BEAUTY Santé et beauté
SERVICE_FOR_INDIVIDUAL Services à la personne
SERVICE_FOR_BUSINESS Services aux entreprises
SPORTS Sports
CLOTHING_AND_ACCESSORIES Vêtements et accessoires
TRAVEL Voyage
HOME_AUDIO_PHOTO_VIDEO Son, image et vidéo
TELEPHONY Téléphonie
Table 44: Valeurs associées à vads_product-type0

Catégorie Informations sur la transaction.

vads_product_vatN

Description Allows to define the tax for each item in the cart.
N corresponds to the reference of the article. (0 for the first item, 1 for the second
item, etc.)

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 Euro : 14520 (for an amount of 145 Eurosand 20 cents)
• An integer less than 100 with a decimal separator
To display a percentage applied to the payment amount for the product in
question with maximum 4 digits after the decimal point.
Examples : 20.0 or 19.6532
Notes :

Hosted Payment Page - Document version 3.21

Category Order details.

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
Category Payment method details.

vads_proof_of_id_type

Description This field corresponds to the ID type selected by the buyer during the entry of the
payment card details.
In Latin America, this parameter is required for DECIDIR.

Input field.

Format enum
Error code 128
Category Payment method details.

vads_recurrence_number

Description Recurrence number of the subscription

Output field, returned in the response (IPN and Return URL).

Format n..2
Category Subscription details

vads_recurrence_status

Description Subscription status.

Appears only if the requested action concerns creating or updating
a subscription (REGISTER_SUBSCRIBE, SUBSCRIBE, REGISTER_PAY_SUBSCRIBE,
REGISTER_UPDATE_PAY).

Output field, returned in the response (IPN and Return URL).

Format string

Hosted Payment Page - Document version 3.21

All rights reserved - 181 / 221
Possible values Value Description
CREATED The subscription has been successfully created
The subscription details are visible in the Merchant Back Office.
NOT_CREATED The recurring payment has not been created and cannot be viewed in
the Merchant Back Office.
ABANDONED The request for creating a subscription has been abandoned by the
buyer (debtor).
The recurring payment has not been created and cannot be viewed in
the Merchant Back Office.

Category Subscription details.

Hosted Payment Page - Document version 3.21

Description Allows to define the message that will appear before automatic redirection to the
merchant 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 the

merchant 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 the
vads_url_refused field. If the parameter is not filled in, the buyer will be redirected
to the return URL entered in the vads_url_return field or to the return URL entered
in the Merchant Back Office. If the return URL is not set, it will be redirected to the
merchant website.

Input field.

Format n..3
Error code 36
Category Redirection to the merchant website.

Hosted Payment Page - Document version 3.21

Description Allows to specify the message that will appear upon automatic redirection to the
merchant website.

Input field.

Format ans..255
Error code 35
Category Redirection to the merchant website.

vads_redirect_success_timeout

Description Allows to define a delay in seconds before an automatic redirection to the

merchant 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 the
vads_url_success field. If the parameter is not filled in, the buyer will be redirected
to the return URL entered in the vads_url_return field or to the return URL entered
in the Merchant Back Office. If the return URL is not set, it will be redirected to the
merchant website.

Input field.

Format n..3
Error code 34
Category Redirection to the merchant website.

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 by
means of a signed document.
• S (= Yes)
The buyer's authorization is mandatory as the signed document will serve as
evidence of debt.

Input and output field, returned in the response (IPN and Return URL).

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

Hosted Payment Page - Document version 3.21

Description Return code of the requested action.

Output field, returned in the response (IPN and Return URL).

Format n2
Possible values Value Description
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 match with the value of the vads_extra_result field.
96 Technical details.

Category Technical details

vads_return_mode

Description Allows to specify the data transmission method used while returning to the
merchant website.

Input field.

Format enum
Error code 48

Field name Value Description

Possible values
absent, empty No parameters will be transmitted to the Return
or NONE URL.
GET The return fields will be transmitted to the return
URL in an HTTP GET form (in the "query string").
vads_return_mode POST The return fields will be transmitted to the return
URL in an HTTP POST form.
If the return to the shop in done from an
environment other than https, a security pop-up
message will be displayed to the buyer.

Category Redirection to the merchant website.

Hosted Payment Page - Document version 3.21

Description Returns the result of the risk management process performed by an external system
(Konduto, ClearSale, CyberSource, etc.).

Output field, returned in the response (IPN and Return URL).

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 the
response 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.
Table 45: Values common to all risk analyzers types

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 in
force.
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 the
parameters of the external risk analyzer.
RPP Order automatically declined. The order is reproved based on the customer or ClearSale policy
Table 46: Values returned by ClearSale

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 include
timeouts 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.
Table 47: Values returned by Cybersource

Hosted Payment Page - Document version 3.21

All rights reserved - 187 / 221
Konduto
APPROVE Konduto recommends to accept the transaction.
If no rule refute this recommendation, the transaction status will be AUTHORISED.
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 status
will be:
• AUTHORISED_TO_VALIDATE if the cardholder has successfully authenticated.
• REFUSED in case of authentication failure of the cardholder.

Table 48: Values returned by Konduto

Category Transaction details.

Hosted Payment Page - Document version 3.21

Description Returns the list of actions performed on the transaction, following the activation of
the advanced risk assessment activated in the Merchant Back Office.
When triggering multiple rules, the vads_risk_assessment_results field will consist of
multiple keywords separated by a ";".
Example:
vads_risk_assessment_results="ENABLE_3DS;MANUAL_VALIDATION"

Output field, returned in the response (IPN and Return URL).

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 the
desired 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 of
possible 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 or
SMS).

Category Transaction details.

Hosted Payment Page - Document version 3.21

Description Allows to define the result of the risk management process.

Output field, returned in the response (IPN and Return URL).

Format control1=result1;control2=result2
Possible values Value Description
CARD_FRAUD Verifies whether the cardholder's card number is in the
card greylist.
SUSPECT_COUNTRY Verifies whether the cardholder's card number is in the list
of forbidden countries.
IP_FRAUD Verifies whether the cardholder's IP address is in the IP
greylist.
CREDIT_LIMIT Verifies the purchase frequency and amounts for the same
card number, or the maximum amount of an order.
BIN_FRAUD Verifies whether the BIN code of the card is in the greylist
for 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 credit
card.
SYSTEMATIC_AUTO Verifies whether the buyer's card is a MAESTRO or VISA
ELECTRON credit card.
INCONSISTENT_COUNTRIES Verifies whether the country of the IP address, the country
of the payment card and the country of residence of the
buyer match.
NON_WARRANTY_PAYMENT Verifies the liability shift of the transaction.
SUSPECT_IP_COUNTRY Verifies whether the cardholder's country, identified by
his/her IP address, is in the list of forbidden countries.

The possible values for result are:

Value Description
OK OK
WARNING Informational control failed
ERROR Blocking control failed

Category Transaction details

Hosted Payment Page - Document version 3.21

Description Concerns donations only (or secondary transactions).

Allows to override the risk management configuration Verification of transfer of

responsibility for primary transactions.

Output field, returned in the response (IPN and Return URL).

Format enum
Error code 117
Possible values Value Description
DEFAULT or empty Default value. Applying shop settings.
IGNORE Ignore the value of transfer of responsibility for the primary transaction
before creating a secondary transaction.
CHECK Force the verification process of transfer of responsibility for the primary
transaction before creating a secondary transaction

Category Donation details

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 a
rejected payment, the sequence number will be incremented upon each new
attempt.
The number of additional attempts after a rejected payment can be configured via
the Merchant Back Office (menu Settings > Shop > Configuration).

If vads_payment_config = SINGLE:
vads_url_check_srcvads_sequence_number
Description
1 Payment made in 1 attempt
PAY 2 Payment made in 2 attempts
3 Payment made in 3 attempts
1 Deferred Payment made in 1 attempt
BATCH_AUTO 2 Deferred Payment made in 2 attempts
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 additional
attempts in case of rejected payment.

Note:
vads_sequence_number field is not returned in the response when a payment is
canceled or abandoned.

Hosted Payment Page - Document version 3.21

Category Transaction details.

vads_ship_to_city

Description Allows to specify the city for shipping.

Input and output field, returned in the response (IPN and Return URL).

Format an..128
Error code 83
Category Shipping details.

Hosted Payment Page - Document version 3.21

Description Allows you to specify the buyer's country code in the ISO 3166 standard.

Input and output field, returned in the response (IPN and Return URL).

Format a2
Error code 86
Examples of Code Country Code Country
possible values 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

Category Shipping details.

vads_ship_to_delay

Description Allows to define the speed depending on the shipping method when
vads_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.

Category Shipping details.

vads_ship_to_delivery_company_name

Description Allows to define the name of the transporter.

Input field.

Format ans..127
Error code 96
Category Shipping details.

vads_ship_to_district

Description Allows to define the shipping district.

Input and output field, returned in the response (IPN and Return URL).

Format ans..127

Hosted Payment Page - Document version 3.21

vads_ship_to_first_name

Description Allows to specify the buyer's first name

Input field.

Format ans..63
Error code 106
Category Shipping details.

vads_ship_to_last_name

Description Allows to specify the buyer's last name

Input field.

Format ans..63
Error code 107
Category Shipping details.

vads_ship_to_legal_name

Description Company name of the shipping location.

Input field.

Format an..100
Error code 125
Category Shipping details.

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_name
fields.

Input and output field, returned in the response (IPN and Return URL).

Format ans..63
Error code 80
Category Shipping details.

vads_ship_to_phone_num

Description Allows to specify the shipping buyer's phone number.

Input and output field, returned in the response (IPN and Return URL).

Hosted Payment Page - Document version 3.21

Description Allows to specify the shipping mode.

Input field.

Format enum
Error code 95
Possible values STANDARD, EXPRESS, PRIORITY
Note:
The use of PRIORITY as a value implies that the vads_ship_to_delay will be used.

Category Shipping details.

vads_ship_to_status

Description Allows to specify the type of the shipping address.

Input and output field, returned in the response (IPN and Return URL).

Format enum
Error code 93
Possible values PRIVATE, COMPANY
Category Shipping details.

vads_ship_to_state

Description Allows to specify the buyer's state for shipping.

Input and output field, returned in the response (IPN and Return URL).

Format ans..127
Error code 84
Category Shipping details.

Hosted Payment Page - Document version 3.21

Description Allows to specify the buyer's address.

Input and output field, returned in the response (IPN and Return URL).

Format ans..255
Note:> and < are not authorized.

Error code 81
Category Shipping details.

vads_ship_to_street2

Description Allows to specify the second line of the buyer's address.

Input and output field, returned in the response (IPN and Return URL).

Format ans..255
Note:> and < are not authorized.

Error code 82
Category Shipping details.

vads_ship_to_street_number

Description Allows to specify the shipping street number.

Input and output field, returned in the response (IPN and Return URL).

Format ans..64
Error code 114
Category Shipping details.

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 in an airport, a guard or a travel
agency.
• PACKAGE_DELIVERY_COMPANY for shipping by the transporter (Colissimo,
UPS, etc.).
• ETICKET for sending an electronic ticket, download.

Category Shipping details.

Hosted Payment Page - Document version 3.21

Description Information about the user who made the payment.

This parameter will be returned with the response and will include the value
transmitted in the request.
Note:
For backward compatibility, it is possible to use this field to set the CPF/CNPJ (legal
identifier in a numeric format between 11 and 20 digits long) required by the
ClearSale risk management module. However, vads_cust_national_id field can be
used.

The input and output field, returned in the response (IPN and Return URL).

Format ans..255
Error code 116
Category Shipping details.

vads_ship_to_zip

Description Allows to specify the buyer's postal code.

Input and output field, returned in the response (IPN and Return URL).

Format an..64
Error code 85
Category Shipping details.

vads_shipping_amount

Description Allows to transmit the shipping fees for the whole order

Input field.

Format n..12
Error code 109
Category Shipping details.

vads_shop_name

Description Allows to define the shop name as it appears in the summary at the end of
payment, the receipt and the payment confirmation e-mails.

The input and output field, returned in the response (IPN and Return URL).

Format ans..127
Error code 72
Category Customization of the payment page.

Hosted Payment Page - Document version 3.21

Description URL that appears on the payment page and in payment confirmation e-mails.
This setting overrides the default value of your shop.

Input and output field, returned in the response (IPN and Return URL).

Format ans..1024
Error code 73
Category Customization of the payment page.

vads_site_id

Description Mandatory parameter.

Generated while subscribing to the payment gateway.
Its value can be seen in the interface of the Merchant Back Office in Settings > Shop
> Certificates tab by all authorized persons.

If the value is not correct, when paying the buyer will get an error message on his
browser.
It becomes impossible to make the payment and the transaction is definitively lost.
A warning e-mail is then sent to the administrator contact. It contains the form that
the gateway could not process.

Input and output field, returned in the response (IPN and Return URL).

Format n8
Error code 02
Category Technical details

vads_subscription

Description Optional parameter used for creating a recurring payment. It designates the ID of
the recurring payment ID to create.
There are two choices:
• The payment gateway manages the IDs.
In this case, this parameter must not be populated.
In case the subscription is successfully created, the response will contain the
value generated by the payment gateway.
• The merchant website manages the IDs.
In this case, this parameter must be populated with the desired value of the
recurring payment ID.

There is no uniqueness check on the subscription ID.

When creating a recurring payment, the merchant site can fill
vads_subscription with an already existing value.

Hosted Payment Page - Document version 3.21

Input and output field, returned in the response (IPN and Return URL).

Format ans..50
Error code 63
Category Recurring payment details.

Hosted Payment Page - Document version 3.21

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 EURand 28 cents, the value of the parameter is
1028.

Input field.

Format n..12
Error code 65
Category Recurring payment details.

vads_sub_currency

Description Mandatory parameter used for creating a recurring payment.

It indicates the currency to use for the recurring payment, in compliance with the
ISO 4217 standard.

Input and output field, returned in the response (IPN and Return URL).

Format n3
Examples of The possible currencies are:
possible values
Number of digits after
Currency ISO 4217 encoding
the 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

Hosted Payment Page - Document version 3.21

All rights reserved - 201 / 221
Number of digits after
Currency ISO 4217 encoding
the decimal point
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
Turkish Lira (TRY) 949 2
Euro (EUR) 978 2
Polish Zloty (PLN) 985 2
Brazilian Real (BRL) 986 2

Error code 67
Category Recurring payment details.

vads_sub_desc

Description Mandatory parameter used for creating a subscription.

It designates the subscription rule to be applied.
The expected value for this parameter is a chain of characters that comply with
the iCalendar (Internet Calendar) specification, described in RFC5545 (seehttp://
tools.ietf.org/html/rfc5545).
Among other aspects, this specification allows to define complex subscription rules
via the RRULE property.
For technical reasons, it is not possible to define subscription periods that are
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 month
for 12 months, the rule is:
RRULE:FREQ=MONTHLY;BYMONTHDAY=28,29,30,31;BYSETPOS=-1;COUNT=12
This rule means that if the current month does not have 31 days, the machine
will take the 30th into account. If the 30th does not exist, the machine will 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
and October each year. The total number of installments depends on the
subscription start date (see vads_sub_effect_date parameter).

For more information and examples, visit http://recurrance.sourceforge.net/.

Hosted Payment Page - Document version 3.21

Format string
Error code 64
Category Subscription details

Hosted Payment Page - Document version 3.21

Description Mandatory parameter used for creating a subscription that allows to define the
subscription start date.
This parameter does not always match with the date of the first installment that
depends only on the vads_sub_desc parameter.
The effective date indicates when the recurring payment starts. The date format
is AAAAMMJJ.
Example: for February 1st 2015, enter 20150201.

Input and output field, returned in the response (IPN and Return URL).

Format n8
Error code 69
Category Subscription details

vads_sub_init_amount

Description Optional parameter used for creating a subscription. Represents the amount of the
first installments of the recurring payment.
The number of these first installments is defined by the
vads_sub_init_amount_number parameter.
This amount is presented in the currency defined by the vads_sub_currency
parameter 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.

Input and output field, returned in the response (IPN and Return URL).

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 installments
for 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

Input and output field, returned in the response (IPN and Return URL).

Format n..3

Hosted Payment Page - Document version 3.21

vads_tax_amount

Description Parameter that allows to define the amount of taxes for the entire order.
This amount will be presented in the smallest unit of the currency (Cents for Euro.).
Concerns only the PayPal payment method.

Input field.

Format n..12
Error code 108
Category Order details.

vads_theme_config

Description Allows to personalize certain elements on the payment page, such as the custom
template to be used, the button labels and some messages.
This parameter purpose a list of keywords (codes) corresponding to the elements
on the payment page and which are associated with a value.
Example:
vads_theme_config="SUBMIT_BUTTON_LABEL=PAY;TICKET_LABEL=PAYMENT RECEIPT"

See Advanced customization - Back Office user manual for more details on payment
page personalization.
Input field.

Format map
Error code 32

Possible values

Code Description
Functionalities
RESPONSIVE_MODEL Allows to override the custom template to be applied to the payment
pages.
Example of use:

vads_theme_config="RESPONSIVE_MODEL=Model_1"

The use of custom templates requires the activation of the "Advanced

customization" 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 "Advanced

customization" option.
SIMPLIFIED_DISPLAY Allows to reduce the volume of data to be loaded during the display of
the payment page.
Deletes the language and logo selector from the footer.

Hosted Payment Page - Document version 3.21

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 of
payment method selection, the card detail entry page, and the result
page 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 of
successful payment.
Example 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 successful
payment.
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 via
Settings > Customization > Payment pages tab > Logo group.
Example of use:

vads_theme_config="MERCHANT_MESSAGE=Transaction
summary"

SECURE_ MESSAGE Default value: The address of this website starting with https indicates
that you are on a secure page and can safely proceed to your payment.

Hosted Payment Page - Document version 3.21

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 website starting with https indicates
that you are on a secure page and can safely enter your bank details.
REGISTER_ON_PAYMENT Allows to customize the text of the checkbox that appears during
ASK_REGISTER_PAY.
Default value: I would like to register my payment method details for a
future 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 date
Information displayed only during an installment payment.
CUST_ID_LABEL Default value: Buyer reference
Information displayed only during a payment by token.
CUST_ADRESS_NUMBER_LABEL Default value: Address number
Information displayed only during a payment by token.
CUST_ADRESS_LABEL Default value: Address
Information displayed only during a payment by token.
CUST_ADRESS2_LABEL Default value: Second line of the address
Information displayed only during a payment by token.
CUST_DISTRICT_LABEL Default value: District
Information displayed only during a payment by token.
CUST_CITY_LABEL Default value: City
Information displayed only during a payment by token.
CUST_COUNTRY_LABEL Default value: Country
Information displayed only during a payment by token.
CUST_PHONE_LABEL Default value: Phone
Information displayed only during a payment by token.
CUST_NAME_LABEL Default value: Buyer's last name
Information displayed only during a payment by token.
RECURRENCE_AMOUNT_LABEL Default value: Amount per installment
Information displayed only during a payment by token.
RECURRENCE_INIT_AMOUNT_ Default value: Number of installments of initial amount
NUMBER_LABEL Information displayed only during a payment by token.
RECURRENCE_INIT_AMOUNT_LABEL Default value: Initial amount of the recurring payment
Information displayed only during a payment by token.
SHOP_LABEL Default value: SHOP
Information displayed only on the PDF receipt.
SITE_URL_LABEL Default value: URL address
Information displayed only on the PDF receipt.
CUST_LANGUAGE Default value: Language
Information displayed only on the PDF receipt.

Category Customization of the payment page.

vads_threeds_cavv

Description Indicates cardholder authentication via the ACS. Its value is populated by 3DS
authentication server (ACS) when the buyer has been correctly authenticated
(vads_threeds_status equals "Y" or "A").

Hosted Payment Page - Document version 3.21

Format ans..28
Error code 52
Category 3DS Authentication.

vads_threeds_cavvAlgorithm

Description Algorithm used by the ACS to generate the value of the CAVV
Its value is populated by 3DS authentication server (ACS) when the buyer has been
correctly authenticated (vads_threeds_status equals "Y" or "A").

Input and output field, returned in the response (IPN and Return URL).

Format n1
Error code 55

Value Description
Possible values
0 HMAC
1 CVV
2 CVV_ATN
3 MasterCard SPA

Category 3DS Authentication.

vads_threeds_eci

Description Indicates the e-commerce index.

Its value is populated by 3DS authentication server (ACS) when the buyer has been
correctly identified (vads_threeds_status equals "Y" or "A").
status =Y status = A status = U status =N
VISA and 5 6 7 -
AMEX
MasterCard 02 01 - -

Input and output field, returned in the response (IPN and Return URL).

Format n..2
Error code 53
Category 3DS Authentication.

vads_threeds_enrolled

Description Indicates the enrollment status of the cardholder. Its value is populated by the VISA
and MASTERCARD (DS) servers during 3D Secure authentication.

Input and output field, returned in the response (IPN and Return URL).

Format a1
Error code 51

Hosted Payment Page - Document version 3.21

All rights reserved - 208 / 221
Value Description
Possible values
Y Cardholder enrolled, 3DS authentication possible.
Note: In the Merchant Back Office, the ENROLLED value is displayed (3D Secure tab
in Transaction details).
N Cardholder not enrolled.
Note: In the Merchant Back Office, the NOT_ENROLLED value is displayed (3D
Secure 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 Secure
tab in Transaction details).

Category 3DS Authentication.

vads_threeds_error_code

Description Final status of the 3D Secure process.

This field is deprecated. It is replaced by the vads_threeds_exit_status field.

Output field, returned in the response (IPN and Return URL).

Format n..2
Category 3DS Authentication.

vads_threeds_exit_status

Description Final status of 3D Secure authentication.

Populated by the payment gateway.

Output field, returned in the response (IPN and Return URL).

Format n..2

Value Description
Possible values
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 (payment by token, PayPal, Cetelem, etc.)
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 not available for this payment channel (payment by file)
16 Card and network type eligible for 3DS, but no "brand" associated with the
card (pure CB)
98 Initialization of 3DS authentication OK
99 Unknown status

Hosted Payment Page - Document version 3.21

Category 3DS Authentication.

Hosted Payment Page - Document version 3.21

Description Enables / disables 3DS authentication for an e-commerce payment.

Input field.

Format n1
Error code 50

Value Description
Possible values
Absent 3DS authentication managed by the payment gateway (configuration by the merchant).
or
empty
0 3DS authentication managed by the payment gateway (configuration by the merchant).
1 3DS authentication completely managed by the merchant on the condition that the
vads_card_number field is populated (card data entered by the merchant).
In this case, the data produced by 3D Secure authentication initiated by the
MPI must be submitted in specific fields of the form (vads_threeds_enrolled,
vads_threeds_cavv, vads_threeds_eci, vads_threeds_xid, vads_threeds_cavvAlgorithm,
vads_threeds_status).
2 3DS authentication disabled for the transaction independently of the usual configuration
of the merchant.

Category 3DS Authentication.

vads_threeds_sign_valid

Description Indicates the validity of the PARes message signature. Its value is populated by the
payment gateway.

Output field, returned in the response (IPN and Return URL).

Format n1

Value Description
Possible values
empty 3DS unavailable.
0 Incorrect signature.
1 Correct signature.

Category 3DS Authentication.

Hosted Payment Page - Document version 3.21

Description Indicates the authentication status of the cardholder. Populated by the 3DS
authentication server (ACS) during the 3D Secure authentication.

Input and output field, returned in the response (IPN and Return URL).

Format a1
Error code 56

Value Description
Possible values
Y Successful authentication.
Note: In the Merchant Back Office, the SUCCESS value is displayed (3D Secure tab in
Transaction details).
N Authentication error.
Note: In the Merchant Back Office, the FAILED value is displayed (3D Secure tab in
Transaction details).
U Authentication impossible.
Note: In the Merchant Back Office, the UNAVAILABLE value is displayed (3D Secure tab in
Transaction details).
A Authentication attempt
Note: In the Merchant Back Office, the ATTEMPT value is displayed (3D Secure tab in
Transaction details).

Category 3DS Authentication.

vads_threeds_xid

Description Indicates the unique 3DS authentication reference.

Its value is populated by the authentication server (ACS) during the 3D Secure
authentication

Input and output field, returned in the response (IPN and Return URL).

Format ans..28
Error code 54
Category 3DS Authentication.

vads_token_id

Description Payment order ID associated with the transaction.

Corresponds to the offerId field of the paymentOfferResponse object >
offerEntities (see Implementation guide "SOAP Web service API Payment order").

Output field, returned in the response (IPN and Return URL).

Format ans..255

Category Order details.

Hosted Payment Page - Document version 3.21

Description Mandatory parameter.

Corresponds to the timestamp in the YYYYMMDDHHMMSS format
The timestamp must necessarily correspond to the current date and time, in the
GMT + 0 (or UTC) time zone in 24h format.
Note: If you are using Web Services, the vads_trans_date field will correspond to
the transmissionDate field. It is recommended to store this value in the database
to be able to set the correct value for transmissionDate when you make calls via
Web Services.

Input and output field, returned in the response (IPN and Return URL).

Format n14
Error code 04
Common mistakes:
• 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 will
generate 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.

Category Transaction details.

Hosted Payment Page - Document version 3.21

Description Mandatory parameter.

It consists of 6 numeric characters and must be unique for each transaction for a
given 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. It
must be between 000000 and 899999.
The numbers between 900000 and 999999 are reserved for refunds and operations
made via the Merchant Back Office.

Input and output field, returned in the response (IPN and Return URL).

Format n6
Error code 03
Common 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 on "Cancel and return to the shop", the transaction number
must be different for the next attempt as the previous one will be considered
as already used.
Otherwise, the message "The transaction has been canceled" will appear.

Category Transaction details.

Hosted Payment Page - Document version 3.21

Description Allows to define the transaction status.

Output field, returned in the response (IPN and Return URL).

Format enum
Possible values Value Description
ABANDONED Abandoned
payment abandoned by the buyer.
The transaction has not been created, and
therefore cannot be viewed in the Merchant
Back Office.
AUTHORISED Waiting for capture
The transaction has been accepted and will
be automatically captured at the bank on the
expected date.
AUTHORISED_TO_VALIDATE To be validated
The transaction, created with manual
validation, is authorized. The merchant must
manually validate the transaction in order for it
to be captured.
The transaction can be validated as long as the
expiration date of the authorization request
has not passed. If the authorization validity
period has passed, the payment status changes
to EXPIRED. The Expired status is final.
CANCELLED Canceled
The transaction has been canceled by the
merchant.
CAPTURED Captured
The transaction has been captured by the bank.
CAPTURE_FAILED The transaction capture has failed.
Contact the technical support.
EXPIRED Expired
The expiry date of the authorization request
has passed and the merchant has not validated
the transaction. The account of the cardholder
will, therefore, not be debited.
INITIAL Pending
This status concerns all the payment methods
that require integration via a payment form
with redirection.
This status is returned when:
• no response has been returned by the
acquirer
or
• the delay of the response from the acquirer
has exceeded the payment session on the
payment gateway.
This status is temporary. The final
status will be displayed in the Merchant
Back Office immediately after the
synchronization has been completed.

NOT_CREATED Transaction not created

The transaction has not been created, and
therefore cannot be viewed in the Merchant
Back Office.
REFUSED Rejected
Transaction is declined.

Hosted Payment Page - Document version 3.21

All rights reserved - 215 / 221
Value Description
SUSPENDED Suspended
The capture of the transaction is temporarily
blocked by the acquirer (AMEX GLOBAL or
SECURE TRADING). Once the transaction has
been correctly captured, its status changes to
CAPTURED.
UNDER_VERIFICATION For PayPal transactions, this value means that
PayPal withholds the transaction for suspected
fraud.
The payment will remain in the Transactions in
progress tab until the verification process has
been completed. The transaction will then take
one of the following statuses: AUTHORISED or
CANCELED.
A notification will be sent to the merchant to
warn them about the status change (Instant
Payment Notification on batch change).
WAITING_AUTHORISATION Waiting for authorization
The capture delay exceeds the authorization
validity period.
WAITING_AUTHORISATION_TO_VALIDATE To be validated and authorized
The capture delay exceeds the authorization
validity period.
An authorization of 1 EUR (or information
request about the CB network if the acquirer
supports it) has been accepted.
The merchant must manually validate the
transaction for the authorization request and
the capture to occur.
Table 49: Values associated with the vads_trans_status field

Category Transaction details.

vads_trans_uuid

Description Unique transaction reference generated by the payment gateway when creating
a payment transaction.
Guarantees that each transaction is unique.

Output field, returned in the response (IPN and Return URL).

Format ans32
Category Transaction details

vads_url_cancel

Description URL where the buyer will be redirected after having clicked on Cancel and return
to shop before proceeding to payment.

Input field.

Format ans..1024
Error code 27
Category Redirection to the merchant website.

Hosted Payment Page - Document version 3.21

Description URL of the page to notify at the end of payment. Overrides the value entered in
the 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 the
Merchant Back Office. The called URL is the URL that has been set up in the
notification rule (see chapter Setting up notifications).

Input field.

Format ans..1024
Error code 33
Category Redirection to the merchant website.

Hosted Payment Page - Document version 3.21

Description This parameter defines the source of the notification (also called IPN).

Output field, returned in the response (IPN and Return URL).

Format enum

Value Description
Possible values
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 acquirer
side (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.

Category Redirection to the merchant website.

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
Category Redirection to the merchant website.

vads_url_post_wallet

Description This field allows the merchant to transmit the URL to which the buyer will be
redirected 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 shipping
fees, register the payment method, etc.) before allowing the buyer to finalize his
or 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 the
payment session expires, a rejected transaction will be created. If the merchant
has configured the notification rule for abandoned/canceled transactions, the
merchant website will be notified about the reason of rejection via the
vads_payment_error field. This field will be set to149 indicating that the payment
session has expired.
It will then become visible in the Merchant Back Office, in the History tab

Hosted Payment Page - Document version 3.21

Format ans..1024
Error code 138
Category Redirection to the merchant website.

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 (code
02 Contact the card issuer) after having clicked on Return to shop.

Input field.

Format ans..127
Error code 26
Category Redirection to the merchant website.

vads_url_refused

Description URL where the buyer will be redirected in case of a declined payment after having
clicked on Return to shop.

Input field.

Format ans..1024
Error code 25
Category Redirection to the merchant website.

Hosted Payment Page - Document version 3.21

Description Default URL to where the buyer will be redirected after having clicked on Return to
shop, if vads_url_error, vads_url_refused, vads_url_success or vads_url_cancel is
not set.
If this field has not been transmitted, the Merchant Back Office configuration will
be taken into account.
It is possible to set up return URLs in TEST and PRODUCTION modes. These fields
are called Return URL of the shop in test mode and Return URL of the shop in
production mode; they can be viewed in Settings > Shop > Configuration.
If no URL has been specified in the Merchant Back Office and in the form, the
Return to shop button will redirect the buyer to the merchant website URL (URL
field in the shop configuration section).

Input field.

Format ans..1024
Error code 28
Category Redirection to the merchant website.

vads_url_success

Description URL where the buyer will be redirected in case of an accepted payment after having
clicked on Return to shop.

Input field.

Format ans..1024
Error code 24
Category Redirection to the merchant website.

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 and
will include the value transmitted in the request.
In the case of a MOTO payment from the Merchant Back Office, this field will be
valued 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 (legal
identifier in a numeric format between 11 and 20 digits long) required by the
ClearSale risk management module. However, vads_cust_national_id field can be
used.

Input and output field, returned in the response (IPN and Return URL).

Format ans..255
Error code 61
Category Buyer details.

Hosted Payment Page - Document version 3.21

Description Specifies the validation mode of the transaction

Input and output field, returned in the response (IPN and Return URL).

Format enum
Error code 05

Value Description
Possible values
Absent or Takes the value specified in the Merchant Back Office
empty
0 Automatic validation by the payment gateway.
1 Manual validation by the merchant.

Category Transaction details.

vads_version

Description Mandatory parameter.

Version of the exchange protocol with the payment gateway

Input and output field, returned in the response (IPN and Return URL).

Format enum
Error code 01
Possible value V2
Category Technical details

vads_warranty_result

Description Liability shift in case of accepted payment.

Output field, returned in the response (IPN and Return URL).

Format enum

Value Description
Possible values
YES The payment is guaranteed.
NO The payment is not guaranteed.
UNKNOW Due to a technical error, the payment cannot be guaranteed.
Not specified Liability shift not applicable

Category Transaction details.

Hosted Payment Page - Document version 3.21

The - 1000 - Project - Canna - Campbell 2 PDF
100% (2)
The - 1000 - Project - Canna - Campbell 2 PDF
178 pages
SPARK Matrix - Card Management System (CMS) - 2022 - BPC - Full Report - Quadrant Knowledge Solutions Jan 2023
100% (1)
SPARK Matrix - Card Management System (CMS) - 2022 - BPC - Full Report - Quadrant Knowledge Solutions Jan 2023
54 pages
Cybersource Guide
No ratings yet
Cybersource Guide
107 pages
BDO Supplementary Application Form
No ratings yet
BDO Supplementary Application Form
1 page
Best Practices For Better Usage of Response Codes Version 2.0 Effective April 2021 - ENG
No ratings yet
Best Practices For Better Usage of Response Codes Version 2.0 Effective April 2021 - ENG
28 pages
John Citizen
No ratings yet
John Citizen
1 page
Clear 2 Pay
No ratings yet
Clear 2 Pay
2 pages
PAYFORT Merchant Integration Guide V 10.0
No ratings yet
PAYFORT Merchant Integration Guide V 10.0
302 pages
E Wallet User MasterCard
No ratings yet
E Wallet User MasterCard
12 pages
MC PayPass Terminals
No ratings yet
MC PayPass Terminals
31 pages
iSeries-AS/400 MICR Printing Made Easy
No ratings yet
iSeries-AS/400 MICR Printing Made Easy
11 pages
Ach Process
No ratings yet
Ach Process
2 pages
Frozen Food Packaging - Freedonia
0% (1)
Frozen Food Packaging - Freedonia
8 pages
Web Service API: Integration Guide
No ratings yet
Web Service API: Integration Guide
124 pages
BPE 3.0 Service Creditcards.1.06
No ratings yet
BPE 3.0 Service Creditcards.1.06
12 pages
PayPal NVP API Developer Guide
100% (1)
PayPal NVP API Developer Guide
165 pages
PFP ExpressCheckout PP
No ratings yet
PFP ExpressCheckout PP
84 pages
PayWay API Developers Guide
No ratings yet
PayWay API Developers Guide
48 pages
PHP Payment Gateway Integration
No ratings yet
PHP Payment Gateway Integration
5 pages
1029
No ratings yet
1029
12 pages
"ITGEL MM" V 1.5 Softpay
No ratings yet
"ITGEL MM" V 1.5 Softpay
18 pages
Ach Streamline
No ratings yet
Ach Streamline
47 pages
Payment Gateways
100% (1)
Payment Gateways
11 pages
Chip Card Acceptance Device Ref Guide 6 (1) .0
No ratings yet
Chip Card Acceptance Device Ref Guide 6 (1) .0
143 pages
Payment Gateways in India
No ratings yet
Payment Gateways in India
14 pages
Payment Processing Glossary - WePay
No ratings yet
Payment Processing Glossary - WePay
15 pages
Interchange Fees and Their Impact On Small Businesses
No ratings yet
Interchange Fees and Their Impact On Small Businesses
8 pages
EMV v4.3 Book 4 Other Interfaces 20120607062305603-1 PDF
No ratings yet
EMV v4.3 Book 4 Other Interfaces 20120607062305603-1 PDF
154 pages
I5310 A2C User Manual
No ratings yet
I5310 A2C User Manual
52 pages
Online Payments
No ratings yet
Online Payments
21 pages
Credit Cards SO API
No ratings yet
Credit Cards SO API
517 pages
White Paper - All About Ecommerce and Payment Gateways
No ratings yet
White Paper - All About Ecommerce and Payment Gateways
8 pages
Visa Pin Security Program Guide Public
No ratings yet
Visa Pin Security Program Guide Public
33 pages
E Banking e Payments
No ratings yet
E Banking e Payments
7 pages
PCCharge DevKit - v5.7.1 Release I SP8 - User's Manual PDF
No ratings yet
PCCharge DevKit - v5.7.1 Release I SP8 - User's Manual PDF
471 pages
Transaction Acceptance Device Guide TADG V3 May 2015 PDF
No ratings yet
Transaction Acceptance Device Guide TADG V3 May 2015 PDF
273 pages
Mobile Payments
No ratings yet
Mobile Payments
36 pages
Visa Merchant Data Standards Manual PDF
No ratings yet
Visa Merchant Data Standards Manual PDF
106 pages
What Is Electronic Funds Transfer (EFT) ?
No ratings yet
What Is Electronic Funds Transfer (EFT) ?
2 pages
IMPS Online Switching Specification Newv3 3docx
No ratings yet
IMPS Online Switching Specification Newv3 3docx
96 pages
API Documentation October 18, 2016
No ratings yet
API Documentation October 18, 2016
37 pages
Paytm Payment Solutions Feb15 PDF
No ratings yet
Paytm Payment Solutions Feb15 PDF
30 pages
MasterCard JJ
No ratings yet
MasterCard JJ
7 pages
VISA Ais Guide Stepspcicompliant
No ratings yet
VISA Ais Guide Stepspcicompliant
15 pages
Bank of Maldives: Head Office, Boduthakurufaanu Magu Male
No ratings yet
Bank of Maldives: Head Office, Boduthakurufaanu Magu Male
22 pages
FD Globalgatewayconnect Usermanualnorthamerica
No ratings yet
FD Globalgatewayconnect Usermanualnorthamerica
86 pages
Unit-4.4-Payment Gateways
No ratings yet
Unit-4.4-Payment Gateways
8 pages
Payment Gateway Analysis
No ratings yet
Payment Gateway Analysis
18 pages
Salvador Mendoza - PINATA - PIN Automatic Try Attack
No ratings yet
Salvador Mendoza - PINATA - PIN Automatic Try Attack
26 pages
Visa Pin Security Program Auditors Guide
No ratings yet
Visa Pin Security Program Auditors Guide
97 pages
Visa Perso Data PDF
No ratings yet
Visa Perso Data PDF
5 pages
Internet Payment Gateway
100% (1)
Internet Payment Gateway
25 pages
Verifone VX680 User Manual PDF
No ratings yet
Verifone VX680 User Manual PDF
13 pages
Online Paymet Systems
No ratings yet
Online Paymet Systems
23 pages
Online Payment Processing:: What You Need To Know
No ratings yet
Online Payment Processing:: What You Need To Know
14 pages
Merchant Acquiring (POS) Training Manual
100% (1)
Merchant Acquiring (POS) Training Manual
62 pages
3D-Secure Programmers Guide
No ratings yet
3D-Secure Programmers Guide
14 pages
EMV Issuer Security Guidelines: Emvco, LLC
No ratings yet
EMV Issuer Security Guidelines: Emvco, LLC
33 pages
MasterCard Authentication Guide Europe
No ratings yet
MasterCard Authentication Guide Europe
75 pages
TechTrex Company & SecurePro Introduction V16
No ratings yet
TechTrex Company & SecurePro Introduction V16
27 pages
VISA CC Acceptance Device Testing
No ratings yet
VISA CC Acceptance Device Testing
36 pages
Risk-based authentication A Complete Guide
From Everand
Risk-based authentication A Complete Guide
Gerardus Blokdyk
No ratings yet
Review of Some Free Remote Desktop Protocol (RDP) Services
From Everand
Review of Some Free Remote Desktop Protocol (RDP) Services
Dr. Hidaia Mahmood Alassouli
No ratings yet
ISO 8583 Complete Self-Assessment Guide
From Everand
ISO 8583 Complete Self-Assessment Guide
Gerardus Blokdyk
No ratings yet
Canada's Role in the Payment Processing Industry
From Everand
Canada's Role in the Payment Processing Industry
Robert Ronning
No ratings yet
Digital Banking Products
100% (1)
Digital Banking Products
68 pages
Mexico Payments Systems
No ratings yet
Mexico Payments Systems
35 pages
Synopsis
No ratings yet
Synopsis
20 pages
GUBA CARD Application Form - Access Bank-1
No ratings yet
GUBA CARD Application Form - Access Bank-1
2 pages
Visa Debit Cards - HMB
No ratings yet
Visa Debit Cards - HMB
12 pages
Bulletin No. 2., S. 2020 - SVMA-Power Mac Center Partnership and Start of Classes
No ratings yet
Bulletin No. 2., S. 2020 - SVMA-Power Mac Center Partnership and Start of Classes
2 pages
Wald Imports-Stimulus Sale
No ratings yet
Wald Imports-Stimulus Sale
24 pages
uiduacujasd
No ratings yet
uiduacujasd
11 pages
AmBank Aggrmnt
No ratings yet
AmBank Aggrmnt
12 pages
Payment: Onward Journey Ticket Details
No ratings yet
Payment: Onward Journey Ticket Details
1 page
Colt Custom Shop Order Form
100% (1)
Colt Custom Shop Order Form
8 pages
NEW2017WESTERNUNIONSCAMTUTORIAL
100% (2)
NEW2017WESTERNUNIONSCAMTUTORIAL
5 pages
RTOM Part 1
No ratings yet
RTOM Part 1
47 pages
Questionnaire On Consumer Awareness and Perception About Credit Cards in India
100% (1)
Questionnaire On Consumer Awareness and Perception About Credit Cards in India
6 pages
Consent Order
No ratings yet
Consent Order
11 pages
China Digital Payments
No ratings yet
China Digital Payments
15 pages
Visa Internship - JD - 2025
No ratings yet
Visa Internship - JD - 2025
2 pages
Chapter 2
No ratings yet
Chapter 2
21 pages
RFP of CERT
No ratings yet
RFP of CERT
62 pages
UBL Final Project Report
No ratings yet
UBL Final Project Report
87 pages
Credit Card Application Form
No ratings yet
Credit Card Application Form
8 pages
World Converted Flexible Packaging: Industry Study With Forecasts For
No ratings yet
World Converted Flexible Packaging: Industry Study With Forecasts For
8 pages
NSCC Application
No ratings yet
NSCC Application
4 pages
Credit Card Fees and Charges
No ratings yet
Credit Card Fees and Charges
2 pages
CSR-MCIC Credit or Debit Card Payments Salvatore Maggiacomo RIA000484210 Encrypted
No ratings yet
CSR-MCIC Credit or Debit Card Payments Salvatore Maggiacomo RIA000484210 Encrypted
1 page