Payment Links & Subscriptions

Create hosted payment links for one-time charges and direct billing installment plans, or standalone subscriptions for recurring monthly charges.

Base URL: https://payments.audit1.com/api/v1 — every endpoint on this page lives there. This is a different host from the core Developer API (https://apiv2.audit1.com/api/v2, used for payroll reports, employee sync, and API keys) — that host does not serve payment endpoints, and calling it for /payment-links returns 404.

Payment Links #

Create a Payment Link #

POST /api/v1/payment-links

Fees

Audit1 charges no platform fee on payment links — there is no Audit1 rate to publish. Any amount on top of premium_cents is entirely yours to set via fee_cents; Audit1 never adds to it or takes a cut of it. The customer is charged the two together as one amount: total_cents = premium_cents + fee_cents.

When fee_cents is greater than 0, Audit1 records it and flags it as fee_source: "partner" — on the link, on the payment record, and in the payment.completed webhook — so it's always traceable back to you rather than to Audit1. Use fee_breakdown to itemize what the fee is for; it's stored for your own records but doesn't change how the charge or the webhook fields work.

Payment Context Values

Example: One-Time Payment

curl -X POST https://payments.audit1.com/api/v1/payment-links \
  -H "X-Client-ID: $CLIENT_ID" \
  -H "X-Client-Secret: $CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "employer_id": "681xyz789abc123456789012",
    "carrier_id": "680abc456def789012345678",
    "policy_id": "682def789ghi012345678901",
    "premium_cents": 250000,
    "fee_cents": 5000,
    "payment_type": "ONE_TIME",
    "payment_context": "down_payment",
    "customer": {
      "name": "Smith Industries",
      "email": "ap@smithindustries.com"
    }
  }'

carrier_id may be omitted here — single-carrier keys infer it server-side.

Response (201 Created):

{
  "ok": true,
  "data": {
    "_id": "683abc123def456789012345",
    "stripe_payment_link_id": "plink_1abc2def3ghi...",
    "stripe_url": "https://checkout.stripe.com/c/pay/cs_a1b2c3...",
    "status": "created",
    "billing_entity_type": "employer",
    "total_cents": 255000,
    "link_amount_cents": 255000,
    "installment_plan": null
  }
}

Example: Direct Billing with Installment Plan

curl -X POST https://payments.audit1.com/api/v1/payment-links \
  -H "X-Client-ID: $CLIENT_ID" \
  -H "X-Client-Secret: $CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "employer_id": "681xyz789abc123456789012",
    "carrier_id": "680abc456def789012345678",
    "policy_id": "682def789ghi012345678901",
    "premium_cents": 1200000,
    "fee_cents": 50000,
    "payment_type": "DIRECT_BILLING",
    "payment_context": "down_payment",
    "total_installments": 10,
    "down_payment_months": 3,
    "customer": {
      "name": "Smith Industries",
      "email": "ap@smithindustries.com"
    }
  }'

carrier_id may be omitted here — single-carrier keys infer it server-side.

This creates a payment link for the calculated down payment portion. After the insured pays, a monthly subscription is automatically created for the remaining installments.

Response (201 Created):

{
  "ok": true,
  "data": {
    "_id": "683abc123def456789012345",
    "stripe_payment_link_id": "plink_1abc2def3ghi...",
    "stripe_url": "https://checkout.stripe.com/c/pay/cs_a1b2c3...",
    "status": "created",
    "billing_entity_type": "employer",
    "total_cents": 1250000,
    "link_amount_cents": 312500,
    "installment_plan": {
      "total_installments": 10,
      "down_payment_percentage": 25,
      "down_payment_cents": 312500,
      "per_installment_cents": 93750,
      "extra_fee_cents": 0
    }
  }
}

List Payment Links #

GET /api/v1/payment-links?carrier_id=...&employer_id=...&status=created&page=1&limit=50

Get a Payment Link #

GET /api/v1/payment-links/{id}

Cancel a Payment Link #

DELETE /api/v1/payment-links/{id}

Deactivates the link on Stripe and marks it as cancelled in the database. Cannot cancel a link that has already been paid (use refund instead).

Refund a Payment #

POST /api/v1/payment-links/{id}/refund

Refunds are tracked as refunded_cents on the payment record, with individual refund entries in a refunds array. Multiple partial refunds are supported.

Simulate a Completed Payment (Sandbox) #

POST /api/v1/payment-links/{id}/simulate-completion

The fastest way to test your integration end to end: mark a sandbox payment link as paid without a real card and without waiting for anyone to click through checkout. This is not a mocked copy of an event — it drives the exact same completion path a real Stripe payment does, and fires the exact same, correctly-signed payment.completed webhook to your registered endpoints.

Sandbox keys only. Call it with a live key and you get 403 Forbidden ("Completion simulation is available for sandbox keys only"). Only links created with a sandbox key exist to be simulated in the first place, so this can never touch real money.

It takes no parameters. Send an empty body — the endpoint always simulates the link's full total_cents being paid.

curl -X POST https://payments.audit1.com/api/v1/payment-links/683abc123def456789012345/simulate-completion \
  -H "X-Client-ID: audit1_test_cli_your_id_here" \
  -H "X-Client-Secret: audit1_test_sec_your_secret_here" \
  -H "Content-Type: application/json" \
  -d '{}'

✓ Response

{
  "ok": true,
  "data": {
    "_id": "683abc123def456789012345",
    "status": "paid"
  }
}

Calling it again on a link that's already paid is a safe no-op — you get the same response back (with already_paid: true added) instead of an error or a second webhook delivery.

Register a webhook endpoint before you simulate a completion, or there's nothing listening for the event — see Payment Webhooks.

Subscriptions #

Standalone subscriptions for recurring monthly charges. Requires the employer to already have a Stripe customer (created automatically when a payment link is first created for that employer).

Create a Subscription #

POST /api/v1/subscriptions

The billing interval is always month (monthly). The payment_method_id is set as the default payment method on the Stripe customer.

List Subscriptions #

GET /api/v1/subscriptions?carrier_id=...&status=active&page=1&limit=50

Get a Subscription #

GET /api/v1/subscriptions/{id}

Cancel a Subscription #

DELETE /api/v1/subscriptions/{id}

Cancels the subscription on Stripe and marks all remaining scheduled payments as cancelled.

Payment Link Statuses #

Refunds do not change the payment link status. Refund amounts are tracked separately via refunded_cents on the associated payment record.

Subscription Statuses #

Installment Plan Fields #

When payment_type is DIRECT_BILLING, the response includes an installment_plan object:

The link_amount_cents in the response is the down payment amount (what the initial link charges). The remaining balance is collected via the auto-created subscription.

All monetary values are in cents. $1,500.00 = 150000. This avoids floating-point precision issues.