L. Law firm accounting: collect client expense funding by card

For law firm accounting, use FRAGMENT checkout to collect authorized client funding for an expert expense by card. The Payment Type records the receipt and processing fee. Keep funding assigned to the matter's expense authorization, then allocate it to an approved expert invoice with a Ledger Entry.

Use the Quickstart to configure your SDK and create a Ledger with the example schema. Use law-firm as its ik. Configure a Payment Account before collecting payments. The schema marks assets/payments with payment: { "enabled": true }.

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

Add client_expense_funding 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 contains both.

{
  "type": "client_expense_funding",
  "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 authorization_id. The client receives credit for the gross amount. The Payment Account receives that amount less the processing fee.

[
  {"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/funding:{{authorization_id}}/available"}, "amount": "{{settled_amount}}"},
  {"key": "fee-expense", "account": {"path": "expenses/payment-fees"}, "amount": "{{fragment_fee_amount}}"}
]

Resolve the approved matter expense authorization, 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.

const { createPayment } = await fragment.createPayment({
  ik: 'client_expense_funding-1-v1',
  ledgerIk: 'law-firm',
  type: 'client_expense_funding',
  typeVersion: 1,
  parameters: { authorization_id: '1', amount: '10000' },
});
if (createPayment.__typename !== 'CreatePaymentResult') {
  throw new Error(createPayment.message);
}
return { payment: createPayment.payment };

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.

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

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.

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>}
  </>;
};

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

Determine the permitted receiving account and confirm the client's expense authorization before collecting funds. After settlement, apply $70 of the $100 receipt to approved expert invoice. The entry leaves $30 available. Your accounting policy determines the recognition date. Use the AddLedgerEntry mutation with these variables.

{
  "ik": "client_expense_funding_apply-1-v1",
  "entry": {
    "ledger": {
      "ik": "law-firm"
    },
    "type": "client_expense_funding_apply",
    "typeVersion": 1,
    "parameters": {
      "authorization_id": "1",
      "amount": "7000"
    }
  }
}

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 client_expense_funding_apply is posted by your application.

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

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 records these checks.

Determine the permitted receiving account and confirm the client's expense authorization before collecting funds. Keep those decisions in the law firm's application and pass only approved identifiers and amounts to FRAGMENT.

Use a sandbox Ledger and the documented test cards. Compare actual entries with the illustrative snapshots. 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.

1. A 
   Make Payments: Payment Types and embedded checkout
2. B 
   Quickstart: SDK and Ledger setup
3. C 
   Posting Ledger Entries
4. D 
   Payment schema
5. E 
   Illustrative accounting results
6. F 
   Payment and Ledger Entry request variables
7. G 
   Application contract