Skip to main content
POST
  • The whole request is validated before we respond (payload, employer onboarding, every employee, MVR payment gate, active USIs). If anything is wrong you get a 400 listing every error and nothing is stored.
  • A valid request returns 202 Accepted with a transactionId straight away. The submission to the clearing house happens in the background as one transaction (one direct debit).
  • The outcome arrives via the contribution.submission_completed webhook, or poll GET /v2/contributions/:transactionId.

Idempotency-Key (required)

Send a unique Idempotency-Key header with every new submission and reuse it when retrying the same submission (e.g. after a timeout or network error). Keys are scoped to your client and never expire.

Limits

100 funds / 1000 members per request (v1: 8 funds / 40 members).

Request Parameters

string
required
Your unique key for this submission (e.g. a UUID, or your own pay-run ID). Reuse it when retrying the same request; use a new one for a new submission.

Request Body

string
required
Employer ID that this contribution belongs to. The employer must be associated with the authenticated client.
object
required
Simplified contribution details. Only variable data (fund USIs, amounts, pay periods) is required. Employee and employer static data will be automatically retrieved from the database.

Responses

Response fields

string
The SuperChoice transaction ID for this submission. It is used everywhere afterwards: GET /v2/contributions/:transactionId, payment status endpoints and payment.status_changed webhooks.
string
string
ACCEPTED on a new submission. A replay returns the submission’s current status.
object
Totals calculated from the request body
boolean
integer
string
array
Every validation error found, each as { path, message }
Last modified on November 10, 2026