Opening accounts on behalf of your Merchants

Having established your parent API keys for your Embedded Partner account, configured your Hawk Authentication headers, and ensured your merchants have agreed to the BVNK policies, you are now ready to create an Embedded Partner Merchant (EPM) account via the API.

Creating an EPM Account

You're set to create your first EPM by submitting a request to the Onboard Embedded Merchant endpoint.

This request must include general information about your merchant, an external ID to link with the account reference generated by BVNK, and the reference to the previously accepted policies as acceptedAgreementReferences.

{
  "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"]
}

Upon submitting this request, you will receive a response indicating whether the creation was successful. A 202 Accepted response confirms that the EPM account has been successfully created. Following this, an onboarding webhook will be dispatched to the previously specified webhook URL, containing essential information.

{
  "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"
  }
}

The critical piece of information to note from this webhook is the accountReference. This unique reference ID is used in API requests as the x-account-reference in the headers to represent the EPM account.

❗️

Important Regarding accountReference

The accountReference is crucial for identifying which account to target in API requests when included as x-account-reference in the headers. Requests lacking this header will default to being executed at the EP account level, so it's essential to store and use this reference accurately.