Testing payouts

Testing payouts is how you send a sandbox payout and confirm the result. A payout moves funds from a customer wallet to a beneficiary.

Test these three outcomes:

• A payout that settles as PAID.
• A payout that the bank returns as RETURN.
• A payout that needs a request for information (RFI) before it can settle.

For how mock data and simulation APIs differ, see Testing Nium. For allowed status transitions, see Simulate transaction status.

Prerequisites

Create a customer with funds before you run a payout scenario. Complete the steps in order.

Step	Request	What you do
1	Customer onboarding	Onboard a customer and confirm status is clear. Follow Approve customer.
2	Assign Payment ID	Link a funding source to the wallet. This is once per wallet and is required for every payout flow. A financial institution can skip this step.
3	Fund Wallet	Add funds to the customer wallet. Confirm the balance covers the payout. See Fund a wallet.

Payout processing is asynchronous. After Transfer Money, the payout moves through INITIATED, IN_PROGRESS, COMPLIANCE_COMPLETED, SENT_TO_BANK, and then PAID or RETURN. Some payment partners skip SENT_TO_BANK or PG_PROCESSING.

Each change runs in a batch. Updates usually arrive within 10–30 seconds and can take up to a minute. Poll Fetch remittance lifecycle status to follow the payout. See Remittance lifecycle.

Settle a payout

This payout completes with no extra step. You can skip Add Beneficiary V2 when you send the beneficiary details in the Transfer Money request. Use a PAID example from Payout account numbers.

Step	Request	What you do
1	Add Beneficiary V2	Create a beneficiary. Set the account number so it matches the PAID example for the currency, for example 000987654321 for USD.
2	Transfer Money	Start the payout. Reference the beneficiary, or send the beneficiary details in this request.
3	Fetch remittance lifecycle status	Confirm the status is PAID.

Return a payout

This payout is rejected or returned by the bank. Use a RETURN example from Payout account numbers. You can skip Add Beneficiary V2 when you send the beneficiary details in Transfer Money.

Step	Request	What you do
1	Add Beneficiary V2	Create a beneficiary. Set the account number so it matches the RETURN example for the currency, for example 000897654321 for USD.
2	Transfer Money	Start the payout. Reference the beneficiary, or send the beneficiary details in this request.
3	Fetch remittance lifecycle status	Confirm the status is RETURN.

Request information for a payout

This payout needs more compliance information before it can settle. Include TransactionCreditorHit in beneficiaryName, and use a PAID example from Payout account numbers so the payout settles as PAID after approval.

The status order is IN_PROGRESS, then RFI_REQUESTED, then RFI_RESPONDED, then COMPLIANCE_COMPLETED, then PAID.

For how to read and answer the RFI, see RFI v5 flow.

Create the payout and raise the flag

You can skip Add Beneficiary V2 when you send beneficiaryName and beneficiaryAccountNumber in Transfer Money.

Step	Request	What you do
1	Add Beneficiary V2	Create a beneficiary. Include TransactionCreditorHit in beneficiaryName, for example John Doe TransactionCreditorHit. Set beneficiaryAccountNumber to a PAID example, such as 000987654321 for USD.
2	Transfer Money	Start the payout. Reference the beneficiary, or send the beneficiary details in this request.
3	Fetch remittance lifecycle status	Confirm the status is IN_PROGRESS and statusDetails says the transaction is undergoing compliance review.

Request, answer, and approve

Use the payout simulation API for the actions the compliance team takes in production.

Step	Request	What you do
4	Simulate transaction status	Set nextStatus to RFI_REQUESTED. Set requestInfoFor when you need a specific document. If the call fails because the compliance status is still IN_PROGRESS, the payout is still processing. Wait, then retry. If it still fails after 2 minutes, contact Nium Support.
5	Fetch RFI Details	Set rfiEntity to TRANSACTION. Read the information Nium is requesting.
6	Respond to RFI	Submit the answer. The RFI moves to RFI_RESPONDED. In production you answer after a webhook.
7	Simulate transaction status	Set nextStatus to COMPLIANCE_COMPLETED. This stands in for the compliance review. REJECTED is permanent. A payout in REJECTED cannot be recovered.
8	Fetch remittance lifecycle status	Confirm the final status is PAID.

This RFI flow is for testing. In production, Nium handles steps 4 and 7. You only answer the RFI in step 6 after a webhook.

Update payout status

Use this when a payout stays in an intermediate status such as SENT_TO_BANK and you need to simulate the bank finishing or rejecting it.

From	To	What it simulates
SENT_TO_BANK	PAID	The bank completes processing
SENT_TO_BANK	RETURN	The bank rejects the payout
PAID	RETURN	A reversal after payment

Step	Request	What you do
1	Fetch remittance lifecycle status	Read the current status, for example SENT_TO_BANK.
2	Simulate transaction status	Send the systemReferenceNumber and set nextStatus to PAID or RETURN.
3	Fetch remittance lifecycle status	Confirm the status changed.