> ## 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 tutorial using Yapily Hosted Pages
> Tutorial for setting up a Commercial VRP (cVRP) mandate using Yapily Hosted Pages. Generate a consent session URL and guide users through the complete VRP authorization journey.
Commercial VRP (cVRP) is available as a [Private Beta version](/getting-started/overview#private-beta). 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](/getting-started/integration-setup/api-authentication).
***
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](/payments/vrps/additional-information#compliance-requirements) for the full list of required fields.
```bash Request theme={null}
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"
}'
```
```json Response theme={null}
{
"meta": {
"tracingId": "2dbfd85b4f2940c6a206e96dd90e52d0"
},
"data": {
"consentRequestId": "eb39f8ae-aeff-4ffa-a23d-d4a5b3eff406",
"userId": "3ddf5dd0-aa48-4d0f-baa7-fa057e9e911d",
"applicationUserId": "john.doe@company.com",
"applicationId": "64949de6-6510-4d70-9500-d4aa094c506c",
"institutionIdentifiers": {
"institutionId": "modelo-sandbox",
"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
}
},
"hostedUrl": "https://prototypes.yapily.com/auth-link1.html",
"authToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
"createdAt": "2021-06-10T11:26:54.887Z",
"authorisationExpiresAt": "2021-06-10T11:36:54.887Z",
"status": "ACTIVE"
}
}
```
Store the `hostedUrl` returned in the response to use in step 2.
Redirect the end user from your application to the Yapily Hosted Pages URL. This initiates the user journey for the cVRP mandate request.
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](/tools-and-services/hosted-pages/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.
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.
```bash Request theme={null}
curl -L -X GET 'https://api.yapily.com/hosted/vrp/commercial/consents/{consentRequestId}' \
-H 'Content-Type: application/json' \
-u 'APPLICATION_KEY:APPLICATION_SECRET'
```
```json Response theme={null}
{
"meta": {
"tracingId": "2dbfd85b4f2940c6a206e96dd90e52d0"
},
"data": {
"consentRequestId": "eb39f8ae-aeff-4ffa-a23d-d4a5b3eff406",
"userId": "3ddf5dd0-aa48-4d0f-baa7-fa057e9e911d",
"applicationUserId": "john.doe@company.com",
"applicationId": "64949de6-6510-4d70-9500-d4aa094c506c",
"institutionIdentifiers": {
"institutionId": "modelo-sandbox",
"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
}
},
"createdAt": "2021-06-10T11:26:54.887Z",
"authorisationExpiresAt": "2021-06-10T11:36:54.887Z",
"status": "AUTHORISED",
"consentToken": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}
}
```
Store the `consentToken` from the response — you will need it to execute payments against this mandate.
### Monitoring Consent Status
We recommend using [webhooks](/tools-and-services/hosted-pages/payment-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
* [VRP Get Started](/payments/vrps/get-started) - Full cVRP flow including payment execution
* [VRP Mandate Details](/payments/vrps/mandate-details) - Mandate parameter reference
* [VRP Institution Coverage](/payments/vrps/coverage) - Supported institutions for cVRP
* [VRP Additional Information](/payments/vrps/additional-information) - Compliance requirements and use case scope
* [Webhooks](/tools-and-services/webhooks/introduction) - Real-time payment notifications