• Transaction state as the source of truth
• Errors during payments
• Error types
• Error codes
• Note
• Pending transactions

Transaction state as the source of truth

You can read further details about the state field here.

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:

• Recipient details are incorrect
• Recipient is not registered for the mobile provider’s wallet
• Recipient’s account is locked and doesn’t accept funds
• Recipient’s bank is having connectivity issues
• Recipient didn’t pick up the funds in time

Whenever we face a problem during payment we will add a note to the recipient’s 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 both 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.

Once we find a problem we don’t stop processing however. Due to how most of our corridors work we know that a lot of the errors are only temporary. Even errors that look fatal - for example one that says that the recipient doesn’t exist - could just be a temporary issue with the bank or provider. Hence every time we receive an error we don’t stop, but try again until either:

• We manage to pay out the funds
• You cancel the transaction
• You have auto-cancellation enabled and 24 hours have elapsed since the transaction was funded

For more info on cancellations please read our how to cancel recipients and transactions guide.

Instead of cancelling a transaction you can sometimes also fix the problem by updating the details on the recipient, for example if the details they have entered is incorrect and you need to change it. Please see our editing a recipient guide.

Error types

We categorize most errors into the following categories:

• temporary_error: errors where the problem is usually temporary. This includes connectivity issues with banks and providers, and problems with the central banking switch of the country. We constantly retry these transactions and they usually pay out within 24 hours. For these errors the retriable flag on the recipient will be set to true.
• recipient_error: errors where the problem is usually permanent. This includes issues like the recipient details being incorrect, or the recipient’s account is locked. As occasionally we get invalid reports from our providers we sometimes retry these transactions as well, however it is usually unlikely that these transactions pay out in the future, and should either be cancelled, or the recipient’s details should be changed. For these errors the retriable flag on the recipient will be set to false, however the editable flag will be true.
• sender_error: these are issues where either the sender or the transaction details provided mean that the transaction cannot be paid out - even if the recipient details are changed. In this case both the retriable and the editable flag will be set to false.
• pending: this is not an error, but means that the transaction has not yet been fully processed. Please see the next section for more details.
• exception / manual_reconciliation_required: errors where there was an unknown error during processing. These transactions will be investigated by the technical team, and will either be retried or need to be cancelled.

Error codes

Note

The categories recipient_action_required and recipient_error get mapped to user_action_required and user_invalid_data_error when dealing with a Collection Transaction.

Pending transactions

Occasionally a transaction has neither errored, nor has paid out. We call these transactions pending. There are two main cases for pending transactions:

• For any kind of cash pickup transactions, pending means that the recipient has received a pickup notice, but didn’t pick up the funds yet. This is also called the recipient_action_required state. These transactions can be cancelled, in which case the pickup notice will be invalidated and the recipient will not be able to use it to pick up the funds anymore.
• For some providers there might need to be action taken by the beneficiary to pick up the funds, for example they need to sign a mandate form. TTransactions here will also be in the recipient_action_required state.
• For other transactions pending means that the recipient’s bank or mobile provider is still processing the transaction and will note at a later date whether it could deposit the funds or not. These transactions will have a may_cancel field set to false. If you try to cancel them using the DELETE /v1/recipients/[TRANSFERZERO_RECIPIENT_ID] endpoint they get cancelled right after we get confirmation from our bank or mobile provider that the funds could not be debited. However if the confirmation we receive says that the funds are sent out these transactions will not be cancelled, they will be marked as successful.
• For collections in user_action_required means that we sent the notification to the User and we are currently awaiting for the User to proceed with sending the funds.