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.
• TIMED_OUT - No response was received from the beneficiary bank within the expected time. A final response is still awaiting.

note

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).
TIMED_OUT	No response received from the beneficiary bank within the expected time. Final response awaited.	Incorrect/closed account or name mismatch (MD07, MM20, AG03, AC01, AC03).

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"
  }'