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://paiement.systempay.fr/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:
  • 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 pairs ​​separated by a “;”.

Each key/value pair contains the name of the key followed by “=”, followed by a value.

The value can be:
  • a chain of characters
  • a boolean
  • a json object
  • an xml object

The list of possible values ​​​​for each key/value pair is provided in the field definition.

Example: vads_theme_config=SIMPLIFIED_DISPLAY=true;RESPONSIVE_MODEL=Model_1

  • 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 Defines the mode of interaction with the payment gateway. enum TEST or PRODUCTION
    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 an 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.: 20200101130025
    vads_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
      • CVCONNECT
      • PAYLIB
      • MASTERCARD
      • VISA
    • 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 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.: 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 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.

  • 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 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 Second line of the address 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 Quantity of items. 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_.

  • 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"/>