Payments

Overview

Warning

Socotra is not a PCI-Compliant system. We recommend you store all information that is subject to PCI compliance requirements on a system dedicated for this purpose, and in Socotra store only references or tokens that can be used as a lookup key for this data.

The Socotra Payments system handles all aspects of payment management in conjunction with an external payment gateway that executes the actual financial transction 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 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.

Important

Payment Requests and AutoPay will not be available immediately, they are planned for a future release. Contact Socotra if you have questions about scheduling or details for this feature.

Payments

Payments have a state flow from draft, to validated, and then posted. They can be extended with extension data.

  • 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 target. Targets can be either a specific invoice, or an account, and each target can have a specified amount. See Payment Distribution, below.

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, etc

  • 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

When a new payment is created, it may optionally reference to a specific financial instrument, otherwise the default instrument for the account will be selected.

External Cash Transactions

Payments are not directly associated with financial instruments; rather they have an external cash transaction which has the reference. They also can store additional data:

  • transactionMethod, which defaults to the financial instrument’s default method

  • transactionNumber, an optional reference to the external gateway’s transactions id

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 transfered the remaining amount to the account’s credit balance.

Note

After distribution, the payment will always be fully distributed. There is no provision for a “partially distributed” payment.

Important

Payments cannot be distributed to Invoices or Credit Balances belonging to other customer accounts.

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.

Note

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.

See Also