Bulk Payments Feature

Table of Contents

This feature allows Merchants, which need to process large amounts of transactions periodically for their customers, to submit those transactions at once, using a file and a simple HTTP request. This feature works in two different ways:

  • Processing the Bulking File at Once: This option is available as a Hosted Page integration method, as described by the next subsections.
  • Load the Bulking File and Process the Payment Separately: This option is available for merchants using our Selfcare System, when enabled. Take a look at Selfcare System page for more details.

In the current page we are going to explore the first option.

This feature works beased on the submission of the 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 URLs.

Bulk Payments Submit

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.isvpay.io/merchant/subscriptionpage/register



Request Body Fields

The following fields represent the data which should be send to in your request.

Filter:

FIELD NAME REQUIRED DESCRIPTION
TERMINALID Y Terminal ID Provided by Worldnet Payments
TRANSACTIONCOUNT Y The count of transaction 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.
ISBULKACH N This field should only be used by terminals using ACH to processes payments. In this case, you can inform “Y” or “N”, to indicate that the CSV file sent contain only ACH transactions (Y) or sale transactions (N).

Additionally to these fields, the File containing the transactions you want to process also need to be informed. Take a look at the file format in ND002 - Bulk File Transaction Fields.

LOWER CASE FIELDS: Due to special circunstancies, the fields for this feature requests' need to be informed with lower case letters. In case you don't do that, your request is going to be rejected and the processing is not going to happen.


Notes and Details About the Request

ND001 - Hash Formation

The general rule to build HASH field is given at the Special Fields and Parameters section. For this specific feature, you should use the following formats:

TERMINALID:TRANSACTIONCOUNT:BATCHTOTAL:DATETIME:SECRET


ND002 - Bulk File Transaction Fields

The file send by this request needs to be composed by the transactions you want to process. During the processing, each line informed 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 you can see the CSV format, in case you want to submit 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 inform the CARDREFERENCE of the given Secure Tokens.
CARDTYPE Y Card Type used for the transaction.
For more details visit Special Fields and Parameters - Card Types.
This field can also admit the SECURECARD type, when using a Secure Tokens to perform the transaction.
CARDEXPIRY N Expiry date of he card.A 4 digit expiry field (MMYY), required if the CARDTYPE is not SECURECARD.
If the CARDTYPE is SECURECARD this field shouldn't be informed.
CARDHOLDERNAME N The cardholders name. Required if the CARDTYPE is not SECURECARD.
If the CARDTYPE is SECURECARD this field shouldn't be informed.
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.
EMAIL N Card holder email for notification.


On the next table you can see the CSV format in case you want to submit a list of ACH Payments.

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
ACH_SECURE N Two possibilities: Y (for YES) and N (for NO).
SEC_CODE Y Standard Entry Class (SEC) codes to determine what information is required to be sent in the submission. Options supported:
WEB (Internet Initiated Entry): An internet initiated entry is a method of payment for goods or services made via the internet.
TEL (Telephone Initiated Entry ): A telephone initiated entry is a payment for goods or services made with a single entry debit with oral authorization obtained from the consumer via the telephone.
PPD (Prearranged Payment and Deposit): A pre-authorized consumer payment.
CCD (Cash Concentration and Disbursement): A pre-authorized corporate payment.
ACCOUNT_TYPE Y ACH account type: CHECKING or SAVINGS.
ACCOUNT_NUMBER Y ACH account number.
If ACH_SECURE is set to Y, this field should inform the ACHREFERENCE of the given ACH Secure Account.
ROUTING_NUMBER Y ACH account routing number.
ACCOUNT_NAME Y ACH cardholder's name.
CHECK_NUMBER N Check number used.
DL_STATE N Customer's driver licence state.
DL_NUMBER N Customer's driver licence number.
ADDRESS1 N AVS Address Line 1.
ADDRESS2 N AVS Address Line 2.
CITY N Customer's city.
REGION N Customer's region.
COUNTRY N Customer's country.
POSTCODE N AVS Post Code.
PHONE N Customer's phone number.
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 NOTE 02 for more details.
DESCRIPTION N Optional transaction description.
EMAIL N Customer's e-mail.


NOT MANDATORY Fields: In case you are not going to use one of the NOT MANDATORY fields for of or more of your transaction, don't forget to add the comma separating that field from the next one. The processing of your file is going to consider the order of fields in your CSV file based on the order presented above. If you fail on informing any of them (or add them in the wrong sequence), the processing is going to 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 HASH field is given at the Special Fields and Parameters section. For this specific feature, you should use the following format:

TERMINALID:ODERID:AMOUNT:DATETIME:SECRET

Examples for a Request

  • Scenario: Minimum request, with only mandatory data.
  • Request: Using a simple HTML Post.
  • Terminal Secret: x4n35c32RT.
<html>
  <body>
    <form action="https://testpayments.isvpay.io/merchant/subscriptionpage/register" 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 change the Terminal Id and Terminal Secret for valid values. Verify the Integration Docs for viable examples or contact our support team.

REMEMBER the file you are going to submit does not need (shouldn't have) header for the columns. Just add the fields values, on 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 inform it.

Response Body Fields

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”). This is important, once you need the BULKID field when requesting the result of your bulk processing.

  • Response Code: Code defining the result of the bulk payment submission. the code is a 3 digit numeric code.

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


  • ATENTION: The response returned represents only the processing of the file, but not the processing of the transactions. For that there's another subfeature, described in the next section.


Bulk Payments Processing Result

This component allows you to request from the gateway a file with the details of each transaction processing.

This is also accomplished by means of a 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 Result https://testpayments.isvpay.io/merchant/bulkpayments/submit



Request Body Fields

Filter:

FIELD NAME REQUIRED DESCRIPTION
bulkid Y The bulk id supplied to merchant after submitting bulk payments file.
terminalid Y Terminal ID Provided by Worldnet Payments
hash Y A HASH code formed by part of the request fields. Take a look at ND001 - Hash Formation for more details.


Notes and Details About the Request

ND001 - Hash Formation

The general rule to build HASH field is given at the Special Fields and Parameters section. For this specific feature, you should use the following formats:

TERMINALID:BULKID:SECRET

Examples for a Request

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.


Response Body Fields

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.


Notes and Details About the Request

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 authorisation.
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 precceded by a comma and susceded by the next element, if there's any left.

ND002 - Hash Formation for Transaction on Result File

The general rule to build HASH field is given at the Special Fields and Parameters 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

  • 1. The CURRENCY is formed by a three letters code - i.e.: EUR.
  • 2. The AMOUNT is formatted using minor units based on the CURRENCY and then rounded to 2 decimals.


Copyright © 2024 | Powered by DokuWiki