Busha Developer Documentation

July 2026

2026/07/06

Changed: NIN Verification Flow for Individual Customers

NIN verification is now a non-document flow. When verifying customers with a Nigerian National Identification Number (NIN), you no longer need to upload ID document images only the NIN number and a selfie are required.What changed:

Removed: image_front and image_back from the national-id object in identifying_information
Unchanged: Passport verification and selfie requirements remain the same

Updated guides:

Reference payload:

"identifying_information": [
  {
    "type": "national-id",
    "number": "12345678901",
    "country": "NG"
  },
  {
    "type": "selfie",
    "image_front": "{{base64 encoded selfie image}}",
    "number": "",
    "country": "NG"
  }
]

May 2026

2026/05/22

New: Busha Pay Mobile SDKs for React Native, iOS, Android, and Flutter

Busha Pay is now available as a native mobile SDK for React Native, iOS (Swift), Android (Kotlin), and Flutter, enabling crypto checkout directly within your mobile app.

React Native — @busha/pay-react-native via npm or GitHub releases
iOS (Swift) — BushaPay via Swift Package Manager
Android (Kotlin) — pay-android via JitPack
Flutter — busha_pay via pub.dev

New guide: Accept Stablecoin with Mobile SDK

2026/05/06

Removed: dry_run Parameter from Payment Requests

Page: guides/payment-requests/create-first-payment
Removed the dry_run parameter from the POST /v1/payments/requests endpoint. The field is no longer accepted or documented. Developers previously using dry_run: true to preview payment request calculations should remove the field from their request bodies requests will now be created and persisted regardless.

April 2026

2026/04/26

New Filter: quote_id on List Transfers Endpoint

Added quote_id as a query parameter on the GET /v1/transfers endpoint, allowing you to retrieve the transfer associated with a specific quote.New query parameter:

quote_id: Filter transfers by the quote used to create them.

Example:

curl -X GET "https://api.busha.io/v1/transfers?quote_id=QUO_xxxxxxxxxx" \
  -H "Authorization: Bearer YOUR_SECRET_KEY"

Example response:

{
  "status": "success",
  "message": "Fetched transfers successfully",
  "data": [
    {
      "id": "TRF_xxxxxxxxxx",
      "quote_id": "QUO_xxxxxxxxxx",
      ...
    }
  ]
}

March 2026

2026/03/27

New Field: kyc_status in customers endpoints

Introduced the kyc_status field in the GET /customers and GET /customers/{id} endpoints to allow businesses to check the KYC verification status of their customers.New field:

kyc_status: Returns the current KYC verification state of the customer. Possible values: pending, in_review, verified, rejected.

For example:

{
  "id": "CUS_9z8y7x6w5v4u3t2s1r",
  "email": "john@example.com",
  "first_name": "John",
  "last_name": "Doe",
  "phone_number": "+234 8012345678",
  "kyc_status": "verified", // customer has completed KYC verification
  "created_at": "2026-03-15T10:30:00Z"
}

In the response above, the kyc_status field shows that the customer has successfully completed KYC verification, allowing you to programmatically gate features or transaction limits based on their verification level.

2026/03/06

New Webhook Event: deposit.success

Introduced deposit.success webhook event to notify you when deposits are made to your static bank account.Use case:This event enables you to automatically convert incoming fiat deposits to your preferred stablecoin using the Quotes and Transfers endpoints.How it works:

Customer deposits funds to your static bank account
deposit.success webhook event is triggered
Your system receives the webhook notification
You can automatically create a quote and transfer to convert the deposited amount to crypto

Event payload example:

{
  "business_id": "bus_1a2b3c4d5e6f7g8h9i0j",
  "event": "deposit.success",
  "data": {
    "id": "289bb2c1-b4fc-46df-b313-6945a8d23615",
    "profile_id": "CUS_9z8y7x6w5v4u3t2s1r",
    "amount": "5900.00",
    "fee": "100.00",
    "total": "6000.00",
    "currency": "NGN",
    "reference": "Resf12dx3c333333",
    "channel": "bank_transfer",
    "status": "COMPLETED",
    "source_account_name": "Test Oluwatoni",
    "source_bank_name": "Bank of World",
    "source_account_number": "1234567890",
    "reserved_account_id": "8d1c58b0-9143-410b-be61-805e8421c466",
    "account_name": "ARTAX DIGITAL / Oluwatoni Test",
    "account_number": "4051483002",
    "created_at": "2025-02-26T11:29:02.336285+01:00"
  }
}

Key fields:

amount: The deposited amount (after fees)
fee: The deposit fee charged
total: The total amount deposited (before fees)
currency: The currency of the deposit (e.g., NGN, KES)
status: Deposit status (COMPLETED)
profile_id: The customer ID who made the deposit

Important: To start receiving this event, you must re-register your webhook:

Navigate to Settings → Developer Tools → Webhooks in your Busha dashboard
Delete your existing webhook endpoint
Create a new webhook and select the deposit event along with any other events you want to subscribe to
Save your new webhook configuration

2026/03/04

Selfie Image for Individual Customer KYC

Updated KYC requirements for individual customers. The identifying_information field now requires a selfie image instead of a selfie video.What changed:

Removed: documents array with selfie video requirement
Added: Selfie image object in identifying_information array
Required combinations: Customers must provide ONE of the following:
- Passport + number + image_front + selfie image
- National ID + number + image_front + image_back + selfie image

Identifying information object structure:

"identifying_information": [
    {
      "type": "passport",
      "number": "passport-number",
      "country": "NG",
      "image_front": "",
      "image_back": ""
    },
    {
      "type": "selfie",
      "image_front": "",
      "number": "",
      "country": "NG"
    }
  ]

February 2026

2026/02/27

API Request Logs

Added request logs feature to help businesses monitor and debug API activity. View detailed logs of API requests made to Busha directly from your dashboard.What you can see:

Status code: HTTP response status
HTTP method: Request type
Endpoint: The specific API endpoint called
Request ID: Unique identifier for each request
Timestamp: Date of each request

Features:

Search by Request ID: Quickly find specific requests using the search bar
Filter options: Narrow down logs by various criteria
Pagination: Browse through your request history
Auto-refresh: Logs update automatically as new requests are made

How to access:Navigate to Settings → Developer Tools → Request Logs in your Busha dashboard.

2026/02/24

Reversal Policy for Quote Cancellations

Introduced the reversal_policy field in quote object to control how cancelled/failed transfers are refunded.New field:

reversal_policy: An optional field set to "conversion_only" to refund the original source amount to the source balance in the event of a transfer failure. The field accepts conversion_only value for now.

For example:

{
  "source_currency": "USDT",
  "target_currency": "NGN",
  "source_amount": "100",
  "reversal_policy": "conversion_only", // refund the transfer back to USDT if the quote transfer fails.
  "pay_in": {
    "type": "address",
    "network": "SOL"
  },
  "pay_out": {
    "type": "bank_transfer",
    "recipient_id": "625syssysts8388"
  }
}

In the quote above, the originating transfer will refund the source amount of 100 to the business source (USDT) balance if the transfer goes into a refunded state either from cancellation or failure to complete its lifecycle.

2026/02/23

Webhook Event History & Replay

Added webhook event history and replay functionality in the Busha dashboard. Businesses can now view, monitor, and resend past webhook events for the last 21 days.Key features:

Event History: View all webhook events from the last 21 days with full request/response details
Manual Replay: Resend failed or missed webhook events directly from the dashboard
Search & Filter: Find specific events by reference ID, status, category, or date
Delivery Tracking: Monitor webhook delivery success and failure rates
Debugging Tools: Inspect exact payloads sent for troubleshooting integration issues

How to access: Navigate to Settings → Developer Tools → Webhooks in your Busha dashboard, then click on a webhook to view its activity log.

2026/02/18

Request IDs in API Responses

All API endpoints now return a unique request identifier in the response headers under X-Request-Id. Request IDs help track specific API calls and expedite issue resolution when contacting Busha support.Key details:

Header name: X-Request-Id
Format: req_ prefix followed by alphanumeric string (e.g., req_JfPBXEC5rLHc)
Availability: All endpoints
Retention: 21 days

New guide: guides/request-id/request-id explains how to capture request IDs in your code and when to use them for debugging.Use request IDs to provide precise details when reporting API errors or unexpected behavior to Busha support.

2026/02/10

Obsolete Recipient Code Snippets Removed

Page: guides/recipients/create-and-manage
Deleted legacy code examples that no longer match the current API surface. - Removed the deprecated X-BU-VERSION header from sample requests so developers copying the guide use headers the API actually accepts.

2026/02/04

Transfer Webhook Event: transfer.funds_refunded

Added the transfer.funds_refunded event in guides/webhooks/webhook-events. This event fires when funds are returned to the sender’s balance after a transfer fails (for example, an invalid payout destination or network delivery issue).

Event	Trigger	Key Payload Fields
`transfer.funds_refunded`	Funds are refunded to the balance following a failed transfer.	`status: "funds_refunded"`, `fees` (array with refund-related fees), `pay_out` (original destination details), `updated_at`

Use this event to automatically reconcile balances, notify users that their funds have been returned, or trigger retry logic.

Transfers Overview Update

Page: overview/transfers - Added funds_refunded to the list of possible transfer statuses so integrators know this terminal state exists.

January 2026

2026/01/30

Sandbox Setup Guide Update

Page: guides/getting-started/setup-sandbox
Updated the sandbox account registration link to point to the current developer console URL. - Refreshed the onboarding steps so new integrators land on the correct dashboard and can generate API keys without confusion.

2026/01/28

Delegated Transactions Guide Update

Page: guides/customers/transactions-on-behalf
Adjusted usage scenarios and parameter descriptions to stay accurate for delegated (on-behalf-of) transaction flows. - Ensured code samples reflect the latest required headers and request body shape.

2026/01/27

Comprehensive Customer Documentation Updates

The following guides under guides/customers/ have been completely rewritten to improve clarity and align with current API behavior:

Page	Summary of Changes
`Create business`	Expanded KYB (Know Your Business) workflow documentation, added field-by-field explanations for required business registration data, and included sample request/response payloads that match the live API.
`Create individual`	Overhauled KYC (Know Your Customer) instructions with step-by-step guidance, clearer document-upload requirements, and updated example payloads reflecting actual field names and validation rules.
`Verify identity`	Clarified the verification lifecycle (from `inactive` → `in_review` → `active` or `rejected`), documented each possible status transition, and explained how to interpret verification outcomes programmatically.

Four New Webhook Events for Customer Verification

Added comprehensive webhook coverage in guides/webhooks/webhook-events. The following four events are now documented with full sample payloads, trigger conditions, and recommended handling patterns:

Event	Trigger	Key Payload Fields
`customer.verification.in_review`	Customer submits verification documents and review begins.	`status: "in_review"`, `level: "0"`, `updated_at`
`customer.verification.active`	Review succeeds; customer is fully verified.	`status: "active"`, `level: "1"`, `updated_at`
`customer.verification.rejected`	Review fails due to invalid or incomplete documents.	`status: "rejected"`, `rejection_reason`, `level: "0"`, `updated_at`
`customer.verification.inactive`	Verification reverted (compliance issue, suspension, etc.).	`status: "inactive"`, `level: "0"`, `updated_at`

Each event follows the standard webhook envelope (business_id, event, data) and can be used to automate customer onboarding workflows, surface rejection reasons to end-users, or trigger compliance alerts.

Release Notes

Changelog

July 2026

2026/07/06

May 2026

2026/05/22

2026/05/06

April 2026

2026/04/26

March 2026

2026/03/27

2026/03/06

2026/03/04

February 2026

2026/02/27

2026/02/24

2026/02/23

2026/02/18

2026/02/10

2026/02/04

January 2026

2026/01/30

2026/01/28

2026/01/27

​July 2026

​2026/07/06

​May 2026

​2026/05/22

​2026/05/06

​April 2026

​2026/04/26

​March 2026

​2026/03/27

​2026/03/06

​2026/03/04

​February 2026

​2026/02/27

​2026/02/24

​2026/02/23

​2026/02/18

​2026/02/10

​2026/02/04

​January 2026

​2026/01/30

​2026/01/28

​2026/01/27

July 2026

2026/07/06

May 2026

2026/05/22

2026/05/06

April 2026

2026/04/26

March 2026

2026/03/27

2026/03/06

2026/03/04

February 2026

2026/02/27

2026/02/24

2026/02/23

2026/02/18

2026/02/10

2026/02/04

January 2026

2026/01/30

2026/01/28

2026/01/27