Receiving payments (pacs.008)
  • 18 Sep 2024
  • 10 Minutes to read
  • Dark
    Light

Receiving payments (pacs.008)

  • Dark
    Light

Article summary


This tutorial describes how you can use information from notifications to get details about incoming payments with the Payments Hub API.

For this tutorial, consider a scenario where you have registered to receive a notification whenever you receive a new payment. When an incoming payment notification arrives, the beneficiary wants to see the payment amount and who has sent it. The Payments Hub API can be used to retrieve these details. The tutorial describes how you can retrieve the payment details using the ISO pacs.008 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:

2. Retrieve the payment details

This section describes how to retrieve the details of the incoming payment via a pacs.008 HTTP request to the Payments Hub API. To send this request, you need to provide the Payments Hub ID that was provided in the notification. For information, see Notifications . This section also illustrates a successful response.

Note

Notifications are not used in the sandbox environment.

Request

Create and send a request using the following operation:

GET https://sandbox.api.pagonxt.com/payments/pacs008/v08/{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 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 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 in the notification.

String

Required

Request example

The following example illustrates the request using raw HTTP code:

GET /payments/pacs008/v08/YOUR_PAYMENTS_HUB_ID HTTP/1.1
Host: sandbox.api.pagonxt.com
Content-Type: application/json
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 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 fitoFICstmrCdtTrf JSON object, which contains a pacs.008 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.008 .

Extract the value of the cdtTrfTxInf.dbtr.nm and cdtTrfTxInf.intrBkSttlmAmt.value keys to see the debtor name and amount for the payment.

Table: Retrieve payment details – Relevant response body elements.

Element

Description

Data type

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 submission request

String

grpHdr.nbOfTxs

Number of transactions within the message.

Value: 1

String

grpHdr.ttlIntrBkSttlmAmt

Data structure containing the payment currency and the amount for the total interbank settlement.

The currency is GBP and the amount is a positive value.

If these fields are used, the amount is equal to the sum of all the transactions in the message.

Object

grpHdr.sttlmInf.sttlmMtd

Settlement method.

Value: CLRG

String

cdtTrfTxInf.pmtId.endToEndId

End-to-end ID, which can be used to track the transaction between payment systems.

If the ID is not available, the value is NOT PROVIDED.

String

cdtTrfTxInf.pmtId.txId

Transaction ID, which uniquely identifies each transaction within the message

String

cdtTrfTxInf.pmtTpInf.svcLvl.prtry

Payment scheme type.

Value: FP

String

cdtTrfTxInf.pmtTpInf.lclInstrm.prtry

Faster Payments Scheme (FPS) processing code

String

cdtTrfTxInf.pmtTpInf.ctgyPurp.prtry

Payment channel

String

cdtTrfTxInf.intrBkSttlmAmt

Data structure containing the payment currency and the amount that was transferred.

The currency is GBP and the amount is a positive value.

Object

cdtTrfTxInf.chrgBr

Charge bearer type.

The possible values are:

  • SLEV = Charges are applied according to the rules agreed in the service level and/or scheme

  • SHAR = Charges on the sender side are borne by the debtor, and charges on the receiver side are borne by the creditor

String

cdtTrfTxInf

► .intrmyAgt1

► .intrmyAgt1Acct

Data structures containing the details for the intermediary agent and the agent's account.

These structures are required if multiple agencies and agency accounts have been used for debiting.

Object

cdtTrfTxInf

► .dbtr

► .dbtrAcct

► .dbtrAgt

Data structures containing the details for the debtor, the debtor’s account, and the debtor agent

Object

cdtTrfTxInf

► .cdtrAgt

► .cdtr

► .cdtrAcct

Data structures containing the details for the creditor agent, the creditor, and the creditor’s account

Object

cdtTrfTxInf.rmtInf

Data structure containing remittance details

Object

Example response body for the FP payment scheme:

{
    "fitoFICstmrCdtTrf": {
        "grpHdr": {
            "msgId": "MsgId-44458394999944",
            "creDtTm": "2022-02-03T11:08:19.664+01:00",
            "nbOfTxs": "1",
            "sttlmInf": {
                "sttlmMtd": "CLRG"
            }
        },
        "cdtTrfTxInf": [
            {
                "pmtId": {
                    "endToEndId": "e2eId-1587641040",
                    "txId": "111112"
                },
                "pmtTpInf": {
                    "svcLvl": [
                        {
                            "prtry": "FP"
                        }
                    ],
                    "lclInstrm": {
                        "prtry": "SIP"
                    }
                },
                "intrBkSttlmAmt": {
                    "value": 10.04,
                    "ccy": "GBP"
                },
                "chrgBr": "SHAR",
                "dbtr": {
                    "nm": "Steve",
                    "pstlAdr": {
                        "twnNm": "miltonKeynes",
                        "ctry": "GB",
                        "adrLine": [
                            "Somewhere in MK"
                        ]
                    }
                },
                "dbtrAcct": {
                    "id": {
                        "othr": {
                            "id": "12345678"
                        }
                    }
                },
                "dbtrAgt": {
                    "finInstnId": {
                        "bicfi": "ABBYGB20",
                        "clrSysMmbId": {
                            "mmbId": "090401"
                        },
                        "pstlAdr": {
                            "twnNm": "miltonKeynes",
                            "ctry": "GB",
                            "adrLine": [
                                "Somewhere in MK"
                            ]
                        }
                    }
                },
                "cdtrAgt": {
                    "finInstnId": {
                        "bicfi": "ABBYGB3E",
                        "clrSysMmbId": {
                            "mmbId": "090401"
                        },
                        "pstlAdr": {
                            "twnNm": "miltonKeynes",
                            "ctry": "GB",
                            "adrLine": [
                                "Somewhere in MK"
                            ]
                        }
                    }
                },
                "cdtr": {
                    "nm": "Creditor",
                    "pstlAdr": {
                        "twnNm": "miltonKeynes",
                        "ctry": "GB",
                        "adrLine": [
                            "Somewhere in MK"
                        ]
                    }
                },
                "cdtrAcct": {
                    "id": {
                        "iban": "GB91BARC09023134945865"
                    }
                },
                "rmtInf": {
                    "strd": [
                        {
                            "cdtrRefInf": {
                                "ref": "validref123"
                            }
                        }
                    ]
                }
            }
        ]
    }
}


Was this article helpful?