Making payments with Faster Payments (pain.001)

API Docs

Swagger file

This tutorial describes how you can make Faster Payments (FP) payments with the Payments Hub API.

For this tutorial, consider a scenario where a customer wants to make multiple similar payments to several beneficiaries, for example, a payroll wanting to make their payroll payments. The customer is sending money from their UK or overseas bank account to a UK bank account. If the customer has enough funds in their account, the Payments Hub API can be used to transfer the money to the other account. This tutorial describes how you can first submit the FP payment using the ISO pain.001 message.

Note

• The instructions in this tutorial apply to the sandbox environment.

• The pain.001 requests are not currently supported in the sandbox.

Prerequisites

Before obtaining the access token, make sure you have a public-private key pair that you can use to sign 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:

  eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6InByb1BheW1lbnRzSHViU2IifQ.eyJzdWIiOiJxTWtaOTBxb0hBTjVJbkE2V2xNYVZBaE41dDhBQWVPeCIsImlzcyI6IlNhbnRhbmRlciIsImlhdCI6MTcxMDg0MjgwNCwibmJmIjoxNzEwODQyODA0LCJleHAiOjE3NDIzNzg4MDQsImp0aSI6ImM3YWY0Yzg0LTRkYzQtNDM2Mi05OTA2LWM5ZTg5N2YyNzUzOCJ9.LOaGmVUnQ6I0HYUQWA1y2vUhREaJrAasAxDlqAnxKbEYGmjP6AKeIViLdkBVVPTUWRETxmnlU6fBQRYU0BN8NEJ9dd_uJ20uiPGWp1ieTFvee27LbqqqS-4AbwD_oJluBUzb77cx4P_1o35gFskcFjbzdl5ert4xJvpbXNOQYa0C7f4YQ6wMLjCGkbdhimwRxeOEGVdYiRoVEizkPpNgUZi_H3o58gATIJ4rSSWqLmKvy9aBlK_YAT947klkJI-ej22KU8qgLCInBbBGdoW9gjg8Zpmizs7Xc7eAvNm7QRiAzd1NT6dgX3hAYDJz2m2dnZYS6zE_UPWOi5cbAyQggw

• In the sandbox environment, you can use a predefined test SCA JWT Bearer token:

  eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6InByb1BheW1lbnRzSHViU2IifQ.eyJoZCI6IjVnd2JaSmlzSDI3b3ZVT2pjdnNXTnlPVEk4a2JHSzlIT2VqLzUxb0l6Zlk9Iiwibm9uY2UiOiJiMTVmNzU5MzQwYmRlZmM4MmI2OSIsImFsZyI6IlNIQTI1NiIsImlzcyI6IlNhbnRhbmRlciIsImlhdCI6MTcxMjU1NTg3MSwibmJmIjoxNzEyNTU1ODcxLCJleHAiOjE3NDQwOTE4NzEsImp0aSI6Ijg3ZTNjZTg3LTA3MjctNDI2YS05NjNhLTM2OGNkYmM0ZTQxNiJ9.FBpbOdSZtf6EeZdahGDqJhjLIwN64ORMUAJ6MyD8zeLF8RIczhNnsMOOWFh18Okus59dpU3Nhl2Ev4P2b08aRzyYm__-47zq6JPxbhZoE2lb-xRABEfg7OQzr-b8AiPbfwJKc9cayM2AqUJFDUHsyDK9_RzHJHweCIDiW_EWg1lxCMxZPiMs5YYn6A1SnYMauKfaJaQaBYwOluoLC3IrSbUV4H9Nd_g01NHniO9EgxKIdG07723TgNDzxIeggd_bM1aj_IQAe5uMFpqEGoES06D24_QQCmQbQ0LZ2V_76u9r1E9izkUogYF1_1dFaD_CyzvBLApZjvgHeQkneFnkmw

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 Authentication.

• For detailed instructions on how to get the access token, see Authentication guide.

Submit the payment

This section describes how to submit a payment via a pain.001 HTTP request to the Payments Hub API. It also illustrates a successful response.

Request

Create and send a request using the following operation:

POST https://sandbox.api.pagonxt.com/payments/pain001/v09

Headers

The request must contain the headers shown in the following table.

Table: Submit the payment - Required request headers.

Request body

The request must include a JSON payload object in the request body. The JSON payload is a pain.001 ISO message with the cstmrCdtTrfInitn root element, and it contains the request details for submitting a payment.

The following table only provides information about some especially important fields. For details on all the required and optional message fields, see Message field definition for pain.001.

Table: Submit the payment - Relevant request body elements.

Example request 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"
              ]
            }
          }
        ]
      }
    ]
  }
}

Request example

The following example illustrates the request using raw HTTP code:

POST /payments/pain001/v09 HTTP/1.1
Host: sandbox.api.pagonxt.com
Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN
X-Client-Id: YOUR_CLIENT_ID
sca-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6InByb1BheW1lbnRzSHViU2IifQ.eyJoZCI6IjVnd2JaSmlzSDI3b3ZVT2pjdnNXTnlPVEk4a2JHSzlIT2VqLzUxb0l6Zlk9Iiwibm9uY2UiOiJiMTVmNzU5MzQwYmRlZmM4MmI2OSIsImFsZyI6IlNIQTI1NiIsImlzcyI6IlNhbnRhbmRlciIsImlhdCI6MTcxMjU1NTg3MSwibmJmIjoxNzEyNTU1ODcxLCJleHAiOjE3NDQwOTE4NzEsImp0aSI6Ijg3ZTNjZTg3LTA3MjctNDI2YS05NjNhLTM2OGNkYmM0ZTQxNiJ9.FBpbOdSZtf6EeZdahGDqJhjLIwN64ORMUAJ6MyD8zeLF8RIczhNnsMOOWFh18Okus59dpU3Nhl2Ev4P2b08aRzyYm__-47zq6JPxbhZoE2lb-xRABEfg7OQzr-b8AiPbfwJKc9cayM2AqUJFDUHsyDK9_RzHJHweCIDiW_EWg1lxCMxZPiMs5YYn6A1SnYMauKfaJaQaBYwOluoLC3IrSbUV4H9Nd_g01NHniO9EgxKIdG07723TgNDzxIeggd_bM1aj_IQAe5uMFpqEGoES06D24_QQCmQbQ0LZ2V_76u9r1E9izkUogYF1_1dFaD_CyzvBLApZjvgHeQkneFnkmw
Content-Length: 3966

{
    "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"
                            ]
                        }
                    }
                ]
            }
        ]
    }
}

Response

If the request is valid, you receive an HTTP 201 Created response, which means that the payment was successfully submitted. In addition, the response body returns the data JSON object, which contains details of the submitted payment. If the request is submitted again with the same message ID, you receive an HTTP 200 OK response. For further details of HTTP response codes and instructions on how to handle errors, see HTTP codes and request error handling.

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 Message field definition for pain.001.

Table: Submit the payment - Relevant response body elements.

Example response body:

  "data": {
    "paymentsHubId": "8b8464bf-9a53-3d3e-916e-3793f84c4ae7",
    "paymentId": "SGP01234567890123",
    "status": "PENDING",
    "creationDateTime": "2024-02-21T07:21:27.243844"
  }
}