Agreements

StudentPay stores a Payment Plan Agreement on first confirm. A provider-specific student agreement object is not required for NZ Enrolment Integration launch. Declarations on confirm (payment_plan_accepted, information_confirmed, privacy_consent_accepted) plus the PPA cover consent capture.

There is no public provider endpoint that downloads the PDF.

When the agreement is created

Confirm is the Integration acceptance step. The payer must have completed GoCardless setup (setup_complete), and the confirm body must send all three declaration booleans plus payment.deposit_confirmed: true. That last field records acceptance. It does not collect the initial payment at confirm.

On the first successful confirm, after setup is complete and declarations are accepted, StudentPay:

Creates a Payment Plan Agreement if one does not already exist
Records acceptance
Generates a PDF and stores it
Returns agreement identifiers on the confirm response

A repeat confirm returns the existing agreement with already_confirmed: true. It does not generate a second agreement or a second payment schedule.

What the API returns

Confirm (and later GET) expose references, not a file stream.

Confirm may include:

Field	Meaning
`agreement.id` / `payment_plan_agreement_id`	Agreement record id
`agreement.number` / `payment_plan_agreement_number`	Human-readable number (for example `PPA-000001`)
`agreement.status`	Agreement status
`agreement.pdf_content_document_id`	Stored PDF id
`agreement.pdf_generated` / `pdf_generated`	`true` when a PDF id is present
`agreement_already_existed`	`true` when confirm reused an existing accepted agreement

GET /v1/provider-checkouts/{checkoutId} may include:

{
  "agreement": {
    "id": "a0JXXXXXXXXXXXX",
    "number": "PPA-000001",
    "status": "Accepted",
    "version": "2026-08-02",
    "accepted_at": "2026-08-13T02:00:00.000Z",
    "pdf_content_document_id": "069XXXXXXXXXXXX"
  }
}

or agreement: null if confirm has not stored one yet.

What you should do with the PDF id

Keep it for support correlation. Do not expect a StudentPay URL that streams the PDF to your application. If your operations team needs the file, they retrieve it through StudentPay’s back office — not this API.

Hosted legal pages

Payers can read hosted terms during enrolment (/legal/direct-debit-terms, /legal/payment-plan-terms). Those are browser pages, not authenticated provider API operations.