'/%3e%3cdefs%3e%3cpattern%20id='pattern0_2104_4598'%20patternContentUnits='objectBoundingBox'%20width='1'%20height='1'%3e%3cuse%20xlink:href='%23image0_2104_4598'%20transform='matrix(0.00376176%200%200%200.0172414%20-0.00219436%200)'/%3e%3c/pattern%3e%3cimage%20id='image0_2104_4598'%20width='267'%20height='58'%20preserveAspectRatio='none'%20xlink:href='data:image/png;base64,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'/%3e%3c/defs%3e%3c/svg%3e)
Overview
A beneficiary represents an individual or entity added by a customer to receive funds. Beneficiaries are typically used for payouts, transfers, or automated disbursements. This API allows you to create, retrieve, update, list, and delete beneficiaries, enabling smooth management of payout recipients within your system.
Create Beneficiary
Use Case
Create a new beneficiary so the user can save recipient details and use them later for payouts or transfers.
Create Beneficiary Request
A label for the beneficiary, used to identify the recipient in lists and payouts.
The beneficiary type. Must be lowercase: 'bank' or 'crypto'. Determines which destination fields are expected.
For 'bank' beneficiaries: a JSON-encoded string (not a JSON object) containing account_number, bank_code, and account_name.
For a crypto beneficiary, set type to crypto and provide wallet_address, currency, and network instead of destination — e.g. { "name": "...", "type": "crypto", "wallet_address": "0x...", "currency": "USDT", "network": "ethereum" }.
Create Beneficiary Response
Indicates whether the request succeeded.
Human-readable result message.
Unique identifier of the beneficiary, used in get/update calls.
The company that owns the beneficiary (assigned by the server from your credentials).
Beneficiary type: 'bank' or 'crypto'.
The beneficiary label supplied at creation.
For bank beneficiaries, a JSON-encoded string of the bank details (account_number, bank_code, account_name). Crypto beneficiaries return '{}'.
Crypto beneficiaries only — the destination wallet address.
Crypto beneficiaries only — the asset (e.g. 'USDT').
Crypto beneficiaries only — the chain (e.g. 'ethereum').
Whether the beneficiary is blacklisted and blocked from receiving funds.
Whether the beneficiary is currently active.
ID of the API client/user that created the beneficiary (assigned by the server).
When the beneficiary was created.
When the beneficiary was last updated.
Server time when the response was generated.
Get Beneficiaries
Use Case
Retrieve a list of all beneficiaries associated with a company. This is useful for displaying saved recipients in a dashboard, selecting a beneficiary for transfers or payouts.
Create Beneficiary Response
Indicates whether the API request was successful. `true` means the beneficiaries were retrieved without errors.
A human-readable message describing the result of the operation, useful for display or logging.
The unique identifier of the beneficiary.
The ID of the company that owns the beneficiary, linking the record to the correct company account.
The type of beneficiary, e.g., 'bank'. Determines the method used for transfers or payouts.
The name of the beneficiary. Used for display in lists and to identify the recipient.
An object containing the bank account details of the beneficiary, including `account_name`, `account_number`, and `bank_code`.
The full name of the beneficiary as registered with the bank. Used to verify the account.
The bank account number of the beneficiary, required for processing transfers.
The code identifying the beneficiary's bank, ensuring funds are routed correctly.
Indicates if the beneficiary is blacklisted. Blacklisted beneficiaries cannot receive transfers until unblocked.
Indicates if the beneficiary is currently active. Only active beneficiaries can receive funds.
The ID of the user who created the beneficiary. Useful for auditing and tracking purposes.
The timestamp when the beneficiary was created, formatted in ISO 8601 standard.
The timestamp when the beneficiary was last updated, formatted in ISO 8601 standard.
Total number of beneficiaries available in the system.
The number of beneficiaries returned in this response, useful for pagination.
The starting index of the beneficiaries in this response, useful for pagination.
A unique ID for tracking the API request, useful for debugging or support.
The timestamp when the response was generated, indicating the exact time of the API operation.
Get Beneficiary By ID
Use Case
Retrieve all beneficiaries associated with a company. This allows users to view saved recipients, check account details, verify activation status, and select a beneficiary for transfers or payouts.
Beneficiary Example Payload
The name of the beneficiary or bank. Used to identify the recipient.
The bank account number of the beneficiary. Required for transfers.
The bank code identifying the beneficiary's bank. Ensures funds are routed correctly.
The full name of the beneficiary as registered with the bank.
Indicates if the beneficiary is blacklisted. Blacklisted beneficiaries cannot receive transfers.
Get Beneficiary By ID Response
Indicates whether the API request was successful. `true` means the beneficiary was updated successfully.
A human-readable message describing the result of the operation.
The unique identifier of the updated beneficiary.
The ID of the company associated with the beneficiary.
The type of beneficiary, e.g., 'bank'.
The name of the beneficiary or bank. Used to identify the recipient.
The full name of the beneficiary as registered with the bank.
The bank account number of the beneficiary.
The code identifying the beneficiary's bank.
Indicates if the beneficiary is blacklisted. Blacklisted beneficiaries cannot receive transfers.
Indicates if the beneficiary is currently active. Only active beneficiaries can receive funds.
The ID of the user who created the beneficiary.
The timestamp when the beneficiary was created.
The timestamp when the beneficiary was last updated.
A unique ID for tracking the API request.
The timestamp when the response was generated.
Webhooks
Learn how to listen for transactions that happen on your account
A webhook is a URL on your server where we send payloads for transaction events. For example, if you implement webhooks, we will immediately notify your server with a btc.lightning.received.success event Once a lightning payment is received. Whenever you receive a webhook notification from us, return a 200 OK to avoid resending the same event again from our server.
Verifying Events
Verifying that these events come from Bitnob is necessary to avoid creating transactions due to a fraudulent event.
To verify events, validate the x-bitnob-signature header sent with the event. The HMAC SHA512 signature is the event payload signed with your secret key.
Notification Retries
When posting notifications, we expect to receive a 200 response code from you. If the response code is not 200, we retry sending the event 3 times after the first failure.
This way, whenever you experience downtime on your end, your updates will still be sent.
Don't rely on webhooks entirely
We recommend that you set up a service to always query transactions, in the event that webhooks keep failing.
Testing Webhooks
Since notifications must always be available on a publicly accessible URL, you are likely to run into issues while starting to build your application in a local environment. You can easily get around this by using a tool like ngrok or localtunnel
Create a tunnel, and update the new webhook URL setting on your dashboard. Only do this in your test environment to avoid leaking data to the public.
Beneficiary Webhooks
Beneficiary webhooks are fired when a customers adds a beneficiary
This webhook is fired when a created beneficiary is ready to receive funds.
The name of the webhook event that was triggered. In this case, it indicates that a beneficiary's status has changed (e.g., 'beneficiary.status.changed').
A unique identifier for the beneficiary object. This ID can be used to retrieve more details about the beneficiary or to reconcile data with your internal records.
Represents the current state of the beneficiary. For example, 'pending' if the beneficiary is being processed, or 'success' if the beneficiary is ready to receive funds.
A unique string used to link this webhook notification to the original beneficiary creation request.
An optional URL that was provided during the beneficiary creation process for receiving callbacks. If set, the system may attempt to notify this URL after processing is complete. If not provided, this will be null.
The unique identifier of the company to which the beneficiary belongs. This value can help you ensure the webhook data is scoped correctly to the right organization within a multi-tenant system.
Beneficiary Status Pending
This webhook is fired immediately after a new beneficiary is added.
Indicates the type of webhook event triggered. In this case, it signifies that the beneficiary status is in a 'pending' state after being added.
The unique identifier of the company that owns or initiated the creation of the beneficiary.
A unique identifier assigned to the newly added beneficiary for tracking and reference purposes.
A unique reference string used to trace and identify the specific beneficiary setup request.
Represents the current status of the beneficiary setup. Typically set to 'pending' at this stage until processing is complete.
Beneficiary Status Success
This webhook is fired when the beneficiary has been added successfully.
Specifies the webhook event type. In this case, it confirms the beneficiary was successfully added.
A unique identifier for the company that owns or added the beneficiary.
The unique ID assigned to the beneficiary. Useful for lookup or future reference.
A unique string used to track and identify the beneficiary setup request.
The current state of the beneficiary. For successful creation, this will be 'success'.
An optional URL provided to receive asynchronous updates about the beneficiary setup outcome.