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.

Example:

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

  1. The name of the file must comply with the format <YYYYMMDD>.<siteID>.PAY.REQ.<z>.<xx>.

    Where:

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

  2. 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    		  
  3. 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 validation

    Empty: 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

  4. 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 Merchant Back Office via the menu: Management > TEST recurring payments > Payment request.

It allows:

  • 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.