Skip to content

Mandates

Mandates establish permission for VRP collections. Merchants must present mandate information in customer-facing flows and store acceptance evidence for regulatory audits.

Creating Mandates

POST /mandates

Required fields:

Field Type Description
customer_id string Identifier assigned by VRP Billing for a verified customer.
maximum_amount string (decimal) Maximum amount per payment in the mandate currency.
currency string ISO 4217 currency code; currently GBP and EUR supported.
frequency string daily, weekly, monthly, or adhoc.

Optional fields:

  • reference (string): Merchant-defined reference displayed on bank statements.
  • metadata (object): See API Reference.

Constraints

  • The customer must have an active payment account on file with a primary bank account.
  • Maximum amount cannot exceed the merchant's approved VRP limit.
  • Duplicate mandates for the same customer and reference are rejected with 409_conflict errors.
  • Mandates expire automatically after 13 months of inactivity.

Sample Request

{
  "customer_id": "cust_1a2b3c",
  "maximum_amount": "250.00",
  "currency": "GBP",
  "frequency": "monthly",
  "reference": "GYM-MANDATE",
  "metadata": {
    "location": "London",
    "channel": "web"
  }
}

Response Body

{
  "id": "mandate_f9d3",
  "status": "active",
  "created_at": "2024-05-02T11:20:18Z",
  "customer_id": "cust_1a2b3c",
  "limits": {
    "maximum_amount": "250.00",
    "currency": "GBP",
    "frequency": "monthly"
  },
  "expires_at": "2025-05-02T11:20:18Z"
}

Mandate Lifecycle

Status Meaning Next actions
pending_authorisation Customer has not completed strong customer authentication. Redirect customer to SCA URL.
active Mandate can be used for payments. Schedule payments respecting the configured limits.
suspended Mandate temporarily paused due to risk controls. Contact support; no payments allowed.
revoked Mandate cancelled by merchant or customer. Cannot be reactivated; create a new mandate.

Retrieving Mandates

Use GET /mandates/{mandate_id} to obtain the latest status and limits. The endpoint also returns remaining_daily_amount and remaining_monthly_amount fields to help merchants enforce frequency limits.

Listing Mandates

GET /mandates?customer_id=cust_1a2b3c&status=active&page_size=25

Results are paginated using cursors described in Pagination. Pass the returned next_cursor back to the cursor query parameter to fetch subsequent pages.

Cancelling Mandates

POST /mandates/{mandate_id}/cancel

  • Cancelling is idempotent; repeated calls return the existing revoked status.
  • Cancellation is immediate and prevents new payments from being created.
  • Any scheduled payments transition to cancelled with error code mandate_revoked.

Mandate Evidence Upload

Merchants subject to enhanced due diligence can upload mandate evidence through POST /mandates/{id}/evidence. Only JPEG or PDF up to 5 MB are accepted. Evidence is encrypted at rest and accessible to compliance teams only.

Monitoring Mandates

Subscribe to the following webhooks to remain informed:

  • mandate.activated
  • mandate.revoked
  • mandate.suspended

Webhooks deliver near real-time updates within 30 seconds of status change.