V1 Format

Each file must consist of a series of records.

A “record” is a list of parameters separated by the “;” character ending with a carriage return.

The files are structured as follows:

  • A header record containing transmission details.
  • A variable number of records, each corresponding to a payment order.

Notes for Microsoft Excel users
  • A “record” corresponds to a line in the spreadsheet.
  • The header record is the first line of the file.
  • The positions (“Pos.”) indicated in the tables below (01, 02 etc.) correspond to the columns of your spreadsheet. For example: “Pos. 01” corresponds to the column A, “Pos. 02” corresponds to the column B.
  • If you do not want to enter the data, leave the corresponding cell empty.
  • Make sure all the cells are in “Text” format.

The header record

Pos. Description Values
01 Header version 01
02 Shop ID 12345678
03 Mode TEST or PRODUCTION
04 Channel MAIL

Detail record

Pos. Description
01 Description: Defines the action to be performed. If the field is sent empty, the "PAYMENT” value is applied by default.

Type: VARCHAR | Length: 32 | Optional

Hosted Payment Form equivalent: vads_page_action

REST API equivalent: formAction

Possible values:
  • PAYMENT: Payment.
  • REGISTER: Recording of the payment method, without payment.

    Requires an amount set to “0”. Not compatible with the use of the data collection form.

  • REGISTER_PAY: Recording of the payment method during the payment. Not compatible with the use of the data collection form.
  • ASK_REGISTER_PAY: Payment with possibility for the cardholder to record the payment method. Not compatible with the use of the data collection form.

E.g.: PAYMENT

02 Description: Payment order reference or order ID. The only accepted special character is “-”.

Type: VARCHAR | Length: 64 | Optional

Hosted Payment Form equivalent: vads_order_id

REST API equivalent: orderId

E.g.: CX-1254

03 Description: Transaction amount expressed in the smallest currency unit . The amount cannot be populated with 0.

Type: NUMERIC | Length: 13 | Required

Hosted Payment Form equivalent: vads_amount

REST API equivalent: amount

E.g.: 4525 for EUR 45.25

04 Description: Numeric code of the currency (ISO 4217 standard).

Type: NUMERIC | Length: 3 | Required

Must correspond to the currency of the company.

Hosted Payment Form equivalent: vads_currency

REST API equivalent: currency

E.g.: 978 for euro (EUR) (See chapter List of supported currencies in appendix)

05

Description: Buyer’s e-mail address.

Type: VARCHAR | Length: 255 | Required

Hosted Payment Form equivalent: vads_cust_email

REST API equivalent: customer.email

E.g.: sample@example.net

06 Description: Validation mode. For more information, see the chapter Configuring the default validation mode of the “Transaction management” user manual.

Type: NUMERIC | Length: 1 | Optional

Hosted Payment Form equivalent: vads_validation_mode

REST API equivalent: cardOptions.manualValidation

Possible values:
  • 0: for automatic validation
  • 1: for manual validation
  • Empty: for using the default validation mode.

E.g.: 0

07

Description: Description of the invoice. The field is ignored for an e-mail payment order.

Type: VARCHAR | Length: 255 | Optional

08 Description: Expiry date of the payment order. Cannot be before the current date and may not exceed 90 days. If this parameter is not sent, the value defined in the shop configuration will be applied (Settings > Shop menu, Configuration tab).

Type: NUMERIC | Length: 8 | Optional

Hosted Payment Page equivalent: N/A

REST API equivalent: expirationDate

E.g.: 20210603

09 Description: Field specific to Latin America. Tax rate applied to the entire order. The value must be the percentage to be applied (19.6 for 19.6%).

Type: NUMERIC | Length: 4 | Optional

Hosted Payment Form equivalent: vads_tax_rate

REST API equivalent: taxRate

E.g.: 19.6

10 Description: Merchant preference regarding 3DS authentication. If the field is sent empty, the “NO_PREFERENCE” value is applied by default.

Type: VARCHAR | Length: 32 | Optional

Hosted Payment Form equivalent: vads_threeds_mpi

REST API equivalent: strongAuthentication

Possible values:
  • FRICTIONLESS: Authentication request without buyer interaction.
  • NO_PREFERENCE: Transfer to the card issuer.
  • CHALLENGE_REQUESTED: Authentication request with buyer interaction.
  • CHALLENGE_MANDATE: Authentication request with buyer interaction for regulatory reasons.

E.g.: NO_PREFERENCE

11 Description: Using the data collection form. May be sent with the ‘true’ value only if the action be performed is PAYMENT.

Type: BOOLEAN | Length: 1 | Optional

Hosted Payment Page equivalent: N/A

REST API equivalent: dataCollectionForm

Possible values:
  • true
  • false (default value)

E.g.: true

File samples

  • basic example:
01;12345678;TEST;MAIL
PAYMENT;CX-1254;3000;978;sample@example.net;;;;;;
REGISTER;CX-1255;0;978;sample@example.net;;;;;;
REGISTER_PAY;CX-1256;3990;978;sample@example.net;;;;;;
ASK_REGISTER_PAY;CX-1257;11000;978;sample@example.net;;;;;;

  • advanced example:
01;12345678;TEST;MAIL
PAYMENT;CX-1254;3000;978;sample@example.net;0;;20210603;;NO_PREFERENCE;true
REGISTER;CX-1255;0;978;sample@example.net;0;;20210603;;NO_PREFERENCE;
REGISTER_PAY;CX-1256;3990;978;sample@example.net;0;;20210603;;NO_PREFERENCE;
ASK_REGISTER_PAY;CX-1257;11000;978;sample@example.net;0;;20210603;;NO_PREFERENCE;

Download the sample pack: https://paiement.systempay.fr/doc/files/samples/sample-files.zip.

You will find sample files in the MAIL folder.