Create Sub-Merchant
curl --request POST \
--url https://mapi.zbx.boomfi.xyz/v1/partners/orgs \
--header 'Content-Type: application/json' \
--header 'X-API-KEY: <api-key>' \
--data '
{
"external_reference": "<string>",
"name": "<string>",
"owner": {
"email": "<string>",
"name": "<string>",
"phone": "<string>"
},
"country_of_incorporation": "<string>",
"dba_name": "<string>",
"end_user_ip": "<string>",
"legal_name": "<string>",
"mid": "<string>",
"partner_id": "<string>",
"payment_fee_pct": 123,
"principal_place_of_business": "<string>",
"registration_number": "<string>",
"settlement_accounts": [
"<unknown>"
],
"webhook_url": "<string>"
}
'import requests
url = "https://mapi.zbx.boomfi.xyz/v1/partners/orgs"
payload = {
"external_reference": "<string>",
"name": "<string>",
"owner": {
"email": "<string>",
"name": "<string>",
"phone": "<string>"
},
"country_of_incorporation": "<string>",
"dba_name": "<string>",
"end_user_ip": "<string>",
"legal_name": "<string>",
"mid": "<string>",
"partner_id": "<string>",
"payment_fee_pct": 123,
"principal_place_of_business": "<string>",
"registration_number": "<string>",
"settlement_accounts": ["<unknown>"],
"webhook_url": "<string>"
}
headers = {
"X-API-KEY": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-API-KEY': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
external_reference: '<string>',
name: '<string>',
owner: {email: '<string>', name: '<string>', phone: '<string>'},
country_of_incorporation: '<string>',
dba_name: '<string>',
end_user_ip: '<string>',
legal_name: '<string>',
mid: '<string>',
partner_id: '<string>',
payment_fee_pct: 123,
principal_place_of_business: '<string>',
registration_number: '<string>',
settlement_accounts: ['<unknown>'],
webhook_url: '<string>'
})
};
fetch('https://mapi.zbx.boomfi.xyz/v1/partners/orgs', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://mapi.zbx.boomfi.xyz/v1/partners/orgs",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'external_reference' => '<string>',
'name' => '<string>',
'owner' => [
'email' => '<string>',
'name' => '<string>',
'phone' => '<string>'
],
'country_of_incorporation' => '<string>',
'dba_name' => '<string>',
'end_user_ip' => '<string>',
'legal_name' => '<string>',
'mid' => '<string>',
'partner_id' => '<string>',
'payment_fee_pct' => 123,
'principal_place_of_business' => '<string>',
'registration_number' => '<string>',
'settlement_accounts' => [
'<unknown>'
],
'webhook_url' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-API-KEY: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://mapi.zbx.boomfi.xyz/v1/partners/orgs"
payload := strings.NewReader("{\n \"external_reference\": \"<string>\",\n \"name\": \"<string>\",\n \"owner\": {\n \"email\": \"<string>\",\n \"name\": \"<string>\",\n \"phone\": \"<string>\"\n },\n \"country_of_incorporation\": \"<string>\",\n \"dba_name\": \"<string>\",\n \"end_user_ip\": \"<string>\",\n \"legal_name\": \"<string>\",\n \"mid\": \"<string>\",\n \"partner_id\": \"<string>\",\n \"payment_fee_pct\": 123,\n \"principal_place_of_business\": \"<string>\",\n \"registration_number\": \"<string>\",\n \"settlement_accounts\": [\n \"<unknown>\"\n ],\n \"webhook_url\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-API-KEY", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://mapi.zbx.boomfi.xyz/v1/partners/orgs")
.header("X-API-KEY", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"external_reference\": \"<string>\",\n \"name\": \"<string>\",\n \"owner\": {\n \"email\": \"<string>\",\n \"name\": \"<string>\",\n \"phone\": \"<string>\"\n },\n \"country_of_incorporation\": \"<string>\",\n \"dba_name\": \"<string>\",\n \"end_user_ip\": \"<string>\",\n \"legal_name\": \"<string>\",\n \"mid\": \"<string>\",\n \"partner_id\": \"<string>\",\n \"payment_fee_pct\": 123,\n \"principal_place_of_business\": \"<string>\",\n \"registration_number\": \"<string>\",\n \"settlement_accounts\": [\n \"<unknown>\"\n ],\n \"webhook_url\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://mapi.zbx.boomfi.xyz/v1/partners/orgs")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-API-KEY"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"external_reference\": \"<string>\",\n \"name\": \"<string>\",\n \"owner\": {\n \"email\": \"<string>\",\n \"name\": \"<string>\",\n \"phone\": \"<string>\"\n },\n \"country_of_incorporation\": \"<string>\",\n \"dba_name\": \"<string>\",\n \"end_user_ip\": \"<string>\",\n \"legal_name\": \"<string>\",\n \"mid\": \"<string>\",\n \"partner_id\": \"<string>\",\n \"payment_fee_pct\": 123,\n \"principal_place_of_business\": \"<string>\",\n \"registration_number\": \"<string>\",\n \"settlement_accounts\": [\n \"<unknown>\"\n ],\n \"webhook_url\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"data": {
"created_at": "<string>",
"kyc_status": "<string>",
"name": "<string>",
"org_id": "<string>",
"owner": {
"email": "<string>",
"name": "<string>",
"phone": "<string>",
"user_id": "<string>"
},
"partner_id": "<string>",
"settlement_accounts": [
{
"address": "<string>",
"chain_id": 123,
"currencies": [
"<string>"
],
"id": 123,
"name": "<string>",
"reference": "<string>"
}
],
"verification_url": "<string>"
},
"error": true,
"message": "<string>"
}{
"data": {
"created_at": "<string>",
"kyc_status": "<string>",
"name": "<string>",
"org_id": "<string>",
"owner": {
"email": "<string>",
"name": "<string>",
"phone": "<string>",
"user_id": "<string>"
},
"partner_id": "<string>",
"settlement_accounts": [
{
"address": "<string>",
"chain_id": 123,
"currencies": [
"<string>"
],
"id": 123,
"name": "<string>",
"reference": "<string>"
}
],
"verification_url": "<string>"
},
"error": true,
"message": "<string>"
}{
"error": {
"code": 400,
"errors": [
{
"domain": "orders",
"reason": "InsufficientQuantity"
}
],
"message": "Insufficient quantity"
}
}{
"error": {
"code": 400,
"errors": [
{
"domain": "orders",
"reason": "InsufficientQuantity"
}
],
"message": "Insufficient quantity"
}
}{
"error": {
"code": 400,
"errors": [
{
"domain": "orders",
"reason": "InsufficientQuantity"
}
],
"message": "Insufficient quantity"
}
}{
"error": {
"code": 400,
"errors": [
{
"domain": "orders",
"reason": "InsufficientQuantity"
}
],
"message": "Insufficient quantity"
}
}{
"error": {
"code": 400,
"errors": [
{
"domain": "orders",
"reason": "InsufficientQuantity"
}
],
"message": "Insufficient quantity"
}
}Partners
Create Sub-Merchant
Onboard a merchant under your partner account. In an environment where a custody provider owns merchant identity, this registers the merchant with that provider and returns a one-time verification_url to send them to; the merchant’s accounts are provisioned once they clear KYC, and kyc_status reports where they are. Repeating the call with the same external_reference returns the org you already created rather than a second one.
POST
/
partners
/
orgs
Create Sub-Merchant
curl --request POST \
--url https://mapi.zbx.boomfi.xyz/v1/partners/orgs \
--header 'Content-Type: application/json' \
--header 'X-API-KEY: <api-key>' \
--data '
{
"external_reference": "<string>",
"name": "<string>",
"owner": {
"email": "<string>",
"name": "<string>",
"phone": "<string>"
},
"country_of_incorporation": "<string>",
"dba_name": "<string>",
"end_user_ip": "<string>",
"legal_name": "<string>",
"mid": "<string>",
"partner_id": "<string>",
"payment_fee_pct": 123,
"principal_place_of_business": "<string>",
"registration_number": "<string>",
"settlement_accounts": [
"<unknown>"
],
"webhook_url": "<string>"
}
'import requests
url = "https://mapi.zbx.boomfi.xyz/v1/partners/orgs"
payload = {
"external_reference": "<string>",
"name": "<string>",
"owner": {
"email": "<string>",
"name": "<string>",
"phone": "<string>"
},
"country_of_incorporation": "<string>",
"dba_name": "<string>",
"end_user_ip": "<string>",
"legal_name": "<string>",
"mid": "<string>",
"partner_id": "<string>",
"payment_fee_pct": 123,
"principal_place_of_business": "<string>",
"registration_number": "<string>",
"settlement_accounts": ["<unknown>"],
"webhook_url": "<string>"
}
headers = {
"X-API-KEY": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-API-KEY': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
external_reference: '<string>',
name: '<string>',
owner: {email: '<string>', name: '<string>', phone: '<string>'},
country_of_incorporation: '<string>',
dba_name: '<string>',
end_user_ip: '<string>',
legal_name: '<string>',
mid: '<string>',
partner_id: '<string>',
payment_fee_pct: 123,
principal_place_of_business: '<string>',
registration_number: '<string>',
settlement_accounts: ['<unknown>'],
webhook_url: '<string>'
})
};
fetch('https://mapi.zbx.boomfi.xyz/v1/partners/orgs', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://mapi.zbx.boomfi.xyz/v1/partners/orgs",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'external_reference' => '<string>',
'name' => '<string>',
'owner' => [
'email' => '<string>',
'name' => '<string>',
'phone' => '<string>'
],
'country_of_incorporation' => '<string>',
'dba_name' => '<string>',
'end_user_ip' => '<string>',
'legal_name' => '<string>',
'mid' => '<string>',
'partner_id' => '<string>',
'payment_fee_pct' => 123,
'principal_place_of_business' => '<string>',
'registration_number' => '<string>',
'settlement_accounts' => [
'<unknown>'
],
'webhook_url' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-API-KEY: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://mapi.zbx.boomfi.xyz/v1/partners/orgs"
payload := strings.NewReader("{\n \"external_reference\": \"<string>\",\n \"name\": \"<string>\",\n \"owner\": {\n \"email\": \"<string>\",\n \"name\": \"<string>\",\n \"phone\": \"<string>\"\n },\n \"country_of_incorporation\": \"<string>\",\n \"dba_name\": \"<string>\",\n \"end_user_ip\": \"<string>\",\n \"legal_name\": \"<string>\",\n \"mid\": \"<string>\",\n \"partner_id\": \"<string>\",\n \"payment_fee_pct\": 123,\n \"principal_place_of_business\": \"<string>\",\n \"registration_number\": \"<string>\",\n \"settlement_accounts\": [\n \"<unknown>\"\n ],\n \"webhook_url\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-API-KEY", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://mapi.zbx.boomfi.xyz/v1/partners/orgs")
.header("X-API-KEY", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"external_reference\": \"<string>\",\n \"name\": \"<string>\",\n \"owner\": {\n \"email\": \"<string>\",\n \"name\": \"<string>\",\n \"phone\": \"<string>\"\n },\n \"country_of_incorporation\": \"<string>\",\n \"dba_name\": \"<string>\",\n \"end_user_ip\": \"<string>\",\n \"legal_name\": \"<string>\",\n \"mid\": \"<string>\",\n \"partner_id\": \"<string>\",\n \"payment_fee_pct\": 123,\n \"principal_place_of_business\": \"<string>\",\n \"registration_number\": \"<string>\",\n \"settlement_accounts\": [\n \"<unknown>\"\n ],\n \"webhook_url\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://mapi.zbx.boomfi.xyz/v1/partners/orgs")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-API-KEY"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"external_reference\": \"<string>\",\n \"name\": \"<string>\",\n \"owner\": {\n \"email\": \"<string>\",\n \"name\": \"<string>\",\n \"phone\": \"<string>\"\n },\n \"country_of_incorporation\": \"<string>\",\n \"dba_name\": \"<string>\",\n \"end_user_ip\": \"<string>\",\n \"legal_name\": \"<string>\",\n \"mid\": \"<string>\",\n \"partner_id\": \"<string>\",\n \"payment_fee_pct\": 123,\n \"principal_place_of_business\": \"<string>\",\n \"registration_number\": \"<string>\",\n \"settlement_accounts\": [\n \"<unknown>\"\n ],\n \"webhook_url\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"data": {
"created_at": "<string>",
"kyc_status": "<string>",
"name": "<string>",
"org_id": "<string>",
"owner": {
"email": "<string>",
"name": "<string>",
"phone": "<string>",
"user_id": "<string>"
},
"partner_id": "<string>",
"settlement_accounts": [
{
"address": "<string>",
"chain_id": 123,
"currencies": [
"<string>"
],
"id": 123,
"name": "<string>",
"reference": "<string>"
}
],
"verification_url": "<string>"
},
"error": true,
"message": "<string>"
}{
"data": {
"created_at": "<string>",
"kyc_status": "<string>",
"name": "<string>",
"org_id": "<string>",
"owner": {
"email": "<string>",
"name": "<string>",
"phone": "<string>",
"user_id": "<string>"
},
"partner_id": "<string>",
"settlement_accounts": [
{
"address": "<string>",
"chain_id": 123,
"currencies": [
"<string>"
],
"id": 123,
"name": "<string>",
"reference": "<string>"
}
],
"verification_url": "<string>"
},
"error": true,
"message": "<string>"
}{
"error": {
"code": 400,
"errors": [
{
"domain": "orders",
"reason": "InsufficientQuantity"
}
],
"message": "Insufficient quantity"
}
}{
"error": {
"code": 400,
"errors": [
{
"domain": "orders",
"reason": "InsufficientQuantity"
}
],
"message": "Insufficient quantity"
}
}{
"error": {
"code": 400,
"errors": [
{
"domain": "orders",
"reason": "InsufficientQuantity"
}
],
"message": "Insufficient quantity"
}
}{
"error": {
"code": 400,
"errors": [
{
"domain": "orders",
"reason": "InsufficientQuantity"
}
],
"message": "Insufficient quantity"
}
}{
"error": {
"code": 400,
"errors": [
{
"domain": "orders",
"reason": "InsufficientQuantity"
}
],
"message": "Insufficient quantity"
}
}Authorizations
Body
application/json
Merchant to onboard
External reference for this resource.
Display name.
Owner for this resource. owner.phone must be a verified E.164 mobile.
Show child attributes
Show child attributes
Postal address. Country and city are required when present.
Show child attributes
Show child attributes
alpha-3
Dba name for this resource.
EndUserIP is the merchant's own IP at signup, which ZBX documents as "required for risk assessment and compliance" on user registration.
Optional here because only the partner can know it: this is a server-to-server call, so the connecting address is their backend, not the merchant's browser. Absent falls back to that connecting address — which keeps working, but feeds ZBX's risk engine a datacenter IP. A partner who can supply the real one should.
Top-level rather than on the shared owner object: it means nothing on the self-custody path and does not belong in its contract.
LegalName is the optional field that earns its keep here: it becomes zbx.expected_holder_name, which is how an inbound IBAN — a payload carrying no uid — gets attributed to this merchant. Absent falls back to Name.
Mcc for this resource. Optional, but all three sub-fields are required when it is present — a half-filled MCC is a mistake, an absent one is a choice.
Show child attributes
Show child attributes
Mid for this resource.
Identifier of the partner organisation, when this org is under a partner.
Payment fee percentage.
alpha-3 country code
Registration number for this resource.
Accounts exists only to be rejected, and is untyped so that any shape gets the explanation below rather than a binding error about a missing sub-field.
HTTPS URL that receives webhook events.
⌘I