Refunding payments with Faster Payments (pacs.007 and pacs.002)

This tutorial describes how you can refund (reverse) Faster Payments (FP) payments with the Refund API (also known as the pacs.007 endpoint of the Payments Hub API).

For this tutorial, consider a scenario where you are a payment provider, and your UK-based merchant has a customer in the UK who purchases an item for which they later want a refund. The Refund API can be used to reverse the GBP transfer and return part of the money from the merchant account to the customer's account.

This tutorial describes, in 2 separate sections, how:

• You can initiate a refund for an FP payment using the ISO pacs.007 message.

• You can receive a notification of the refund, allowing you to retrieve its status using the ISO pacs.002 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.

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.eyJoZCI6Im9XSEZldFBZbzM5YUl1cTU2ZEdyb1BDV0ZudlRiREJOdENPRnNsY1VIdUU9Iiwibm9uY2UiOiI0MGRkMGRlZDJkNDk4OTJlNmZkOCIsImFsZyI6IlNIQTI1NiIsImlzcyI6IlNhbnRhbmRlciIsImlhdCI6MTcxMjA1MTUyMSwibmJmIjoxNzEyMDUxNTIxLCJleHAiOjE3NDM1ODc1MjEsImp0aSI6IjIzY2ExNjQyLTYxMjAtNDg4MC1iMDU1LTEwMzZhNjMxNjcxMCJ9.aoJ1hGVPg4ArEb3gdu0VO7rhnL2SpsRXAtZTk-Ou3CWKYZ1u4_Y31MjGQuYabUHJf8GHMT8h_jsHjyxkqcp6tgkZB7cTYgb9nScwSGYQ0jGCul_-v7YUH6zByt7HBfb2XA3XhzcxOLLCkajAQErWCgvHytW0c5x6lQNFSBfrSdCNmuE3cAnu5sabYRtgFeX_L59JbOkLB5raGltiYT627G1M1RF_Lfjc0dvc4szXlKDhIwYFm-6Z5-pazsDaK03zZ27pnrUo1O7pWhPRJz5l02clipE_e-JktOFcpnESPMifZaDeu8P54gGP0-zEqJFJCuGaXahRc-HYhEAxSnBnmQ

1. Authenticate to get an access token

The Payments Hub API endpoints (including the Refund API) 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. Refund the payment

A customer is not happy with their purchase and they request a refund from your merchant, who forwards the request to you. You can then initiate the payment refund using the pacs.007 HTTP request.

This section describes how to make a partial refund via a pacs.007 HTTP request to the Refund API. It also illustrates a successful response.

Request

Create and send a request using the following operation:

POST https://sandbox.apis.santander.com/payments/pacs007/v08

Headers

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

Table: Refund the payment - Required request headers.

Request body

The request must include a JSON payload object in the request body. The JSON payload is a pacs.007 ISO message with the fitoFIPmtRvsl root element, and it contains the request details for refunding 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 pacs.007 .

Table: Refund the payment - Relevant request body elements.

Example request body:

{
  "fitoFIPmtRvsl": {
    "grpHdr": {
      "msgId": "12345324543",
      "creDtTm": "2019-05-16T16:31:49-04:00",
      "nbOfTxs": 1,
      "sttlmInf": {
        "sttlmMtd": "CLRG"
      }
    },
    "txInf": [{
      "rvslId": "12345324543",
      "rvsdIntrBkSttlmAmt": {
        "value": 0.01,
        "ccy": "GBP"
      },
      "rvslRsnInf": [{
        "addtlInf": ["My own inbound reference"]
      }]
    }]
  }
}

Request example

The following example illustrates the request using raw HTTP code:

POST /payments/pacs007/v08 HTTP/1.1
Host: sandbox.apis.santander.com
Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN
X-Santander-Client-Id: YOUR_CLIENT_ID
sca-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6InByb1BheW1lbnRzSHViU2IifQ.eyJoZCI6Im9XSEZldFBZbzM5YUl1cTU2ZEdyb1BDV0ZudlRiREJOdENPRnNsY1VIdUU9Iiwibm9uY2UiOiI0MGRkMGRlZDJkNDk4OTJlNmZkOCIsImFsZyI6IlNIQTI1NiIsImlzcyI6IlNhbnRhbmRlciIsImlhdCI6MTcxMjA1MTUyMSwibmJmIjoxNzEyMDUxNTIxLCJleHAiOjE3NDM1ODc1MjEsImp0aSI6IjIzY2ExNjQyLTYxMjAtNDg4MC1iMDU1LTEwMzZhNjMxNjcxMCJ9.aoJ1hGVPg4ArEb3gdu0VO7rhnL2SpsRXAtZTk-Ou3CWKYZ1u4_Y31MjGQuYabUHJf8GHMT8h_jsHjyxkqcp6tgkZB7cTYgb9nScwSGYQ0jGCul_-v7YUH6zByt7HBfb2XA3XhzcxOLLCkajAQErWCgvHytW0c5x6lQNFSBfrSdCNmuE3cAnu5sabYRtgFeX_L59JbOkLB5raGltiYT627G1M1RF_Lfjc0dvc4szXlKDhIwYFm-6Z5-pazsDaK03zZ27pnrUo1O7pWhPRJz5l02clipE_e-JktOFcpnESPMifZaDeu8P54gGP0-zEqJFJCuGaXahRc-HYhEAxSnBnmQ
Content-Length: 798

