Asynchronous error codes are returned when payments, mandates, or other operations fail after being initially accepted. These errors occur during the background processing of your requests and are typically delivered through webhooks or can be retrieved by polling the relevant endpoints.
Understanding Error Codes
These error codes provide insight into why an operation failed, helping you understand the root cause and take appropriate action. Common scenarios include:
- Payment failures: When a payment is declined by the bank or fails during settlement
- Account issues: When payer or payee accounts have problems (closed, blocked, insufficient funds)
- Mandate problems: When recurring payment agreements encounter issues
- Data validation: When the bank rejects a transaction due to invalid or incompatible data
Important Considerations
Do not build business logic around specific error codes. These codes may change without notice as we improve our platform and integrate with new banking partners.
While you can use these codes to provide more meaningful error messages to your users, always design your application to handle unknown or unexpected error codes gracefully. Focus on the general category of error rather than specific codes when implementing retry logic or user flows.
Here's a list of common asynchronous error codes you may encounter:
PAYMENTS_ERROR_CODE_PAYER_ACCOUNT_CLOSED: Payer account is closedPAYMENTS_ERROR_CODE_PAYER_ACCOUNT_BLOCKED: Payer account is blockedPAYMENTS_ERROR_CODE_PAYMENT_EXPIRED: We haven't had a response from the bank and have cancelled this attemptPAYMENTS_ERROR_CODE_UNKNOWN: An unknown error occurredPAYMENTS_ERROR_CODE_BANK_REJECTED: The payment was rejected either by the bank or by the user through the bank app / websitePAYMENTS_ERROR_CODE_DATA_INVALID_AMOUNT: Amount field is not valid. It could exceed the pre defined terms or the bank's limitsPAYMENTS_ERROR_CODE_DATA_INVALID_COUNT: Count field is not valid. It could exceed the pre defined terms or the bank's limitsPAYMENTS_ERROR_CODE_DATA_INVALID_CURRENCY: Currency field is not validPAYMENTS_ERROR_CODE_DATA_INVALID_FIRST_PAYMENT_DATE: First payment date is not validPAYMENTS_ERROR_CODE_DATA_INVALID_INSTITUTIONAL_IDENTIFIER: Institutional identifier (e.g. BSB, ABN, BIC) is not validPAYMENTS_ERROR_CODE_DATA_INVALID_LAST_PAYMENT: Payment marked as last payment unexpectedly. You might have not respected the existing agreementPAYMENTS_ERROR_CODE_DATA_INVALID_LAST_PAYMENT_DATE: Last payment date is not validPAYMENTS_ERROR_CODE_DATA_INVALID_MULTIPLE: Multiple fields break the bank's expectationsPAYMENTS_ERROR_CODE_DATA_INVALID_PAYEE_NAME: Something's wrong with the creditor's namePAYMENTS_ERROR_CODE_DATA_INVALID_PAYER_NAME: Something's wrong with the debtor's namePAYMENTS_ERROR_CODE_DATA_INVALID_UNKNOWN_ERROR: An error indicating a bad request was reported by the bank. Contact us for more detailsPAYMENTS_ERROR_CODE_DATA_INVALID_VALIDITY_END_DATE: Validity end date is not validPAYMENTS_ERROR_CODE_DATA_INVALID_VALIDITY_START_DATE: Validity start date is not validPAYMENTS_ERROR_CODE_MANDATE_INACTIVE: Payments can be initiated only with an active mandate. Please check the status of the mandatePAYMENTS_ERROR_CODE_MANDATE_INELIGIBLE_AMOUNT: Amount requested does not align with the existing agreementPAYMENTS_ERROR_CODE_MANDATE_INELIGIBLE_AMOUNT_EXCEEDED: Amount requested exceeds the existing agreement limitsPAYMENTS_ERROR_CODE_MANDATE_INELIGIBLE_AMOUNT_LESS_THAN: Amount requested is below the existing agreement minimumPAYMENTS_ERROR_CODE_MANDATE_INELIGIBLE_BEFORE_VALIDITY_DATE: Payment is before the mandate validity start datePAYMENTS_ERROR_CODE_MANDATE_INELIGIBLE_FIRST_PAYMENT_AMOUNT: First payment amount not supported by mandatePAYMENTS_ERROR_CODE_MANDATE_INELIGIBLE_FIRST_PAYMENT_DATE: First payment date not supported by mandatePAYMENTS_ERROR_CODE_MANDATE_INELIGIBLE_LAST_PAYMENT_AMOUNT: Last payment amount different from the one on the existing agreementPAYMENTS_ERROR_CODE_MANDATE_INELIGIBLE_LAST_PAYMENT_DATE: Last payment date does not respect the existing agreementPAYMENTS_ERROR_CODE_MANDATE_INELIGIBLE_MANDATE_INACTIVE: Payments can be initiated only with an active mandate. Please check the status of the mandatePAYMENTS_ERROR_CODE_MANDATE_INELIGIBLE_PAST_VALIDITY_DATE: Payments cannot be created after the validity end datePAYMENTS_ERROR_CODE_MANDATE_INELIGIBLE_PAYEE_ACCOUNT: The creditor account does not match the one on the existing agreementPAYMENTS_ERROR_CODE_MANDATE_INELIGIBLE_PAYEE_NAME: The creditor name does not match the name specified in the mandatePAYMENTS_ERROR_CODE_MANDATE_INELIGIBLE_PAYMENT_DETAILS: Payment details do not match mandatePAYMENTS_ERROR_CODE_MANDATE_INELIGIBLE_TIME: Time that this payment was initiated does not match that specified in the mandatePAYMENTS_ERROR_CODE_MANDATE_NOT_FOUND: Mandate not found at the bank levelPAYMENTS_ERROR_CODE_MANDATE_UNCANCELLABLE_STATE: Mandate cannot be cancelled while in current statePAYMENTS_ERROR_CODE_PAYEE_ACCOUNT_ACCOUNT_CHANGE: Payee account details have changedPAYMENTS_ERROR_CODE_PAYEE_ACCOUNT_CLOSED: Payee account is closedPAYMENTS_ERROR_CODE_PAYEE_ACCOUNT_LIMIT_EXCEEDED: Payee account has exceeded its transaction limitPAYMENTS_ERROR_CODE_PAYEE_ACCOUNT_NOT_FOUND: Payee account was not foundPAYMENTS_ERROR_CODE_PAYEE_ACCOUNT_NOT_PROVIDED: Payee details must be specified for a payment when not previously specified on the mandatePAYMENTS_ERROR_CODE_PAYEE_ACCOUNT_NOT_VALID: Payee account is not validPAYMENTS_ERROR_CODE_PAYEE_ACCOUNT_UNSUPPORTED_TRANSACTION: Payee account is unable to support this transaction typePAYMENTS_ERROR_CODE_PAYER_ACCOUNT_CURRENCY_NOT_SUPPORTED: Payer account does not support this currencyPAYMENTS_ERROR_CODE_PAYER_ACCOUNT_INSUFFICIENT_FUNDS: Payer account has insufficient fundsPAYMENTS_ERROR_CODE_PAYER_ACCOUNT_LIMIT_EXCEEDED: Payer account has exceeded its transaction limitPAYMENTS_ERROR_CODE_PAYER_ACCOUNT_NOT_FOUND: Payer account was not foundPAYMENTS_ERROR_CODE_PAYER_ACCOUNT_NOT_VALID: Payer account is not validPAYMENTS_ERROR_CODE_PAYER_ACCOUNT_PAYEE_NOT_AUTHORIZED: Payer has not authorized payments to this payeePAYMENTS_ERROR_CODE_PAYER_ACCOUNT_UNSUPPORTED_TRANSACTION: Payer account is unable to support this transaction typePAYMENTS_ERROR_CODE_PAYER_ACTION_MANDATE_DECLINED: Customer declines the agreement in their banking appPAYMENTS_ERROR_CODE_PAYER_ACTION_NO_RESPONSE: Payer did not respond to mandatePAYMENTS_ERROR_CODE_PAYER_ACTION_PAYMENT_DECLINED: Payer has declined the paymentPAYMENTS_ERROR_CODE_ALIAS_LOOKUP_LIMIT_REACHED: Alias lookup limit reachedPAYMENTS_ERROR_CODE_ALIAS_LOOKUP_UNAVAILABLE: Alias lookup unavailablePAYMENTS_ERROR_CODE_ALIAS_PAYEE_NOT_FOUND: Payee alias not foundPAYMENTS_ERROR_CODE_ALIAS_PAYER_NOT_FOUND: Payer alias not foundPAYMENTS_ERROR_CODE_ALIAS_RESOLUTION_ERROR: Error resolving the aliasPAYMENTS_ERROR_CODE_ALIAS_REMOTE_IP_LOOKUP_LIMIT_REACHED: Remote IP lookup limit reachedPAYMENTS_ERROR_CODE_ALIAS_REQUESTER_ID_LOOKUP_LIMIT_REACHED: Requester ID lookup limit reachedPAYMENTS_ERROR_CODE_ALIAS_RESOLUTION_NOT_POSSIBLE: Account not enabled for alias resolution servicesPAYMENTS_ERROR_CODE_PAYMENT_SETTLEMENT_BANK_UNAVAILABLE: Bank settlement system failed or was offlinePAYMENTS_ERROR_CODE_PAYMENT_SETTLEMENT_FAILURE: Payment failed due to settlement errorPAYMENTS_ERROR_CODE_PAYMENT_SETTLEMENT_NETWORK_UNAVAILABLE: Settlement system not availablePAYMENTS_ERROR_CODE_PAYMENT_SETTLEMENT_PAST_VALIDITY_DATE: Settlement failed because underlying agreement has expiredPAYMENTS_ERROR_CODE_PAYMENT_SETTLEMENT_RETRY_LIMIT_EXCEEDED: Number of payment retries exceededPAYMENTS_ERROR_CODE_PAYMENT_SETTLEMENT_RETRY_NOT_ELIGIBLE: Payment not retryablePAYMENTS_ERROR_CODE_PAYMENT_SETTLEMENT_TIMEOUT: Payment failed due to timeoutPAYMENTS_ERROR_CODE_MANDATE_EXPIRED: Mandate expiredPAYMENTS_ERROR_CODE_MANDATE_INELIGIBLE_COUNT_PER_FREQUENCY: Number of payments requested exceeds mandate limit for the current frequency periodPAYMENTS_ERROR_CODE_PAYEE_ACTION_MANDATE_DEACTIVATED: Payee has suspended/cancelled the mandatePAYMENTS_ERROR_CODE_MANDATE_SUSPENDED_CONTRACT_AMENDMENT: Mandate suspended due to amendment of the contractPAYMENTS_ERROR_CODE_PAYEE_ACTION_CANCELLED: Mandate suspended due to cancellation of the contract requested by the debtorPAYMENTS_ERROR_CODE_MANDATE_FINAL_PAYMENT_COMPLETED: Mandate suspended as final collection took placePAYMENTS_ERROR_CODE_MANDATE_EXCESSIVE_FAILED_COLLECTIONS: Mandate suspended after consecutive unsuccessful collectionsPAYMENTS_ERROR_CODE_PAYMENT_MERCHANT_CANCELLED: Payment was cancelled by the merchantPAYMENTS_ERROR_CODE_PAYMENT_CUSTOMER_CANCELLED: Payment was cancelled by the customerPAYMENTS_ERROR_CODE_ACTION_NOT_ALLOWED: The requested action is not allowedPAYMENTS_ERROR_CODE_INTERNAL_SYSTEM_ERROR: An internal system error occurredPAYMENTS_ERROR_CODE_PAYEE_ACTION_NOT_AUTHORIZED: Payee action is not authorizedPAYMENTS_ERROR_CODE_PAYEE_ACCOUNT_FROZEN: Payee account is frozenPAYMENTS_ERROR_CODE_DATA_INVALID_DATE: Date field is not validPAYMENTS_ERROR_CODE_CONSUMER_UNREACHABLE: The payment has been cancelled because the consumer could not be reachedPAYMENTS_ERROR_CODE_PAYER_ACTION_MANDATE_AMENDMENT_DECLINED: Payer has declined the mandate amendmentPAYMENTS_ERROR_CODE_PAYER_ACTION_MANDATE_AMENDMENT_NO_RESPONSE: Payer did not respond to mandate amendmentPAYMENTS_ERROR_CODE_MANDATE_UNAMENDABLE_STATE: Mandate cannot be amended while in current statePAYMENTS_ERROR_CODE_MANDATE_AMENDMENT_IN_PROGRESS: Pending amendment already in progressPAYMENTS_ERROR_CODE_MANDATE_AMENDMENT_NO_CHANGE_SPECIFIED: No changes were specifiedPAYMENTS_ERROR_CODE_MANDATE_AMENDMENT_VALIDITY_END_DATE: Validity end date cannot be amended if it was null in original mandatePAYMENTS_ERROR_CODE_MANDATE_AMENDMENT_NOT_PERMITTED: This mandate can no longer be amendedPAYMENTS_ERROR_CODE_MANDATE_CREATION_LIMIT_REACHED: Mandate creation limit reachedPAYMENTS_ERROR_CODE_MANDATE_AMENDMENT_UNCANCELLABLE_STATE: Amendment cannot be cancelled while in current statePAYMENTS_ERROR_CODE_MANDATE_AMENDMENT_CANCELLATION_IN_PROGRESS: Cancellation already in progress for this amendmentPAYMENTS_ERROR_CODE_MANDATE_AMENDMENT_CANCELLATION_NOT_POSSIBLE: Amendment cancellation not possiblePAYMENTS_ERROR_CODE_MANDATE_CANCELLATION_IN_PROGRESS: Pending cancellation already in progressPAYMENTS_ERROR_CODE_MANDATE_INACTIVATABLE_STATE: Mandate cannot be reactivated while in current statePAYMENTS_ERROR_CODE_MANDATE_REACTIVATION_IN_PROGRESS: Pending reactivation already in progressPAYMENTS_ERROR_CODE_MANDATE_UNSUSPENDABLE_STATE: Mandate cannot be suspended while in current statePAYMENTS_ERROR_CODE_MANDATE_SUSPENSION_IN_PROGRESS: Pending suspension already in progressPAYMENTS_ERROR_CODE_MANDATE_TOO_MANY_AGREEMENTS_FOR_DEBTOR: Too many mandates created for debtorPAYMENTS_ERROR_CODE_PAYEE_ACTION_GRACEFUL_EXIT: Graceful exit initiated by payeePAYMENTS_ERROR_CODE_PAYMENT_SETTLEMENT_PENDING: Payment settlement is delayed due to payer bankPAYMENTS_ERROR_CODE_PAYER_ACCOUNT_AUTHORIZATION_FAILED: Payer account authorization failedPAYMENTS_ERROR_CODE_MANDATE_INELIGIBLE_LAST_PAYMENT_SENT: No further payments can be made, the final payment has been sentPAYMENTS_ERROR_CODE_PAYEE_ACCOUNT_NAME_MISMATCH: Payee account name mismatchPAYMENTS_ERROR_CODE_PAYER_ACTION_NOT_AUTHORIZED: Payer action is not authorizedPAYMENTS_ERROR_CODE_PAYMENT_SETTLEMENT_RETURNED: Payment settlement returnedPAYMENTS_ERROR_CODE_PAYER_ACTION_MANDATE_INACTIVE: Mandate inactive by payer request