Skip to main content
This guide provides a technical walkthrough on programmatically verifying a customer account using the Busha API.
What You’ll Achieve:
  1. Update customer profile with KYC/KYB documents.
  2. Successfully verify your customer identity.
  3. Monitor verification status changes.

​
Prerequisites

Before you begin, ensure you have:

​
Verifying Customer Identity (KYC/KYB)

1

Submit Customer KYC/KYB Documents

Skip this step if verification documents were attached when creating the customer.
The core requirement for verifying a customer is the completed upload of identification documents.
Files uploaded for KYC/KYB must be in Base64 format and have a file size less than 4MB.
Individual customerFor individual customers, you must provide ONE of the following combinations in the identifying_information array:Option 1: Passport + Selfie
"identifying_information": [
  {
    "type": "passport",
    "number": "A12345678",
    "country": "NG",
    "image_front": "{{base64 encoded passport image}}"
  },
  {
    "type": "selfie",
    "image_front": "{{base64 encoded selfie image}}",
    "number": "",
    "country": "NG"
  }
]
Option 2: National ID + Selfie
"identifying_information": [
  {
    "type": "national-id",
    "number": "12345678901",
    "country": "NG",
    "image_front": "{{base64 encoded ID front}}",
    "image_back": "{{base64 encoded ID back}}"
  },
  {
    "type": "selfie",
    "image_front": "{{base64 encoded selfie image}}",
    "number": "",
    "country": "NG"
  }
]
CountryDocuments Required
Nigeria
  • NIN slip and selfie image
  • National passport and selfie image
  • Driver’s license and selfie image
Kenya
  • National ID and selfie image
To update an individual customer with their verification documents:
  1. Open your terminal or command prompt.
  2. Use the PUT request below to the /v1/customers/{customer_id} endpoint.
  3. Replace {customer_id} with the customer ID.
  4. Replace YOUR_BASE_URL with your chosen environment’s URL and {YOUR_SECRET_KEY} with your actual key.
  5. Replace the values in the identifying_information array with the customer documents.
Example with Passport + Selfie:
$ curl -i -X PUT https://YOUR_BASE_URL/v1/customers/{customer_id} \
  -H 'Authorization: Bearer {YOUR_SECRET_KEY}' \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "customer@gmail.com",
    "first_name": "John",
    "last_name": "Doe",
    "has_accepted_terms": true,
    "type": "individual",
    "country_id": "NG",
    "phone": "+234 8012345678",
    "birth_date": "15-06-1990",
    "address": {
      "city": "Lagos",
      "state": "Lagos",
      "country_id": "NG",
      "address_line_1": "10 Allen Avenue",
      "postal_code": "100001"
    },
    "identifying_information": [
      {
        "type": "passport",
        "number": "A12345678",
        "country": "NG",
        "image_front": "{{base64 string}}"
      },
      {
        "type": "selfie",
        "image_front": "{{base64 string}}",
        "number": "",
        "country": "NG"
      }
    ]
  }'
Example with National ID + Selfie:
$ curl -i -X PUT https://YOUR_BASE_URL/v1/customers/{customer_id} \
  -H 'Authorization: Bearer {YOUR_SECRET_KEY}' \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "customer@gmail.com",
    "first_name": "John",
    "last_name": "Doe",
    "has_accepted_terms": true,
    "type": "individual",
    "country_id": "NG",
    "phone": "+234 8012345678",
    "birth_date": "15-06-1990",
    "address": {
      "city": "Lagos",
      "state": "Lagos",
      "country_id": "NG",
      "address_line_1": "10 Allen Avenue",
      "postal_code": "100001"
    },
    "identifying_information": [
      {
        "type": "national-id",
        "number": "12345678901",
        "country": "NG",
        "image_front": "{{base64 string}}",
        "image_back": "{{base64 string}}"
      },
      {
        "type": "selfie",
        "image_front": "{{base64 string}}",
        "number": "",
        "country": "NG"
      }
    ]
  }'
Business customerFor business customers, the KYB documents and sections required are:Documents:
  • Certificate of Incorporation
  • Corporate registry extract
  • Memorandum of Association articles (memart)
  • Corporate structure chart
  • Board resolution
  • Anti-money laundering policy
  • Regulatory licenses
  • Proof of wealth
  • Proof of address
Required Sections:
  • Business Owners - Directors and beneficial owners information
  • Business Transaction - Expected transaction patterns and volumes
  • Business Registration - Legal and regulatory details
To update a business customer with complete KYB information:
  1. Open your terminal or command prompt.
  2. Use the PUT request below to the /v1/customers/{customer_id} endpoint.
  3. Replace {customer_id} with the customer ID.
  4. Replace YOUR_BASE_URL with your chosen environment’s URL and {YOUR_SECRET_KEY} with your actual key.
  5. Include all required sections and documents.
