Payments Overview | Fragment Docs

A Payments overview#

FRAGMENT lets you make payments that automatically reconcile. A Payment is a Schema primitive alongside Accounts and Entry Types, and it posts the Ledger Entries you defined for it as it moves.

A Payment Account holds the money FRAGMENT holds for you. Settlement and fee lines post to it. Set payment on an asset account in your Chart of Accounts:

fragment/schema.jsonc

{
  "key": "payments",
  "type": "asset",
  "payment": { "enabled": true }
}

A Payment Account must be:

An active asset account.
Single-currency USD.
Strongly consistent, with totalBalanceUpdates set to strong.
Childless, and neither a Template Account nor the child of one.

Each Schema has at most one.

A Payment Type is the reusable definition of one kind of money movement. You declare it in your Schema and deploy it the same way you deploy Accounts and Entry Types:

View the Payment Type JSON

fragment/schema.jsonc

{
  "type": "card_payin",
  "typeVersion": 1,
  "status": "active",
  "payment": {
    "amount": "{{order_amount}}",
    "direction": "payin"
  },
  "accounting": {
    "settled": {
      "description": "Order {{order_id}} settled",
      "lines": [
        {
          "key": "settlement",
          "system": "payment_settlement_line",
          "account": {
            "path": "assets-root/payments"
          },
          "amount": "{{settled_amount}}"
        },
        {
          "key": "fee",
          "system": "payment_fee_line",
          "account": {
            "path": "assets-root/payments"
          },
          "amount": "-{{fragment_fee_amount}}"
        },
        {
          "key": "receivable",
          "account": {
            "path": "assets-root/receivable:{{order_id}}"
          },
          "amount": "-{{settled_amount}}"
        },
        {
          "key": "fee-expense",
          "account": {
            "path": "expense-root/payment-fees"
          },
          "amount": "{{fragment_fee_amount}}"
        }
      ]
    }
  }
}

payment.direction — payin (money in). Payouts (money out) are coming soon.
payment.amount — the amount, parameterized in the same {{param}} style as an Entry Type. Use whole cents as a string; the amount must be between "100" ($1) and "10000000" ($100,000), inclusive.
accounting — the Ledger Entry to post on a lifecycle transition. settled is required, and initiated is optional.

There are now two SDKs for interacting with FRAGMENT: a server side SDK for calling the API, and a frontend SDK for securely collecting card details.

To install the frontend React SDK,

npm install --save @fragment-dev/payment-elements

Read the Checkout section to learn how to embed the SDK in your product.

To install the backend SDK, follow the Quickstart.

A card Payment moves through these states:

State	Meaning
`needs_payment_method`	Created, but no payment method attached yet.
`processing`	Submitted to the rail, outcome not yet known.
`accepted`	Captured by the network and guaranteed to settle.
`settled`	The money has moved.

a. Payment Accounts

b. Payment Types

c. SDKs

d. The Payment state machine