Payments/Payouts in JustOn Cash Management

JustOn Cash Management summarizes receivables and payables as entries, based on which you trigger the relevant payment operations. Technically, you process the payments or payouts via

a payment provider integration or
a connected bank account.

Payment/Payout Processing: General Concepts

In the context of payment or payout processing, the following objects are important:

Payment

JustOn Cash Management uses payment records to track a money transfer and its status, see Payment Lifecycle.

Refund

Businesses can refund received payments – partially or completely – usually as the result of some corrections. JustOn Cash Management uses refund records to track returned money that is related to a previously received payment.

Payment Notification

A payment notification represents updates (through Webhook notifications, for example) for payments and refunds processed via a payment provider.

Bank statement item

A bank statement item represents the recorded money transfer operation for a payment processed via a bank using EBICS.

Bank statement

A bank statement represents the daily summary of bank statement items for one bank account.

JustOn Cash Management can retrieve banking data up to the day before the current date.

In addition, the following objects are relevant to hold the data that is required for processing collections and payouts:

Business entity

The business entity represents the legal entity or organization "doing business".

Payment instrument

A payment instrument holds online payment, credit card or bank account information, which is used for the automatic payment collection or SEPA payment order export.

Payment provider

The payment provider represents a service provider that executes collections and payouts (accepts and processes payment operations) on behalf of the business entity.

Bank account

Bank account records hold all relevant information on actual bank accounts, through which business entities can execute EBICS-based transactions.

EBICS bank account credential

The EBICS bank account credential wraps your EBICS-based bank access. These records hold the credentials and parameters that are required for interacting with banks via EBICS.

By default, an EBICS bank account credential record is locked to the user who has created it. This prevents other users from changing and using the relevant bank access configuration. Optionally, users who have created them can share EBICS bank account credential records with other users.

For an overview of all objects that are relevant for JustOn Cash Management, see Object Model.

Payment Lifecycle

Payment records track money transfer operations that take place in external systems – banks and payment service providers (PSP). The integration makes sure that externally recorded operations are "translated" to the Payment data model, resulting in updates to the status and amount values. JustOn Cash Management operates on the payment records, which allows to separate the integration from the business logic.

pay_app_pay_norm

Payment Types

Depending on the intended operation – settling receivables or payables –, payments can be of two types:

Payment – intended to settle receivables, recorded amounts with this respect are negative values
Payout – intended to settle payables, recorded amounts with this respect are positive values

Payment Statuses

According to the payment operation phases, the payment status changes:

Payment Phase	Payment Status	Description
Preparation No interaction with the bank or PSP	`Open`	Customer has interacted with the payment page
	`Canceled`	Business or customer have canceled the payment operation
Capture Request to the bank or PSP is sent, money has not been collected yet	`Pending`	Request has been sent to the PSP
	`Issued`	Request has been sent to the bank
	`Canceled`	Business or customer have canceled the payment operation
	`Rejected`	Payment has not been accepted by the PSP or bank
Collection Money has been received	`Collected`	Money has been moved from the debtor to the business' bank account or from the business' bank account to the creditor
Late Changes Refunds and chargebacks may take place	`Reversed`	A chargeback over the complete amount has taken place
	`Refunded`	A refund over the complete amount has taken place
Sunset No changes to the payment expected	`Final`	The payment is no longer subject to changes. Future refund operations must be tracked using a new payment record.

Matching and Settlement Statuses

Payments are subject to settlement operations. According to the taken path and its outcome, payments can have various states with this respect – as kept in the field Matching Result.

Matching Result	Description
`Account matched`	JustOn Cash Management has found a matching account, but has not completed the settlement. A user must proceed to manually settle the payment.
`Entry matched`	JustOn Cash Management has found a matching entry, but has not completed the settlement. A user must proceed to manually settle the payment.
`Manually settled`	A user has settled the payment manually.
`Payment Id matched`	JustOn Cash Management has found a matching payment based on a unique ID but the current transaction involves an amount with a reversed sign. Usually, this indicates a chargeback.
`Settled by Payment Id`	JustOn Cash Management has completed the settlement based on a matching unique ID.
`Settled by automatic match`	JustOn Cash Management has completed the settlement through data comparison based on active matching configurations.
`Unmatched`	JustOn Cash Management has not found any matching data. A user must review the matching configurations and repeat the automatic settlement, or proceed to manually settle the payment.
`Unmatched, multiple results`	JustOn Cash Management has found multiple possible matches for different accounts or business entities. A user must review the matching configurations and repeat the automatic settlement, or proceed to manually settle the payment.

