Add a corporate cardholder
curl --request POST \
--url https://api.bitnob.com/api/cards/kyc/corporate/{customerId}/cardholders \
--header 'Content-Type: application/json' \
--header 'X-Auth-Client: <api-key>' \
--header 'X-Playground-Client-Secret: <api-key>' \
--data '
{
"cardholder": {
"address": {
"city": "Accra",
"country": "Ghana",
"country_code": "GH",
"line1": "7 Oxford Street",
"postal_code": "GA-000-0000",
"region": "Greater Accra"
},
"birth_date": "1992-07-03",
"country_of_issue": "GH",
"email": "ama.owusu@example.com",
"first_name": "Ama",
"is_terms_of_service_accepted": true,
"last_name": "Owusu",
"national_id": "GHA-000000000-0",
"phone_country_code": "+233",
"phone_number": "200000001"
}
}
'const options = {
method: 'POST',
headers: {
'X-Auth-Client': '<api-key>',
'X-Playground-Client-Secret': '<api-key>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
cardholder: {
address: {
city: 'Accra',
country: 'Ghana',
country_code: 'GH',
line1: '7 Oxford Street',
postal_code: 'GA-000-0000',
region: 'Greater Accra'
},
birth_date: '1992-07-03',
country_of_issue: 'GH',
email: 'ama.owusu@example.com',
first_name: 'Ama',
is_terms_of_service_accepted: true,
last_name: 'Owusu',
national_id: 'GHA-000000000-0',
phone_country_code: '+233',
phone_number: '200000001'
}
})
};
fetch('https://api.bitnob.com/api/cards/kyc/corporate/{customerId}/cardholders', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api.bitnob.com/api/cards/kyc/corporate/{customerId}/cardholders"
payload = { "cardholder": {
"address": {
"city": "Accra",
"country": "Ghana",
"country_code": "GH",
"line1": "7 Oxford Street",
"postal_code": "GA-000-0000",
"region": "Greater Accra"
},
"birth_date": "1992-07-03",
"country_of_issue": "GH",
"email": "ama.owusu@example.com",
"first_name": "Ama",
"is_terms_of_service_accepted": True,
"last_name": "Owusu",
"national_id": "GHA-000000000-0",
"phone_country_code": "+233",
"phone_number": "200000001"
} }
headers = {
"X-Auth-Client": "<api-key>",
"X-Playground-Client-Secret": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.bitnob.com/api/cards/kyc/corporate/{customerId}/cardholders",
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([
'cardholder' => [
'address' => [
'city' => 'Accra',
'country' => 'Ghana',
'country_code' => 'GH',
'line1' => '7 Oxford Street',
'postal_code' => 'GA-000-0000',
'region' => 'Greater Accra'
],
'birth_date' => '1992-07-03',
'country_of_issue' => 'GH',
'email' => 'ama.owusu@example.com',
'first_name' => 'Ama',
'is_terms_of_service_accepted' => true,
'last_name' => 'Owusu',
'national_id' => 'GHA-000000000-0',
'phone_country_code' => '+233',
'phone_number' => '200000001'
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-Auth-Client: <api-key>",
"X-Playground-Client-Secret: <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://api.bitnob.com/api/cards/kyc/corporate/{customerId}/cardholders"
payload := strings.NewReader("{\n \"cardholder\": {\n \"address\": {\n \"city\": \"Accra\",\n \"country\": \"Ghana\",\n \"country_code\": \"GH\",\n \"line1\": \"7 Oxford Street\",\n \"postal_code\": \"GA-000-0000\",\n \"region\": \"Greater Accra\"\n },\n \"birth_date\": \"1992-07-03\",\n \"country_of_issue\": \"GH\",\n \"email\": \"ama.owusu@example.com\",\n \"first_name\": \"Ama\",\n \"is_terms_of_service_accepted\": true,\n \"last_name\": \"Owusu\",\n \"national_id\": \"GHA-000000000-0\",\n \"phone_country_code\": \"+233\",\n \"phone_number\": \"200000001\"\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-Auth-Client", "<api-key>")
req.Header.Add("X-Playground-Client-Secret", "<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://api.bitnob.com/api/cards/kyc/corporate/{customerId}/cardholders")
.header("X-Auth-Client", "<api-key>")
.header("X-Playground-Client-Secret", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"cardholder\": {\n \"address\": {\n \"city\": \"Accra\",\n \"country\": \"Ghana\",\n \"country_code\": \"GH\",\n \"line1\": \"7 Oxford Street\",\n \"postal_code\": \"GA-000-0000\",\n \"region\": \"Greater Accra\"\n },\n \"birth_date\": \"1992-07-03\",\n \"country_of_issue\": \"GH\",\n \"email\": \"ama.owusu@example.com\",\n \"first_name\": \"Ama\",\n \"is_terms_of_service_accepted\": true,\n \"last_name\": \"Owusu\",\n \"national_id\": \"GHA-000000000-0\",\n \"phone_country_code\": \"+233\",\n \"phone_number\": \"200000001\"\n }\n}")
.asString();{
"data": {
"cardholder_customer_id": "019a3b5c-4f60-7b2c-9d3e-5f6a7b8c9d72",
"completion_link": "https://kyc.sandbox.example.com/s/sbx_c4e1b7a9f203",
"status": "action_required"
},
"message": "Corporate cardholder added successfully",
"success": true,
"timestamp": "2026-10-30T09:15:02.481Z"
}Virtual cards
Add a corporate cardholder
Adds a person as a cardholder on a KYB-approved business. completion_link is returned while the cardholder’s compliance check is pending or needs action.
POST
/
api
/
cards
/
kyc
/
corporate
/
{customerId}
/
cardholders
Add a corporate cardholder
curl --request POST \
--url https://api.bitnob.com/api/cards/kyc/corporate/{customerId}/cardholders \
--header 'Content-Type: application/json' \
--header 'X-Auth-Client: <api-key>' \
--header 'X-Playground-Client-Secret: <api-key>' \
--data '
{
"cardholder": {
"address": {
"city": "Accra",
"country": "Ghana",
"country_code": "GH",
"line1": "7 Oxford Street",
"postal_code": "GA-000-0000",
"region": "Greater Accra"
},
"birth_date": "1992-07-03",
"country_of_issue": "GH",
"email": "ama.owusu@example.com",
"first_name": "Ama",
"is_terms_of_service_accepted": true,
"last_name": "Owusu",
"national_id": "GHA-000000000-0",
"phone_country_code": "+233",
"phone_number": "200000001"
}
}
'const options = {
method: 'POST',
headers: {
'X-Auth-Client': '<api-key>',
'X-Playground-Client-Secret': '<api-key>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
cardholder: {
address: {
city: 'Accra',
country: 'Ghana',
country_code: 'GH',
line1: '7 Oxford Street',
postal_code: 'GA-000-0000',
region: 'Greater Accra'
},
birth_date: '1992-07-03',
country_of_issue: 'GH',
email: 'ama.owusu@example.com',
first_name: 'Ama',
is_terms_of_service_accepted: true,
last_name: 'Owusu',
national_id: 'GHA-000000000-0',
phone_country_code: '+233',
phone_number: '200000001'
}
})
};
fetch('https://api.bitnob.com/api/cards/kyc/corporate/{customerId}/cardholders', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api.bitnob.com/api/cards/kyc/corporate/{customerId}/cardholders"
payload = { "cardholder": {
"address": {
"city": "Accra",
"country": "Ghana",
"country_code": "GH",
"line1": "7 Oxford Street",
"postal_code": "GA-000-0000",
"region": "Greater Accra"
},
"birth_date": "1992-07-03",
"country_of_issue": "GH",
"email": "ama.owusu@example.com",
"first_name": "Ama",
"is_terms_of_service_accepted": True,
"last_name": "Owusu",
"national_id": "GHA-000000000-0",
"phone_country_code": "+233",
"phone_number": "200000001"
} }
headers = {
"X-Auth-Client": "<api-key>",
"X-Playground-Client-Secret": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.bitnob.com/api/cards/kyc/corporate/{customerId}/cardholders",
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([
'cardholder' => [
'address' => [
'city' => 'Accra',
'country' => 'Ghana',
'country_code' => 'GH',
'line1' => '7 Oxford Street',
'postal_code' => 'GA-000-0000',
'region' => 'Greater Accra'
],
'birth_date' => '1992-07-03',
'country_of_issue' => 'GH',
'email' => 'ama.owusu@example.com',
'first_name' => 'Ama',
'is_terms_of_service_accepted' => true,
'last_name' => 'Owusu',
'national_id' => 'GHA-000000000-0',
'phone_country_code' => '+233',
'phone_number' => '200000001'
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-Auth-Client: <api-key>",
"X-Playground-Client-Secret: <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://api.bitnob.com/api/cards/kyc/corporate/{customerId}/cardholders"
payload := strings.NewReader("{\n \"cardholder\": {\n \"address\": {\n \"city\": \"Accra\",\n \"country\": \"Ghana\",\n \"country_code\": \"GH\",\n \"line1\": \"7 Oxford Street\",\n \"postal_code\": \"GA-000-0000\",\n \"region\": \"Greater Accra\"\n },\n \"birth_date\": \"1992-07-03\",\n \"country_of_issue\": \"GH\",\n \"email\": \"ama.owusu@example.com\",\n \"first_name\": \"Ama\",\n \"is_terms_of_service_accepted\": true,\n \"last_name\": \"Owusu\",\n \"national_id\": \"GHA-000000000-0\",\n \"phone_country_code\": \"+233\",\n \"phone_number\": \"200000001\"\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-Auth-Client", "<api-key>")
req.Header.Add("X-Playground-Client-Secret", "<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://api.bitnob.com/api/cards/kyc/corporate/{customerId}/cardholders")
.header("X-Auth-Client", "<api-key>")
.header("X-Playground-Client-Secret", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"cardholder\": {\n \"address\": {\n \"city\": \"Accra\",\n \"country\": \"Ghana\",\n \"country_code\": \"GH\",\n \"line1\": \"7 Oxford Street\",\n \"postal_code\": \"GA-000-0000\",\n \"region\": \"Greater Accra\"\n },\n \"birth_date\": \"1992-07-03\",\n \"country_of_issue\": \"GH\",\n \"email\": \"ama.owusu@example.com\",\n \"first_name\": \"Ama\",\n \"is_terms_of_service_accepted\": true,\n \"last_name\": \"Owusu\",\n \"national_id\": \"GHA-000000000-0\",\n \"phone_country_code\": \"+233\",\n \"phone_number\": \"200000001\"\n }\n}")
.asString();{
"data": {
"cardholder_customer_id": "019a3b5c-4f60-7b2c-9d3e-5f6a7b8c9d72",
"completion_link": "https://kyc.sandbox.example.com/s/sbx_c4e1b7a9f203",
"status": "action_required"
},
"message": "Corporate cardholder added successfully",
"success": true,
"timestamp": "2026-10-30T09:15:02.481Z"
}Authorizations
Your workspace client id.
All calls must include four headers:
X-Auth-Client— your workspace client idX-Auth-Timestamp— Unix secondsX-Auth-Nonce— 16-byte random hexX-Auth-Signature— hex(HMAC-SHA256({client_id}:{timestamp}:{nonce}:{raw_body}, client_secret))
The playground computes the timestamp, nonce and signature for you.
Your sandbox client secret. The playground uses it to sign the request in your browser and removes it before the request is sent. Never send your client secret as a header in your own integration.
Path Parameters
Business customer ID
Body
application/json
Show child attributes
Show child attributes
Response
OK
Successful responses are wrapped in this envelope, and so are errors a handler answers itself (request body and field validation, some not-found and conflict cases, ORG_NOT_ACTIVE): success is false and error carries a code and message. Errors raised by authentication and by the services behind a handler are a Problem instead.
true on success
When the response was written.
The payload; its shape is given per operation. Omitted when there is none.
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Human-readable summary; omitted when empty.
List metadata. Page lists set page, per_page, total and total_pages; offset and cursor lists set limit, offset, has_more and next_cursor. Zero and empty fields are omitted, and metadata is absent when nothing is set.
Show child attributes
Show child attributes
Set on error envelopes: the request's correlation id (req_ followed by a UUID), the same value as the X-Correlation-ID response header. Quote it to support.