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.
0001-0099
Code | Message | Description |
---|---|---|
BVNK:PAYMENT:0001 | 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. | |
BVNK:PAYMENT:0002 | The system could not locate the requested payout using the provided ID. Verify that the payout ID is correct and exists in the system. | |
BVNK:PAYMENT:0003 | The request was rejected due to authentication failure. Ensure your API keys, tokens, or credentials are valid and correctly included in the request header. | |
BVNK:PAYMENT:0008 | The payment method specified in the request is not currently supported by the platform. Review the documentation for a list of supported payment methods. |
Code | Message | Description |
---|---|---|
BVNK:FEES:0001 | 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 | The system couldn't find the specified wallet associated with the requested account. Verify that the wallet exists and is correctly linked to the account. | |
BVNK:FEES:0003 | 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 authorised to perform this action | Error given when a payment was attempted using API keys that did not have withdrawals enabled, or was requested from a non-whitelisted IP. New keys are needed with the relevant permissions. |
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 | Error given when a payment was attempted using one or more parameters with the incorrect format. Parameter to change is given in the parameter field. |
MER-PAY-2001 | amount x.xx <currency> failed is less than minimum limit of x.xx <currency> | Error given when a payment was below the minimum threshold amount set for the account, the payment amount needs to be increased. |
MER-PAY-2001 | amount x.xx <currency> failed validation as it is over max limit x.xx <currency> | Error given when a payment was above the maximum threshold amount set for the account, the payment amount needs to be decreased. |
MER-PAY-2002 | exchange quote <id> for payment <id> does not exist | Error given when a quote that is accepted by the end customer cannot be found. |
MER-PAY-2003 | exchange quote <id> for payment <id> has status ACCEPTED so cannot be accepted | Error given when a quote that is accepted by an end customer has already been accepted. |
MER-PAY-2004 | payment has expired | Error given when a quote that is accepted by an end customer has expired. a new quote needs to be issued. |
MER-PAY-2005 | address <address> has failed validation for currency: <currency>, protocol: <protocol> and tag: <tag> | Error given when a supplied wallet address fails validation. Could be due to wrong address format or providing the incorrect protocol, ie issuing a TRC20 payment to an ERC20 address. |
MER-PAY-2006 | merchant not found | Error given when the Merchant ID given in the payment request cannot be found on the account. |
MER-PAY-2008 | payment with external id <id> could not be found | Error given when the payment ID could not be found. |
MER-PAY-2009 | invalid request message | Error given when the JSON payload of a request is not valid syntax. |
MER-PAY-2010 | <reference> value already exists | Error given when a payment was already created using this reference. All references need to be unique. |
MER-PAY-2011 | currency <currency> is disabled | Error given when creating a payment with a currency is disabled and is not available for trade. |
MER-PAY-2012 | insufficient funds. | Error given when there is too little funds in the associated wallet to allow for the withdrawal. |
MER-PAY-2014 | exchange quote <id> for payment <id> can no longer be accepted as acceptance has expired | Error given when a quote is accepted, after it has expired. |
MER-PAY-2015 | crypto instruction not found for payment <id> | Error given when the crypto payout instructions are not present on a payout. |
MER-PAY-2016 | merchant not authorised to perform this action | Error given when a merchant is not authorised to perform the requested action. |
MER-PAY-2017 | cannot cancel payment with external id <id> and status PROCESSING | Error given when an attempt to cancel a payment does not have the status COMPLETE or PENDING. |
MER-PAY-2027 | address <address> has failed validation for currency: <currency>, protocol: <protocol> and tag: <tag> | Error given when 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. | Error given when the crypto payout receive address is rejected because of risk and compliance reasons. |
3000-3999
Code | Message | Description |
---|---|---|
BVNK-3001 | 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 | 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 | 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. |
4001-4999
Code | Message | Description |
---|---|---|
BVNK:LEDGER:4001 | 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 | 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 | 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 | 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. |
5000-5999
Code | Message | Description |
---|---|---|
BVNK:LEDGER:5001 | 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 | 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 | 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 | 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. |