Notifications

The Payments Hub API supports the use of notifications, an opt-in feature that allows you to receive an alert when the status changes for a payment that you have initiated. Notifications are messages that can be sent to your server as an HTTP POST request to allow you to stay informed of the current status of your outgoing or incoming payments, without having to constantly query Payments Hub.

Payments Hub notifications

In Payments Hub, notifications allow you to track the status of each payment or refund that you have initiated. You can also track incoming payments. Each time the payment status changes, a message can be sent from Payments Hub to the defined server endpoint as an HTTP POST request, which can then be processed within your app.

Notifications can be configured to contain:

• URLs that can be used as GET requests to retrieve the original payment or status details.

• Original payment details (such as pacs.008).

• Status report details (such as pacs.002).

Note

Notifications are currently only available in the live environment of Payments Hub, not in the sandbox environment.

Webhook notifications

Webhook notifications do not contain the actual payment. Instead, they contain the location where the details of the original payment and its status report can be obtained.

This type of notification contains URIs, which can be found in the originalMessage and statusReportMessage fields of the received message, respectively. The originalMessage field contains the endpoint URI that can be used to retrieve the original message, such as a pacs.008 or camt.056 message, and the statusReportMessage field contains the endpoint URI that can be used to retrieve the status report, such as a pacs.002 or camt.029 message.

The Webhook notification also contains a paymentsHubId field, which is the unique identifier of your payment used in Payments Hub.

Use these URIs to call Payments Hub to obtain the details of the payment.

The following is an example of a Webhook notification sent by Payments Hub:

json

{

paymentsHubId=58857c5e-fe4a-3d44-ac63-e17b3820139f,

originalMessage=/payments/pacs008/v08/58857c5e-fe4a-3d44-ac63-e17b3820139f,

statusReportMessage=/payments/pacs002/10/58857c5e-fe4a-3d44-ac63-e17b3820139f

}

Payment notifications

Payment notifications contain the payment details. In this case, the actual payment message will be sent in the notification instead of URIs. This type of notification can be configured to have the original message or the status report.

For example, if payment notification is configured to send the original message and you send a payment using a pacs.008 message, the payment notification you receive contains the pacs.008 message you submitted instead of the status report (pacs.002).

Example with original message

The following is an example of a payment notification that contains the original message (pacs.008). This content is in the body of the HTTP POST sent by Payments Hub.

json

{
  "fitoFICstmrCdtTrf": {
    "grpHdr": {
      "msgId": "1638782807448",
      "creDtTm": "2022-02-03T11:08:19.664+01:00",
      "nbOfTxs": "1",
      "sttlmInf": {
        "sttlmMtd": "CLRG"
      }
    },
    "cdtTrfTxInf": [
      {
        "pmtId": {

          "endToEndId": "e2eId-1638782807448",
          "txId": "txId1638782807448"
        },
        "pmtTpInf": {
          "svcLvl": [
            {
              "prtry": "FP"
            }
          ],
          "lclInstrm": {
            "prtry": "SIP"
          }
        },
        "intrBkSttlmAmt": {
          "value": 10,
          "ccy": "GBP"
        },
        "chrgBr": "SHAR",
        "dbtr": {
          "nm": "John Doe",
          "pstlAdr": {
            "twnNm": "miltonKeynes",
            "ctry": "GB",
            "adrLine": [
              "Somewhere in MK"
            ]

          }
        },
        "dbtrAcct": {
          "id": {
            "othr": {
              "id": "12345678"
            }

          }
        },
        "dbtrAgt": {
          "finInstnId": {
            "bicfi": "XXXXXXXX",
            "clrSysMmbId": {
              "mmbId": "090401"
            },
            "pstlAdr": {
              "twnNm": "miltonKeynes",
              "ctry": "GB",
              "adrLine": [
                "Somewhere in MK"
              ]
            }

          }
        },
        "cdtrAgt": {
          "finInstnId": {
            "bicfi": "XXXXXXXX",
            "clrSysMmbId": {
              "mmbId": "090401"
            },
            "pstlAdr": {
              "twnNm": "miltonKeynes",
              "ctry": "GB",
              "adrLine": [
                "Somewhere in MK"
              ]
            }

          }
        },
        "cdtr": {
          "nm": "Jane Doe",
          "pstlAdr": {
            "twnNm": "miltonKeynes",
            "ctry": "GB",
            "adrLine": [
              "Somewhere in MK"
            ]
          }

        },
        "cdtrAcct": {
          "id": {
            "iban": "ES6200491500022915408932"
          }
        },
        "rmtInf": {

          "strd": [
            {
              "cdtrRefInf": {
                "ref": "rmtInf1638782807448"
              }
            }
          ]
        }
      }
    ]
  }
}

Example with status report

The following is an example of a payment notification that contains the status report (pacs.002). This content is in the body of the HTTP POST sent by Payments Hub.

{
  "fitoFIPmtStsRpt": {
    "grpHdr": {
      "msgId": "1638805803",
      "creDtTm": "2021-12-06T15:50:02.957Z"
    },
    "txInfAndSts": [
      {
        "orgnlGrpInf": {
          "orgnlMsgId": "1638805800047",
          "orgnlMsgNmId": "pacs.008.001.08"
        },
        "txSts": "ACSC",
        "stsRsnInf": [
          {
            "rsn": {
              "cd": "G000"
            },
            "addtlInf": [
              "PaymentTransferredAndTracked",
              "The Status Originator transferred the payment to the next Agent. The payment transfer is tracked."
            ]
          }
        ]
      }
    ]
  }
}

Registering for notifications

Registering to receive notifications takes place during your onboarding process.

You need to provide at least 1 full URL of a server endpoint where Payments Hub can send HTTP POST requests containing the notifications. You can define different server endpoints for different notifications.

When you register for notifications, you can determine exactly what kind of notifications you want to receive. For example, for pacs.008 you can receive Webhook notifications on endpoint A while for pacs.007 you can receive payment notifications on endpoint B.

Notifications are sent over an encrypted connection between Payments Hub and your server. The exact authentication mechanism is agreed during the onboarding process and usually involves API keys and tokens.

Receiving notifications

When a notification from Payments Hub is received, you do not need to send a formal acknowledgement, but your system must return a 200 OK response as soon as the notification is received.