Async contribution submissions

​

When to use v2 vs v1

​

How it works

• Submit — POST /v2/contributions with your Idempotency-Key header.
• Validated up front, all or nothing — we check the payload, that the employer exists and is onboarded at the clearing house, that every employee exists for your client, the MVR payment gate (same rules as v1), and that every usi is an active fund. If anything fails you get a 400 listing every error, and nothing is stored.
• 202 Accepted — you get back a transactionId. This is the one SuperChoice transaction ID used everywhere afterwards: payments, payment status endpoints, and payment.status_changed webhooks.
• Background submission — the submission is usually picked up within about a minute and sent to the clearing house as one transaction (one direct debit).
• Outcome — the contribution.submission_completed webhook fires, or poll GET /v2/contributions/:transactionId.
• After SUBMITTED — everything else (payment status, payment.status_changed webhooks, fund responses) works exactly as it does for v1 transactions.

​

Idempotency-Key

curl -X POST 'https://qa-super.mygigsters.com.au/v2/contributions' \
  -u "apiUsername:apiPassword" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: payrun-2026-10-27-001" \
  --data @contribution.json

{
  "transactionId": "txn-3cb85051-09cd-4a04-9952-100b20384ada",
  "employerId": "6960d86e466f44ab3f163c66",
  "status": "ACCEPTED",
  "totals": { "funds": 2, "members": 3, "amount": "3.00" }
}

​

Validation errors

{
  "success": false,
  "statusCode": 400,
  "message": "Contribution validation failed",
  "errors": [
    {
      "path": "contributionDetails.funds[0].usi",
      "message": "USI 12345678901234 is not an active fund"
    },
    {
      "path": "contributionDetails.funds[1].members[2].employeeId",
      "message": "Payment blocked for employee 6a58c9406820b9ff62b527b3: MVR status is PENDING"
    }
  ]
}

​

Statuses

​

Webhook: contribution.submission_completed

{
  "event": "contribution.submission_completed",
  "timestamp": "2026-10-27T10:34:05.148Z",
  "data": {
    "transactionId": "txn-3cb85051-09cd-4a04-9952-100b20384ada",
    "employerId": "6960d86e466f44ab3f163c66",
    "status": "SUBMITTED",
    "totals": { "funds": 2, "members": 3, "amount": "3.00" },
    "completedAt": "2026-10-27T10:34:04.123Z"
  }
}

​

Retrying safely

• No response / timeout / 5xx from POST /v2/contributions — resend the same body with the same Idempotency-Key. You’ll get the original transactionId back; nothing is submitted twice.
• 400 — nothing was stored. Fix the errors and send again (the same key is fine, since nothing was stored under it).
• FAILED — safe to fix and resubmit, with a new Idempotency-Key. Requests are re-checked just before sending, so FAILED can also mean something changed after you submitted (for example, an employee’s MVR status).
• UNDER_REVIEW — don’t resubmit. The money may already have gone through; our team will resolve it.

​

Limits

• 100 funds and 1000 members (across all funds) per request.
• Need more? Split the pay run into several requests, each with its own Idempotency-Key.