Before executing the API calls to create an Embedded Partner Merchant (EPM) account, you'll need to use your API ID and Keys. To access these details, follow the Creating your API Keys section of the guide. See how to Authenticate on the API in our guide here.

Executing API calls to get agreements

Before opening an EPM, you will need to fetch the BVNK agreements which are dependent on the Country of incorporation of the EPM:

curl --location 'https://api.sandbox.bvnk.com/api/v1/agreement?product=embedded&country=GB' \
--header 'Accept: application/json'

Above is a sample Country value which uses GB ISO code representing Great Britain.

A list of all countries with associated ISO codes can be retrieved using the below:

curl --location 'https://api.sandbox.bvnk.com/api/country' \
--header 'Accept: application/json'

Executing API calls to open an account for your EPM

Check out the API reference

curl --request POST \
     --url https://api.sandbox.bvnk.com/api/v1/embedded-partner/onboarding \
     --header 'Authorization: Hawk id="B9jnE1U8eLblzHtNeJZRxfcq03CQKcmcP9FOrACMzXb1HfrxrePWsTfuP70JNns9", ts="1633010032", nonce="guGXrD", mac="uKeg+w1qXqzaF/8mOQGv8Y9IlRxyxTT+iINLe03EQ60="' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "firstName": "John",
  "lastName": "Smith",
  "emailAddress": "[email protected]",
  "accountName": "ACME Limited",
  "businessRegistrationNumber": "12345678",
  "address1": "Registered address 1",
  "address2": "Registered address 2",
  "postalCode": "Registered postal code",
  "city": "Registered city",
  "countryOfIncorporationCode": "US",
  "usageReason": "Onboard to BVNK",
  "externalId": "4549a370-0e9f-450a-bafa-65ffbd5954f2",
  "acceptedAgreementReferences" : ["9fc28f1a-f946-11ed-a643-027612b7f6b5", "4b7c0cdf-f42a-11ed-a643-027612b7f6b5"]
}
'

Once you've submitted this request, you'll receive a response confirming success or failure. Success would look like this - 202 Accepted

The webhook URL response will contain the accountReference which is a unique identifier for your EPM.

{
  "source":"onboarding",
  "event":"onboardingSuccess",
  "date":1684749021489,
  "dateFormatted":"2023-05-22T09:50:21.489833737Z",
  "data":{
     "emailAddress":"[email protected]",
     "externalId":"12345",
     "accountReference":"39bd9cd2-8d57-4547-ae2a-f82c5bc328ce"
  }
}