Business Direct Debit (BDD) is a part of Rabo BoekhoudKoppeling and Rabo Banking Link. This API supports all third parties and direct connectors.

This API allows Rabobank business account holders to process bulk direct debits through your application.

Using BDD, you can optimize the customer journey in your web service.

We offer two variations of the BDD API:

Business Direct Debit:
- With signing for the Rabobank creditor in Rabo Business Banking
Business Direct Debit – STP:
- Straight Through Processing (STP), without signing for the Rabobank creditor
- Only available for Direct Connectors

To know more read the manual that connects to your use case:

Prerequisites

Business Direct Debit

Signed contract for Rabo Banking Link - Business Direct Debit
Subscribe your application to Business Direct Debit
Use OAuth scope: bdd.bulk.read-write in the consent flow

Business Direct Debit - STP

This option is only available if you execute direct debits from your own account (Direct Connector)
Signed contract for Rabo Banking Link for Direct Connectors - Business Direct Debit STP
Subscribe your application to Business Direct Debit STP
Use OAuth scope: bdd.stp-directdebit.read-write in the consent flow

Authentication

These APIs use token-based authentication, which consists of 2 things:

Consent granted by the account holder
Access token, with the integrated consent.

With the /authorize endpoint the account holder is requested to give consent for a certain API (scope). After the consent is granted, an authorization code is returned. This authorization code should be used in the /token call to retrieve an access token. This access token is a Bearer token that you use in the Authorization header of each request.

Set up using the Authorization Services API .
Read the complete OAuth guide.

Relevant scope(s) for oauth2 access code flow

API	Scope name	Description
Business Direct Debit	bdd.payments.write	Send direct debit files, signing in RBB required
Business Direct Debit - STP	bdd.stp-directdebit.read-write	Send direct debit batch files using straight through processing (already signed, will be executed directly) for Direct Connectors

Consent required for Third Parties and Direct Connectors:

Third Party
- Performing actions on behalf of your customers (Rabo account holders)
- The account holder must provide consent to the third party to Rabobank on behalf of their organisation for the specified account(s) and scopes (provide access to specific actions). This consent is continuous.
Direct Connector
- Performing actions on/from your own account
- You must provide consent for technical reasons for the specified account(s) and scopes (provide access to specific actions). This is a one time action.

📘
Make sure that you use the Authorization and Token URL as provided by the Authorization Services.

Limits

Size limits

Direct Debit files containing multiple batches can be sent to the bank using BDD or BDD-STP, with a maximum of 3,000 batches per file. To ensure smooth processing, do not exceed 25,000 direct debit orders in a one direct debit file. Larger files—up to 100,000 direct debit orders—can be processed if compressed using GZIP.

Rate Limiting

A default rate limit plan is set for all APIs. The rate limit can be shared or defined per operation. The table below describes the rate limiting for the Business Direct Debit product.

Operation	Type	Limit (API calls / s)	Counts towards shared limit
`POST /bulk/direct-debits`	Individual	5	No
`GET /bulk/direct-debits/{paymentId}/status`	Individual	10	No
All (premium) Oauth calls	Shared	10	Yes

The table below describes the rate limiting for the Business Direct Debit STP product.

Operation	Type	Limit (API calls / s)	Counts towards shared limit
`POST /bulk-stp/direct-debits`	Individual	5	No
`GET /bulk-stp/direct-debits/{paymentId}/status`	Individual	10	No
All (premium) Oauth calls	Shared	6	Yes

Bulk Direct Debits step-by-step

The API user sends the file(s) containing direct debit batches using Business Direct Debit.
Rabobank provides the status of the submitted bulk upload.
Flow in case of signing in RBB:
1. The customer authorises the direct debit batches in Rabo Business Banking or Rabo Business Banking Pro using Sign/Sign Orders from the menu.
2. After successful authorisation, Rabobank processes the direct debit batches following their process, same as if the direct debit is submitted using a Rabobank channel.
Flow in case of STP:
1. Rabobank processes the direct debit batches following their process, same as if the direct debit is submitted using a Rabobank channel.
The API user can retrieve the status of the individual direct debits in the batches through PAIN-002.

Requests

The POST Payment and GET Status requests must contain a digital signature. You can generate this digital signature using the private key of your certificate. For the Sandbox environment, you can use an example certificate available in the Signing documentation .

The POST call requires a PAIN008 file, read more about it here .

You can initiate a bulk direct debit order with Creation of a bulk direct debit order.

Endpoints:
Creation of a bulk direct debit order
POST /payments/bulk/direct-debits

