Getting payment details (pain.001)
This tutorial describes how you can get payment details with the Payments Hub API.
For this tutorial, consider a scenario where a customer wants to see the details of a payment they have previously made. The Payments Hub API can be used to retrieve these details. The tutorial describes how you can retrieve the payment details using the ISO pain.001 message.
Note
The instructions in this tutorial apply to the sandbox environment.
Retrieve the payment details
This section describes how to retrieve the payment details via a pain.001 HTTP request to the Payments Hub API. To send this request, you need to provide the Payments Hub ID. This section also illustrates a successful response.
Request
Create and send a request using the following operation:
GET https://sandbox.api.pagonxt.com/payments/pain001/v09/{paymentsHubId}Headers
The request must contain the headers shown in the following table.
Table: Retrieve payment details – Required request headers.
Header name | Description | Required/ Optional | Values |
|---|---|---|---|
Authorization | Authorization basic security header. To create the value, use the client ID (user) and client secret (password) you received when registering your app. | Required | Bearer <Access token> |
X-Client-Id | Client ID | Required | <Client ID> |
Accept | Format of the response body | Required | application/json |
Parameters
The request must contain the path parameter shown in the following table.
Table: Retrieve payment details – Request parameters.
Parameter type | Parameter name | Description | Data format | Required/ Optional |
|---|---|---|---|---|
Path | paymentsHubId | Payments Hub ID related to the payment whose details you want to retrieve. This is the value you received when you originally submitted the payment. | String | Required |
Request example
The following example illustrates the request using raw HTTP code:
GET /payments/pain001/v09/YOUR_PAYMENTS_HUB_ID HTTP/1.1
Host: sandbox.api.pagonxt.com
Content-Type: application/json
Authorization: Bearer 7f697073-cddf-4b51-995f-aab611fe8ae9
X-Client-Id: YOUR_CLIENT_IDResponse
If the request is valid, you receive an HTTP 200 OK response, which means that the payment details were successfully retrieved. For further details of HTTP response codes and instructions on how to handle errors, see HTTP codes and request error handling.
In addition to the response code, the response body returns the cstmrCdtTrfInitn JSON object, which contains a pain.001 ISO message.
Response body
The following table shows the response body elements that are relevant for the current use case. For details on all the response body elements, see the Message field definition for pain.001.
Extract the values of the details you are interested in.
Table: Retrieve payment details – Relevant response body elements.
Element | Description | Data type |
|---|---|---|
grpHdr.nbOfTxs | Number of transactions within the message. Value: 1 | String |
grpHdr.initgPty.nm | Name of the payment initiating party (debtor or a party acting on behalf of the debtor) | String |
grpHdr.msgId | Message ID, which uniquely identifies each request that was sent. This ID is used internally for idempotency of the API. | String |
grpHdr.creDtTm | Date and time of the payment request | String |
pmtInf.pmtInfId | Unique identification of the payment information group within the request | String |
pmtInf.pmtMtd | Payment method used. The value is TRF. | String |
pmtInf.btchBookg | Whether a single entry per individual transaction or a batch entry for the sum of the amounts of all transactions within the group is requested. The value is false. | Boolean |
pmtInf.reqdExctnDt | Date when the initiating party wants the clearing agent to process the payment | String |
pmtInf.pmtTpInf.svcLvl.prtry | Proprietary service level. The value is FP. | String |
pmtInf .dbtr .dbtrAcct .dbtrAgt | Data structures containing the details for the debtor, the debtor’s account, and the debtor agent | Object |
pmtInf.cdtTrfTxInf.pmtId.instrId | Instruction ID used to uniquely identify the instruction | String |
pmtInf.cdtTrfTxInf.pmtId.endToEndId | End-to-end ID, which can be used to track the transaction between payment systems. | String |
pmtInf.cdtTrfTxInf.pmtTpInf.lclInstrm.prtry | Faster Payments Scheme (FPS) processing code. The possible values are:
| String |
pmtInf.cdtTrfTxInf .intrmyAgt1 .intrmyAgt1Acct | Data structures containing the details for the intermediary agent, and the intermediary agent’s account. These structures are used only for overseas payments (payments originating from outside the UK). | Object |
pmtInf.cdtTrfTxInf.amt | Data structure containing the amount of money to be moved between the debtor and creditor, before deduction of charges, expressed in the currency as ordered by the initiating party. The currency is GBP and the amount is a positive value. | Object |
pmtInf.cdtTrfTxInf .cdtr .cdtrAgt .cdtrAcct | Data structures containing the details for the creditor, the creditor’s account, and the creditor agent | Object |
pmtInf.cdtTrfTxInf.rmtInf | Data structure containing remittance details, either in unstructured or structured form | Object |
Example response body:
{
"cstmrCdtTrfInitn":
{
"grpHdr":
{
"nbOfTxs": "1",
"initgPty":
{
"nm": "CROSSFITXP"
},
"msgId": "SGP01234567890123",
"creDtTm": "2024-03-08T18:04:25.000Z"
},
"pmtInf":
[
{
"pmtInfId": "SGP01234567890123",
"pmtMtd": "TRF",
"btchBookg": false,
"reqdExctnDt": "2024-03-08",
"pmtTpInf":
{
"svcLvl":
{
"prtry": "FP"
}
},
"dbtr":
{
"nm": "CROSSFIT EXPERIENCE (UK) LIMITED",
"pstlAdr":
{
"ctry": "GB"
}
},
"dbtrAcct":
{
"id":
{
"othr":
{
"id": "12345678"
}
}
},
"dbtrAgt":
{
"finInstnId":
{
"clrSysMmbId":
{
"mmbId": "012345"
}
}
},
"cdtTrfTxInf":
[
{
"pmtId":
{
"endToEndId": "Sarah Connor"
},
"pmtTpInf":
{
"lclInstrm":
{
"prtry": "10"
}
},
"amt":
{
"instdAmt":
{
"ccy": "GBP",
"value": 1500
}
},
"cdtr":
{
"nm": "John Doe",
"pstlAdr":
{
"ctry": "GB"
}
},
"cdtrAcct":
{
"id":
{
"othr":
{
"id": "01234567"
}
}
},
"cdtrAgt":
{
"finInstnId":
{
"clrSysMmbId":
{
"mmbId": "012345"
},
"pstlAdr":
{
"ctry": "GB"
}
}
},
"rmtInf":
{
"strd":
[
{
"cdtrRefInf":
{
"ref": "CROSSFIT PAYROLL"
}
}
],
"ustrd":
[
"CROSSFIT PAYROLL"
]
}
}
]
}
]
}
}