Skip to main content

Transaction Lifecycle

The diagram below outlines the entire journey of a payout (also called a remittance), from its initiation to its completion. See transaction statuses for detailed descriptions of each status a payout goes through.

Sign up

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.

Request example​

curl 'https://gateway.nium.com/api/v1/client/%7B%7BclientHashId%7D%7D/customer/%7B%7BcustomerHashId%7D%7D/wallet/%7B%7BwalletHashId%7D%7D/remittance/%7B%7BsystemReferenceNumber%7D%7D/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.

Request example​

curl 'https://gateway.nium.com/api/v1/client/%7B%7BclientHashId%7D%7D/customer/%7B%7BcustomerHashId%7D%7D/wallet/%7B%7BwalletHashId%7D%7D/remittance/%7B%7BsystemReferenceNumber%7D%7D/audit' \
  --header 'X-Api-Key: YOUR_SECRET_TOKEN'
  --header 'externalId: true'

Transaction statuses​

StatusDescription
APPROVEDThe transaction is approved for Payout by the authorized personnel.
AWAITING_FUNDSThe transaction is waiting for funding.
CANCELLEDThe 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_COMPLETEDThe transaction has cleared compliance review and is ready for further processing.
COMPLIANCE_REJECTEDThe transaction is rejected by compliance rules.
DECLINEDThe transaction is declined by the checker or due to monitoring rules.
ERRORAn error occurred while processing the transaction. Depending on the type of error, the transaction can be retried by returning to the PG_PROCESSING status.
EXPIREDThe transaction is expired due to insufficient funds or the expiration of the FX rate.
IN_PROGRESSThe transaction is currently being processed.
INITIATEDThe transaction is initiated for processing.
PAIDMoney has been sent to the beneficiary bank from Nium's partner bank.
PG_PROCESSINGThe payout transaction is ready for processing, and we are finding the optimal route to process the payment using the Nium partner bank network.
RFI_REQUESTEDThe transaction has been flagged by compliance rules. Additional information has been requested for this transaction for compliance purposes.
RFI_RESPONDEDNium has received the response to the request for additional compliance information requested per RFI.
RETURNEDThe 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.
SCHEDULEDThe transaction is scheduled and is going to be processed on the scheduled date.
SENT_TO_BANKThe payout instruction has been sent to Nium's partner bank. When the partner bank sends the payment out, the status changes to PAID.