Error Dictionary

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.

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

🚧
If you come across any errors mentioned in this section, it means your payment or transaction attempt has failed. These errors trigger a system response that blocks the transaction at the API level, preventing it from proceeding. As a result, the transaction won't go through, and you won't see any record of this failed attempt in 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.