Generating a payment file
The payment request file will consists of a series of records.
A "record" is a list of parameters separated by ";" that end with a carriage return. Thus, there is one record on every line.
This format type is generally called "CSV" (Comma Separated Values), and is notably 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.
A test file was submitted on 30/11/2016 for the shop 12345678. It contains two payment requests with the following parameters:
- UMR: ‘MY-UMR-TEST-1’
- Transaction number: 000001
- Amount: €32.99
- UMR: ‘MY-UMRTEST-2’
- Transaction number: 000002
- Amount: €7.90
- The name of the file must respect 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 of the file within a day, in 2 numeric characters.
The name of the file in the example is 20161130.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 Environement (TEST or PRODUCTION) TEST vads_ctx_mode 06 Creation date n8 In the YYYYMMDD format 07 Time of creation n6 In the 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 the YYYYMMDD format vads_trans_date 04 Transaction time n6 In the HHMMSS format vads_trans_date 05 05 n..6 Unique on a given day and shared with other payment modes vads_trans_id 06 Transaction type a2 CD 07 Amount n..12 In cents. vads_amount 08 Euro currency code n3 978 vads_currency 09 Expected due date n8 In the YYYYMMDD format, leave 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 Unique Mandate Reference ans..50 UMR to use for the direct debit vads_identifier 12 The commercial contract to use for the payment. 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 19 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 Equivalent 01 Record code n2 01 02 Number of transmitted detail records n..6 2
File name: 20161130.12345678.PAY.REQ.T.01
00;PAY;02;12345678;TEST;20161130;102008; 02;1;20161130;102008;000001;CD;3299;978;;;MY-UMRTEST-1;;;;; 02;2;20161130;102008;000002;CD;790;978;;;MY-RUM-TEST-2;;;;; 01;2
To assist you in integration, a validation interface is available in the Back Office via the menu: Management > Test recurring payments > Payment request.
- To verify the structure of the file before submitting it
- To import the TEST payment file
- To create TEST payments on the basis of the imported file