NAV Navbar
Search results for:
    Questions

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

    Introduction

    Online Payment Platform (OPP) is an end-to-end payment solution with a set of flexible API's designed to support platforms and marketplaces. Allowing a platform to seamlessly onboard new business and consumer merchants enabling them to accept payments on the platform while processing the money in flexible ways to sellers and service providers.

    Usecases:

    This guides consist of the following chapters:

    Let's get started!

    Before we start, have a look at our terminology, to make sure you understand every word we say.

    For each receiver of the money, the partner (platform) is required to create a merchant within OPP. A merchant can be a business or a consumer. Depending on the type of merchant, these have to go through different verifications before they can receive money. It is important to note that transactions can be initiated for a merchant before they are required to finalize any verifications, but it is up to you whether you want to provide this possibility.

    These verifications are required for processing payments because as a Payment Service Provider we are obliged to know to whom payments are made. For example to prevent money laundering and the financing of terrorism.

    Merchants can be created using our Seamless Merchant onboarding. Seamless onboarding allows you to onboard merchants (business or consumer) seamlessly from within your platform environment through API onboarding.

    Advantages

    As a partner you can simply create an underlying merchant using the minimal requirements: their emailaddress and phonenumber.

    Once a new merchant has been created you will receive a Merchant UID which is the unique identifier for this user. You will need to save the Merchant UID and use it to, amongst other things, create transactions for this merchant.

    How will payouts work for this merchant?

    After creating a merchant, it is immediately possible to start a transaction. Transactions can be created and successfully paid to a merchant of whom only the e-mail address has been verified. However funds cannot be paid out to the merchant until they have successfully finished the onboarding process and its compliance requirements.

    Quickstart

    This quickstart will show you the most minimalistic requests to create a merchant and a transaction. By following this quickstart, you will be able to create and fully verify a merchant, and start a transaction for this merchant.

    Create a merchant

    Every user who sells a product or service and is earning money while doing this, needs to be onboarded as a merchant. This can either be a business, or consumer. Creating and onboarding merchants can be done using our Seamless Merchant API

    Creating a merchant contains of 3 steps:

    1. Creating the merchant, using country of origin, email address, phonenumber and CoC number (in case of a business merchant).
    2. Create a bank_account.
    3. Let the merchant verify his/her bank_account and other open requirements.

    The first step is necessary for creating and receiving the merchant_uid. As soon as this step is completed, transactions can be started using this identifier. Please note that payouts only take place when the merchant is verified by our compliance department. Steps 2 and 3 can be completed at a later moment in time. For example, as soon as a merchant has money waiting to be received. Our advice is to keep the onboarding process as easy and accessible as possible, and move steps that are not necessary at the moment of creation to a future moment.

    Step 1 - Create the merchant

    Example request - Create a consumer merchant

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

    Example request - Create a business merchant

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

    As you gather all information on your platform, the user will not have to leave the platform in order to create a merchant account at OPP. You are able to seamlessly provide information that is needed for the onboarding. As soon as the user completes all the steps at your platform, and you create the merchant, a unique merchant identifier will be generated (merchant_uid: mer_xxxxxxxx) and shared with you via the response. This identifier needs to be saved and will for example be used to create transactions for this merchant.

    Step 2 - Create a bank_account

    Example request - Create a bank_account

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

    You need to create a bank_account object. Contrary to what it suggests, you will not have to provide bank details of the merchant here. This is merely an object, after which the merchant can connect his/her bank account to this object. After that, we can connect this bank_account object to the payouts of this merchant.

    Step 3 - Verification

    Example response - Retrieve a merchant

    {
        "uid": "{{merchant_uid}}",
        "object": "merchant",
        ...
        "compliance": {
            "level": 400,
            "status": "unverified",
            "overview_url": "https://sandbox.onlinebetaalplatform.nl/en/{{partner_slug}}/{{merchant_uid}}/15c0bdb17283475ec5f274cad0a2a0245dda11ff/overview",
            "requirements": [
                {
                    "type": "contact.verification.required",
                    "status": "unverified",
                    "object_type": "contact",
                    "object_uid": "{{contact_uid}}",
                    "object_url": "https://api-sandbox.onlinebetaalplatform.nl/v1/merchants/{{merchant_uid}}/contacts/{{contact_uid}}",
                    "object_redirect_url": "https://sandbox.onlinebetaalplatform.nl/nl/testindividual/merchants/{{merchant_uid}}/verificatie/contactgegevens/{{contact_uid}}/e23405b8d2fc98d6fef9a5999dde0a0a7db26f6a"
                },
                {
                    "type": "bank_account.verification.required",
                    "status": "unverified",
                    "object_type": "bank_account",
                    "object_uid": "{{bank_account_uid}}",
                    "object_url": "https://api-sandbox.onlinebetaalplatform.nl/v1/merchants/{{merchant_uid}}/bank_accounts/{{bank_account_uid}}",
                    "object_redirect_url": "https://sandbox.onlinebetaalplatform.nl/nl/testindividual/merchants/{{merchant_uid}}/verificatie/bankgegevens/{{bank_account_uid}}/fc0b7c490a5021069ae04b50a1a2ee4b2be1b691"
                }
            ]
        },
        ...
    }
    

    Once steps 1 and 2 are finished, you should retrieve the merchant object using GET https://api-sandbox.onlinebetaalplatform.nl/v1/merchants/
    {{merchant_uid}}
    . In this object, you will find a compliance object. Depending on the compliance level, you will find a list with all open requirements. Redirect the user to the overview_url, in order to let him/her verify all outstanding requirements.

    Below you can find an example of an overview_url.

    Create a transaction

    Example request - Create a transaction

    POST https://api-sandbox.onlinebetaalplatform.nl/v1/transactions
    {
        "merchant_uid": "{{merchant_uid}}",
        "products": [
            {
                "name": "Test",
                "price": 100,
                "quantity": 1
            }
        ],
        "return_url": "https://platform.example.com/return/",
        "notify_url": "https://platform.example.com/notify/",
        "total_price": 100
    }
    

    Example response

    {
        "uid": "{{transaction_uid}}",
        "object": "transaction",
        ...
        "redirect_url": "https://onlinebetaalplatform.nl/nl/betalen/?trx={{transaction_uid}}",
        ...
    }
    

    Transactions are created using the Transaction API. Transactions can be created as soon as a merchant_uid is known. After creating a transaction, the buyer needs to be redirected to the redirect_url. After a (un)successful payment, or cancellation, the buyer will always be redirected to the return_url. In addition, a partner_fee can be provided. This fee will then be subtracted from the total price and paid to you as a split.

    Transactions can have many different statuses. The different statuses and their explanation can be found here. As soon as the status of a transaction changes, we will send a POST to the notify_url

    An example of the redirect_url can be found below.

    Compliance

    {
        "uid": "{{merchant_uid}}",
        "object": "merchant",
        ...
        "compliance": {
            "level": 200, 
            "status": "unverified", 
            
    "requirements": [ { "type": "bank_account.verification.required", "status": "unverified", "object_uid": {{bank_account_uid}}, "object_type": "bank_account", "object_url": "https://api-sandbox.onlinebetaalplatform.nl/v1/merchants/...", "object_redirect_url": https://sandbox.onlinebetaalplatform.nl/... } ]
    }, ... }

    A merchant can be a consumer or a business entity and each has its own set of KYC (Know Your Customer) compliance requirements. OPP is obliged to do this KYC check, to see if the consumer or business has been in touch with illegal activities, like money laundring or finance of terrorism, or other frauds.

    The merchant object contains the ‘compliance’ object. This object contains details on the merchant's current compliance level (1) , compliance status (2) and lists the compliance requirements (3) the merchant should meet to get a verified compliance status. An unverified compliance status results in not being able to receive payouts.

    Receive the merchant object using this call: GET https://api.onlinebetaalplatform.nl/v1/merchants/{{merchant_uid}}

    Compliance levels

    {
        "uid": "{merchant_uid}",
        "object": "merchant",
        ...
        "compliance": {
            "level": 200,
            "status": "unverified",
            "requirements": [
                {
                    "type": "bank_account.verification.required",
                    "status": "unverified",
                    "object_uid": bnk_1a2b3c4d5e6f,
                    "object_type": "bank_account",
                    "object_url": "https://api-sandbox.onlinebetaalplatform.nl/v1/merchants/...", 
                    "object_redirect_url": https://sandbox.onlinebetaalplatform.nl/...
                }
            ]
        },
        ...
    }
    

    The compliance levels determine which compliance requirements the merchant should meet.

    Compliance levels
    100

    Merchant has been created but does not yet have a linked bank account. Transactions can be created on level 100 but cannot yet be paid out to the merchant.

    200
    Low KYC

    Once the partner creates a bank account object for the merchant, the compliance level of the merchant is updated to 200. OPP will review the bank account information provided and once approved the merchant can receive payouts of the money on the bank account.

    Thresholds: the standard thresholds for Level 200 merchants are € 250,- in one transaction or € 1.500,- in lifetime volume. After which the merchant is required to identify itself before payouts can be reactivated. This threshold can be adjusted based on the risk profile and assessment of the platform or marketplace.

    400
    High KYC

    If the merchant passes the threshold the compliance level is updated to 400 and is obliged to confirm his or her identity. The merchant can do this by uploading an identity document or by performing a local identification method (such as iDIN or itsme).

    Compliance status

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

    Compliance statuses
    Unverified Merchant is unverified and unable to receive payouts. Merchant should meet all unverified ‘compliance requirements’ to get to the ‘verified’ state. Unverified means that no verifications have been done yet, or delivered verifications have been disapproved.
    Pending Merchant compliance status is pending and is unable to receive payouts. OPP is currently reviewing the merchant's updated ‘compliance requirements’.
    Verified Merchant compliance status is verified and the merchant is able to receive payouts.

    Compliance requirements

    Each compliance requirement states the compliance requirement type and details of the related object. A merchant can be redirect to object_redirect_url in order to get to the whitelabel OPP page where the required actions will be explained and can be finalized. It is also possible to provide your own redirect URL and seamlessly integrate these compliance requirement steps.

    Compliance requirements
    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.
    contact.phonenumber.required No phonenumber available, while at least one is required.
    contact.phonenumber.verification.required No verified phonenumber available, while at least one is required.
    coc_extract.required ( BUSINESS ONLY! ) Compliance does not have a state of the art extract, and will trigger the option to deliver it.
    organization_structure.required ( BUSINESS ONLY! ) Compliance cannot create a clear view on the organization structure, and will trigger the option to deliver it.
    ubo.required ( BUSINESS ONLY! ) Compliance found that an UBO is required, and will trigger the option to verify.
    ubo.verification.required ( BUSINESS ONLY! ) The merchant has to fill / verify all UBO’s.

    Merchant onboarding

    Every user who sells a product or service and is earning money while doing this, needs to be onboarded as a merchant. This can either be a business, or consumer. We will seperate both flows, because a business merchant requires more additional information than a consumer merchant does.

    Consumer onboarding

    For onboarding a consumer merchant we offer a tiered verification process (Low KYC and High KYC). Low KYC means that only a verified bank account is needed in order to be able to receive payouts. The standard thresholds for Low KYC merchants are € 250,- in one transaction or € 1.500,- in lifetime volume. If one of these thresholds is reached the consumer is required to identify him- or herself before payouts can be reactivated. The threshold can be adjusted based on the risk profile and assessment of the platform or marketplace.

    As soon as a merchant is created, you can start doing transactions. As a partner, you are in charge of when the merchant fulfills the verification requirements. In many cases the partner wants the merchant to perform the least number of actions as possible in the beginning, but in some cases the partner may wish to force the consumer to perform all KYC steps before transactions can be started. Both options are possible, and completely up to you.

    The four steps of consumer merchant creation are:

    1. Create a consumer merchant.
    2. Create a bank_account.
    3. Verify consumer bank account (Low KYC).
    4. Consumer ID verification (High KYC).

    1. Create a consumer merchant

    Example request:

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

    Example response:

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

    With the example request shown at the right you can create a consumer merchant. As a partner you will receive the Merchant Object with compliance.level 100 as a response.

    The minimal required fields are: country, emailaddress, phone and notify_url. The emailaddress is our unique identifier. You cannot create multiple merchants with the same email address. The notify_url is the webhook URL used by OPP for notifications of status changes.

    The merchant object contains three fields that you will need to save in your database:

    Ofcourse, other values can be saved in your database as well, if that is preferred by you. These three values are important for the flows in your platform.

    After the creation of the merchant, it is immediately possible as a partner to create transactions for this merchant. The funds of the paid transactions cannot (yet) be paid out because the merchant does not yet have a linked bank account.

    2. Create a bank account - Consumer

    Example request:

    POST https://api-sandbox.onlinebetaalplatform.nl/v1/merchants/{{merchant_uid}}/bank_accounts
    {
        "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
        "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
    }
    

    With the request at the right you can create an 'empty' bank account for the merchant. This 'empty' bank account serves as a container that needs to be filled with verified bank account information. The bank account is created with a status of 'new' and needs to be verified by the merchant.

    As soon as a bank account has been created for the merchant, the compliance.level of the merchant will immediately be increased to 200. You will receive the merchant.compliance_level.changed notification of this change on the merchant's specified notify_url. Because the level has been increased, you can now also find the bank_acount.verification.required within the compliance.requirements. The verification_url that can be found in the response of the bank_account object is the same URL that is detailed in the compliance requirement.

    Optionally, you can save the UID and verification_url in your database.

    3. Verify consumer bank account

    In the previous step we created an 'empty' bank account for the consumer merchant. To verify the bank account, we can follow three routes:

    1. Use the verification_url.
    2. Use the seamless bank integration.
    3. Perform a transaction (buyer onboarding).

    In all cases OPP will send a notification right after the verification took place. The compliance requirement bank_account.verification.required and the bank account status will be pending until OPP has performed a compliance check.

    3.1. Verify the bank account by redirecting the merchant to the verification_url.

    bank_account object:

    {
        "uid": "{{bank_account_uid}}",
        "object": "bank_account",
        "created": 1554200096,
        "updated": 1554200096,
        "verified": null
         "verification_url": "https://onlinebetaalplatform.nl/nl/{{partner_name}}/merchants/{{merchant_uid}}/verificatie/bankgegevens/{{bank_account_uid}}/7a8d3c308b0739ef96320720017d070533912548",
        "status": "new",
        ...
    }
    

    merchant compliance object:

    {
        "uid": "{{merchant_uid}}",
        "object": "merchant",
        ...
        "compliance": {
            "level": 200,
            "status": "unverified",
            "overview_url": "https://sandbox.onlinebetaalplatform.nl/en/{{partner_slug}}/{{merchant_uid}}/15c0bdb17283475ec5f274cad0a2a0245dda11ff/overview",
            "requirements": [
                {
                    "type": "bank_account.verification.required",
                    "status": "unverified",
                    "object_type": "bank_account",
                    "object_uid": "{{bank_account_uid}}",
                    "object_url": "https://api-sandbox.onlinebetaalplatform.nl/v1/merchants/{{merchant_uid}}/bank_accounts/{{bank_account_uid}}",
                    "object_redirect_url": "https://sandbox.onlinebetaalplatform.nl/nl/{{partner_name}}/merchants/{{merchant_uid}}/verificatie/bankgegevens/{{bank_account_uid}}/7a8d3c308b0739ef96320720017d070533912548"
                }
            ]
        },
        ...
    }
    

    You can find the verification_url in two places: the bank_account object, and the merchant compliance.requirements.

    Bank account object

    Find the verification_url and redirect the merchant to this link to verify the bank account.

    Merchant compliance requirements

    Find the requirement with type bank_account.verification.required and redirect the merchant to the object_redirect_url.

    An example of this url can be found below.

    3.2 Verify bank seamlessly by redirecting merchant directly to bank / payment method.

    In case of Belgium and The Netherlands, we provide a direct link with Bancontact and iDEAL, providing a seamless integration, so that merchants do not see our bank verification screen. To do this, first find the verification_url by using on of the methods in 3.1. After that, append additional parameters to the url. Then redirect the user to the new url.

    Additional parameters
    payment_method one of ideal or bcmc
    issuer required if payment_method is ideal, one of the SWIFT codes of the iDEAL issuers list.
    https://onlinebetaalplatform.nl/nl/{{partner}}/merchants/{{merchant_uid}}/
        verificatie/bankgegevens/
        {{bank_account_uid}}/{{hash}}?payment_method=ideal&issuer=INGBNL2A
    

    3.3. Verify the bank account by performing a transaction.

    Example Request:

    POST https://api-sandbox.onlinebetaalplatform.nl/v1/transactions
    {
        "merchant_uid": "{{seller_merchant_uid}}",
        "products": [
            {
                "name": "Test",
                "price": 100,
                "quantity": 1
            }
        ],
        "return_url": "https://platform.example.com/return/",
        "notify_url": "https://platform.example.com/notify/",
        "total_price": 100,
        "verification_merchant_uid": "{{buyer_merchant_uid}}",
        "metadata":
          {
            "external_id": "2015486"
          }
    }
    

    OPP also supports the ability to verify a merchant's bank account when the merchant itself completes a transaction to another merchant. This can for example be used to perform buyer onboarding, when the buyer will be a seller at the platform as well. Another case is when you as a platform want to have a dynamic onboarding fee, that differs per merchant. In that case, the {{seller_merchant_uid}} will be your platform merchant.

    If the merchant does not yet exist, create a merchant and an 'empty' bank account for this merchant first. This allows you to set the right notify_url and other details. Do note that you do not have to redirect merchant to the bank_account verification_url. You may pass this new merchant's uid as a parameter to the Create Transaction API call using parameter verification_merchant_uid to verify the bank account via this transaction.

    The bank account will stay in a new state if this transaction is not successfully completed and will change to state pending if transaction is successfully completed, just like the regular bank account verification flow.

    Process of the approval OR disapproval

    The compliance team of OPP checks all new or updated verifications within 24 hours on working days and will either approve or disapprove the verification. Notifications are sent as soon as OPP has approved or disapproved the bank account.

    Approved:

    The bank account information has been approved and has received the status approved. The compliance requirement bank_account.verification.required has received the status verified and will no longer be visible within the merchant.compliance.requirements.

    Sent notifications
    merchant.compliance_requirement.status.changed
    status pending > verified
    bank_account.status.changed
    status pending > approved

    If the merchant has no other unverified or pending compliance.requirements, then merchant's compliance.status shall be updated from pending to verified. This change in status will also be sent by the following notification merchant.compliance_status.changed.

    - OR -

    Disapproved:

    The bank account information has been disapproved and has received the status disapproved. The compliance requirement bank_account.verification.required has received the status unverified. Merchant is required to verify its bank details again, see step 3.1.

    Sent notifications
    merchant.compliance_requirement.status.changed
    status pending > unverified
    bank_account.status.changed
    status pending > disapproved

    If the merchant's compliance.status was pending, this will be changed to unverified. This change in status will also be sent by the following notification merchant.compliance_status.changed.

    4. Verify consumer identity

    As a partner, you are free to decide at what moment in time you would like your merchants to complete their identity verification. We distinguish two different paths to do this:

    1. The merchant has not yet reached compliance level 400.
    2. The merchant has reached compliance level 400.

    In both cases, identification provided must contain the same name as the bank account holder name.

    4.1. The merchant has not yet reached compliance level 400.

    Example request

    GET https://api-sandbox.onlinebetaalplatform.nl/v1/merchants/{{merchant_uid}}?expand[]=contacts
    

    Example response

    {
        "livemode": false,
        "uid": "{{merchant_uid}}",
        "object": "merchant",
        ...
        "contacts": [
            {
                "uid": "con_59c4c3b3493d",
                "object": "contact",
                "created": 1604404358,
                "updated": 1604404358,
                "verified": null,
                "status": "unverified",
                "verification_url": "https://sandbox.onlinebetaalplatform.nl/en/{{partner_slug}}/merchants/{{merchant_uid}}/verifications/contact-details/{{contact_uid}}/273db5ea58b3ce0fb061608054f32efd258b954d",
                "type": "representative",
                "title": null,
                "name_initials": null,
                "name_first": null,
                "name_last": null,
                "names_given": null,
                "birthdate": null,
                "partner_name_last": null,
                "emailaddresses": [],
                "phonenumbers": []
            }
        ],
        ...
    }
    

    As long as the merchant has not yet reached a compliance level of 400, the identity verification is not obliged by OPP. In case you would want to already fulfill the contact verification, you can do so by using the verification_url in the merchant.contact object.

    Find a request and response at the right.

    After verification, the merchant will be updated, and the platform will receive the notifications that go with these updates. The compliance level will raise to 400. This means that from the first moment an identity got uploaded, we need to have a verified identity in order to do payouts. There is no way to go back to compliance level 200.

    An example of the verification url can be found below.

    4.2. The merchant has reached compliance level 400.

    Once the compliance.level of the merchant has reached 400, identity verification is required. There are three ways to provide OPP this identity. You can

    1. Use the verification_url as used in 4.1.
    2. Redirect the merchant to the white-label object_redirect_url.
    3. Verify the identification seamlessly by redirecting directly to a local identification method (such as iDIN or itsme).

    4.2.2. Redirect merchant to white-label object_redirect_url.
    {
        "uid": "{merchant_uid}",
        "object": "merchant",
        ...
        "compliance": {
            "level": 400, 
            "status": "unverified",
            "overview_url": "https://sandbox.onlinebetaalplatform.nl/en/{{partner_slug}}/{{merchant_uid}}/e1e477f8c7e6e688c8c752e5e7a4bad448f52a67/overview"
            "requirements": [
            {
        "type": "contact.verification.required",
        "status": "unverified",
        "object_uid": {{contact_uid}},
        "object_type": "contact",
        "object_url": "https://api-sandbox.onlinebetaalplatform.nl/v1/merchants/...", 
        "object_redirect_url": https://sandbox.onlinebetaalplatform.nl/...
    }
            ]
        },
        ...
    }
    

    Within the Merchant Object you will find the compliance requirement contact.verification.required. Find the object_redirect_url and redirect the merchant to this url to identify him/herself. Note that this is the same url as the verification_url of 4.1.

    OPP will send a notification immediately after the identification took place. The compliance.requirement contact.verification.required and the contact status will be pending until OPP performed a compliance check.

    4.2.3. Seamlessly identify merchant by redirecting directly to a local idenfication method.

    You can skip the whitelabel screens and immediately redirect the user to a local identification method if this is available in your country. Doing this requires three steps:

    Additional parameters
    verification_type One of idin or itsme
    issuer required if verification_type is idin, one of the SWIFT codes of the iDIN issuers list.
    https://onlinebetaalplatform.nl/nl/{{partner}}/merchants/{{merchant_uid}}/
        verificatie/contactgegevens
        /{{contact_uid}}/{{hash}}?verification_type=idin&issuer=INGBNL2A
    

    OPP will send a notification immediately after the identification took place. The compliance.requirement contact.verification.required and the contact status will be pending until OPP performed a compliance check.

    Process of the approval OR disapproval

    The compliance team of OPP checks all new or updated verifications within 24 hours on working days and will either approve or disapprove the verification. Notifications are sent as soon as OPP has approved or disapproved the identification.

    Approved:

    The identification has been approved and has received the status verified. The compliance requirement contact.verification.required has been updated with the status verified and is no longer visible within the merchant.compliance.requirements.

    Sent notifications
    merchant.compliance_requirement.status.changed
    status pending > verified
    contact.status.changed
    status pending > verified

    If the merchant has no other unverified or pending compliance.requirements, merchant's compliance.status will be updated from pending to verified. This change in status will also be sent by the following notification merchant.compliance_status.changed.

    - OR -

    Disapproved:

    The identification has been disapproved and has received the status unverified. The compliance requirement contact.verification.required has been updated with the status unverified. The merchant is required to identify itself again, see step 1.

    Sent notifications
    merchant.compliance_requirement.status.changed
    status pending > unverified
    contact.status.changed
    status pending > unverified

    If the merchant's compliance.status was pending, this will be updated to unverified. This change in status will also be sent by the following notification merchant.compliance_status.changed.

    Business onboarding

    As a partner you can create a business merchant using the 5 steps described below. A business merchant must always complete the High KYC.

    As soon as a merchant is created, you can start doing transactions. As a partner, you are in charge of when the merchant fulfills the verification requirements. In many cases the partner wants the merchant to perform the least number of actions as possible in the beginning, but in some cases the partner may wish to force the business to perform all KYC steps before transactions can be started. Both options are possible, and completely up to you.

    The five steps of business merchant creation are:

    1. Create a business merchant.
    2. Create a bank_account.
    3. Verify business bank account.
    4. Business representative verification.
    5. Fulfill other requirements (not required in all cases).

    1. Create a business merchant

    Example request:

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

    Example response:

    
    {
        "uid": "{{merchant_uid}}",
        "object": "merchant",
        "created": 1604661043,
        "updated": 1604661043,
        "status": "pending",
        "compliance": {
            "level": 400,
            "status": "unverified",
            "overview_url": "https://sandbox.onlinebetaalplatform.nl/en/{{partner_slug}}/{{merchant_uid}}/{{hash}}/overview",
            "requirements": [
                {
                    "type": "bank_account.required",
                    "status": "unverified",
                    "object_type": "bank_account",
                    "object_uid": null,
                    "object_url": "https://api-sandbox.onlinebetaalplatform.nl/v1/merchants/{{merchant_uid}}/bank_accounts",
                    "object_redirect_url": null
                },
                {
                    "type": "contact.phonenumber.required",
                    "status": "unverified",
                    "object_type": "contact_phonenumber",
                    "object_uid": null,
                    "object_url": null,
                    "object_redirect_url": "https://sandbox.onlinebetaalplatform.nl/en/{{partner_slug}}/merchants/{{merchant_uid}}/verifications/phonenumber-form/{{contact_uid}}/{{hash}}"
                },
                {
                    "type": "contact.verification.required",
                    "status": "unverified",
                    "object_type": "contact",
                    "object_uid": "{{contact_uid}}",
                    "object_url": "https://api-sandbox.onlinebetaalplatform.nl/v1/merchants/{{merchant_uid}}/contacts/con_e9e5e1b7bd23",
                    "object_redirect_url": "https://sandbox.onlinebetaalplatform.nl/en/{{partner_slug}}/merchants/{{merchant_uid}}/verifications/contact-details/{{contact_uid}}/{{hash}}"
                }
            ]
        },
        "type": "business",
        "coc_nr": "12345678",
        ...
    }
    

    With the example request shown below you can create a business merchant. As a partner you will receive the Merchant Object with compliance.level 400 as a response.

    The minimal required fields are: coc_nr, type, country, emailaddress, phone and notify_url. The emailaddress is our unique identifier. You cannot create multiple merchants with the same email address. The notify_url is the webhook URL used by OPP for notifications of status changes.

    Within the Merchant Object you will also find the Merchant UID, this is the unique identifier of the created merchant and as a partner you will need to save the Merchant UID and use it to, amongst other things, create transactions for this merchant. It is therefore required to store the Merchant UID within your own application.

    The notify_url is the webhook URL used by OPP for notifications of status changes.

    The merchant object contains three fields that you will need to save in your database:

    Ofcourse, other values can be saved in your database as well, if that is preferred by you. These three values are important for the flows in your platform.

    After the creation of the merchant, it is immediately possible as a partner to create transactions for this merchant. The funds of the paid transactions cannot (yet) be paid out because the merchant still has outstanding compliance requirements.

    2. Create a bank account - Business

    Example request:

    POST https://api-sandbox.onlinebetaalplatform.nl/v1/merchants/{{merchant_uid}}/bank_accounts
    {
        "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
        "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
    }
    

    With the request at the right you can create an 'empty' bank account for the merchant. This 'empty' bank account serves as a container that needs to be filled with verified bank account information. The bank account is created with a status of 'new' and needs to be verified by the merchant.

    Now that the required bank account has been created, you will receive a notification with type merchant.compliance_requirement.status.changed. You can now also find the bank_acount.verification.required within the compliance.requirements. The verification_url that can be found in the response of the bank_account object is the same URL that is detailed in the compliance requirement.

    Optionally, you can save the UID and verification_url in your database.

    3. Verify business bank account

    In the previous step we created an 'empty' bank account for the business merchant. To verify the bank account, we can follow three routes:

    1. Use the verification_url.
    2. Use the seamless bank integration.
    3. Perform a transaction (buyer onboarding).

    In all cases OPP will send a notification right after the verification took place. The compliance requirement bank_account.verification.required and the bank account status will be pending until OPP has performed a compliance check.

    3.1. Verify the bank account by redirecting the merchant to the verification_url.

    bank_account object:

    {
        "uid": "{{bank_account_uid}}",
        "object": "bank_account",
        "created": 1554200096,
        "updated": 1554200096,
        "verified": null
         "verification_url": "https://onlinebetaalplatform.nl/nl/{{partner_name}}/merchants/{{merchant_uid}}/verificatie/bankgegevens/{{bank_account_uid}}/7a8d3c308b0739ef96320720017d070533912548",
        "status": "new",
        ...
    }
    

    merchant compliance object:

    {
        "uid": "{{merchant_uid}}",
        "object": "merchant",
        ...
        "compliance": {
            "level": 200,
            "status": "unverified",
            "overview_url": "https://sandbox.onlinebetaalplatform.nl/en/{{partner_slug}}/{{merchant_uid}}/15c0bdb17283475ec5f274cad0a2a0245dda11ff/overview",
            "requirements": [
                {
                    "type": "bank_account.verification.required",
                    "status": "unverified",
                    "object_type": "bank_account",
                    "object_uid": "{{bank_account_uid}}",
                    "object_url": "https://api-sandbox.onlinebetaalplatform.nl/v1/merchants/{{merchant_uid}}/bank_accounts/{{bank_account_uid}}",
                    "object_redirect_url": "https://sandbox.onlinebetaalplatform.nl/nl/{{partner_name}}/merchants/{{merchant_uid}}/verificatie/bankgegevens/{{bank_account_uid}}/7a8d3c308b0739ef96320720017d070533912548"
                }
            ]
        },
        ...
    }
    

    You can find the verification_url in two places: the bank_account object, and the merchant compliance.requirements.

    Bank account object

    Find the verification_url and redirect the merchant to this link to verify the bank account.

    Merchant compliance requirements

    Find the requirement with type bank_account.verification.required and redirect the merchant to the object_redirect_url.

    An example of this url can be found below.

    3.2 Verify bank seamlessly by redirecting merchant directly to bank / payment method.

    In case of Belgium and The Netherlands, we provide a direct link with Bancontact and iDEAL, providing a seamless integration, so that merchants do not see our bank verification screen. To do this, first find the verification_url by using on of the methods in 3.1. After that, append additional parameters to the url. Then redirect the user to the new url.

    Additional parameters
    payment_method one of ideal or bcmc
    issuer required if payment_method is ideal, one of the SWIFT codes of the iDEAL issuers list.
    https://onlinebetaalplatform.nl/nl/{{partner}}/merchants/{{merchant_uid}}/
        verificatie/bankgegevens/
        {{bank_account_uid}}/{{hash}}?payment_method=ideal&issuer=INGBNL2A
    

    3.3. Verify the bank account by performing a transaction.

    Example Request:

    POST https://api-sandbox.onlinebetaalplatform.nl/v1/transactions
    {
        "merchant_uid": "{{seller_merchant_uid}}",
        "products": [
            {
                "name": "Test",
                "price": 100,
                "quantity": 1
            }
        ],
        "return_url": "https://platform.example.com/return/",
        "notify_url": "https://platform.example.com/notify/",
        "total_price": 100,
        "verification_merchant_uid": "{{buyer_merchant_uid}}",
        "metadata":
          {
            "external_id": "2015486"
          }
    }
    

    OPP also supports the ability to verify a merchant's bank account when the merchant itself completes a transaction to another merchant. This can for example be used to perform buyer onboarding, when the buyer will be a seller at the platform as well. Another case is when you as a platform want to have a dynamic onboarding fee, that differs per merchant. In that case, the {{seller_merchant_uid}} will be your platform merchant.

    If the merchant does not yet exist, create a merchant and an 'empty' bank account for this merchant first. This allows you to set the right notify_url and other details. Do note that you do not have to redirect merchant to the bank_account verification_url. You may pass this new merchant's uid as a parameter to the Create Transaction API call using parameter verification_merchant_uid to verify the bank account via this transaction.

    The bank account will stay in a new state if this transaction is not successfully completed and will change to state pending if transaction is successfully completed, just like the regular bank account verification flow.

    Process of the approval OR disapproval

    The compliance team of OPP checks all new or updated verifications within 24 hours on working days and will either approve or disapprove the verification. Notifications are sent as soon as OPP has approved or disapproved the bank account.

    Approved:

    The bank account information has been approved and has received the status approved. The compliance requirement bank_account.verification.required has received the status verified and will no longer be visible within the merchant.compliance.requirements.

    Sent notifications
    merchant.compliance_requirement.status.changed
    status pending > verified
    bank_account.status.changed
    status pending > approved

    If the merchant has no other unverified or pending compliance.requirements, then merchant's compliance.status shall be updated from pending to verified. This change in status will also be sent by the following notification merchant.compliance_status.changed.

    - OR -

    Disapproved:

    The bank account information has been disapproved and has received the status disapproved. The compliance requirement bank_account.verification.required has received the status unverified. Merchant is required to verify its bank details again, see step 3.1.

    Sent notifications
    merchant.compliance_requirement.status.changed
    status pending > unverified
    bank_account.status.changed
    status pending > disapproved

    If the merchant's compliance.status was pending, this will be changed to unverified. This change in status will also be sent by the following notification merchant.compliance_status.changed.

    4. Business representative verification

    Within the Merchant Object you will find the compliance requirement contact.verification.required. The representative of the business is required to identify him or herself.

    There are three ways to provide OPP this identity. You can

    1. Use the verification_url.
    2. Redirect the merchant to the white-label object_redirect_url.
    3. Verify the identification seamlessly by redirecting directly to a local identification method (such as iDIN or itsme).

    4.1. Use the whitelabel verification url.

    Example request

    GET https://api-sandbox.onlinebetaalplatform.nl/v1/merchants/{{merchant_uid}}?expand[]=contacts
    

    Example response

    {
        "livemode": false,
        "uid": "{{merchant_uid}}",
        "object": "merchant",
        ...
        "contacts": [
            {
                "uid": "con_59c4c3b3493d",
                "object": "contact",
                "created": 1604404358,
                "updated": 1604404358,
                "verified": null,
                "status": "unverified",
                "verification_url": "https://sandbox.onlinebetaalplatform.nl/en/{{partner_slug}}/merchants/{{merchant_uid}}/verifications/contact-details/{{contact_uid}}/273db5ea58b3ce0fb061608054f32efd258b954d",
                "type": "representative",
                "title": null,
                "name_initials": null,
                "name_first": null,
                "name_last": null,
                "names_given": null,
                "birthdate": null,
                "partner_name_last": null,
                "emailaddresses": [],
                "phonenumbers": []
            }
        ],
        ...
    }
    

    In case you would want to fulfill the contact verification using the contact object, you can do so by using the verification_url in the merchant.contact object. Find a request and response at the right.

    After verification, the merchant will be updated, and the platform will receive the notifications that go with these updates.

    An example of the verification url can be found below.

    4.2. Redirect merchant to white-label object_redirect_url.

    {
        "uid": "{merchant_uid}",
        "object": "merchant",
        ...
        "compliance": {
            "level": 400, 
            "status": "unverified",
            "overview_url": "https://sandbox.onlinebetaalplatform.nl/en/{{partner_slug}}/{{merchant_uid}}/e1e477f8c7e6e688c8c752e5e7a4bad448f52a67/overview"
            "requirements": [
            {
        "type": "contact.verification.required",
        "status": "unverified",
        "object_uid": {{contact_uid}},
        "object_type": "contact",
        "object_url": "https://api-sandbox.onlinebetaalplatform.nl/v1/merchants/...", 
        "object_redirect_url": https://sandbox.onlinebetaalplatform.nl/...
    }
            ]
        },
        ...
    }
    

    Within the Merchant Object you will find the compliance requirement contact.verification.required. Find the object_redirect_url and redirect the merchant to this url to identify him/herself. Note that this is the same url as the verification_url of 4.1.

    OPP will send a notification immediately after the identification took place. The compliance.requirement contact.verification.required and the contact status will be pending until OPP performed a compliance check.

    4.3. Seamlessly identify merchant by redirecting directly to a local idenfication method.

    You can skip the whitelabel screens and immediately redirect the user to a local identification method if this is available in your country. Doing this requires three steps:

    Additional parameters
    verification_type One of idin or itsme
    issuer required if verification_type is idin, one of the SWIFT codes of the iDIN issuers list.
    https://onlinebetaalplatform.nl/nl/{{partner}}/merchants/{{merchant_uid}}/
        verificatie/contactgegevens
        /{{contact_uid}}/{{hash}}?verification_type=idin&issuer=INGBNL2A
    

    OPP will send a notification immediately after the identification took place. The compliance.requirement contact.verification.required and the contact status will be pending until OPP performed a compliance check.

    Process of the approval OR disapproval

    The compliance team of OPP checks all new or updated verifications within 24 hours on working days and will either approve or disapprove the verification. Notifications are sent as soon as OPP has approved or disapproved the identification.

    Approved:

    The identification has been approved and has received the status verified. The compliance requirement contact.verification.required has been updated with the status verified and is no longer visible within the merchant.compliance.requirements.

    Sent notifications
    merchant.compliance_requirement.status.changed
    status pending > verified
    contact.status.changed
    status pending > verified

    If the merchant has no other unverified or pending compliance.requirements, merchant's compliance.status will be updated from pending to verified. This change in status will also be sent by the following notification merchant.compliance_status.changed.

    - OR -

    Disapproved:

    The identification has been disapproved and has received the status unverified. The compliance requirement contact.verification.required has been updated with the status unverified. The merchant is required to identify itself again, see step 1.

    Sent notifications
    merchant.compliance_requirement.status.changed
    status pending > unverified
    contact.status.changed
    status pending > unverified

    If the merchant's compliance.status was pending, this will be updated to unverified. This change in status will also be sent by the following notification merchant.compliance_status.changed.

    5. Fulfill other requirements

    A business merchant might have several other compliance requirements to fulfill:

    5.1. Contact phone verification

    phone number required

        "uid": "{{merchant_uid}}",
        "object": "merchant",
        ...
        "compliance": {
            "level": 400,
            "status": "unverified",
            "overview_url": "https://sandbox.onlinebetaalplatform.nl/en/{{partner_slug}}/{{merchant_uid}}/feabfd98b2a9d246a6e33742f92af061059b9f81/overview",
            "requirements": [
                {
                    "type": "contact.phonenumber.required",
                    "status": "unverified",
                    "object_type": "contact_phonenumber",
                    "object_uid": null,
                    "object_url": null,
                    "object_redirect_url": "https://sandbox.onlinebetaalplatform.nl/en/{{partner_slug}}/merchants/{{merchant_uid}}/verifications/phonenumber-form/{{contact_uid}}/feabfd98b2a9d246a6e33742f92af061059b9f81"
                }]
            ...
    

    seamlessly update the contact object

    POST https://api-sandbox.onlinebetaalplatform.nl/v1/merchants/{{merchant_uid}}/contacts/{{contact_uid}} \
    {
        "phonenumbers": [
                {
                    "phonenumber": "0612345678"
                }
            ]
    }
    

    Once the business merchant is created, you will find the contact.phonenumber.required requirement. OPP needs to have a phonenumber that belongs to the representative who verified in step 4. We are legally bound to have a verified phonenumber and email address from every merchant, in order to contact him/her when something is wrong with a transaction or verification. You as a partner have to deal with the verification of an email address before creating the merchant. For phone number verification, OPP provides the choice to do it yourself, or let us do the phonenumber verification.

    If you prefer to do verification yourself, you can choose to do this at the very beginning, before creating a merchant at our side, or when the merchant already exists. In the compliance requirements, find the object_redirect_url and redirect the representative of the business to this url. If you would prefer a seamless solution, you can do this by performing a POST on the contact object as can be seen on the right. Once the phonenumber is filled in, the merchant will be updated and the notifications will be send.

    In case you want OPP to do the verification, you will find a object_redirect_url in the contact.phonenumber.verification.required compliance requirement. Redirect the user to this url, where (s)he can fill in the phonenumber to be verified. A text message will be send to the phonenumber, which needs to be filled in to verify the phonenumber. The requirement will then disappear.

    5.2. UBO verification

    {
        "uid": "{{merchant_uid}}",
        "object": "merchant",
        ...
        "compliance": {
            "level": 400,
            "status": "unverified",
            "requirements": [
                {
        "type": "ubo.required",
        "status": "unverified",
        "object_uid": null,
        "object_type": "null",
        "object_url": "https://api-sandbox.onlinebetaalplatform.nl/v1/merchants/...", 
        "object_redirect_url": https://sandbox.onlinebetaalplatform.nl/...
    }
            ]
        },
        ...
    }
    

    OPP is obliged to trace all Ultimate Beneficial Owners (UBO) of a business entity. Legal business entities such as a B.V., GmbH or BVBA may have more than one UBO. When checking the business verifications, OPP determines whether the UBO verification is required. This verification is therefore never directly required when creating the merchant.

    An UBO is a natural person that has at least one of the following:

    As a partner, you can either choose to already provide us with the UBO information, or wait for the requirement to arrive. If our compliance department finds an UBO that has not registered yet, the compliance requirement ubo.required will be triggered. You can then choose to seamlessly provide the UBO information as described in the documentation, or redirect the merchant to the object_redirect_url to fulfill the requirement.

    An example of the redirect url can be found below:

    OPP will sent the following notifications when the UBO verification is required:

    Sent notifications
    merchant.compliance_status.changed
    status pending/verified > unverified

    Within the Merchant Object the compliance requirement ubo.required is available.

    The compliance team of OPP checks all new or updated verifications within 72 hours on working days and will either approve or disapprove the verification. Notifications are sent as soon as OPP has approved or disapproved the identification.

    5.3. Chamber of Commerce extract

    {
        "uid": "{{merchant_uid}}",
        "object": "merchant",
        ...
        "compliance": {
            "level": 400,
            "status": "unverified",
            "requirements": [
                {
                    "type": "coc_extract.required",
                    "status": "unverified",
                    "object_type": null,
                    "object_uid": null,
                    "object_url": null,
                    "object_redirect_url": "https://sandbox.onlinebetaalplatform.nl/en/{{partner_name}}/merchants/{{merchant_uid}}/verifications/coc-extract/feabfd98b2a9d246a6e33742f92af061059b9f81"
                }
            ]
        },
        ...
    }
    

    In case our compliance department is unable to retrieve the chamber of commerce extract from our registers, you might be required to deliver this to us. In that case, you will find the coc_extract.required type of requirement in your compliance requirements. Redirect the merchant to the object_redirect_url to fulfill this requirement.

    An example of the url can be found below:

    5.4. Organization structure

    {
        "uid": "{{merchant_uid}}",
        "object": "merchant",
        ...
        "compliance": {
            "level": 400,
            "status": "unverified",
            "requirements": [
                {
                    "type": "organization_structure.required",
                    "status": "unverified",
                    "object_type": null,
                    "object_uid": null,
                    "object_url": null,
                    "object_redirect_url": "https://sandbox.onlinebetaalplatform.nl/en/{{partner_name}}/merchants/{{merchant_uid}}/verifications/coc-extract/feabfd98b2a9d246a6e33742f92af061059b9f81"
                }
            ]
        },
        ...
    }
    

    In case our compliance department is unable to create on organization structure, e.g. because parts are unknown by the Chamber of Commerce, you might be required to deliver this to us. In that case, you will find the organization_structure.required type of requirement in your compliance requirements. Redirect the merchant to the object_redirect_url to fulfill this requirement. This is the same url as the Chamber of Commerce url.

    Dashboard

    Every partner has their own wishes and demands of what a correct dashboard looks like and which information it should contain. Because of this reason, we always advise our partners to build an own dashboard for merchants and for yourself. This has two great benefits:

    OPP always provides the possibility to use the dashboard created by OPP for you and your merchants, but experience teaches us that partners like the benefits and freedom of their own dashboard. The dashboard created by OPP is also built on our own APIs. Therefore, anything found in the dashboards of OPP can be retrieved via our APIs.

    We distinguish three differences:

    1. Merchant profile - What information of the merchant account should be visible?
    2. Merchant dashboard - What information about transactions and payouts should be visible?
    3. Partner dashboard - What information about merchants, transactions and payouts should be visible?

    Merchant Profile

    Besides all the information that your platform whishes to show on a profile page (like avatar, nickname, password management, etc), we advise you to take several of the OPP flows into consideration. We advise you to show the following on the merchant profile:

    Merchant information

    Merchant status

    Request

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

    Response

    {
        "uid": "{{merchant_uid}}",
        "object": "merchant",
        "created": 1554113700,
        "updated": 1554113700,
        "status": "live",
        "compliance": {
            "level": 400,
            "status": "unverified",
            "overview_url": "https://sandbox.onlinebetaalplatform.nl/en/{{partner_slug}}/{{merchant_uid}}/{{hash}}/overview",
            "requirements": [
                {
                    "type": "contact.phonenumber.required",
                    "status": "unverified",
                    "object_type": "contact_phonenumber",
                    "object_uid": null,
                    "object_url": null,
                    "object_redirect_url": "https://sandbox.onlinebetaalplatform.nl/en/{{partner_slug}}/merchants/{{merchant_uid}}/verifications/phonenumber-form/{{contact_uid}}/{{hash}}"
                },
                {
                    "type": "contact.verification.required",
                    "status": "unverified",
                    "object_type": "contact",
                    "object_uid": "{{contact_uid}}",
                    "object_url": "https://api-sandbox.onlinebetaalplatform.nl/v1/merchants/{{merchant_uid}}/contacts/{{contact_uid}}",
                    "object_redirect_url": "https://sandbox.onlinebetaalplatform.nl/en/{{partner_slug}}/merchants/{{merchant_uid}}/verifications/contact-details/{{contact_uid}}/{{hash}}"
                }
            ]
        },
    ...
    }
    

    You can retrieve the merchant status of the merchant using the call on the right. The status that can be found in the response is the merchant account status. Different meanings of the merchant status can be found here. Please note that you should have saved the merchant status in your database, so a GET request should not be necessary every time a merchant reaches his/her profile page.

    Merchant Compliance

    You can retrieve the merchant compliance status of the merchant by retrieving the merchant object. The compliance object withing the merchant object contains a status. This is the merchant compliance status, and shows whether the merchant is compliant and allowed to receive payouts. Different meanings of the merchant compliance status can be found here. Please note that you should have saved the merchant compliance status in your database, so a GET request should not be necessary every time a merchant reaches his/her profile page.

    Merchant Compliance Requirements

    In case the Merchant Compliance status is not verified, you should show the outstanding compliance requirements. Retrieve the merchant object, and find the compliance object. Within this object, you will find the requirements array. All possible requirements can be found here.

    Once you have retrieved the merchant object, the merchant can then choose to fulfill outstanding using his/her overview_url, or by using the object_redirect_url in the outstanding requirement.

    Bank Account

    Current IBAN We strongly advise you to show the current IBAN that is used for payouts, so that merchants always see what bank account of theirs is connected to our platform. You can find the currently connected IBAN by retrieving the merchant's profile. Unless the merchant is a company that has multiple affiliates which need seperated payouts, a merchant will only have one profile.

    Find the profile's bank_account, using

    GET https://api-sandbox.onlinebetaalplatform.nl/v1/merchants/{{merchant_uid}}?expand[]=profiles.bank_account

    In the profiles object, find the first profile and find the bank_account object. Within this object, you will find the account, which shows a masked account_iban and account_name. These values are the current bank account details that are used for the merchant's payouts.

        {
        "livemode": true,
        "uid": "{{merchant_uid}}",
        "object": "merchant",
        ...
        "profiles": [
            {
                "uid": "{{profile_uid}}",
                "object": "profile",
                "created": 1602071644,
                "updated": 1602071769,
                ...
                },
                "bank_account": {
                    "uid": "{{bank_account_uid}}",
                    "object": "bank_account",
                    ...
                    "status": "approved",
                    "account": {
                        "account_iban": "NL12***********123",
                        "account_name": "John Tester"
                    },
                    "bank": {
                        "bic": "{{BIC}}"
                    },
                    ...
                },
                ...
            }
        ],
    ...
    }
    

    Change IBAN

    Occasionally, merchants would like to change their IBAN for payouts, because of many reasons. Research has shown us that many partners get these questions, and forward them to the OPP support team. You can create a button to change the IBAN account for payouts as follows.

    Please note that whenever a new bank_account is created, the old bank_account cannot be used for payouts anymore. In case the merchant has second thoughts, and does want the first bank_account for payouts, (s)he will have to verify it again.

    Step 1: Check whether the merchant has a bank_account with status new

    First, we must find out whether the merchant already has a bank_account that can be filled. This is an important step, to keep your, and our database free of noise. Besides that, every time a new bank_account is created, the old bank_account will not be used for payouts anymore. This means that eventually, the merchant could not have a connected IBAN at all, if we do not keep track.

    Find the merchant bank_accounts, and filter the status new by using the following call:

        GET https://api-sandbox.onlinebetaalplatform.nl/v1/merchants/{{merchant_uid}}/bank_accounts?filter[status]=new
    

    Step 2.1: Merchant already has an outstanding bank_account

    Get the bank_account with status new, and redirect the user to the verification_url.

        {
        "uid": "{{bank_account_uid}}",
        "object": "bank_account",
        "created": 1554200096,
        "updated": 1554200096,
        "verified": null
        "verification_url": "https://onlinebetaalplatform.nl/nl/
         {{partner_name}}/merchants/{{merchant_uid}}/verificatie/
         bankgegevens/{{bank_account_uid}}/7a8d3c308b0739ef96320720017d070533912548",
        "status": "new",
        ...
    }
    

    After the merchant has gone through the process, you will receive a notification with type bank_account.status.changed. The status is now pending. After our compliance department has checked the new bank_account, you will again receive a notification with type bank_account.status.changed. This can either be approved, or disapproved. When approved, the bank_account will be used for payouts.

    Step 2.2: Merchant has no outstanding bank_account

    Create a new bank_account, as described in the Docs. Then redirect the user to the verification_url.

    After the merchant has gone through the process, you will receive a notification with type bank_account.status.changed. The status is now pending. After our compliance department has checked the new bank_account, you will again receive a notification with type bank_account.status.changed. This can either be approved, or disapproved. When approved, the bank_account will be used for payouts.

    Merchant Dashboard

    When providing payments on your platform, merchants would like to know what happens to their orders and payments, and what funds are available for payouts. In this chapter, we will guide you through providing all information that is required to build your own dashboard for the merchant. This dashboard consists of two parts:

    1. Settlements
    2. Transactions

    In this guide, we assume that you have registered all refund_uid’s and transaction_uid’s in your database, in order to relate them to the correct bookings and other related data.

    Settlements

    A settlement is the (current) balance of a merchant over a specific period of time. Settlement periods can be daily, weekly, or monthly. Every settlement has a specification for every profile a merchant has. Unless the merchant is a company with multiple affiliates which need seperated payouts, a merchant will only have one profile and thus one specification.

    The current settlement can be found using:

        GET https://api-sandbox.onlinebetaalplatform.nl/v1/merchants/{{merchant_uid}}/settlements?filter[status]=current&expand[]=specifications
    

    If the merchant has no current settlement, the server will respond with an empty list. Every specification has its own specification_uid. The specification is build up the same way as a settlement is. In case you want to specify the dashboard per profile, it is important to look at the different specifications, instead of the complete settlement. Important in this response is:

    A response might look like this:

    {
        "object": "list",
        "url": "/v1/merchants/{{merchant_uid}}/settlements",
        "has_more": false,
        "total_item_count": 1,
        "items_per_page": 10,
        "current_page": 1,
        "last_page": 1,
        "data": [
            {
                "uid": "{{settlement_uid}}",
                "object": "settlement",
                "created": 1606307019,
                "updated": 1606307020,
                "status": "current",
                "paid": null,
                "period_start": 1606258800,
                "period_end": 1606345199,
                "total_number_of_transactions": 2,
                "number_of_transactions": 1,
                "number_of_refunds": 1,
                "number_of_withdrawals": 0,
                "number_of_mandates": 0,
                "number_of_internal_transfers": 0,
                "number_of_multi_transactions": 0,
                "total_volume": 80,
                "transaction_volume": 100,
                "refund_volume": -20,
                "withdrawal_volume": 0,
                "mandate_volume": 0,
                "internal_transfer_volume": 0,
                "multi_transaction_volume": 0,
                "total_transaction_costs": 0,
                "transaction_costs": 0,
                "refund_costs": 0,
                "withdrawal_costs": 0,
                "mandate_costs": 0,
                "internal_transfer_costs": 0,
                "multi_transaction_costs": 0,
                "total_order_fees": 0,
                "total_refund_fees": 0,
                "total_gateway_fees": 0,
                "total_amount": 80,
                "amount_paid": 0,
                "amount_payable": 80,
                "payout_type": "collective",
                "po_number": null,
                "specifications": [
                    {
                        "uid": "{{specification_uid}}",
                        "object": "specification",
                        "created": 1606307019,
                        "updated": 1606307020,
                        "source": {},
                        "status": "current",
                        "paid": null,
                        "period_start": 1606258800,
                        "period_end": 1606345199,
                        "total_number_of_transactions": 2,
                        "number_of_transactions": 1,
                        "number_of_refunds": 1,
                        "number_of_withdrawals": 0,
                        "number_of_mandates": 0,
                        "number_of_internal_transfers": 0,
                        "number_of_multi_transactions": 0,
                        "total_volume": 80,
                        "transaction_volume": 100,
                        "refund_volume": -20,
                        "withdrawal_volume": 0,
                        "mandate_volume": 0,
                        "internal_transfer_volume": 0,
                        "multi_transaction_volume": 0,
                        "total_transaction_costs": 0,
                        "transaction_costs": 0,
                        "refund_costs": 0,
                        "withdrawal_costs": 0,
                        "mandate_costs": 0,
                        "internal_transfer_costs": 0,
                        "multi_transaction_costs": 0,
                        "total_order_fees": 0,
                        "total_refund_fees": 0,
                        "total_gateway_fees": 0,
                        "total_amount": 80,
                        "amount_paid": 0,
                        "amount_payable": 80,
                        "po_number": null
                    }
                ]
            }
        ]
    }
    

    All previous settlements can be found using the following call:

        GET https://api-sandbox.onlinebetaalplatform.nl/v1/merchants/{{merchant_uid}}/settlements?expand[]=specifications&order[]=-period
    

    With &order[]=-period we order the response to view the settlement with the most recent period_end to be the first result.

    Accountancy information

    Aside from the above information, merchants would like to know what their payouts consist of, so that they can process this in their accountancy. Unless you have contractually decided to provide individual payouts, every payout contains the following text on the bank statement:

    Betaling settlement {{specification_uid}} {{merchant_name}} periode 01-12-2019 - 01-12-2019

    On request, OPP can change this text. Keep in mind that this payout text is for all merchants on your platform. The following tags can be used in the settlement payout description:

    We would advise you to create an export of the necessary information for merchants to be able to download. Having the settlement_uid and specification_uid we can retrieve an overview of every event within the specification with the following call:

        GET https://api-sandbox.onlinebetaalplatform.nl/v1/merchants/{{merchant_uid}}/settlements/{{settlement_uid}}/specifications/{{specificiation_uid}}/rows
    

    The response shows al settlement specification rows. Important in this row is:

    {
        "object": "list",
        "url": "/v1/merchants/{{merchant_uid}}/settlements/{{settlement_uid}}/specifications/{{specification_uid}}/rows",
        "has_more": false,
        "total_item_count": 2,
        "items_per_page": 10,
        "current_page": 1,
        "last_page": 1,
        "data": [
            {
                "object": "settlement_row",
                "created": 1606306677,
                "updated": 1606306677,
                "date": 1606306674,
                "type": "transaction",
                "reference": "{{transaction_uid}}",
                "volume": 100,
                "fees": {
                    "total_merchant_fee": 50,
                    "total_partner_fee": 40,
                    ...
                },
                "amount": 100,
                "amount_paid": 0,
                "amount_payable": 100
            },
            {
                "object": "settlement_row",
                "created": 1606307020,
                "updated": 1606307020,
                "date": 1606307016,
                "type": "refund",
                "reference": "{{refund_uid}}",
                "volume": -20,
                "fees": {
                    "total_merchant_fee": 0,
                    "total_partner_fee": 100,
                    ...
                },
                "amount": -20,
                "amount_paid": 0,
                "amount_payable": -20
            }
        ]
    }   
    

    In case a "type": "refund" is found, which does not match with a transaction in the same specification, you can find the transaction to which this refund belongs by the following call:

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

    Transactions

    If you want to show a merchant all transactions that have been done, you can use the following call. This example shows all transactions of a merchant that have status completed or reserved. If desired, the filter can be expanded with other statuses to show for example, pending statuses.

        GET https://api-sandbox.onlinebetaalplatform.nl/v1/merchants/{{merchant_uid}}/transactions?filter[0][name]=status&filter[0][operand]=in&filter[0][value]=completed,reserved
    

    If you want to show all completed and reserved transactions within a certain period of time, you can expand the filter to also filter on a date.

        GET https://api-sandbox.onlinebetaalplatform.nl/v1/merchants/{{merchant_uid}}/transactions?filter[0][name]=status&filter[0][operand]=in&filter[0][value]=completed,reserved&filter[1][name]=date_completed&filter[1][operand]=between&filter[1][value]=2020-11-01 00:00:00, 2020-11-30 23:59:59
    

    A transaction can contain one or more refunds. Refunds belonging to a transaction can be found as follows:

        GET https://api-sandbox.onlinebetaalplatform.nl/v1/transactions/{{transaction_uid}}/refunds
    

    Do note that we expect you to save all transaction_uids and refund_uids that belong to an order, so filtering and ordering could also be done on your own data.

    Partner Dashboard

    When providing payments on your platform, you would like to know what happens to their orders and payments. Besides that, it is wise for you to know what happens to your fee and how much you pay for transactions, refunds, mandates, etc.

    In this chapter, we will guide you through providing all information that is required to build your own dashboard. In this guide, we assume that you have registered all refund_uid’s and transaction_uid’s in your database, in order to relate them to the correct bookings and other related data.

    Al your monthly fee is combined into a settlement. A settlement is the (current) balance over a specific period of time. Every settlement has a specification for every merchant your platform has. This way you can see exactly how much you earn from specific merchants.

    The current settlement can be found using:

        GET https://api-sandbox.onlinebetaalplatform.nl/v1/settlements?filter[status]=current&expand[]=specifications
    

    If you do not have a current settlement, the server will respond with an empty list. Every specification has its own specification_uid. The specification is build up the same way as a settlement is. In case you want to specify the dashboard per merchant, it is important to look at the different specifications, instead of the complete settlement. Important in this response is:

    A response might look like this:

    {
        "object": "list",
        "url": "/v1/settlements",
        "has_more": false,
        "total_item_count": 1,
        "items_per_page": 10,
        "current_page": 1,
        "last_page": 1,
        "data": [
            {
                "uid": "{{settlement_uid}}",
                "object": "settlement",
                "created": 1606307019,
                "updated": 1606307020,
                "status": "current",
                "paid": null,
                "period_start": 1606258800,
                "period_end": 1606345199,
                "total_number_of_transactions": 72,
                "number_of_transactions": 47,
                "number_of_refunds": 3,
                "number_of_withdrawals": 0,
                "number_of_mandates": 20,
                "number_of_internal_transfers": 0,
                "number_of_multi_transactions": 2,
                "total_volume": 685188,
                "transaction_volume": 686218,
                "refund_volume": -1030,
                "withdrawal_volume": 0,
                "mandate_volume": 0,
                "internal_transfer_volume": 0,
                "multi_transaction_volume": 0,
                "total_transaction_costs": -4285,
                "transaction_costs": -435,
                "refund_costs": 0,
                "withdrawal_costs": 0,
                "mandate_costs": -3850,
                "internal_transfer_costs": 0,
                "multi_transaction_costs": 0,
                "total_order_fees": 0,
                "total_refund_fees": 0,
                "total_gateway_fees": 0,
                "total_amount": 80,
                "amount_paid": 0,
                "amount_payable": -4442,
                "payout_type": "collective",
                "po_number": null,
                "specifications": [
                    {
                        "uid": "set_8751fc4fb25f",
                        "object": "specification",
                        "created": 1606386063,
                        "updated": 1606386064,
                        "source": {},
                        "status": "current",
                        "paid": null,
                        "period_start": 1604358000,
                        "period_end": 1606777199,
                        "total_number_of_transactions": 35,
                        "number_of_transactions": 12,
                        "number_of_refunds": 1,
                        "number_of_withdrawals": 0,
                        "number_of_mandates": 20,
                        "number_of_internal_transfers": 0,
                        "number_of_multi_transactions": 2,
                        "total_volume": 33078,
                        "transaction_volume": 34078,
                        "refund_volume": -1000,
                        "withdrawal_volume": 0,
                        "mandate_volume": 0,
                        "internal_transfer_volume": 0,
                        "multi_transaction_volume": 0,
                        "total_transaction_costs": -3910,
                        "transaction_costs": -60,
                        "refund_costs": 0,
                        "withdrawal_costs": 0,
                        "mandate_costs": -3850,
                        "internal_transfer_costs": 0,
                        "multi_transaction_costs": 0,
                        "total_order_fees": 398,
                        "total_refund_fees": -100,
                        "total_gateway_fees": -650,
                        "total_amount": 188,
                        "amount_paid": 0,
                        "amount_payable": -4262,
                        "po_number": null
                    },
                    ...
                ]
            }
        ]
    }
    

    All previous settlements can be found using the following call:

        GET https://api-sandbox.onlinebetaalplatform.nl/v1/settlements?expand[]=specifications&order[]=-period
    

    With &order[]=-period we order the response to view the settlement with the most recent period_end to be the first result.

    The set_xxx code, is also visible on your bank statement of that specific period. Your bank statement will look something like this:

        Betaling settlement {{settlement_uid}} {{partner_name}} periode 01-12-2019 - 31-12-2019
    

    Aside from the above information, you might want to know what your payouts consist of, so that you can process this in your accountancy. Every payout contains the following text on the bank statement:

    We would advise you to create an export of the necessary information for you to be able to download. Having the settlement_uid and specification_uid you can retrieve an overview of every event within the specification with the following call:

        GET https://api-sandbox.onlinebetaalplatform.nl/v1/settlements/{{settlement_uid}}/specifications/{{specificiation_uid}}/rows
    

    The response shows al settlement specification rows. Important in this row is:

    The sum of all amount_payable in the specifications adds up to the amount_payable of the settlement, and is the amount that you will receive on your bank account.

    {
        "object": "list",
        "url": "/v1/merchants/{{merchant_uid}}/settlements/{{settlement_uid}}/specifications/{{specification_uid}}/rows",
        "has_more": false,
        "total_item_count": 2,
        "items_per_page": 10,
        "current_page": 1,
        "last_page": 1,
        "data": [
            {
                "object": "settlement_row",
                "created": 1606306677,
                "updated": 1606306677,
                "date": 1606306674,
                "type": "transaction",
                "reference": "{{transaction_uid}}",
                "volume": 100,
                "fees": {
                    "total_merchant_fee": 0,
                    "total_partner_fee": 40,
                    ...
                },
                "amount": 40,
                "amount_paid": 0,
                "amount_payable": 40
            },
            {
                "object": "settlement_row",
                "created": 1606307020,
                "updated": 1606307020,
                "date": 1606307016,
                "type": "refund",
                "reference": "{{refund_uid}}",
                "volume": -20,
                "fees": {
                    "total_merchant_fee": 0,
                    "total_partner_fee": 100,
                    ...
                },
                "amount": -20,
                "amount_paid": 0,
                "amount_payable": -20
            }
        ]
    }   
    

    In case a "type": "refund" is found, which does not match with a transaction in the same specification, you can find the transaction to which this refund belongs by the following call:

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