Direct Debit Setup

NZ enrolment uses hosted BECS NZ setup through GoCardless.

Your server creates the checkout. The payer’s browser completes bank setup. Your server then confirms.

Two terms you must not mix

Direct debit setup complete

The payer finished hosted GoCardless setup and StudentPay has the required Billing Request / mandate information.

Typically:

Billing Request status is fulfilled
A mandate id is present
Mandate status is pending_submission, submitted, or active

This is enough for StudentPay’s checkout setup-complete gate. You may call confirm.

The mandate may still be pending_submission or submitted. That is normal.

Direct debit Authorised

The GoCardless mandate has reached active.

Only then does StudentPay treat the direct-debit authority as Authorised.

Never use “authorised” as a synonym for “setup completed”.

State	`setup_complete`	`authorised`	Confirm?
New checkout	`false`	`false`	No
Hosted setup finished, mandate `pending_submission`	`true`	`false`	Yes
Mandate `submitted`	`true`	`false`	Yes
Mandate `active`	`true`	`true`	Yes

Browser flow

Your backend                 Payer browser              GoCardless
     |                            |                          |
     |  create checkout           |                          |
     |----------------------->    |                          |
     |  setup_url + token         |                          |
     |                            |  open setup_url          |
     |                            |------------------------->|
     |                            |  BECS NZ bank details    |
     |                            |<------------------------>|
     |                            |  return to StudentPay    |
     |  GET checkout              |                          |
     |  setup_complete?           |                          |
     |  POST confirm              |                          |

Hosted setup URL

Create returns direct_debit.setup_url, for example:

https://sandbox-api.studentpay.co.nz/api/dd-setup?token=eyJ…

That page starts or reuses a GoCardless Billing Request Flow. The payer does not submit bank details to your API.

Return

GoCardless returns to StudentPay at /api/direct-debit/gocardless/return. StudentPay syncs mandate data.

If setup was a popup, the return page may send studentpay:dda-return to the opener. Do not trust that message as the confirm gate. Call GET /v1/provider-checkouts/{checkoutId}.

These hosted URLs are not provider API operations. Do not send your API key to them. They are not listed as Try-it operations in the API Reference.

Polling after return

Read direct_debit on GET:

Field	Meaning
`setup_complete`	Confirm gate
`billing_request_status`	Hosted Billing Request status
`mandate_status`	GoCardless mandate status
`authorisation_status`	StudentPay authority status
`authorised`	`true` only when Authorised / mandate `active`

Confirm errors

If you confirm too early:

409 with error.code = DIRECT_DEBIT_SETUP_INCOMPLETE

Wait and GET again. Do not retry confirm in a tight loop.

After confirm

Mandate activation can continue asynchronously. Salesforce owns the payment schedule and later collection. Authorised is a collection gate, not the enrolment gate.