Skip to main content
The Billing API lets PayChoice run recurring charges for you. You describe the plan and the customer; PayChoice generates the schedule, raises invoices, charges the stored payment method as each item falls due, and tells you the outcome by webhook.

​
The flow

1

Create a customer

A customer record with contact and address details. You get a GUID.
2

Attach a payment method

Tokenise a card or bank account — via the API or the Create Token page — and attach it to the customer. Attaching it is what stops the token expiring after first use.
3

Define a membership

A membership is a reusable plan: setup fee, optional trial, billing cycle, minimum term, cancellation rules.
4

Subscribe the customer

A subscription links a customer to a membership from a start date.
5

PayChoice takes it from there

The payment schedule lists what will be charged and when. As each item falls due, an invoice is raised and the customer’s default payment method charged. Failed payments can attract a dishonour fee.

​
Response envelope

Billing responses use a different envelope from the payment endpoints. Every success looks like this, with the payload under a key named by object_type:
​
string
Always "Success" on a successful call.
​
integer
201 when a record was created, otherwise 200. The HTTP status is 200 in both cases.
​
array
One item: message_text and message_type (success).
​
object | array
The payload, e.g. customer, membership, subscription_list.
​
integer
Paginated lists only (customers, memberships, subscriptions). null on an empty page.

​
Errors

Send Accept: application/json on every Billing request. Without it, errors come back as HTML.
status is false, code matches the HTTP status, and messages has one item per problem (message_field on validation errors). message is Unauthorized (401), Forbidden (403), Not Found (404) or The given data was invalid. (422). See Errors for the full list.

​
Identifiers

Customers, memberships, subscriptions, payment-schedule items and invoices are identified by GUID in URLs and in each object’s id. Objects also expose an integer reference_id (or customer_id / invoice_number) for display; don’t use the integer in URLs.

​
Request format

Billing endpoints are documented with v4 form-data; /api/v5/ accepts the same fields as JSON. URLs are case-sensitive.