Batch API

The batch API supports multiple requests (max 100) combined into one request to our Batch API endpoints:

Endpoints

Transactions

Test endpoint:

https://testcheckout.buckaroo.nl/json/batch/Transactions

Live endpoint:

https://checkout.buckaroo.nl/json/batch/Transactions

Data Requests

Test endpoint:

https://testcheckout.buckaroo.nl/json/batch/DataRequests

Live endpoint:

https://checkout.buckaroo.nl/json/batch/DataRequests

Request Example

[
   {
      "AmountDebit": 10,
      "Currency": "EUR",
      "Invoice": "BATCHA12455110000",
      "Description": "124551 BATCHA12455110000",
      "StartRecurrent": "True",
      "Culture": "nl-NL",
      "Services": {
         "ServiceList": [
            {
               "Name": "CreditManagement3",
               "Action": "CreateCombinedInvoice",
               "Parameters": [
                  {
                     "Name": "InvoiceAmount",
                     "Value": "10.00"
                  },
                  {
                     "Name": "InvoiceDate",
                     "Value": "2020-02-10"
                  },
                  {
                     "Name": "DueDate",
                     "Value": "2020-10-03"
                  },
                  {
                     "Name": "SchemeKey",
                     "Value": "DefaultNone"
                  },
                  {
                     "Name": "Code",
                     "GroupType": "Debtor",
                     "Value": "JanVanPietersen123"
                  }
               ]
            },
            {
               "Name": "SepaDirectDebit",
               "Action": "Pay",
               "Parameters": [
                  {
                     "Name": "customeraccountname",
                     "Value": "John Smith"
                  },
                  {
                     "Name": "CustomerIBAN",
                     "Value": "NL32INGB00000XXXXX"
                  },
                  {
                     "Name": "CollectDate",
                     "Value": "2020-04-03"
                  }
               ]
            }
         ]
      }
   },
   {
      "AmountDebit": 10,
      "Currency": "EUR",
      "Invoice": "BATCHA12455110001",
      "Description": "124551 BATCHA12455110000",
      "StartRecurrent": "True",
      "Culture": "nl-NL",
      "Services": {
         "ServiceList": [
            {
               "Name": "CreditManagement3",
               "Action": "CreateCombinedInvoice",
               "Parameters": [
                  {
                     "Name": "InvoiceAmount",
                     "Value": "10.00"
                  },
                  {
                     "Name": "InvoiceDate",
                     "Value": "2020-02-10"
                  },
                  {
                     "Name": "DueDate",
                     "Value": "2020-10-03"
                  },
                  {
                     "Name": "SchemeKey",
                     "Value": "DefaultNone"
                  },
                  {
                     "Name": "Code",
                     "GroupType": "Debtor",
                     "Value": "JanVanPietersen123"
                  }
               ]
            },
            {
               "Name": "SepaDirectDebit",
               "Action": "Pay",
               "Parameters": [
                  {
                     "Name": "customeraccountname",
                     "Value": "John Smith"
                  },
                  {
                     "Name": "CustomerIBAN",
                     "Value": "NL32INGB00000XXXXX"
                  },
                  {
                     "Name": "CollectDate",
                     "Value": "2020-04-03"
                  }
               ]
            }
         ]
      }
   }
]

Success Response

A correct batch API request will result in a gateway response with the message that the transactions are queued for processing at Buckaroo.

Example

{
   "Message": "2 transactions were queued for processing."
}

Error Response

The batch API has basic validation: required parameters and value formats. Such validation errors are returned in the gateway response. The error field is an array of objects with the properties “Reference” and “Message”. The reference refers to the InvoiceNumber used in the request. The message will contain the error message related to the request using the referenced InvoiceNumber.

If one or more basic validation errors occur, the entire batch will be rejected and nothing will be processed. The gateway response will return every validation error found per transaction object, referring to each object by its invoice number.

The batch API does not perform service-specific validations, for example, Credit Management validations like correct scheme key, invoice and due dates, and duplicate invoice numbers. Service-specific validation errors are notified through the transaction push response.

Example

{
   "Message": "One or more validation errors occurred.",
   "Errors": [
      {
         "Reference": "INV00001",
         "Message": "amount should be provided for the action."
      }
   ]
}

Push messages and the Batch API

The Batch API does send push messages, but the behavior is different from individual transaction calls:

Push messages are sent per transaction within the batch, not per batch job.
Pushes are sent asynchronously — they may arrive after a delay depending on batch queue size and processing time.
The PushURL you configure in the Plaza under Settings > Websites is used. You cannot override the PushURL at the batch request level.
There is no "batch completed" push — you receive individual transaction pushes as each transaction is processed.

If you are not receiving pushes from batch transactions:

Confirm the PushURL is set correctly and reachable in your batch API request and/or under Settings > Websites in the Plaza if applicable if no pushURL was provided in the API request.
Check that your server returns HTTP 200 for push requests.
Allow extra time — batch transactions process in a queue and pushes may arrive later than real-time transactions.