Payment Plans
NZ provider checkout establishes an interest-free payment plan. Your create request describes the commercial plan. StudentPay does not collect the instalments on that call.
After confirm, Salesforce creates the schedule and owns collection.
Fields
| Field | Required | Meaning |
|---|---|---|
pricing.course_price |
Yes | Full course price. Must be greater than zero |
pricing.upfront_payment |
No | Amount due before instalments. This API does not charge it |
pricing.amount_to_finance |
Yes | Amount to be financed on the instalment plan. Must be greater than zero. This API does not collect it |
plan.instalment_amount |
Yes | Each instalment. Must be greater than zero |
plan.number_of_instalments |
Yes | Count of instalments. Must be greater than zero |
plan.payment_frequency |
Yes | For example Weekly |
plan.first_payment_date |
Yes | ISO date (YYYY-MM-DD) |
plan.payment_type |
Yes | Use interest_free_payment_plan |
Validation the API enforces
Create returns 400 VALIDATION_ERROR when required fields are missing or when the numeric/date fields above are not positive / not a valid date.
The API does not currently reject a request solely because the arithmetic does not balance. Send a coherent plan anyway.
Recommended relationship
For a coherent plan, send:
course_price = upfront_payment + amount_to_finance
amount_to_finance = number_of_instalments × instalment_amount
Sandbox example used in Quickstart:
| Field | Value |
|---|---|
| Course price | 2800 |
| Upfront payment | 10 |
| Amount financed | 2790 |
| Instalment amount | 15 |
| Number of instalments | 186 |
| Frequency | Weekly |
| First payment date | 2026-08-20 |
10 + (186 × 15) = 2800.
Confirm body
Confirm repeats payment.first_payment_date and requires payment.deposit_confirmed: true and payment.payment_method (use studentpay_payment_plan). Those fields record acceptance. This API does not charge a deposit.
After confirm
Do not call a payments API. There isn’t one on this contract. Salesforce creates the schedule from the confirmed plan. First collection is not the confirm response.