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:

1. Create a payout using the Transfer Money request and note down the systemReferenceNumber returned in the response.
2. Fetch the remittance lifecycle status by using the Fetch Remittance Lifecycle Status request and include the systemReferenceNumber.

Example request

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:

1. 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.
2. Fetch the remittance lifecycle status by using the Fetch Remittance Lifecycle Status request and include the externalId.

Example request

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.