VRP billing merchant guide

Welcome! This guide walks you through everything a merchant needs to start using Variable Recurring Payments (VRP) with the VRP Billing starter project. You will connect your GoCardless account, collect customer consent, take the first payment, and keep an eye on ongoing activity—all without diving into code or developer tools.

Quickstart

Work through the setup steps below to configure webhooks, collect consent, and take payments.
Explore the interactive API reference to try requests against your environment.
Review the raw API schema if you need the underlying OpenAPI definition for tooling or validation.

End-to-end VRP flow

Visualise how consent collection, customer redirection, webhook updates, and reconciliation hang together in a standard VRP Billing journey.

sequenceDiagram
    autonumber
    participant Merchant
    participant Customer
    participant GoCardless
    participant "VRP Billing" as VRP

    Merchant->>VRP: Create consent
    VRP->>GoCardless: Create billing request
    GoCardless->>Customer: Prompt to authorise consent
    Customer->>GoCardless: Approve consent
    GoCardless-->>Customer: Redirect to merchant
    GoCardless-->>VRP: Webhook (billing_request.consent_granted)
    Merchant->>VRP: Create payment using mandate
    VRP->>GoCardless: Submit payment
    GoCardless-->>VRP: Webhook (payment updated)
    VRP-->>Merchant: Reconciliation data via console/API

Core data model

The primary resources tie merchants, mandates, and payments together while keeping a record of every webhook notification.

