> ## Documentation Index
> Fetch the complete documentation index at: https://docs.yapily.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Reverse Payments

> Initiate reverse payments (refunds) using the Yapily API. Understand eligibility criteria, required parameters, and institution support for payment reversal operations.

## 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](/api-reference/authorisations/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](/api-reference/institutions/get-institution). If an `Institution` supports reverse payments, you may request refund account information by adding an additional parameter, `readRefundAccount` in [Create Payment Authorisation](/api-reference/authorisations/create-payment-authorisation) (see the attribute in the `paymentRequest` object):

```json theme={null}
{
    "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):

```json theme={null}
{
    "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:

```json theme={null}
{
    "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](/api-reference/payments/create-payment) and the response should also include the `readRefundAccount` object (see below):

```json theme={null}
 ...,
    "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](/api-reference/payments/get-payment-details) if refund account details were requested.

<Info>
  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.
</Info>