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.

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

​
Introduction

This tutorial explains how to use Yapily Hosted Pages to set up a UK domestic Commercial VRP (cVRP) mandate. Note: All requests made to the Yapily API require basic authentication.
1

Create a hosted cVRP consent request

Make a request to POST /hosted/vrp/commercial/consents, including the consent request details, institution country code, redirect URL and user ID.You must provide the institutionIdentifiers.institutionCountryCode field. This controls the country of the institution the user can set up the mandate with.In addition, you can optionally provide the ID of a specific institution in institutionIdentifiers.institutionId field to only allow mandate setup with this institution. This skips the bank selection screen in the hosted flow.You can optionally provide userSettings to set the user’s preferred language and location.
Yapily Connect customers must provide payer details in the complianceData object, including Transaction Risk Indicators (TRIs) such as PaymentContextCode, PaymentPurposeCode, and MerchantCategoryCode. If the ultimate recipient of funds differs from the named Creditor, also provide the UltimateCreditor field. See compliance requirements for the full list of required fields.
curl -L -X POST 'https://api.yapily.com/hosted/vrp/commercial/consents' \
-H 'Content-Type: application/json' \
-u 'APPLICATION_KEY:APPLICATION_SECRET' \
-d '{
  "applicationUserId": "john.doe@company.com",
  "institutionIdentifiers": {
    "institutionCountryCode": "GB"
  },
  "userSettings": {
    "language": "en",
    "location": "GB"
  },
  "redirectUrl": "https://tpp-application.com/",
  "mandateDetails": {
    "mandateIdentification": "mandate-001",
    "creditor": {
      "name": "Utility Provider",
      "accountIdentifications": [
        {
          "type": "SORT_CODE",
          "identification": "123456"
        },
        {
          "type": "ACCOUNT_NUMBER",
          "identification": "12345678"
        }
      ]
    },
    "maximumAmount": 500,
    "currency": "GBP",
    "periodicLimits": {
      "alignment": "CALENDAR",
      "frequency": "MONTHLY",
      "maxAmount": 500
    }
  },
  "complianceData": {
    "psuIdentifiers": {
      "name": "John Doe"
    },
    "transactionRiskIndicators": {
      "paymentContextCode": "BillingGoodsAndServicesInAdvance",
      "paymentPurposeCode": "BONU",
      "contractPresentIndicator": true,
      "beneficiaryPrePopulated": true,
      "beneficiaryAccountType": "PersonalCurrentAccount",
      "merchantCategoryCode": "4900"
    }
  },
  "psuInteractionType": "PRESENT"
}'
Store the hostedUrl returned in the response to use in step 2.
2

Redirect the user to the hosted URL

Redirect the end user from your application to the Yapily Hosted Pages URL. This initiates the user journey for the cVRP mandate request.
3

End user completes the cVRP authorization flow

The end user follows the Yapily hosted screens to complete the cVRP mandate setup.A typical journey includes bank selection, a limits confirmation screen, redirection to their chosen bank, mandate authorization confirmation, and redirection back to your application.
Yapily Hosted Pages automatically handles all pre-mandate disclosure requirements under the UKPI scheme on your behalf. No additional implementation is needed to meet regulatory obligations.
See UI screens for more details.The user will be automatically redirected to the redirectUrl specified in the initial consent request in Step 1 once the authorization flow is complete. We recommend you redirect the user back to your application to create a good user experience.The consentRequestId is returned as part of the redirectUrl. You can use this to check the status of the consent in step 4.
4

Retrieve details of the cVRP consent request

On an end user’s completion of the hosted pages flow, you should check the consent status to confirm the mandate has been authorized successfully before proceeding with any further actions.You can retrieve details of the consent request using GET /hosted/vrp/commercial/consents/{consentRequestId}, specifying the consentRequestId in the path.
curl -L -X GET 'https://api.yapily.com/hosted/vrp/commercial/consents/{consentRequestId}' \
-H 'Content-Type: application/json' \
-u 'APPLICATION_KEY:APPLICATION_SECRET'
Store the consentToken from the response — you will need it to execute payments against this mandate.
We recommend using webhooks to receive real-time notifications when your consent is authorized or fails. This provides:
  • Immediate status updates - No polling delay
  • Reduced API calls - Cost savings for both parties
  • Better user experience - Faster feedback to customers
If you cannot use webhooks, you can monitor the consent status by repeatedly calling the GET endpoint above until the status field transitions to AUTHORISED or FAILED.Note: Polling increases API usage and may delay status updates compared to webhooks.

​
Further Reading