# Insurance payment processing: collect premiums by card

Source: https://fragment.dev/solutions/insurance-payment-processing

## How do you use Fragment for insurance payment processing?

Use Fragment for insurance payment processing when a policyholder pays an approved premium installment by card. Embedded checkout collects the payment, and the Payment Type records settlement and fees. Keep the receipt in a prepaid balance until the policy system authorizes the earned-premium allocation.

| Operation | Who handles it? |
| --- | --- |
| Authorize the policy installment and collectible amount | Your application |
| Collect a card payment from the policyholder | Fragment checkout and payments API |
| Post settlement and processing-fee accounting | Fragment, using your Payment Type |
| Apply funding to authorized earned-premium allocation | Your application posts `premium_payment_apply` |

## Set up the Ledger and Payment Account

Use the [Quickstart](/guides/quickstart) to configure your SDK and create a Ledger with the [example schema](/examples/vertical-ai/insurance--claimant-disbursements/schema.json). Use `insurance-billing` as its `ik`. Configure a Payment Account before collecting payments. The schema marks `assets/payments` with `payment: { "enabled": true }`.

- `assets/payments`
- `liabilities/deposits:<id>/available`
- `income/earned-premiums:<id>`
- `expenses/payment-fees`

Collected funds remain a liability until an authorized application entry moves them to income. Processing fees are a separate expense.

| Account | What it tracks |
| --- | --- |
| `assets/payments` | Card receipts less processing fees |
| `liabilities/deposits:<installment_id>/available` | Funds available for this record |
| `income/earned-premiums:<installment_id>` | Recognized income |
| `expenses/payment-fees` | Fragment processing fees |

## Define the Payment Type

Add `premium_payment` to `payments.types` in your Schema. Its `payment.amount` reads the server-approved `amount`. Add the settlement accounting below to these fields; the [complete schema](/examples/vertical-ai/insurance--claimant-disbursements/schema.json) contains both.

```json title="Payment Type fields"
{
  "type": "premium_payment",
  "typeVersion": 1,
  "status": "active",
  "payment": {
    "amount": "{{amount}}",
    "direction": "payin"
  }
}
```

Set `accounting.settled.lines` to these four lines. Fragment supplies `settled_amount` and `fragment_fee_amount`; your application supplies `installment_id`. The policyholder receives credit for the gross amount. The Payment Account receives that amount less the processing fee.

```json title="Settlement lines"
[
  {"key": "settlement", "account": {"path": "assets/payments"}, "amount": "{{settled_amount}}", "system": "payment_settlement_line"},
  {"key": "fee", "account": {"path": "assets/payments"}, "amount": "-{{fragment_fee_amount}}", "system": "payment_fee_line"},
  {"key": "receipt", "account": {"path": "liabilities/deposits:{{installment_id}}/available"}, "amount": "{{settled_amount}}"},
  {"key": "fee-expense", "account": {"path": "expenses/payment-fees"}, "amount": "{{fragment_fee_amount}}"}
]
```

## Create a Payment from your backend

Resolve the approved policy installment, payer, and amount from authenticated application records. Call `createPayment` with a stable idempotency key. Amounts are integer strings in USD cents. Return the Payment to your frontend; keep API credentials on your server.

```typescript title="Create a $100 card payment"
const { createPayment } = await fragment.createPayment({
  ik: 'premium_payment-1-v1',
  ledgerIk: 'insurance-billing',
  type: 'premium_payment',
  typeVersion: 1,
  parameters: { installment_id: '1', amount: '10000' },
});
if (createPayment.__typename !== 'CreatePaymentResult') {
  throw new Error(createPayment.message);
}
return { payment: createPayment.payment };
```

## Embed Fragment checkout in your product

Mount `Checkout` inside `PaymentElements` from `@fragment-dev/payment-elements`. Pass the Payment returned by your backend and the payer's email. The Payment starts in `needs_payment_method`. Your Pay button calls `confirm()` to charge the card.