Creation of a STP bulk direct debit order
POST /payments/bulk-stp/direct-debits

You can retrieve the status of a bulk direct debit order with Status of a bulk direct debit order.

Endpoints
Status of a bulk direct debit order
GET /payments/bulk/direct-debits/{paymentId}/status

Status of a STP bulk direct debit order
GET /payments/bulk-stp/direct-debits/{paymentId}/status

📘
You can only use business current accounts as Ordering account/Creditor Account.

Response

POST Payment initiation for Business Direct Debit.

You can initiate bulk direct debits using a POST direct debits request.

After receiving the direct debits, a response of RCVD or RJCT is returned. You can use the status endpoint to get the latest status of the direct debits.

   <?xml version="1.0" encoding="UTF-8"?>
      <InitiatedTransactionResponse>
          <_links>
             <status>
                 <href>/payments/bulk/direct-debits/123e4567-e89b-42d3-a456-556642440000/status</href>
             </status>
          </_links>
          <paymentId>123e4567-e89b-42d3-a456-556642440000</paymentId>
          <transactionStatus>RCVD</transactionStatus>
      </InitiatedTransactionResponse>

If a required header is not provided or left blank, then the status of the response is always 400 BAD REQUEST and the response contains the missing header name. For example if the header Signature is missing, then the response is:

{
       <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
       <ErrorResponse>
         <errorMessages>
           <category>WARNING</category>
           <code>FORMAT_ERROR</code>
           <text>Required header 'signature' is not present</text>
         </errorMessages>
       </ErrorResponse>
                  }

Below you can find all supported test scenarios. In order to test these scenarios, call the API by using the examples for the fields provided in the endpoint description for POST/direct-debits.

Request Scenario	Response	Remark
Valid Request with valid PAIN008 xml file	201 CREATED	multipart/form-data with payload variable name as xml_dd
Send Request with required header missing	400 BAD REQUEST	Make a request without a header such as PSU-IP-Address
Create payment with invalid multiform	400 BAD REQUEST	Only for Sandbox
Send Request with incorrect header format	400 BAD REQUEST	Only for Sandbox
Large PAIN008 xml file	400 BAD REQUEST	Make a request with PAIN008 xml file larger than 64MB and valid digest
PAIN008 xml file is missing *	400 BAD REQUEST	Make a request without the PAIN008 xml file
PAIN008 xml file is empty *	400 BAD REQUEST	Make a request with and empty PAIN008 xml file
Send Request with invalid signature	401 Unauthorised - Invalid Signature	Make a request with an invalid signature
Send Request with invalid certificate	401 Unauthorised - Invalid Certificate	Make a request with an invalid certificate
Send Request with invalid digest	401 Unauthorised - Invalid digest	Make a request with an invalid digest
If there is no consent for the used accounts	401 Unauthorised - No permissions found	Make a request with an account that has no permissions for this product type
Server issue with the account consent	500 Internal server error	Internal Server Error, Permissions for this product type cannot be accessed
Use PUT instead of POST method	405 Method Not Allowed	Use an incorrect HTTP method when making the request

Note: These codes are for Sandbox only.

For test scenarios marked with * use the following values for the Digest and Signature header:

Scenario

Digest + Signature

400 Bad Request, PAIN001 missing

digest: sha-512=XQ48ASLpmAaHugPp6xxefYxP7rZSDsT3cDjq8Xe9wAVfIoaufLDAP3zpc7O9Lk2pva1xPTSP/a2/yemgVGwnRw== </li><li>signature: keyId="1523433508",algorithm="rsa-sha512",headers="date digest x-request-id",signature="d7srUHUwsoN1GJas1dtDmaa5ho9JUgNLX4bKA6GgbB+mxKe3qx6x6RRDPhE+Jo5fz31Jp/ZcjHslQkH1mt1xsalHAr0eJyVe6DYfyW8uJKHCDOWMoauzI2b/TxiI4nS+yYkUr+5wLiBh02lYtq8hDtAJNlpuGJbRVPc9a0T7TErefeh8famvWffRUCmTqWZdU7oxyBColVOYmUoS9ZCMxrBMUi/24txIGciiqVyvfVkrP8yTaKL2CknGLc06G5UWfwm/xnU4qzlRIAOJNT752+ol5JC1mZTZZUdoHJtwPovHcMZrIbmM0S3m0HccZH/NCr8umZyScwy9ic4w3ZVYzg=="

400 Bad Request, PAIN001 empty