Payment Amount Values

With respect to the payment lifecycle, the following amount values are important:

pay_app_payment_amounts

Amount Type	Description
Open Amount	Shows the amount to be moved, corresponds to the `Open Amount` of the entry. Negative values are payments, positive values are payouts.
Collected Amount	Shows the amount of the collected payments. Negative values are payments, positive values are payouts. `Collected Amount <= Open Amount`
Assigned Amount	Shows the amount assigned to one or more entries (via one or more entry items) used to settle them. Technically, this is a roll-up summary over the `Effective Amount` values of all associated entry items.
Available Amount	Shows the amount available for being assigned to an entry. The value depends on the payment status. `Open`, `Canceled`, `Reversed`, `Refunded` → `0` `Pending`, `Issued` → difference between `Open Amount` and `Assigned Amount` `Collected`, `Final` → difference between `Collected Amount` and `Assigned Amount`
Initial Amount	Shows the original amount. Negative values are payments, positive values are payouts (see Payment Types). The initial amount never changes.
Refunded Amount	Shows the sum of any refunded amounts (positive values) for payments of the type `Payment`. Technically, this is a roll-up summary over the `Refunded Amount` values of all associated refunds. `Initial Amount + Refunded Amount = Open Amount`

Entry and Payment Lifecycle gives an outline view of how these values change as payment and settlement progress.

Refund

Some use cases require merchants or service providers to return money to their customers, like preventing fraud attempts, undoing duplicate or disputed payments, answering specific customer requests, or preventing money laundering attempts. In these cases, businesses refund received payments – either partially or completely. In JustOn Cash Management, specific refund records track money being returned to a payer in connection with a previously received payment using the same payment instrument.

As payments do, refund records track money transfer operations that take place in banks and payment service providers (PSP). The integration makes sure that externally recorded operations are "translated" to the Refund data model, resulting in updates to the status and amount values. JustOn Cash Management operates on the refund records, which allows to separate the integration from the business logic.

Refunds can take place

on initialization by a payment service provider for payments processed by them
using SEPA Credit Transfer based on a credit balance

Refund Statuses

In accordance with the refund operation phases, the refund status changes:

Refund Phase	Refund Status	Description
Preparation Money has been blocked from the related payment record	`Prepared`	Refund has been created through credit balance strategy or user interaction
Approval User or automated process has approved the refund	`Approved`	Refund has been approved and is ready for payout
Capture Request to bank or PSP is sent, money has not been collected yet	`Pending`	Request has been sent to the bank or PSP
	`Failed`	Payout has not been accepted by the bank or PSP
Collection Money has been sent	`Refunded`	Money has been moved to the customer
Late Changes Payment errors may take place	`Failed`	Payment error has occurred

Refund Amount Values

For refunds, the following amount values are relevant:

Amount Type	Description
Open Amount	When initialized, shows the amount to be moved. Is always a positive value.
Refunded Amount	Indicates the actually moved amount. Matches the `Open Amount` if the refund operation has been executed successfully, otherwise, is `0`.

Info

While processing the refund, JustOn Cash Management will reduce the Open Amount and the Collected Amount of the related payment (see Payment Amount Values) in accordance with the refunded amount.

Payment Instrument

A payment instrument is a SEPA mandate, a credit card handle or an online payment handle. It allows the business entity to collect or pay out money from or to a customer via a connected bank account or a payment provider integration, respectively.

Payment instruments can explicitly allow or restrict an incoming or outgoing (from the business's perspective) money flow. This way, your accounts can have dedicated payment instruments for debits, credits or refunds.

Field	Description
Money Flow Incoming	Money flow restriction for incoming money (→ collecting receivables), can be `unrestricted` (default) or `disallowed`
Money Flow Outgoing	Money flow restriction for outgoing money (→ settling payables or return claims), can be `unrestricted`, `refund-only` or `disallowed`

To indicate the "health status", JustOn Cash Management saves the last captured amount and the corresponding timestamp to a payment instrument.

Field	Description
Last Capture Amount	The amount to be captured, is set on direct debit/credit transfer job or on payment initialization via payment provider
Last Capture Time	The timestamp of the last initialized capture event, is set on direct debit/credit transfer job or on payment initialization via payment provider
Last Successful Capture Amount	The captured amount, is set on successful collection (end-to-end matching for SEPA payments or success message from PSP)
Last Successful Capture Time	The timestamp of the last successful capture event, is set on successful collection (end-to-end matching for SEPA payments or success message from PSP)