Billing integration

Connect your billing system.

Create, suspend, restore and cancel VPN services from your billing system.

Before you start

Create the billing API token inside your hosted dashboard under Settings → Billing. Treat it like a password and keep it on your server; never include it in browser or mobile application code.

Authorization: Bearer <billing-api-token>
Accept: application/json
Content-Type: application/json

Your dashboard shows its own API address. Replace vpn.yourdomain.com in the examples with that hostname.

Create or update an account

Use identifiers from your billing system. Keep the same identifiers and idempotency key when retrying the same request.

curl -X POST "https://vpn.yourdomain.com/api/v1/integration/accounts" \
  -H "Authorization: Bearer <billing-api-token>" \
  -H "Idempotency-Key: order-8801-create" \
  -H "Content-Type: application/json" \
  --data '{
    "external_client_id": "customer-1042",
    "external_service_id": "service-8801",
    "email": "customer@example.com",
    "name": "Example Customer",
    "profile_count": 5,
    "plan_type": "shared",
    "product_name": "VPN access"
  }'

Integration API

VPN Dashboard Integration API

Authenticated billing integration API for customer, account, server and app-token lifecycle automation.

v1.3.26 OpenAPI 3.1.0

Base URL

https://vpn.yourdomain.com/api/v1/integration

Rate limit

90 requests per minute per token/IP bucket.

Provider scope

When a billing token is scoped to a provider, omit provider from requests. Otherwise pass provider as a lowercase billing connection key.

Safe retries

A matching key and request body returns the original response with Idempotency-Replayed. The same key with a different body returns HTTP 409.

Account request fields

external_client_id: Required. Stable customer identifier from your billing system; maximum 120 characters.
external_service_id: Required. Stable service identifier; maximum 120 characters.
email: Required when creating a new customer. Must be a valid email address.
name: Optional customer name; maximum 255 characters.
profile_count: Required. Number of VPN profiles included with the service, from 1 to 10,000.
product_name: Optional customer-facing product name; maximum 255 characters.
status: Optional: active, suspended or cancelled.

Endpoints

get /profile Read integration profile and capabilities

Responses

200: Integration profile

post /accounts Create or update a VPN account

Parameters

Idempotency-Key: header · optional
Required for safe webhook retries. The same key must always use the same request body.

Responses

200: Existing account updated
201: Account created and app token returned
409: Idempotency key conflict or in-progress request

post /accounts/{external_service_id}/suspend Suspend a VPN account

Parameters

external_service_id: path · required
External service/account identifier from the billing platform.
Idempotency-Key: header · optional
Required for safe webhook retries. The same key must always use the same request body.

Responses

200: Lifecycle action applied
409: Idempotency key conflict or in-progress request

post /accounts/{external_service_id}/unsuspend Reactivate a VPN account

Parameters

external_service_id: path · required
External service/account identifier from the billing platform.
Idempotency-Key: header · optional
Required for safe webhook retries. The same key must always use the same request body.

Responses

200: Lifecycle action applied
409: Idempotency key conflict or in-progress request

post /accounts/{external_service_id}/cancel Cancel a VPN account

Parameters

external_service_id: path · required
External service/account identifier from the billing platform.
Idempotency-Key: header · optional
Required for safe webhook retries. The same key must always use the same request body.

Responses

200: Lifecycle action applied
409: Idempotency key conflict or in-progress request

Building a custom integration?

The signed-request contract, customer application API, compatibility fields and complete data models are available in the client area.

Open developer reference

Errors and retries

400: The request could not be understood.
401: The token or request signature is missing or invalid.
403: The token does not have permission for the action.
404: The customer, account, profile or server was not found.
409: The request conflicts with existing state or an idempotency key.
422: One or more request fields failed validation.
429: The rate limit was reached. Retry after the response indicates.
5xx: A temporary service failure occurred. Retry with bounded exponential backoff.