Skip to main content

API Reference

This page is generated from api/openapi.json. Do not edit endpoint details by hand.

Status: The external sandbox API hostname is live for approved controlled pilots at https://api.sandbox.sparelane.com.au/v1.

Contract version: 2026-10-23.phase-6c

Authentication: send Authorization: Bearer <sandbox-api-key> with every request.

Endpoints​

GET /merchant​

Get authenticated merchant profile

Returns the merchant resolved from the bearer API key. Merchant identity is never accepted from request parameters.

Responses​

  • 200 Authenticated merchant profile.
  • 401 Missing, invalid, expired or revoked bearer API key.
  • 403 Merchant is not active.
  • 429 Rate limit exceeded.
  • 503 Distributed rate-limit store is unavailable in merchant API deployment.

GET /customers​

List merchant customers

Lists only customers belonging to the authenticated merchant.

Parameters​

  • limit (query) optional — integer

Responses​

  • 200 Customers.
  • 400 Invalid request.
  • 401 Missing, invalid, expired or revoked bearer API key.
  • 429 Rate limit exceeded.

POST /customers​

Create a merchant customer

Creates a merchant-scoped customer with an opaque placeholder consumer. The global consumer ID is not exposed. externalCustomerId is unique per merchant.

Request Body​

  • externalCustomerId required (string)
  • displayName required (string)
  • email required (string)

Responses​

  • 201 Customer.
  • 400 Invalid request.
  • 401 Missing, invalid, expired or revoked bearer API key.
  • 409 Request conflicts with current sandbox state or idempotency.
  • 429 Rate limit exceeded.

GET /customers/{customerId}​

Get a merchant customer

Returns 404 for customers outside the authenticated merchant tenant.

Parameters​

  • customerId (path) required — string

Responses​

  • 200 Customer.
  • 401 Missing, invalid, expired or revoked bearer API key.
  • 404 Resource not found in authenticated merchant tenant.
  • 429 Rate limit exceeded.

PATCH /customers/{customerId}​

Update merchant-owned customer fields

Allows updates to merchant-owned display fields only. Consumer identity, merchant ownership, mandates and authorisation state cannot be modified.

Parameters​

  • customerId (path) required — string

Request Body​

  • externalCustomerId optional (string)
  • displayName optional (string)
  • email optional (string)

Responses​

  • 200 Customer.
  • 400 Invalid request.
  • 401 Missing, invalid, expired or revoked bearer API key.
  • 404 Resource not found in authenticated merchant tenant.
  • 409 Request conflicts with current sandbox state or idempotency.
  • 429 Rate limit exceeded.

POST /customers/{customerId}/link-authorizations​

Create a consumer link authorisation

Creates a short-lived, single-use invitation for this merchant customer. The invitation token is returned once. Consumer approval requires separate consumer authentication outside merchant API credentials.

Parameters​

  • customerId (path) required — string

Request Body​

  • expiresInMinutes optional (integer)
  • consentText optional (string)
  • consentVersion optional (string)

Responses​

  • 201 Link authorisation and one-time invitation token.
  • 400 Invalid request.
  • 401 Missing, invalid, expired or revoked bearer API key.
  • 404 Resource not found in authenticated merchant tenant.
  • 429 Rate limit exceeded.

POST /customers/{customerId}/link-authorizations/{authorizationId}/cancel​

Cancel a pending link authorisation

Cancels a pending link authorisation owned by this merchant customer. Already non-pending authorisations are returned unchanged.

Parameters​

  • customerId (path) required — string
  • authorizationId (path) required — string

Responses​

  • 200 Link authorisation.
  • 401 Missing, invalid, expired or revoked bearer API key.
  • 404 Resource not found in authenticated merchant tenant.
  • 429 Rate limit exceeded.

GET /mandates​

List merchant payment mandates

Lists mandates owned by the authenticated merchant. Payment method details are masked fictional metadata only.

Parameters​

  • limit (query) optional — integer
  • status (query) optional — string

Responses​

  • 200 Mandates.
  • 400 Invalid request.
  • 401 Missing, invalid, expired or revoked bearer API key.
  • 429 Rate limit exceeded.

GET /bills​

List bills

Parameters​

  • limit (query) optional — integer
  • status (query) optional — string

Responses​

  • 200 Bills.
  • 400 Invalid request.
  • 401 Missing, invalid, expired or revoked bearer API key.
  • 429 Rate limit exceeded.

POST /bills​

Submit a fictional bill

Creates an issued bill for a merchant customer identified by externalCustomerId. idempotencyKey is required and maps to externalBillId when externalBillId is omitted. Matching repeated submissions return 200 with idempotent=true; conflicting payloads return 409.

Request Body​

  • externalCustomerId required (string)
  • amountCents required (integer)
  • currency required (string)
  • dueAt required (string)
  • description required (string)
  • idempotencyKey required (string)
  • externalBillId optional (string)

Responses​

  • 200 Bill submission result.
  • 201 Bill submission result.
  • 400 Invalid request.
  • 401 Missing, invalid, expired or revoked bearer API key.
  • 404 Resource not found in authenticated merchant tenant.
  • 409 Request conflicts with current sandbox state or idempotency.
  • 429 Rate limit exceeded.

GET /bills/{billId}​

Get a bill

Returns 404 for bills outside the authenticated merchant tenant.

Parameters​

  • billId (path) required — string

Responses​

  • 200 Bill.
  • 401 Missing, invalid, expired or revoked bearer API key.
  • 404 Resource not found in authenticated merchant tenant.
  • 429 Rate limit exceeded.

POST /bills/{billId}/simulations​

Run a sandbox payment simulation

Sandbox-only deterministic fictional payment simulation for a merchant-owned bill. Does not move real money, change consumer consent or call an external payment provider.

Parameters​

  • billId (path) required — string

Request Body​

  • scenario optional (string)

Responses​

  • 200 Simulation result.
  • 400 Invalid request.
  • 401 Missing, invalid, expired or revoked bearer API key.
  • 404 Resource not found in authenticated merchant tenant.
  • 409 Request conflicts with current sandbox state or idempotency.
  • 429 Rate limit exceeded.

GET /payments​

List payments

Parameters​

  • limit (query) optional — integer
  • status (query) optional — string

Responses​

  • 200 Payments.
  • 400 Invalid request.
  • 401 Missing, invalid, expired or revoked bearer API key.
  • 429 Rate limit exceeded.

GET /payments/{paymentId}​

Get a payment

Returns 404 for payments outside the authenticated merchant tenant.

Parameters​

  • paymentId (path) required — string

Responses​

  • 200 Payment.
  • 401 Missing, invalid, expired or revoked bearer API key.
  • 404 Resource not found in authenticated merchant tenant.
  • 429 Rate limit exceeded.

GET /webhooks​

List webhook endpoints

Responses​

  • 200 Webhook endpoints.
  • 401 Missing, invalid, expired or revoked bearer API key.
  • 429 Rate limit exceeded.

POST /webhooks​

Create webhook endpoint

Registers an HTTPS webhook endpoint. Localhost, private, internal, link-local and metadata destinations are rejected. The plaintext signing secret is returned once and only its SHA-256 hash is stored.

Request Body​

  • url required (string)
  • description optional (string)
  • eventTypes required (array)

Responses​

  • 201 Webhook endpoint with one-time signing secret.
  • 400 Invalid request.
  • 401 Missing, invalid, expired or revoked bearer API key.
  • 409 Request conflicts with current sandbox state or idempotency.
  • 429 Rate limit exceeded.

GET /webhooks/{endpointId}/deliveries​

List webhook delivery history

Returns the latest delivery records for an endpoint owned by the authenticated merchant.

Parameters​

  • endpointId (path) required — string

Responses​

  • 200 Webhook deliveries.
  • 401 Missing, invalid, expired or revoked bearer API key.
  • 404 Resource not found in authenticated merchant tenant.
  • 429 Rate limit exceeded.

POST /webhooks/{endpointId}/disable​

Disable webhook endpoint

Parameters​

  • endpointId (path) required — string

Responses​

  • 200 Webhook endpoint.
  • 401 Missing, invalid, expired or revoked bearer API key.
  • 404 Resource not found in authenticated merchant tenant.
  • 429 Rate limit exceeded.

POST /webhooks/{endpointId}/rotate-secret​

Rotate webhook signing secret

Generates and returns a replacement signing secret once. Existing delivery signing uses the current stored secret hash.

Parameters​

  • endpointId (path) required — string

Responses​

  • 200 Webhook endpoint with rotated one-time signing secret.
  • 401 Missing, invalid, expired or revoked bearer API key.
  • 404 Resource not found in authenticated merchant tenant.
  • 429 Rate limit exceeded.

POST /webhooks/{endpointId}/test-event​

Generate signed webhook test payload

Returns a signed test payload and headers without delivering it.

Parameters​

  • endpointId (path) required — string

Responses​

  • 200 Signed test payload and headers. Not delivered.
  • 401 Missing, invalid, expired or revoked bearer API key.
  • 404 Resource not found in authenticated merchant tenant.
  • 409 Request conflicts with current sandbox state or idempotency.
  • 429 Rate limit exceeded.