Error handling

Errors during payments

In an ideal world payments always succeed and arrive in the recipient's account. However occasionally there are issues that only occur after the transaction has been funded. There could be various issues, for example:

• Transaction details invalid
• Transaction sender phone_number invalid
• Transaction recipient phone_number invalid

Whenever we face a problem during payment we will add a note to the transaction state_reason and state_reason_details fields as shown here. These notes contain human readable error informations that can help you debug the issue. Note that they should never be shown to your customers as they could be technical in nature. They can be shown in your internal system for your customer service team to see however.

Error codes

Error Code	Description
initial	Transaction is created.
processing	Transaction payout has been initiated and we're waiting for a response from the provider.
paid	Transaction was paid to the recipient.
refunded	Funds have been returned to the sender either partially or fully.
exception	An exception happened during the processing of the transaction.
provider_pending	Transaction is awaiting a status update from the provider.
provider_timeout	Transaction is awaiting a status update from the provider.
provider_error	There was an error from the provider. We will review the transaction, and update the state.
provider_unresponsive	We didn't receive a response from the provider in time. We will retry to fetch the response at a later date.
provider_not_accepting_transactions	The payment provider is not accepting transactions at the moment.
recipient_bank_not_accepting_transactions	Transaction recipient bank is not accepting payments at the moment.
recipient_bank_unresponsive	Transaction recipient bank is having connectivity issues.
manual_reconciliation_required	Transaction requires manual verification. Please wait until this is done.
sender_details_invalid	Transaction sender details invalid.
sender_not_allowed_to_transact	Transaction sender is not allowed to transact.
sender_aml_suspicion	Transaction sender has suspicious in AML.
sender_phone_number_invalid	Transaction sender phone_number invalid.
sender_transfer_limit_exceeded	Transaction sender has exceeded transfer limits.
recipient_details_invalid	Transaction recipient details invalid.
recipient_phone_number_invalid	Transaction recipient phone_number invalid.
recipient_phone_number_not_registered_on_network	Transaction recipient phone_number is not registered on the network.
recipient_phone_number_not_allowed_for_mobile_money	Transaction recipient phone_number is not registered for mobile money.
recipient_bank_account_invalid	Transaction recipient bank_account invalid.
recipient_bank_account_locked	Transaction recipient account is locked and doesn't accept funds.
recipient_bank_code_invalid	Transaction recipient bank_code invalid.
recipient_bank_details_invalid	Transaction recipient bank_account or bank_code invalid.
recipient_name_validation_failed	Transaction recipient name has failed name validation against the account holder name.
recipient_transfer_limit_exceeded	Transaction recipient has exceeded transfer limits.
recipient_daily_transfer_limit_exceeded	Transaction recipient has exceeded daily transfer limits.
recipient_not_allowed_to_receive_money	Transaction recipient not allowed to receive money.
transaction_details_invalid	Transaction details invalid.
cannot_assign_collection_id_for_transaction	Can not assign cash collection ID for transaction.
transaction_reference_already_used	Transaction reference was already used.
transaction_amount_invalid	Transaction amount invalid.
transaction_cancel_requested_by_provider	Transaction was requested to be cancelled at the provider.
transaction_canceled_by_provider	Transaction was cancelled by the provider.
transaction_canceled_by_sender	Transaction was cancelled by the sender.
transaction_canceled_by_recipient	Transaction was cancelled by the recipient.
transaction_canceled_by_admin	Transaction was cancelled by the admin.
transaction_expired	Transaction expired, and has been cancelled.
transaction_cannot_be_processed	Transaction cannot be processed.
transaction_has_issues	Payment to the recipient have run into issues.