action.skip

Billing & Invoice Management/Cash Management Integration

← About Receivables and Payables

Your business can integrate JustOn Billing & Invoice Management with JustOn Cash Management. Use JustOn Billing & Invoice Management to create and manage the invoices for the products and services you sell, and use JustOn Cash Management to manage the related payments, directly connecting Salesforce CRM with German or other European banks as well as payment service providers.

Enabling JustOn Cash Management
JustOn Cash Management

Integration Concepts

The payment functionality shipped with JustOn Cash Management is centered around entries (see Receivables/Payables Concepts). These records hold all information with respect to an amount of money owed to or requested by a business partner, based on statements that justify the corresponding request.

In JustOn Billing & Invoice Management, the produced invoices or – if set up and used – installments represent payment requests. Now integrating JustOn Billing & Invoice Management with JustOn Cash Management provides for both

  • the creation of the relevant entry records directly after the invoice finalization or installment creation/modification, and
  • the creation of the relevant balance records for a registered money flow (where the field Origin is set to JPAY1).

Canceling an invoice in JustOn Billing & Invoice Management will cancel the related entry in JustOn Cash Management.

jpay_jo_integration
Creating entries on invoice finalization or installment creation, creating balances for payments

Note

Integrating JustOn Billing & Invoice Management with JustOn Cash Management will change your workflows.

Payment-related balances produced for a registered money flow in JustOn Cash Management (where the field Origin is set to JPAY1) must not be subject to balance-based business processes like automatic assignment to invoices or balance transfer. To cover these use cases, you manually associate entries with payments in JustOn Cash Management.

Balance Creation

In JustOn Cash Management, registering a money flow for a payment record results in a modified amount value of the payment with a possible settlement to an entry. "Translating" this to JustOn Billing & Invoice Management means to create or update balance records.

In the simplest use case, there are 1:1 relations – one invoice (or installment) makes one entry, and one payment settled with this entry makes one balance record associated to the invoice.

JustOn Cash Management can, however, relate entries with payments in an n:m relationship. This allows, for example, to distribute one money transfer to multiple entries or to settle one entry with multiple money transfers.

The integration with JustOn Billing & Invoice Management provides for the creation of the relevant balances. The system takes the registered payment amount per entry and compares it to the existing payment balance (with Origin = JPAY1) of the original invoice – producing new payment balance records in the amount of the difference, associated to the original invoices or, in case of overpayments or payments without entry settlement, to the related account.

The following examples illustrate this behavior.

Multiple payments for one invoice

# Step Payment Amount Settled Amount per Entry Existing Balances Produced Balances
1 Finalize invoice
I1 100
0 I1: 0
2 Partial payment
P1 80
80 80 I1: 0 I1: Payment P1 -80
3 Partial payment
P2 20
20 100 I1: -80 I1: Payment P2 -20

Multiple payments for multiple invoices

# Step Payment Amount Settled Amount per Entry Existing Balances Produced Balances
1 Finalize invoice
I1 100
0 I1: 0
2 Finalize invoice
I2 100
0 I2: 0
3 Partial payment
P1 180
180 I1: 100
I2: 80
I1: 0
I2: 0
I1: Payment P1 -100
I2: Payment P1 -80
3 Partial payment
P2 20
20 I1: 100
I2: 100
I1: -100
I2: -80
I2: Payment P1 -20

Multiple payments for an invoice with installments

# Step Payment Amount Settled Amount per Entry Existing Balances Produced Balances
1 Finalize invoice
I1 100
4 installments
0
0
0
0
I1: 0
2 Partial payment
P1 80
80 25
25
25
5
I1: 0 I1: Payment P1 -25
I1: Payment P1 -25
I1: Payment P1 -25
I1: Payment P1 -5
3 Partial payment
P2 20
20 25
25
25
25
I1: Payment P1 -25
I1: Payment P1 -25
I1: Payment P1 -25
I1: Payment P1 -5
I1: Payment P2 -20

Overpayment, producing a "free" balance on the account A1

# Step Payment Amount Settled Amount per Entry Existing Balances Produced Balances
1 Finalize invoice
I1 100
0 I1: 0
2 Payment
P1 120
120 I1: 100 I1: 0 I1: Payment P1 -100
A1: Payment P1 -20

Data Mapping

Entries hold all information with respect to an amount of money owed to or requested by a business partner. The entries' data is based on invoice data or on installments data and, if applicable, on already received payments. If a payment plan is modified after the invoice finalization producing new installments, the existing entry records are deleted, and new entry records are created accordingly.

The following fields are set on entry creation:

