Questions

Please let us know if you have any questions regarding the guides, references or implementation. We’re here to help!

• E-mail implementation support
• Schedule an implementation call
• Request a development Slack channel

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 payment setup and financial flows compliant to laws (PSD2) and local schemes. 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. Within every chapter, we will provide an example request and response if possible.

Terminology

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

Environments

OPP knows two environments. A sandbox environment, in which you will be able to test all sorts of scenarios, 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. 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 environment

The OPP Sandbox is a virtual testing environment that mimics the live OPP 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 in production. No actual payments are made or processed. Where needed a simulation mode will be provided to test various scenarios.

Please bear in mind, as the sandbox environment is a direct copy of our production environment, it will not be possible to delete data or clear the sandbox and start fresh.

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

• 18.193.11.50
• 18.159.20.179

Postman collection

To make testing single requests in sandbox and production easier, we have created a fully functional Postman collection, free for you to use. In order to use the collections below, you should create an environment containing the following variables:

• {{api_key}} - Your API key
• {{url}} - The base url of our API
• {{notify_url}} - The webhook of your platform
• {{return_url}} - If preferred, the return_url of the merchant/transaction
• {{merchant_uid}} - If preferred, your test merchant for transactions
• {{token}} - In case of mandates, your test mandate token

You can download the collections according to your needs:

• Merchants API
• Transactions API
• Mandates API
• Charges API
• Withdrawals API
• Disputes API

Go-Live

OPP will perform quality control on the implementation of the features in your platform. All necessary notifications should be handled correctly, and furthermore, the following functionality will be checked. For all below functionality, please have a look at the Guides.

KYC / Merchant onboarding requirements

• The email address is verified by the platform before creating an OPP account
• The merchant needs to agree with the terms and conditions of OPP
• KYC Low: Connecting merchant bank account enabled
• KYC Low: Merchant phone number provided
• KYC High: Merchant identity check enabled
• KYC Business: UBO, Chamber of Commerce extract and Organization structure check enabled

Merchant account / profile requirements

• Merchant is able to see current merchant.status and merchant.compliance.status
• Merchant is able to see outstanding compliance requirements

Besides the above required functionality, we highly recommend to also implement the following, in order to reduce questions and support load:

• Merchant account / profile - Merchant is able to see the connected bank account for payouts
• Merchant account / profile - Merchant is able to change the connected bank account

Partner backoffice requirements

• Partner backoffice is able to see the merchant's current merchant.status and merchant.compliance.status
• Partner backoffice is able to see the merchant's outstanding compliance requirements

Transactions requirements

• Complete checkout flow, including unhappy flows
• Platform prevents users from paying multiple times for the same order
• The buyer agrees with the Terms and Conditions of OPP before the transaction is completed

Mandates requirements (if applicable)

• Complete mandate checkout flow, including unhappy flows
• Platform prevents users from paying multiple times for the same order
• Platform implemented fall-back system in case of chargebacks

Production key

Your production key will be provided to you once the following actions have taken place or files have been delivered:

• Sales: Signed partner contract with OPP
• Compliance: Delivered signed Partner Onboarding form
• Compliance: Completed RISK assessment
• Integrations: Delivered signed implementation checklists:
  
  • Merchants API
  • Transactions API
  • Mandates API (if applicable)
• Integrations: Demo of the required OPP functionality

Production environment

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

• 18.197.215.227
• 3.120.97.52
• 3.121.39.192

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 the basic functionalities 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 has occurred.

API Authentication

Example header of a request

headers: {
    "Authorization": "Bearer {{api_key}}",
  }

-H "Authorization: Bearer {{api_key}}"

In order to communicate with our API, authentication is required. You received an API key from your Implementation Manager. This API key differs for both the environments, therefore it is advised to keep them separate from one another.

Every request you send to our API needs to have a header with Bearer Token Authentication: Authorization : Bearer {{api_key}}. In case your API request does not have a correct API key in its header, you will see the error at the right.

API Restrictions

Example response error

{
    "error": {
        "type": "not_found",
        "message": "Unrecognized URL requested or no permissions to view request URL. See https://docs.onlinepaymentplatform.com for valid endpoints or contact support if you have any questions.",
        "parameter": null
    }
}

Every platform has its own way of working, with its own set of features to be activated. Every part of our API can be individually (in)activated upon request. Whenever you feel like you are missing a set of features, or would like to expand your current set of features to improve your platform, please contact your Implementation Manager.

Once you try to call on an API endpoint, which is not activated, you will get the same response as when you did not provide a valid API key. In this case, first check whether your request header actually contains the API key. Afterwards, check with your Implementation Manager whether the feature has been activated for your account.

API Status

Example request - Status check

GET https://api-sandbox.onlinebetaalplatform.nl/status

curl https://api-sandbox.onlinebetaalplatform.nl/status \
    -H "Authorization: Bearer {{api_key}}"

Example response

{
    "status": "online",
    "date": 1611321273
}

In order for partners to check whether our APIs are still up and running, we provided an endpoint to reach out to. Please find the example request and response on the right.

Idempotency

Example header of a request

headers: {
    "Authorization": "Bearer {{api_key}}",
    "Content-Type": "application/json",
    "Idempotency-Key": "{{key}}"
  }

The API supports idempotency, a mechanism to allow safely retrying requests without performing the same operation twice, for all POST requests. To perform an idempotent request, you must provide an additional header to the request: Idempotency-Key: {key}

Please be aware of the following:

• This mechanism will ensure that you get the same response as the first time you have sent the request
• The response for an idempotency key is stored only if the request is valid and returned a valid (OK) response
• Idempotency keys and their response may be removed from the system after 60 minutes
• The idempotency key must be a unique value though your application must understand how the key is generated to ensure subsequent retries of the same request send the same key

The best practice to use this solution is to use your own unique ID of an object, which will not refresh every time a request is sent to our APIs. Also, make sure the rest of your application knows how to deal with this situation. For example when providing a refund, you would normally receive an error when a refund is provided twice, because of insufficient funds. Using the idempotency solution, you will not get an error, but the same response twice.

In cases where multiple requests with the same idempotency key arrive simultaneously, you might receive a HTTP status 409 - Conflict, as is described in the security section.

Pagination

Example request - Retrieve page 2 of the transactions list:

curl https://api-sandbox.onlinebetaalplatform.nl/v1/transactions?page=2&perpage=10 \
    -H "Authorization: Bearer {{api_key}}"

GET "https://api-sandbox.onlinebetaalplatform.nl/v1/transactions?page=2&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 sorting through many results. The pages can be switched by adding the following parameters to the GET call:

Basic pagination usage:
?page=2&perpage=10

