Skip to main content

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.

A tutorial for Yapily VRP.
Commercial VRP (cVRP) is available as a Private Beta version. Please contact your Customer Success Manager if you would like to access it.
All requests made to the Yapily API require basic authentication.
Select a VRP type to get started:
This section will get you familiarised with Yapily’s Sweeping VRP flow.
1

Select a supported institution

Select a supported institution, either:
  • See our Institution Coverage or
  • Search for the institutions that support the sweeping 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
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 WebhookTo 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 NotificationAfter 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: