--- developer:api_specification:hpp_bulk_payments_features [2019/10/30 14:00]
branko
+++ developer:api_specification:hpp_bulk_payments_features [2022/07/15 15:23] (current)
@@ Line 1: / Line 1: @@
+====== HPP Bulk Payments Feature ======
+~~TOC~~
+\\
+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 **[[merchant:existing_merchant:selfcare_system|%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
+<WRAP center important 100%>
+**REMEMBER**: All the URLs used in this guide are test environment related. Before going live contact our support team for the correct URLs.
+</WRAP>
+\\
+===== 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 | %URLBulkPayments |
+\\
+\\
+==== Request Body Fields ====
+The following fields represent the data which should be send to in your request.
+<searchtable>
+^ **FIELD NAME**        ^ **REQUIRED**  ^ **DESCRIPTION ** ^
+| TERMINALID        | Y         | Terminal ID Provided by %CompanyName                     |
+| 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). |
+</searchtable>
+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**.
+\\
+<WRAP center important 100%>
+**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.
+</WRAP>
+\\
+==== Notes and Details About the Request ====
+**ND001 - Hash Formation**
+The general rule to build HASH field is given at the **[[developer:api_specification:special_fields_and_parameters#the_hash_parameter|Special Fields and Parameters]]** section. For this specific feature, you should use the following formats:
+<WRAP center box 100%>
+TERMINALID:TRANSACTIONCOUNT:BATCHTOTAL:DATETIME:SECRET
+</WRAP>
+\\
+**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 Token. |
+| CARDTYPE	   | Y         | Card Type used for the transaction.\\ For more details visit **[[developer:api_specification:special_fields_and_parameters#the_card_types|Special Fields and Parameters - Card Types]]**.\\ This field can also admit the SECURECARD type, when using a Secure Token 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. |
+\\
+<WRAP center important box 100%>
+**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.
+</WRAP>
+\\
+**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 **[[developer:api_specification:special_fields_and_parameters#the_hash_parameter|Special Fields and Parameters]]** section. For this specific feature, you should use the following format:
+<WRAP center box 100%>
+TERMINALID:ODERID:AMOUNT:DATETIME:SECRET
+</WRAP>
+\\
+==== Examples for a Request ====
+  * **Scenario**: Minimum request, with only mandatory data.
+  * **Request**: Using a simple HTML Post.
+  * **Terminal Secret**: x4n35c32RT.
+<code html>
+<html>
+  <body>
+    <form action="%URLBulkPayments" 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>
+</code>
+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.
+<WRAP center important 100%>
+**REMEMBER** to change the Terminal Id and Terminal Secret for valid values.
+Verify the **[[developer:integration_docs|Integration Docs]]** for viable examples or contact our support team.
+</WRAP>
+<WRAP center important 100%>
+**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.
+</WRAP>
+\\
+==== 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 | %URLBulkResultPayments |
+\\
+\\
+==== Request Body Fields ====
+<searchtable>
+^ **FIELD NAME** ^ **REQUIRED** ^ **DESCRIPTION** ^
+| BULKID      | Y | The bulk id supplied to merchant after submitting bulk payments file.  |
+| TERMINALID | Y | Terminal ID Provided by %CompanyName                                   |
+| HASH | Y | A HASH code formed by part of the request fields. Take a look at **ND001 - Hash Formation** for more details. |
+</searchtable>
+\\
+==== Notes and Details About the Request ====
+**ND001 - Hash Formation**
+The general rule to build HASH field is given at the **[[developer:api_specification:special_fields_and_parameters#the_hash_parameter|Special Fields and Parameters]]** section. For this specific feature, you should use the following formats:
+<WRAP center box 100%>
+TERMINALID:BULKID:SECRET
+</WRAP>
+\\
+==== 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 **[[merchant:existing_merchant:other_information:transaction_responses|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. |
+\\
+<WRAP>
+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.
+</WRAP>
+**ND002 - Hash Formation for Transaction on Result File**
+The general rule to build HASH field is given at the **[[developer:api_specification:special_fields_and_parameters#the_hash_parameter|Special Fields and Parameters]]** section. For this specific feature, you should use the following formats:
+If the terminal uses a single Currency.
+<WRAP center box 100%>
+TERMINALID:ORDERID:AMOUNT:DATETIME:RESPONSECODE:RESPONSETEXT:SECRET
+</WRAP>
+If the terminal is Multi Currency.
+<WRAP center box 100%>
+TERMINALID:ORDERID:CURRENCY:AMOUNT:DATETIME:RESPONSECODE:RESPONSETEXT:SECRET
+</WRAP>
+  * **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.
+\\

Differences

Worldnet

Learn More

Request

Contact Us