Payment Status Update

Payment status update webhook.

Definition

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

Headers:

Field	Description
Content-Type	The Content-Type entity header is used to indicate the media type of the resource. Expected value is application/json.
x-api-key	f9be0d9e-6903-4862-8d69-5b2651426bf9

Example Request:

Bash
Javascript

curl --location --request POST 'https://<customerHost:Port>/webhook' \\
--header 'Content-Type: application/json' \\
--header 'x-api-key: f9be0d9e-6903-4862-8d69-5b2651426bf9' \\
--data-raw '{
    "reference_number": "1625203888",
    "payment_id": "UATPY103166714",
    "event": "TRANSACTION_STATUS_CHANGE",
    "status": "PG_PROCESSING",
    "timestamp": "2021-07-02T05:31:30.530Z",
    "expected_to_be_paid_at": "2025-02-21T09:00:00.000Z"
}'

var settings = {
  "url": "https://<customerHost:Port>/webhook",
  "method": "POST",
  "timeout": 0,
  "headers": {
    "content-type": "application/json",
    "x-api-key": "f9be0d9e-6903-4862-8d69-5b2651426bf9"
  },
  "data": JSON.stringify({
    "reference_number": "1625203888",
    "payment_id": "UATPY103166714",
    "event": "TRANSACTION_STATUS_CHANGE",
    "status": "PG_PROCESSING",
    "timestamp": "2021-07-02T05:31:30.530Z",
    "expected_to_be_paid_at": "2025-02-21T09:00:00.000Z"
  }),
};

$.ajax(settings).done(function (response) {
  console.log(response);
});

Request Body:

Fields	Description	Type
reference_number	Unique reference number for every payout sent by client.	String
payment_id	Unique Id for every payout generated by Nium.	String
event	Event name of the webhook. Here, it will be TRANSACTION STATUS CHANGE	String
status	Payment status values (IN_PROCESS, AWAITING_FUNDS, INFO_REQUESTED, COMPLIANCE_REJECTED, SENT_TO_BANK, PG_PROCESSING, PAID, RETURNED, REJECTED, CANCELLED)	String
sub_status	Current sub-status. One of: SENT_TO_BENEFICIARY_BANK_ACCOUNT, SENT_TO_BENEFICIARY_BANK, PROCESSED_BY_CLEARING, DEEMED_PAID, TIMED_OUT.	String
timestamp	Date and time of status change.	String
expected_to_be_paid_at	Expected Date and time, of transaction to be paid to beneficiary	String

Sub-status meanings

Sub-statuses provide more detail about a payout that reaches to the final stage. They help you understand what stage the transaction is in—whether it’s still with the beneficiary’s bank or has already been credited to the beneficiary’s account.

This added transparency is especially useful for tracking how payouts behave in different countries and regions.

status	sub_status	Description
PAID	SENT_TO_BENEFICIARY_BANK_ACCOUNT	The funds have been credited to the beneficiary’s bank account.
PAID	SENT_TO_BENEFICIARY_BANK	The transaction has been sent to the beneficiary’s bank. If the account is active and compliant, the funds will be credited shortly.
PAID	PROCESSED_BY_CLEARING	The transaction was processed by the clearing system and is expected to be credited to the beneficiary. This status occurs when Nium has limited visibility due to clearing or partner constraints.
PAID	DEEMED_PAID	The transaction is considered PAID with high confidence, as the clearing return window has passed without any returns.
SENT_TO_BANK	TIMED_OUT	No response received from the beneficiary bank within the expected time. Final response awaited.

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

Enhancements As per ISO Standards

NIUM has implemented the payments messaging as per the ISO standards for the local ACH transactions

Please note: Currently the ISO messaging will be available for the following currencies

INR, USD, AUD, GBP, EUR

Example Request

Bash
Javascript

curl --location --request POST 'https://<customerHost:Port>/webhook' \\
--header 'Content-Type: application/json' \\
--header 'x-api-key: f9be0d9e-6903-4862-8d69-5b2651426bf9' \\
--data-raw '{
    "reference_number": "1625203888",
    "payment_id": "UATPY103166714",
    "event": "TRANSACTION_STATUS_CHANGE",
    "status": "RETURNED",
    "timestamp": "2021-07-02T05:31:30.530Z",
    "return_reason": {
        "status_code": "ACO1",
        "status_reason": "IncorrectAccountNumber",
        "status_description": "Format of the account number specified is not correct"
    }
}'

var settings = {
  "url": "https://<customerHost:Port>/webhook",
  "method": "POST",
  "timeout": 0,
  "headers": {
    "content-type": "application/json",
    "x-api-key": "f9be0d9e-6903-4862-8d69-5b2651426bf9"
  },
  "data": JSON.stringify({
    "reference_number": "1625203888",
    "payment_id": "UATPY103166714",
    "event": "TRANSACTION_STATUS_CHANGE",
    "status": "RETURNED",
    "timestamp": "2021-07-02T05:31:30.530Z",
    "return_reason": {
        "status_code": "ACO1",
        "status_reason": "IncorrectAccountNumber",
        "status_description": "Format of the account number specified is not correct"
    }
  }),
};

$.ajax(settings).done(function (response) {
  console.log(response);
});

Request Parameters

Parameter	Description	Type
reference_number	Unique reference number for every payout sent by client.	String
payment_id	Unique Id for every payout generated by Nium.	String
event	Event name of the webhook. Here, it will be TRANSACTION STATUS CHANGE	String
status	Payment status values (IN_PROCESS, AWAITING_FUNDS, INFO_REQUESTED, COMPLIANCE_REJECTED, SENT_TO_BANK, PG_PROCESSING, PAID, RETURNED, REJECTED, CANCELLED)	String
timestamp	Date and time of status change.	String
return_reason.status_code	Standard error code provided as per ISO 20022 standards	String
return_reason.status_reason	Standard reason corresponding to ISO error code	String
return_reason.status_description	Enhanced remarks provided by NIUM corresponding to ISO error code	String

