V2 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 | 02 |
| 02 | Shop ID | 12345678 |
| 03 | Mode | TEST or PRODUCTION |
| 04 | Channel | ALL |
Detail record
| Pos. | Description |
|---|---|
| 01 | Description: Defines the sending channel: Type: VARCHAR | Length: 32 | Required Hosted Payment Page equivalent: N/A REST API equivalent: channelOptions.channelType Possible values:
E.g.: MAIL |
| 02 | 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 Page equivalent: vads_page_action REST API equivalent: formAction Possible values:
E.g.: PAYMENT |
| 03 | Description: Payment order reference or order ID. The only accepted special character is “-”. For an invoice payment order, this reference must be unique and the data mandatory. Type: VARCHAR | Length: 64 | Optional Hosted Payment Page equivalent: vads_order_id REST API equivalent: orderId E.g.: CX-1254 |
| 04 | Description: Transaction amount expressed in the smallest currency unit. The amount cannot be populated with 0, unless the operation to be performed (Position 02) is "REGISTER". Type: NUMERIC | Length: 13 | Required Hosted Payment Page equivalent: vads_amount REST API equivalent: amount E.g.: 4525 for EUR 45.25 |
| 05 | Description: Numeric code of the currency (ISO 4217 standard). Type: NUMERIC | Length: 3 | Required Must correspond to the currency of the company. Hosted Payment Page equivalent: vads_currency REST API equivalent: currency E.g.: 978 for euro (EUR) (See chapter List of supported currencies in appendix) |
| 06 | Description: Buyer’s e-mail address. Mandatory for an e-mail payment order. Type: VARCHAR | Length: 255 | Optional Hosted Payment Page equivalent: vads_cust_email REST API equivalent: customer.email E.g.: sample@example.net |
| 07 | Description: Shipping buyer’s phone number Mandatory for SMS payment orders Type: VARCHAR | Length: 255 | Optional Hosted Payment Page equivalent: N/A REST API equivalent: channelOptions.smsOptions.phoneNumber E.g.: +33600000000 |
| 08 | 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 Page equivalent: vads_validation_mode REST API equivalent: cardOptions.manualValidation Possible values:
E.g.: 0 |
| 09 | Description: Description of the invoice. The field is only taken into account for an invoice payment order. This description will be displayed to the buyer after the entry of the invoice reference in the data collection form. To guide the buyer and to reassure him/her, the “Description” area allows the merchant to display information specifying the invoice to his/her buyer. This description is displayed when the buyer clicks the “?” symbol to the right of the “Reference” entry field. To be in compliance with the GDPR, it is recommended to limit the display of personal information in this field. For example, for rent payment, specify the billing period and the reference of the accommodation rather than the name of the tenant. Type: VARCHAR | Length: 128 | Optional Hosted Payment Page equivalent: vads_order_description REST API equivalent: description E.g.: My order description |
| 10 | 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 |
| 11 | Do not populate. |
| 12 | 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 Page equivalent: vads_threeds_mpi REST API equivalent: strongAuthentication Possible values:
E.g.: NO_PREFERENCE |
| 13 | Description: Using the data collection form. This field must be set to true, if transmitted. Type: BOOLEAN | Length: 1 | Optional Hosted Payment Page equivalent: N/A REST API equivalent: dataCollectionForm E.g.: true |
| 14 | Do not populate. |
File samples
- basic example:
02;12345678;TEST;ALL MAIL;REGISTER_PAY;CX-1253;3500;978;sample@example.net;;;;;;;; URL;PAYMENT;CX-1255;4000;978;sample@example.net;;;;;;;; SMS;PAYMENT;CX-1254;3000;978;;+330600000000;;;;;;true; INVOICE;PAYMENT;CX-1256;2000;978;sample@example.net;;;My order description;;;;;
- advanced example:
02;12345678;TEST;ALL MAIL;PAYMENT;CX-1253;3500;978;sample@example.net;+330600000000;0;;20240603;;NO_PREFERENCE;true; MAIL;REGISTER;CX-1254;0;978;sample@example.net;+330600000000;0;;20240603;;;; URL;PAYMENT;CX-1255;4500;978;sample@example.net;+330600000000;0;;20240603;;NO_PREFERENCE;true; SMS;PAYMENT;CX-1256;3000;978;sample@example.net;+330600000000;0;;20240603;;NO_PREFERENCE;;
Download the sample pack: https://sogecommerce.societegenerale.eu/doc/files/samples/sample-files.zip.
You will find sample files in the PaymentOrder/V2 folder.