Generating a payment file (REQ)
The payment request file consists of a series of records.
A “record” is a list of parameters separated by the “;” character ending with a carriage return. Thus, there is one record on every line.
This format type is generally called "CSV" (Comma Separated Values), and is recognized by MS Excel.
The file will have the following structure:
- A header record containing transmission details.
- A variable amount of records containing details of payments to be made.
- A trailer record that allows to verify the consistency of the transmitted file.
The number of records present in the files directly affects the amount of time it will take to process the file as well as the availability of the return file.
Beyond 2,000 records it is recommended to generate several payment files.
A test file was submitted on 30/11/2018 for the 12345678 store. It contains two payment requests with the following parameters:
First payment by token:
- ID: ‘TEST-TOKEN-1’
- Transaction number: 000001
- Amount: 935,99 EUR
Second payment by token:
- ID: ‘TEST-TOKEN-2’
- Transaction number: 000002
- Amount: 75,90 EUR
- The name of the file must comply with the format <YYYYMMDD>.<siteID>.PAY.REQ.<z>.<xx>.
- <YYYYMMDD> represents the date when the file was generated.
- <siteID> represents the shop number that has been assigned to you (vads_site_id).
- <z> takes either the value "T" for a file in TEST mode, or "P" for a file in PRODUCTION mode.
- <xx> represents the sequential number (2 numeric characters) of the file within the same day.
The name of the file in the example is 20181130.12345678.PAY.REQ.T.01
- Populate the header record with the following values:
Pos. Description Format Values Equivalent 01 Record code n2 00 02 File type PAY 03 File version n2 02 04 Shop ID n8 12345678 vads_site_id 05 Environment (TEST or PRODUCTION) TEST vads_ctx_mode 06 Creation date n8 In YYYYMMDD format 07 Time of creation n6 In HHMMSS format 08 Requested execution date. n8
Reserved for future use.Do not populate
- Populate each detail record respecting the format below:
Pos. Description Format Values Equivalent 01 Record code n2 02 02 Sequence number of the detail record in the file. n..6 Starts at 1 03 Transaction date n8 In YYYYMMDD format vads_trans_date 04 Transaction time n6 In HHMMSS format vads_trans_date 05 Transaction identifier n..6 Unique within the same day and shared with other payment modes vads_trans_id 06 Transaction type a2 CD 07 Amount n..12 In its smallest currency unit. vads_amount 08 Currency code n3 E.g.: 978 for euro (EUR) vads_currency 09 Requested capture date n8 In YYYYMMDD format
Empty to indicate the current date
10 Validation mode n..1
0: for automatic validation
1: for manual validationEmpty: for using the default validation mode
vads_validation_mode 11 Card token ans..50 Card token to use for the direct debit vads_identifier 12 Merchant ID to be used. ans..250 Leave empty for using the default contract. vads_contract_used 13 Order reference ans..32 Leave empty if not used vads_order_id 14 Details of order 1 ans..255 Leave empty if not used vads_order_info 15 Details of order 2 ans..255 Leave empty if not used vads_order_info2 16 Details of order 3 ans..255 Leave empty if not used vads_order_info3
- Populate the trailer record respecting the format below:
Pos. Description Format Values 01 Record code n2 01 02 Number of transmitted detail records n..6 E.g.: 2.
It is recommended to not exceed 2,000 records per file.
Example of a file:
File name: 20181130.12345678.PAY.REQ.T.01
00;PAY;02;12345678;TEST;20181130;102008; 02;1;20181130;102008;000001;CD;93599;978;;;TEST-TOKEN-1;;;;; 02;2;20181130;102008;000002;CD;7590;978;;;TEST-TOKEN-1;;;;; 01;2
To assist you in integration, a validation interface is available in the Expert Back Office via the menu: Management > TEST recurring payments > Payment request.
- to check the structure of the file to be submitted,
- to import the TEST payment file,
- to create TEST payments on the basis of the imported file.