Reverse Payments

Introduction

Reverse Payments is a feature from the Open Banking API Specification V3.1.5. Reverse Payments allows a TPP to request that the refund account information be included as part of the payments response. By returning the refund account information (i.e. name, SORT_CODE and ACCOUNT_NUMBER), the TPP is then able to initiate a further payment to refund the original payment, if required. This feature is available if the Institution includes the following feature:

  • READ_DOMESTIC_SINGLE_REFUND

In order to retrieve the refund account information, a TPP must specify readRefundAccount=true when executing a Create Payment Authorisation.

Coverage

As of 25th January 2021, this feature is supported for payments with the following payment types:

  • DOMESTIC_PAYMENT
  • DOMESTIC_SCHEDULED_PAYMENT
  • DOMESTIC_PERIODIC_PAYMENT

And for the following banks:

  • NatWest
  • RBS
  • Ulster Bank NI
  • HSBC UK
  • Nationwide
  • Danske
  • Lloyds
  • Bank of Scotland
  • Halifax
  • Barclays (Single Domestic Payment only)

We will continue to upgrade our support of reverse payments as more institutions release this feature.

Usage

Any Institution that supports reverse payments will first have the feature READ_DOMESTIC_SINGLE_REFUND when executing Get Institution. If an Institution supports reverse payments, you may request refund account information by adding an additional parameter, readRefundAccount in Create Payment Authorisation (see the attribute in the paymentRequest object):