digest: sha-512=Ee51KhNukKes30kaFD9UZkwFR57ybIIfOwch1d/lPX0q5lhpD/aC44kALU4OYNyh+gHbDA/ly2nFnHZjOXN5gA== </li><li>signature: keyId="1523433508",algorithm="rsa-sha512",headers="date digest x-request-id",signature="Pob7hhQM7kyAg0pCXnaWWKMPuZMtVLCYv+fjuozc4HnJ4wDnzx0DsoUlNjtZ3sd9AJV9mR241KgTMn5h4mgstTL/7PvbUaz1JejlA827kjL4mXR12B9okgypC0d5QMraSBzjsUHYu4sCxAvVXnLHK1TZ93qJJChLk9KOydJepRN+O2K123UNORJ/9MHzVbV5gt9XGs4fTMCAQRNAKsqbnLvSqGqbVmVsfawdCmAojj7h3kFwWg9XQzja1CYwxjz2GuE5sgc7jif/XvNstFz8i7KRpDzQiG0jK0910MNmZAkOhhYfSwhmYWKFQfeP1fPZT+oR0WMQp0iTUa3nZPg01w=="

GET Payment Status for Business Direct Debit.

You can retrieve the status information for a direct debit initiation using a GET status request.

{
      <?xml version="1.0" encoding="UTF-8"?>
      <Document xmlns="urn:iso:std:iso:20022:tech:xsd:pain.002.001.03">
          <CstmrPmtStsRpt>
              <GrpHdr>
                  <MsgId>RABO-PAIN002-PO-0000000001865274433</MsgId>
                  <CreDtTm>2021-08-09T15:42:17.252</CreDtTm>
                  <InitgPty>
                      <Id>
                          <OrgId>
                              <BICOrBEI>RABONL2U</BICOrBEI>
                          </OrgId>
                      </Id>
                  </InitgPty>
              </GrpHdr>
              <OrgnlGrpInfAndSts>
                  <OrgnlMsgId>MMMM20211231v1</OrgnlMsgId>
                  <OrgnlMsgNmId>PAIN.008.001.02</OrgnlMsgNmId>
                  <OrgnlCreDtTm>2013-07-18T10:00:00.000</OrgnlCreDtTm>
                  <OrgnlNbOfTxs>1</OrgnlNbOfTxs>
                  <OrgnlCtrlSum>0.02</OrgnlCtrlSum>
                  <GrpSts>ACTC</GrpSts>
              </OrgnlGrpInfAndSts>
              <OrgnlPmtInfAndSts>
                  <OrgnlPmtInfId>PmtInfId-DD20211231-1</OrgnlPmtInfId>
                  <OrgnlNbOfTxs>1</OrgnlNbOfTxs>
                  <OrgnlCtrlSum>0.02</OrgnlCtrlSum>
                  <PmtInfSts>ACSC</PmtInfSts>
              </OrgnlPmtInfAndSts>
          </CstmrPmtStsRpt>
      </Document>
    }

Some scenarios, as mentioned below, require specific paymentId(s) in the URL, example: (/payments/bulk/direct-debits/paymentId/status) to get the mentioned responses.

Response	Scenario	Payment-id	Remark
PAIN002 file	200 OK	123e4567-e89b-42d3-a456-556642440000	All statuses are returned as a part of a PAIN002 file after the payment is processed.
RCVD	200 OK	123e4567-e89b-42d3-a456-556642440007	This is an initial status indicating that a payment initiation is received but not yet processed by Rabobank's order manager.
RJCT	200 OK	123e4567-e89b-42d3-a456-556642440008	The payment initiation is rejected.
	500 Internal Server Error	123e4567-e89b-42d3-a456-556642444324	Resource Unknown. An error occurred during the processing of the request.
	500 Internal Server Error	123e4567-e89b-42d3-a456-556642440005	Payment Id not found
	400 BAD REQUEST	any paymentId	The request contains invalid or missing data. For example the PSU-IP-Address is missing in the header
	401 Unauthorised	any paymentId	Make a request with an invalid digest or signature or certificate.

Response Status

Here is a description of the expected response statuses:

Statuses present in the POST response

RCVD: Payment file received
RJCT: Payment file rejected

Statuses present in the GET response

Interchange status/group status:

ACTC: Payment successfully created
RJCT: Payment rejected.

Batch status:

RCVD: Payment batch received.
ACTC: Awaiting authorization.
ACCP: Payment authorized.
ACSC: Payment processed.
RJCT: Payment rejected, expired, or cancelled.
PDNG: Payment pending.

Transaction status on individual payment in the batch:

RJCT: Payment rejected.
ACCP: Payment authorized.
CANC: Payment withdrawn.
PDNG: Payment pending.
ACSC: Payment processed.