Remit Transaction Sub-status Update

This webhook fires whenever the sub-status of a remittance transaction in paid status changes. Use it to keep your systems and customer communications in sync across corridors that offer different levels of payment visibility.

https://<customerHost:Port>/webhook

When this event occurs

We send this event as soon as there is an update to the remittance subStatus. Typical transitions are:

• Sent_To_Beneficiary — Funds reached the beneficiary (final leg). A return is rare and usually due to the beneficiary refusing funds (for example, ISO code MD06).
• Sent_To_Beneficiary_Bank — Funds reached the beneficiary’s bank. Returns may occur because of incorrect or closed accounts, or name/number mismatches (common ISO codes include MD07, MM20, AG03, AC01, AC03).
• Processed_By_Clearing — Funds passed the clearing system; final credit is pending at the beneficiary bank.
• Deemed_PAID — No return was received within the corridor’s observation window, so the transaction is treated as paid. Any later return will trigger your standard return-handling flow.

These sub-statuses improve transparency in corridors where a final, bank-confirmed “PAID” signal is not always available.

Use cases

• Enterprise payroll (for example, Rippling, Gusto): show whether a payout is credited, at the beneficiary bank, in clearing, or deemed paid. Automate follow-ups only when needed.
• Financial institutions (for example, Koho, Currencycloud): display “Deemed PAID” where appropriate to set expectations and reduce inquiries about later returns.

Endpoint and headers

Field	Value
Content-Type	application/json

POST https://<customerHost:Port>/webhook

Request body

Top-level fields

Field	Description	Type
clientHashId	Unique client identifier provisioned before integration.	UUID
customerHashId	Unique customer identifier created when you onboard a customer.	UUID
walletHashId	Unique wallet identifier created with the customer.	UUID
systemReferenceNumber	Unique transaction reference in Nium.	String
transactionCurrency	Transaction currency in ISO-4217 format.	String
transactionAmount	Destination amount of the remittance.	String
billingCurrency	Wallet balance currency in ISO-4217 format.	String
billingAmount	Source amount of the remittance.	String
exchangeRate	Applied FX rate (source → destination).	String
beneficiaryName	Beneficiary name.	String
beneficiaryAccountNumber	Beneficiary account number (may be masked).	String
beneficiaryBankName	Beneficiary bank name.	String
template	Fixed value: REMIT_TRANSACTION_SUBSTATUS_UPDATE_WEBHOOK.	String
subStatus	Current sub-status. One of: Sent_To_Beneficiary, Sent_To_Beneficiary_Bank, Processed_By_Clearing, Deemed_PAID.	String
tags[]	Optional metadata items to help reconciliation (for example, “Transaction Reference Number”).	Array
externalId	Your unique identifier for the transaction (see Transfers API).	String

Sub-status meanings

subStatus	What it means	Typical return cause(s)
Sent_To_Beneficiary	Funds reached the beneficiary; final leg complete.	Beneficiary refusal (MD06).
Sent_To_Beneficiary_Bank	Funds reached the beneficiary bank; final posting pending.	Incorrect/closed account, name mismatch (MD07, MM20, AG03, AC01, AC03).
Processed_By_Clearing	Funds passed the clearing system; pending at beneficiary bank.	Corridor-specific reasons.
Deemed_PAID	No return within corridor’s observation window; treated as paid.	Late scheme/partner returns (rare but possible).

The observation window and return behaviors vary by corridor and partner. Align your SLAs and customer messaging per corridor.

Examples

Deemed paid

curl --location --request POST 'https://<customerHost:Port>/webhook' \
  -H 'content-type: application/json' \
  -d '{
    "clientHashId": "0498f10f-1968-494f-9f7a-454ed23942a0",
    "customerHashId": "0de1e512-e0d7-4eca-ad41-dd39325facc2",
    "walletHashId": "e83cca77-8b63-4a25-b580-1d872380ef29",
    "transactionCurrency": "INR",
    "transactionAmount": "5418.1700",
    "systemReferenceNumber": "RT1343085439",
    "exchangeRate": "54.454000000"
  }'