Payout Rail Preference

By default, Nium selects the optimal payout rail for each transaction based on internal routing logic — factoring in cost, coverage, and speed. The Payout Rail Preference feature lets clients override this default and specify how their payments should be routed, per corridor or per payment.

This is useful when you need to guarantee real-time delivery, optimise for cost, or ensure consistent settlement behaviour across a product line.

Why It Matters

Without rail preference, clients have limited visibility or control over which rail Nium uses. With this feature, you can:

• Guarantee real-time routing for specific corridors (e.g. always use FPS for GBP, never CHAPS)
• Optimise for cost or speed depending on your use case
• Give your end users a predictable, consistent payment experience
• Advertise specific SLAs confidently, knowing Nium will not silently downgrade the rail

How It Works

Include the payoutRail field in your Transfer Money request. Nium validates the value against your client configuration and the destination corridor, then routes accordingly.

{
  "preferences": {
    "payoutRail": ["REALTIME"]
  }
}

If no value is passed for payoutRail, Nium applies its internal routing logic to select the best rail for your transaction.

If the specified rail is unavailable and no fallback partner can honour it, the transaction is rejected — Nium does not silently downgrade to a slower or alternate rail.

Supported Values

Generic Modes (Recommended)

Corridor-agnostic values that Nium maps to the best available rail per destination.

Value	Description	Best For
REALTIME	Near-instant settlement (e.g. FPS, FedNow, Interac)	When settlement speed is the priority
SAMEDAY	Same-day, batch-processed rails where schemes and cut-offs permit	Payroll, batch payouts, end-of-day settlements
LOWCOST	Lowest-cost available rail per corridor	When cost is the priority and SLA allows standard settlement
SWIFT	Settlement via the SWIFT network	Cross-border payouts where local rails are unavailable, or high-value B2B transfers
LOCAL	Standard domestic clearing rails (e.g. ACH, SEPA Credit Transfer)	Non-urgent domestic payouts where rail predictability matters more than speed or cost

Explicit Rail IDs (Advanced)

Specify an exact rail ID for precise control. Only honoured if it matches your client configuration and the destination corridor. Contact your Nium account manager to enable this for your account.

{
  "preferences": {
    "payoutRail": ["uk_fps"]
  }
}

Supported Corridors and Rail Mapping

Generic Mode → Rail Mapping

Currency	REALTIME	SAMEDAY	LOWCOST	SWIFT	LOCAL
EUR	INSTANT	STANDARD	INSTANT	SWIFT	INSTANT, STANDARD
GBP	FPS	CHAPS	FPS	SWIFT	FPS, CHAPS
HKD	FPS, ACT, CHATS	Not supported	FPS, ACT	SWIFT	FPS, ACT, CHATS
SGD	FPS	SFTP	SFTP	SWIFT	FPS, SFTP
AUD	NPP	DE	DE	SWIFT	NPP, DE
CAD	INTERAC	EFT	EFT	SWIFT	EFT

Explicit Rail IDs

Currency	Supported Values
EUR	eu_instant, eu_standard
GBP	uk_fps, uk_chaps
HKD	hk_fps, hk_chats
SGD	sg_fast, sg_sftp
AUD	au_npp, au_de
CAD	ca_interac, ca_eft

Error Handling

Every rail preference is validated against your client configuration and corridor capabilities before the payout is processed. If the requested mode or rail is not supported, the request is rejected with a clear error — there is no silent downgrade or fallback.

HTTP Status	Error Code	Description	Recommended Action
4XX	payoutRail	The requested payoutRail value is not supported or does not match your client configuration.	Review the supported rail IDs for the corridor in the Explicit Rail IDs table above. Contact your Nium account manager if you believe your configuration should support this rail.

Example error response:

{
  "status": "BAD_REQUEST",
  "issues": [
    {
      "code": "incorrect_value",
      "description": "Payout Rail: uk_abc is not supported for currency AUD",
      "field": null,
      "action": null,
      "regex": null
    }
  ]
}

Best Practices

• Use generic modes (REALTIME, LOCAL) over explicit rail IDs — they are corridor-agnostic and easier to maintain as your payment corridors expand.
• Set corridor-level defaults during onboarding via your Nium account manager, then use transaction-level payoutRail to override for specific payments when needed.
• Confirm supported rail IDs per corridor in the tables above before configuring preferences.

Related Resources

• Transfer Money
• Country and Regional Guides