erDiagram
    MERCHANT ||--o{ MANDATE : "owns"
    MERCHANT ||--o{ PAYMENT : "initiates"
    MANDATE ||--o{ PAYMENT : "authorises"
    MERCHANT ||--o{ WEBHOOKEVENT : "receives"
    MANDATE ||--o{ WEBHOOKEVENT : "context"
    PAYMENT ||--o{ WEBHOOKEVENT : "status change"

Before you begin

Make sure you have the following in place before starting the setup:

Requirement	Details
Merchant console access	Log in to the VRP merchant console so you can monitor activity and manage settings.
GoCardless account	Use sandbox or live credentials with permissions to create billing requests, payments, and webhooks.
API key	Request a merchant API key from your VRP Billing contact or support team. You will add it to every request as the `X-Api-Key` header.
Redirect URL	Confirm the URL your customers return to after approving a VRP consent.

Need technical help? Share this page with your developer and point them at the developer integration guide for implementation details.

Step 1: Point GoCardless webhooks to VRP Billing

Webhooks let the VRP Billing service know when GoCardless updates a consent or payment. Configure them once and leave them running in the background.

In the GoCardless dashboard, create or edit a webhook endpoint.
Set the URL to the webhook path for your merchant. Use https://api.vrpbilling.com/v1/vrp/webhook/<token>/ when sending live traffic with your production GoCardless credentials, or https://sandbox.api.vrpbilling.com/v1/vrp/webhook/<token>/ when testing with sandbox credentials.
Use the shared secret shown in the VRP merchant console. Keep it safe—this secret proves the webhook really comes from GoCardless.
Save your changes. From now on, GoCardless sends every VRP event to VRP Billing.

When testing, you can resend recent events from the GoCardless dashboard to confirm everything is working. VRP Billing acknowledges each valid webhook with 204 No Content, so you will not see a response body.

Headers to include when GoCardless calls your webhook

Header	Purpose
`Webhook-Signature` (or `GoCardless-Signature`)	HMAC signature used by VRP Billing to verify the payload before processing it.

For background reading, see webhook signature verification.

Customers must approve a VRP consent before you can collect payments. The VRP Billing service creates a billing request and provides an authorisation link you can share with the customer.

Send a POST request to the VRP Billing API (https://api.vrpbilling.com/v1/vrp/mandate/ for production with live credentials, or https://sandbox.api.vrpbilling.com/v1/vrp/mandate/ for sandbox testing).
Include your merchant API key (issued to you out of band) in the header table below.
Provide the consent details in the JSON body.
Redirect or email the customer using the authorisation_url returned in the response.

Headers for consent creation

Header	Example	Notes
`X-Api-Key`	`prefix.secret`	Required on every call you make to VRP Billing.
`Content-Type`	`application/json`	Needed when sending JSON bodies.

Request fields

Field	Required?	Description
`redirect_uri`	Yes	Where GoCardless sends the customer after they approve the consent.
`description`	Optional	Shown to the customer during approval (max 255 characters).
`constraints`	Optional	Spending limits such as amount caps or schedules.

Response

{
  "billing_request_id": "BR123",
  "authorisation_url": "https://pay-sandbox.gocardless.com/flow/BO-123"
}

Share the authorisation link with your customer. Once they approve it, the mandate is ready for payments. Learn more in the GoCardless billing request flow overview.

After the customer completes the consent flow, you can create payments against the mandate whenever needed.

Send a POST request to the VRP Billing API (https://api.vrpbilling.com/v1/vrp/payment/ for production with live credentials, or https://sandbox.api.vrpbilling.com/v1/vrp/payment/ for sandbox testing) with the API key provided by support in the header.
Include the mandate reference and payment details in the JSON body.
Confirm the response contains a payment ID—keep it for reconciliation or customer support.

Payment request fields

Field	Required?	Description
`gc_mandate_id` or `mandate_id`	One required	The VRP mandate returned after the customer approved the consent.
`amount_minor`	Yes	Amount to collect in pence (GBP minor units only).
`currency`	Optional	ISO currency code. GBP only—omit to default to GBP or set explicitly to `GBP`.
`metadata`	Optional	Object of string key/value pairs forwarded to GoCardless (keys ≤ 50 chars, values ≤ 500).

Currency reminder: GBP only; amount_minor is pence; omitting currency defaults to GBP but if present it must be GBP.

Metadata tips: Send strings where possible. Boolean and numeric values are automatically converted to strings before the payment is created.

The response includes the GoCardless payment ID and the initial status. Payments move through statuses such as pending_submission, confirmed, and paid_out. Check the GoCardless payments guide for full details.

Step 4: Manage activity with the console API

The VRP console UI uses an authenticated API endpoint so you can reproduce the same manual tasks in your own tooling. Send a POST request to the appropriate host (https://api.vrpbilling.com/v1/vrp/console/api/ in production with live credentials, or https://sandbox.api.vrpbilling.com/v1/vrp/console/api/ in sandbox with test credentials) with the action you want to perform and the corresponding payload, authenticating with the API key provided by VRP Billing support.

Supported console actions

Action	When to use it
`create_consent`	Start a new VRP billing request using your configured GoCardless creditor.
`create_flow`	Generate a hosted authorisation URL for a billing request.
`mandate_for_br`	Look up the mandate created after a billing request is authorised.
`preflight`	Run the sandbox preflight check to confirm a payment would not breach limits.
`create_payment`	Collect a payment against a resolved mandate.
`check_payment`	Refresh payment status and sync it into VRP Billing.
`window_report`	Summarise the last 30 days of payments taken on a mandate.
`cancel_mandate`	Cancel an active mandate through GoCardless.
`retry_payment`	Retry a GoCardless payment when the provider allows another collection attempt.
`reinstate_mandate`	Reinstate a cancelled mandate while the customer's bank still honours the consent.

Need to review webhook events instead? Open the Activity page in the merchant console to browse the event log without making API calls.

Helpful tips

Keep your API key secure. Contact VRP Billing support for a new key if you suspect it has been exposed.
Use the GoCardless sandbox to rehearse the full flow before switching to live payments.
When testing payments, trigger webhook redeliveries from the GoCardless dashboard to confirm VRP Billing is receiving updates.

Advanced options (optional)

The VRP Billing project includes automation, error handling, and developer tooling that are not covered in this merchant guide. Developers can review:

Integration guide for API payloads, example code, and troubleshooting tips.
Source code in the /api directory for Django view names and advanced customisation.

With these steps complete, you are ready to offer VRP to your customers and manage payments with confidence.