Data Category Entry Field Invoice Source Field Installment Source Field Default Value/Notes
General Type Debit for positive amount
Credit for negative amount
Title Invoice: custom label with invoice number
Installment: custom label with title and invoice number
Payment Reference String built as defined in the Payment Reference field of the template, see Configuring Payment Reference Text
Business Entity Tenant Invoice__r.Tenant The business entity record in JustOn Cash Management is modified or created on entry record creation using the values given by the invoice.
The given business entity must specify the company name in the Company field because it is required in JustOn Cash Management.
Requests Requested Payment Method PaymentMethod Invoice__r.PaymentMethod
Requested Payment Provider RequestedPaymentProvider Invoice__r.RequestedPaymentProvider Optional lookup to JPAY1__PaymentProvider
Requested Payment Instrument RequestedPaymentInstrument Invoice__r.RequestedPaymentInstrument Optional lookup to JPAY1__PaymentInstrument
Requested Bank Account RequestedBankAccount Invoice__r.RequestedBankAccount Optional lookup to JPAY1__BankAccount
Customer Data BP Number DebtorNo or
Account__r.ON_DebtorNo
Invoice__r.DebtorNo or
Invoice__r.Account__r.ON_DebtorNo
Optional
BP Type Debtor
Account Account Invoice__r.Account
Account Name AccountName Invoice__r.AccountName
Contact EmailContact Invoice__r.EmailContact
Statement Data Statement Type Invoice
Installment
Statement Description
Statement No Name Invoice__r.Name
Invoice Id Invoice Lookup to entry source
Installment Id Lookup to entry source
Statement Distribution URL ContentDistributionUrl Invoice__r.ContentDistributionUrl
Dates Statement Date Date Invoice__r.Date
Statement Payment Due Date NextPaymentDueDate Date
Service Period Start ServicePeriodStart ServicePeriodStart
Service Period End ServicePeriodEnd ServicePeriodEnd
Amount Status Status PaymentStatus OpenOpen
PaidBalanced
Open Amount NextPaymentDue OpenPaymentAmount
Additional Payment Assignment Key PaymentAssignmentKey Unique string used to filter eligible payments

JustOn Cash Management includes a payment page. It provides your buyers the option to pay their purchases (represented as entries) via integrated payment service providers.

In order to invite your buyers to pay, you publish a link to your payment page. This payment link looks like

https://payment.juston.cloud/pay/:link-id/to/:tenant

where :link-id encodes the relevant entries and :tenant represents your organization.

After integrating with JustOn Cash Management, JustOn Billing & Invoice Management retrieves the produced payment links using two batch processes: BatchGetEntryPaymentLinks and BatchGetInvoicePaymentLinks. They are executed on invoice finalization before generating the PDF files, which allows to add the payment links to invoice PDF documents.

To set payment page links on invoice finalization, the following conditions must be met:

  • The requested payment method for the entries must be Online Payment. That is, the entries must have been created for invoices with the payment method Online Payment.
  • There is an active payment provider.
BatchGetEntryPaymentLinks
On invoice finalization, the batch class BatchGetEntryPaymentLinks retrieves the payment page links for all related entries. If an entry is directly related to an invoice, the process writes link to the field Payment Page URL on the invoice. If, however, an entry is related to an installment (see Integration Concepts), the process writes the link to the field Payment Page URL on the installment. Error messages are written to the field Payment Page URL Error.
BatchGetInvoicePaymentLinks

For installment invoices, the entries are related to installments, thus the batch class BatchGetEntryPaymentLinks will not write a payment link to the invoice. So the batch class BatchGetInvoicePaymentLinks generates a combined payment link for all installments related to an invoice and writes the result to the Payment Page URL field on the invoice.

As a result, there is always a payment link on the invoice, either for a single entry if there are no installments, or for all installments of the invoice. If there are installments, each installment will get an individual payment link in addition.

Info

Changing the installments of a finalized invoice will cancel all existing related entries and create new entries based on the new installments. As a consequence, the payment page links on the invoice and installments, which relate to the deleted entries, become invalid and will therefore be deleted and replaced by valid payment links for the new entries.

Payment Processing Data

Entries can define specific information to control how subsequent payment processes are to be executed.

Integrating JustOn Billing & Invoice Management with JustOn Cash Management produces entries from finalized invoices. To enable the payment process control from the produced entries, you need the corresponding Entry fields set on entry creation. This, in turn, requires the information on the invoice and, consequently, as part of the invoice source data – to be transferred to the invoice using the ON field mechanism.

