Testing Nium

Testing Nium is how you test customer onboarding, payouts, and account verification in the sandbox. You trigger each outcome with mock test data or a simulation API, without Nium support.

Prerequisites

Before you test, confirm the following:

• You can authenticate. See Key concepts and Authentication.
• You have a clientHashId and an x-api-key from client configuration.

Simulation methods

In the sandbox, a payout settles to PAID when the beneficiary account number ends with the success suffix. Use that path when you only need a successful payout.

You also need to test cases that don't follow that path. A customer may need more compliance information. A bank may reject a payout. A transaction may need a manual review. In production, Nium systems and the compliance team handle these cases. In the sandbox, you trigger them yourself so your app can handle the full lifecycle, not only the successful result.

There are two ways to trigger a different outcome. Each one has a different purpose.

Mock test data

Use mock test data when the outcome depends on a value in the request. Put the value in the field below. Nium returns the matching result.

Scenario	Field	Magic value	Result
Successful payout	Beneficiary account number	Ends with 987654321	Status PAID
Bank rejects the payout	Beneficiary account number	Ends with 897654321	Status RETURN
Payout needs a request for information (RFI)	beneficiaryName	Contains TransactionCreditorHit	The payout stays in compliance review

If you omit a magic value, a payout follows the successful path. Account-number formats vary by currency. The full list is on Payout account numbers.

Onboarding uses no special field value. Create Customer v5 sets subStatus to awaiting_kyc. You complete Know Your Customer (KYC), then you use a simulation API for the step Nium takes. See Testing onboarding.

Simulation APIs

Use a simulation API when you need to perform an action that Nium support takes in an internal portal. The call moves a customer or a payout from one status to the next.

For example, you can:

• Move a customer from under_review to clear after KYC.
• Raise an RFI for a customer or a payout.
• Move a payout from SENT_TO_BANK to PAID.
• Move a payout from RFI_RESPONDED to REJECTED.

Each API accepts only specific transitions. See Simulation APIs for the endpoints, request fields, and allowed transitions.

Set onboarding nextAction to clear only when subStatus is under_review. The customer needs the KYC result on file before you use them in a payout or payin test.

Use mock test data for a single payout outcome, such as success or a bank return. Use simulation APIs when intermediate statuses, a rejection, or a manual approval matter.

important

Simulation APIs work in the sandbox only.

Test a feature

• Testing onboarding covers a customer with status clear, and an onboarding RFI.
• Testing payouts covers successful settlement, a bank return, and an RFI.
• Testing Verify covers bank account verification before a payout.

Two more sandbox tools sit outside those flows:

• Simulate an incoming payment credits a virtual account.
• Simulate funding instrument status completes or reverses a microdeposit.

Sandbox and production

In production, Nium systems and the compliance team act on their own. You respond to webhooks when Nium needs information from you. Most workflows need no manual status change.

In the sandbox, you trigger the actions Nium takes in production. For onboarding, call Get Customer v5 and read status and subStatus before the next step. Use simulation APIs to step through a multi-step flow and confirm your app handles each status.