API Reference

The VRP Billing API follows REST semantics and uses JSON over HTTPS for all data exchange. All endpoints require authentication with a bearer token obtained from the Merchant Console or via support. See the Integration Guide for setup steps.

Base URLs

Environment	Base URL
Sandbox	https://sandbox.api.vrpbilling.com/v1
Production	https://api.vrpbilling.com/v1

Mandates

Operation	Method & Path	Description
Create Mandate	POST /mandates	Creates a variable recurring payment mandate between a customer and merchant.
Get Mandate	GET /mandates/{mandate_id}	Retrieves mandate status and limits.
List Mandates	GET /mandates	Returns paginated list of mandates filtered by customer or status.
Cancel Mandate	POST /mandates/{mandate_id}/cancel	Immediately revokes the mandate and halts future collections.

Request Example

POST /mandates HTTP/1.1
Host: sandbox.api.vrpbilling.com
Authorization: Bearer <token>
Content-Type: application/json
Idempotency-Key: 1c0b2c9a-4d2f-4872-b335-1c35a33e9c35

{
  "customer_id": "cust_123",
  "maximum_amount": "100.00",
  "currency": "GBP",
  "frequency": "weekly",
  "description": "Gym membership"
}

Response Example

{
  "id": "mandate_456",
  "status": "active",
  "created_at": "2024-01-15T10:03:22Z",
  "limits": {
    "maximum_amount": "100.00",
    "currency": "GBP",
    "frequency": "weekly"
  }
}

Constraints

• Customers must have completed strong customer authentication prior to mandate creation.
• Currency must match the merchant's payout currency.
• Mandate frequency accepts daily, weekly, monthly, or adhoc.
• Subsequent mandate updates are not supported; cancel and recreate to change limits.

Payments

Operation	Method & Path	Description
Create Payment	POST /payments	Initiates a variable recurring payment using an active mandate.
Get Payment	GET /payments/{payment_id}	Retrieves the payment lifecycle including clearing status.
List Payments	GET /payments	Returns paginated list of payments filtered by date or mandate.
Retry Payment	POST /payments/{payment_id}/retry	Re-attempts failed payments while mandate remains active.

Payment Constraints

• Payments may not exceed the maximum_amount defined on the mandate.
• Only one open payment per mandate is allowed at a time.
• Payments are retriable up to 3 times within 7 days of the original attempt.

Payment Example

POST /payments HTTP/1.1
Authorization: Bearer <token>
Content-Type: application/json
Idempotency-Key: 4b7f941e-32d7-4d9d-94b7-204573a6090a

{
  "mandate_id": "mandate_456",
  "amount": "42.50",
  "currency": "GBP",
  "metadata": {
    "invoice": "INV-10045"
  }
}

Refunds

Operation	Method & Path	Description
Create Refund	POST /payments/{payment_id}/refunds	Issues a full or partial refund on a settled payment.
Get Refund	GET /refunds/{refund_id}	Returns refund status and settlement timeline.
List Refunds	GET /refunds	Lists refunds filtered by payment or creation date.

Refund Constraints

• Partial refunds must be at least 1.00 in the payment currency.
• Refunds are only available once the original payment has settled.
• Total refunded amount cannot exceed the original payment amount.

Metadata

All top-level resources (mandates, payments, refunds) allow an optional metadata object with up to 20 keys. Keys are strings limited to 40 characters and values may be strings or numbers up to 200 characters.

Expansions

Use the expand query parameter to include nested resources in responses. Multiple fields can be requested comma-separated, for example:

GET /payments/{id}?expand=mandate,refunds

Expanded resources follow the same schema as their standalone endpoints.