Entry Field Invoice Source Field Notes
Requested Bank Account RequestedBankAccount Restricts the payment process to the current bank account for SEPA transactions.
Requested Payment Instrument RequestedPaymentInstrument Restricts the payment process to the current payment instrument.
Requested Payment Method PaymentMethod Indicates the expected payment method, which is not mandatory for the payer but can control downstream processes.
The picklist values include SEPA, Online Payment and Bank Transfer.
Requested Payment Provider RequestedPaymentProvider Restricts the payment process to the current payment provider.

For details, see Enabling Payment Instrument Handling and Enabling Support for Other Payment Processing Data.

Additional Information

Entries hold relevant information with respect to an amount of money owed to or requested by a business partner. This data is based on a specific set of invoice data or installment data (see Data Mapping). Your business, however, may require to copy additional information from the invoice or installment to the entry for further processing in JustOn Cash Management.

copy_data_inv_entry To this end, JustOn Billing & Invoice Management provides a specific copy mechanism: all additional custom fields on the entry – with the same API name and data type as the source fields on the invoice or the installment – invoke a copy operation on entry creation when finalizing the invoice or modifying installments. Specific field prefixes (like for the ON field mechanism) are not required.

You create the required custom field (for example, CustomInfo) on both the Invoice object and the Entry object. On entry creation, JustOn Billing & Invoice Management will copy the given value from the invoice field to the corresponding field on the produced entry.

Explicitly set entry fields → excluded from copy operation

The integration will set the following fields explicitly when creating entries according to the applied business logic. This is why they will not be copied as additional custom fields:

Entry Field Invoice Source Field Installment Source Field Default Value/Notes
Account Account Invoice__r.Account
AccountName AccountName Invoice__r.AccountName
BPNumber DebtorNo or
Account__r.ON_DebtorNo
Invoice__r.DebtorNo or
Invoice__r.Account__r.ON_DebtorNo
BPType Debtor
Creditor
BusinessEntity Tenant Invoice__r.Tenant
Contact EmailContact Invoice__r.EmailContact
Invoice Id Invoice
OpenAmount NextPaymentDue OpenPaymentAmount
Payment Id
PaymentDate Date of the last associated payment, which sets the entry to Balanced
PaymentReference PaymentReference
RequestedBankAccount RequestedBankAccount Invoice__r.RequestedBankAccount
RequestedPaymentInstrument RequestedPaymentInstrument Invoice__r.RequestedPaymentInstrument
RequestedPaymentMethod PaymentMethod Invoice__r.PaymentMethod
RequestedPaymentProvider RequestedPaymentProvider Invoice__r.RequestedPaymentProvider
ServicePeriodEnd ServicePeriodEnd ServicePeriodEnd
ServicePeriodStart ServicePeriodStart ServicePeriodStart
StatementDate Date Invoice__r.Date
StatementDescription
StatementDistributionUrl ContentDistributionUrl Invoice__r.ContentDistributionUrl
StatementId Salesforce ID of the original invoice/installment
StatementNo Name Invoice__r.Name
StatementPaymentDueDate NextPaymentDueDate Date
StatementType Invoice
Installment
Status Status PaymentStatus OpenOpen
PaidBalanced
Title Invoice: custom label with invoice number
Installment: custom label with title and invoice number
Type Debit for positive amount
Credit for negative amount

For details, see Enabling Additional Information on Entries.

Entry Assignment

Specific integration scenarios with web shops or sales portals may produce entries via the JustOn Cash Management API. In this case, an invoice generated and finalized after the entry has already been created must not trigger the creation of a new entry but "find" the existing one.

To this end, JustOn Cash Management provides the assignment key on entries, and JustOn Billing & Invoice Management supports the entry assignment key on invoices. With the same key, the system will associate an existing entry with a new invoice.

pp_entry_asskey

Info

If the open amount of the assigned entry is smaller than the invoice total, JustOn Billing & Invoice Management creates a correction entry to cover the remaining invoice amount.

If the open amount of the assigned entry is larger than the invoice total, JustOn Billing & Invoice Management applies the overpayment mechanism.

The entry may already be paid – or settled – before the invoice creation. This means, there is a payment linked to the entry via an entry item. Based on this registered payment, JustOn Billing & Invoice Management creates a payment balance (see Balance Creation) and associates it with the corresponding account (because there is no invoice yet). Now creating and finalizing the invoice not only relates the invoice with the existing entry using the assignment key, but also associates the existing payment balance on the account with the invoice (using BatchAssignBalancesHelper as part of the FinalizeInvoiceChain – the invoice checkbox ON_NoAutoBalanceAssignment is ignored in this case). If the registered payment amount covers the open amount of the invoice, the invoice becomes immediately Paid.

pp_entry_asskey_balance

For details, see Enabling Entry Assignment.