$ curl -i -X PUT https://YOUR_BASE_URL/v1/customers/{customer_id} \
  -H 'Authorization: Bearer {YOUR_SECRET_KEY}' \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "business@gmail.com",
    "has_accepted_terms": true,
    "type": "business",
    "country_id": "NG",
    "phone": "+234 8012345678",
    "business_name": "ABC Corporation",
    "business_industry": "BIN_C4UvTYR5V8jsOx5LmwQ",
    "business_incorporation_date": "2015-06-15",
    "documents": [
      {
        "purposes": ["certificate_of_incorporation"],
        "file": "{{base64 string}}"
      }
    ],
    "business_owners": [
      {
        "first_name": "John",
        "last_name": "Owner",
        "role": ["director"],
        "percentage_ownership": 100,
        "is_pep": false,
        "nationality": "NG",
        "bvn": "12345678901"
      }
    ],
    "business_transaction": {
      "purpose": "international trade",
      "monthly_transaction_value": "above_1m_usd",
      "monthly_transaction_count": "100_to_200",
      "client_transaction_status": "self-owned",
      "api_access_needed": true,
      "api_integration_url": "https://yourbusiness.com"
    },
    "business_registration": {
      "business_type": "type_registered_company",
      "business_structure": "limited_liability_company",
      "business_regulation_status": "regulated",
      "registration_number": "RC1234567",
      "tax_identification_number": "TIN1234567",
      "corporate_group_status": "standalone_company",
      "exchange_listing_status": "not_listed_on_exchange",
      "license_number": "LIC123456"
    }
  }'
2

Verify the Customer

After uploading all required documents and information, call the verify endpoint to submit the customer for verification.To verify the customer:
  1. Open your terminal or command prompt.
  2. Use the POST request below to the /v1/customers/{customer_id}/verify endpoint.
  3. Replace {customer_id} with the customer ID.
  4. Replace YOUR_BASE_URL with your chosen environment’s URL and {YOUR_SECRET_KEY} with your actual key.
    $ curl -i -X POST "https://YOUR_BASE_URL/v1/customers/{customer_id}/verify" \
      -H 'Authorization: Bearer {YOUR_SECRET_KEY}'
Expected ResponseA successful response indicates the verification request has been submitted:
{
  "status": "success",
  "message": "Customer verified successfully"
}
After calling the verify endpoint, the customer status will change from inactive to in_review. You’ll receive webhook notifications as the verification progresses.
3

Check Verification Status

Monitor the customer’s verification status by retrieving their details:
    $ curl -i -X GET "https://YOUR_BASE_URL/v1/customers/{customer_id}" \
      -H 'Authorization: Bearer {YOUR_SECRET_KEY}'
Customer Status Values:
  • inactive - Customer created but not yet verified
  • in_review - Verification documents submitted and under review
  • active - Customer verified and can perform transactions
  • rejected - Verification failed (check rejection reason)
Example Response:
{
  "status": "success",
  "message": "Fetched customer successfully",
  "data": {
    "id": "CUS_Ikdb49NLsnlYU",
    "email": "customer@gmail.com",
    "first_name": "John",
    "last_name": "Doe",
    "type": "individual",
    "status": "in_review",
    "level": "0",
    "created_at": "2026-01-27T09:23:09.317273Z",
    "updated_at": "2026-01-27T09:26:34.537881Z"
  }
}
4

Monitor Verification via Webhooks (Recommended)

Set up webhooks to receive real-time notifications about verification status changes. See Webhook Events for available customer verification events:
  • customer.verification.in_review - Verification submitted
  • customer.verification.active - Verification approved
  • customer.verification.rejected - Verification failed
  • customer.verification.inactive - Verification reverted
Example Webhook Payload:
{
  "business_id": "BUS_CQr0jPzGGzmn1uW5W7OVs",
  "event": "customer.verification.in_review",
  "data": {
    "id": "CUS_Ikdb49NLsnlYU",
    "business_id": "BUS_CQr0jPzGGzmn1uW5W7OVs",
    "business_name": "",
    "first_name": "John",
    "last_name": "Doe",
    "email": "customer@gmail.com",
    "type": "individual",
    "status": "in_review",
    "level": "0",
    "created_at": "2026-01-27T09:23:09.317273Z"
  }
}
Learn how to set up webhooks in the Webhooks Guide.

​
Common Verification Errors

Individual Customers: 
{
  "error": {
    "name": "profile_kyc_verification",
    "message": "KYC document does not contain a selfie image"
  }
}
Solution: Ensure the identifying_information array includes a selfie object with type: "selfie" and image_front containing a base64 encoded selfie image. Business Customers: 
{
  "error": {
    "name": "missing_section",
    "message": "Owners section must be completed before final submission"
  }
}
Solution: Add the business_owners array with at least one owner/director. 
{
  "error": {
    "name": "missing_section",
    "message": "Transaction section must be completed before final submission"
  }
}
Solution: Add the business_transaction object with transaction details.

​
Troubleshooting

  • 400 Bad Request / 422 Unprocessable Entity: Review your request body to ensure all required fields are present and correctly formatted.
  • 401 Unauthorized: Verify that your Secret API Key is correct and included in the header.
  • missing_section errors: For business customers, ensure all three sections (owners, transaction, registration) are complete before verification.
  • profile_kyc_verification errors: For individual customers, ensure all required documents (ID images and selfie image) are uploaded in the identifying_information array.

​
What’s Next?

Now that you can programmatically verify customers, you can proceed to perform transactions on their behalf: