This feature allows Merchants, which need to process large amounts of transactions periodically for their customers, to submit those transactions at once, using a CSV file and a simple HTTP request. This feature works in two different ways:
In the current page we are going to explore the first option.
This feature works based on the submission of transactions in a CSV file. This submission returns a response based on a file format and a set of field validation rules.
Also, an e-mail notification is sent when the processing of the bulk file ends. This will only be sent if the notification email is configured.
After the processing, the result of the processing is also available to be requested, also returning a CSV file with all the transactions processed as per the original request.
REMEMBER: All the URLs used in this guide are test environment related. Before going live, contact our support team for the correct live URLs.
This component allows you to submit your bulk file with all the payments you want to be processed by the gateway.
You are going to submit to the gateway a simple CSV file containing all the details of the transactions you desire to process.
The above is accomplished by means of a simple HTTP Post Request to the Submit URL (shwon below) or a simple HTML form post using enctype=“multipart/form-data” with a number of defined form fields, as you will see at the following subsections.
| TYPE | REQUEST URL |
|---|---|
| Bulk Payment Submit | https://testpayments.nuvei.com/merchant/bulkpayments/submit |
The following fields represent the data which should be send to in your request.
| FIELD NAME | REQUIRED | DESCRIPTION |
|---|---|---|
| TERMINALID | Y | Terminal ID Provided by the merchant service provider |
| TRANSACTIONCOUNT | Y | The count of transactions in the bulk payment file. |
| BATCHTOTAL | Y | The net total of all amounts fields in the bulk payment file. |
| DATETIME | Y | The date time of submission. Format: DD-MM-YYYY:HH:SS:SSS |
| HASH | Y | A HASH code formed by part of the request fields. Take a look at ND001 - Hash Formation for more details. |
In addition to these fields, the file containing the transactions you want to process also need to be configured. Take a look at the file format in ND002 - Bulk File Transaction Fields.
LOWER CASE FIELDS
Note that the fields need to be provided with lower case letters. If lower case letters are not provided, the file will be be rejected and the processing will not occur.
ND001 - Hash Formation
The general rule to build the HASH field is given at the Special Fields and Parameters page, under the Hash Parameter section. For this specific feature, you should use the following formats:
TERMINALID:TRANSACTIONCOUNT:BATCHTOTAL:DATETIME:SECRET
ND002 - Bulk File Transaction Fields
When a file is submitted, each line provided in your file is going to be considered a transaction and each transaction (line) should be represented by the following fields in your CSV file.
Below is the CSV format for submitting a list of Sale Transactions:
| FIELD NAME | REQUIRED | DESCRIPTION |
|---|---|---|
| ODERID | Y | A unique reference generated by Merchant system to identify the transaction. Maximum of characters. |
| CURRENCY | Y | ISO 4217 Currency Code. |
| AMOUNT | Y | Amount formatted to two decimal places. E.g. 1653.00 |
| CARDNUMBER | Y | Card PAN. If a SECURECARD is used (in CARDTYPE), this field should include the CARDREFERENCE of the given Secure Card. |
| CARDTYPE | Y | Card Type used for the transaction. For more details visit Special Fields and Parameters - Card Types. This field can also include the SECURECARD type, when using a Secure Card to perform the transaction. |
| CARDEXPIRY | N | Expiry date of the card. A 4 digit expiry field (MMYY), required if the CARDTYPE is not SECURECARD. If the CARDTYPE is SECURECARD this field should be left blank. |
| CARDHOLDERNAME | N | The cardholders name. Required if the CARDTYPE is not SECURECARD. If the CARDTYPE is SECURECARD this field should be left blank. |
| ADDRESS1 | N | AVS Address Line 1. |
| ADDRESS2 | N | AVS Address Line 2. |
| POSTCODE | N | AVS Post Code. |
| DATETIME | Y | Format: DD-MM-YYYY:HH:MM:SS:SSS. |
| HASH | Y | A HASH code formed by part of the request fields. Take a look at ND003 - Hash Formation For Transactions on Bulk File for more details. |
| AUTOREADY | N | Set to Y for setting auto ready or N to mark as pending. |
| DESCRIPTION | N | Optional transaction description. |
| N | Card holder email for notification. |
NOT REQUIRED Fields
If you plan on omitting fields that are NOT REQUIRED in your transactions, make sure to include the comma separating your omitted field(s) from the next one. Processing will occur on the order of transaction fields in the CSV file based on the order presented above. If commas are missing (or you include them in the wrong sequence), processing will fail.
ND003 - Hash Formation For Transactions on Bulk File
Each transaction of your CSV file also contains a HASH and they also should follow a formation rule.
The general rule to build the HASH field is given at the Special Fields and Parameters page, under the Hash Parameter section. For this specific feature, you should use the following format:
TERMINALID:ODERID:AMOUNT:DATETIME:SECRET
<html> <body> <form action="https://testpayments.nuvei.com/merchant/bulkpayments/submit" method="post" enctype="multipart/form-data"> <input type="hidden" name="terminalid" value=""/> <input type="hidden" name="transactioncount" value=""/> <input type="hidden" name="batchtotal" value=""/> <input type="hidden" name="datetime" value="15-3-2018:10:43:01:673" /> <input type="hidden" name="hash" value="56083f2c6aa3d233dade436b1308805a" /> Bulk File: <input type="file" name="file"/> <input type="submit" name="UPLOAD" value="Upload" /> </form> </body> </html>
After executing this form on a browser, you request will be sent to the Payment Gateway. Another alternative is to choose a technology (PHP, Java, Python, C#, etc.) and perform a HTTP POST request, but in this case you're going to need to process your file - different way in each technology - add the request fields, then send your request.
REMEMBER to replace the TERMINALID and Terminal Secret with valid values.
REMEMBER the file you are going to submit does not need (shouldn't have) a header for the columns. Just add the fields values, in the right sequence, or leave the field blank (if optional and you don't want to provided it), but don't forget the field separator (“,”) if you are not going to include it.
The response of a file submission is quite simple. A string is returned in a CSV file to represent the result of the submission. In case of success, the code 200 and the BULKID are returned as a one line CSV file to your request (E.g. “200”,”76528”). The BULKID field is important as it will be needed when requesting the results of the transactions processed in your bulk file.
The possible response codes to be returned are:
| RESPONSE CODE | DESCRIPTION |
|---|---|
| 200 | VALIDATION OK |
| 001 | INVALID FILE ITEM COUNT |
| 002 | INVALID FILE FORMAT |
| 003 | FILE UPLOAD ERROR |
| 004 | INVALID TRANSACTION COUNT |
| 005 | INVALID BATCH TOTAL |
| 006 | INVALID TERMINAL ID |
| 007 | INVALID DATETIME |
| 008 | INVALID HASH |
| 009 | NOTHING TO SETTLE |
| 010 | INVALID NUMBER OF BATCH FILES |
| 011 | METHOD NOT SUPPORTED |
| 012 | UNKNOWN ERROR |
| 013 | INVALID BULK ID |
| 014 | INVALID BULK ID TERMINAL ID COMBINATION |
| 015 | BULK PAYMENTS ARE NOT ALLOWED |
| 016 | BULK PROCESSING IN PROGRESS |
This component allows you to request from the gateway a file with the details of each transaction processed.
This is also accomplished by means of an HTTP GET request with a number of defined fields, as you will see at the following subsections.
The following Request URL is to be used on your HTML form as the “action” property.
| TYPE | REQUEST URL |
|---|---|
| Bulk Payment Submit | https://testpayments.nuvei.com/merchant/bulkpayments/submitResult |
| FIELD NAME | REQUIRED | DESCRIPTION |
|---|---|---|
| BULKID | Y | The bulk id supplied to merchant after submitting bulk payments file. |
| TERMINALID | Y | Terminal ID Provided by the merchant service provider |
| HASH | Y | A HASH code formed by part of the request fields. Take a look at ND001 - Hash Formation for more details. |
ND001 - Hash Formation
The general rule to build the HASH field is given at the Special Fields and Parameters page, under the Hash Parameter section. For this specific feature, you should use the following formats:
TERMINALID:BULKID:SECRET
In this case, just perform the HTTP GET request in your preferred technology (PHP, Java, Python, C#, etc.) using the BULKID received in your original request.
The response data is returned also returned in a CSV file, as in the previous case. This file will contain the results of all the transactions submited in your request file.
ND001 - Bulk File Processing Result Transaction Fields
Each present in your processing result bulk file will contain the following fields:
| FIELD NAME | REQUIRED | DESCRIPTION |
|---|---|---|
| ORDERID | Y | Order ID supplied by merchant in request. Maximum of 24 characters. |
| APPROVALCODE | N | Will be present for a successful authorization. |
| RESPONSECODE | N | For successful transactions: A: (APPROVED/ AUTHORIZED/ ACCEPTED, respectively). E: (ACCEPTED for later processing, but result currently unknown - specifically for China Union Pay). D: (DECLINED). R: (REFERRED, also considered as PICKUP). C: (PICKUP, also known as Referral A or Referral B). For more details, visit at Transaction Responses. For unsuccessful transactions, there is a 3 digit numeric error code contained in this column: 100 - Order Already Processed. 101 - System Error. |
| RESPONSETEXT | Y | Text describing state of transaction. Error message will be displayed here if an issue was encountered while processing transactions. |
| DATETIME | N | Only sent in the case of no error. Format DD-MM-YYYY:HH:MM:SS:SSS. |
| HASH | Y | A HASH code formed by part of the request fields. Take a look at ND002 - Hash Formation for Transaction on Result File for more details. |
If any field is missing from one transaction, the field is going to be preceded by a comma and succeeded by the next element, if there's any left.
ND002 - Hash Formation for Transaction on Result File
The general rule to build the HASH field is given at the Special Fields and Parameters page, under the Hash Parameter section. For this specific feature, you should use the following formats:
If the terminal uses a single Currency.
TERMINALID:ORDERID:AMOUNT:DATETIME:RESPONSECODE:RESPONSETEXT:SECRET
If the terminal is Multi Currency.
TERMINALID:ORDERID:CURRENCY:AMOUNT:DATETIME:RESPONSECODE:RESPONSETEXT:SECRET