NAV Navbar
shell

Introduction

Welcome to Online Payment Platform (OPP). We are glad that you want to integrate our product into your service. We provide several options in order to make your service compliant to laws, concerning financial flows. This document describes how to communicate with the OPP REST API. You will be able to create merchants, bank accounts, transactions, mandates and more! You will learn what responses to expect, and more importantly, which calls to make for a seamless integration.

Our API works with raw JSON, which means all GETs will return JSON, and all POSTs accept and return only JSON as well. Aside every chapter, we will provide an example request and respond if possible.

Terminology

OPP uses some basic terminology. Find their explanations in the table below.

Term Explanation
Partner You, the platform, who will be integrating OPP.
Merchant Any customer of your platform. Any receiver of money
Know Your Customer (KYC) By law, OPP is obliged to know who we pay-out money to. Therefore, we apply compliance levels to fulfil to the KYC procedure.
Ultimate Beneficial Owner (UBO) Representative of the company. An UBO is a natural person that has:
  • 25% of the shares or exercising voting rights
  • effective control of the company or organization
  • 25% or more beneficiary rights on the capital
  • special control of 25% or more on the capital
Transaction A transaction is created whenever a merchant pays money to another merchant
Settlement The "balance" of a merchant. Once the settlement period expires, OPP will pay-out the merchant.
Escrow Money that has been payed by a merchant, but has not yet been put on the settlement of the receiving merchant.
Chargeback Revert all the money of a transaction that is in escrow back to the merchant who payed the money.
Refund Revert (part of) the money of a transaction that is on the settlement of the receiving merchant.

Environments

OPP knows two environments. A sandbox environment, in which you will be able to test all sorts of scenario's, and a production environment, which will be used for live customers.

Both environments use a different API key. You authenticate to the environment and its API by providing one of the API keys in every request you perform. The producation API key will be provided to you, after contracting is finalized and the go-live checklist is signed. You can view your API keys through your Partner/Merchant Login.

Please keep in mind that API keys provide many privileges. Make sure to keep them safe.

Sandbox

The OBP Sandbox is a virtual testing environment that mimics the live OBP production environment. You will be using the Sandbox version of the API and application. All resources created on sandbox are tests and will not be available on production. No actual payments are made or processed. Where needed a simulation mode will be provided to test various scenario’s.

In order to use the sandbox environment successfully, please whitelist the IP: 3.122.130.129

sandbox API URL: https://api-sandbox.onlinebetaalplatform.nl/v1
sandbox API key: APIKEY:

Production

In order to use the production environment successfully, please whitelist the IP's:

production API URL: https://api.onlinebetaalplatform.nl/v1
production API key: APIKEY:

API Basics

Before we dive into the deep matter of the OPP API, we first need to explain some basics. This chapter will guide you through all basic functionality necessary for you to get the most out of our product!

Responses

Example response - Transaction creation without providing the required merchant_uid:

{
    "error": {
        "code": 400,
        "message": "Missing required merchant_uid"
    }
}

OPP uses the default HTTP response codes to indicate failure or success of an API request. We will always return a JSON string, even if an error occurred.

Code Message Description
200 OK Success
400 Bad Request Missing parameter(s)
401 Unauthorized Invalid or revoked API key
402 Request Failed Parameter(s) OK but something went wrong
404 Not Found Resource doesn't exist
50X Server Errors Temporary problem on our side

Pagination

Example request - Retrieve page 2 of the transactions list:

curl https://api-sandbox.onlinebetaalplatform.nl/v1/transactions \
    -u [API-KEY]: \
    -d page=2 \
    -d perpage=10

Example response:

{
    "livemode": true,
    "object": "list",
    "url": "/v1/transactions",
    "has_more": true,
    "total_item_count": 259,
    "items_per_page": 10,
    "current_page": 2,
    "last_page": 26,
    "data": []
}

When retrieving lists of objects, OPP creates pages to keep the transferred objects small. Use the pagination functionality to navigate when having many results. The pages can be switched by adding the following arguments to the POST call:

Argument Description
page integer The number of the current page.
perpage integer The limit of objects to be returned. Limit can range between 1 and 100 items.

The response sent can be seen below.

Response Description
object string value: "list"
url string The url that was called upon.
has_more: boolean Whether the object list has more pages.
total_item_count integer Total number of objects in the list.
items_per_page integer The number of items per page requested.
current_page integer The current page requested.
last_page integer The number of the last page that can be requested.
data array The actual data object list.

Notifications

Example response - Notification of a status change of a merchant's bank account status.

{
    “uid”: ”[notification_uid]”,
    “type”: ”bank_account.status.changed”,
    “created”: 1554199810,
    “object_uid”: ”[bank_account_uid]”,
    “object_type”: ”bank_account”,
    “object_url”: ”https://api-sandbox.onlinebetaalplatform.nl/v1/
     merchants/[merchant_uid]/bank_accounts/[bank_account_uid]”,
    “parent_uid”: ”[merchant_uid]”,
    “parent_type”: ”merchant”,
    “parent_url”: ”https://api-sandbox.onlinebetaalplatform.nl/v1/
     merchants/[merchant_uid]”
}

OPP provides a number of notifications which will be POST to the provided webhook or notify_url. The notifications are structured as described below. You may use the object_type to determine the related resource (e.g. a bankaccount or a transaction) and use the object_url to retrieve the object directly via API. You may receive notifications for nested resources, such as status updates for a multi transaction or a transaction. We add parent details to these notifications which makes it easier to find the related merchant for these resources.

Notification object Description
uid string Unique identifier of the notification.
type string Type of the notification.
created timestamp Timestamp when object is created.
verification_hash string Hash that can be used for validating notifications.
object_uid string Unique object identifier to which the type belongs.
object_type string Type of the object
object_url string Direct link to the object.
parent_uid string Unique parent object identifier to which the type belongs.
parent_type string Type of the parent object
parent_url string Direct link to the parent object.

Use the notification type to determine the required action you would need to take in your own system. Use the object uid and type to determine the related resource. Follow the object_url to retrieve the resource details.

To retrieve the updated details, you must query the API for the updated resource again. For security reasons you may block all notifications which do not originate from the IP ranges of the Sandbox/Production environment.

When we send notifications please ensure that your system handles the notification and responds with a 200 OK, 201 CREATE, 202 ACCEPTED or 204 NO CONTENT within 10 seconds. If we do not receive one of these statuses or when the notification times out, we will try to send the notification again using the following interval/scheme: after 1 minute, after 2 minutes and every 5 minutes after that for up to 10 tries.

A list of all possible notification types can be found below:

Signup Notifications:

Merchant Notifications:

Contact Notifications:

Bank Account Notifications:

Transaction Notifications:

Multi-transaction Notifications:

Payment Reference Notifications:

Mandate Notifications:

iDEAL Notifications:

Dispute Notifications:

Validating Notifications

In addition to whitelisting our notification servers' IP addresses you may also verify that a transaction is sent by us by verifying the verification_hash. The verification_hash can be compared using the notification_secret. The notification_secret can be found in your partner interface, or ask your implementation manager to provide it to you. To check the hash, use the following call: $ echo -n "[NOTIFICATION_UID]" | openssl sha256 -hmac "[NOTIFICATION_SECRET]" This will return true when the notification was sent by OPP. False if it was not.

Filter & Order

Example request - Transactions belonging to a certain merchant:

curl https://api-sandbox.onlinebetaalplatform.nl/v1/transactions \
    ?filter[merchant]=mer_a1b2c3d4e5f6

Example request - Transactions between a given datetime range:

curl https://api-sandbox.onlinebetaalplatform.nl/v1/transactions \
    ?filter[0][name]=date_completed \
    &filter[0][operand]=between \
    &filter[0][value]=2017-01-01 00:00:00, 2017-01-31 23:59:59

Filter Parameter

You may filter data retrieved via API by adding the filter parameter to your API call. OPP supports two different ways of using the filter parameter: simple and extended. A simple filter allows for a direct comparison on given VALUE in given FILTER.

Basic filter usage: ?filter[FILTER]=VALUE

An extended filter allows for complicated filters on given VALUE(S) in given FILTER using OPERATOR Extended filter usage: ?filter[KEY][name]=FILTER &filter[KEY][operand]=OPERATOR &filter[KEY][value]=VALUE

The following operators are accepted:

Operator Description Expected value(s)
lt less than single value
lte less than or equal to single value
gt greater than single value
gte greater than or equal to single value
in in given set comma separated values
notin not in given set comma separated values
null value null empty value
notnull value not null empty value
eq equals single value
notequals does not equal single value
between between given set comma separated values

Filtering Metadata

You may filter metadata by a specific key/value pair by providing both metadata as your filter name as well as your metadata key and value as your search field and value. This will result in a filter such as ?filter[metadata][KEY]=VALUE.

Order Parameter

You may order data retrieved via API by adding the order parameter to your API call. OPP supports both ordering data ascending and descending.

Order ascending: ?order[]=VALUE Order descending: ?order[]=-VALUE

Expanding objects

Example request - Expand the transaction with the order details:

curl https://api-sandbox.onlinebetaalplatform.nl/v1/transactions/[transaction_uid] \
    -u [APIKEY]: \
    -d expand[]=order

Example response:

{
    "livemode": true,
    "uid": "tra_1a2b3c1baeec",
    "object": "transaction",
    "metadata": [],
    "statuses":[],
    "order": {
        uid: "ord_1a2b3c6c8fd6",
        object: "order",
        created: 1554113700,
        updated: 1554113700,
        processed: true,
        price: 6000,
        shipping: 695,
        discount: 0,
        street: "van den Brinkring",
        housenumber: "174",
        housenumber_addition: null,
        zipcode: "7391 SW",
        city: "Nieuwediep",
        state: "Groningen",
        country: null,
        customer: {}
    }
}