The response sent can be seen below.

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}}",
    "verification_hash": "5678ikmnaw9pe89fkanwbpf9kw"
}

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.

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.

Notification Types

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

Validating Notifications (Signed Notifications)

The notification requests will be signed using the Signature scheme from the http-signatures document published by the Internet Engineering Task Force (IETF). This document is in draft but is used widely and provides our partners a solid method to ensure messages received from us are not tampered with.

Each request to a webhook endpoint will have a header containing a signing signature. This signature is composed by defined parts of the request. Tampering with the request will result in the invalidity of the signature. A secret key (pair) will be used to create and verify the signature assuring only OPP can create the signature.

The signature will be added to the headers of the request and is created from other headers. The body is included in the signature using a hash of the body contents which is added as the Digest header.

A complete request message could look like this:

  POST /notify HTTP/1.1
  Content-Length: 246
  Accept: */*
  Content-Type: application/json
  Host: onlinepaymentplatform.com
  Date: Wed, 15 Jun 2022 08:27:14 GMT
  Digest: SHA-256=GmUCOfLhpwG/mnmzlLmaqgEVvsxv4BUc1DWtAyxRvE8=
  Signature: keyId="nsk_7b0f85351b52",algorithm="hmac-sha256",headers="(request-target) host date digest",signature="7aBAXZkkZXBYfM8Rxv+FtarqwaqOnlBYNoFSqwE33wI="

  {"uid":"not_3e0f7595152b","type":"transaction.status.changed","created":1655274434,"object_uid":"sta_50473c4b0a4d","object_type":"transaction","object_url":""}

Signature Parameters

        (request-target): post /notify
        host: onlinepaymentplatform.com
        date: Wed, 15 Jun 2022 08:27:14 GMT
        digest: SHA-256=GmUCOfLhpwG/mnmzlLmaqgEVvsxv4BUc1DWtAyxRvE8=
      

Verify the HTTP Signature Header

To verify the HTTP Signature header in an incoming webhook request, you would need to perform the following steps:

1. Parse the HTTP Signature header and extract the relevant components, including the key ID, signature algorithm, and signature value.
2. Retrieve the notification secret associated with the key ID from a trusted source, such as a key server or a configuration file.
3. Calculate the expected signature value for the message using the same signature algorithm and input data as the sender.
4. Compare the expected signature value with the signature value included in the HTTP Signature header.
5. If the two values match, the signature is valid and the message can be processed. Otherwise, the message should be rejected as potentially tampered with or originating from an unauthorized source.

DEPRECATED - Validating Notifications (verification_hash)

In addition to whitelisting our notification servers' IP addresses you can also verify that a notification has been sent by us by verifying the verification_hash. The verification_hash can be compared using the notification_secret. Create a HMAC hash of the notification_secret, and compare this to the verification_hash. This will return true when the notification was sent by OPP. False if it was not. The notification_secret can be found in your partner interface, or ask your implementation manager to provide it to you. To check the hash, you can use the bash example below, or translate this to any programming language that is preferred.

    $ echo -n "{{NOTIFICATION_UID}}" | openssl sha256 -hmac "{{NOTIFICATION_SECRET}}"

Filter & Order

Example request - Transactions belonging to a certain merchant:

curl https://api-sandbox.onlinebetaalplatform.nl/v1/transactions?filter[merchant]={{merchant_uid}}
    -H "Authorization: Bearer {{api_key}}"

GET https://api-sandbox.onlinebetaalplatform.nl/v1/transactions?filter[merchant]={{merchant_uid}}

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]=2020-01-01 00:00:00, 2020-09-30 23:59:59 \
    -H "Authorization: Bearer {{api_key}}"

GET https://api-sandbox.onlinebetaalplatform.nl/v1/transactions?filter[0][name]=date_completed&filter[0][operand]=between&filter[0][value]=2020-01-01 00:00:00, 2020-09-30 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. Before passing information into the filter, always make sure that you have encoded your input to make it readable in URLs, otherwise special characters like +, & or ? might be interpreted in a different way.

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:

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

Every object can be ordered by the variables created and updated by using the order parameters date_created and date_updated respectively.

Expanding objects

Example request - Expand the transaction with the order details:

curl https://api-sandbox.onlinebetaalplatform.nl/v1/transactions/{{transaction_uid}}\
    ?expand[]=order \
    -H "Authorization: Bearer {{api_key}}"

GET "https://api-sandbox.onlinebetaalplatform.nl/v1/transactions/{{transaction_uid}}?expand[]=order"

Example response:

{
    "livemode": true,
    "uid": "{{transaction_uid}}",
    "object": "transaction",
    "metadata": [],
    "statuses": [],
    "order": {
        "uid": "{{order_uid}}",
        "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": {}
    }
}

curl https://api-sandbox.onlinebetaalplatform.nl/v1/merchants\
?expand[]=contacts \
-H "Authorization: Bearer {{api_key}}" \
-d country=nld \
-d emailaddress=email@domain.com \
-d phone=0612345678 \
-d notify_url=https://platform.com/notify \
-d return_url=https://platform.com/return

POST "https://api-sandbox.onlinebetaalplatform.nl/v1/merchants?expand[]=contacts"
{
  "country": "nld",
  "emailaddress": "email@domain.com",
  "phone": "0612345678",
  "notify_url": "https://platform.com/notify",
  "return_url": "https://platform.com/return"
}

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 descriptions of the objects.

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. Expands are also available on POST requests, to receive expanded data in the response.

Metadata

Example request:

curl https://api-sandbox.onlinebetaalplatform.nl/v1/transactions/{{transaction_uid}}/metadata \
    -H "Authorization: Bearer {{api_key}}"
    -d "metadata[external_id]=2015486"

POST "https://api-sandbox.onlinebetaalplatform.nl/v1/transactions/{{transaction_uid}}/metadata"
  {
    "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.

Information about filtering metadata can be found in filter & order

Updating or deleting metadata

In all cases, where metadata can be added, it is possible to update or delete metadata after creating the object.

GET /v1/transactions/{{transaction_uid}}/metadata POST /v1/transactions/{{transaction_uid}}/metadata DELETE /v1/transactions/{{transaction_uid}}/metadata

The key is the unique identifier in this metadata, meaning that if the key does not yet exist, the key/value pair will be added to the metadata. Should the key exist, the old value will be overwritten.

Deleting all metadata is possible by calling the delete method.

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.

Limitations

As any technical product, we continuously strive to improve our services and possibilities. As new features and products are implemented, this documentation page will be updated.

Online Payment Platform is obliged to follow Dutch laws, and must adhere to terms and conditions that are laid upon us by the Dutch National Bank, integrated payment methods, etc. This means that the API currently has the following limitations:

1. If you are building a web-/native app, iDEAL payments cannot be done in any in-app browser. iFrames, WebViews, or other in-app browsing solutions are not permitted, and we cannot guarantee a working solution here. Any other payment method might work, depending on what the provider allows. We cannot guarantee a working solution if you are using any kind of in-app browsing method.
2. Credit card payments are provided by our credit card acquirer WorldLine. Worldline makes sure that all rules according to 3DS and privacy are met. This also means that for credit card payments, you will be redirected to a webpage of Worldline.
3. Currently, not all objects within the OPP system will trigger a notification on a status change. For a full list of the current notifications, please take a look here.

Security

Another reason some limitations exist is due to security reasons, and prevention of cyber-attacks.

1. For security reasons API requests containing a direct reference to localhost, 127.0.0.1 or similar, for example in notify or return URLs, are not permitted and will be blocked. OPP will throw an HTTP status response 403 - Forbidden in this case. You may use a service such as xip.io or nip.io as a workaround or set up a local test-domain which can be referenced in the *_url fields.
2. OPP requires partners to throttle requests and send them sequentially to ensure the system does not get overloaded and partners do not get blacklisted due to DDOSing the system. To enforce this, OPP has implemented an HTTP status response 409 - Conflict. You will receive the error message "The request could not be completed.". When this happens, please retry the request at a later moment in time.
3. Please note that our API is a so called System-to-System API. This means that reaching it via a Frontend system will not work and lead to e.g. CORS errors. Due to security reasons (mainly having the API key available in the frontend), you will only be able to reach the API when using a suitable backend.

Merchants

OPP defines two kinds of merchants: Business merchants and Consumer merchants. This chapter will provide you all the necessary information about merchants and the functionalities of a merchant object. OPP provides a Seamless API onboarding for merchants, which ensures that you do not have to use two registration forms. Via the merchant 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 (except for file upload).

We have already provided a Postman collection on the Merchant API for you to start with. Also, we have provided a step-by-step guide on how to onboard Business and Consumer merchants.

Merchant

Object Definition - Merchant

The merchant object contains the following variables.

Merchant status

The merchant status is a status indication about the merchant account in the OPP system. The merchant status is NOT linked to the compliance status. A live merchant, does not mean that the merchant is approved, and thus able to receive payouts. Only when a merchant status is live and when the compliance status is verified, the merchant will be able to receive payouts.

The possible status flows can be found below:

Please note that the statuses can be forced in sandbox. See Merchant status simulations.

Notification Example - Merchant

Example notification:

{
  "uid": "{{notification_uid}}",
  "type": "merchant.status.changed",
  "created": 1619182391,
  "object_uid": "{{merchant_uid}}",
  "object_type": "merchant",
  "object_url": "https://api-sandbox.onlinebetaalplatform.nl/v1/merchants/{{merchant_uid}}",
  "verification_hash": "{{hash}}"
}

Please find a notification example to the right.

Merchant countries

OPP is licensed to onboard almost all countries in the European Economic Area. The current countries that are allowed for onboarding and thus payouts are: Belgium, Bulgaria, Cyprus, Denmark, Germany, Estonia, Finland, France, Greece, Hungary, Ireland, Italy, Croatia, Lithuania, Latvia, Luxembourg, Malta, The Netherlands, Norway, Austria, Poland, Portugal, Romania, Slovenia, Slovakia, Spain, Czech Republic, Great-Britain, Sweden.

The list of countries that are allowed according to our licence can always be seen here.

Create Merchant

Example request - Creating a consumer merchant:

curl https://api-sandbox.onlinebetaalplatform.nl/v1/merchants \
    -H "Authorization: Bearer {{api_key}}" \
    -d country=nld \
    -d emailaddress=email@domain.com \
    -d phone=0612345678 \
    -d notify_url=https://platform.com/notify \
    -d return_url=https://platform.com/return

POST https://api-sandbox.onlinebetaalplatform.nl/v1/merchants
{
  "country": "nld",
  "emailaddress": "email@domain.com",
  "phone": "0612345678",
  "notify_url": "https://platform.com/notify",
  "return_url": "https://platform.com/return"
}

Example response:

{
    "uid": "{{merchant_uid}}",
    "object": "merchant",
    "created": 1554113700,
    "updated": 1554113700,
    "status": "pending",
    "compliance": {
        "level": 100,
        "status": "verified",
        "overview_url": "https://sandbox.onlinebetaalplatform.nl/nl/{{slug}}/{{merchant_uid}}/{{hash}}/overzicht",
        "requirements": []
    },
    "type": "consumer",
    "coc_nr": null,
    "name": "John Tester",
    "phone": "31601234567",
    "vat_nr": null,
    "country": "nld",
    "sector": null,
    "addresses": [],
    "trading_names": [],
    "contacts": [],
    "profiles": [],
    "payment_methods": [],
    "notify_url": "https://platform.com/notify",
    "return_url": "https://platform.com/return",
    "metadata": []
}

You can create a merchant using the Merchant API. The merchant_uid will be known immediately after creating the merchant, even when the compliance part has not been finalised by the user yet.

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

• Country: country
• Email address: emailaddress
• Notify URL: notify_url
• ( BUSINESS ONLY! ) Type: type = business
• ( BUSINESS ONLY! ) CoC Number: coc_nr

The more fields of the merchant object you fill in when creating a merchant, the easier the Know Your Customer (KYC) check on our side can be done. Below are all merchant object variables that can be used in the POST request when creating a merchant.

Retrieve Merchant

Example request - Retrieve a single merchant:

curl https://api-sandbox.onlinebetaalplatform.nl/v1/merchants/{{merchant_uid}} \
    -H "Authorization: Bearer {{api_key}}"

GET https://api-sandbox.onlinebetaalplatform.nl/v1/merchants/{{merchant_uid}}

Example response:

{
    "uid": "{{merchant_uid}}",
    "object": "merchant",
    "created": 1554113700,
    "updated": 1554113700,
    "status": "pending",
    "compliance": {
        "level": 100,
        "status": "verified",
        "overview_url": "https://sandbox.onlinebetaalplatform.nl/nl/{{slug}}/{{merchant_uid}}/{{hash}}/overzicht",
        "requirements": []
    },
    "type": "consumer",
    "coc_nr": null,
    "name": "John Tester",
    "phone": "31601234567",
    "vat_nr": null,
    "country": "nld",
    "sector": null,
    "addresses": [],
    "trading_names": [],
    "contacts": [],
    "profiles": [],
    "payment_methods": [],
    "notify_url": "https://platform.com/notify",
    "return_url": "https://platform.com/return",
    "metadata": []
}

Example request - Retrieve all merchants:

curl https://api-sandbox.onlinebetaalplatform.nl/v1/merchants \
    -H "Authorization: Bearer {{api_key}}"

GET https://api-sandbox.onlinebetaalplatform.nl/v1/merchants

Example response:

{
    "object": "list",
    "url": "/v1/merchants",
    "has_more": true,
    "total_item_count": 178,
    "items_per_page": 10,
    "current_page": 1,
    "last_page": 18,
    "data": [
        {
            "uid": "{{merchant_uid}}",
            "object": "merchant",
            "created": 1606988065,
            "updated": 1606988065,
            "status": "pending",
            "compliance": {
                "level": 400,
                "status": "unverified",
                ...
            },
            "type": "business",
            ...
            "metadata": []
        },
        ...
    ]
}

You can retrieve an individual merchant as well as a list of all merchants. Certain data, such as profiles, addresses, trading names and payment methods may be expanded.

The following filters can be used when retrieving merchants:

Merchant Trading Names

Example response - expanding trading_names:

{
    "livemode": false,
    "uid": "{{merchant_uid}}",
    "object": "merchant",
    ...
    "trading_names": [
        {
            "uid": "mtn_06275a6fcd44",
            "object": "trading_name",
            "created": 1613486266,
            "updated": 1613486266,
            "name": "Testing BV"
        },
        {
            "uid": "mtn_7e453883c8ea",
            "object": "trading_name",
            "created": 1613486266,
            "updated": 1613486266,
            "name": "Testing NV"
        }
    ],
...
}

When expanding certain objects, they will appear when requested. Objects that do not have any CRUD functionality, but are either set by OPP or only set when creating the merchant can be found here.

Merchant Payment Methods

Example response - Expanding payment_methods:

{
    "livemode": false,
    "uid": "{{merchant_uid}}",
    "object": "merchant",
    ...
    "payment_methods": [
        {
            "uid": "mpm_6b2917f3a0b6",
            "object": "payment_method",
            "name": "ideal",
            "status": "active"
        },
        {
            "uid": "mpm_cc8a94c50d5a",
            "object": "payment_method",
            "name": "bcmc",
            "status": "active"
        },
        {
            "uid": "mpm_c34fc02123e6",
            "object": "payment_method",
            "name": "sepa",
            "status": "active"
        }
    ],
    ...
}

Example request - Retrieve the payment methods of a merchant.

curl https://api-sandbox.onlinebetaalplatform.nl/v1/merchants/{{merchant_uid}}/payment_methods \
    -H "Authorization: Bearer {{api_key}}"

POST https://api-sandbox.onlinebetaalplatform.nl/v1/merchants/{{merchant_uid}}/payment_methods

Example response:

{
    "object": "list",
    "url": "/v1/merchants/{{merchant_uid}}/payment_methods",
    "has_more": false,
    "total_item_count": 3,
    "items_per_page": 10,
    "current_page": 1,
    "last_page": 1,
    "data": [
        {
            "uid": "mpm_6b2917f3a0b6",
            "object": "payment_method",
            "name": "ideal",
            "status": "active"
        },
        {
            "uid": "mpm_cc8a94c50d5a",
            "object": "payment_method",
            "name": "bcmc",
            "status": "active"
        },
        {
            "uid": "mpm_c34fc02123e6",
            "object": "payment_method",
            "name": "sepa",
            "status": "active"
        }
    ],
}

Merchant payment methods can either be retrieved by expanding the merchant object, or by using the payment_methods endpoint, as can be seen on the right.

Update Merchant

Example request - Update a merchant:

curl https://api-sandbox.onlinebetaalplatform.nl/v1/merchants/{{merchant_uid}} \
    -H "Authorization: Bearer {{api_key}}" \
    -d notify_url=https://platform.com/notify \
    -d return_url=https://platform.com/return

POST https://api-sandbox.onlinebetaalplatform.nl/v1/merchants/{{merchant_uid}}
{
    "notify_url": "https://platform.com/notify",
    "return_url": "https://platform.com/return"
}

Example response:

{
    "uid": "{{merchant_uid}}",
    "object": "merchant",
    "created": 1554113700,
    "updated": 1554113700,
    "status": "pending",
    "compliance": {
        "level": 100,
        "status": "verified",
        "overview_url": "https://sandbox.onlinebetaalplatform.nl/nl/{{slug}}/{{merchant_uid}}/{{hash}}/overzicht",
        "requirements": []
    },
    "type": "consumer",
    "coc_nr": null,
    "name": "John Tester",
    "phone": "31601234567",
    "vat_nr": null,
    "country": "nld",
    "sector": null,
    "addresses": [],
    "trading_names": [],
    "contacts": [],
    "profiles": [],
    "payment_methods": [],
    "notify_url": "https://platform.com/notify",
    "return_url": "https://platform.com/return",
    "metadata": []
}

You are able to update a merchant by performing a POST on the merchant object. You can update one variable at a time, or multiple as you desire. The following fields can be updated:

Migrate Merchant

Example request - Migrate a merchant to business merchant:

curl https://api-sandbox.onlinebetaalplatform.nl/v1/merchants/{{merchant_uid}}/migrate \
    -H "Authorization: Bearer {{api_key}}" \
    -d coc_nr=12345678 \
    -d country=nld

POST https://api-sandbox.onlinebetaalplatform.nl/v1/merchants/{{merchant_uid}}/migrate
{
  "coc_nr": "12345678",
  "country": "nld"
}

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 and the country in which the business merchant operates. Please note that it is not possible (and not permitted) to migrate a merchant from business back to consumer. In this case, you will always need to terminate the business account and create a new consumer merchant.

Delete Merchant

curl https://api-sandbox.onlinebetaalplatform.nl/v1/merchants/{{merchant_uid}} \
    -H "Authorization: Bearer {{api_key}}" \
    -d status=terminated

POST https://api-sandbox.onlinebetaalplatform.nl/v1/merchants/{{merchant_uid}}
{
    "status": "terminated"
}

Example response:

{
    "uid": "{{merchant_uid}}",
    "object": "merchant",
    "created": 1554113700,
    "updated": 1554113700,
    "status": "terminated",
    "compliance": {
        "level": 100,
        "status": "verified",
        "overview_url": "https://sandbox.onlinebetaalplatform.nl/nl/{{slug}}/{{merchant_uid}}/{{hash}}/overzicht",
        "requirements": []
    },
    "type": "consumer",
    ...
}

Due to legal reasons, we can never fully delete merchants. Therefore, it will not be possible for you to delete merchants in the sandbox nor the production environment. You can however, update the merchant status in order to let us know the account needs to be closed.

Please note that updating the merchant status means the merchant will not receive payouts anymore.

We distinguish two reasons and statuses for deleting merchants:

• Termination - terminated - The merchant account is closed and will not be used anymore.
• Suspension - suspended - The merchant has committed fraud and the user will (temporarily) be blocked.

Sandbox Simulation - Merchant

Example request - Update the merchant status

curl https://api-sandbox.onlinebetaalplatform.nl/v1/merchants/{{merchant_uid}}/update-status \
    -H "Authorization: Bearer {{api_key}}" \
    -d status=live

POST https://api-sandbox.onlinebetaalplatform.nl/v1/merchants/{{merchant_uid}}/update-status
{
    "status": "live"
}

The status of the merchant can be changed using a post to the endpoint at the right

The flows that can be simulated are:

• new -> pending -> live
• new -> pending -> live -> suspended
• new -> pending -> live -> terminated
• new -> pending -> live -> blocked
• suspended -> live
• terminated -> live

Address

Object Definition - Address

The merchant address object contains the following variables.

Create Address

Example request - Create address object for the merchant:

curl https://api-sandbox.onlinebetaalplatform.nl/v1/merchants/{{merchant_uid}}/addresses \
    -H "Authorization: Bearer {{api_key}}" \
    -d "address_line_1=Kerklaan 1" \
    -d zipcode=1234AB \
    -d city=Amsterdam \
    -d country=nld

POST https://api-sandbox.onlinebetaalplatform.nl/v1/merchants/{{merchant_uid}}/addresses
{
  "address_line_1": "Kerklaan 1",
  "zipcode": "11234AB",
  "city": "Amsterdam",
  "country": "nld"
}

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",
    "country": "Netherlands"
}

You can create a merchant address using the Merchant API. Below are all merchant address object variables that can be used in the POST request when creating a merchant address.

Retrieve Address

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

curl https://api-sandbox.onlinebetaalplatform.nl/v1/merchants/{{merchant_uid}}/addresses/{{merchant_address_uid}} \
    -H "Authorization: Bearer {{api_key}}" \

GET https://api-sandbox.onlinebetaalplatform.nl/v1/merchants/{{merchant_uid}}/addresses/{{merchant_address_uid}}

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",
    "country": "Netherlands"
}

Example request - Retrieve all address objects from the merchant:

curl https://api-sandbox.onlinebetaalplatform.nl/v1/merchants/{{merchant_uid}}/addresses \
    -H "Authorization: Bearer {{api_key}}" \

GET https://api-sandbox.onlinebetaalplatform.nl/v1/merchants/{{merchant_uid}}/addresses

Example response:

{
    "object": "list",
    "url": "//v1/merchants/{{merchant_uid}}/addresses",
    "has_more": true,
    "total_item_count": 7,
    "items_per_page": 5,
    "current_page": 1,
    "last_page": 2,
    "data": [
        {
            "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",
            "country": "Netherlands"
        },
        ...
    ]
}

You can retrieve an individual address of a merchant as well as a list of all addresses of a merchant. The following filters can be used when retrieving merchant addresses:

Update Address

Example request - Update address object for the merchant:

curl https://api-sandbox.onlinebetaalplatform.nl/v1/merchants/{{merchant_uid}}/addresses/{{merchant_address_uid}} \
    -H "Authorization: Bearer {{api_key}}" \
    -d "address_line_1=Kerklaan 1" \
    -d zipcode=1234AB \
    -d city=Amsterdam \
    -d country=nld

POST https://api-sandbox.onlinebetaalplatform.nl/v1/merchants/{{merchant_uid}}/addresses//{{merchant_address_uid}}
{
  "address_line_1": "Kerklaan 1",
  "zipcode": "11234AB",
  "city": "Amsterdam",
  "country": "nld"
}

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",
    "country": "Netherlands"
}

You are able to update a merchant address by performing a POST on the merchant object. You can update one variable at a time, or multiple as you desire. The following fields can be updated:

Delete address

It is not possible to delete an address. In case an address is not valid anymore, please create a new address with the valid information. The latest address wil be used by OPP if needed.

Bank Account

Object Definition - Bank Account

The merchant bank account object contains the following variables.

Bank Account status

The merchant bank_account status is a status indication about the merchant bank_account verification in the OPP system. The merchant bank_account status is DIRECTLY linked to the compliance status, when the compliance level is >= 200. Only when a merchant status is live and when the compliance status is verified, the merchant will be able to receive payouts.

The possible status flows can be found below:

Please note that the statuses can be forced in sandbox. See Merchant bank account status simulations.

Bank Account Disapproval Reasons

Example response:

{
  ...
  "disapprovals": [
    {
      "name": "bank_account_document_front_missing",
      "created": 1685698690
    }
  ]
}

A bank account object can be disapproved for various reasons. To make sure you can help your merchants as good as possible, OPP provides the disapproval reasons in the bank account object via the API. If no disapproval reasons can be found, the array will be empty. If the bank account has multiple rejections, the reasons will be added at the end of the list.

The reasons used can be found below.

Notification Example - Bank Account

Example notification:

{
  "uid": "{{notification_uid}}",
  "type": "bank_account.status.changed",
  "created": 1653488841,
  "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}}",
  "verification_hash": "{{hash}}"
}

Please find a notification example to the right.

Create Bank Account

Example request - Create contact object for the merchant:

curl https://api-sandbox.onlinebetaalplatform.nl/v1/merchants/{{merchant_uid}}/bank_accounts \
    -H "Authorization: Bearer {{api_key}}" \
    -d return_url=https://platform.example.com/return \
    -d notify_url=https://platform.example.com/notify

POST https://api-sandbox.onlinebetaalplatform.nl/v1/merchants/{{merchant_uid}}/bank_accounts
{
    "return_url": "{{return_url}}",
    "notify_url": "{{notify_url}}"
}

Example response:

{
    "uid": "{{bank_account_uid}}",
    "object": "bank_account",
    "created": 1554200096,
    "updated": 1554200096,
    "verified": null,
    "verified_with": null,
    "verification_url": "https://onlinebetaalplatform.nl/nl/
     {partner_name}/merchants/{{merchant_uid}}/verificatie/
     bankgegevens/{{bank_account_uid}}/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,
    "disapprovals": [
        {
            "name": "bank_account_document_front_missing",
            "created": 1685698690
        }
    ]
}

You can create a merchant bank account using the Merchant API. Below are all merchant bank_account object variables that can be used in the POST request when creating a merchant bank account. Every bank account you create needs to be verified using the verification_url.

Retrieve Bank Account

Example request - Retrieve a single bank_account object from the merchant, using the bank_account_uid:

curl https://api-sandbox.onlinebetaalplatform.nl/v1/merchants/{{merchant_uid}}/bank_accounts/{{bank_account_uid}} \
    -H "Authorization: Bearer {{api_key}}"

GET https://api-sandbox.onlinebetaalplatform.nl/v1/merchants/{{merchant_uid}}/bank_accounts/{{bank_account_uid}}

Example response:

{
    "uid": "{{bank_account_uid}}",
    "object": "bank_account",
    "created": 1554200096,
    "updated": 1554200096,
    "verified": null,
    "verified_with": null,
    "verification_url": "https://onlinebetaalplatform.nl/nl/
     {partner_name}/merchants/{{merchant_uid}}/verificatie/
     bankgegevens/{{bank_account_uid}}/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,
  "disapprovals": [
    {
      "name": "bank_account_document_front_missing",
      "created": 1685698690
    }
  ]
}

Example request - Retrieve all bank accounts objects from the merchant:

curl https://api-sandbox.onlinebetaalplatform.nl/v1/merchants/{{merchant_uid}}/bank_accounts \
    -H "Authorization: Bearer {{api_key}}"

GET https://api-sandbox.onlinebetaalplatform.nl/v1/merchants/{{merchant_uid}}/bank_accounts

Example response:

{
    "object": "list",
    "url": "//v1/merchants/{{merchant_uid}}/bank_accounts",
    "has_more": false,
    "total_item_count": 5,
    "items_per_page": 5,
    "current_page": 1,
    "last_page": 1,
    "data": [
        {
            "uid": "{{bank_account_uid}}",
            "object": "bank_account",
            "created": 1554200096,
            "updated": 1554200096,
            "verified": null,
            "verified_with": null,
            "verification_url": "https://onlinebetaalplatform.nl/nl/
             {partner_name}/merchants/{{merchant_uid}}/verificatie/
             bankgegevens/{{bank_account_uid}}/7a8d3c308b0739ef96320720017d070533912548",
            "status": "new",
            "account": {
                "account_iban": null,
                "account_name": null
            },
            "bank": {
                "bic": null
            },
            "reference": null,
            "return_url": "https://platform.example.com/return",
            "notify_url": "https://platform.example.com/notify",
            "is_default": true,
      "disapprovals": [
        {
          "name": "bank_account_document_front_missing",
          "created": 1685698690
        }
      ]
        }
        ...
    ]
}

You can retrieve an individual bank account of a merchant as well as a list of all bank accounts of a merchant. The following filters can be used when retrieving merchant bank accounts:

Update Bank Account

Example request - Update bank_account object for the merchant:

curl https://api-sandbox.onlinebetaalplatform.nl/v1/merchants/{{merchant_uid}}/bank_accounts/{{bank_account_uid}} \
    -H "Authorization: Bearer {{api_key}}" \
    -d reference=bank-123 \
    -d return_url=https://platform.example.com/return \
    -d notify_url=https://platform.example.com/notify

POST https://api-sandbox.onlinebetaalplatform.nl/v1/merchants/{{merchant_uid}}/bank_accounts/{{bank_account_uid}}
{
    "reference": "bank-123",
    "return_url": "https://platform.example.com/return",
    "notify_url": "https://platform.example.com/notify"
}

Example response:

{
    "uid": "{{bank_account_uid}}",
    "object": "bank_account",
    "created": 1554200096,
    "updated": 1554200096,
    "verified": null,
    "verified_with": null,
    "verification_url": "https://onlinebetaalplatform.nl/nl/
     {partner_name}/merchants/{{merchant_uid}}/verificatie/
     bankgegevens/{{bank_account_uid}}/7a8d3c308b0739ef96320720017d070533912548",
    "status": "new",
    "account": {
        "account_iban": null
    },
    "bank": {
        "bic": null
    },
    "reference": bank-123,
    "return_url": "https://platform.example.com/return",
    "notify_url": "https://platform.example.com/notify",
    "is_default": true,
    "disapprovals": [
      {
        "name": "bank_account_document_front_missing",
        "created": 1685698690
      }
    ]
}

You are able to update a merchant bank account by performing a POST on the merchant object. You can update one variable at a time, or multiple as you desire. The following fields can be updated:

Delete Bank Account

It is not possible to delete a bank account. In case a bank_account is not valid anymore, please create a new bank_account with the valid information. The latest bank_account information wil be used by OPP for payouts.

Sandbox Simulation - Bank Account

Example request - Update the merchant bank_account status

curl https://api-sandbox.onlinebetaalplatform.nl/v1/merchants/{{merchant_uid}}/bank_accounts/{{bank_account_uid}}/update-status \
    -H "Authorization: Bearer {{api_key}}" \
    -d status=approved

POST https://api-sandbox.onlinebetaalplatform.nl/v1/merchants/{{merchant_uid}}/bank_accounts/{{bank_account_uid}}/update-status
{
    "status": "approved"
}

The status of the merchant bank account can be changed using a post to the endpoint at the right.

The flows that can be simulated are:

• new -> pending -> approved
• new -> pending -> disapproved
• approved -> disapproved -> approved

Contact

Object Definition - Contact

The merchant contact object contains the following variables.

Contact status

The merchant contact status is a status indication about the merchant representative verification in the OPP system. The merchant contact status is DIRECTLY linked to the compliance status, when the compliance level is >= 400. Only when a merchant status is live and when the compliance status is verified, the merchant will be able to receive payouts.

The possible status flows can be found below:

Please note that the statuses can be forced in sandbox. See Merchant contact status simulations.

Contact Disapproval Reasons

Example response:

{
  ...
  "disapprovals": [
    {
      "name": "contact_document_expired",
      "created": 1685698690
    }
  ]
}

A contact object can be disapproved for various reasons. To make sure you can help your merchants as good as possible, OPP provides the disapproval reasons in the contact object via the API. If no disapproval reasons can be found, the array will be empty. If the bank account has multiple rejections, the reasons will be added at the end of the list.

The reasons used can be found below.

Notification Example - Contact

Example notification contact status:

{
  "uid": "{{notification_uid}}",
  "type": "contact.status.changed",
  "created": 1653488996,
  "object_uid": "{{contact_uid}}",
  "object_type": "contact",
  "object_url": "https://api-sandbox.onlinebetaalplatform.nl/v1/merchants/{{merchant_uid}}/contacts/{{contact_uid}}",
  "parent_uid": "{{merchant_uid}}",
  "parent_type": "merchant",
  "parent_url": "https://api-sandbox.onlinebetaalplatform.nl/v1/merchants/{{merchant_uid}}",
  "verification_hash": "{{hash}}"
}

Example notification contact phone number:

{
"uid": "{{notification_uid}}",
"type": "contact.status.changed",
"created": 1653488996,
"object_uid": "{{contact_uid}}",
"object_type": "contact",
"object_url": "https://api-sandbox.onlinebetaalplatform.nl/v1/merchants/{{merchant_uid}}/contacts/{{contact_uid}}",
"parent_uid": "{{merchant_uid}}",
"parent_type": "merchant",
"parent_url": "https://api-sandbox.onlinebetaalplatform.nl/v1/merchants/{{merchant_uid}}",
"verification_hash": "{{hash}}"
}

Please find a notification example to the right.

Create Contact

Example request - Create contact object for the merchant:

curl https://api-sandbox.onlinebetaalplatform.nl/v1/merchants/{{merchant_uid}}/contacts \
    -H "Authorization: Bearer {{api_key}}" \
    -d type=representative \
    -d title=mr \
    -d gender=m \
    -d name[initials]=T \
    -d name[names_given]=Tinus \
    -d name[first]=Tinus \
    -d name[last]=Tester \
    -d birthdate=1970-10-10 \
    -d emailaddresses[0][emailaddress]=tinus@tester.com \
    -d phonenumbers[0][phonenumber]=0612345678

POST https://api-sandbox.onlinebetaalplatform.nl/v1/merchants/{{merchant_uid}}/contacts
{
    "type": "representative",
    "title": "mr",
    "gender": "m",
    "name":
        {
            "initials": "t",
            "names_given": "Tinues",
            "first": "Tinus",
            "last": "Tester"
        },
    "birthdate": "1970-10-10",
    "emailaddresses": [
        {
            "emailaddress": "tinus@tester.com"
        },
        {
            "emailaddress": "tinus2@tester.com"
        }
    ],
    "phonenumbers": [
        {
            "phonenumber": "0612345678"
        },
        {
            "phonenumber": "0687654321"
        }
    ]
}

Example response:

{
    "livemode": false,
    "uid": "{{contact_uid}}",
    "object": "contact",
    "created": 1594297774,
    "updated": 1594297774,
    "verified": null,
    "verified_with": null,
    "status": "unverified",
    "verification_url": "https://sandbox.onlinebetaalplatform.nl/nl/testindividual/merchants/{{merchant_uid}/verificatie/contactgegevens/{{contact_uid}}/d4e3e1cec62b9f25458367b416d7a58ac3f20b7e",
    "type": "representative",
    "title": "mr",
    "name_initials": "t",
    "name_first": "Tinus",
    "name_last": "Tester",
    "names_given": "Tinues",
    "birthdate": 13,
    "partner_name_last": 14,
    "emailaddresses": [
        {
            "uid": "ema_23d902800c7c",
            "object": "emailaddress",
            "created": 1594297774,
            "updated": 1594297774,
            "verified": null,
            "emailaddress": "tinus@tester.com"
        },
        {
            "uid": "ema_d7d123643921",
            "object": "emailaddress",
            "created": 1594297774,
            "updated": 1594297774,
            "verified": null,
            "emailaddress": "tinus2@tester.com"
        }
    ],
    "phonenumbers": [
        {
            "uid": "pho_785e81851ab6",
            "object": "phonenumber",
            "created": 1594297774,
            "updated": 1594297774,
            "verified": null,
            "phonenumber": "0612345678"
        },
        {
            "uid": "pho_ea6610cc8154",
            "object": "phonenumber",
            "created": 1594297774,
            "updated": 1594297774,
            "verified": null,
            "phonenumber": "0687654321"
        }
    ],
    "is_pep": null,
    "disapprovals": [
      {
        "name": "contact_document_expired",
        "created": 1685698690
      }
    ]
}

You can create a merchant contact using the Merchant API. Below are all merchant contact object variables that can be used in the POST request when creating a merchant contact. Every contact you create needs to be verified using the verification_url.

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 48 hours on working days.

More information on how to use the iDIN issuers can be found here. You can use the iDIN issuers to immediately redirect the user to the bank, without showing our screens. Append the verification URL with {verification_url}?verification_type=idin&issuer=[BIC]

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.

Retrieve Contact

Example request - Retrieve a single contact object from the merchant, using the contact_uid:

curl https://api-sandbox.onlinebetaalplatform.nl/v1/merchants/{{merchant_uid}}/contacts/{{contact_uid}} \
    -H "Authorization: Bearer {{api_key}}"

GET https://api-sandbox.onlinebetaalplatform.nl/v1/merchants/{{merchant_uid}}/contacts/{{contact_uid}}

Example response:

{
    "uid": "{{contact_uid}}",
    "object": "contact",
    "created": 1594297774,
    "updated": 1594297774,
    "verified": null,
    "verified_with": null,
    "status": "unverified",
    "verification_url": "https://sandbox.onlinebetaalplatform.nl/nl/testindividual/merchants/{{merchant_uid}/verificatie/contactgegevens/{{contact_uid}}/d4e3e1cec62b9f25458367b416d7a58ac3f20b7e",
    "type": "representative",
    "title": "mr",
    "name_initials": "t",
    "name_first": "Tinus",
    "name_last": "Tester",
    "names_given": "Tinues",
    "birthdate": 13,
    "partner_name_last": 14,
    "emailaddresses": [
        {
            "uid": "ema_23d902800c7c",
            "object": "emailaddress",
            "created": 1594297774,
            "updated": 1594297774,
            "verified": null,
            "emailaddress": "tinus@tester.com"
        },
        {
            "uid": "ema_d7d123643921",
            "object": "emailaddress",
            "created": 1594297774,
            "updated": 1594297774,
            "verified": null,
            "emailaddress": "tinus2@tester.com"
        }
    ],
    "phonenumbers": [
        {
            "uid": "pho_785e81851ab6",
            "object": "phonenumber",
            "created": 1594297774,
            "updated": 1594297774,
            "verified": null,
            "phonenumber": "0612345678"
        },
        {
            "uid": "pho_ea6610cc8154",
            "object": "phonenumber",
            "created": 1594297774,
            "updated": 1594297774,
            "verified": null,
            "phonenumber": "0687654321"
        }
    ],
    "is_pep": null,
    "disapprovals": [
        {
            "name": "contact_document_expired",
            "created": 1685698690
        }
    ]
}

Example request - Retrieve all contact objects from the merchant:

curl https://api-sandbox.onlinebetaalplatform.nl/v1/merchants/{{merchant_uid}}/contacts \
    -H "Authorization: Bearer {{api_key}}"

GET https://api-sandbox.onlinebetaalplatform.nl/v1/merchants/{{merchant_uid}}/contacts

Example response:

{
    "object": "list",
    "url": "//v1/merchants/{{merchant_uid}}/contacts",
    "has_more": false,
    "total_item_count": 3,
    "items_per_page": 5,
    "current_page": 1,
    "last_page": 1,
    "data": [
        {
            "uid": "{{contact_uid}}",
            "object": "contact",
            "created": 1568205415,
            "updated": 1612165832,
            "verified": null,
            "verified_with": null,
            "status": "pending",
            "verification_url": "https://sandbox.onlinebetaalplatform.nl/nl/testindividual/merchants/{{merchant_uid}}/verificaties/contact-gegevens/{{contact_uid}}/eaf0ea30cbd2e048c0d9c9b6282b95acc7e99300",
            "type": "representative",
            "title": "mr",
            "name_initials": "t",
            "name_first": "Tinus",
            "name_last": "Tester",
            "names_given": "Tinues",
            "birthdate": 13,
            "partner_name_last": 14,
            "emailaddresses": [
                {
                    "uid": "ema_23d902800c7c",
                    "object": "emailaddress",
                    "created": 1594297774,
                    "updated": 1594297774,
                    "verified": null,
                    "emailaddress": "tinus@tester.com"
                },
                {
                    "uid": "ema_d7d123643921",
                    "object": "emailaddress",
                    "created": 1594297774,
                    "updated": 1594297774,
                    "verified": null,
                    "emailaddress": "tinus2@tester.com"
                }
            ],
            "phonenumbers": [
                {
                    "uid": "pho_785e81851ab6",
                    "object": "phonenumber",
                    "created": 1594297774,
                    "updated": 1594297774,
                    "verified": null,
                    "phonenumber": "0612345678"
                },
                {
                    "uid": "pho_ea6610cc8154",
                    "object": "phonenumber",
                    "created": 1594297774,
                    "updated": 1594297774,
                    "verified": null,
                    "phonenumber": "0687654321"
                }
            ]
        },
        ...
    ]
}

You can retrieve an individual contact of a merchant as well as a list of all contacts of a merchant. The following filters can be used when retrieving merchant contacts:

Update Contact

Example request - Update contact object for the merchant:

curl https://api-sandbox.onlinebetaalplatform.nl/v1/merchants/{{merchant_uid}}/contacts/{{contact_uid}} \
    -H "Authorization: Bearer {{api_key}}" \
    -d type=representative \
    -d title=mr \
    -d gender=m \
    -d name[initials]=T \
    -d name[names_given]=Tinus \
    -d name[first]=Tinus \
    -d name[last]=Tester \
    -d birthdate=1970-10-10 \
    -d emailaddresses[0][emailaddress]=tinus@tester.com \
    -d phonenumbers[0][phonenumber]=0612345678

POST https://api-sandbox.onlinebetaalplatform.nl/v1/merchants/{{merchant_uid}}/contacts/{{contact_uid}}
{
    "type": "representative",
    "title": "mr",
    "gender": "m",
    "name":
        {
            "initials": "t",
            "names_given": "Tinues",
            "first": "Tinus",
            "last": "Tester"
        },
    "birthdate": "1970-10-10",
    "emailaddresses": [
        {
            "emailaddress": "tinus@tester.com"
        },
        {
            "emailaddress": "tinus2@tester.com"
        }
    ],
    "phonenumbers": [
        {
            "phonenumber": "0612345678"
        },
        {
            "phonenumber": "0687654321"
        }
    ]
}

Example response:

{
    "uid": "{{contact_uid}}",
    "object": "contact",
    "created": 1594297774,
    "updated": 1594297774,
    "verified": null,
    "verified_with": null,
    "status": "unverified",
    "verification_url": "https://sandbox.onlinebetaalplatform.nl/nl/testindividual/merchants/{{merchant_uid}/verificatie/contactgegevens/{{contact_uid}}/d4e3e1cec62b9f25458367b416d7a58ac3f20b7e",
    "type": "representative",
    "title": "mr",
    "name_initials": "t",
    "name_first": "Tinus",
    "name_last": "Tester",
    "names_given": "Tinues",
    "birthdate": 13,
    "partner_name_last": 14,
    "emailaddresses": [
        {
            "uid": "ema_23d902800c7c",
            "object": "emailaddress",
            "created": 1594297774,
            "updated": 1594297774,
            "verified": null,
            "emailaddress": "tinus@tester.com"
        },
        {
            "uid": "ema_d7d123643921",
            "object": "emailaddress",
            "created": 1594297774,
            "updated": 1594297774,
            "verified": null,
            "emailaddress": "tinus2@tester.com"
        }
    ],
    "phonenumbers": [
        {
            "uid": "pho_785e81851ab6",
            "object": "phonenumber",
            "created": 1594297774,
            "updated": 1594297774,
            "verified": null,
            "phonenumber": "0612345678"
        },
        {
            "uid": "pho_ea6610cc8154",
            "object": "phonenumber",
            "created": 1594297774,
            "updated": 1594297774,
            "verified": null,
            "phonenumber": "0687654321"
        }
    ],
    "is_pep": null,
    "disapprovals": [
        {
            "name": "contact_document_expired",
            "created": 1685698690
        }
    ]
}

You are able to update a merchant contact by performing a POST on the merchant object. You can update one variable at a time, or multiple as you desire. The following fields can be updated:

Delete Contact

It is not possible to delete a contact. In case a contact is not valid anymore, please create a new contact with the valid information. The latest contact information wil be used by OPP if needed.

Sandbox Simulation - Contact

Merchant Contact statuses

Example request - Update the merchant contact status

curl https://api-sandbox.onlinebetaalplatform.nl/v1/merchants/{{merchant_uid}}/contacts/{{contact_uid}}/update-status \
    -H "Authorization: Bearer {{api_key}}" \
    -d status=verified

POST https://api-sandbox.onlinebetaalplatform.nl/v1/merchants/{{merchant_uid}}/contacts/{{contact_uid}}/update-status
{
    "status": "verified"
}

The status of the merchant contact can be changed using a post to the endpoint at the right.

The flows that can be simulated are:

• pending -> unverified
• pending -> verified
• unverified -> verified

iDIN verification

You can skip the whitelabel screens and immediately force an iDIN status when appending the redirect_url with the following:

    https://onlinebetaalplatform.nl/nl/{{partner}}/merchants/{{merchant_uid}}/
        verificatie/contactgegevens
        /{{contact_uid}}/{{hash}}?verification_type=idin&issuer={{issuer}}

You can use one of the issuers below for automatic testing: