The BVNK API responds with detailed information in the event of a failed request. Below is a comprehensive list of payment error codes, along with brief descriptions on how to address them. This resource serves as a valuable reference for developers, enabling them to efficiently troubleshoot and address errors in their applications' integration with BVNK's API.
Error codes categories
- 1xxx: Authentication & Authorization errors
- 2xxx: Client errors (validation, not found, business logic)
- 3xxx: Internal service errors (contact administrator)
- 4xxx: Internal service errors (contact administrator)
0001-0099
Fiat payouts
| Code | Message | Description |
|---|---|---|
| BVNK:PAYMENT:0001 | Received Bad Request | The system received a request with invalid parameters or missing required information. Check the request format, parameters, and ensure all required fields are correctly filled. |
| BVNK:PAYMENT:0002 | Payout with the given identifier could not be found | The system was unable to locate the requested payout using the provided ID. Verify that the payout ID is correct and exists in the system. |
| BVNK:PAYMENT:0003 | Forbidden → received request with wrong authentication details | The request was rejected due to an authentication failure. Ensure your API keys, tokens, or credentials are valid and correctly included in the request header. |
| BVNK:PAYMENT:0004 | Error while receiving or validating beneficiary | The beneficiary details could not be retrieved, or failed validation checks. This may occur due to missing or malformed fields (name, address, account identifiers), failed KYC/KYB or sanctions screening, or temporary downstream connectivity errors. Verify beneficiary data to ensure the required fields and formats (e.g., IBAN/ABA) are accurate. Confirm the beneficiary is allowed, and retry once issues are resolved. |
| BVNK:PAYMENT:0005 | Validation of the beneficiary has failed | The beneficiary did not pass mandatory validation rules. Typical reasons include invalid account identifiers, an unsupported destination, a mismatched currency/network, or a compliance screening failure. Correct the beneficiary information (names, address, account numbers, tags/memos where required) or select a different, validated beneficiary before retrying. |
| BVNK:PAYMENT:0006 | Payout with the idempotency key already exists | A payout using the provided idempotency key already exists. For idempotent safety, the platform rejects creating a new payout with the same key. If you intend to retry the same request, use the original response; otherwise, generate a new, unique idempotency key for a new payout. |
| BVNK:PAYMENT:0008 | The payment method is not supported | The platform does not currently support the payment method specified in the request. Review the documentation for a list of supported payment methods. |
| BVNK:PAYMENT:0009 | Specific functionality is not enabled for this account or wallet | The specific functionality or flow is not enabled or provisioned for this account or wallet. Check your permissions and product enablement. If the feature is available, enable it in the portal; otherwise, contact support to request access. |
| BVNK:PAYMENT:0010 | The Virtual Account has been disabled for this given wallet. Customer should use a different wallet or choose different payment method. | The Virtual Account assigned to the specified wallet is disabled. Use a different wallet or select an alternative payment method. If you need this Virtual Account re-enabled, review the wallet configuration and contact support or your account manager. |
| Mass Payouts | ||
| BVNK:PAYMENT:0030 | Could not find a single payment within a given payout batch | The referenced payout batch contains no payments matching your query, or the payments have not been associated with the batch yet. Verify the payout batch identifier, ensure the batch was created successfully, and confirm that items were added and not removed by validation. If you are filtering, check the date/status filters to ensure you are querying the correct environment (sandbox vs. production). |
| BVNK:PAYMENT:0031 | Could not find specific payout batch | The payout batch could not be located. The batch identifier may be invalid, belong to another account, or the batch may have been archived/expired. Double-check the batch ID/token and your account permissions, then try again. If the batch was created recently, allow a short delay and retry. |
| BVNK:PAYMENT:0032 | Cannot delete a single payout from a batch, as it has started processing already | Once batch processing has started, individual payouts become immutable. Deletions are only permitted while the batch is in a pre‑processing state. To remove items, cancel the whole batch if supported, or create a new batch without the unwanted payout. |
| BVNK:PAYMENT:0033 | Cannot update a single payout from a batch, as it has started processing already | Individual payout updates are blocked after batch processing begins. Modify items only before submission. If you need changes, cancel the batch (where supported) and recreate it with corrected payout details, or submit a follow‑up adjustment as a new payout. |
Fees
| Code | Message | Description |
|---|---|---|
| BVNK:FEES:0001 | Invalid wallet selected on client request. | The wallet selected in the client request is invalid. Check that the wallet identifier is correctly formatted and belongs to a valid wallet type. |
| BVNK:FEES:0002 | Provided wallet not found for a specific account. | The system was unable to find the specified wallet associated with the requested account. Verify that the wallet exists and is correctly linked to the account. |
| BVNK:FEES:0003 | Invalid customer fee wallet configuration. | The customer fee wallet configuration contains invalid settings or parameters. Review and correct the fee wallet configuration in your account settings. |
1000-1999
These errors are returned in the format below:
{
"code": "MER-PAY-XXXX",
"status": "Forbidden",
"message": <error message>,
"documentLink": ""
}| Code | Message | Description |
|---|---|---|
| MER-PAY-1000 | Not authorized to perform this action | A user or merchant is not authorised to perform the requested action. This can occur due to insufficient permissions or invalid authentication credentials. |
2000-2999
Should you encounter any of the errors outlined in this section, be aware that your payment or transaction attempt will not be successful. The system will reject the transaction at the API level, consequently preventing the creation of a failed transaction record. Therefore, you will not find any evidence of the unsuccessful operation within the merchant portal.
These errors are returned in the format below:
{
“errorList”:
[
{
“code”: "MER-PAY-XXXX",
“parameter”: <parameter causing error>,
“message”: <error message>
}
]
}| Code | Message | Description |
|---|---|---|
| MER-PAY-2000 | Invalid parameter value | The request parameters fail validation. This includes JSON parsing errors, missing required parameters, invalid data types, or constraint violations on request fields. |
| MER-PAY-2001 | Amount x.xx <currency> failed is less than minimum limit of x.xx <currency> | The payment amount fails validation. This occurs when the amount is below the minimum limit or above the maximum limit for the specified currency. |
| MER-PAY-2002 | Payment has no quote | An error occurs when a payment operation requires an exchange quote, but none is found. This typically occurs when attempting to process payments that require currency conversion. |
| MER-PAY-2003 | Exchange quote <id> for payment <id> has status ACCEPTED so cannot be accepted | An error is given when attempting to modify a quote that has already been finalised. Once a quote is in a final state, it cannot be changed. |
| MER-PAY-2004 | Payment has expired | An error occurs when attempting to process a payment that has exceeded its expiration time. Expired payments cannot be processed and need to be recreated. |
| MER-PAY-2005 | Instruction validation failed message | The payment instruction data is invalid. This includes validation failures for payment addresses, amounts, or other instruction-specific parameters. |
| MER-PAY-2006 | Merchant not found | An error occurs when the Merchant ID provided in the payment request cannot be found in the account. |
| MER-PAY-2008 | Payment not found | An error occurs when the payment ID cannot be found. |
| MER-PAY-2009 | Invalid request message | Error given for general request validation failures. |
| MER-PAY-2010 | A payment with reference <reference> already exists. Please enter a unique reference. | An error was given when a payment was already created using this reference. All references need to be unique. |
| MER-PAY-2011 | Currency <currency> is disabled | An error occurs when creating a payment with a disabled currency that is not available for trade. |
| MER-PAY-2012 | Insufficient funds | A wallet does not have sufficient funds to complete the requested transaction. |
| MER-PAY-2014 | Exchange quote <id> for payment <id> can no longer be accepted as acceptance has expired | A quote is accepted after it has expired. |
| MER-PAY-2015 | Crypto instruction not found for payment <id> | A required crypto payment instruction cannot be found for the specified payment. |
| MER-PAY-2016 | Merchant not authorised to perform this action | A merchant is not authorised to perform the requested action. |
| MER-PAY-2017 | Cannot cancel payment with external id <id> and status PROCESSING | An attempt is made to cancel a payment and the status is not COMPLETE or PENDING. |
| MER-PAY-2018 | Resource modified by another request | A concurrent modification conflict arises. This happens when multiple requests attempt to modify the same resource simultaneously. |
| MER-PAY-2019 | Currency <currency> not found | The specified currency is not found in the system. |
| MER-PAY-2024 | protocol <protocol> not found for currency <currency> | The specified protocol is not found or not supported for the given currency. |
| MER-PAY-2025 | Please enter your own wallet address, not the address that you paid into originally. | The provided refund address fails validation checks. |
| MER-PAY-2027 | address <address> has failed validation for currency: <currency>, protocol: <protocol> and tag: <tag> | The crypto payout receive address format is invalid. |
| MER-PAY-2028 | We couldn't process your payout request to this address: <address> this time, please try another address. | The crypto payout receiving address is rejected due to risk and compliance reasons. |
| MER-PAY-2029 | Protocol with code <protocol> not found | The specified protocol code is not found in the system. |
| MER-PAY-2030 | Unable to find protocol <protocol> for currency code <currency> | The specified protocol cannot be found for the given currency code. |
| MER-PAY-2031 | Account not enabled for flow: <flow>. Please check your permissions or contact support for more information. | The account is not enabled for the specific payment flow being requested. |
| MER-PAY-2033 | Multiple protocols found for currency <currency> Please specify which one to use: <protocols>. | Multiple protocols are available for a currency, but no specific protocol is selected, rendering automatic selection impossible. |
| MER-PAY-2035 | mass payout data row validation failed | One or more rows in a mass payout file fail validation checks. |
| MER-PAY-2036 | <rows> payments uploaded. This exceeds the maximum number of <max_rows> rows. Please reduce your file to <max_rows> rows. | A mass payout file contains more rows than the system maximum allows. |
| MER-PAY-2037 | Failed to process mass upload file. File name already exists. | Attempting to upload a mass payout file with a filename that already exists. |
| MER-PAY-2038 | Failed to process mass upload file. File is required. | A required mass payout file is not provided. |
| MER-PAY-2039 | Failed to process mass upload file. One of Merchant id or Wallet id fields have to be provided. | A mass payout request is missing both the required merchant ID and wallet ID parameters. |
| MER-PAY-2040 | Failed to process mass upload file. Header is invalid. | The mass payout file contains invalid or missing required headers. |
| MER-PAY-2041 | Deleting mass payout item with status CREATED is not allowed. | An error is given when attempting to delete a mass payout item that is not in a deletable state. |
| MER-PAY-2042 | Updating mass payout item with status <status> is not allowed. | An error is given when attempting to edit a mass payout item that is not in an editable state. |
| MER-PAY-2043 | One of merchantId or walletId properties have to be provided, both are missing | A request requires a merchant ID or a wallet ID, but neither is provided. |
| MER-PAY-2044 | network <network> not found | The specified blockchain network is not valid or supported. |
| MER-PAY-2045 | Payout details currency <currency> and network <network> mismatch from previously provided currency <currency> and network <network> | The payout details do not match the details previously provided for the estimate. |
| MER-PAY-2046 | protocol not found for currency <currency> and network <network> | The specified protocol and network combination is not valid or supported. |
| MER-PAY-2047 | Estimate cannot be modified. Payment with uuid <uuid> already created for estimate <estimate id>. | An error is given when attempting to accept an estimate that already has an associated payment. |
| MER-PAY-2048 | Failed to process mass upload file. File is empty. | The uploaded mass payout file contains no data rows. |
| MER-PAY-2049 | Recipient address is not associated with a contact. You will assign or add a contact to it on the next step. | The specified contact cannot be found for the given address or criteria. |
| MER-PAY-2050 | Recipient address is associated with more than 1 contact. You'll be asked to choose which contact to use for this transaction. | Multiple matching contacts are found for the provided address. |
| MER-PAY-2051 | Crypto account <crypto account> is not verified. Please verify your crypto account before using it | An error occurs when attempting to use an unverified cryptocurrency account that requires verification. |
| MER-PAY-2052 | This country is unavailable. If you require this region, please reach out to your account manager. | Geographical screening encounters an error or fails due to regional restrictions. |
| MER-PAY-2053 | The payment can not be processed. | Geographical screening determines that the payment cannot be processed due to regional restrictions. |
| MER-PAY-2054 | Payment direction 'IN' is not compatible with flow 'EMBEDDED_CRYPTO' | An error is given when attempting to use an unsupported payment direction with an embedded crypto flow. |
| MER-PAY-2055 | mesh client invalid request message | A request to the mesh client is invalid or malformed. |
| MER-PAY-2056 | Customer not found for reference: <customer reference> | The specified customer cannot be found in the system. |
| MER-PAY-2057 | required header missing | A required HTTP header is missing from the request. |
| MER-PAY-2058 | Cannot confirm/accept payment <uuid> as it has been cancelled | An error is given when attempting to perform operations on a payment that has been cancelled. |
| MER-PAY-2059 | Wallet with ID <walletId> not found | The specified wallet ID does not exist. |
3000-3999
Network
| Code | Message | Description |
|---|---|---|
| BVNK-3001 | Received Bad Request | The system received a request with invalid parameters or missing required information. Check the request format, parameters, and ensure all required fields are properly filled and formatted correctly. |
| BVNK-3003 | Forbidden → received request with wrong authentication details | Access to the requested resource is denied due to authentication failure. Ensure your API keys, tokens, or credentials are valid, correctly included in the request header, and have the necessary permissions to perform this operation. |
| BVNK-3040 | Transfer not found | The requested transfer could not be located in the system. Verify that the transfer identifier is correct and exists within your account. If you recently initiated the transfer, it may still be processing. |
Customers
| Code | Message | Description |
|---|---|---|
| MER-PAY-3003 | Resource not found | Error given when a requested static resource or endpoint cannot be found. |
| MER-PAY-3XXX | Unexpected error - please contact administrator | Error given for unexpected or unhandled exceptions. |
4001-4999
Wallets
| Code | Message | Description |
|---|---|---|
| BVNK:LEDGER:4001 | Received Bad Request | The system received a request with invalid parameters or missing required information. Check the request format, ensure all required fields are properly filled, and validate that parameter values meet the expected format and constraints. |
| BVNK:LEDGER:4003 | FORBIDDEN! You don't have the necessary permissions to access this resource. | Access to the requested resource is denied due to insufficient permissions. This could be due to missing capabilities when creating a customer wallet, or because the customer has been rejected in the system. Verify your account permissions and customer status before retrying. |
| BVNK:LEDGER:4004 | Wallet creation request with the same idempotency key and account reference exists | A wallet creation request with the same idempotency key and account reference already exists in the system. Idempotency keys must be unique for each new wallet creation. Check your records to find the existing wallet or use a new idempotency key for a new wallet. |
| BVNK:LEDGER:4005 | Wallet creation request with missing data, one of the customer reference and external reference has to be provided | The wallet creation request is missing essential identifying information. Either a customer reference or an external reference must be provided in the request. Review your request data and include at least one of these required reference identifiers. |
Customers
| Code | Message | Description |
|---|---|---|
| MER-PAY-4011 | Customer fee wallet not found. Please contact support if you need assistance. | The customer fee wallet has not been set. Configuration error. |
| MER-PAY-4XXX | Unexpected error - please contact administrator | Error given for unexpected or unhandled exceptions. |
Rules
| Error Code | Message | Description |
|---|---|---|
| bvnk:payment:rules:4001 | Wallet configuration already exists | A wallet configuration with the specified parameters already exists in the system. This error occurs when attempting to create a duplicate wallet configuration that conflicts with an existing one. |
| bvnk:payment:rules:4002 | Address validation error | The provided wallet address failed validation checks. This error indicates that the address format is invalid, doesn't match the expected format for the specified network, or contains invalid characters. |
| bvnk:payment:rules:4003 | Invalid currency | The specified currency code is not recognized or supported by the system. Ensure you're using a valid currency identifier that matches the supported currencies for your account. |
| bvnk:payment:rules:4004 | Unsupported network | The blockchain network specified in the request is not supported by the payment rules system. Check the list of supported networks and use a valid network identifier. |
| bvnk:payment:rules:4005 | Invalid party details | The party details provided in the request contain invalid or missing information. This includes issues with party identification, contact information, or other required party-specific data. |
| bvnk:payment:rules:4006 | Data integrity violation | A data integrity constraint has been violated. This error occurs when the provided data conflicts with existing database constraints or business rules that ensure data consistency. |
| bvnk:payment:rules:4007 | Invalid fee type | The fee type specified in the request is not valid or supported. Check the documentation for valid fee type values and ensure you're using the correct fee structure for your configuration. |
| bvnk:payment:rules:4008 | Invalid destination type | The destination type provided is invalid or not supported for the current operation. Verify that you're using a supported destination type for your wallet configuration. |
| bvnk:payment:rules:4016 | Invalid request format | The request format is malformed or contains invalid structure. This error indicates issues with JSON formatting, missing required fields, or incorrect data types in the request payload. |
| bvnk:payment:rules:4009 | Wallet not found | The specified wallet could not be found in the system. Verify that the wallet ID or identifier exists and that you have the necessary permissions to access it. |
| bvnk:payment:rules:4010 | Wallet configuration not found | The requested wallet configuration does not exist. This error occurs when trying to access, modify, or delete a wallet configuration that is not present in the system. |
| bvnk:payment:rules:4011 | Wallet configuration already active | The wallet configuration is already in an active state and cannot be modified or activated again. Check the current status of the configuration before attempting to change it. |
| bvnk:payment:rules:4012 | Currency mismatch | There is a mismatch between the expected currency and the provided currency. Ensure that all currency references in your request are consistent and match the wallet's configured currency. |
| bvnk:payment:rules:4013 | Wallet status validation error | The wallet status validation failed. This error occurs when the current wallet status doesn't allow the requested operation or when the wallet is in an invalid state for the action being performed. |
| bvnk:payment:rules:4014 | Wallet configuration state error | The wallet configuration is in an invalid state for the requested operation. This may occur when trying to perform actions on configurations that are pending, disabled, or in transition states. |
| bvnk:payment:rules:4015 | Invalid customer fee configuration | The customer fee configuration contains invalid parameters or values. Check that fee amounts, percentages, and fee structure parameters are within acceptable ranges and properly formatted. |
5000-5999
Wallets
| Code | Message | Description |
|---|---|---|
| BVNK:LEDGER:5001 | Wallet not found | The requested wallet could not be located in the system. Verify that the wallet identifier is correct and exists within your account. |
| BVNK:LEDGER:5050 | Wallet balance not found | The system could not retrieve balance information for the specified wallet. Ensure the wallet exists and has been properly initialized with a balance. |
| BVNK:LEDGER:5040 | Bad Request | The request contained invalid data, malformed parameters, or violated validation constraints. Review your request format and ensure all required fields contain valid data. |
| BVNK:LEDGER:5051 | Wallet creation failed | The wallet creation process failed to complete successfully. This could be due to system constraints, validation issues, or conflicts with existing data. Check the request details and try again with valid parameters. |
Customers
| Code | Message | Description |
|---|---|---|
| MER-PAY-5001 | The requested wallet could not be located in the system. | Verify that the wallet identifier is correct and exists within your account. |
| MER-PAY-5050 | The system could not retrieve balance information for the specified wallet. | Ensure the wallet exists and has been properly initialized with a balance. |
| MER-PAY-5040 | The request contained invalid data, malformed parameters, or violated validation constraints. | Review your request format and ensure all required fields contain valid data. |
| MER-PAY-5051 | The wallet creation process failed to complete successfully. This could be due to system constraints, validation issues, or conflicts with existing data. | Check the request details and try again with valid parameters. |
Rules
| Code | Message | Description |
|---|---|---|
| bvnk:payment:rules:5001 | Feature not implemented | The requested feature or functionality is not yet implemented in the current version of the payment rules system. This feature may be available in future releases. |
| bvnk:payment:rules:5003 | Wallet validation error | Wallet validation services are currently unavailable. This error indicates a temporary issue with external validation services or network connectivity problems affecting wallet verification. |
| bvnk:payment:rules:5004 | Internal error | An unexpected internal server error occurred while processing the request. This indicates a system-level issue that should be reported to technical support for investigation. |