Many objects contain a reference to another object. Those objects can be expanded inline with the expand parameter. The availability of the expand parameter and its options differ per request and are noted in the request descriptions.

You can nest expand requests with the dot property. For example, requesting a transaction including the related order and customer details can be done by requesting order and order.customer. The order property will be expanded into a full order object, and the customer property within the order object will be transformed into a full customer object. Expands can be used both when fetching a list of resources and when fetching a single resource.

Arguments
expand string name of expandable object

Metadata

Example request:

curl https://api-sandbox.onlinebetaalplatform.nl/v1/transactions \
    -u [API-key]: \
    -d "metadata[external_id]=2015486"

Most objects support metadata. You can add this to the resource in your requests to store additional key/value data to the object. Any metadata set on the object will be returned when the object is retrieved. Use this to keep track of your own internal identifiers or other relevant data. A useful example could be to store your corresponding unique identifier of an OPP object.

Merchants

OPP defines two kinds of merchants: Business merchants and Consumer merchants. This chapter will provide you all the necessary information about and functionality of a merchant object. OPP provides two options for onboarding merchants:

The Whitelabel onboarding redirects the merchant to a whitelabel page of OPP, where (s)he is able to fill in all the information required. Via the Seamless onboarding, you as a partner have complete influence on what is happening in the workflow. OPP often only functions in the background when the merchant API is used. This way, the user merchant will never leave your platform to go to a page created by OPP. Because of this, we always suggest partners to use the merchant API instead of the signup form.

Merchant object

You can retrieve an individual merchant as well as a list of all merchants. Be it in a list or as a single result, the data or merchant object will contain the following details. Certain data, such as profiles and payment methods may be expanded. Addresses, trading names can’t be expanded until further notice.

Merchant object Description
uid string Merchant unique identifier.
up to 20 characters
object string value: merchant
created timestamp Timestamp when object is created.
updated timestamp Timestamp when object is updated.
status string Status of the merchant object. One of: newpendinglivesuspendedterminatedblocked
compliance object Object that states all compliance requirements for the merchant.
type string Merchant type. One of: consumerbusiness
coc_nr string Chamber of Commerce number of the merchant.
up to 45 characters
nullable
!BUSINESS ONLY!
name string (Business) Name of the merchant.
up to 45 characters
vat_nr string Value added tax identification number.
up to 45 characters
!BUSINESS ONLY!
country string Country code of the merchant,
use ISO 3166-1 alpha-3 country code.
sector string Sector in which merchant is affiliate with.
up to 45 characters
nullable
addresses array Address array of the merchant with name/value pairs.
address_line_1 string First address line of the addressee.
up to 150 characters
address_line_2 string Second address line of the addressee.
up to 150 characters
zipcode string Zip code of the addressee.
up to 20 characters
city string City of the addressee.
up to 100 characters
country string Country code of the addressee,
use ISO 3166-1 alpha-3 country code.
trading_names array Array with one or more trading names.
nullable
name string Trading name.
contacts array Object containing contact information of the merchant.
profiles array Profile object of the merchant.
payment_methods array The available payment methods of the merchant.
notify_url string Notification url to receive status updates for this merchant.
up to 255 characters

Whitelabel onboarding

You can create a signup by calling the Signup API. You can retrieve an individual signup request as well as a list of all requests. Be it in a list or as a single result, the data or signup object will contain the following details. Once the signup is complete, the merchant_uid will be returned. The attributes of the signup object can be found below.

Signup object Description
uid string Signup unique identifier.
up to 20 characters
object string Value: signup
status string One of: createdpendingexpiredcompleted
created timestamp Timestamp when object is created.
updated timestamp Timestamp when object is updated.
completed timestamp timestamp when object is completed.
only once signup is completed (registered),
nullable
merchant_uid string Unique identifier of the created merchant.
only if signup is completed (registered),
up to 20 characters, default is: null
return_url string The merchant is directed to this url, once the signup is completed.
up to 255 characters
redirect_url string The merchant is directed to this url, for the signup.
up to 255 characters
notify_url string Notification url to receive status updates.
up to 255 characters
metadata array Set of key / value pairs to store additional data.
nullable

Create a Signup

Example request - Creating a signup:

curl https://api-sandbox.onlinebetaalplatform.nl/v1/signups \
    -u APIKEY: \
    -d type=business\
    -d return_url=https://platform.example.com/return \
    -d notify_url=https://platform.example.com/notify

Example response:

{
    “uid”: “sgn_1a2b3c4d5e6f7g8h”,
    “object”: “signup”,
    “status”: “pending”,
    “created”: 1554199810,
    “updated”: 1554199810,
    “completed”: null,
    “merchant_uid”: null,
    “return_url”: “https://platform.example.com/return”,
    “redirect_url”: “https://sandbox.onlinebetaalplatform.nl/nl/
     {merchant}/sgn_1a2b3c4d5e6f7g8h/
     verificatie/bedrijf/introductie”,
    “notify_url”: “https://platform.example.com/notify”,
    “metadata”: [ {
        “key”: “external_id”,
        “value”: “123456789”
    } ]
}
Create Signup object Description
locale required one of: nl en fr
type required one of: business consumer
return_url required The return url the customer is redirected to, once the signup process is completed.
up to 255 characters
notify_url required Notification url to receive status updates.
up to 255 characters
provide_login_credentials optional, boolean
data optional Set of key / value pairs to prefill signup form.
company_name optional name of the company,
[for review: up to 100 characters]
recommended for type = "business"
coc_number optional chamber of commerce number of the merchant,
between 8 and up to 10 characters
recommended for type = "business"
name_initials optional initials,
up to 8 characters
recommended for type = "consumer"
name_first optional first name,
up to 50 characters
recommended for type = "consumer"
name_last optional last name,
up to 50 characters
recommended for type = "consumer"
address_line_1 optional street name without house number and without house number addition,
up to 150 characters
housenumber optional house number, required when zipcode exists
numeric
housenumber_addition optional addition to the house number,
up to 10 characters
zipcode optional zip code for the address,
between 3 and 9 characters
city optional city of the address,
up to 100 characters
required when zipcode exists
recommended for type = "business"
country optional country code of the merchant,
use ISO 3166-1 alpha-3 country code
required when coc_number exists
recommended for type = "business"
emailaddress optional e-mailaddress,
up to 100 characters
phone optional phone number,
between 8 and up to 15 characters,
recommended for type = "business"
mobile_number optional dutch mobile phone number: "316XXXXXXXX" or suggested prefix "316"
recommended for type = "consumer"
will be used for SMS verification
metadata optional array with name / value pairs to store additional data
key required unique key within metadata object,
up to 255 characters
value required corresponding value,
up to 65535 characters

You can retrieve a signup request, and a list of all requests. Use either one of the following API calls to do so:

Signup status

A signup object can have one of the following statuses.

Signup Status
created Partner has created the signup request; no activity was found (redirect_url was never followed).
pending Consumer (merchant) has started signup process.
expired Consumer has not finished the signup process within 5 days.
completed Signup process is completed and merchant is created / can processed transactions. From this point the merchant_uid will be available in the signup object.

Signup e-mails

We will create an OPP account and send a verification e-mail to the e-mailaddress entered in the signup process once the process is completed. After verifying the e-mailaddress, a password will be send which allows the user to log in to the merchant backoffice. All e-mailaddresses must be unique or an error will be shown. If you do not have access to a mailbox with unlimited aliases, you may use a disposable e-mailaddress service such as yopmail.com or guerrillamail.com while testing the signup process.

Creating Merchants

Example request - Creating a consumer merchant:

curl https://api-sandbox.onlinebetaalplatform.nl/v1/merchants \
    -u APIKEY: \
    -d country=nld \
    -d emailaddress=tinus@merchant.example.com \
    -d notify_url=https://platform.example.com/notify

Example response:

{
    “uid”: “{merchant_uid}”,
    “object”: “merchant”,
    “created”: 1554113700,
    “updated”: 1554113700,
    “status”: “pending”,
    “compliance”: {
        “level”: 100,
        “status”: “verified”,
        “requirements”: []
    },
    “type”: “consumer”,
    “coc_nr”: null,
    “name”: “Tinus Tester”,
    “vat_nr”: null,
    “country”: “nld”,
    “sector”: null,
    “addresses”: [],
    “trading_names”: [],
    “contacts”: [],
    “profiles”: [],
    “payment_methods”: []
}

Creating a merchant can be done by calling a post to the merchant API: /v1/merchants. The required fields for creating a merchant are:

The more fields of the merchant object you fill in when creating a merchant, the easier representative verification (KYC) on our side can be done.

A merchant object contains three nested objects that provide information of the merchant:

Address object

Example request - Retrieve the address object from the merchant, using the address_uid:

curl https://api-sandbox.onlinebetaalplatform.nl/v1/merchants/{merchant_uid}/addresses/{merchant_address_uid} \
    -u APIKEY:

Example response:

{
    “uid”: “{merchant_address_uid}”,
    “object”: “merchant_address”,
    “created”: 1554199810,
    “updated”: 1554199810,
    “verified”: 1554201030,
    “type”: “default”,
    “address_line_1”: “Kerklaan 1”,
    “address_line_2”: null,
    “zipcode”: “1234AB”,
    “city”: “Amsterdam”
}

The address object contains all address information of the merchant. You can retrieve a single address object or a list of all addresses of a merchant by using one of the following calls to the API respectively.

Contact object

Example request - Retrieve merchant's contact information:

curl https://api-sandbox.onlinebetaalplatform.nl/v1/merchants/{{merchant_uid}}/contacts/{contact_uid} \
-u [API-key]:

Example response:

{
    "livemode": false,
    "uid": "{contact_uid}",
    "object": "contact",
    "created": 1409906820,
    "updated": 1516095074,
    "verified": 1516095074,
    "status": "verified",
    "verification_url": "https://onlinebetaalplatform.nl.local/nl/moneymedic/merchants/mer_610f4c187db9/verificatie/contactgegevens/con_e8bccd9c6b75/90e14fccbf154372d8f04a21e5f64aaaa4186b15",
    "type": "representative",
    "title": "mr",
    "name_initials": "MR",
    "name_first": "Victor",
    "name_last": "Palm",
    "names_given": null,
    "birthdate": "0000-00-00",
    "partner_name_last": null,
    "emailaddresses": [
        {
            "uid": "ema_9176a23a12c5",
            "object": "emailaddress",
            "created": 1409906820,
            "updated": 1552475854,
            "verified": null,
            "emailaddress": "phpunit-1552475854-update@throwaway.obp"
        }
    ],
    "phonenumbers": [
        {
            "uid": "pho_d347ee900808",
            "object": "phonenumber",
            "created": 1409906820,
            "updated": 1409906820,
            "verified": null,
            "phonenumber": "+31698317352"
        }
    ]
}

A contact object contains all contact information of the merchant. You can either retrieve a single contact object or a list of all contacts of a merchant. Retrieving a merchant's contact information can be done using the API call on the right.

A contact object has the following attributes:

Contact object Description
uid string Contact unique identifier.
up to 20 characters
object string Value: contact
type string Role of the contact,
one of: representative technical financial
created timestamp Timestamp when object is created.
updated timestamp Timestamp when object is updated.
verified timestamp Timestamp when object is verified.
null if not (yet) verified
status string Status of the contact verification.
verification_url string Url for verification of the contact.
title string Title of the contact,
one of: mrmrs
name_initials string Initials of the contact,
up to 10 characters, nullable
name_first string First name of the contact,
up to 50 characters, nullable
name_last string Last name of the contact,
up to 50 characters, nullable
birthdate date Birthdate of the contact.
nullable
emailaddresses array Array of emailaddresses[#][emailaddress]=value pair.
emailaddress email E-mailaddress details of the contact.
phonenumbers array Array of phonenumbers[#][phonenumber]=value pair.
phonenumber phonenumber Phone number details of the contact.

Profiles

Example request - Retrieve a merchant's profile:

curl https://api-sandbox.onlinebetaalplatform.nl/v1/merchants/{merchant_uid}/profiles/{profile_uid} \
    -u APIKEY:

Example response:

{
    “uid”: “{profile_uid}”,
    “object”: “profile”,
    “created”: 1554199810,
    “updated”: 1554199810,
    “status”: “live”,
    “name”: “Janssen Webshop”,
    “sector”: “ICT”,
    “url”: “https://webshop.example.com“,
    “po_number”: null,
    “contact”: null,
    “settings”: null,
    “bank_account”: null,
    “payment_methods”: [],
    “files”: null,
    “messages”: null
}

Example request - Get the list of merchant's profiles:

curl https://api-sandbox.onlinebetaalplatform.nl/v1/merchants/{merchant_uid}/profiles \
    -u APIKEY:

Example response:

{
    object : “list”,
    url: “/v1/merchants/{merchant_uid}/profiles”,
    has_more: false,
    total_item_count: 1,
    items_per_page: 10,
    current_page: 1,
    last_page: 1,
    data: [ {
        “uid”: “{profile_uid}”,
        “object”: “profile”,
        “created”: 1554199810,
        “updated”: 1554199810,
        “status”: “live”,
        “name”: “Janssen Webshop”,
        “sector”: “ICT”,
        “url”: “https://webshop.example.com“,
        “po_number”: null,
        “contact”: null,
        “settings”: null,
        “bank_account”: null,
        “payment_methods”: [],
        “files”: null,
        “messages”: null,
    } ]
}

Every merchant has at least one profile. This profile is created automatically, and most of the times will be unnoticed by you as a partner, nor by the merchant. A profile might be used to distinguish groups of transactions that belong to one certain event. When a bank account is created, this is automatically linked to a merchant's profile.

You can retrieve an individual profile as well as a list of all profiles for a merchant. Be it in a list or as a single result, the data or profile object will contain the following details. Do note that contact, bank_account, files and messages can’t be expanded until further notice.

Profile object Description
uid string Merchant profile unique identifier.
up to 20 characters
object string Value profile
created timestamp Timestamp when object is created.
updated timestamp Timestamp when object is updated.
status string One of: pendinglivesuspendedblocked
name string Name of the (sub)organization or unit of the merchant.
up to 100 characters
sector string Sector the merchants profile is affiliate with.
up to 45 characters
url string up to 150 characters
po_number string Payout reference.
up to 40 characters
contact array Expanded by default,
nullable
settings array Expanded by default,
nullable
bank_account array Bank account that is linked to the profile. Expanded by default,
nullable
payment_methods array See payment_methods object,
can be expanded,
nullable
files array Can not be expanded,
nullable
messages array Can not be expanded,
nullable

Migrating Merchants

Example request - Migrate a merchant to business merchant:

curl https://api-sandbox.onlinebetaalplatform.nl/v1/merchants/{merchant_uid}/migrate \
-u [API-key]: \
-d country=NLD \
-d coc_nr=12345678

Created a consumer merchant, but wanted to create a business merchant? You can migrate the merchant by calling the API with a Chamber of Commerce number.

Advanced Chamber of Commerce numbers

The Chamber of Commerce checks on sandbox mode differ a bit compared to production mode. We allow all kinds of (duplicate) CoC numbers and generate dummy company details for all numbers. This allows for easy testing without the need of (re)entering valid CoC numbers. To test certain flows, you may use the following magic CoC numbers:

First 3 digits Description
999****** Forces a different flow which requires user to fill in a form to complete his business details. This is usually the case for foreign CoC number or when the Dutch CoC number can’t be checked.
888****** Forces the ‘merchant exists’ flow, asking users to connect their new merchant using their existing OBP credentials. Connecting your existing OBP account is not available on Sandbox.

Ultimate Beneficial Owner (UBO)

Example request - Create an UBO:

curl https://api-sandbox.onlinebetaalplatform.nl/v1/merchants/mer_{uid}/ubos \
   -u API-KEY: \
   -d names_first="Tinus" \
   -d name_prefix="van der" \
   -d name_last="Tester" \
   -d date_of_birth="1978-01-04" \
   -d is_decision_maker=true \
   -d is_shareholder=false \
   -d is_pep=false

An UBO needs to be created for every business merchant. This UBO will then be checked by the compliance department. Notifications will be send to the merchant's notify_url.

UBO object Description
uid string Merchant UBO unique identifier.
up to 20 characters
object string Value ubo
created timestamp Timestamp when object is created.
updated timestamp Timestamp when object is updated.
status string One of: pendingverifiedunverified
verified boolean True when the UBO is verified. False if not. Null when initialized.
names_first string First names of the UBO.
up to 45 characters
name_prefix string Prefix of the UBO.
up to 40 characters
name_last string Last name of the UBO.
up to 40 characters
date_of_birth string Date of birth of the UBO.
Must be formatted as yyyy-mm-dd
is_decision_maker boolean Whether the UBO is a decision maker.
is_shareholder boolean Whether the UBO is a shareholder.
is_pep boolean Whether the UBO is a Politically Exposed Persons (PEP).

You can create an UBO object using the following fields:

Create UBO object Description
names_first required The first names of the UBO.
name_prefix Prefix of the UBO.
name_last required Last name of the UBO.
date_of_birth required Date of birth of the UBO.
Must be formatted as yyyy-mm-dd
is_decision_maker Whether the UBO is a decision maker.
is_shareholder Whether the UBO is a shareholder.
is_pep Whether the UBO is a Politically Exposed Persons (PEP).

Compliance

Every merchant contains a compliance object. A compliance object contains details on merchant’s current compliance level, compliance status and lists requirements which the merchant should meet to get a verified compliance status.

The compliance object contains the following attributes:

Compliance object Description
level integer This level determines which requirements merchant should meet.
between 100 and 500
status string Compliance status of the merchant. One of: unverifiedpendingverified
requirements array The Array of the requirements that merchant still needs to fulfil. Contains zero, one or more compliance requirement objects.
Compliance Requirement object
type string The requirement type.
object_uid string Unique identifier of the object the requirement applies to.
object_type string Object type the requirement applies to.
object_url string API resource url of the object the requirement applies to.
object_redirect_url string The merchant is directed to this url, to fulfil the required actions.

Each compliance requirements states the compliance requirement type and details the related object. Merchant should be redirect to object_redirect_url in order to get to the (whitelabel) OPP page where the required actions will be explained. We will send out notifications for each change in compliance requirements and compliance status. We advise you to not save details of each compliance requirement but always to retrieve the latest data via API whenever there is a change.

Compliance requirement types

The compliance requirement types are used to describe the requirement in a simplified way. We currently list the following compliance requirement types:

Compliance Requirement type Description
bank_account.required No bank account available while at least one is required.
bank_account.verification.required No verified bank account available while at least one verified bank account is required.
contact.verification.required No verified merchant contact available.
ubo.verification.required !BUSINESS ONLY! The merchant has to fill / verify all UBO’s.

Compliance status

The compliance status determines whether or not a merchant is able to receive payouts. You may expect the following states:

Compliance Status Description
unverified Merchant is unverified and unable to receive payouts.
Merchant should meet all ‘compliance requirements’ to get to the ‘verified’ state.
pending Merchant compliance status is pending and is unable to receive payouts.
We are currently reviewing merchant’s updated ‘compliance requirements’.
verified Merchant compliance status is verified and is able to receive payouts.

Contact Verification

Contact verification can be done by either using iDIN or by uploading an ID card/Passport/Driver's license. After verification, OPP will manually check whether the merchant is who (s)he claims to be. This is normally done within 24 hours on working days.

iDIN issuers can be retrieved by using the call to the right. Please keep in mind that the iDIN issuers don't change a lot. Therefore, we suggest only retrieving the iDIN issuers once a day, and save them locally.

Bank Accounts

Every merchant needs to have a verified bank account in order to receive pay-outs. You are able to retrieve an individual bank account as well as a list of all bank accounts of one merchant. A bank account object contains the following information.

Bank account object
uid string Bank account unique identifier.
up to 20 characters
object string Value: bank_account
created timestamp Timestamp when object is created.
updated timestamp Timestamp when object is updated.
verified timestamp Timestamp when bank account is verified.
nullable
verification_url string Url for verification of the bank account.
up to 255 characters
status string One of: newpendingapproveddisapproved
account object Contains:
account_iban string International bank account number.
nullable,
up to 34 characters
Bank object Contains:
bic string Bank identifier code.
nullable,
up to 20 characters
reference string up to 45 characters
return_url string The return url the customer is redirected to, once the bank account is verified.
up to 255 characters
notify_url string Notification url to receive status updates.
up to 255 characters
is_default boolean One of: truefalse
Indicates the default bank account for the merchant
note: the first bank account will always be set as default

Creating Bank Accounts

Example request - Create a bank account:

curl https://api-sandbox.onlinebetaalplatform.nl/v1/merchants/{merchant_uid}/bank_accounts \
    -u APIKEY: \
    -d return_url=https://platform.example.com/return \
    -d notify_url=https://platform.example.com/notify

Example response:

{
    “uid”: “bnk_1a2b3c4d5e6f”,
    “object”: “bank_account”,
    “created”: 1554200096,
    “updated”: 1554200096,
    “verified”: null
    “verification_url”: “https://onlinebetaalplatform.nl/nl/
     {partner_name}/merchants/mer_1a2b3c4d5e6f/verificatie/
     bankgegevens/bnk_1a2b3c4d5e6f/7a8d3c308b0739ef96320720017d070533912548”,
    “status”: “new”,
    “account”: {
        “account_iban”: null
    },
    “bank”: {
        “bic”: null
    },
    “reference”: null,
    “return_url”: “https://platform.example.com/return”,
    “notify_url”: “https://platform.example.com/notify”,
    “is_default”: true
}

Create a bank account request using the following attributes. A created bank account has an unique identifier which we will provide in the response.

Create Bank account object Description
return_url required The return url the customer is redirected to, once the bank account is verified.
up to 255 characters
notify_url required Notification url to receive status updates.
up to 255 characters
is_default optional One of: true false
Indicates whether the bank account is merchant's default bank account.
reference optional string
verification_method optional Empty or sepa

verification_method Determines the preselected verification method on OPP’s whitelabel bank account verification page. If this option is set to "sepa", OPP will return the SEPA payment reference in the bank account object. Partner may display these details to merchant to process the SEPA bank transfer. In this case the merchant does not need to be redirected to the verification_url found in the bank account object.

You can retrieve a single bank account object or a list of all bank accounts of a merchant by using one of the following calls to the API respectively.

Verifying Bank Accounts

The bank account object contains a verification_url. You should always redirect the merchant to the verification_url. If the verification_method was set to SEPA, SEPA payment reference details can be found there. If the verification_method is not set to SEPA, you can add extra parameters to the verification_url, so that the merchant will not land on our whitelabel page. E.g.: POST {verification_url}?payment_method=ideal&issuer=INGBNL2A. These payment_methods can be seen below.

Verify Bank account parameters
payment_method required One of: iDEAL - ideal Bancontact - bcmc
issuer optional One of the BIC/SWIFT codes of the iDEAL issuers list
Required if payment_method = "ideal"

Update Bank Account

Whenever the merchant wants to change his/her bank account, a new bank account should be created. Please keep in mind that the merchant has to verify the new bank account as well, and until then, no pay-outs can be done. Always make sure to redirect the merchant to the ‘verification_url’ of the bank account object.

Settlement

Example request - Retrieve a merchant's settlement:

curl https://api-sandbox.onlinebetaalplatform.nl/v1/merchants/{merchant_uid}/settlements/{settlement_uid} \
    -u APIKEY:

Example response:

{
    “uid”: “{settlement_uid}”,
    “object”: “settlement”,
    “created”: 1554069900,
    “updated”: 1554200096,
    “status”: “paid”,
    “paid”: null,
    “period_start”: 1554073200,
    “period_end”: 1554159599,
    “total_number_of_transactions”: 4,
    “number_of_refunds”: 0,
    “total_volume”: 24000,
    “transaction_volume”: 24000,
    “refund_volume”: 0,
    “total_transaction_costs”: 159,
    “transaction_costs”: 159,
    “refund_costs”: 0,
    “total_order_fees”: 0,
    “total_refund_fees”: 0,
    “total_amount”: 23841,
    “amount_paid”: 3500,
    “amount_payable”: 20341,
    “po_number”: null,
    “specifications”: [ {
        “uid”: “{settlement_uid}”,
        “object”: “specification”,
        ...
    } ]
}

Example request - Retrieve all settlements of a merchant:

curl https://api-sandbox.onlinebetaalplatform.nl/v1/merchants/{merchant_uid}/settlements \
    -u APIKEY:

Example response:

{
    object : “list”,
    url: “/v1/merchants/{merchant_uid}/settlements”,
    has_more: false,
    total_item_count: 2,
    items_per_page: 10,
    current_page: 1,
    last_page: 1,
    data: [ {
        “uid”: “{settlement_uid}”,
        “object”: “settlement”,
        “created”: 1554069900,
        “updated”: 1554200096,
        “status”: “paid”,
        “paid”: null,
        “period_start”: 1554073200,
        “period_end”: 1554159599,
        “total_number_of_transactions”: 4,
        “number_of_refunds”: 0,
        “total_volume”: 24000,
        “transaction_volume”: 24000,
        “refund_volume”: 0,
        “total_transaction_costs”: 159,
        “transaction_costs”: 159,
        “refund_costs”: 0,
        “total_order_fees”: 0,
        “total_refund_fees”: 0,
        “total_amount”: 23841,
        “amount_paid”: 3500,
        “amount_payable”: 20341,
        “po_number”: null,
        “specifications”: []
    },
    { ...another settlement... }
    ]
}

The settlement of a merchant is his current "balance". Together with OPP, you as a partner decided on a settlement period (daily, weekly, bi-weekly, monthly, yearly). Once the settlement period ends, OPP will pay-out the merchant.

Each settlement contains a specifications attribute. This attribute is an array, containing all sub-settlements of the current settlement. The sub-settlement object is the same as the settlement object below, except that it also contains a source attribute. For you as a partner, this allows you to see how much of your current settlement has been provided by a specific merchant. This can be done by checking the source.object and source.uid respectively. Each settlement consists of one settlement specification per merchant profile. Each specification consists of one more rows based on the number of transactions, mandates, withdrawals, etc for the merchant in given settlement period.

You can retrieve an individual settlement as well as a list of all settlements for a merchant. Be it in a list or as a single result, the data or settlement object will contain the following details. A settlement has a default period.

Settlement object Description
uid string Settlement unique identifier.
up to 20 characters
object string Value: settlement
created timestamp Timestamp when object is created.
updated timestamp Timestamp when object is updated.
status string One of: currenttransferpaidcancellednext
paid timestamp Timestamp when settlement is paid.
period_start timestamp Timestamp when settlement period is started.
period_end timestamp Timestamp when settlement period is finalized.
total_number_of_transactions integer Total number of transactions within this settlement including refunds, withdrawals, mandates, internal_transfers and multi_transactions
number_of_transactions integer Number of transactions within this settlement.
number_of_refunds integer Number of refunds within this settlement.
number_of_withdrawals integer Number of withdrawals within this settlement.
number_of_mandates integer Number of mandates within this settlement.
number_of_internal_transfers integer Number of internal_transfers within this settlement.
number_of_multi_transactions integer Number of multi_transactions within this settlement.
total_volume integer Resulting transaction volume after deducting refunds.
(total_volume = transaction_volume - refund_volume)
transaction_volume integer Transaction volume.
refund_volume integer Refund volume.
withdrawal_volume integer Withdrawal volume.
mandate_volume integer Mandate volume>
internal_transfer_volume integer Internal transfer volume.
multi_transaction_volume integer Multi transaction volume
total_transaction_costs integer Total transaction costs for transactions and refunds within this settlement.
(total_transaction_costs = transaction_costs + refund_costs)
transaction_costs integer Transaction costs for transactions within this settlement.
refund_costs integer Transaction costs for refunds within this settlement.
withdrawal_costs integer Transaction costs for withdrawal within this settlement.
mandate_costs integer Transaction costs for mandate within this settlement.
internal_transfer_costs integer Transaction costs for internal transfers within this settlement.
multi_transaction_costs integer Transaction costs for multi_transactions within this settlement.
total_order_fees integer Total fees for all orders.
total_refund_fees integer Total fees for all refunds.
total_gateway_fees integer Total gateway fees.
total_amount integer Total amount of the settlement.
(total_amount = total_volume - total_transaction_costs - total_order_fees - total_refund_fees)
amount_paid integer Amount already paid.
amount_payable integer Amount payable.
(amount_payable = total_amount - amount_paid)
payout_type string Payout type of the settlement.
po_number varchar Payout number.
specifications array The specifications of the current settlement.

Refunds

Example request - Create a refund of a transaction.

curl https://api-sandbox.onlinebetaalplatform.nl/v1/transactions/tra_1a2b3c1baeec/refunds \
    -u APIKEY: \
    -d amount=6750 \
    -d "message=As agreed a fully refund" \
    -d "internal_reason=Customer is not satisfied with product"

Example response:

{
    "livemode": true,
    "uid": "ref_1a2b3cfe0b2a",
    "object": "refund",
    "created": 1554113700,
    "updated": 1554113700,
    "paid": null,
    "amount": 6750,
    "status": "created",
    "message": "As agreed a fully refund",
    "internal_reason": "Customer is not satisfied with product"
}                       

A refund will make sure that money that has been put on the settlement of the merchant, can be reverted to a buyer. Refunds can be created as long as the merchant has money on his/her settlement. If the merchant has no more money on his/her settlement, the merchant will be able to perform a top-up, to put money on his/her settlement, after which the refund can be created. A refund is only possible if the funds of the transaction have not yet been entirely refunded. Direct PayPal transactions cannot be refunded from within OPP but have to be refunded from the PayPal environment itself.

One can create a refund using the following call to the API: POST /v1/transactions/{transaction_uid}/refunds, using the following parameters:

Create Refund object Description
amount required Refund amount in cents.
minimum: 1 cent, maximum: the (remaining) refunded amount for the transaction
message optional E-mail message to the original customer.
internal_reason optional Internal reason for refund.

A refund object consists of the following attributes:

Refund object Description
uid string Refund unique identifier.
up to 20 characters
object string Value: refund
created timestamp Timestamp when object is created.
updated timestamp Timestamp when object is updated.
paid timestamp Timestamp when refund is paid.
amount integer Refund amount in cents.
status string One of: createdcompleted
message string Message sent to customer in e-mail.
internal_reason string Internal reason for refund.

Transactions

Transactions need to be created whenever something is bought from a merchant. You can retrieve individual transactions as well as a list of transactions. With our advanced payment flow integration it is possible to create direct- or email transactions. Use checkout to initiate the responsive OPP checkout. A transaction object consists of the following attributes.

Transaction object Description
uid string Transaction unique identifier.
up to 20 characters
object string Value: transaction
created timestamp Timestamp when transaction is created.
updated timestamp Timestamp when transaction is updated.
completed timestamp Timestamp when transaction is completed.
mechant_uid string Merchant to which the transaction belongs.
has_checkoutboolean One of: true false
payment_method string One of: idealpaypalbcmcsepa mandatecreditcard
payment_flow string One of: directemail
payment_details array Displays the details of the payment.
amount integer Transaction amount in cents.
return_url string The customer is directed to this url, once the payment is completed.
up to 255 characters
redirect_url string The customer is directed to this url, for making the payment.
up to 255 characters
notify_url string Notification url to receive status updates.
up to 255 characters
status string Single-field representation of the last updated status value
one of: completedrefundedchargeback
metadata array Metadata that can be added to a transaction.
statuses array Transaction statuses.
order array The order that has been placed.
escrow array The specifications of the escrow period.
fees object The specifications of the fees.
refunds object The refund that belongs to this transaction, if any.

Create a Transaction

Example request - Create a transaction, customer buying 1 product

curl https://api-sandbox.onlinebetaalplatform.nl/v1/transactions \
    -u APIKEY: \
    -d merchant_uid=mer_xxx \
    -d "buyer_name_first=John" \
    -d "buyer_name_last=Tester" \
    -d buyer_emailaddress=john@customer.example.com \
    -d "products[0][name]=WakeUp Light" \
    -d products[0][ean]=5012345000008 \
    -d products[0][price]=11454 \
    -d products[0][quantity]=1 \
    -d shipping_costs=675 \
    -d total_price=11454 \
    -d return_url=https://platform.example.com/return/ \
    -d notify_url=https://platform.example.com/notify/ \
    -d "metadata[external_id]=2015486"

Example response

{
    "livemode": true,
    "uid": "tra_1a2b3c1baeec",
    "object": "transaction",
    "created": 1554113700,
    "updated": 1554200096,
    "completed": null,
    "checkout": true,
    "payment_method": "ideal",
    "payment_flow": "direct",
    "payment_details": [],
    "amount": "12129",
    "return_url": "https://platform.example.com/return/",
    "redirect_url": "https://onlinebetaalplatform.nl/nl/betalen/?trx=tra_1a2b3c1baeec",
    "notify_url": "https://platform.example.com/notify/",
    "status": "created",
    "metadata": [{
        "key": "external_id",
        "value": "2015486"
    }],
    "statuses": [{
        "uid": "sta_1a2b3cfa77e9",
        "object": "status",
        "created": 1554113700,
        "updated": 1554113700,
        "status": "created"
    }],
    "order": {},
    "escrow": {}
}

Create a transaction using the following attributes. An initiated transaction has a unique identifier which we provide in the response.

Create transaction object Description
merchant_uid required Unique identifier of a merchant.
profile_uid optional Unique identifier of a merchants profile.
default is: first merchant profile UID
locale optional Locale used for transaction,
one of: nl en fr
checkout optional Default is: true
one of: true false
payment_method optional Default is: null,
one of: ideal paypal bcmc sepa paypal-pc mandate creditcard
payment_flow optional Default is: direct
one of:
directa direct payment with or without a checkout option
emailan e-mail will be send to the e-mailaddress of the customer with a link to process the payment
issuer optional In case payment_method is ideal, an issuer can be provided to be redirected to the bank immediately.
escrow optional Default is: false
one of:
false
trueone of escrow_period or escrow_date is required
When escrow is true
escrow_period optional Escrow period in days
escrow_date optional Escrow end datetime
format: YYYY-MM-DD HH:MM:SS
skip_confirmation_page optional Default is: false one of:
true false
buyer_name_first optional If payment_flow = emailthe buyer's first name,
up to 45 characters
buyer_name_last optional If payment_flow = emailthe buyer's last name,
up to 45 characters
buyer_emailaddress optional Required when payment_flow = email
customer.country optional
unique optional
date_expired optional
total_price required Total price in cents for all products quantities * prices,
maximum: € 999,999.99
shipping_costs optional Shipping costs in cents,
maximum: € 999,999.99,
default is account setting
discount optional Default is: 0,
discount in cents,
maximum: € 999,999.99
partner_fee optional Partner fee in cents.
payout_description optional Payout description.
up to 125 characters
address optional Address of the buyer.
array with name/value pairs
address_line_1 optional Street name of the buyer.
up to 45 characters
housenumber optional House number of the buyer.
up to 10 characters
housenumber_addition optional Addition to the house number of the buyer.
up to 10 characters
zipcode optional Zip code for the address of the buyer.
between 3 and 9 characters
city optional City of the address of the buyer.
up to 45 characters
country optional Country code of the address of the buyer,
use ISO 3166-1 alpha-3 country code
products required Products to be added to the checkout,
array of one or more products objects
name required Product name,
up to 150 characters
ean optional Product EAN code (European Article Number),
up to 13 characters
code optional Product code,
up to 50 characters
quantity required Number, number of products,
maximum: 65535
price required Number, product price in cents,
maximum: € 999,999.99
vat_rate optional Value added tax rate.
between 0 and 100 (%)
return_url required The return url the customer is redirected to once the payment is completed.
up to 255 characters
notify_url optional Notification url to receive status updates
up to 255 characters
metadata optional Array with name/value pairs to store additional data
key required Unique key within metadata object.
up to 255 characters
value required Corresponding value.
up to 65535 characters

Escrow

Example request - Update escrow of a transaction:

curl https://api-sandbox.onlinebetaalplatform.nl/v1/transactions/{transaction_uid} \
    -u APIKEY: \
    -d "escrow_date=2020-10-01 19:00:00"

OPP provides the option to put money in escrow. By doing this, you can somewhat give a guaranteed feeling to buyer and seller. OPP will put the money in the settlement of the merchant, only when the escrow period ends, or is manually ended by you as a partner. The escrow period can be set by setting escrow = true and either escrow_period = [days] or escrow_date = [date]. Because of technical delays, you will have to set a minimal escrow period of 15 minutes.

If you'd like to update the escrow_period to another date, this is possible by calling the API as can be seen in the right.

Partner fees

OPP charges fees for every transaction that has been done. As a partner, you will be able to provide partner fees towards merchants, to charge these fees towards the merchants, and if wanted, add some fee for you as a partner as well. You can add partner fees by providing the partner_fee attribute in the transaction.

Status simulations

Use the following amounts to trigger transaction statuses on sandbox mode. Do note that if iDEAL is your payment method, you must follow the redirect url and go through the iDEAL simulator.

Amount Status
100 completed
200 cancelled
300 expired
400, 700, 800 pending
500 failed
any other amount completed

SEPA transaction

Example request - SEPA Transaction:

curl https://api-sandbox.onlinebetaalplatform.nl/v1/transactions \
    -u APIKEY: \
    -d merchant_uid=mer_1ab2c3d4e5g6 \
    -d products[0][name]=Product 12345 \
    -d products[0][price]=4000 \
    -d products[0][quantity]=1 \
    -d total_price=40000 \
    -d return_url=https://platform.example.com/return/ \
    -d notify_url=https://platform.example.com/notify/ \
    -d payment_method=sepa \
    -d checkout=false \
    -d payment_flow=direct \
    -d date_expired=2019-05-01 08:15:00

Example response:

Example response:

{
    “uid”: “tra_1ab2c3d4e5g6”,
    “object”: “transaction”,
    “created”: 1554113700,
    “updated”: 1554113700,
    “completed”: null,
    “merchant_uid”: “mer_1ab2c3d4e5g6”,
    “has_checkout”: false,
    “payment_method”: “sepa”,
    “payment_flow”: “direct”,
    “payment_details”: {
        “provider_bank_account_name”: “Stichting Online Betalen”,
        “provider_bank_account_iban”: “NL35INGB0653386540”,
        “provider_bank_account_bic”: “INGBNL2A”,
        “reference”: “P4JRGW”,
        “expired”: 1556705700
    },
    “amount”: 40000,
    “return_url”: “https://platform.example.com/return”,
    “redirect_url”: “https://onlinebetaalplatform.nl/nl/
     {profile_uid}/transactie/start/tra_1ab2c3d4e5g6”,
    “notify_url”: “https://platform.example.com/notify/”,
    “status”: “created”,
    “metadata”: [],
    “statuses”: [ {
        “uid”: “sta_c6893fda4862”,
        “object”: “status”,
        “created”: 1554113700,
        “updated”: 1554113700,
        “status”: “created”
    } ],
    “order”: [],
    “escrow”: null,
    “fees”: {},
    “refunds”: {}
}

To complete a SEPA transaction the payer has to complete a bank transfer with the full amount of the transaction to our third-party funds “Stichting Online Betalen” (Foundation Online Payments). All details required for this transfer can be found in the payment details object within the transaction object. It is very important that the payer uses our unique ‘reference’ and our reference only for the description of the transfer. All payments received which cannot be processed due to reasons such as an incorrect description, amount and/or payments received after the expiration date will be refunded to payer’s bank account.

For international transfers it might be required for payer to provide additional company or/and bank information. In these cases the payer can use the following:

Company information Bank information
MediaMedics B.V. ING Bank N.V.
Foreign Operations
Kanaalweg 1 PO Box 1800
2628 EB Delft 1000 BV Amsterdam
The Netherlands The Netherlands

Expiry date

Every single transaction has an expiry date. For SEPA transactions this defaults to 7 days. You can however change this date by POSTing the date_expired parameter while creating a transaction using our API. We always add 5 days to the expiry date to register a SEPA transfer before the transaction will be expired. It may takes several (working) days to register a transfer on our bank account. During this period the payer will see a ‘pending’ screen when he visits the redirect_url.

Example: If you want to receive the funds latest by August 25, you will have to set the date_expired parameter to August 20. We will expire the transaction if we have not received the funds on August 25 or earlier.

Payment details object
provider_bank_account_name Account holder name of our bank account
provider_bank_account_iban IBAN of our bank account
provider_bank_account_bic BIC of our bank account
reference Unique reference which must be used as description in the bank transfer
expired The transaction must be transferred before this date

Payment Methods

Example request - Retrieve the payment methods of a merchant.

curl https://api-sandbox.onlinebetaalplatform.nl/v1/merchants/{merchant_uid}/payment_methods \
    -u APIKEY:

Example response:

{
    “object”: “list”,
    “url”: “/v1/merchants/{merchant_uid}/payment_methods”,
    “has_more”: false,
    “total_item_count”: 4,
    “items_per_page”: 10,
    “current_page”: 1,
    “last_page”: 1,
    “data”: [ {
        “uid”: “mpm_{uid}”,
        “object”: “payment_method”,
        “name”: “paypal”,
        “status”: “active”
    },
    { ...another payment_method... }
    ],
}

Currently OPP provides the following payment methods:

You can retrieve the payment methods provided to a merchant by providing the API call to the right.

Payment method object Description
uid string Payment_method unique identifier
up to 20 characters
object string value: payment_method
name string one of: idealbcmcsepapaypalpaypal-pccreditcardmandate
status string one of: activeinactive

Refund

Example request - Create a refund

curl https://api-sandbox.onlinebetaalplatform.nl/v1/transactions/{transaction_uid}/refunds \
    -u APIKEY: \
    -d amount=6750 \
    -d "message=As agreed a fully refund" \
    -d "internal_reason=Customer is not satisfied with product"

Example response:

{
    "livemode": true,
    "uid": "ref_1a2b3cfe0b2a",
    "object": "refund",
    "created": 1554113700,
    "updated": 1554113700,
    "paid": null,
    "amount": 6750,
    "status": "created",
    "message": "As agreed a fully refund",
    "internal_reason": "Customer is not satisfied with product"
}

A refund will revert (part of) the money of a transaction, that is on the settlement of the receiving merchant. A refund is only possible if the funds of the transaction have not yet been entirely refunded and enough funds are available on the settlement of the merchant. Direct PayPal transactions cannot be refunded from within OBP but have to be refunded from the PayPal environment itself.

In case a transaction is still in escrow, only a full refund can be initiated. The transaction will then get status chargeback

To create a refund, provide an API call with the amount, and optionally a message and internal reason: POST /v1/transactions/{transaction_uid}/refunds

You can retrieve all refunds of a transaction by calling the API: GET /v1/transactions/{transaction_uid}/refunds

Refund object Description
uid string Refund unique identifier.
up to 20 characters
object string Value: refund
created timestamp Timestamp when object is created.
updated timestamp Timestamp when object is updated.
paid timestamp Timestamp when refund is paid.
amount integer Refund amount in cents.
status string One of: createdcompleted
message string Message sent to customer in e-mail.
internal_reason string Internal reason for refund.

Multi-Transaction

Example request - Create a multi-transaction

curl https://api-sandbox.onlinebetaalplatform.nl/v1/multi_transactions \
    -u APIKEY: \
    -d checkout=false \
    -d payment_method=ideal \
    -d total_price=2695 \
    -d return_url=https://platform.example.com/return/ \
    -d notify_url=https://platform.example.com/notify/ \
    -d "metadata[external_id]=2015486" \
    -d transactions[0][merchant_uid]=mer_715e19a404b9 \
    -d transactions[0][total_price]=2000 \
    -d transactions[0][shipping_costs]=0 \
    -d transactions[0][partner_fee]=0 \
    -d "transactions[0][products][0][name]=Product A" \
    -d transactions[0][products][0][ean]=5012345000008 \
    -d transactions[0][products][0][price]=1500 \
    -d transactions[0][products][0][quantity]=1 \
    -d "transactions[0][products][1][name]=Product B" \
    -d transactions[0][products][1][ean]=4000001000005 \
    -d transactions[0][products][1][price]=500 \
    -d transactions[0][products][1][quantity]=1 \
    -d transactions[1][merchant_uid]=mer_24fa4b68793c \
    -d transactions[1][total_price]=695 \
    -d transactions[1][shipping_costs]=0 \
    -d transactions[1][partner_fee]=0 \
    -d "transactions[1][products][0][name]=Verzending" \
    -d transactions[1][products][0][ean]=5400000000003 \
    -d transactions[1][products][0][price]=695 \
    -d transactions[1][products][0][quantity]=1

Example response:

{
    “livemode”: true,
    “uid”: “mtr_1a2b3c7c1b4e”,
    “object”: “multi_transaction”,
    “created”: 1554200096,
    “updated”: 1554200097,
    “completed”: null,
    “checkout”: false,
    “payment_method”: “ideal”,
    “payment_flow”: “direct”,
    “payment_details”: [],
    “amount”: 2695,
    “return_url”: “https://platform.example.com/return/”,
    “redirect_url”: “https://onlinebetaalplatform.nl/en/
     {slug}/multi-transaction/start/{uid}”,
    “notify_url”: “https://platform.example.com/notify/”,
    “status”: “created”,
    “metadata”: [ {
        “key”: “external_id”,
        “value”: “2015486”
    } ],
    “statuses”: [ {
        “uid”: “sta_1a2b3cc819a8”,
        “object”: “status”,
        “created”: 1554200096,
        “updated”: 1554200097,
        “status”: “created”
    } ],
    “transactions”: [ {
        “uid”: “tra_44808f766343”,
        “object”: “transaction”,
        “created”: 1554200096,
        “updated”: 1554200097,
        “completed”: null,
        “merchant_uid”: “mer_715e19a404b9”,
        “merchant_profile_uid”: “prf_f54be44a262a”,
        “total_price”: 2000,
        “shipping_cost”: 0,
        “partner_fee”: 0,
        “payment_details”: [],
        “return_url”: “https://platform.example.com/return/”,
        “redirect_url”: “https://onlinebetaalplatform.nl/en/
         {slug}/multi-transaction/start/{uid}”,
        “notify_url”: “https://platform.example.com/notify/”,
        “status”: “created”,
        “metadata”: [],
        “statuses”: [ {
            “uid”: “sta_1a2b3cc819a8”,
            “object”: “status”,
            “created”: 1554200096,
            “updated”: 1554200097,
            “status”: “created”
        } ],
        “order”: {},
        “escrow”: {}
    },
    {
        “uid”: “tra_c4560476b28e”,
        “object”: “transaction”,
        “created”: 1554200096,
        “updated”: 1554200097,
        “completed”: null,
        “merchant_uid”: “mer_24fa4b68793c”,
        “merchant_profile_uid”: “prf_7aca19e8caea”,
        “total_price”: 695,
        “shipping_cost”: 0,
        “partner_fee”: 0,
        “payment_details”: [],
        “return_url”: “https://platform.example.com/return/”,
        “redirect_url”: “https://onlinebetaalplatform.nl/en/
         {slug}/multi-transaction/start/{uid}”,
        “notify_url”: “https://platform.example.com/notify/”,
        “status”: “created”,
        “metadata”: [],
        “statuses”: [ {
            “uid”: “sta_1a2b3cc819a8”,
            “object”: “status”,
            “created”: 1554200096,
            “updated”: 1554200097,
            “status”: “created”
        } ],
        “order”: {},
        “escrow”: {}
    } ]
}

Multi transactions allow you to handle multiple transactions, for different merchants or different cases, in one API call. You can always retrieve a multi-transaction or a list of multi-transactions by calling the API:

If you'd like to retrieve a single transaction within a multi-transaction, you can call the API:

A refund ca be done by calling the API with attribute amount and a message: POST /v1/transactions/{merchant_transaction_uid}/refunds

A multi-transaction object contains the following variables:

Multi-transaction object Description
uid string Multi_transaction unique identifier.
up to 20 characters
object integer Value: multi_transaction
created timestamp Timestamp when object is created.
updated timestamp Timestamp when object is updated.
completed timestamp Timestamp when object is completed.
checkout boolean Fixed value: false
We do not support checkout for multi-transactions.
payment_method string One of: idealbcmcsepapaypalpaypal-pccreditcard
payment_flow string Value: direct
payment_details array [for review: array with banking details: account name, masked IBAN and BIC]
amount integer Amount in cents,
sum of all transactions within the multi_transaction.
return_url string The return url the customer is redirected to, once the payment is completed.
up to 255 characters
redirect_url string Url to redirect the customer to, for making the payment.
up to 255 characters
notify_url string Notification url to receive status updates.
up to 255 characters
status string Status of the multi-transaction
One of created pending completed expired cancelled
metadata array The metadata given to the multi-transaction
statuses array see statuses object
transactions array Array with transaction objects

Creating a multi-transaction

Example request - Refund a transaction from a multi-transaction:

curl https://api-sandbox.onlinebetaalplatform.nl/v1/multi_transactions/{multi_transaction_uid}/transactions/{transaction_uid}/refunds \
    -u APIKEY: \
    -d amount=695 \
    -d "message=Refund verzendkosten"

Example response:

{
    “livemode”: true,
    “uid”: “ref_1a2b3c01ca44”,
    “object”: “refund”,
    “created”: 1554113700,
    “updated”: 1554113700,
    “paid”: null,
    “amount”: 695,
    “status”: “created”,
    “message”: “Refund verzendkosten”,
    “internal_reason”: null
}
Create multi transaction object
payment_method required One of: ideal paypal bcmc sepa creditcard
Total_price required Total price in cents for all transactions.
shipping_costs optional Shipping costs in cents for all transactions.
partner_fee optional Partner fee in cents for all transactions.
date_expired optional Date between NOW + 15 minutes and NOW + 1 year
description optional Description of the multi-transaction
transactions required Array of one or more transaction objects
maximum: 25 objects
return_url required The customer is directed to this url, once the payment is completed.
up to 255 characters
notify_url required Notification url to receive status updates.
up to 255 characters
metadata optional A set of key-value pairs that you can attach to the transaction object to store additional data.
default is: null
key required Unique key within metadata object,
up to 255 characters
value required Corresponding value,
up to 65535 characters

Mandates & Direct Debt

Mandates can be used to let a merchant fulfil a direct debt on your bank account. This can either be recurring or once. You can retrieve an individual mandate as well as a list of all mandates. Use GET /v1/mandates/{mandate_uid} or GET /v1/mandates to retrieve mandates.

If you would like to revoke a mandate, use the following call: DELETE /v1/mandates/{mandate_uid}.

Transactions belonging to one mandate can be retrieved using the following API call: GET v1/mandates/{man_uid}/transactions

Be it in a list or as a single result, the data or mandate object will contain the following details.

Mandate object Description
uid string Mandate unique identifier.
up to 20 characters
object string Value: mandate
token string When mandate is completed, this will contain the mandate token.
nullable
created timestamp Timestamp when object is created.
updated timestamp Timestamp when object is updated.
start timestamp Timestamp start of period when mandate is valid.
nullable
end timestamp Timestamp end of period when mandate is valid.
nullable
completed timestamp Timestamp when mandate is authorized.
nullable
expired timestamp Timestamp when mandate is expired.
nullable
revoked timestamp Timestamp when mandate is revoked.
nullable
amount integer The amount which is paid to complete the mandate.
repeats integer Number of times a mandate repeats (mandate_repeat = "subscription").
interval integer Interval in days a mandate repeats (mandate_repeat = "subscription").
description Description for the mandate.
return_url string The customer is directed to this url, once the mandate is completed.
up to 255 characters
redirect_url string The customer is directed to this url, to complete the mandate flow.
up to 255 characters
notify_url string Webhook to call when mandate status changes.
up to 255 characters
has_checkout boolean Whether or not the mandate flow contained the checkout.
mandate_flow string Value: direct
mandate_repeat string One of: oncesubscriptioncontinued
mandate_type string One of: consumerbusiness
mandate_method string One of: paymentformimport
status string One of: createdpendingexpiredcancelledfailedcompletedrevoked
customer object Customer object, contains customer data.
order object Order object, contains order data and products.
metadata array Array with name/value pairs to store additional data.
nullable
statuses array All statuses for this mandate (mandate_status).

Create a Mandate

Example request - Create a mandate:

curl https://api-sandbox.onlinebetaalplatform.nl/v1/mandates \
    -u APIKEY: \
    -d checkout=false \
    -d mandate_method=payment \
    -d mandate_type=consumer \
    -d mandate_repeat=subscription \
    -d mandate_amount=100 \
    -d "products[0][name]=Test product" \
    -d products[0][price]=2525 \
    -d products[0][quantity]=1 \
    -d total_price=2525 \
    -d return_url=”https://platform.example.com/return/” \
    -d notify_url=”https://platform.example.com/notify/” \
    -d metadata[external_id]=2015486

Example response:

{
    “uid”: “man_bec5b2f1701d”,
    “object”: “mandate”,
    “token”: null,
    “created”: 1554199810,
    “updated”: 1554199810,
    “start”: null,
    “end”: null,
    “completed”: null,
    “expired”: null,
    “revoked”: null,
    “amount”: 100,
    “repeats”: 12,
    “interval”: 30,
    “description”: null,
    “return_url”: “http://platform.example.com/return”,
    “redirect_url”: “https://sandbox.onlinebetaalplatform.nl/nl/<MERCHANT>/
     machtiging/formulier/gegevens/man_bec5b2f1701d”,
    “notify_url”: “http://platform.example.com/notify”,
    “has_checkout”: true,
    “mandate_flow”: “direct”,
    “mandate_repeat”: “subscription”,
    “mandate_type”: “consumer”,
    “mandate_method”: “payment”,
    “status”: “created”,
    “customer”: {},
    “order”: {},
    “metadata”: [],
    “statuses”: []
}

You should redirect customer to the redirect url. You shall receive status updates when the mandate status changes on the notify_url. When receiving the completed status you should get the token with the API. Store token AND mandate_uid in your system, you need both for creating mandate transactions. Mandate should contain the following fields.

Create Mandate object
merchant_uid required The merchant UID.
merchant_profile_uid optional The merchant profile UID.
locale optional one of:
nl dutch
en english
fr french
de german
checkout required Whether or not to use the whitelabel checkout flow designed by OPP.
skip_confirmation optional Skip the confirmation page after successful mandate creation,
one of: true false
mandate_method required one of:
form authorization by form
payment authorization by iDEAL payment
emandate authorization by bank
import batch import
see mandate methods
mandate_flow required one of: direct email
mandate_type required one of: business consumer
mandate_repeat required one of:
once
subscription
continued
mandate_amount required Amount used for mandate verification transaction in cents.
only required when mandate_method = "payment"
minimum: 10 cents
payment_method optional one of: ideal bcmc creditcard
only required if checkout = false or checkout = true and mandate_method = "payment"
ideal_issuer required The iDEAL issuer of the bank. Use valid BIC here.
only required if mandate_method = "ideal"
issuer required The issuer of the bank. Use valid BIC here.
only required if mandate_method = "emandate"
repeats optional Number of times a mandate repeats.
for instance: 12 (times) !NOTE! This is only for visualisation purposes.
interval optional Interval in days a mandate repeats.
for instance: 30 (days) !NOTE! This is only for visualisation purposes.
total_price required The (total) price of the first payment, in cents. This includes the mandate_amount.
minimum: € 1.00, maximum: € 250.00
shipping_costs required Shipping costs in cents.
can be: 0
maximum: € 999,999.99
customer optional Array of customer[name]=value attributes.
required if mandate_method = "payment" or "import"
emailaddress optional E-mail address of the customer.
up to 100 characters
required if mandate_method = "payment"
phonenumber optional Phone number of the customer.
up to 20 characters
required if mandate_method = "payment"
gender optional Gender, one of:
mmale ffemale xunknown
name_first optional First name of the customer.
up to 45 characters
required if mandate_method = "payment" or "import"
name_prefix optional Prefix in front of last name of the customer.
up to 45 characters
name_last optional Last name of the customer.
up to 45 characters
required if mandate_method = "payment" or "import"
street optional Street name for the address of the customer.
up to 100 characters
housenumber optional House number for the address of the customer.
numeric
housenumber_addition optional Addition to the house number of the customer.
up to 10 characters
zipcode optional Zip code for the address of the customer.
up to 10 characters
city optional City of the address of the customer.
up to 100 characters
state optional State of the address of the customer.
up to 45 characters
country optional Country code of the customer.
use ISO 3166-1 alpha-3 country code
company_name optional Name of the company.
up to 100 characters
bank_iban optional required if mandate_method = "import",
only available when creating a new mandate.
bank_bic optional required if mandate_method = "import",
only available when creating a new mandate.
bank_name optional required if mandate_method = "import",
only available when creating a new mandate.
products optional Array of one or more products objects.
required when mandate_method = "payment" or "form"
name required Product name.
up to 150 characters
ean optional Product EAN code (European Article Number).
up to 13 characters
code optional Product code.
up to 50 characters
price required Product price in cents.
e.g. 10000 cents for a € 100.00 product
maximum: € 999,999.99
quantity required Number of products.
maximum: 65535
return_url required The return url the customer is redirected to, once the mandate is created.
notify_url required Notification url to receive status updates.
metadata optional Array with name/value pairs to store additional data.
nullable
key required Unique key within metadata object.
up to 255 characters
value required Corresponding value.
up to 65535 characters

Mandate methods

Mandate methods
form Customer enters his IBAN and name on account and signs the mandate form to authorize Stichting Online Betalen to send collection instructions to his bank to debit his account and to authorize his bank to debit his account once or on a recurrent basis in accordance with the instructions from Stichting Online Betalen
payment Customer completes an iDEAL payment and signs the mandate form to authorize Stichting Online Betalen to send collection instructions to his bank to debit his account and to authorize his bank to debit his account once or on a recurrent basis in accord- ance with the instructions from Stichting Online Betalen
import Import allows you to create a mandate by specifying customer IBAN, BIC and Account holder name. When mandate_method is import these fields are required in the consumer object. See consumer object.
emandate Customer authorises Stichting Online Betalen to send collection instructions via their bank’s online banking application.

Create a Mandate Transaction

Example request - Create a mandate transaction:

curl https://api.onlinebetaalplatform.dev/v1/mandates/man_bec5b2f1701d/transactions \
    -u APIKEY: \
    -d "reference=20150501B1010" \
    -d token=E5D1429F912588CA7C822AF1D89DC1655EC1EED7 \
    -d total_price=2525 \
    -d return_url=https://platform.example.com/return/ \
    -d notify_url=https://platform.example.com/notify/ \
    -d "metadata[external_id]=2015486"

Create a mandate transaction using the token. Returns a regular merchant_transaction object. Mandate transactions should contain the following fields. You need to provide a unique reference for each mandate transaction to prevent accidental duplicate transactions.

Create Mandate transaction object
reference required Unique reference for each mandate transaction to prevent accidental duplicate transactions.
token required Mandate token.
shipping_costs required Shipping costs in cents.
can be 0
maximum: € 999,999.99
total_price required Total price in cents for all products (quantities * prices).
partner_fee optional Partner fee in cents.
payout_description optional Description the merchant sees on his bank account.
string, up to 125 characters
products optional Array of products objects.
required when mandate_method = "payment" or "form"
if not specified, products from mandate request will be used
name required Product name.
up to 150 characters
ean optional Product EAN code (European Article Number).
up to 13 characters
code optional Product code.
up to 50 characters
price required Number, product price in cents.
e.g. 10000 cents for a € 100.00 product
maximum: € 999,999.99
quantity required Number, number of products.
maximum: 65535
notify_url optional Defaults to the mandate notify_url.
metadata optional Array with name/value pairs to store additional data.
nullable
key required Unique key within metadata object.
up to 255 characters
value required Corresponding value.
up to 65535 characters

Status simulation

Amount Status
100, 200 pending
400 cancelled
500 reserved
600 completed
700 failed
800 refunded
900 chargeback
any other amount completed

Mandate Multi Transactions

Example Request - Create a mandate multi transaction:

curl https://api-sandbox.onlinebetaalplatform.nl/v1/mandates/{mandate_uid}/multi_transactions \
    -u APIKEY: \
    -d "reference=ABC123456789" \
    -d "token={token}" \
    -d total_price=2695 \
    -d return_url=https://platform.example.com/return/ \
    -d notify_url=https://platform.example.com/notify/ \
    -d "metadata[external_id]=2015486" \
    -d transactions[0][merchant_uid]={merchant_1_uid} \
    -d transactions[0][total_price]=2000 \
    -d transactions[0][partner_fee]=0 \
    -d "transactions[0][products][0][name]=Product A" \
    -d transactions[0][products][0][price]=1500 \
    -d transactions[0][products][0][quantity]=1 \
    -d "transactions[0][products][1][name]=Product B" \
    -d transactions[0][products][1][price]=500 \
    -d transactions[0][products][1][quantity]=1 \
    -d transactions[1][merchant_uid]={merchant_2_uid} \
    -d transactions[1][total_price]=695 \
    -d transactions[1][partner_fee]=0 \
    -d "transactions[1][products][0][name]=Product C" \
    -d transactions[1][products][0][price]=695 \
    -d transactions[1][products][0][quantity]=1

Example response:

{
    “livemode”: true,
    “object”: “list”,
    “url”: “/v1/multi_transactions”,
    “has_more”: false,
    “total_item_count”: 1,
    “items_per_page”: 10,
    “current_page”: 1,
    “last_page”: 1,
    “data”: [ {
        “uid”: “{uid}”,
        “object”: “multi_transaction”,
        “created”: 1554200096,
        “updated”: 1554200097,
        “completed”: null,
        “checkout”: false,
        “payment_method”: “mandate”,
        “payment_flow”: “direct”,
        “payment_details”: [],
        “amount”: 2695,
        “return_url”: “https://platform.example.com/return/”,
        “redirect_url”: null,
        “notify_url”: “https://platform.example.com/notify/”,
        “status”: “created”,
        “metadata”: [ {
            “key”: “external_id”,
            “value”: “2015486”
        } ],
        “statuses”: [ {
            “uid”: “{uid}”,
            “object”: “status”,
            “created”: 1554200096,
            “updated”: 1554200097,
            “status”: “created”
        } ],
        “transactions”: [ {
            “uid”: “{uid}”,
            “created”: 1554200096,
            “updated”: 1554200097,
            “completed”: null,
            “object”: “transaction”,
            “merchant_uid”: “{merchant_uid_1}”,
            “merchant_profile_uid”: “{merchant_profile_uid}”,
            “total_price”: 2000,
            “shipping_cost”: 0,
            “partner_fee”: 0,
            “payment_details”: [],
            “return_url”: “https://platform.example.com/return/”,
            “redirect_url”: null,
            “notify_url”: “https://platform.example.com/notify/”,
            “status”: “created”,
            “metadata”: [],
            “statuses”: [ {
                “uid”: “sta_1a2b3cc819a8”,
                “object”: “status”,
                “created”: 1554200096,
                “updated”: 1554200097,
                “status”: “created”
            } ],
            “order”: {},
            “escrow”: {}
        },
        {
            “uid”: “{uid}”,
            “created”: 1554200096,
            “updated”: 1554200097,
            “completed”: null,
            “object”: “transaction”,
            “merchant_uid”: “{merchant_uid_2}”,
            “merchant_profile_uid”: “{merchant_profie_uid}”,
            “total_price”: 695,
            “shipping_cost”: 0,
            “partner_fee”: 0,
            “payment_details”: [],
            “return_url”: “https://platform.example.com/return/”,
            “redirect_url”: null,
            “notify_url”: “https://platform.example.com/notify/”,
            “status”: “created”,
            “metadata”: [],
            “statuses”: [ {
                “uid”: “sta_1a2b3cc819a8”,
                “object”: “status”,
                “created”: 1554200096,
                “updated”: 1554200097,
                “status”: “created”
            } ],
            “order”: {},
            “escrow”: {}
        } ]
    } ]
}

The multi transaction allows you to handle multiple merchant transactions, for different merchants, in one API call. As a partner you may create one SDD multi transaction with one or more sub transactions. For each sub transaction you may specify the transaction amount and which merchant should receive the funds once the SDD transaction is completed. A mandate multi transaction object contains the same attributes as the normal multi transaction. Additional attribute information can be found below.

Multi transaction attributes
reference required Unique reference for each mandate transaction to prevent accidental duplicate transactions
token required Mandate token

To retrieve a list of all multi transactions from a mandate, perform a GET request to /v1/mandates/{mandate_uid}/multi_transactions To retrieve a single multi transaction from a mandate, perform a GET request to /v1/mandates/{mandate_uid}/multi_transactions/{multi_transaction_uid}

Issuers

OPP has several features that imply a connection with Dutch bank providers (also called issuers). For each of these features, it is necessary to obtain a list which banks support this feature. These lists barely change. To make sure that our APIs are not called unnecessarily for every time you use one of these features, we ask you to only retrieve the issuers once a day, and save them in a cache memory.

iDEAL issuers

Example request - Retrieve iDEAL issuers:

curl https://api-sandbox.onlinebetaalplatform.nl/v1/ideal_issuers \
    -u APIKEY:

Example response:

{
    “object”: “list”,
    “url”: “/v1/ideal_issuers”,
    “has_more”: false,
    “total_item_count”: 2,
    “items_per_page”: 10,
    “current_page”: 1,
    “last_page”: 1,
    “data”: [ {
        “object”: “ideal_issuer”,
        “bic”: “RABONL2U”,
        “name”: “Issuer Simulation V3 - RABO”
    },
    {
        “object”: “ideal_issuer”,
        “bic”: “INGBNL2A”,
        “name”: “Issuer Simulation V3 - ING”
    } ]
}

iDEAL issuers can be used for transactions that require iDEAL. When providing an issuer, the user of the platform will not be redirected to whitelabel pages of OPP, but will be redirected to his/her bank immediately.

iDEAL issuers can be used for the following functionality:

iDIN issuers

Example request - Retrieve iDIN issuers:

curl https://api-sandbox.onlinebetaalplatform.nl/v1/idin_issuers \
    -u APIKEY:

Example response:

{
    "object": "list",
    "url": "/v1/idin_issuers",
    "has_more": false,
    "total_item_count": 2,
    "items_per_page": 10,
    "current_page": 1,
    "last_page": 1,
    "data": [ {
        "object": "idin_issuer",
        "bic": "INGBNL2A",
        "name": "ING Bank"
    },
    {
        "object": "idin_issuer",
        "bic": "RABONL2U",
        "name": "Rabobank"
    } ]
}

iDIN issuers can be used for contact verification. When providing an issuer, the user of the platform will not be redirected to whitelabel pages of OPP, but will be redirected to his/her bank immediately.

iDIN issuers can be used for the following functionality:

e-mandate issuers

Example request - Retrieve iDEAL issuers:

curl https://api-sandbox.onlinebetaalplatform.nl/v1/mandates/mandate_issuers \
    -u APIKEY:

Example response:

{
    “object”: “list”,
    “url”: “/v1/mandates/mandate_issuers”,
    “has_more”: false,
    “total_item_count”: 2,
    “items_per_page”: 10,
    “current_page”: 1,
    “last_page”: 1,
    “data”: [ {
        “object”: “mandate_issuer”,
        “bic”: “RABONL2U”,
        “name”: "Core issuer simulation - RABO"
    },
    {
        “object”: “mandate_issuer”,
        “bic”: “INGBNL2A”,
        “name”: "Core issuer simulation - ING"
    } ]
}

eMandate issuers can be used for mandate verification. When providing an issuer, the user of the platform will not be redirected to whitelabel pages of OPP, but will be redirected to his/her bank immediately.

eMandate issuers can be used for the following functionality:

Mandate issuers can be filtered on mandate_type. This can either be business or consumer. Use a filter as: v1/mandates/mandate_issuers?filter[mandate_type]=consumer