Single Payments
This document outlines the standard (Happy-path) flow for the BPI - Single API. It explains how to initiate a payment, retrieve its status, and use optional headers to control specific initiation behaviors.
To test error scenarios, see Try it Out (Sandbox).
With single payment initiation, you can initiate Single credit transfers directly or on behalf of your users with a Rabobank business payment account and retrieve the status of an initiated transaction.
Single payments flow
Before initiating single payments, the account holder must provide consent to their account or a third party for sending single payment orders to Rabobank on behalf of their organization for the specified payment account(s). This consent is continuous.
-
The account holder initiates the payment order to be executed by Rabobank using your platform.
-
Rabobank provides the API user (third party) with the status on the submitted upload.
-
The customer authorizes the payment:
- in Rabo Business Banking or Rabo Business Banking Pro using Sign/Sign orders from the menu, or
- 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 starts processing the payment order following its payment process same as if the payment is submitted using a Rabobank channel.
Example:
- If a payment order is refused due to insufficient funds, we may check one or more times, up to and including three working days after the date of refusal, whether the reason for refusal still exists. If we believe that there is no longer a reason for refusal, we may restart processing the payment order on behalf of our customer.
- When processing a Euro Payment, we check whether the beneficiary's bank is reachable for Instant Payments. If true, we process the payment order as an Instant Payment. If false, we process the payment order as a normal SEPA Credit Transfer.
-
The third party can retrieve the status of the payment through the status endpoint to keep track.
Before you begin
Before you initiate a single payment, you should to meet the following requirements.
Sandbox Requirements
- Set up a sandbox account
- Set up sandbox application and subscription to either:
- Business Payment Initiation
- 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 Payment Initiation
- 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 |
|---|---|---|
| Content-Type | Defines the type of the request. Only required for POST requests. | string |
| X-Request-ID | The X-Request-ID is a UUID generated by you. | UUID |
| PSU-IP-Address | The PSU-IP-Address consist of the IP address of the initiating party. | string |
| Signature-Certificate | The signature certificate is the public part of your EV SSL signing certificate. | string |
| Date | The date in a RFC-compliant date/time format. | string |
| Signature | The signature is the signing string signed with your private key. | string |
| Digest | The digest is a base64 encoded hash of the body. | 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 payment order
Endpoints:
Creation of a payment order of type Sepa Credit TransferPOST /payments/v1/single/sepa-credit-transfers
Creation of a periodic payment order of type Sepa Credit TransferPOST /payments/v1/periodic/sepa-credit-transfers
Creation of a payment order of type Cross Border Credit TransferPOST /payments/v1/single/cross-border-credit-transfers
Creation of a payment order of type Periodic Cross Border Credit TransferPOST /payments/v1/periodic/cross-border-credit-transfers
Purpose: These endpoints can be used to initiate an payment order. A successful call returns a paymentId and an initial transactionStatus.
Optional headers
| Name | Description | Format |
|---|---|---|
| redirectionFlag | Defaults to No . The user can decide if a payment should be signed immediately or in RBB. This flag value should be 'Yes' or 'No' and the default value is 'No' which means signing in RBB. Note: The parameter 'IP-Redirect-URI' becomes mandatory when this parameter is sent as 'Yes'. | string |
| IP-Redirect-URI | URI of the initiating Party, where the transaction flow shall be redirected to after a Redirect. Note: This parameter becomes mandatory only when the parameter 'redirectionFlag' is sent as 'Yes'. | string |
redirectionFlag
The third party can decide to offer the account holder the choice to sign a payment immediately or in RBB.
If set to Yes, the IP-Redirect-URI field becomes a mandatory field. The user is redirected to signing screens to sign the payment and after the payment is signed, the users is redirected back using the URL in the IP-Redirect-URI field.
If set to No, the payment is signed in RBB. This means the payment flow stops and the user should login to RBB and manually sign the payment.
The default value is set to No.
IP-Redirect-URI
If the redirectionFlag is set to Yes, the IP-Redirect-URI becomes mandatory. After signing the payment, the user is redirected back using the URI entered as input in this field.
Example: If a payment is initiated using a third party app, the user is redirected to the signing screens. After signing the payment, the user is redirected back to the third party app. See Signing flow for single payments
Step 2 — Retrieve status
Endpoints :
Status of a single sepa paymentGET /payments/v1/single/sepa-credit-transfers/{paymentId}/status
Status of a periodic sepa paymentGET /payments/v1/periodic/sepa-credit-transfers/{paymentId}/status
Status of a cross border paymentGET /payments/v1/single/cross-border-credit-transfers/{paymentId}/status
Status of a periodic cross border paymentGET /payments/v1/periodic/cross-border-credit-transfers/{paymentId}/status
Purpose: Retrieves the latest status for a previously initiated payment using the paymentId.
Step 3 — Retrieve details
Endpoints:
Details of a single sepa paymentGET /payments/v1/single/sepa-credit-transfers/{paymentId}
Details of a periodic sepa paymentGET /payments/v1/periodic/sepa-credit-transfers/{paymentId}
Details of a cross border paymentGET /payments/v1/single/cross-border-credit-transfers/{paymentId}
Details of a periodic cross border paymentGET /payments/v1/periodic/cross-border-credit-transfers/{paymentId}
Purpose: Retrieves the details of a previously initiated payment using the paymentId.