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.

Example:

A test file was submitted on 30/11/2016 for the shop 12345678. It contains two payment requests with the following parameters:

First installment:

  • UMR: ‘MY-UMR-TEST-1
  • Transaction number: 000001
  • Amount: €32.99

Second installment:

  • UMR: ‘MY-UMRTEST-2
  • Transaction number: 000002
  • Amount: €7.90

  1. The name of the file must respect 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 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

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

    Empty 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

  4. 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 example:

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.

It allows:

  • 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