Reverse Payments

Yapily's knowledge article about Reverse Payments

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, sortCode and accountNumber), the TPP is then able to initiate a further payment to refund the original payment, if required.

In order to retrieve the refund account information, a TPP must specify readRefundAccount=true when executing a payment authorisation request on any of the POST Create Payment Authorisation Request endpoint.

Coverage

As of 24th November 2020, this feature is currently only 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

Barclays, Nationwide, and Dankse will be released soon and it is expected many UK banks with follow suit.

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 to the POST Create Payment Authorisation Request (line 7):

{
    "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):

{
    "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:

{
    "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 POST Create Payment Request and the response should also include the readRefundAccount object (lines 3-15 below):

     ...,
    "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 Get Payment Details if refund account details were requested.

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.