Jump to Content

Payment Links & Subscriptions

Create hosted payment links and recurring subscriptions

💳 Payment Links & Subscriptions

Create hosted payment links for one-time charges and subscriptions for recurring installments.

Payment Links

Create a Payment Link

POST /api/v1/payment-links

Field	Type	Required	Description
`employer_id`	string	Yes	Employer ObjectId
`carrier_id`	string	Yes	Carrier ObjectId
`policy_id`	string	Yes	Policy ObjectId
`amount_cents`	integer	Yes	Amount in cents ($1,500.00 = `150000`)
`payment_type`	string	Yes	`down_payment`, `late_payment`, `extra_payment`, `installment`
`customer.name`	string	No	Insured business name
`customer.email`	string	No	Email to receive the payment link
`customer.phone`	string	No	Phone number
`installment_plan.count`	integer	No	Auto-create subscription after down payment
`installment_plan.interval`	string	No	`monthly` (default)
`installment_plan.per_installment_cents`	integer	No	Amount per installment
`metadata`	object	No	Custom key-value pairs

curl -X POST /api/v1/payment-links \
  -H "X-Client-ID: $CLIENT_ID" \
  -H "X-Client-Secret: $CLIENT_SECRET" \
  -d '{
    "employer_id": "681xyz789abc123456789012",
    "carrier_id": "680abc456def789012345678",
    "policy_id": "682def789ghi012345678901",
    "amount_cents": 250000,
    "payment_type": "down_payment",
    "customer": {
      "name": "Smith Industries",
      "email": "[email protected]"
    },
    "installment_plan": {
      "count": 10,
      "per_installment_cents": 75000
    }
  }'

This creates a payment link for a $2,500 down payment. After the insured pays, a monthly subscription is automatically created for 10 installments of $750.

List Payment Links

GET /api/v1/payment-links?carrier_id=...&employer_id=...&status=active&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 so it can no longer be used for payment.

Refund a Payment

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

Field	Type	Required	Description
`amount_cents`	integer	No	Partial refund amount (omit for full refund)
`reason`	string	No	Refund reason

Subscriptions

Create a Subscription

POST /api/v1/subscriptions

Field	Type	Required	Description
`employer_id`	string	Yes	Employer ObjectId
`carrier_id`	string	Yes	Carrier ObjectId
`policy_id`	string	Yes	Policy ObjectId
`amount_cents`	integer	Yes	Amount per billing period
`interval`	string	No	`monthly` (default) or `quarterly`
`customer.name`	string	No	Insured business name
`customer.email`	string	Yes	Email for invoice delivery

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}

Payment Statuses

Status	Description
`active`	Payment link is live, awaiting payment
`completed`	Payment received
`expired`	Link expired without payment
`cancelled`	Manually cancelled
`refunded`	Full refund issued
`partially_refunded`	Partial refund issued

Subscription Statuses

Status	Description
`active`	Billing on schedule
`past_due`	Payment failed, retrying
`cancelled`	Manually cancelled
`completed`	All installments paid

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

Updated 1 day ago