Get Payment by ID

Get details for a specific payment by payment_ID.

Definition

URL

GET https://api-test.instarem.com:4803/api/v1/payments/id/{payment_id}

Header Parameters

Parameter	Description	Type	Required
authorization	Authentication token	String	Yes
content-type	The Content-Type entity header is used to indicate the media type of the resource. Expected value is application/json.	String	Yes
X-CLIENT-ID	Unique id for client generated by Nium, Required only in case of partner based model (E.g. 593feb7c7c52bb2357b2df6c).	String	No

Example Request

Bash

curl --request get \\
--url "https://api-test.instarem.com:4803/api/v1/payments/id/{payment_id}" \\
--header 'authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE0OTgxMzQ4OTQsImRhdGEiOnsic3ViIjoiNTk0MjNmMzZjZWEyMTQ2OTI2ODczOWE1IiwiY2xpZW50IjoiNTk0MjNmMzZjZWEyMTQ2OTI2ODczOWExIn0sImlhdCI6MTQ5ODA0ODQ5NH0.pevwSDpk-JDNtVIpqFu_m0Xu1UnDVumrAYStcrxf8sM' \\

Javascript

var data = JSON.stringify({})
var xhr = new XMLHttpRequest();
xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});
xhr.open("get", "https://api-test.instarem.com:4803/api/v1/payments/id/{payment_id}")
xhr.setRequestHeader("authorization", "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE0OTgxMzQ4OTQsImRhdGEiOnsic3ViIjoiNTk0MjNmMzZjZWEyMTQ2OTI2ODczOWE1IiwiY2xpZW50IjoiNTk0MjNmMzZjZWEyMTQ2OTI2ODczOWExIn0sImlhdCI6MTQ5ODA0ODQ5NH0.pevwSDpk-JDNtVIpqFu_m0Xu1UnDVumrAYStcrxf8sM");
xhr.send(data);

C#

var client = new RestClient("https://api-test.instarem.com:4803/api/v1/payments/id/{payment_id}");
var request = new RestRequest(Method.GET);
request.AddHeader("authorization", "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE0OTgxMzQ4OTQsImRhdGEiOnsic3ViIjoiNTk0MjNmMzZjZWEyMTQ2OTI2ODczOWE1IiwiY2xpZW50IjoiNTk0MjNmMzZjZWEyMTQ2OTI2ODczOWExIn0sImlhdCI6MTQ5ODA0ODQ5NH0.pevwSDpk-JDNtVIpqFu_m0Xu1UnDVumrAYStcrxf8sM");
request.AddParameter("application/json", @"{}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);

Path Parameters

Parameter	Description	Type	Required
payment_id	Authentication token	String	Yes

Example Response

{
    "reference_number": "ZQ1101",
    "payment_id": "PY10001485",
    "status": "PAID",
    "autobookfx_confirmation_id": "USD-MYR-SJtfvAOQb",
    "sub_status": "",
    "status_description": "Payment successfully done",
    "created_at": "2017-06-16T17:25:52.136+05:30",
    "updated_at": "2017-06-16T17:26:20.670+05:30"
}

Response Parameters

Parameter	Description	Type
reference_number	Transaction Reference Number	String
payment_id	Transaction id	String
status	Transaction Status	String
autobookfx_confirmation_ id	Unique confirmation ID generated by Nium for successful AutoBook Fx.	String
sub_status	Transaction Sub Status	String
status_description	Transaction Status details	String
created_at	Date and time (UTC) of transaction.	String
updated_at	Date and time (UTC) of transaction.	String
payment_reference_number	Payment confirmation number from the bank	String

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 Response

{
    "reference_number": "ZQ1101",
    "payment_id": "PY10001485",
    "status": "RETURNED",
    "autobookfx_confirmation_id": "USD-MYR-SJtfvAOQb",
    "sub_status": "",
    "status_description": "No account or incorrect account",
    "created_at": "2017-06-16T17:25:52.136+05:30",
    "updated_at": "2017-06-16T17:26:20.670+05:30",
    "return_reason" : {
    	"status_code" : "ACO1",
      "status_reason" : "IncorrectAccountNumber",
      "status_description" : "Format of the account number specified is not correct"
    }
}

Response Parameters

Parameter	Description	Type
reference_number	Transaction Reference Number	String
payment_id	Transaction id	String
status	Transaction Status	String
autobookfx_confirmation_id	Unique confirmation ID generated by Nium for successful AutoBook Fx.	String
sub_status	Transaction Sub Status	String
status_description	Transaction Status details	String
created_at	Date and time (UTC) of transaction.	String
updated_at	Date and time (UTC) of transaction.	String
payment_reference_number	Payment confirmation number from the bank	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:

1. Only the response parameters of API are enhanced. URL, headers and path parameters of the request body remains the same.
2. For opt-in clients, the entire GPI details array listing current and historical GPI parameters would appear in the response.
3. These enhancements are for swift wire transactions only.

Example Response

{
    "reference_number": "ZQ1101",
    "payment_id": "PY10001485",
    "status": "SENT_TO_BANK",
    "autobookfx_confirmation_id": "USD-MYR-SJtfvAOQb",
    "sub_status": "",
    "status_description": "Payment successfully done",
    "created_at": "2017-06-16T17:25:52.136+05:30",
    "updated_at": "2017-06-16T17:26:20.670+05:30",
    "gpi_details": [
      {
        "status": "SENT_TO_BANK",
        "gpi_reason_code": "G002",
        "gpi_status_description": "Pending credit may not be same day.",
        "gpi_timestamp": "2023-08-27 11:51:47",
        "gpi_forward_bank_name": "Natwest",
        "gpi_forward_bank_code": "NWBKGB2LXXX",
        "gpi_remarks": "Often it means that the payment is under manual due diligence in the bank and settlement may take few hours."
      },
    	{
        "status": "SENT_TO_BANK",
        "gpi_reason_code": "G000",
        "gpi_status_description": "Delivered to next bank",
        "gpi_timestamp": "2023-08-27 11:29:47",
        "gpi_forward_bank_name": "HSBC",
        "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."
      }
    ]
}

Response Parameters

Parameter	Description	Type
reference_number	Transaction Reference Number	String
payment_id	Transaction id	String
status	Transaction Status	String
autobookfx_confirmation_id	Unique confirmation ID generated by Nium for successful AutoBook Fx.	String
sub_status	Transaction Sub Status	String
status_description	Transaction Status details	String
created_at	Date and time (UTC) of transaction.	String
updated_at	Date and time (UTC) of transaction.	String
payment_reference_number	Payment confirmation number from the bank	String
gpi_details.status	Transaction Status at the instance of GPI status update (It can be different from final transaction status)	String
gpi_details.gpi_reason_code	GPI code shared by Partner (GXXX)	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.