Get Started with Yapily VRP

A tutorial for Yapily VRP.

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

Here is the big-picture view of the flow:

1. Select a supported institution, either:
   • See our Institution Coverage or
   • Search for the institutions that support the VRP feature via GET /institutions
2. Specify VRP Mandate details and let the user authorise it
3. Confirm that the payer has sufficient funds
   • This is an optional but recommended step which serves to improve error handling and increase payment success rates
4. Carry-out payments on the authorised Consent and VRP Mandate

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

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.

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

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

Get Notified once a Payment is Processed

It is possible to receive a Webhook 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:

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

Get Consent Details

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

See API specification

Get VRP Payment Details

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

See API specification

Further Reading

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

• Payment Consents
• Webhooks