Checkout flow: your backend creates a Payment, your frontend renders Fragment checkout, and the customer confirms the card. [View the diagram](https://fragment.dev/solutions/insurance-payment-processing#embed-fragment-checkout-in-your-product).

Place checkout in the policy installment screen. Use `onConfirmed` to update that screen. Verify the Payment's settled status on your backend before marking the receipt available.

```typescript title="PaymentCheckout.tsx"
import { Checkout, PaymentElements, type Payment } from '@fragment-dev/payment-elements';
import { PayButton } from './PayButton';

type Props = { payment: Payment; email: string; onConfirmed: () => void };

export const PaymentCheckout = ({ payment, email, onConfirmed }: Props) => (
  <PaymentElements>
    <Checkout
      payment={payment}
      billingDetails={{ email }}
      onConfirmed={onConfirmed}
      onError={(message) => console.error(message)}
    >
      <PayButton />
    </Checkout>
  </PaymentElements>
);
```

Disable the Pay button until checkout can confirm the Payment. Show errors beside the form so the customer can correct their card details.

```typescript title="PayButton.tsx"
import { usePayment } from '@fragment-dev/payment-elements';

export const PayButton = () => {
  const { confirm, canConfirm, isConfirming, isLoading, error } = usePayment();
  return <>
    <button type="button" disabled={isLoading || !canConfirm || isConfirming}
      onClick={() => canConfirm && confirm()}>Pay by card</button>
    {error && <p role="alert">{error}</p>}
  </>;
};
```


## Inspect the allowed entry types

Fragment posts settlement accounting automatically. Your application posts the separate business entry after authorization. Do not submit native settlement entries through `addLedgerEntry`.

### `payment_premium_payment_settled`

Records the gross card receipt and processing fee. Credits the available funds for this record.

### `premium_payment_apply`

Apply funding to authorized earned-premium allocation. The schema rejects an entry that makes available funds negative.

## Apply collected funds after approval

Confirm the policy, payer, installment, and approved premium amount in the policy administration system. After settlement, apply $70 of the $100 receipt to authorized earned-premium allocation. The entry leaves $30 available. Your accounting policy determines the recognition date. Use the [AddLedgerEntry mutation](/examples/vertical-ai/AddLedgerEntry.graphql) with these variables.

```json title="AddLedgerEntry variables"
{
  "ik": "premium_payment_apply-1-v1",
  "entry": {
    "ledger": {
      "ik": "insurance-billing"
    },
    "type": "premium_payment_apply",
    "typeVersion": 1,
    "parameters": {
      "installment_id": "1",
      "amount": "7000"
    }
  }
}
```

## Walk through the expected balances

These diagrams show a $100 card receipt followed by a $70 application, leaving $30 available. The assumed $3 fee illustrates accounting; it is not a pricing quote. Fragment supplies the actual fee. Only `premium_payment_apply` is posted by your application.

<a id="step-1-payment-settled"></a>

### Step 1: payment-settled

[Link to this step](https://fragment.dev/solutions/insurance-payment-processing#step-1-payment-settled)

Amount parameters, in cents: settled_amount=10000, fragment_fee_amount=300. Expected outcome: `posted`.

Expected result: The assets/payments balance increases from 0 to 9,700 USD cents. The available funds balance increases from 0 to 10,000 USD cents. The expenses/payment-fees balance increases from 0 to 300 USD cents.

Entry: `payment_premium_payment_settled`. Posted changes (USD cents):

- `assets/payments`: +9700
- `liabilities/deposits:1/available`: +10000
- `expenses/payment-fees`: +300

Balances after this step (USD cents):

- `assets/payments`: 9700
- `liabilities/deposits:1/available`: 10000
- `income/earned-premiums:1`: 0
- `expenses/payment-fees`: 300

<a id="step-2-funds-applied"></a>

### Step 2: funds-applied

[Link to this step](https://fragment.dev/solutions/insurance-payment-processing#step-2-funds-applied)

Amount parameters, in cents: amount=7000. Expected outcome: `posted`.

Expected result: The available funds balance decreases from 10,000 to 3,000 USD cents. The income balance increases from 0 to 7,000 USD cents.

Entry: `premium_payment_apply`. Posted changes (USD cents):

- `liabilities/deposits:1/available`: -7000
- `income/earned-premiums:1`: +7000

Balances after this step (USD cents):

- `assets/payments`: 9700
- `liabilities/deposits:1/available`: 3000
- `income/earned-premiums:1`: 7000
- `expenses/payment-fees`: 300

## What happens if the card payment fails?

Store the Payment identifier with the policy installment and operation key. A client callback alone does not establish settlement. Recover server-side status when the response is lost.

| Situation | Application behavior |
| --- | --- |
| Card is declined | Keep the receipt unavailable. Let the payer correct checkout or use the documented `retryPayment` flow. |
| Request times out | Recover the operation with its existing key and exact payload. |
| Payment remains processing | Display its pending state and avoid creating a second collection. |
| Payment settles | Use the automatically posted entries; do not post a second receipt. |

## Enforce the application-side input contract

Authorize each application of collected funds against the business record. The balance condition prevents overuse; it does not replace business approval. Bind the payer, Ledger, record, and amount on your server. The [application contract](/examples/vertical-ai/insurance--claimant-disbursements/application-contract.json) records these checks.

| Check | Required behavior |
| --- | --- |
| Ownership | Resolve the record from the authenticated payer's permissions. |
| Amount | Validate positive integer cents against the approved amount. |
| Retry | Reuse each operation's key and exact payload. |
| Concurrent requests | Serialize decisions for the same record and recover in-flight operations. |

## Check the insurance business rules

Confirm the policy, payer, installment, and approved premium amount in the policy administration system. Keep those decisions in the insurance billing operator's application and pass only approved identifiers and amounts to Fragment.

| Situation | Handling |
| --- | --- |
| Coverage activation | The policy system determines coverage. A successful card payment does not independently activate a policy. |
| Premium adjustment | Approve endorsements and revised installments before collecting an additional payment. |
| Accounting scope | This receipt example does not calculate statutory reserves or determine premium-earning policy. |

## Test the checkout and accounting flow

Use a sandbox Ledger and the [documented test cards](/guides/make-payments#testing). Compare actual entries with the [illustrative snapshots](/examples/vertical-ai/insurance--claimant-disbursements/scenarios.json). The snapshots do not execute checkout or prove settlement.

1. Collect through checkout, then apply part of the settled funds after approval.
2. Verify the Payment status, gross receipt, fee expense, and remaining balance.
3. Retry with the same key and verify that the operation does not duplicate its financial effect.
4. Test a decline, a lost response, and concurrent collection requests.

## Sources and companion files

- [Make Payments: Payment Types and embedded checkout](/guides/make-payments)
- [Quickstart: SDK and Ledger setup](/guides/quickstart)
- [Posting Ledger Entries](/guides/post-ledger-entries)
- [Payment schema](/examples/vertical-ai/insurance--claimant-disbursements/schema.json)
- [Illustrative accounting results](/examples/vertical-ai/insurance--claimant-disbursements/scenarios.json)
- [Payment and Ledger Entry request variables](/examples/vertical-ai/insurance--claimant-disbursements/requests.json)
- [Application contract](/examples/vertical-ai/insurance--claimant-disbursements/application-contract.json)