Copy
Copied
{
    "applicationUserId": "{{application-user-id}}",
    "institutionId": "{{institution-id}}",
    "callback": "{{callback-url}}",
    "paymentRequest": {
            "type": "DOMESTIC_PAYMENT",
            "readRefundAccount": true,
            "paymentIdempotencyId": "{{paymentIdempotencyId}}",
            "reference": "{{paymentReference}}",
            "contextType": "PERSON_TO_PERSON",
            "amount": {
                "amount": "{{paymentAmount}}",
                "currency": "{{paymentCurrency}}"
            },
            "payee": { ...

The response for the authorisation will confirm that the feature is supported by the Institution and is being actively used for this particular payment Consent (see line 12 within the featureScope property):

Copy
Copied
{
    "meta": {
        "tracingId": "7e36098c464cad866f01c6e08bf8163f"
    },
    "data": {
        "id": "b81ba80d-cc77-4e78-b90e-7060c0c8254a",
        "userUuid": "c3fb97e0-44e2-477b-bfdc-c2534057b5e9",
        "institutionId": "rbs",
        "status": "AWAITING_AUTHORIZATION",
        "createdAt": "2020-10-06T13:27:26.162Z",
        "featureScope": [
            "READ_DOMESTIC_SINGLE_REFUND",
            "CREATE_DOMESTIC_SINGLE_PAYMENT",
            "EXISTING_PAYMENTS_DETAILS",
            "EXISTING_PAYMENT_INITIATION_DETAILS"
        ],
        "authorisationUrl": "https://personal.secure1.rbs.co.uk/as/authorization.oauth2?client_id=jOWO30rrwG9nwOHWirKXLK&response_type=code+id_token&state=77ef1824ebeb4be784569d07d64bdf34&nonce=77ef1824ebeb4be784569d07d64bdf34&scope=openid+payments&redirect_uri=https%3A%2F%2Fauth.yapily.com%2F&request=eyJraWQiOiJPNWp3ZXpxTlNzeVlacHotZHpfVUhEbkJINHciLCJhbGciOiJQUzI1NiJ9.eyJhdWQiOiJodHRwczovL3NlY3VyZTEucmJzLmNvLnVrIiwic2NvcGUiOiJvcGVuaWQgcGF5bWVudHMiLCJpc3MiOiJqT1dPMzBycndHOW53T0hXaXJLWExLIiwiY2xpZW50X2lkIjoiak9XTzMwcnJ3Rzlud09IV2lyS1hMSyIsInJlc3BvbnNlX3R5cGUiOiJjb2RlIGlkX3Rva2VuIiwicmVkaXJlY3RfdXJpIjoiaHR0cHM6Ly9hdXRoLnlhcGlseS5jb20vIiwic3RhdGUiOiI3N2VmMTgyNGViZWI0YmU3ODQ1NjlkMDdkNjRiZGYzNCIsImNsYWltcyI6eyJpZF90b2tlbiI6eyJhY3IiOnsidmFsdWUiOiJ1cm46b3BlbmJhbmtpbmc6cHNkMjpzY2EiLCJlc3NlbnRpYWwiOnRydWV9LCJvcGVuYmFua2luZ19pbnRlbnRfaWQiOnsidmFsdWUiOiIwNmI4NzBlOTg1NWE0ODdiYWY1NDlkNGU5ZjlhYzU1YyIsImVzc2VudGlhbCI6dHJ1ZX19LCJ1c2VyaW5mbyI6eyJvcGVuYmFua2luZ19pbnRlbnRfaWQiOnsidmFsdWUiOiIwNmI4NzBlOTg1NWE0ODdiYWY1NDlkNGU5ZjlhYzU1YyIsImVzc2VudGlhbCI6dHJ1ZX19fSwibm9uY2UiOiI3N2VmMTgyNGViZWI0YmU3ODQ1NjlkMDdkNjRiZGYzNCIsImp0aSI6IjBiMjA5MjA0LWYxZDEtNDExZS1hMTU1LWE0N2FjNjI0MjFhMSIsImlhdCI6MTYwMTk5MDg0NiwiZXhwIjoxNjAxOTkyNjQ2fQ.siGAJf0HNkp3KwGpasPXWc8iRQjfRV42hYGlURdzgm4LI_ReCzon338e49KiufULn92bGkgwbVRoM_8pBmJMRG7qh7wyjpM4R10FCO4vx6lYiI4uwZgJnmAkeyFEPKk_EDxAqF5wCb6kZPg5hbZGWvQnV4ETP04CVQyCEs3yrGQlhQtAs_fEO_KdcKK3wc7qcahY8kDonV0bj-RJUq-WAEOslo00nK7agCyLlOI22J56S9Wrp6R_h5fu-1YGcHYNvq0BwBtK1PwEVxD8mWfQj5zygHV-5V_Y-_IaZL2hrXsL_Ab8shLZdeq4O1jJ04xdd1j6ZFV3YYvFjHNM8Z-q9A",
        "qrCodeUrl": "https://images.yapily.com/image/1724b2f4-9b8e-43e2-9c8a-8a7c06da7915/1601990846?size=0"
    }
}

If the readRefundAccount property is NOT supported for either the payment type or the Institution, the following error message will be returned:

Copy
Copied
{
    "error": {
        "code": 400,
        "tracingId": "64efa35a974eeb5107dcbe968b7f8e9b",
        "status": "BAD_REQUEST",
        "source": "YAPILY",
        "message": "Read Refund Account is not supported for this payment type. We can help you on https://support.yapily.com/"
    },
    "raw": [],
    "monitoring": []
}

Assuming that the authorisation request is successful and the user provides consent for the payment, use the consentToken to execute Create Payment and the response should also include the readRefundAccount object (see below):

Copy
Copied
 ...,
    "createdAt": "2020-08-05T11:02:13.819Z",
    "refundAccount": {
        "name": "BLOGGS JOE",
        "accountIdentifications": [
            {
                "type": "ACCOUNT_NUMBER",
                "identification": "12345678"
            },
            {
                "type": "SORT_CODE",
                "identification": "040065"
            }
        ]
    }
}, ...

readRefundAccount should also be present in the response from Get Payment Details if refund account details were requested.

Note

If the readRefundAccount parameter is omitted from a payment request, it will be set to false by default and no refund account information will be returned even if the Institution supports reverse payments.