API Workflow & Setup

This document outlines the standard (Happy-path) flow for the BIP API. It explains how to initiate a payment, retrieve its status, and use optional headers to control specific initiation behaviors. In addition, it details the available status codes and their definitions.

To test error scenarios, see Try it Out (Sandbox).

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 Instant Payout - Direct Connectors
- Business Instant Payout - Third Parties
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 Instant Payout - Direct Connectors
- Business Instant Payout - Third Parties
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
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
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

Step 1 — Creation of instant payment order

Endpoints:

Creation of a payment order of type Sepa Credit Transfer
POST /bip/v3/payments/single-credit-transfers

Creation of a payment order of type Cross Border Credit Transfer POST /bip/v3/payments/cross-border-credit-transfers

Purpose:
These endpoints can be used to initiate an instant payment order. A successful call returns a paymentId and an initial transactionStatus (typically RCVD).

Optional headers

Name	Description	Format
Sepa-Reroute-Allowed	Reroute functionality to execute the payment instruction as a SEPA CT transaction. Possible values : Yes/No	String
Verify-Payee	Indicate whether Rabobank should perform the Verification of Payee (VoP) check. Default value is yes. Possible values : Yes/no	String

Sepa-Reroute-Allowed: Yes or No

If set to Yes, initiating an instant payment order to a beneficiary whose bank is not connected to the instant payment network, results in the payment automatically being rerouted to the SEPA network.

📘
Important:
The SEPA network keeps the transaction in status ACSP for up to 3 days if there are insufficient funds.

If funds become available within 3 days, the payment is executed.

If funds do not arrive within 3 days, the payment is automatically cancelled.

If set to No, initiating an instant payment order to a beneficiary whose bank is not connected to the instant payment network, the payment is automatically rejected.

Verify-Payee: Yes or No

By default, Rabobank performs a Verification of Payee (VoP) check for every payment instruction. This check ensures that the account number matches the provided account holder name.

If there is a mismatch, the payment is rejected.

You can use this header to indicate whether Rabobank should perform the VoP check:

if you have already verified the payee, you can select No by using our Payee Account Check

📘
Liability If you select No but fail to perform a VoP check by other means, you are liable for any resulting losses.

Step 2 — Retrieve status of an instant payment order

Endpoint:

Status of an instant payout order of type Sepa Credit Transfer
GET /bip/v3/payments/single-credit-transfers/{paymentId}/status

Status of an instant payout order of type Cross Border Credit Transfer GET /bip/v3/payments/cross-border-credit-transfers/{paymentId}/status

Purpose: Retrieves the latest status for a previously initiated payment using the paymentId.