Choose your NZ enrolment product

StudentPay NZ enrolment is two products that share the same financial state machine. Pick the product that matches who owns the student-facing UX.

Product	Who owns the UX	Who calls `/v1`	Start here
Enrolment Integration API	The education provider	The provider’s backend	Enrolment Integration
Hosted Enrolment Checkout	StudentPay	StudentPay’s hosted app	Hosted Enrolment Checkout

Do not copy StudentPay Hosted Checkout, and do not call /api/demos/bela-beauty/*. Those demo routes are not the Integration contract.

Product 1 — Enrolment Integration API

Use this when you already have (or will build) enrolment UX.

Provider frontend
    ↓
Provider backend   ← API key stays here
    ↓
POST /v1/provider-checkouts
    ↓
Payer browser opens setup_url (GoCardless BECS NZ)
    ↓
GET /v1/provider-checkouts/{checkout_id}  until setup_complete
    ↓
POST /v1/provider-checkouts/{checkout_id}/confirm

Your server authenticates. The payer’s browser never sees your provider key.

Full contract: Enrolment Integration.

Product 2 — Hosted Enrolment Checkout

Use this when you do not want to own enrolment UX.

Student
    ↓
StudentPay hosted enrolment
    ↓
StudentPay backend
    ↓
same /v1 Provider Checkout machine

StudentPay hosts course presentation, student details, declarations, the GoCardless handoff, and confirm. Hosted Checkout has completed production certification. StudentPay coordinates any new hosted tenant.

Details: Hosted Enrolment Checkout.

Shared financial machine

Both products reuse the same /v1 create → direct debit → confirm path:

Create a checkout
Payer completes hosted BECS NZ setup through GoCardless
Confirm only when direct_debit.setup_complete is true
StudentPay stores the Payment Plan Agreement PDF
Salesforce originates the charge schedule (including any residual final instalment)

Confirm eligibility is setup_complete. It is not necessary for authorisation_status to already be Authorised, or for the GoCardless mandate to already be active.

After confirmation, Salesforce owns instalment collection. Your integration does not submit payments.

What this API does not do

It does not collect instalments on create or confirm
It does not collect an initial payment at confirm. After confirm, Salesforce originates any initial-payment Charge_Schedule and the existing Direct Debit processor collects it
Catalogue-authoritative Integration providers cannot override StudentPay course price or derived instalment maths
It does not treat hosted setup as Authorised
It does not expose a public agreement PDF download
Outbound provider webhooks are implemented in code; they are delivered only when StudentPay has configured a destination for that environment

See Current contract for the accurate limitations.

Start here

If you need	Go to
To choose Integration vs Hosted	This page
Sandbox API host and a first enrolment	Sandbox testing
How to authenticate	Authentication
How to create, poll, and confirm	Enrolment Integration
What `setup_complete` means	Direct debit setup
How retries work	Idempotency
Current limitations	Current contract
Moving to Production	Production onboarding
Interactive OpenAPI	API Reference

Base URLs

Environment	Base URL
Sandbox (start here)	`https://sandbox-api.studentpay.co.nz`
Production	`https://api.studentpay.co.nz`

Sandbox and Production are isolated: separate keys, Salesforce orgs, and GoCardless accounts. Never reuse sandbox credentials in Production.

curl https://sandbox-api.studentpay.co.nz/v1/environment

Expect "environment": "sandbox", "payment_processor": "gocardless", and "ready_for_api_calls": true.

Public provider routes

Method	Path
`GET`	`/v1`
`GET`	`/v1/environment`
`POST`	`/v1/provider-checkouts`
`GET`	`/v1/provider-checkouts/{checkoutId}`
`POST`	`/v1/provider-checkouts/{checkoutId}/confirm`

New providers should use /v1 only.

Start sandbox testing Enrolment Integration Open API Reference