Customers

Create and manage business-customer KYB records under your merchant business.

Only type: business is accepted. Editable while draft or rejected. Document types: cac, memart, status_report, scuml, proof_of_funds, utility_bill.

GET/customers

Scope: customers:read

List customers for the authenticated merchant (paginated).

Request

curl -X GET "https://api.bitstac.io/api/v1/merchant/customers" \
  -H "Authorization: Bearer $BITSTAC_API_KEY" \
  -H "Accept: application/json"

Example response

{
  "success": true,
  "data": [
    {
      "id": "3f2c…",
      "external_reference": "crm-1001",
      "type": "business",
      "business_name": "Northwind Trading Ltd",
      "status": "draft",
      "created_at": "2026-07-26T12:00:00.000000Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "last_page": 1,
    "per_page": 15,
    "total": 1
  }
}

POST/customers

Scope: customers:write

Create a draft business customer. All profile fields are optional at create time; required fields are enforced on submit.

Body fields

type — optional, must be business if sent
external_reference, business_name, trading_name
registration_country, registration_number, registration_date, tax_identification_number
business_type, business_classification (UUID)
business_address, business_state, business_country
business_phone, business_email

Request

curl -X POST "https://api.bitstac.io/api/v1/merchant/customers" \
  -H "Authorization: Bearer $BITSTAC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{  "type": "business",  "external_reference": "crm-1001",  "business_name": "Northwind Trading Ltd",  "trading_name": "Northwind",  "registration_country": "NG",  "registration_number": "RC123456",  "registration_date": "2020-01-15",  "tax_identification_number": "12345678-0001",  "business_type": "limited_liability",  "business_address": "12 Marina, Lagos",  "business_state": "Lagos",  "business_country": "NG",  "business_phone": "+2348012345678",  "business_email": "ops@northwind.example"}'

Example response

{
  "success": true,
  "data": {
    "id": "3f2c…",
    "type": "business",
    "status": "draft",
    "business_name": "Northwind Trading Ltd",
    "documents": [],
    "stakeholders": []
  }
}

GET/customers/{id}

Scope: customers:read

Retrieve a customer including documents and stakeholders.

Request

curl -X GET "https://api.bitstac.io/api/v1/merchant/customers/3f2c0000-0000-4000-8000-000000000001" \
  -H "Authorization: Bearer $BITSTAC_API_KEY" \
  -H "Accept: application/json"

PATCH/customers/{id}

Scope: customers:write

Update draft (or rejected) customer profile fields.

Request

curl -X PATCH "https://api.bitstac.io/api/v1/merchant/customers/3f2c0000-0000-4000-8000-000000000001" \
  -H "Authorization: Bearer $BITSTAC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{  "business_phone": "+2348099999999"}'

POST/customers/{id}/documents

Scope: customers:write

Upload or replace a KYB document (multipart). Max 5MB; PDF/JPEG/PNG.

Request

curl -X POST "https://api.bitstac.io/api/v1/merchant/customers/3f2c0000-0000-4000-8000-000000000001/documents" \
  -H "Authorization: Bearer $BITSTAC_API_KEY" \
  -F "document_type=cac" \
  -F "file=@./cac.pdf"

Example response

{
  "success": true,
  "data": {
    "id": "…",
    "document_type": "cac",
    "status": "uploaded",
    "has_file": true
  }
}

POST/customers/{id}/stakeholders

Scope: customers:write

Create or update a stakeholder (multipart). Pass id to update an existing stakeholder.

Multipart fields

Required: full_name, email, role, identity_document, address_document
Optional: id, date_of_birth, nationality, percentage, bvn (11), nin (11), residence fields, identity_document_type

Request

curl -X POST "https://api.bitstac.io/api/v1/merchant/customers/3f2c0000-0000-4000-8000-000000000001/stakeholders" \
  -H "Authorization: Bearer $BITSTAC_API_KEY" \
  -F "full_name=Ada Okafor" \
  -F "email=ada@northwind.example" \
  -F "role=director" \
  -F "percentage=40" \
  -F "bvn=22123456789" \
  -F "nin=12345678901" \
  -F "identity_document_type=national_id" \
  -F "identity_document=@./id.pdf" \
  -F "address_document=@./address.pdf"

POST/customers/{id}/submit

Scope: customers:write

Submit a complete KYB package for review. Moves status to under_review when the checklist passes.

Request

curl -X POST "https://api.bitstac.io/api/v1/merchant/customers/3f2c0000-0000-4000-8000-000000000001/submit" \
  -H "Authorization: Bearer $BITSTAC_API_KEY" \
  -H "Accept: application/json"

Example response

{
  "success": true,
  "data": {
    "id": "3f2c…",
    "status": "under_review",
    "submitted_at": "2026-07-26T12:30:00.000000Z"
  }
}