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.
The customer authorizes the payment:
1. The customer authorizes the payment batches in Rabo Business Banking or Rabo Business Banking Pro using Sign/Sign Orders from the menu, or.
2. directly from your platform, using the redirect URL that you received from us (optional and on request) after submitting the payment order.
  After successful authorization, Rabobank processes the payment batches following their payment process, same as if the payment 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.

Before you begin

Before you initiate an instant payout, you should 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

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

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

Optional Headers

Optional headers to include in your requests for POST (creation of an instant payment order) are:

Name	Description	Format
redirectionFlag	The user can decide if a payment should be signed immediately or in RBB, Default value is 'NO' which means sign later	String
IP-Redirect-URI	Redirect url of the Third party provider, This field will be come mandatory if redirectionFlag is 'YES'	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.

Bulk Direct Debits flow

Before you begin

Required Headers

Optional Headers

Step 1 — Create a bulk direct debit order

Step 2 — Retrieve status of an instant payment order

Download API Specification