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.

Please note, for the following corridors a transaction may move from SENT_TO_BANK to PG_PROCESSING if it's being reprocessed internally. This is expected behavior and doesn't require any action on your part:

• AUD
• BRL
• CAD
• EUR
• GBP
• MYR
• SGD
• USD

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'

Transaction statuses

The following lists all possible payout transaction statuses, 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.
ERROR	An error occurred while processing the transaction. Depending on the type of error, the transaction can be retried by resubmitting the details and creating a new transaction.
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.

Compliance statuses

Every transaction is reviewed for compliance. The following statuses show the progress and outcome of compliance review.

Status	Description
PENDING	The transaction is under compliance review and may require additional checks before it can proceed.
RFI_REQUESTED	Additional information has been requested to complete the compliance review of this transaction.
CLEAR	The transaction has passed all compliance checks and can proceed to the next step in processing.
REJECTED	The transaction did not meet compliance requirements and cannot proceed.