Payments Errors

The Payment API employs standard HTTP response codes to convey the outcome of an API request, whether it was successful or encountered an error. In case of an error, the API will provide a comprehensive response that includes detailed information such as the reason for the error, the error code, the title of the error, and the error message itself. This ensures that developers and users can easily identify and understand the nature of the error and take appropriate actions to resolve it.

{
    "type": "error",
    "title": "Parameter not valid.",
    "code": "parameter-not-valid",
    "detail": "Amount value is not valid.",
    "source": {...}
}

The following table provides an overview of the responses and scenarios that are considered as "un-happy paths". Additionally, it provides a detailed description of the underlying reasons behind these scenarios.

Error	code	Title	Detailed reason
Supplying incorrect Amount	parameter-not-valid	Parameter not valid.	The amount needs to be 0.01 or higher
Payer bank branch code is not valid/missing	parameter-not-valid	Parameter value is not valid	The payer account number is invalid/missing. The error of this field being missing would only occur if the payer bank branch code is provided and the account number is not
Payer account number is not valid/missing	parameter-not-valid	Parameter value is not valid	The payee bank branch code is invalid/missing. The error of this field being missing would only occur if the payee account number is provided and the bank branch code is not
Payee account number is not valid/missing	parameter-not-valid	Parameter value is not valid	The payee account number is invalid/missing. The error of this field being missing would only occur if the payee bank branch code is provided and the account number is not
Payout method is not valid	parameter-not-valid	Parameter value is not valid	Payout method is invalid. Valid values are: {fast, batch, fast/batch} Note: method field is optional and can be omitted.
Duplicate request	resource-already-exists	Resource already exists.	The partner application has already submitted a payment with the same requestId
Duplicate request in same bulk request	resource-already-exists	Resource already exists.	The request submitted has one or more request Ids with the same values
Bulk limit exceeded	maximum-count-exceeded.	Maximum count exceeded.	The number of requested payments exceeded the system limit (currently set at 100).
Payments not enabled	payments-not-enabled	Payments not enabled.	The partner application has not be enabled to send payments
Catch all for all other schema errors	invalid-content	Invalid request content	The partner needs to rectify the error(s) in the request and resend. These could be: A missing or incorrect field Format is not followed correctly …others
User not found	resource-not-found	Resource not found.	The user Id supplied cannot be found
User name invalid	invalid-user-name	Invalid user name.	The user referenced has an invalid first and/or last name. First name must have at least 2 letters and last name must have at least 2 letters
User email invalid	invalid-user-email	Invalid user email.	The user referenced has an invalid /missing email name.
Missing payee account details	missing-payee-account-details	Missing Payee account details.	We cannot determine which payee account to use for the referenced payee
Missing payer account details	missing-payer-account-details	Missing Payer account details.	We cannot determine which payer account to use for the referenced payee
External provider unreachable	external-provider-unreachable	External provider unreachable.	An error occurred communicating with the external payment provider after retries have been exhausted
Payment transaction limit reached	transaction-limit-reached	Transaction limit reached	The per transaction limit set on the account within the external provider has been hit. Customer can contact us to agree on new limits if need be.
Daily limit reached	daily-limit-reached	Daily limit reached	The daily limit enforced on the partner has been reached. Customer can contact us to agree on new limits if need be.
Check balance resulted in insufficient funds	check-balance-insufficient-funds	Check balance insufficient funds.	The user account you attempting to debit does not have sufficient funds according to the most recent account balance check Please contact the user to make sure the account has
Account unreachable for checking account balance due to technical reasons	account-unreachable	Account unreachable	The account linked cannot be accessed to check the latest balance
The account balance is outdated (has not been updated in the last 24 hours)	account-balance-outdated	Account balance outdated	The account balance is outdated (has not been updated in the last 24 hours)
Invalid or missing payee user Id	parameter-not-valid	parameter-not-valid	payeeUserId value is not valid.
Invalid of missing payer user Id	parameter-not-valid	parameter-not-valid	payerUserId value is not valid.
Payer account cannot be the same account as the partner’s	payer-account-not-allowed	Payer account details are not allowed	External error.
Debit failed: Refer to Customer	refer_to_customer	Refer to customer	Usually means insufficient funds or that the target account has breached their transaction limits.

For more details, read more about payments here.