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

This page should get you familiarised with Yapily's **Sweeping VRP** flow.

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

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

    Now 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)

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

* [Payment Consents](/payments/payment-resources/payment-consents)
* [Webhooks](/tools-and-services/webhooks/introduction)