{
    "fitoFIPmtRvsl": {
        "grpHdr": {
            "msgId": "12345324543",
            "creDtTm": "2019-05-16T16:31:49-04:00",
            "nbOfTxs": 1,
            "sttlmInf": {
                "sttlmMtd": "CLRG"
            }
        },
        "txInf": [
            {
                "rvslId": "12345324543",
                "rvsdIntrBkSttlmAmt": {
                    "value": 0.01,
                    "ccy": "GBP"
                },
                "rvslRsnInf": [
                    {
                        "addtlInf": [
                            "My own inbound reference"
                        ]
                    }
                ]
            }
        ]
    }
}

Response

If the request is valid, you receive an HTTP 201 Created response, which means that the payment refund request was successfully submitted. In addition, the response body returns the data JSON object, which contains payment refund details. 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 pacs.007 .

Table: Refund the payment - Relevant response body elements.

Extract the value of the paymentsHubId key, as you'll need it in the next section.

Example response body:

{
  "data": {
    "paymentsHubId": "b3141861-b9e7-3906-90a6-ef384f232f82",
    "paymentId": "1587641040",
    "status": "PENDING",
    "creationDateTime": "2020-04-23T11:24:01"
  }
}

3. Retrieve the refund payment status

This section describes how, after receiving a notification, you can retrieve the payment refund status via a pacs.002 HTTP request to the Payments Hub API. To send this request, you need to provide the Payments Hub ID provided in the notification, 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.apis.santander.com/payments/pacs002/v10/{paymentsHubId}

Headers

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

Table: Retrieve the refund payment status - Required request headers.

Parameters

The request must contain the path parameter shown in the following table.

Table: Retrieve the refund payment status - Request parameter.

Request example

The following example illustrates the request using raw HTTP code:

GET /payments/pacs002/v10/YOUR_PAYMENTS_HUB_ID HTTP/1.1
Host: sandbox.apis.santander.com
Authorization: Bearer YOUR_ACCESS_TOKEN
X-Santander-Client-Id: YOUR_CLIENT_ID

Response

If the request is valid, you receive an HTTP 200 OK response, which means that the refund payment status was 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 fIToFIPmtStsRpt JSON object, which contains a pacs.002 ISO message.

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 pacs.002 .

Table: Retrieve the refund payment status - Relevant response body elements.

Extract the value of the txInfAndSts.txSts key and the txInfAndSts.orgnlTxRef.intrBkSttlmAmt data structure to see the refund payment status and amount.

Example response body:

{
  "fitoFIPmtStsRpt": {
    "grpHdr": {
      "msgId": "1587641040",
      "creDtTm": "2019-05-14T11:30:19.123"
    },
    "txInfAndSts": [
      {
        "orgnlGrpInf": {
          "orgnlMsgId": "1587641040",
          "orgnlMsgNmId": "pacs.007.001.08"
        },
        "orgnlEndToEndId": "e2eId-1587641040",
        "orgnlTxId": "111111",
        "txSts": "ACCC",
        "stsRsnInf": [
          {
            "rsn": {
              "cd": "G000"
            },
            "addtlInf": [
              null,
              null,
              null,
              "tppId_0"
            ]
          }
        ],
        "orgnlTxRef": {
          "intrBkSttlmAmt": {
            "ccy": "GBP"
            "value": 0.50,
          },
          "sttlmInf": {
            "sttlmMtd": "CLRG"
          },
          "pmtTpInf": {
            "svcLvl": {
              "prtry": "FP"
            },
          },
          "rmtInf": {
            "ustrd": [
              "DebtorReference",
              "IGNORED"
            ],
            "strd": [
              {
                "cdtrRefInf": {
                  "ref": "PH PRE-UAT TESTING GB"
                },
                "addtlRmtInf": [
                  "FPID"
                ]
              }
            ]
          },
          "dbtr": {
            "pty": {
              "nm": "Steve",
              "pstlAdr": {
                "adrLine": [
                  "Somewhere in MK"
                ]
              }
            }
          },
          "dbtrAcct": {
            "id": {
              "othr": {
                "id": "GB67ABBY09012803352529"
              }
            },
            "nm": "Mr Steve"
          },
          "dbtrAgt": {
            "finInstnId": {
              "clrSysMmbId": {
                "mmbId": "123456"
              }
            }
          },
          "cdtrAgt": {
            "finInstnId": {
              "clrSysMmbId": {
                "mmbId": "200000"
              }
            }
          },
          "cdtr": {
            "pty": {
              "nm": "Mr Creditor",
              "pstlAdr": {
                "adrLine": [
                  "GB payments hub testing"
                ]
              }
            }
          },
          "cdtrAcct": {
            "id": {
              "othr": {
                "id": "GB69HBUK40333313032018"
              }
            },
          }
        }
      }
    ]
  }
}

ISO20022 API Specification

Check API Documentation

Click below to embark on your journey to new possibilities.

API Docs

Download Swagger File

Take the next step towards enhanced efficiency and performance.

Swagger file