# Payments import Image from 'next/image'; Overview [#overview] The Socotra Payments system handles all aspects of payment management in conjunction with an external payment gateway that executes the actual financial transaction with a financial institution or payments service provider. It consists of the following components: * **Payments**, which are the actual entity that records the creation, posting, etc. for insureds' payments * **Financial Instruments**, which are saved payment methods and references at the [Account](/features/accounts) level. Insureds may have a number of credit cards, bank accounts, etc. saved, and any of these can be used as a reference when creating payments. * **External Cash Transactions**, which are a record of a particular financial transaction that results in funds flowing into the system. Each payment stores information in an external cash transaction, which in turn may reference a financial instrument if it was used for the payment. * **Payment Distribution**, which contains data about the targets to which the payment is applied. * **Payment Reversals**, which may exist when a payment fails and must be unallocated due to error, non-sufficient funds, etc. * **Payment Requests**, which are generated as part of the AutoPay process to manage initiation and error handling for pre-scheduled payments. Like other configurable entities, payments can be extended with [extension data](/configuration/data-extensions/overview). Automation for payment handling is detailed in the [Autopay](/features/billing/autopay) and [Payment Execution Service](/features/billing/payment-execution-service) topics. Payment State Flow [#payment-state-flow] Payments have a typical state flow from `draft`, to `validated`, and then `posted`. * Only `draft` payments may be edited. * `validated` payments may be reset back to `draft`, where they can once again be edited. * Once posted, payments may become `reversed`. * If they haven't yet been posted, they may be `discarded`. When the payment is `posted`, an accounting transaction will be created to debit Cash and credit the payment itself. Then the payment will be distributed, debiting the payment and crediting individual payment target. When the payment reaches `posted` state, it will be distributed based on its targets. Targets can be either specific invoices, invoice items, or an account, and each target can have a specified `amount`. See [payment-distribution](#payment-distribution), below. The state flow includes other states that are used in [autopay](/features/billing/autopay) and [automatic payment execution](/features/billing/payment-execution-service). The full flow looks like this: payment state flow Financial Instruments [#financial-instruments] Accounts have an array of financial instruments, each of which can store information like: * `externalIdentifier` to store a lookup ID or token for data in an external system * `institutionName`, for the credit card or bank name * `instrumentType`, such as `checking`, `savings`, `creditCard`, etc. * `defaultTransactionMethod`, such as `eft`, `ach`, `cash`, etc. * `externalAccountNumber` * `accountLocator` * `nickname`, for human identification of the instrument when selecting from a list * `expirationTime`, an optional time Payments can optionally reference specific financial instruments or use the account's default instrument upon creation. External Cash Transactions [#external-cash-transactions] Payments are not directly associated with financial instruments. If a payment references a financial instrument, this reference is reflected within the associated external cash transaction. An external cash transaction is generated upon the creation of each payment. It may store the following information based on the data provided in the payment creation request: * `financialInstrumentLocator` * `transactionMethod`, such as `eft`, `ach`, `cash`, etc. * `transactionNumber`, an optional reference to the external gateway's transactions ID The `financialInstrumentLocator` is set to the value from the payment creation request if provided, or the default instrument for the associated account when `useDefaultFinancialInstrument` is set to `true`. The `transactionMethod` is set to the value from the payment creation request if provided, or the associated financial instrument's default method, or `standard` if there is no associated financial instrument. Payment Distribution [#payment-distribution] When a payment is ready for distribution, the system will: * Based on the `targets`, find all the unsettled invoice items directly associated with that target. For example, if the target is a specific invoice, it will gather all the unsettled invoice items for that invoice. * Order the invoice items ascending by their `dueTime` (i.e. the `dueTime` of the invoice that contains it.) * If any targets have an amount specified, distribute to these targets up to the amounts, and then distribute any remaining amounts to all targets. * Within each `dueTime` group, order the invoice items by invoice locator. This will tend to fully pay some invoices rather than partially pay all invoices if there's a shortfall. * Create a credit item for each invoice item (with amount equal to the item's unsettled amount) until the amount of the credit is exhausted or no more invoice items remain. * If the total credit is for less than the sum of the items and the last remainder is less than the unsettled amount of the last invoice item that can be paid, the system will apply all of the remaining credit to that invoice item, leaving it not fully settled. * If there are sufficient invoice items, the credit will always be fully consumed, regardless of the granularity of the invoice item amounts. * If there is remaining unapplied credit, the remainder will be transferred the remaining amount to the account's credit balance. After distribution, the payment will always be fully distributed. There is no provision for a "partially distributed" payment. Payments cannot be distributed to [Invoices](/features/billing/invoicing) or [Credit Balances](/features/billing/credit-balances) belonging to other customer accounts. Payment Reversals [#payment-reversals] A payment may be reversed. It can't be reversed more than once, and there isn't a notion of “reversing the reversal.” If a payment was reversed in error, it will have to be recreated. Payments that have been reversed can have an optional `reversalReason`, which can be set to a value to document the context of the reversal, including whether the insured was at-fault for the payment being reversed. When a payment is reversed, the system will offset all of the payment items associated with the payment with the addition of equal-and-opposite payment items associated with the reversal. Similar offsetting will claw back any amounts from the payment to credit balances. This could cause the credit balance to become negative. Reversal could cause invoices that were settled to become unsettled, and potentially initiate delinquency if the invoice's due time is in the past. If there is a delinquency that is caused by the reversal, the clock will start as of the time of the reversal. The system does not try to determine what *would* have happened if the payment hadn't ever been created. Aggregate Payments [#aggregate-payments] Aggregate payments bring additional flexibility to payment targets, making it possible for a payment to span multiple accounts while still making it easy to trace detailed credit flows through the system. As the name implies, an aggregate payment comprises subpayments. Both aggregate payments and subpayments are payment objects. When creating an aggregate payment, you may specify targets that span accounts, but when you post the aggregate payment, you will see subpayments that in turn distribute to those targets. You cannot create subpayments that you manually add to an aggregate; instead, you rely on the system to create subpayments for you, freeing you to focus on the intended payment distribution. Example [#example] Suppose there are accounts A and B in the system, each of which has a policy with outstanding invoices of $1000. With a received payment of $4000, you opt to settle invoices on both accounts, with the remaining $2000 distributed to account credit balances. You could create and post an aggregate like this: ```json { "amount": 4000, "data": { "payerFirstName": "John", "payerLastName": "Smith", "accountNumber": "1234566", "institution": "Big Bank", "note": "payment" }, "paymentMode": "aggregate", "targets": [ { "containerLocator": "01JQ9ZHGSHX7XCG5HX45SZQ17Y", "containerType": "invoice", "amount": 1000 }, { "containerLocator": "01JQ9ZQ6HYY5VZMWTA0VA4BB75", "containerType": "invoice", "amount": 1000 }, { "containerLocator": "01JQ9ZPCMKTRTBXTHJNQQFTRPA", "containerType": "account", "amount": 1000 }, { "containerLocator": "01JQ9ZGE4HY3BGBDWZGCPZN0ZA", "containerType": "account", "amount": 1000 } ], "type": "StandardPayment" } ``` Which, upon posting, would result in a response like the following - note the creation of subpayments: ```json { "locator": "01JQ9ZZPNFM3WERZVGG7QK2T31", "paymentState": "posted", "type": "StandardPayment", "currency": "USD", "amount": 4000.0, "remainingAmount": 0.0, "data": { "accountNumber": "1234566", "institution": "Big Bank" }, "createdAt": "2025-03-26T19:48:35.119922Z", "createdBy": "dc68c494-6918-487a-bf08-58c2983175dc", "targets": [ { "containerLocator": "01JQ9ZHGSHX7XCG5HX45SZQ17Y", "containerType": "invoice" }, { "containerLocator": "01JQ9ZQ6HYY5VZMWTA0VA4BB75", "containerType": "invoice" }, { "containerLocator": "01JQ9ZPCMKTRTBXTHJNQQFTRPA", "containerType": "account" }, { "containerLocator": "01JQ9ZGE4HY3BGBDWZGCPZN0ZA", "containerType": "account" } ], "externalCashTransactionLocator": "01JQ9ZZPNTHN3GXWGBV41S0C5Q", "postedAt": "2025-03-26T19:48:45.819075301Z", "subpayments": [ { "subpaymentLocator": "01JQA0015BBZ4KK68WVKRTNABN", "amount": 2000.0 // for account A, the sum of the invoice amount and account credit }, { "subpaymentLocator": "01JQA0015HX93NJX29JJV2454W", "amount": 2000.0 // for account B, the sum of the invoice amount and account credit } ], "paymentMode": "aggregate" } ``` Each subpayment record can be examined as a , with all corresponding credit distributions working just as they do for any other payment. See Also [#see-also] * [Autopay](/features/billing/autopay) * [Payment Execution Service](/features/billing/payment-execution-service) * [Payments](/api/billing/payments) * [Financial Instruments](/api/billing/financial-instruments)