Errors

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": ""
}

ERROR CODE

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>
      }
    ]
}

ERROR CODE

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.

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.