A batch request is a single API call to upload a file containing a list of transactions. This section describes the batch syntax in detail. The next section contains sample calls.
The number of transactions that you can include in a single batch is limited by the size of the file upload. The maximum file size is 40MB. You should limit the number of transactions in a single batch request to 10,000, as you will encounter longer upload times when uploading larger files. If you need to make more calls than that, use multiple batch requests.
Transactions can reference raw bank or card data, or Payment Profile IDs. For more information on how create Secure Payment Profiles with banking information, check out Create Profile (Bank Account)
Test accounts need to be configured to enable Batch Payment functionality. We enable the functionality on request. You just need to email support.northamerica@bambora.com with your test account ID.
All requests to the Batch Payment API must be authorized. You can authorize a request by passing your merchant ID and API passcode in the Authorization header.
You can generate an API key for the Batch Payment API in the Member Area. After logging in, select administration, then account settings, and finally order settings.
On the Order Settings page, you'll find the Batch File Upload* section. Here you can set an API access code by clicking the Generate New Code button. Once you have a new code, click Update at the bottom of the page.
The authorization string is a base64 encoded concatenation of merchant_id, ":", and api_key. Your authorization header will be formatted like this.
Authorization: Passcode Base64Encoded(merchant_id:passcode)
If you have a partner account with us, you can specify the sub-merchant account on which to process the batched transactions.
A batch request is a single HTTPS request containing data for multiple transactions, using the multipart/form-data
content type. The transaction data is passed in CSV format. You can read more about the content-type
and boundary
directives on MDN.
The JSON object and file data are passed on a Content-Disposition headers. You can read more about them on MDN.
In addition to the content type and authorization headers, you will need to specify the filetype as 'STD', and you can also specify the date the batch should begin processing.
The API expects a single CSV file with one transaction per row, using Windows style end-of-line characters (CR+LF). It does not allow a header row, and you cannot omit any of the expected columns or the format of the payments will be incorrect.
The server's response is a single HTTPS response using the text content type. The response body is formatted as JSON and refers to the success of the upload of the batch request itself, not the success of the individual transactions it contained.
You can query individual transactions from a batch through the Batch Payment Report API and the Report API.
The response object contains a "code" property indicating the success of the request. This will be a number between 1 and 23, inclusive, where "1" indicates success. It has a "message" property with a description of the code. It also has a "process_date" property indicating the date that the batch will be sent to the bank to begin processing. The "batch_mode" property indicates if your account is in test or is live. The data is sent to the bank only for accounts that are live.
This section includes a sample HTTPS request that references a file to be uploaded and a sample request where the data is declared inline within the request. It also includes formatted sample data for bank-to-bank transfer and credit card payments.
The following two examples show the use of the Batch Payment API. You can run these cURL examples in your Terminal. You can create an encoded value for your authorization header here. You can also find these example batch requests in our Postman Collection.
curl -X POST \
https://api.na.bambora.com/v1/batchpayments \
-H 'authorization: Passcode {{passcode_encoded}}' \
-H 'content-type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW' \
-F file=@transactions.csv
curl -X POST \
https://api.na.bambora.com/v1/batchpayments \
-H 'authorization: Passcode your_encoded_passcode' \
-H 'content-type: multipart/form-data; boundary=WebKitFormBoundary7MA4YWxkTrZu0gW' \
-H 'filetype: STD' \
-d '--WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="criteria"
Content-Type: application/json
{
"process_date": ”20191125"
}
--WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="testdata"; filename="transactions.csv"
Content-Type: text/plain
E,C,001,99001,09400313371,10000,1000070001,ACME Corp
E,C,002,99002,09400313372,20000,1000070002,John Doe
E,C,003,99003,09400313373,30000,1000070003,Jane Doe
--WebKitFormBoundary7MA4YWxkTrZu0gW--
'
curl -X POST \
https://api.na.bambora.com/v1/batchpayments \
-H 'authorization: Passcode your_encoded_passcode' \
-H 'content-type: multipart/form-data; boundary=WebKitFormBoundary7MA4YWxkTrZu0gW' \
-H 'filetype: STD' \
-d '--WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="criteria"
Content-Type: application/json
{
"process_date": ”20191125",
"sub_merchant_id: {{sub_merchant_id}}"
}
--WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="testdata"; filename="transactions.csv"
Content-Type: text/plain
E,C,001,99001,09400313371,10000,1000070001,ACME Corp
E,C,002,99002,09400313372,20000,1000070002,John Doe
E,C,003,99003,09400313373,30000,1000070003,Jane Doe
--WebKitFormBoundary7MA4YWxkTrZu0gW--
'
{
"code": 1,
"message": "File successfully received",
"batch_id": 10000001,
"process_date": "20170721",
"process_time_zone": "GMT-08:00"
}
E,C,001,99001,09400313371,10000,1000070001,ACME Corp
E,C,002,99002,09400313372,20000,1000070002,John Doe
E,C,003,99003,09400313373,30000,1000070003,Jane Doe
E,C,,,,10000,,,the_profile_id,dynamic descriptor
A,C,256072691,2025621034,PS,10000,0,Patrick Star
A,C,256072691,2025463767,PC,20000,0,Spongebob Squarepants
A,C,021200339,381036789124,PC,30000,0,Krusty Krab
C,P,,4030000010001234,0619,1000,reference_01,Daffy Duck,daffy@example.com,0
C,P,,4030000010001234,0520,2000,reference_01,Bugs Bunny,bugs@example.com,0
C,P,,4030000010001234,0421,3000,reference_01,Porky Pig,porky@example.com,0