GPI Enhancements for Opt-In (Subscription) Clients

Please Note:

Only request body of the webhook is enhanced. The URL and headers of the webhook would remain the same.
The webhook will send a callback as gpi_reason_code or gpi_forward_bank_name changes
These enhancements are for swift wire transactions only.

Example Request

Bash
Javascript

curl --location --request POST 'https://<customerHost:Port>/webhook' \\
--header 'Content-Type: application/json' \\
--header 'x-api-key: f9be0d9e-6903-4862-8d69-5b2651426bf9' \\
--data-raw '{
 "reference_number": "1696852197",
 "payment_id": "PY11486856",
 "event": "TRANSACTION_STATUS_CHANGE",
 "status": "SENT_TO_BANK",
 "timestamp": "2023-10-09T12:25:16.556Z",
 "gpi_details": {
  "gpi_reason_code": "G000",
  "gpi_status_description": "Delivered to next bank",
  "gpi_timestamp": "2023-10-09 01:21:47",
  "gpi_forward_bank_name": "HSBC BANK",
  "gpi_forward_bank_code": "HSBCSGS2",
  "gpi_remarks": "The payment has been forwarded to next participant bank in the swift network. It can be either credited to beneficiary directly or passed to next bank."
 }
}'

var settings = {
  "url": "https://<customerHost:Port>/webhook",
  "method": "POST",
  "timeout": 0,
  "headers": {
    "content-type": "application/json",
    "x-api-key": "f9be0d9e-6903-4862-8d69-5b2651426bf9"
  },
  "data": JSON.stringify({
    "reference_number": "1696852197",
    "payment_id": "PY11486856",
    "event": "TRANSACTION_STATUS_CHANGE",
    "status": "SENT_TO_BANK",
    "timestamp": "2023-10-09T12:25:16.556Z",
    "gpi_details": {
      "gpi_reason_code": "G000",
      "gpi_status_description": "Delivered to next bank",
      "gpi_timestamp": "2023-10-09 01:21:47",
      "gpi_forward_bank_name": "HSBC BANK",
      "gpi_forward_bank_code": "HSBCSGS2",
      "gpi_remarks": "The payment has been forwarded to next participant bank in the swift network. It can be either credited to beneficiary directly or passed to next bank."
    }
  }),
};

$.ajax(settings).done(function (response) {
  console.log(response);
});

Request Body:

Fields	Description	Type
reference_number	Unique reference number for every payout sent by client.	String
payment_id	Unique Id for every payout generated by Nium.	String
event	Event name of the webhook. Here, it will be TRANSACTION STATUS CHANGE	String
status	Payment status values (IN_PROCESS, AWAITING_FUNDS, INFO_REQUESTED, COMPLIANCE_REJECTED, SENT_TO_BANK, PG_PROCESSING, PAID, RETURNED, REJECTED, CANCELLED)	String
timestamp	Date and time of status change.	String
gpi_details.gpi_reason_code	Gpi code shared by Partner (GXXX etc.)	String
gpi_details.gpi_status_description	Description corresponding to Gpi reason code	String
gpi_details.gpi_timestamp	Date and time of Gpi status change.	String
gpi_details.gpi_forward_bank_name	Name of the next participant bank in the swift network to which the payment has been forwarded.	String
gpi_details.gpi_forward_bank_code	Bank identification code (BIC) of the next participant bank to which the payment has been forwarded.	String
gpi_details.gpi_remarks	Detailed description of the gpi_reason_code. This interpretation is provided by Nium.	String

Interpretation of the gpi reason codes and associated status descriptions

Status	gpi_reason_code	gpi_status_description	gpi_remarks
SENT_TO_BANK	G000	Delivered to next bank	The payment has been forwarded to next participant bank in the swift network. It can be either credited to beneficiary directly or passed to next bank.
SENT_TO_BANK	G001	Delivered to next bank (no tracking)	This often suggests the user may not receive gpi updates beyond this point and will receive a final terminal status.
SENT_TO_BANK	G002	Pending credit may not be same day.	Often it means that the payment is under manual due diligence in the bank and settlement may take few hours.
SENT_TO_BANK	G003	Pending receipt of documentation from the beneficiary.	This often suggests an action on the beneficiary or beneficiary bank. Sender may contact the beneficiary in case of delays or can ensure that beneficiary details provided were correct.
SENT_TO_BANK	G004	Pending receipt of funds from the previous bank.	The forward bank has received an instruction to credit the funds the to the beneficiary, but it has not received the funds yet. Cover payment is missing but it is expected to arrive soon.
SENT_TO_BANK	G005	Delivered to beneficiary bank as GPI.	This suggests that the payment will be credited soon.
SENT_TO_BANK	G006	Delivered to beneficiary bank as non-GPI.	This suggests that the payment will be credited soon.

Definition​

Headers:​

Example Request:​

Request Body:​

Sub-status meanings​

Enhancements As per ISO Standards​

Example Request​

Request Parameters​

GPI Enhancements for Opt-In (Subscription) Clients​

Example Request​

Request Body:​

Definition

Headers:

Example Request:

Request Body:

Sub-status meanings

Enhancements As per ISO Standards

Example Request

Request Parameters

GPI Enhancements for Opt-In (Subscription) Clients

Example Request

Request Body: