Payment Sessions

A payment session is an invitation to pay. You create one, get a URL on your own web address, and send it by email or text. Your customer opens it, sees your brand — not ours — and pays by bank account or card.

This is different from Payment Links, which hands back a Stripe-hosted page. A payment session is served on your domain, with your logo, colour and sender identity, all configured once in the provider portal under Settings → Custom Checkout.

Before you start #

Everything about how the page looks and where it lives is configuration, not code. Set it once in the portal:

Until your own address verifies, links are issued on the Audit1 address and keep working. This is deliberate. A link is never issued on a name nobody has proven they own.

Create a session #

POST /api/v1/payment-sessions

* Send either amount_cents or premium_cents + fee_cents. If you send both and they disagree, the request is rejected — see Amounts.

Example #

POST /api/v1/payment-sessions

{
  "employer_id": "68a1f4c2e9b3d70012ab34cd",
  "policy_id": "68a1f4c2e9b3d70012ab34ce",
  "premium_cents": 1153800,
  "fee_cents": 20000,
  "fee_breakdown": [{ "label": "Audit fee", "amount_cents": 20000 }],
  "description": "Workers' Comp premium — August 2026",
  "customer": {
    "name": "Sample Insured LLC",
    "email": "ap@sampleinsured.com",
    "phone": "+15551234567"
  },
  "deliver": { "email": true }
}

{
  "ok": true,
  "data": {
    "id": "68b7c1d4e9b3d70012ab9911",
    "url": "https://pay.yourcompany.com/pay/9xK2f...",
    "token_prefix": "9xK2fQ7a",
    "mode": "link",
    "status": "pending",
    "amount_cents": 1173800,
    "line_items": [
      { "label": "Premium", "amount_cents": 1153800 },
      { "label": "Audit fee", "amount_cents": 20000 }
    ],
    "expires_at": "2026-08-12T22:48:00.000Z",
    "single_use": true,
    "host_is_custom": true,
    "config_version": 7,
    "delivery": [
      { "channel": "email", "to": "ap@sampleinsured.com", "status": "sent", "at": "..." }
    ],
    "delivery_ok": true
  }
}

Keep the URL #

url is returned once and cannot be recovered. The token in it is a bearer credential — anyone holding it can open a page naming your insured and an amount — so only a hash of it is stored. If you lose it, use reissue.

Amounts #

The rules refuse rather than guess. Every one of these is a 400:

Fees are always shown as their own line on the page. They are never folded into the premium.

Instalment plans #

Send total_installments together with a down payment and the session sells a plan instead of a one-time payment.

A down payment field without total_installments is a 400: a down payment on its own is just a partial payment, and the rest would never be collected.

The reverse is allowed and is worth knowing: total_installments with neither down payment field means a down payment of 0, so the session's amount_cents is 0 and nothing is collected on the day the payer signs. Send down_payment_percent: 0 deliberately if that is what you mean.

The arithmetic #

The rules below are exact. They match the billing rail an agent already builds plans on, so the amounts collected are the amounts the customer was shown.

1. The base includes the fees. The percentage is applied to premium_cents + fee_cents, not to the premium alone.
2. A flat down_payment_cents overrides the percentage entirely.
3. The down payment is floored, never rounded. Rounding up collects more today than the percentage stated.
4. Each instalment is floored: per_installment = floor(remaining / total_installments).
5. The last instalment is derived by subtraction, never computed: last = remaining - per_installment * (total_installments - 1). That is what makes the schedule sum exactly for any N and any percentage.

So total_installments: 9 means 8 instalments at the flat amount plus one final instalment — not 9 flat plus a tenth.

Worked example

A $1,361.00 total, 25% down, 9 instalments:

The schedule is 8 × $113.41 + 1 × $113.47, and $340.25 + $1,020.75 = $1,361.00 exactly.

What gets charged today #

A plan is bank-rail only #

Only the bank rail can run a schedule — each instalment is minted as a leg by the ACH gateway's daily cron. On a card, the payer would be charged the down payment and the other N would never be collected.

So the card mount on the payment page refuses a plan outright. POST /public/payment-sessions/{token}/checkout answers 409:

{
  "ok": false,
  "error": "Unavailable",
  "message": "This is a payment plan, which can only be set up from a bank account. Please use the bank option on this page."
}

The instalment dates are monthly, starting one month after creation, anchored on the UTC day of the month the plan was created, at 17:00 UTC (noon Eastern in winter — the hour is fixed in UTC, not shifted for daylight saving). Month-end is clamped, never rolled — a plan created on 31 January takes its first instalment on 28 February, because rolling into March would put two instalments in one month.

down_payment_months is refused #

{
  "ok": false,
  "error": "Bad Request",
  "message": "down_payment_months has no unambiguous meaning here — there is no honest conversion from a count of months to an amount. Send down_payment_percent (0-100), or down_payment_cents for a flat amount (which wins over the percentage)."
}

Example: a plan #

curl -X POST /api/v1/payment-sessions \
  -H "X-Client-ID: $CLIENT_ID" \
  -H "X-Client-Secret: $CLIENT_SECRET" \
  -d '{
    "employer_id": "681xyz789abc123456789012",
    "carrier_id": "680abc456def789012345678",
    "policy_id": "682def789ghi012345678901",
    "premium_cents": 136100,
    "total_installments": 9,
    "down_payment_percent": 25,
    "customer": {
      "name": "Smith Industries",
      "email": "ap@smithindustries.com"
    },
    "deliver": { "email": true }
  }'

The response's amount_cents is 34025 — the down payment.

Delivery #

Set deliver.email or deliver.sms and we send the invitation immediately, from your configured sender identity.

A failed send is reported, never swallowed. The response carries delivery (one entry per channel, with the reason on failure) and delivery_ok. Check it — if it is false the session still exists and the url is still valid, so you can send it another way. Treating a failed send as success means waiting on a payment nobody was ever asked to make.

Text messages currently send from the Audit1 number. The sms_from setting is stored but not yet applied — the underlying service sends from one fleet number and has no per-message override.

Embedded mode #

mode: "embedded" skips the link entirely and returns a client_secret for mounting Stripe's Embedded Checkout in your own application.

{
  "ok": true,
  "data": {
    "id": "...",
    "client_secret": "cs_live_...",
    "publishable_key": "pk_live_...",
    "status": "pending"
  }
}

Delivery fields are rejected in this mode — there is no link to send.

Track a session #

GET  /api/v1/payment-sessions          List — filter by employer_id, policy_id, carrier_id, status
GET  /api/v1/payment-sessions/:id      One session

opened vs pending distinguishes "never saw it" from "saw it and did not pay" — different conversations.

scheduled is the bank rail's waiting room #

A card payment goes straight to paid — the money moves while the customer is still on the page. A bank debit cannot: it is handed to the ACH network and takes days. So a bank session sits at scheduled in between, and that status means exactly one thing — the customer has committed, and nobody has been debited yet. Do not read it as collected.

A one-time bank session becomes paid when the money is confirmed, and what counts as confirmation depends on where the carrier's money lands:

On the direct rail the money never passes through an account we can read, so the processor's report is the strongest confirmation that can exist there. Both events are documented on Payment Webhooks — subscribe rather than poll, and the settlement_source field on each payload tells you which of the two claims you are holding.

Expect roughly a week of waiting on the FBO rail: the median gap between the ACH processor reporting the debit settled and payment.debit_cleared arriving is about 7 days, measured over the 275 debits matched since the 2026-08-04 backfill that carry a processor settlement date (314 matched in all), as of 2026-08-18. The direct rail carries the processor's report itself, so it resolves sooner.

Cancel a link #

DELETE /api/v1/payment-sessions/:id

A paid session cannot be cancelled (409). The money already moved; changing the record would misstate what happened. Refund the payment instead.

Reissue a link #

POST /api/v1/payment-sessions/:id/reissue

The original token was never stored, so the same link cannot be re-sent. This mints a fresh one with the same details — and cancels the old one in the same call, before the new one exists.

That ordering is deliberate: two live links for one debt is how one payment becomes two, and nobody asking for a resend is asking for that. If the mint fails, nothing is payable — the safe direction.

Accepts ttl_minutes and the same deliver block. The response carries replaces with the cancelled session's id.

A session with a bank debit arranged cannot be reissued (409) — "A bank debit is already arranged for this session — cancel that debit first." That covers a session sitting at scheduled, and any session still carrying a debit reference even if the link itself was cancelled since.

Cancelling a session does not call the debit back. The debit is a separate instruction already on the ACH rail, and the next batch close sends it whatever the session says. So a fresh payable link at that moment is a live link for money that is already leaving the customer's account — they pay it, and they have paid twice. It is the paid-session rule one step earlier: 409 while the money is moving, 409 once it has moved.

There is no partner-API route that cancels a session's bank debit — reach us at support@audit1.com to stop one. (A plan is different: the payer can stop the remaining instalments themselves from the payment page.)

Know when they pay #

Register a callback under Settings → Custom Checkout → Payment notifications, or via the Payment Webhooks API. Which event you get depends on how they paid:

Nothing is sent when a bank debit is arranged. There is no webhook between the customer authorising the debit and the money being confirmed, so if you need to know they committed, read the session — it sits at scheduled for that whole stretch.

payment.completed covers payments taken through Stripe checkout: the card option on this page, and — in embedded mode, where the page is yours and ours is not in the picture — a Stripe bank debit too. It never fires for this page's own Bank account (ACH) option, which runs on Audit1's ACH rails and reports through the payment.debit_* events instead. Subscribing to payment.completed alone means never hearing about a payment made there.

Both events are new (August 2026). Which rails are live for the carriers behind your policies can change — support@audit1.com will confirm before you rely on them. And an existing subscription does not pick up a new event type on its own — resend your full events list to start receiving them. Some carriers sit on neither rail and produce neither event, so their sessions never reach paid; the Payment Webhooks page has the detail, including why you should still subscribe to both names.

Every request is signed. The signing secret is shown once, when you register the callback or rotate it — copy it then.

Sandbox #

Payment sessions have no sandbox mode and will return a 400 on a sandbox-scoped key. The upstream Stripe service ignores the environment flag, so a sandbox key would create a real session against live credentials. Use POST /api/v1/payment-links for sandbox testing.

Errors #