Sending a payment form via POST
The merchant website redirects the buyer to the payment gateway using a POST form from HTML to HTTPS.
This form 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://sogecommerce.societegenerale.eu/vads-payment/" attribute that defines where to send the form data.
Form data:
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 be computed incorrectly and the form will be rejected.
Please, consult the table below that indicates required formats.
| Notation | Description |
|---|---|
| a | Alphabetic characters (from ‘A’ to ‘Z’ and from ‘a’ to ‘z’) |
| n | Numeric characters |
| s | Special characters |
| an | Alphanumeric characters |
| ans | Alphanumeric and special characters (except ‘<’ and ‘>’) |
| 3 | Fixed length of 3 characters |
| ..12 | Variable length up to 12 characters |
| json | JavaScript Object Notation. Object containing key/value pairs separated by commas. It starts with a left brace " {" and ends with a right brace " }". Each key/value pair contains the name of the key between double-quotes followed by “:” followed by a value. The name of the key must be alphanumeric. The value can be:
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 pairs separated by a “;”. Each key/value pair contains the name of the key followed by “=”, followed by a value. The value can be:
The list of possible values for each key/value pair is provided in the field definition. Example: vads_theme_config=SIMPLIFIED_DISPLAY=true;RESPONSIVE_MODEL=Model_1 |
- Required fields:
Field name Description Format Value signature Signature guaranteeing the integrity of the requests exchanged between the merchant website and the payment gateway. ans Ex :
ycA5Do5tNvsnKdc/eP1bj2xa19z9q3iWPy9/rpesfS0=
vads_action_mode Acquisition mode for payment method data enum INTERACTIVE vads_amount Payment amount in the smallest currency unit (cents for euro) n..12 E.g.: 4525 for EUR 45.25 vads_ctx_mode Mode of interaction with the payment gateway enum TEST orPRODUCTION vads_currency Numeric currency code to be used for the payment, in compliance with the ISO 4217 standard (numeric code). n3 E.g.: 978 for euro (EUR) vads_page_action Action to perform enum PAYMENT vads_payment_config Payment type enum SINGLE for immediate payment MULTI for installment payment
vads_site_id Shop ID n8 E.g.: 12345678 vads_trans_date Date and time of the payment form in UTC format n14 Respect the YYYYMMDDHHMMSS format
E.g.: 20200101130025vads_trans_id Transaction number. Must be unique within the same day (from 00:00:00 UTC to 23:59:59 UTC).
Warning: this field is not case sensitive.
an6 E.g.: xrT15p vads_version Version of the exchange protocol with the payment gateway enum V2 - Highly recommended fields:
- The payment method to be used
Field name Description Format Value vads_payment_cards Allows to force the card type to be used. It is recommended to provide a different payment button for each payment method on the merchant website.
It is recommended not to leave the field empty.See chapter Managing the payment methods offered to the buyer of the Hosted Payment Page Implementation guide for more information.
enum E.g.: - CB
- CVCO
- MASTERCARD
- VISA
- SDD
- Order details
Field name Description Format Value vads_order_id Order ID Can contain uppercase or lowercase characters, numbers or hyphens ([A-Z] [a-z], 0-9, _, -).
ans..64 E.g.: 2-XQ001 vads_order_info Additional order info ans..255 E.g.: Door code 3125 vads_order_info2 Additional order info ans..255 E.g.: No elevator vads_order_info3 Additional order info ans..255 E.g.: Express vads_ext_info_xxxx Additional information necessary for the merchant that will be displayed both in the payment confirmation e-mail sent to the merchant and in the Merchant Back Office (Extra tab of the transaction details). xxxx corresponds to the name of the transmitted data.
For example: vads_ext_info_departure_city
ans..255 E.g.: LHR - Buyer details
Field name Description Format Value vads_cust_email Buyer’s e-mail address ans..150 E.g.: ABC@example.com vads_cust_id Buyer reference on the merchant website an..63 E.g.: C2383333540 vads_cust_national_id National identifier ans..255 E.g.: 940992310285 vads_cust_title Buyer’s title an..63 E.g.: M vads_cust_status Status enum
PRIVATE: for a private individual COMPANY: for a company
vads_cust_first_name First name ans..63 E.g.: Laurent vads_cust_last_name Last name ans..63 E.g.: Durant vads_cust_legal_name Buyer’s legal name an..100 E.g.: D. & Cie vads_cust_phone Phone number an..32 E.g.: 0467330222 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 Address line 2 ans..255 E.g.: vads_cust_district District ans..127 E.g.: Centre ville 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 the ISO 3166 alpha-2 standard a2 E.g.: "FR" for France, "PF" for French Polynesia, "NC" for New Caledonia, "US" for the United States.
- The payment method to be used
- Recommended fields:
- Shipping details
Field name Description Format Value vads_ship_to_city City an..128 E.g.: Bordeaux vads_ship_to_country Country code in compliance with the ISO 3166 standard (required for triggering one or more actions if the Shipping country control profile is enabled). a2 E.g.: FR 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 Last 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 shipping address. enum
PRIVATE: for shipping to a private individual 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 Address line 2 ans..255 vads_ship_to_zip Zip code an..64 E.g.: 33000 - Shopping cart details
Field name Description Format Value vads_nb_products Number of items in the cart n..12 E.g.: 2 vads_product_ext_idN Product barcode on the merchant website. N corresponds to the index of the item (0 for the first one, 1 for the second one, etc.). an..100 E.g.: vads_product_ext_id0 = "0123654789123654789"
vads_product_ext_id1 = "0223654789123654789"
vads_product_ext_id2 = "0323654789123654789"
vads_product_labelN Item name. N corresponds to the index of the item (0 for the first one, 1 for the second one, etc.). ans..255 E.g.: vads_product_label0 = "tee-shirt"
vads_product_label1 = "Biscuit"
vads_product_label2 = "sandwich"
vads_product_amountN Price of the item incl. VAT. N corresponds to the index of the item (0 for the first one, 1 for the second one, etc.). n..12 E.g.: vads_product_amount0 = "1200"
vads_product_amount1 = "800"
vads_product_amount2 = "950"
vads_product_typeN Item type. N corresponds to the index of the item (0 for the first one, 1 for the second one, etc.). enum E.g.: vads_product_type0 = "CLOTHING_AND_ACCESSORIES"
vads_product_type1 = "FOOD_AND_GROCERY"
vads_product_type2 = "FOOD_AND_GROCERY"
vads_product_refN Item reference. N corresponds to the index of the item (0 for the first one, 1 for the second one, etc.). an..64 E.g.: vads_product_ref0 = "CAA-25-006"
vads_product_ref1 = "FAG-B5-112"
vads_product_ref2 = "FAG-S9-650"
vads_product_qtyN Item quantity. N corresponds to the index of the item (0 for the first one, 1 for the second one, etc.). n..12 E.g.: vads_product_qty0 = "1"
vads_product_qty1 = "2"
vads_product_qty2 = "2"
Note:
When the vads_nb_products field is populated, the Shopping cart tab becomes available in the transaction details in the Merchant Back Office.
However, if the other fields that start 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 that start with vads_product_.
- Shipping details
- Optional fields :
You can use additional optional parameters.
See the chapter Data Dictionary of the Hosted Payment Page Implementation guide available on our web site to see the list of the available fields.
The Pay button that will allow to send data:
<input type="submit" name="pay" value="Pay"/>