Skip to main content
A tutorial for Yapily VRP. This page should get you familiarised with Yapily’s Sweeping VRP flow.
All requests made to the Yapily API require basic authentication.
1

Select a supported institution

Select a supported institution, either:
  • See our Institution Coverage or
  • Search for the institutions that support the VRP feature via GET /institutions
2

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
Yapily Connect customers must also provide payer details in the complianceData object to meet compliance requirements.
3

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
4

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

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"
    }
  }
}
PropertyValue TypeDescription
idStringThe Webhook ID used for delivering the event
applicationIdStringThe Application ID that registered this webhook
typeStringThe triggered event’s type
event.paymentIdStringThe VRP Payment ID the event was triggered for
event.statusDetails.statusStringThe VRP Payment’s terminal status
event.statusDetails.isoStatus.codeStringThe VRP Payment’s ISO 20022 status code (as provided by the institution)
event.statusDetails.isoStatus.nameStringThe VRP Payment’s ISO 20022 status name (as provided by the institution)
event.statusDetails.statusUpdateDateDate-TimeThe time when the VRP Payment’s status was last updated
metadata.tracingIdStringThe Tracing ID of the event
metadata.userObjectOptional. The metadata provided at Webhook registration
More details on status format and meaning can be found on the Payment Status page.
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
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.

​
Further Reading

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