API Workflow & Setup
This document outlines the standard (Happy-path) flow for the BDD API. It explains how to initiate a bulk direct debit, retrieve its status, and use optional headers to control specific initiation behaviors.
To test error scenarios, see Try it Out (Sandbox).
Bulk Direct Debits flow
-
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:
- The customer authorises the direct debit batches in Rabo Business Banking or Rabo Business Banking Pro using Sign/Sign Orders from the menu.
- 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:
- 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.
Before you begin
Before you initiate an instant payout, you should to meet the following requirements.
Sandbox Requirements
- Set up a sandbox account
- Set up sandbox application and subscription to either:
- Business Direct Debit Sandbox
- Set up your Mutual TLS connection, you can find our example certificates for sandbox here.
- Set up your signing flow, you can find our example certificates for sandbox here.
- Set up your Oauth flow
- Set up sandbox application and subscription to either:
Production Requirements
- Set up a production account. To get a production account, see Go to Production
- Set up production application and subscription to either:
- Business Direct Debit
- Set up your Mutual TLS connection with your EV SSL certificate
- Set up your signing flow with your EV SSL certificate
- Set up your OAuth flow
- Set up production application and subscription to either:
Required Headers
You are required to sign the payload for both the POST (creation of an instant payment order) and GET (retrieve status of an instant payment order) requests.
Read our Validate Signing Requests documentation for a detailed description of our signing method.
Required headers to include in your requests are:
| Name | Description | Format |
|---|---|---|
| Date | The date in a RFC-compliant date/time format. | String |
| Digest | The digest is a base64 encoded hash of the body. | String |
| X-Request-ID | The X-Request-ID is a UUID generated by you. | UUID |
| Signature | The signature is the signing string signed with your private key. | String |
| Signature-Certificate | The signature certificate is the public part of your EV SSL signing certificate. | String |
| PSU-IP-Address | The PSU-IP-Address consist of the IP address of the initiating party. | String |
| Content-Type | Defines the type of the request. Only required for POST requests. | String |
| X-IBM-Client-ID | The X-IBM-Client-ID is a UUID generated by your application. | UUID |
| Authorization | The Authorization header should include your access token. | String |
Step 1 — Create a bulk direct debit order
The POST call requires a PAIN008 file, read more about it here.
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
Purpose: These endpoints can be used to initiate a bulk direct debit order. A successful call returns a paymentId and an initial transactionStatus.
Step 2 — Retrieve status of an instant payment 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
Purpose: Retrieves the latest status for a previously initiated bulk direct debit using the paymentId.
You can only use business current accounts as Ordering account/Creditor Account.