Viveum Batch (advanced)
1. Introduction
This document explains the advanced (automatic) integration procedure for Batch mode.
Batch mode allows you to group your payments into formatted files that can be used for uploading and downloading payment results. This option is specially suited to large volumes of payments that do not need online processing or recurrent invoicing.
The graph above shows a step-by-step transaction flow with Batch integration.
The file format described in this documentation is the standard Viveum file format. For other file formats, go to Other file formats.
For more information on the basic (manual) integration procedure for Batch mode, please refer to the Basic Batch documentation.
2. File format: Upload
The following section contains the standard transaction file formatting rules. If you are using another specific format compatible with our system, go to Other file formats.
2.1 General
A payment file should be formatted in compliance with the following few basic rules:
- The file should be an ASCII text file
- One line per order. The lines are separated by the Carriage Return and Line Feed characters (ASCII : 13 10 – HEX : 0xD 0xA)
- The fields must be separated by a semicolon (“;”)
- The fields themselves cannot contain any semicolons (“;”)
For new transactions (ATR), we automatically split files that are larger than 2,750 lines/transactions. If this is not yet the case for your account, please ask ons Customer Care team to enable this functionality for you.
For maintenance transactions (MTR), we don't split files, so the amount of lines should be limited to 30,000. However, to ensure that your files are processed swiftly, we recommend you limit each file to 2,500 lines.
2.2 File fields
2.2.1 Layout
A standard batch file has the following transaction layout:
Field (No / Name) | Description | Mandatory/Optional |
---|---|---|
1 / AMOUNT | Amount to be paid MULTIPLIED BY 100 since the format of the amount must not contain any decimals or other separators. |
|
2 / CURRENCY | ISO alpha order currency code, for example: EUR, USD, GBP, CHF, etc. Note: To ensure optimal processing of your batch files, all currencies configured in your Viveum account under Configuration > Account > Currency should be configured accordingly per payment method used (Configuration > Payment methods > Contract data). |
|
3 / BRAND | Card brand (See Appendix 3 for non-credit card payment methods). |
|
4 / CARDNO | Card /account number. |
|
5 / ED | Expiry date (MM/YY or MMYY). |
|
6 / ORDERID | Your unique order number (merchant reference). |
|
7 / COM | Order description. | |
8 / CN | Customer name. |
|
9 / PAYID | Our system’s unique transaction reference. |
|
10 / OPERATION |
The payment procedure you have configured in the "Global transaction parameters" tab, "Default operation code" section of the Technical Information page will define your default transaction operation. When you send an operation value in the Operation field in your batch, this will overwrite the default value. Possible values for new orders:
Please note that refunds submitted via Batch are not processed until the following day (after the acquirer cut-off time set in your account). See here for the possible values for maintenance operations. |
|
11 / AUTHORIZATION CODE | Authorisation code, not received via our system. | |
12 / AUTHORIZATION MODE | The way in which the authorisation code in field 11 was received. Possible value: ‘TEL’ for telephone | |
13 / AUTHORIZATION DATE | The date/time when the authorisation code in field 11 was received. (MM/DD/YY hh:mm:ss) | |
14/ PSPID | Your affiliation name in our system. | |
15 / GLOBORDERID | Reference grouping several orders together, allows you to request a maintenance operation on all these transactions at a later time. | |
Blank fields | ... | |
22 / OWNERADDRESS | Customer’s street name and number. | |
23 / OWNERZIP | Customer’s postcode. | |
24 / OWNERTOWN | Customer’s town/city name. | |
25 / OWNERCTY | Customer’s country. | |
26 / OWNERTELNO | Customer’s telephone number. | |
27 / CVC | Card Verification Code (Card Verification Value). |
|
Blank fields | ||
35 / ECI |
Electronic Commerce Indicator. You can configure a default ECI value in the "Global transaction parameters" tab, "Default ECI value" section of the Technical Information page. When you send an ECI value in the ECI field in your batch, this will overwrite the default ECI value. 0 - Swiped 1 - Manually keyed (MOTO, card not present) 2 - Recurring payments, originating from MOTO 3 - Installment payments 7 - E-commerce with SSL encryption 9 - Recurring after first e-commerce transaction |
|
Blank fields | ... |
The following parameters are relevant within the scope of the Credential-on-File guideline (COF) by the payment schemes Visa / MasterCard. Detailed information on their usage can be found in dedicated chapter Alias creation and usage within Credential-on-File guideline (COF).
Field (# / Name) |
Description |
52 / COF_INITIATOR* | Values: CIT - A transaction initiated by a cardholder MIT - A transaction initiated by a merchant |
53 / COF_TRANSACTION* | Values: FIRST - First of a series of transactions SUBSEQ - Subsequent series of transactions |
54 / COF_SCHEDULE* | Values: SCHED - A scheduled transaction UNSCHED - An unscheduled transaction |
55 / Blank field | ... |
56 / COF_RECURRING_EXPIRY* | End date : date of the last scheduled payment of a series Values: YYYYMMDD (i.e. 20190914) |
57 / COF_RECURRING_FREQUENCY* | Days between payments for a scheduled series. Values: numeric between 2 and 4 digits (i.e. 31, 031 or 0031) |
* Please send the parameter values according to the format as defined in the table. Otherwise the transaction will be blocked by our system.
Additional fields may also be optionally sent by merchants who have activated certain options/functionalities in their accounts. Please refer to the respective option documentation for more information on additional fields linked to the option.
2.2.2 Minimum required fields for new transactions
This section only applies to new transactions. Go to Maintenance operations for more information on maintenance operations on existing transactions.
General: new transaction
For new transactions that you would like to enter into our system, the minimum fields required at the transaction level are:
- Amount (field 1 in the file layout)
- Currency (field 2)
- Brand (field 3)
- Card (or account) number (field 4)
- Expiry date (field 5)
- CVC (field 27) (this field is required depending on your acquirer and the ECI value for your transactions)
- Your order reference (field 6)
- Operation (field 10)
Example General: new transaction 10000;EUR;Visa;4111111111111111;11/12;Order0001;;Paul Smith;;SAL;;;;;;;;;;;;;;;;;123; 9500;EUR;Visa;5399999999999999;11/10;Order0002;;Jane Doe;;SAL;;;;;;;;;;;;;;;;;485; 2050;EUR;Visa;4444333322221111;11/09;Order0003;;John Doe;;SAL;;;;;;;;;;;;;;;;;875; |
Exception: authorisations received via an alternative channel
When a (related) transaction does not yet exist in our system, the minimum fields required at the transaction level for authorisations received via an alternative channel (e.g. an authorisation received by phone with your acquirer) are:
- Amount (field 1 in the file layout).
- Currency (field 2)
- Brand (field 3)
- Card (or account) number (field 4).
- Expiry date (field 5).
- Your order reference (field 6).
- Card (account) holder name (field 8).
- Operation (field 10).
- Authorisation code (field 11).
- Authorisation mode (field 12).
- Authorisation date (field 13).
Example Exception: authorisation already received through an alternative channel 1000;EUR;Visa;4111111111111111;11/12;Order0001;;Paul Smith;;IMP;43785;TEL;08/08/07 15:15:52; 9500;EUR;Visa;5399999999999999;11/10;Order0002;;Jane Doe;;IMP;83145;TEL;08/08/07 15:21:45; 2050;EUR;Visa;4111111111111111;11/09;Order0003;;John Doe;;IMP;73586;TEL;08/08/07 15:26:12; |
2.2.3 Magstripe/swipe transactions
For transactions accepted inflight through magnetic stripe/swipe, "TRACK2" data can be sent in line 42 of a batch file.
TRACK2 is a track read by ATMs and credit card checkers. It contains the cardholder's account, encrypted PIN, and other discretionary information.
2.3 Headers and Footer
You will need to use the headers and the footer if you are uploading your files automatically or sending maintenance operations in your file.
There are two headers: OHL containing login information and OHF containing general file information. The headers have to be entered in the first lines of the file, before the actual payment data.
There is one general file footer called OTF. The file footer has to be entered as the last line of the file, after the actual payment data. The footer layout is simply “OTF;”.
The following example shows a file containing both headers and footer. In the following sections, we will take a closer look at the layout of the login information and file information headers.
Example OHL;FishShop1;MySecret84;;FishAPI; OHF;File53484;ATR;RES;2; 10000;EUR;Visa;4111111111111111;11/12;Order0001;golf balls;Paul Smith;;RES;;;;;;;;;;;;;;;;;;123;9500;EUR;Mastercard;5399999999999999;11/10;Order0002;mobile phone;Jane Doe;;RES;;;;;;;;;;;;;;;;;;485; OTF; |
2.3.1 OHL: Login information header
Only use a Login Header when you are uploading your files automatically (exception: manual file upload on a Group).
Login Header layout:
OHL;PSPID;PSWD;USERTYPE;USERID;
Field |
Description |
---|---|
OHL |
Fixed value, indicating this is a header containing login information |
PSPID |
Your affiliation name in our system |
PSWD |
The password belonging to your user (> USERID) |
USERTYPE |
Only applicable for Group structures, value: MGID |
USERID |
Your (API) user (please refer to the User Manager documentation for more information on API users) |
The fields you fill in will depend on whether you use the login details from:
- Your PSPID and a USERID
- A Group: when you have a “Group” structure and you want to send a file containing transactions for more than one PSPID belonging to your group, the login details need to contain a (default) PSPID that belongs to your group and a “Group” level user (as opposed to a user belonging to a specific PSPID).
We will illustrate this in the following examples:
Examples Merchant login header Mike has a PSPID called MilkyMike. He wants to submit his files automatically from an application at his end. To do this, he has created an API user called MikeAPI in his account, with A78H29U41 for the password. His login header would be: OHL;MilkyMike;A78H29U41;;MikeAPI; Group login header John Doe Trading has 3 different PSPIDs: JohnUK, JohnUS and JohnAU. They have a group structure, called JohnDGroup, grouping the 3 PSPIDs together. In JohnDGroup, they have created an API user called JohnUser1 with MySecret12 for the password. John wants to automatically submit a file containing transactions for the 3 different PSPIDs. He has the most transactions in the UK. This is what his login header will look like: OHL;JohnUK;MySecret12;MGID;JohnUser1; |
2.3.2 OHF: File information header
File Header layout:
OHF;FILE_REFERENCE;TRANSACTION_CODE;OPERATION;NB_PAYMENTS;
Field |
Description |
---|---|
OHF |
Fixed value, indicating this is a header containing general file information |
FILE_REFERENCE |
Mandatory reference (name) for the file, freely definable. You can use this reference to look up your file afterwards. (max. 50 characters) |
TRANSACTION_CODE |
Possible values:
|
OPERATION |
For new orders: left blank, RES, SAL, RFD For maintenance operations: REN, DEL, DES, SAL, SAS, RFD, RFS (Go to File fields and File specifics for operation explanations) The OPERATION parameter at the file level can be overwritten by the OPERATION parameter at transaction level. |
NB_PAYMENTS |
Number of payments in the file. Numeric. Mandatory unless you are using a file footer (in which case we still suggest you use this field). |
Example File information header for new orders Jane has a file called Membership0607 containing 86 requests for authorisation. Her file information header would be: OHF;Membership0607;ATR;RES;86; File information header for maintenance transactions Mike has a file called RefundsJune containing 9 (final) refunds. His file information header would be: OHF;RefundsJune;MTR;RFS;9; |
The login and file information details can be transmitted in file headers, as illustrated above, or as parameters in HTTP POST requests (only for automatic file upload).
3. Maintenance operations
Maintenance operations are operations performed on already authorised or paid orders, in other words on transactions already existing in our system.
To perform certain maintenance operations, they have to be enabled for your account (sometimes the availability depends on your subscription), your acquirer must allow the operation, and the operation must be possible for the payment method concerned.
3.1 File specifics
3.1.1 OHF Header
The TRANSACTION_CODE for maintenance operations is MTR.
The OPERATION code for the maintenance operation is provided at a file and/or individual transaction level. The operation code at the transaction level will overwrite the operation code at the file level for maintenance operations. This means you can send one file containing different operations, e.g. partial and last data captures, refunds, etc.
The possible values for maintenance operations (field 10) are:
- DEL: delete authorisation, leaving the transaction open for further potential maintenance operations.
- DES: delete authorisation, closing the transaction after this operation.
- SAL: partial data capture (payment), leaving the transaction open for another potential data capture.
- SAS: (last) partial or full data capture (payment), closing the transaction for further data captures.
- RFD: partial refund (on a paid order), leaving the transaction open for another potential refund.
- RFS: (last) partial or full refund (on a paid order), closing the transaction after this refund.
In general you will perform the operations REN, DEL, DES, SAL, SAS on orders in status 5-Authorised and the operations RFD, RFS on orders in status 9-Payment requested.
3.1.2 Transaction level
The fields required at a transaction level for a manual authorisation after the initial authorisation (via our system) was refused (order in status 2-Authorisation refused) are:
- Amount (field 1 in the file layout)
- Currency (field 2)
- Brand (field 3)
- Our system’s PAYID (field 9)
- Operation code (field 10)
- Authorisation code (field 11)
- Authorisation mode (field 12)
- Authorisation date (field 13).
Example Mike has a PSPID called MilkyMike. He wants to submit his files automatically from an application at his end. To do this, he has created an API user, called MikeAPI, in his account, with A78H29U41 as the password. His login header would be: OHL;MilkyMike;A78H29U41;;MikeAPI; 1. Authorisation Mike has a file called AutoMay, containing 1 transaction: an authorisation request for 75 EUR. His file information header would be: OHF;AutoMay;ATR;RES;1; This is the file he submits: OHL;MilkyMike;A78H29U41;;MikeAPI; OHF;AutoMay;ATR;RES;1; 7500;EUR;Mastercard;5399999999999999;11/10;Order0001;;Jane Doe;;RES;;;;;;;;;;;;;;;;;;485; OTF; After the full upload process, the file is assigned FileID 1543 and the transaction is assigned the following reference from our system (PAYID): 1348645 In the account back office, there is now a PAYID 1348645 with a historic record in status 5-Authorised. 2. Partial data captureMike wants to capture data for a part of the authorised amount, leaving the transaction open for a final data capture for the rest of the amount later (operation code: SAL). He wants to capture an amount of 25 EUR for PAYID 1348645. His file is called DataCap1May. His file information header would be: OHF;DataCap1May;MTR;SAL;1; This is the file he submits: OHL;MilkyMike;A78H29U41;;MikeAPI; OHF;DataCap1May;MTR;SAL;1; 2500;EUR;;;;;;;1348645;SAL; OTF; After the full upload process, the file is assigned FileID 1571. In the account back office, PAYID 1348645 now has 2 historic records: /0 in status 5-Authorised for an amount of 75 EUR and /1 in status 9-Payment requested for an amount of 25 EUR. The order status is still 5-Authorised because the submitted data capture was partial. 3. Final data capture Mike wants to make a LAST data capture for the rest of the authorised amount (operation code: SAS), i.e. a data capture for an amount of 50 EUR for PAYID 1348645. His file is called DataCap2May. His file information header would be: OHF;DataCap2May;MTR;SAS;1; This is the file he submits: OHL;MilkyMike;A78H29U41;;MikeAPI; OHF;DataCap2May;MTR;SAS;1; 5000;EUR;;;;;;;1348645;SAS; OTF; After the full upload process, the file is assigned FileID 1610. In the account back office, PAYID 1348645 now has 3 historic records: /0 in status 5-Authorized for an amount of 75 EUR, /1 in status 9-Payment requested for an amount of 25 EUR and /2 in status 9-Payment requested for an amount of 50 EUR. The order status is now 9- Payment requested because the submitted data capture was the LAST one (closing the transaction). 4. Refund Mike wants to refund (operation code: RFS) the customer for the full amount, a refund for an amount of 75 EUR for PAYID 1348645. His file is called RefundMay. His file information header would be: OHF;RefundMay;MTR;RFS;1; This is the file he submits: OHL;MilkyMike;A78H29U41;;MikeAPI; OHF;RefundMay;MTR;RFS;1; 7500;EUR;;;;;;;1348645;RFS; OTF; After the full upload process, the file is assigned FileID 1671. In the account back office, PAYID 1348645 now has 4 historic records: /0 in status 5-Authorized for an amount of 75 EUR, /1 in status 9-Payment requested for an amount of 25 EUR, /2 in status 9-Payment requested for an amount of 50 EUR and 3/ in status 8-Refund for an amount of 75 EUR. The order status is now 8- Refund because the submitted refund was the LAST one (closing the transaction). |
4. Automatic upload process
There are 2 different ways to upload a file:
- Manual file upload: You can upload the payment files manually from your account’s back office. Go to manual Batch for more information.
- Automatic upload from a merchant application: the merchant application makes https file upload and download requests on specific pages in our system. This requires developments in the merchant application.
This chapter describes the automatic upload process from a merchant application.
4.1 Request URL and specific parameters
An Automatic File Upload allows you to process multiple payments directly from your own system (programme, scheduled task, etc.) without the need for a browser or human intervention. Your server sends an HTTPS POST request to our server. The transaction file and additional parameters are transmitted in the “content” of the https request.
Your application sends an HTTPS request to the following page on our server:
- Test: https://viveum.v-psp.com/ncol/test/AFU_agree.asp (will be used in further examples)
- Production: https://viveum.v-psp.com/ncol/prod/AFU_agree.asp
The file format is identical for manual and automatic file uploads. In the event of automatic file upload however, login data, certain process data and general parameters are mandatory in the request. You can submit these parameters as header/footer parameters included in the file, or as POST parameters separately from the file.
The general parameters set out below need to be sent in each automatic file upload request. These parameters refer to “Content-disposition” in the HTTP protocol and can only be specified as POST parameters separately from the file, not in headers.
Field | Description |
---|---|
REPLY_TYPE | Defines which response format is requested from our system. Possible values:
|
PROCESS_MODE |
Possible values for the processing mode:
|
MODE |
Can be used to specify whether your application is waiting for a response from our server or if you will retrieve the response later. Valid modes are:
Currently this option only has an effect on the PROCESS or CHECKANDPROCESS steps (see PROCESS_MODE above). In SYNC mode, you will receive the result of the payment validation process if you stay connected (not the result of the authorisation with the acquirer(s), as this always occurs offline for file uploads). In ASYNC mode, the validation process is performed offline and you only receive the FILE ID as confirmation. An email is sent to the merchant when the file has been validated by our system. If you send large files, we advise you to use ASYNC mode. Independently of the mode used, an email is also sent once the file has been processed (submitted to the acquirer). |
Examples Additional parameters specified as separate POST parameters <form action="https://viveum.v-psp.com/ncol/test/AFU_agree.asp" method=POST><textarea name=FILE> 10000;EUR;Visa;4111111111111111;11/12;Order0001;golf balls;Paul Smith;;;;;;;;;;;;;;;;;;;123; 9500;EUR;Mastercard;5399999999999999;11/10;Order0002;mobile phone;Jane Doe;;;;;;;;;;;;;;;;;;;485; 2050;EUR;Visa;4444333322221111;11/09;Order0003;cocktails;John Doe;;;;;;;;;;;;;;;;;;;875; </textarea> <input type=text name=FILE_REFERENCE value=”File53484”> <input type=text name=PSPID value=”FishShop1”> <input type=text name=USERID value=”FishAPI”> <input type=text name=PSWD value=”MySecret81”> <input type=text name=TRANSACTION_CODE value=”ATR”> <input type=text name=OPERATION value=”RES”> <input type=text name=NB_PAYMENTS value=”3”> <input type=text name=REPLY_TYPE value=”XML”> <input type=text name=MODE value=”SYNC”> <input type=text name=PROCESS_MODE value=”SEND”> </form> Additional parameters specified in the file headers/footer <form action="https://viveum.v-psp.com/ncol/test/AFU_agree.asp" method=POST><textarea name=FILE> OHL;FishShop1;MySecret81;;FishAPI; OHF;File53484;ATR;RES;3; 10000;EUR;Visa;411111111111111;11/12;Order0001;golf balls;Paul Smith;;RES;;;;;;;;;;;;;;;;;123; 9500;EUR;Mastercard;5399999999999999;11/10;Order0002;mobile phone;Jane Doe;;RES;;;;;;;;;;;;;;;;;485; 2050;EUR;Visa;4444333322221111;11/09;Order0003;cocktails;John Doe;;RES;;;;;;;;;;;;;;;;;875; </textarea> <input type=text name=REPLY_TYPE value=”XML”> <input type=text name=MODE value=”SYNC”> <input type=text name=PROCESS_MODE value=”SEND”> </form> |
4.2 Upload process
We advise you to split the upload process into the different steps: SEND, CHECK and PROCESS (“PROCESS_MODE” values). These steps correspond to the different steps of the manual file upload.
There are two main advantages of splitting the upload process:
- The split between CHECK and PROCESS allows your application to cancel the upload after our system’s format check, should there be too many format errors in the file.
- The split between SEND and the rest of the processing prevents you from processing the same file more than once. If your application doesn't receive a response after a certain step for any reason, you can repeat the step with no risk. If you perform the upload in a single step (CHECKANDPROCESS) and a communication problem occurred before your application received the response, it might think that the file has not been uploaded and try uploading it a second time, resulting in duplicate processing of the same file.
The merchant's application triggers each step by making an HTTPS POST request to our server. The HTTPS request can be sent as a standard POST HTTPS request (with the file content in a standard field named “FILE”) or as a MULTIPART/FORM-DATA POST HTTPS request (with the file content in a “file” type field named “FILE”, <input type="file" name="File1">). For both methods, you need a component capable of sending HTTP requests to a secure server.
In the first step (SEND), the file itself is part of the content of the request. Our system returns a FileID in the XML response to this request. You will use this FileID instead of the file itself in the subsequent upload steps (CHECK and PROCESS).
4.2.1 Send
When you send PROCESS_MODE=SEND, you upload a new transaction file, but no check or processing is performed (this corresponds to Step 1 of a manual file upload).
When our system receives the HTTPS request, it checks that the general parameters are valid. If something is wrong, an error is returned to your application and the process stops without performing any operation.
If the general parameters are valid, our system returns a FILEID and a GUID. This FILEID will be used in subsequent requests instead of the file itself. The GUID can be used in subsequent requests to replace Login/Password.
After this step, the file status is set to “Uploaded” (visible in the back office or with the automatic file download).
Example Request <form action="https://viveum.v-psp.com/ncol/test/AFU_agree.asp" method=POST><textarea name=FILE> 10000;EUR;Visa;411111111111111;11/12;Order0001;golf balls;Paul Smith;;RES;;;;;;;;;;;;;;;;;123; 9500;EUR;Mastercard;5399999999999999;11/10;Order0002;mobile phone;Jane Doe;;RES;;;;;;;;;;;;;;;;;485; 2050;EUR;Visa;4444333322221111;11/09;Order0003;cocktails;John Doe;;RES;;;;;;;;;;;;;;;;;875; </textarea> <input type=text name=FILE_REFERENCE value=”File53484”> <input type=text name=PSPID value=”FishShop1”> <input type=text name=USERID value=”FishAPI”> <input type=text name=PSWD value=”MySecret81”> <input type=text name=TRANSACTION_CODE value=”ATR”> <input type=text name=OPERATION value=”RES”> <input type=text name=NB_PAYMENTS value=”3”> <input type=text name=REPLY_TYPE value=”XML”> <input type=text name=MODE value=”SYNC”> <input type=text name=PROCESS_MODE value=”SEND”> </form> XML reply <?xml version="1.0" ?><AFU_REPLY> <SEND_FILE> <FILEID>2010</FILEID> <GUID>8B1F5D65D5C7C5C80551D2AA955F810A45BD1752</GUID> </SEND_FILE> </AFU_REPLY> |
4.2.2 Check
When you send PROCESS_MODE= CHECK, a simple format check is requested (this corresponds to Step 2 of a manual file upload).
You will use the FILEID in the request instead of the file itself.
Our system returns format errors, should any such errors occur.
After this step, the file status is set to “Checked”.
Example Request <form action="<%URL_TESTENV%>AFU_agree.asp" method=POST><input type=text name=PSPID value=”FishShop1”> <input type=text name=USERID value=”FishAPI”> <input type=text name=PSWD value=”MySecret81”> <input type=text name=REPLY_TYPE value=”XML”> <input type=text name=MODE value=”SYNC”> <input type=text name=PFID value=”2010”> <input type=text name=PROCESS_MODE value=”SEND”> </form> XML reply <?xml version="1.0" ?><AFU_REPLY> <FORMAT_CHECK> <FORMAT_CHECK_ERROR> <ERROR>|Wrong credit card number format|</ERROR> <LINE>1</LINE> <NCERROR>50001002</NCERROR> <PAYID>0</PAYID> <ORDERID>Order0001</ORDERID> <NCSTATUS>5</NCSTATUS> <STATUS>0</STATUS> </FORMAT_CHECK_ERROR> <FILEID>2012</FILEID> </FORMAT_CHECK> </AFU_REPLY> |
4.2.3 Process
When you send PROCESS_MODE=PROCESS, the processing of the file is requested (this corresponds to Step 3 of a manual file upload).
You will use the FILEID in the request instead of the file itself.
Our system returns loading errors, should any such errors occur.
OK_PAYMENTS is the number of transactions correctly loaded. RANGE_START and RANGE_STOP represent the range of PAYIDs for the loaded transactions, as assigned by our system (only when the transaction_code is ATR).
After this step, the file status is set to “Being Processed”.
After the response is sent, the transactions are processed with the acquirers (banks) in offline mode. It is possible to retrieve results in your back office or with the automatic file download.
Example: Request in SYNC mode Request in SYNC mode <form action="https://viveum.v-psp.com/ncol/test/AFU_agree.asp" method=POST> <input type=text name=PSPID value=”FishShop1”> <input type=text name=USERID value=”FishAPI”> <input type=text name=PSWD value=”MySecret81”> <input type=text name=REPLY_TYPE value=”XML”> <input type=text name=MODE value=”SYNC”> <input type=text name=PFID value=”2010”> <input type=text name=PROCESS_MODE value=”PROCESS”> </form> XML reply <?xml version="1.0" ?> <AFU_REPLY> <PROCESSING> <NC_ERROR> <NCERRORPLUS>||Wrong credit card number format|</NCERRORPLUS> <LINE>1</LINE> <NCERROR>50001002</NCERROR> <PAYID>37267</PAYID> <ORDERID>Order0001</ORDERID> <NCSTATUS>5</NCSTATUS> <STATUS>0</STATUS> </NC_ERROR> <FILEID>2011</FILEID> <SUMMARY> <NB_PAYMENTS>3</NB_PAYMENTS> <OK_PAYMENTS>2</OK_PAYMENTS> <RANGE_START>37267</RANGE_START> <RANGE_STOP>37269</RANGE_STOP> </SUMMARY> </PROCESSING> </AFU_REPLY> Example: Request in ASYNC mode Request in ASYNC mode <form action="https://viveum.v-psp.com/ncol/test/AFU_agree.asp" method=POST> <input type=text name=PSPID value=”FishShop1”> <input type=text name=USERID value=”FishAPI”> <input type=text name=PSWD value=”MySecret81”> <input type=text name=REPLY_TYPE value=”XML”> <input type=text name=MODE value=”ASYNC”> <input type=text name=PFID value=”2010”> <input type=text name=PROCESS_MODE value=”PROCESS”> </form> XML reply <?xml version="1.0" ?> <AFU_REPLY> <PROCESSING> <FILEID>2011</FILEID> <SUMMARY> <NB_PAYMENTS>3</NB_PAYMENTS> </SUMMARY> </PROCESSING> </AFU_REPLY> |
4.3 XML response tags
Tag | Description |
---|---|
<AFU_REPLY> | Automatic File Upload Reply |
<PARAMS_ERROR> |
General parameter errors |
<PARAM> |
Parameter name |
<ERROR> |
Error description |
<FILE_ERROR> |
File processing error |
<ERROR> |
Error description |
<FORMAT_CHECK> |
Individual transaction format check |
<FILEID> |
Numeric FileID designated by our system |
<GUID> |
Alphanumeric Login Identifier for the file designated by our system. This GUID is designated the first time you submit a file (only once per FileID). When you want to process the file or perform another valid operation (or download at file level etc.), you can submit this GUID instead of the login parameters described above. It serves as a form of password, granting access only to this specific file. |
<FORMAT_CHECK_ERROR> |
Transaction format error |
<LINE> |
Corresponding line number in the file |
<ERROR> |
Error description |
<NCERROR> |
Numeric error code |
<PROCESSING> | Loading of the individual transactions |
<NC_ERROR> | Load error |
<LINE> | Payment line |
<PAYID> | Our system’s PAYID |
<NCSTATUS> | Error status (first digit of NCERROR) |
<STATUS> | Status of the PAYID after the transaction has been loaded |
<NCERROR> | Numeric error code |
<NCERRORPLUS> | Error description |
<SUMMARY> | Summary of the file |
<NB_PAYMENTS> |
Number of received payments |
<OK_PAYMENTS> |
Number of correctly formatted payments |
<RANGE_START> |
First PAYID (for ATR-new orders only) |
<RANGE_STOP> |
Last PAYID (for ATR-new orders only) |
<NB_ALIAS> |
Number of Alias operations |
<NB_SUBSCRIPTION> |
Number of Subscription operations |
4.4 Security
4.4.1 Secure requests
The automatic file upload and download functions are built on a robust secure communication protocol.Batch API is a set of instructions submitted with standard HTTPS Post requests. We only allow the merchant to connect to us in secure HTTPS mode.
There is no need for a client SSL certificate.
4.4.2 IP address
The IP address(es) or IP address range(s) of the servers from which you are sending us requests can be configured in the IP address field of the "Data and origin verification" tab, checks for automatic Batch section of the Technical Information page in your account. We will check the IP address when you perform a request for an automatic file upload or download.
If the IP address from which the request originates has not been defined in the IP address field of the "Data and origin verification" tab, checks for automatic Batch section of the Technical Information page in your account, you will receive the error message “unknown order/1/i”. The IP address from which the request was sent will also be displayed in the error message.
5. Automatic download process
You can either download a payment file (transaction results) manually via the back office or download your payment files automatically (through an application).
This chapter describes the automatic file download and the electronic reporting page. Go to Basic Batch for more information on manual file downloads and consulting files in the back office.
5.1 Request URL and parameters
Your application sends an HTTPS request to the following page on our server:
- The request URL in the TEST environment is https://viveum.v-psp.com/ncol/test/payment_download_ncp.asp (will be used in further examples)
- The request URL in the PRODUCTION environment is https://viveum.v-psp.com/ncol/prod/payment_download_ncp.asp
The parameters should be sent using the POST method.
Field | Description / Value |
---|---|
PSPID | Your affiliation name in our system |
USERID | Name of your API user |
PSWD | Password of your API user |
level | Level of payment selection Possible values:
|
ofd | Order date ‘from’ day (DD) |
ofm | Order date ‘from’ month (MM) |
ofy | Order date ‘from’ year (YYYY) |
otd | Order date ‘to’ day (DD) |
otm | Order date ‘to’ month (MM) |
oty | Order date ‘to’ year (YYYY) |
afd | Payment date ‘from’ day (DD) |
afm | Payment date ‘from’ month (MM) |
afy | Payment date ‘from’ year (YYYY) |
atd | Payment date ‘to’ day (DD) |
atm | Payment date ‘to’ month (MM) |
aty | Payment date ‘to’ year (YYYY) |
arch | Send the value "arch" with this field if your download will contain transactions older than 45 days. |
PM | Payment method |
BRAND | Card brand |
CARDNO | Card/account number |
orderID | Your reference for the order |
Company | Client company |
facname1 | Customer name |
PAYID | Our system’s reference for the payment |
ID | FileID of a previously uploaded file (our system’s reference) |
status | List of specific statuses (numeric code) separated by “,”. |
OnlyIfProcessed | Indicates that only files with the “Processed” status should be downloaded. If the file is not yet processed, our system will return the message: “File not yet processed: please retry later ...” (to select: OnlyIfProcessed =“1”). |
stok | Only in combination with “OnlyIfProcessed”. Select all accepted transactions (status 5, 6, 7, 74, 85, 8, 84, 85, 9, 94, 95) of a processed file (to select: stok=“1”). |
sterr | Only in combination with “OnlyIfProcessed”. Select all rejected transactions (status 2, 63, 73, 83, 93) of a processed file (to select: sterr=“1”) |
st1 | Status 0, 1, 51, 71, 81, 91. (To select: st1=“1”) |
st2 | Status 2. (To select: st2=“1”) |
st3 | Status 5. (To select: st3=“1”) |
st4 | Status 9, 94. (To select: st4=“1”) |
st5 | “Others” status: all statuses other than the ones in st1, st2, st3, st4 and st6 (to select: st5=“1”) |
st6 | Status 7, 8, 87, 84 (to select: st6=“1”) |
Electronic reporting specification (optional): | |
Structure | File structure. Possible values:
|
Format | File format. Possible values:
|
Sep | Separator in the event that the file format is DEL (delimited). Default separator: “;”. |
headers | File download headers (to select: headers=“1”) |
GR1 | First criterion to group payments together. Possible values:
|
GR2 | Second criterion to group payments together. Possible values: see GR1. |
GR3 | Third criterion to group payments together. Possible values: see GR1. |
Important remarks:
- For the date, you either use ofd, ofm, ofy, otd, otm, oty, to search at the order level (order date) or afd, afm, afy, atd, atm, aty, to search at the history level (payment date). It is mandatory for the date to be sent in your requests, unless the FileID or PAYID is sent.
- For the statuses, you should only use one of the three following options:
- status
- stok, sterr in combination with OnlyIfProcessed
- st1, st2, st3, st4, st5, st6
Example The merchant wants to retrieve all orders for which authorisation has been declined with an order date between 1st and 15th June 2007. |
5.2 Format: Electronic reporting
In the Electronic Reporting page (“Electronic Reporting” link in your back-office menu), you can set the format and structure you want to use for electronic reports such as file downloads (when push-reports are activated in your account, the electronic reporting link will give access to a list of your push-reports.)
The file format can be set per user. If you want to change the electronic reporting settings for an API user, you can do so via the User Management page (“Users” link in the menu > “Edit” button next to the API user > “File format >>>” link).
5.2.1 File structure
The structure defines the type of information available for each transaction. The payment result files can be downloaded in 4 different structures: "Standard", Extended", "File management" or “Dynamic”.
The full description of these structures is available via the "More info" link on the Electronic reporting page. Please refer to the links in this page for the XML tag names, description, size and format of the download fields.
5.2.2 File format
There are three different formats for file downloads: delimited, XML and fixed length. The layout and an example for each of these are provided below. The file structure used in the examples is “Standard”.
Delimited
Layout <DOWNLOAD_REPLY> Beginning of the file<TRANSMISSION Description string> Sequential list of payments: each line corresponds to one order. Each field is separated by the separator specified in the “Electronic Reporting” page. Each occurrence of a separator in a field value is replaced by a blank. <END_TRANSMISSION> End of the payments selection |
Example <DOWNLOAD_REPLY> |
XML
Layout <?xml version="1.0"?><DOWNLOAD_REPLY> Beginning of the file In the event of an error: <SYSTEM_ERROR>: System error message <PARAMS_ERROR>: Parameters error message <NCERROR>: Numeric error code or <WARNING>File not yet processed: please retry later ...</WARNING> <TRANSMISSION attributes: LEVEL, DESCRIP> Beginning of transmission <GROUP1 attributes: ACTION, BRAND, FILE, METHOD, STATUS, DATE > Beginning of Group1, up to 3 groups are possible. Attributes depend on the selected group. <PAYMENT attributes: ID, REF, ORDER, STATUS, LIB, ACCEPT, NCID, NCSTER, PAYDATE, CIE, NAME, COUNTRY, TOTAL, CUR, METHOD, BRAND, CARD, UID, STRUCT, FILEID, ACTION, TICKET, PSPID, DESC> Payment description. The attributes depend on the selected file structure. </TRANSMISSION> end of transmission </DOWNLOAD_REPLY> end of file |
Example <?xml version="1.0"?><DOWNLOAD_REPLY> <TRANSMISSION LEVEL="Order" DESCRIP="- Order date 12/04/2007- Status All except Cancelled by client,Invalid or incomplete-"> <PAYMENT ID="1651818" REF="order0001" ORDER="12/4/2007" STATUS="5" LIB="Authorised" ACCEPT="testoff" PAYDATE="" CIE="" NAME="Paul Smith" COUNTRY="" TOTAL="120.00" CUR="EUR" SHIP="0.00" TAX="0.00" METHOD="CreditCard" BRAND="VISA" CARD="XXXXXXXXXXXX1111" STRUCT=""></PAYMENT> <PAYMENT ID="1651819" REF="order0002" ORDER="12/4/2007" STATUS="5" LIB="Authorised" ACCEPT="testoff" PAYDATE="" CIE="" NAME="Bill Durand" COUNTRY="" TOTAL="56.00" CUR="EUR" SHIP="0.00" TAX="0.00" METHOD="CreditCard" BRAND="Eurocard" CARD="XXXXXXXXXXXX9999" STRUCT=""></PAYMENT> </TRANSMISSION> </DOWNLOAD_REPLY> |
Fixed length
Layout <DOWNLOAD_REPLY> Beginning of the file<TRANSMISSION Description string> Sequential list of payments: each line corresponds to one order. The length of each field is described one page you can check via the "More info" link on the Electronic reporting page. <END_TRANSMISSION> End of the payments selection |
Example <DOWNLOAD_REPLY><TRANSMISSION Order Level: - Order date 12/04/2007- Status All except Cancelled by client,Invalid or incomplete-> 1651818 order0001 12/4/2007 5 Authorised testoff Paul Smith 120.00EUR 0.00 0.00 CreditCard VISA XXXXXXXXXXXX1111 1651819 order0002 12/4/2007 5 Authorised testoff Bill Durand 56.00EUR 0.00 0.00 CreditCard Eurocard XXXXXXXXXXXX9999 <END_TRANSMISSION> |
5.2.3 Extra features
Grouping payments together
You can group payments together in your download, according to certain criteria/values. You can set these criteria in the drop down lists under “Sort by” in the “Electronic Reporting page”. Three different values can be selected, allowing the merchant to create sub-groups. Within a group, payments will be sorted according to the value of the sub-group. For instance:
<GROUP1 FILE="1">
<GROUP2 STATUS="5">
<GROUP3 BRAND="EUROCARD">
<END_GROUP3>
<GROUP3 BRAND="VISA">
<END_GROUP3>
<END_GROUP2>
<GROUP2 STATUS="2">
<GROUP3 BRAND="EUROCARD">
<END_GROUP3>
<GROUP3 BRAND="VISA">
<END_GROUP3>
<END_GROUP2>
<END_GROUP1>
The following example illustrates a Standard (structure), Delimited (format), Sort by File (drop down 1) and Brand (drop down 2) download.
Example <DOWNLOAD_REPLY><TRANSMISSION Order Level: - Order date 12/04/2007- Status All except Cancelled by client,Invalid or incomplete-> <GROUP1 FILE="40555"> <GROUP2 BRAND="EUROCARD"> 1651819;order0002;12/4/2007;5;Authorised;testoff;;;Bill Durand;;56.00;EUR;0.00;0.00;CreditCard;Eurocard;XXXXXXXXXXXX9999;; 1651821;order0004;12/4/2007;5;Authorised;testoff;;;Mark van Steen;;33.00;EUR;0.00;0.00;CreditCard;Eurocard;XXXXXXXXXXXX9999;; <END_GROUP2> <GROUP2 BRAND="VISA"> 1651818;order0001;12/4/2007;5;Authorised;testoff;;;Paul Smith;;120.00;EUR;0.00;0.00;CreditCard;VISA;XXXXXXXXXXXX1111;; 1651820;order0003;12/4/2007;5;Authorised;testoff;;;Jef Geeraerts;;75.10;EUR;0.00;0.00;CreditCard;VISA;XXXXXXXXXXXX1111;; <END_GROUP2> <END_GROUP1> <GROUP1 FILE="40558"> <GROUP2 BRAND="EUROCARD"> 1651834;order5553;12/4/2007;5;Authorised;testoff;;;John Smith;;75.10;EUR;0.00;0.00;CreditCard;Eurocard;XXXXXXXXXXXX9999;; <END_GROUP2> <GROUP2 BRAND="VISA"> 1651835;order5555;12/4/2007;5;Authorised;testoff;;;John Doe;;50.32;EUR;0.00;0.00;CreditCard;VISA;XXXXXXXXXXXX1111;; 1651836;order5558;12/4/2007;5;Authorised;testoff;;;Jane Doe;;86.42;EUR;0.00;0.00;CreditCard;VISA;XXXXXXXXXXXX1111;; <END_GROUP2> <END_GROUP1> <END_TRANSMISSION> |
Headers
You can indicate whether you want to have payment records with or without headers.
A file without headers contains only the transaction lines. If you want to use the <DOWNLOAD_REPLY>, <TRANSMISSION> or <GROUP> tags, you need to enable the “Headers” box.
6. Automatic upload and download test
Our server hosts several test pages (URLs) which you can call up in your browser to simulate the upload process. These URLs are for test purposes only, for establishing the data your system has to submit and the data you receive in response:
Action | Test URL in the browser |
---|---|
Upload: Send and check | https://viveum.v-psp.com/ncol/test/AFU_step1.asp |
Upload: Process | https://viveum.v-psp.com/ncol/test/AFU_step2.asp |
Download: Check file status | https://viveum.v-psp.com/ncol/test/AFU_step3.asp |
Download: Download transaction file | https://viveum.v-psp.com/ncol/test/AFU_step4.asp |
7. File statuses
Default file statuses:
- Uploaded: the file has been received, but has not yet been validated (SEND step).
- To be checked: the file is awaiting validation. (when you request PROCESS in ASYNC mode for an “Uploaded” file).
- Checked: the file has been validated (CHECK step).
- Cancelled: the file has been cancelled after the ‘check’ step.
- To be loaded: the file is waiting to be loaded into our process module (when you request a PROCESS in ASYNC mode for a “Checked” file).
- Being loaded: the file is being loaded into our process module.
- Loaded: the file has been loaded into our process module, but (all) the payments have not yet been sent to the acquirers/banks.
- Processed: all the payments in the file have been sent to the acquirers/banks.
- To be split: the file meets the generic criteria and will be sent for splitting.
- Being split: the file is currently being split.
Veelgestelde vragen
Via het menu van uw Viveum-account kunt u uw transacties eenvoudig opzoeken. Kies 'Transacties’ en klik vervolgens op ‘Beheer transacties' of 'Financiële historiek’/’Dagtotalen’, afhankelijk van het type transactieresultaten dat u zoekt.
Ga naar Uw transacties raadplegen voor meer informatie.
U kunt een betaling eenvoudig terugstorten met de knop 'Terugbetaling’ in het orderoverzicht van een transactie (via ’Beheer transacties’). Als dit door uw account wordt ondersteund, kunt u ook terugbetalingen doen met een DirectLink-aanvraag of met een Batch-bestandsupload (voor meerdere transacties).
Hiervoor moet in uw account de optie Refunds (Terugbetalingen) zijn ingeschakeld.
Ga voor meer informatie naar transacties beheren.
U kunt alleen terugbetalingen uitvoeren op transacties waarvoor het geld al naar uw bankrekening is overgemaakt. Een annulering of verwijdering kan worden gedaan voordat een betaling volledig is verwerkt, d.w.z. vóór de dagelijkse afsluittijd bij de acquirer, op welk moment alle transacties van de vorige dag worden verwerkt.