Error and Warning 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

🚧
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.