Analyzing the return file (ANS)
There are two categories of errors:
- formatting errors and/or field value errors,
- errors related to the execution of payments.
The gateway processes files in two stages:
- the first stage serves to verify the integrity of the file and to detect errors of format and/or values. In case of error, the file is rejected completely.
During this first stage, only global file checks are performed. The more detailed errors are processed during the second stage.
-
During the second stage, payments are executed line by line. If an error is detected in one of the parameters (e.g.: id not found, incorrect currency, etc.), the processing code will get a value of 30 in the detailed record and an additional field will indicate the position of the data in question. In case of payment rejection, the source of the error will be indicated in the detail record.
In the first error case, the file with the result will contain only a header record with the error and the trailer record. The merchant will have to correct and re-submit the file after modifying its name.
In the second case, the result file will contain the same amount of detail records as the request file. Only the payments with an error detected in one of the parameters will have to be submitted one more time by the merchant.
If there is an issue on the platform which does not allow it to process the error in time, they will be analyzed when the platform is functioning properly again. Therefore, there is no need to re-submit the unprocessed payments in a new file.
Here is a response to our sample file 20161130.12345678.PAY.REQ.T.01
The name of response file is 20161130.12345678.PAY.ANS.T.01.
Its content is:
00;PAY;02;0;;12345678;TEST;20161130;102008;20140922;141349 02;1;20161130;102008;000001;CD;3299;978;20140922;0;; FR7630002005701234567890158;;;;;00;0;;FULL;20140922;141350;00; FR7630002005701234567890158_CRLYFRPP;20170922 02;2;20161130;102008;000002;CD;790;978;20140922;0;MY-TEST-UMR-2; FR7630002005701234567890158;;;;;00;0;;FULL;20140922;141351;00; FR7630002005701234567890158_CRLYFRPP;20170922 01;2;2;0
Format of the header:
Pos. | Description | Format | Values | Equivalent in the data dictionary |
---|---|---|---|---|
01 | Record code | n2 | 00 | |
02 | File type | PAY | ||
03 | File version | n2 | 02 | |
04 | Return code of the first stage of processing | n1 |
0: Processing completed 1: Format error 2: Value error |
|
05 | Information about the error | ans..255 | Additional information about the error, empty if successfully completed. | |
06 | Shop ID | n8 | Same as in the request, if valid. | vads_site_id |
07 | Environment | Same as in the request, if valid. | vads_ctx_mode | |
08 | Creation date | n8 | Same as in the request, if valid. | |
09 | Time of creation | n6 | Same as in the request, if valid. | |
10 | End date of processing In YYYYMMDD format |
n8 | 20161130 | |
11 | End time of processing | n6 | 130019 |
Format of detailed record:
Pos. | Description | Format | Values | Equivalent in the data dictionary |
---|---|---|---|---|
01 | Record code | n2 | 02 | |
02 | Sequence number | n..6 | Same as the value used in the request, if valid | |
03 | Transaction date (same as the value used in the request, if valid) | n8 | Same as the value used in the request, if valid | vads_trans_date |
04 | Transaction time (same as the value used in the request, if valid) | n6 | Same as the value used in the request, if valid | vads_trans_date |
05 | Transaction ID (same as the value used in the request, if valid) | n..6 | Same as the value used in the request, if valid | vads_trans_id |
06 | Transaction type (same as the value used in the request, if valid) | a2 | CD | |
07 | Amount (same as the value used in the request, if valid) | n..12 | Same as the value used in the request, if valid | vads_amount |
08 | Currency | n3 | Same as the value used in the request, if valid | vads_currency |
09 | Countervalue of the amount in euro | n..12 | Same as the value used in the request, if valid | vads_effective_amount |
10 | Countervalue currency | n3 | Same as the value used in the request, if valid | |
11 | n8 | Same as the value used in the request, if valid | ||
12 | Validation mode | n1 |
0 if automatic validation 1 if manual validation |
vads_validation_mode |
13 | ans..50 | Same as the value used in the request, if valid | vads_identifier | |
14 | Merchant ID | n7 | MID used to process this request | |
15 | Order reference | ans..32 | Same as the value used in the request, if valid | vads_order_id |
16 | Information about transaction 1 | ans..255 | Same as the value used in the request, if valid | vads_order_info |
17 | Information about transaction 2 | ans..255 | Same as the value used in the request, if valid | vads_order_info2 |
18 | Information about transaction 3 | ans..255 | Same as the value used in the request, if valid | vads_order_info3 |
19 | Return code of processing |
Examples:
|
vads_result | |
20 | Authorization return code | an..2 | Value returned by the authorization server. See the list of codes in the data dictionary chapter.Empty if not applicable. |
vads_auth_result |
21 | Authorization number returned by the acquirer | n6 | not applicable | vads_auth_number |
22 | Authorization mode | FULL | vads_auth_mode | |
23 | Authorization date | n8 | In YYYYMMDD format | |
24 | Authorization hour | n6 | In HHMMSS format | |
25 | Additional return code | ans..255 | Contains the return of risk management (if subscribed), or the position of the incorrect field in case of error 30. See the list of codes in the data dictionary chapter. Empty if not applicable. |
vads_extra_result |
26 | Payment method number (Card number or IBAN and BIC number) | an..36 | Extract of the payment method number. (E.g.: IBAN_BIC) The BIC is optional so the number may just be the IBAN. |
vads_card_number |
27 | Expiry date | n8 | In YYYYMMDD format Empty if not applicable |
Format of the trailer record:
Pos. | Description | Format | Values |
---|---|---|---|
01 | Record code | n2 | 01 |
02 | Total number of transmitted detail records | n..6 | |
03 | Number of successful payments | n..6 | |
04 | Number of failed payments | n..6 |