- 18 Sep 2024
- 12 Minutes to read
- Print
- DarkLight
Getting payment return details (pacs.004)
- Updated on 18 Sep 2024
- 12 Minutes to read
- Print
- DarkLight
This tutorial describes how you can get payment return details with the Payments Hub API.
For this tutorial, consider a scenario where a merchant has received a payment, which they have returned to the payee for some reason, and they later want to see the payment return ID and return amount for that return. The Payments Hub API can be used to retrieve these details. The tutorial describes how you can retrieve the payment return details using the ISO pacs.004 message.
Note
The instructions in this tutorial apply to the sandbox environment.
Prerequisites
Before obtaining the access token, make sure you have a public-private key pair that you can use to sign JWT Bearer tokens.
Click here to email your public key, along with the kid and iss claim values you will use in your JWT Bearer tokens.
Note
The public key must be created with RSA and sent in PEM format, without password encryption, and must have a length of at least 2048 bits. If these criteria are not met, the token will be rejected.
If you don't have a public-private key pair yet, you can use a predefined JWT Bearer token in the sandbox with no need to create or sign your own tokens for authentication:
eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6Ikh1YnRlc3RfcHJvX3NhbmRib3gifQ.eyJzdWIiOiJxTWtaOTBxb0hBTjVJbkE2V2xNYVZBaE41dDhBQWVPeCIsImlzcyI6IlNhbnRhbmRlciIsImlhdCI6MTY2MTMyNzQyNSwibmJmIjoxNjYxMzI3NDI1LCJleHAiOjE2OTI4NjM0MjUsImp0aSI6IjRmMjM0ZmIxLWM3ODAtNGVhNS05YmI5LTBkMTZiYzU3MmFmNyJ9.lz19moa2xSUeBoz4-55qF15CY_LU-1Vb7bh14Q1pGjqR7hEL3OdxK9-EnWSP4eDMivMZWTHOXbFTj9WcH0eiX1u7fNJVVhyWTUqvIfI5Qcpal2j2pQElLe9mv7bytMGPbDpK-9kNqkuNX4J_LB7qLZJtPwSbsFtICORpLrBeMHwqWLRnaFVOMuiMM14CXG31YaKNVphowthVA_21CuE0P5Tl5iIlJIx0MENoq_pbmQpFkuN0VlxW7gv9Zrqo44Vd4TtoZiF4uY-PgbT3JDnbEe5pRa7C4vF-LHrdgfpNW9fjW9kut-ZuyeEIH240t6emstsdtcFAC18TpZjo9HM3sw
1. Authenticate to get an access token
The Payments Hub API endpoints are protected with OAUTH 2.0 JWT Bearer grant. To use the API, you must create a JWT Bearer token and use it to get an access token:
To create a JWT Bearer token, see the Appendix in Authentication guide. For a predefined token that you can use in the sandbox for testing purposes, see the Prerequisites in Authentication guide.
For detailed instructions on how to get the access token, see Authentication guide.
2. Retrieve the payment return details
This section describes how to retrieve the payment return details via a pacs.004 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/pacs004/v09/{paymentsHubId}
Headers
The request must contain the headers shown in the following table.
Table: Retrieve payment return details – Required request headers
Header name | Description | Required/ Optional | Values |
---|---|---|---|
Authorization | Authorization security header | 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 return details – Request parameter
Parameter type | Parameter name | Description | Data format | Required/ Optional |
---|---|---|---|---|
Path | paymentsHubId | Payments Hub ID related to the payment return whose details you want to retrieve. This is the value you received when you originally submitted the payment return request. | String | Required |
Request example
The following example illustrates the request using raw HTTP code:
GET /payments/pacs004/v09/YOUR_PAYMENTS_HUB_ID HTTP/1.1
Host: sandbox.api.pagonxt.com
Authorization: Bearer YOUR_ACCESS_TOKEN
X-Client-Id: YOUR_CLIENT_ID
Response
If the request is valid, you receive an HTTP 200 OK response, which means that the payment return 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 pmtRtr JSON object, which contains a pacs.004 ISO message. This message contains different elements depending on which payment scheme was used in the original transaction.
Response body
The following table shows the response body elements that are relevant for the current use case for the Faster Payments (FP) payment scheme. For details on all the response body elements for all supported payment schemes, see the Message field definition for pacs.004 .
Table: Retrieve payment return details – Relevant response body elements
Element | Description | Data type |
---|---|---|
txInf.rtrlId | Unique payment return ID for the end customer | String |
txInf.rtrdIntrBkSttlmAmt | Data structure containing the payment currency and the amount to be returned. The currency is GBP, and the amount is a positive value that is equal to or less than the original payment amount. | Object |
Extract the values of the txInf.rtrlId, txInf.rtrdIntrBkSttlmAmt.value, and txInf.rtrdIntrBkSttlmAmt.ccy keys to see the payment return ID, amount, and currency.
Example response body for the FP payment scheme:
{
"pmtRtr": {
"grpHdr": {
"msgId": "msgId-6937484558",
"creDtTm": "2024-08-01T08:00:00.000+02:00",
"nbOfTxs": "1",
"sttlmInf": {
"sttlmMtd": "CLRG"
}
},
"txInf": [
{
"rtrId": "rtrId-6937484558",
"rtrdIntrBkSttlmAmt": {
"value": 10.04,
"ccy": "GBP"
},
"intrBkSttlmDt": "2024-08-01",
"chrgBr": "SLEV",
"instgAgt": {
"finInstnId": {
"bicfi": "ABBYGB20XXX"
}
},
"instdAgt": {
"finInstnId": {
"bicfi": "BSCHESM0XXX"
}
},
"rtrRsnInf": [
{
"rsn": {
"cd": "AC01"
},
"addtlInf": [
"raw-code",
"raw-description"
]
}
],
"orgnlTxRef": {
"pmtTpInf": {
"svcLvl": [
{
"prtry": "FP"
}
],
"lclInstrm": {
"prtry": "RTP"
}
},
"rmtInf": {
"strd": [
{
"cdtrRefInf": {
"ref": "validRef123"
}
}
]
},
"dbtr": {
"pty": {
"nm": "Debtor",
"pstlAdr": {
"adrTp": {
"cd": "ADDR"
},
"dept": "CL",
"strtNm": "NAME",
"bldgNm": "1",
"flr": "1",
"room": "D",
"pstCd": "EC1A 1AL",
"twnNm": "LONDON",
"twnLctnNm": "LONDON",
"ctrySubDvsn": "LONDON",
"ctry": "UK",
"adrLine": [
"CL. NAME, 1 1 D",
"EC1A 1AL LONDON LONDON"
]
},
"id": {
"prvtId": {
"othr": [
{
"id": "debitor-id"
}
]
}
}
}
},
"dbtrAcct": {
"id": {
"othr": {
"id": "12345678"
}
}
},
"dbtrAgt": {
"finInstnId": {
"bicfi": "ABBYGB20",
"clrSysMmbId": {
"mmbId": "777241"
}
}
},
"cdtrAgt": {
"finInstnId": {
"bicfi": "BSCHGBM0XXX",
"adrTp": {
"cd": "ADDR"
},
"dept": "CL",
"strtNm": "NAME",
"bldgNm": "1",
"flr": "2",
"room": "I",
"pstCd": "EC1A 1AL",
"twnNm": "LONDON",
"twnLctnNm": "LONDON",
"ctrySubDvsn": "LONDON",
"ctry": "UK",
"adrLine": [
"CL. NAME, 1 2 I",
"EC1A 1AL LONDON LONDON"
]
}
}
},
"cdtrAcct": {
"id": {
"iban": "GB91BARC20032634945865"
},
"ccy": "GBP"
}
}
}
]
}
}