Idempotency

Create and confirm are safe to retry. They do not emit outbound webhooks again on replay.

Create checkout

1. Prefer the Idempotency-Key header (max 255 characters)
2. Otherwise StudentPay uses {provider_code}:{provider_order_id}

POST /v1/provider-checkouts
Idempotency-Key: DEMO-ENROLMENT-1001
Authorization: Bearer <YOUR_API_KEY>

If a checkout already exists for that provider and provider order id (or checkout id), the API returns 200 with:

{
  "success": true,
  "idempotent_replay": true,
  "idempotency_key": "DEMO-ENROLMENT-1001"
}

No additional student, checkout, or direct-debit authority records are created.

While the checkout is still open, a replay may remint a fresh direct_debit.setup_url and direct_debit.token. Use the latest URL and token.

checkout.created is sent only on the first create, not on replay.

Create does not return IDEMPOTENCY_CONFLICT. A retry with the same identity reuses the existing checkout.

Confirm

If the checkout is already confirmed, confirm returns 200 with already_confirmed: true and the existing agreement references.

It does not:

• create a second Payment Plan Agreement
• generate a second PDF
• create a second payment schedule
• emit checkout.confirmed or agreement.generated again

You can safely retry confirm after a network timeout.

StudentPay NZ Provider Checkout API v1 · partners@studentpay.com.au