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

# Get Started

> Getting started guide for Yapily Variable Recurring Payments. Learn how to create VRP consents, configure mandates, and initiate recurring payments programmatically.

A tutorial for Yapily VRP.

<Note>
  Commercial VRP (cVRP) is available as a Private Beta version. Please contact your Customer Success Manager if you would like to access it.
</Note>

<Info>
  All requests made to the Yapily API require [basic authentication](/getting-started/integration-setup/api-authentication).
</Info>

Select a VRP type to get started:

<Tabs>
  <Tab title="Sweeping VRP">
    This section will get you familiarised with Yapily's **Sweeping VRP** flow.

    <Steps>
      <Step title="Select a supported institution">
        Select a supported institution, either:

        * See our [Institution Coverage](/payments/vrps/coverage) or
        * Search for the institutions that support the sweeping VRP feature via `GET /institutions`
      </Step>

      <Step title="Authorise">
        The first and most important step of the VRP flow is authorisation, but Yapily makes it very straightforward:

        1. Call `POST /variable-recurring-payments/sweeping/consents`
           * Specify the correct payee and payer details
           * Specify the appropriate limits (e.g. time period when the consent is valid, maximum amounts per payment and per time period)
           * See the [endpoint's API specification](/api-reference/variable-recurring-payments/create-sweeping-vrp-authorisation) for details
        2. Retrieve the Authorisation URL from the response and redirect the user to it
           * There, the user will have to authorise the payment with their bank
           * For testing purposes, you may use Natwest Sandbox credentials
        3. If the user successfully authorised, then you should retrieve the Consent Token for later
           * For more details on this authorisation flow, see Redirect Payment flow

        <Warning>
          Yapily Connect customers must also provide payer details in the `complianceData` object to meet [compliance requirements](/payments/vrps/additional-information#compliance-requirements).
        </Warning>
      </Step>

      <Step title="Confirm availability of funds">
        Prior to executing a payment, it's best practice to ensure the availability of funds from the payer's side. This will guard you against potentially vague error response messages during the payment execution call later.

        This is an optional but recommended step which serves to improve error handling and increase payment success rates.

        1. Call `POST /variable-recurring-payments/funds-confirmation`
           * Specify the expected payment amount
        2. Verify from the response whether the payer has sufficient funds to execute the payment
           * See the [endpoint's API specification](/api-reference/variable-recurring-payments/confirm-funds-for-vrp-payment) for details
      </Step>

      <Step title="Execute a payment">
        1. Call `POST /variable-recurring-payments/payments`
           * Specify the wanted payment amount (which should be within the limits specified at authorisation, otherwise an error response will be returned)
           * See the [endpoint's API specification](/api-reference/variable-recurring-payments/create-vrp-payment) for details

        You can now execute any number of payments subject to the established limits at authorisation, which is the core strength of VRP. Note that it is recommended to confirm funds availability before each payment.
      </Step>

      <Step title="Get notified once a payment is processed">
        It is possible to receive a [Webhook](/tools-and-services/webhooks/introduction) notification when a payment reaches a terminal status.

        **Register a Webhook**

        To receive a Webhook notification, it is necessary to register a Webhook first.

        Currently, there are two event categories for VRP payments:

        * `sweeping_vrp.payment_status.completed.v1` for successfully completed payments
        * `sweeping_vrp.payment_status.failed.v1` for failed payments

        **Receive a Webhook Notification**

        After a Webhook is registered and a payment is executed, the following notification will be sent whenever a VRP payment reaches a terminal status:

        ```json theme={null}
        {
          "id": "4ac33edc-352e-ed04-dcd3-2cb58c01b2c0",
          "applicationId": "b54d2403-3b41-fd74-4b53-2d0c9609d275",
          "type": "sweeping_vrp.payment_status.completed.v1",
          "event": {
            "paymentId": "1b8b3528-b0f5-bc84-870b-377b966448ef",
            "statusDetails": {
              "status": "COMPLETED",
              "isoStatus": {
                "code": "ACSC",
                "name": "AcceptedSettlementCompleted"
              },
              "statusUpdateDate": "2025-06-06T15:30:45.000Z"
            }
          },
          "metadata": {
            "tracingId": "6cf5ef06-9f96-4f24-8bab-32ab09128010",
            "user": {
              "key": "value"
            }
          }
        }
        ```

        | Property                             | Value Type | Description                                                              |
        | ------------------------------------ | ---------- | ------------------------------------------------------------------------ |
        | id                                   | String     | The Webhook ID used for delivering the event                             |
        | applicationId                        | String     | The Application ID that registered this webhook                          |
        | type                                 | String     | The triggered event's type                                               |
        | event.paymentId                      | String     | The VRP Payment ID the event was triggered for                           |
        | event.statusDetails.status           | String     | The VRP Payment's terminal status                                        |
        | event.statusDetails.isoStatus.code   | String     | The VRP Payment's ISO 20022 status code (as provided by the institution) |
        | event.statusDetails.isoStatus.name   | String     | The VRP Payment's ISO 20022 status name (as provided by the institution) |
        | event.statusDetails.statusUpdateDate | Date-Time  | The time when the VRP Payment's status was last updated                  |
        | metadata.tracingId                   | String     | The Tracing ID of the event                                              |
        | metadata.user                        | Object     | **Optional.** The metadata provided at Webhook registration              |

        <Info>
          More details on status format and meaning can be found on the [Payment Status](/payments/payment-resources/payment-status) page.
        </Info>
      </Step>
    </Steps>

    ### Get Consent Details

    Call `GET /variable-recurring-payments/sweeping/consents/{consentId}` to retrieve details about a particular VRP payment Consent.

    See [API specification](/api-reference/variable-recurring-payments/get-sweeping-vrp-consent-details)
  </Tab>

  <Tab title="Commercial VRP">
    This section will get you familiarised with Yapily's **Commercial VRP (cVRP)** flow.

    <Steps>
      <Step title="Select a supported institution">
        Select a supported institution, either:

        * See our [Institution Coverage](/payments/vrps/coverage) or
        * Search for the institutions that support the commercial VRP feature via `GET /institutions`

        <Info>
          cVRP institution coverage differs from Sweeping VRP. Not all banks that support Sweeping VRP support cVRP. Check the cVRP coverage page before building.
        </Info>
      </Step>

      <Step title="Set up a mandate">
        cVRP consent and mandate setup is delivered via **Yapily Hosted Pages**, ensuring all regulatory disclosure requirements under the UKPI scheme are met automatically.

        1. Call `POST /hosted/vrp-requests/commercial`
           * Specify the correct payee (biller) and payer details
           * Specify the appropriate limits (e.g. time period when the consent is valid, maximum individual payment amount, and per time period)
           * Provide `UltimatePayee` if the recipient of funds differs from the named Payee
           * Provide payer details in the `complianceData` object, including all required Transaction Risk Indicators (e.g. PaymentContextCode, PaymentPurposeCode). See [compliance requirements](/payments/vrps/additional-information#compliance-requirements).
           * See the [endpoint's API specification](/api-reference/hosted-vrp-pages/create-hosted-commercial-vrp-request) for details
        2. Retrieve the Hosted Page URL from the response and redirect the payer to it
           * Yapily will display all required pre-mandate disclosures to the payer on your behalf
           * The payer will authorise the mandate with their bank using Strong Customer Authentication (SCA)
        3. If the payer successfully authorises, retrieve the Consent Token for later use
      </Step>

      <Step title="Confirm availability of funds">
        Prior to executing a payment, it's best practice to ensure the availability of funds from the payer's side. This will guard you against potentially vague error response messages during the payment execution call later.

        This is an optional but recommended step which serves to improve error handling and increase payment success rates.

        1. Call `POST /variable-recurring-payments/funds-confirmation`
           * Specify the expected payment amount
        2. Verify from the response whether the payer has sufficient funds to execute the payment
           * See the [endpoint's API specification](/api-reference/variable-recurring-payments/confirm-funds-for-vrp-payment) for details
      </Step>

      <Step title="Execute a payment">
        1. Call `POST /variable-recurring-payments/payments`
           * Specify the payment amount (which must be within the mandate limits established at authorisation)
           * Provide `PSUInteractionType` to indicate whether the payer is present or the payment is biller-initiated
           * See the [endpoint's API specification](/api-reference/variable-recurring-payments/create-vrp-payment) for details

        You can now execute any number of payments subject to the mandate limits established at authorisation. It is recommended to confirm funds availability before each payment.

        <Info>
          Payments must only be initiated for approved In-Scope Use Cases under the UKPI MLA. See [Additional Information](/payments/vrps/additional-information#scope) for the full list of supported use cases.
        </Info>
      </Step>

      <Step title="Get notified once a payment is processed">
        It is possible to receive a [Webhook](/tools-and-services/webhooks/introduction) notification when a payment reaches a terminal status.

        **Register a Webhook**

        To receive a Webhook notification, it is necessary to register a Webhook first.

        Currently, there are two event categories for cVRP payments:

        * `commercial_vrp.payment_status.completed.v1` for successfully completed payments
        * `commercial_vrp.payment_status.failed.v1` for failed payments

        **Receive a Webhook Notification**

        After a Webhook is registered and a payment is executed, the following notification will be sent whenever a Commercial VRP payment reaches a terminal status:

        ```json theme={null}
        {
          "id": "4ac33edc-352e-ed04-dcd3-2cb58c01b2c0",
          "applicationId": "b54d2403-3b41-fd74-4b53-2d0c9609d275",
          "type": "commercial_vrp.payment_status.completed.v1",
          "event": {
            "paymentId": "1b8b3528-b0f5-bc84-870b-377b966448ef",
            "statusDetails": {
              "status": "COMPLETED",
              "isoStatus": {
                "code": "ACSC",
                "name": "AcceptedSettlementCompleted"
              },
              "statusUpdateDate": "2025-06-06T15:30:45.000Z"
            }
          },
          "metadata": {
            "tracingId": "6cf5ef06-9f96-4f24-8bab-32ab09128010",
            "user": {
              "key": "value"
            }
          }
        }
        ```

        | Property                             | Value Type | Description                                                              |
        | ------------------------------------ | ---------- | ------------------------------------------------------------------------ |
        | id                                   | String     | The Webhook ID used for delivering the event                             |
        | applicationId                        | String     | The Application ID that registered this webhook                          |
        | type                                 | String     | The triggered event's type                                               |
        | event.paymentId                      | String     | The VRP Payment ID the event was triggered for                           |
        | event.statusDetails.status           | String     | The VRP Payment's terminal status                                        |
        | event.statusDetails.isoStatus.code   | String     | The VRP Payment's ISO 20022 status code (as provided by the institution) |
        | event.statusDetails.isoStatus.name   | String     | The VRP Payment's ISO 20022 status name (as provided by the institution) |
        | event.statusDetails.statusUpdateDate | Date-Time  | The time when the VRP Payment's status was last updated                  |
        | metadata.tracingId                   | String     | The Tracing ID of the event                                              |
        | metadata.user                        | Object     | **Optional.** The metadata provided at Webhook registration              |

        <Info>
          More details on status format and meaning can be found on the [Payment Status](/payments/payment-resources/payment-status) page.
        </Info>
      </Step>
    </Steps>

    ### Get Mandate Details

    Call `GET /variable-recurring-payments/commercial/consents/{consentId}` to retrieve details about a particular cVRP mandate.

    See [API specification](/api-reference/variable-recurring-payments/get-commercial-vrp-consent-details)

    ### Cancel a Mandate

    As part of cVRP you will need to provide your payers the active consents visibility. Payers must have ability to cancel a cVRP long lived consent at any time, either through their bank or through the merchant's interface.

    Call `DELETE /consents/{consentId}` to revoke a chosen consent.

    See [API specification](/api-reference/consents/delete-consent)

    <Info>
      Mandates that have not been used for 13 consecutive months must be cancelled. Yapily will notify you when a mandate approaches this threshold.
    </Info>
  </Tab>
</Tabs>

## Get VRP Payment Details

Call `GET /variable-recurring-payments/payments/{paymentId}/details` to retrieve details about a particular VRP payment.

See [API specification](/api-reference/variable-recurring-payments/get-vrp-payment-details)

<Info>
  It is highly advised to use the Webhook notifications described above to receive updates on VRP payment status changes instead of polling on this endpoint, because there are rate limits imposed on all endpoints.
</Info>

## Further Reading

For your next steps, you may want to review the following documentation pages:

* [cVRP Institution Coverage](/payments/vrps/coverage#commercial-vrp)
* [Mandate Details](/payments/vrps/mandate-details)
* [Additional Information](/payments/vrps/additional-information)
* [Webhooks](/tools-and-services/webhooks/introduction)