Transaction Lifecycle
The diagram below outlines the entire journey of a transaction payout (also called a remittance), from its initiation to its completion. See transaction statuses for detailed descriptions of each status a payout goes through.
For details on how to create a payout, see Transfer Money.
Fetch remittance lifecycle status
You can use two fields to fetch transaction statuses:
systemReferenceNumber
externalId
System reference number
To fetch remittance lifecycle statuses using the systemReferenceNumber
:
- Create a payout using the Transfer Money request and note down the
systemReferenceNumber
returned in the response. - Fetch the remittance lifecycle status by using the Fetch remittance lifecycle status request and include the
systemReferenceNumber
.
Request example
curl 'https://gateway.nium.com/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/remittance/{systemReferenceNumber}/audit' \
--header 'X-Api-Key: YOUR_SECRET_TOKEN'
External ID
To fetch remittance lifecycle statuses using the externalId
:
- Create a payout using the Transfer Money request and include a custom
externalId
- a unique identifier you define to track the transaction for your own reconciliation needs. - Fetch the remittance lifecycle status by using the Fetch Remittance Lifecycle Status request and include the
externalId
.
Request example
curl 'https://gateway.nium.com/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/remittance/{systemReferenceNumber}/audit' \
--header 'X-Api-Key: YOUR_SECRET_TOKEN'
--header 'externalId: true'
Payout statuses
The following lists all the possible statuses for payout transaction, from initiation to completion, along with their descriptions.
Status | Description |
---|---|
AWAITING_FUNDS | The transaction is waiting for funding. |
CANCELLED | The transaction is cancelled by the customer. For a Payout transaction, typically, this can only be done on scheduled payouts that are not yet initiated. |
COMPLIANCE_COMPLETED | The transaction has cleared compliance review and is ready for further processing. |
EXPIRED | The transaction is expired due to insufficient funds or the expiration of the FX rate. |
IN_PROGRESS | The transaction is currently being processed. |
INITIATED | The transaction is initiated for processing. |
PAID | Money has been sent to the beneficiary bank from Nium's partner bank. |
PG_PROCESSING | Our payment gateway is processing the transaction, and finding the optimal route to process the payment using our partner bank network. |
REJECTED | The transaction is rejected by compliance rules. |
RETURN | The transaction has been returned by the receiving bank. This status typically applies to a payout transaction when the beneficiary bank returns it for a specific reason. |
RFI_REQUESTED | The transaction has been flagged by compliance rules. Additional information has been requested for this transaction for compliance purposes. |
RFI_RESPONDED | Nium has received the response to the request for additional compliance information requested per RFI. |
SCHEDULED | The transaction is scheduled and is going to be processed on the scheduled date. |
SENT_TO_BANK | The payout instruction has been sent to Nium's partner bank. When the partner bank sends the payment out, the status changes to PAID . |
Substatuses
Status | Substatus | Description |
---|---|---|
PAID | PROCESSED_BY_CLEARING | The transaction has been processed by the clearing system and is expected to be credited to the beneficiary. This status typically occurs when Nium does not have full visibility into the transaction’s journey due to clearing or partner limitations. |
PAID | DEEMED_PAID | This transaction can be considered PAID with a high degree of confidence, as the clearing return window has elapsed without any returns. |
PAID | SENT_TO_BENEFICIARY_BANK | This suggests that the transaction has reached the beneficiary. If the beneficiary has an active and compliant account then the funds will be credited anytime. |
PAID | SENT_TO_BENEFICIARY_BANK_ACCOUNT | This suggests that the funds have reached the beneficiary’s bank account. |