action.skip

Payments/Payouts Concepts

payment_app_intro JustOn Cash Management is a Salesforce app that integrates Salesforce CRM with European banks and payment service providers. The app allows you to trigger payments and track payment information related to your business with customers.

You will be able to prepare and execute payment operations based on your orders, invoices or other statements that involve payments or payouts, as well as to retrieve information on processed payments and to associate it with the corresponding accounts receivable or accounts payable. Broadly speaking, JustOn Cash Management helps reconcile accounts.

Understanding Payments

Businesses sell and purchase products and services. These operations involve payments or payouts – generally, money due to receive from buyers for a sale, or due to pay to suppliers for a purchase. Specific use cases may also involve credits or refunds.

pay_app_payment

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

In this context, 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 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.

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)
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, Refunded0
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.

Payment Provider Integration

JustOn Cash Management can integrate your Salesforce org with payment service providers (PSP) in order to exchange payment information – namely, to provide your buyers the option to pay their purchases (represented as entries) via the payment page.

For details, see Integrating Payment Provider.

Payment Workflow via Payment Provider

In broad strokes, payment requests are processed as follows:

pay_app_pay_process

JustOn Cash Management prepares payment
JustOn Cash Management encrypts the involved entries and publishes the payment page it to the buyer.
Buyer executes payment

The buyer selects a payment service provider or payment method and releases the payment transaction.

JustOn Cash Management creates a Payment record with the status Pending and an Entry Item record with an Expected Amount.

Payment provider captures amount

The payment service provider captures the payment amount in the buyer's bank and notifies JustOn Cash Management about the result.

JustOn Cash Management creates a Payment Notification record that represents the capture result.

  • The Payment Notification record has an Amount value set.
  • The Payment record's Status is set Collected and its Collected Amount is registered.
  • On the Entry Item record, the Expected Amount is deleted and an Assigned Amount value is set – which is transferred to the related Entry record as Assigned Amount.
  • With the Open Amount completely covered, the Entry record's Status is set Balanced.
  • The Payment Notification record has an empty Amount.
  • The Payment record's Status remains or is reset Pending.
  • The Entry Item record keeps or is restored its Expected Amount.
  • The related Entry record's Status remains or is reset Open.
Bank transfers money
The buyer's bank transfers the captured amount to the payment service provider. Subsequently, the payment service provider passes the amount to the merchant's bank.

Info

Collecting payments via PSPs and, consequently, settling the corresponding entries does not involve bank accounts.

The money transfer between the banks does not alter the payment and entry status or the settlement result.

Payment Page

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.

For details, see Configuring Payment Page.

Text Customization

Depending on your requirements, you can modify or translate the texts to be displayed on the payment page. To this end, JustOn Cash Management provides the custom Salesforce object Payment Page Configuration.

Payment page configurations hold customized texts or translations for payment page texts. Once payment page configuration records are available for a given locale, JustOn Cash Management retrieves the texts when loading the payment page.

Additional Pages

Your business may require to publish payment-relevant information that does not "fit" in the text components of the payment page. To support this, you create additional custom pages that are linked with the payment page. You can use this, for example, to attach your terms and conditions.

JustOn Cash Management implements support for custom pages using the Salesforce object CMS Page. Once CMS Page records are available for a given locale and set Active, JustOn Cash Management produces a list of links to these custom pages in the payment page footer when loading the payment page.

Clicking a link opens the page in a modal window. Closing this window returns the user to the payment page, ready to continue the payment process.

Payment Run

Payment providers may offer support for pre-authorized, merchant-initiated payment transactions – provider-specific means to pre-authorize and execute recurring charges (or other subsequent payments) without the need to repeatedly prompt customers for interaction.

Info

Usually, merchant-initiated transactions are specifically negotiated with and provided by payment service providers. Contact your PSP for details.

JustOn Cash Management can make use of merchant-initiated transactions, executing payment runs in order to automatically collect payments on a regular basis. To this end, JustOn Cash Management provides the dedicated Apex class PaymentRunJob, which is to be scheduled using the standard Salesforce Schedule Apex functionality. For details on setting up the payment run, see Configuring Payment Run.

For the payment run to work, it requires an eligible payment instrument as well as an eligible and capturable entry.

Eligible Entries

Entries must meet the following conditions to be eligible for being captured using the payment run:

Field Description
Account The associated account for the debtor
Payable Amount The amount to be captured, which must be non-zero
Statement Payment Due Date The payment due date of the statement, that is, the agreed collection date, which must be before or the same as the current date
Status The status of the entry, must be Open
Requested Payment Method The requested payment method for the entry, must be empty or Online Payment
Requested Payment Instrument The payment instrument to be used for paying the entry (optional, see Capturable Entries)
Requested Payment Provider The payment provider to be used for paying the entry (optional, see Capturable Entries)
Exclude From Payment Run Indicator to exclude the entry from the payment run, must be false
Eligible Payment Instruments

Payment instruments must meet the following conditions to be used for capturing an entry:

Field Description
Type The type of the payment instrument, must be Online Payment
Is Active Indicator that shows whether the payment instrument is active, must be true
Payment Provider Is Active Indicator that shows whether the connected payment provider is active, must be true
Money Flow Incoming Money flow restriction for incoming money (→ collecting receivables), must be unrestricted for the payment instrument to be used to capture entries with a positive payable amount
Money Flow Outgoing Money flow restriction for outgoing money (→ settling payables or return claims), must be unrestricted for the payment instrument to be used to capture entries with a negative payable amount
Business Entity The payment instrument can only be used to capture entries that relate to the same business entity
Capturable Entries

The payment run will ignore entries that are not capturable. For entries to be capturable, they must be both eligible and associated to an eligible payment instrument.

JustOn Cash Management determines the payment instrument to be used applying the following criteria:

  • If the entry has the Requested Payment Instrument field set, JustOn Cash Management selects the specified payment instrument from the eligible payment instruments. If the specified payment instrument is not eligible, the entry is not capturable.
  • If Requested Payment Instrument is not set but, instead, the Requested Payment Provider field, JustOn Cash Management selects an eligible payment instrument that is related to the given payment provider. If it is not possible to select a payment instrument this way, the entry is not capturable.
  • If neither field is set, JustOn Cash Management selects an eligible payment instrument from the payment instruments based on the account related to the entry. If it is not possible to select a payment instrument this way, the entry is not capturable.
Capture Results

Capturing entries using the payment run may yield one of the following results, respectively:

Success
The requested amount has been successfully captured from the payment provider. JustOn Cash Management has created a payment record with the status Collected, and has fully settled the entry.
Delayed
The payment provider has accepted the request and will return the final result later – which may be a success or a failure. JustOn Cash Management has created a payment record with the status Pending, and has set the Expected Amount on the entry.
Temporary Failure

The communication with the payment provider has failed. JustOn Cash Management has created a payment record with the status Rejected, and will retry to capture the entry on the next payment run execution.

If a payment provider causes too many (by default, 10) temporary failures in consecutive payment runs, JustOn Cash Management will deactivate it. Administrators can define the deactivation threshold according to their org's requirements.

The following example – assuming a retry threshold of 10 – illustrates the behavior.

Payment Run Execution Capture Result Failure Count PSP Active
1 Success 0
2 .. 4 Temporary Failure 3
5 Success 0
6 .. 15 Temporary Failure 10

After JustOn Cash Management has deactivated the payment provider (according to the retry threshold and the number of communication failures), administrators must manually reactivate the payment provider.

Permanent Failure

The system has reported an issue with either the entry or the selected payment instrument.

  • Entry – The entry is considered invalid, for example because of an exceeded amount value or a mismatching currency. In this case, JustOn Cash Management creates a payment record with the status Rejected, and excludes the entry from future payment run executions (selecting the checkbox Exclude From Payment Run). The exclusion reason is specified in the Payment Run Exclusion Reason field.
  • Payment Instrument – The payment instrument has been rejected by the payment provider, for example because of an invalid credit card number. In this case, JustOn Cash Management creates a payment record with the status Rejected, and excludes the payment instrument from future capture attempts within the same or future payment run excutions (deselecting the Is Active checkbox). The deactivation reason is specified in the Deactivation Reason field.
Payment Run Notifications

JustOn Cash Management can inform customers about the produced payment run result. To this end, it makes use of the messaging mechanism based on customer notifications.

In the payment run context (where Business Process is set to Payment Run), JustOn Cash Management currently supports notifications for the following events:

Paymnent Run Result Notification Condition Description
No active payment instrument Payment Invitation The amount of the related (eligible) entry cannot be captured or paid because there is no active payment instrument.
Success Payment Successful
Payout Successful
The amount of the related entry has been successfully captured or paid, respectively, using the related payment instrument.
Entry failure Payment: Entry Excluded
Payout: Entry Excluded
The amount of the related entry could not be captured or paid because of errors in the entry, which is therefore excluded from further payment runs.
Payment instrument failure Payment: Payment Instrument Deactivated
Payout: Payment Instrument Deactivated
The amount of the related entry could not be captured or paid because of errors in the related payment instrument, which is therefore deactivated.

JustOn Cash Management stores the actual messages produced during the payment run with the relevant records:

  • Messages produced when no active payment instrument is found are saved to the corresponding (eligible) entry's Last Notification field. In addition, JustOn Cash Management creates a payment link and saves it to the entry's field Payment Link field.
  • Messages produced on successful capture or because of an entry failure are saved to the corresponding entry's Last Notification field.
  • Messages produced because of a payment instument failure are saved to the corresponding payment instrument's Last Capture Notification field.

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 laudering 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. For payments facilitated by a payment service provider, the provider is the leading system. Any modifications to the payment will synchronize with JustOn Cash Management, updating both payment and refund records accordingly.

Currently, JustOn Cash Management supports refunds in response to payments made via Adyen only. For details on initializing a refund via the Adyen dashboard, see Refund a payment.

Usually, PSPs place refund requests in a queue for processing, which may take some time. Once executed, JustOn Cash Management will be notified via a webhook. Subsequently, JustOn Cash Management creates a refund record, with the Open Amount in accordance with the refunded payment (see Refund Amount Values). In addition, 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.

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.

With respect to refunds via Adyen, the possible responses ("webhook events") are mapped to the refund statuses as follows:

Webhook Event Refund Status Adyen Description
REFUND and
success = true
Refunded Adyen's validations were successful and we got the refund request to the card scheme.
REFUND and
success = false
Rejected Adyen's refund validations failed.
REFUND_FAILED and
success = true
Failed This can happen a few days after the refund request was submitted: the card scheme can still reject the refund.
REFUNDED_REVERSED and
success = true
Reversed This can happen for some payment methods, for example, if the shopper's bank account is no longer valid and the funds have been returned to Adyen

Connected Bank Account

JustOn Cash Management directly integrates Salesforce CRM with European banks. Using the secure, EBICS-compliant connection, businesses can directly retrieve and upload relevant payment information.

Prior to using the banking connection of JustOn Cash Management, your business must enter into a (usually chargeable) contract on the intended data access with your bank (see Bank Access Requirements). From a technical perspective, you subscribe to an EBICS-compliant service for exchanging payment information. Hence you may be referred to as the subscriber, with your bank as the other contract party.

How does the EBICS initialization take place?

Generally, EBICS initialization means exchanging public keys: You send your public subscriber keys to your bank, and your bank sends their public bank keys to you. Using the keys, you and your bank can then verify that any sent information – signed using the keys – is genuine.

The initialization procedure includes the following artifacts and procedure steps:

(1) EBICS access information and printed public bank keys

pay_app_init_bank1

After your organization has requested EBICS access, your bank sends a user letter to you. It includes the user data and other relevant access information for you to create the bank access.

The printed public bank keys are often published on the bank's website or are part of the user letter.

Some banks return a confirmation letter that includes the printed public bank keys only after they have verified your public subscriber keys (step 4).

(2) Electronic public subscriber keys

pay_app_init_bank2

As part of the bank access configuration, JustOn Cash Management creates your subscriber keys and transfers the public subscriber key electronically to your bank.

(3) Printed public subscriber keys

pay_app_init_bank3

After adding the bank access, you are prompted to download the initialization letter, which includes your printed public subscriber keys. You send this document to your bank via postal mail or email.

(4) Public subscriber keys validation

pay_app_init_bank4

Your bank compares the public subscriber keys received electronically with the ones sent with the initialization letter.

(5) Electronic public bank keys

pay_app_init_bank6

Now you proceed to validate the public bank keys: This makes JustOn Cash Management fetch the public bank keys electronically.

(6) Public bank keys validation

pay_app_init_bank7

Then you compare the public bank keys received electronically with the printed public bank keys.

Once you confirm the keys' validity, JustOn Cash Management completes the bank access setup. This makes the involved bank accounts ready for the EBICS-based data exchange with your bank.

pay_app_init_bank8

EBICS keys are valid for one year. If the keys are used (for uploading payment orders or retrieving bank statements) within the last 30 days of their validity, JustOn Cash Management automatically renews these keys, making them available for another year. If the expiry date has passed without renewing the keys, JustOn Cash Management disables the bank access, and users must repeat the EBICS initialization.

For details, see Initializing Banking Operations. In addition, consider the banking-related specifics and conditions summarized in Banking Preconditions.

Payment Workflow via Bank Account

This is the typical lifecycle of a SEPA transaction in JustOn Cash Management:

alt text

User starts SEPA order job

JustOn Cash Management validates the input records (business entities, payment instruments, entries).

As a result of the job execution, JustOn Cash Management

  • Creates Payment records with the status Issued
  • Creates Entry Item records with an Expected Amount, which prevents entries from being processed repeatedly
  • Builds SEPA XML files (including a unique end-to-end ID) and sends them to the bank via EBICS (under the EDS class T, see Bank Access Requirements)
Authorized user releases orders

The signature (under the EDS class E or A/B, see Bank Access Requirements) must be given in the banking system.

As a result, the bank processes all payment requests and transfers the money.

User retrieves bank statements

When a matching bank statement item is found (from the original bank account and according to the end-to-end ID), it is automatically associated with the corresponding payment. Consequently, JustOn Cash Management

  • Updates the amount on the Payment record (as related to entries)
  • Sets the payment status to Collected
  • Adjusts the amount on the Entry Item record, which is transferred to the related Entry record as Assigned Amount

For details, see Using Direct Debit and Using Credit Transfer.

Info

Bank statement items may represent bank transfers initiated by customers. These bank statement items do not originate from SEPA orders produced by JustOn Cash Management, which is why they do not have an end-to-end ID known to JustOn Cash Management. In this case, JustOn Cash Management relates the bank statement items (and payments created from them) with entries by data comparison – based on matching data like the customer number or statement number.

That is, JustOn Cash Management can automatically associate

  • existing payment records that originate from SEPA orders (as related to entries) with corresponding bank statement items (from the original bank account and according to the end-to-end ID), or
  • retrieved bank statement items (and corresponding new payment records) that originate from customer-initiated bank transfers with matching entries through data comparison.

For details, see Settlement Approaches.

Eligible entries for SEPA Direct Debit

To collect an entry successfully via SEPA Direct Debit, make sure that the following information is set accordingly:

Field Description
Account The associated account for the debtor
Type The type of the entry, must be Debit
Business Entity Lookup to the related business entity
Must match the business entity of the payment instrument.
Open Amount The overall open amount
For a debit, it must be a positive amount.
Payable Amount The amount to pay (before a related payment is requested)
Must be larger than 0 for the entry to be considered on direct debit order creation.
Statement Date The effective date of the (legally binding) original statement
Statement Payment Due Date The payment due date of the statement, that is, the agreed collection date
Requested Payment Method The requested payment method for the entry, must be SEPA
Using the integration with JustOn Billing & Invoice Management, the value is taken from the invoice, so the invoice payment method must already be set to SEPA.
Requested Payment Instrument Optionally, allows to select a particular active payment instrument according to the selected account. Falls back to the first active payment instrument of the account if empty.
Requested Bank Account Your (the creditor's) bank account – the target of the collection. Falls back to the Preferred Bank Account of the business entity if empty.
Payment Reference Describes the purpose of the payment, a human-readable description for the money transfer. Will be displayed in the bank account statements.

The key date for SEPA transactions is the Statement Payment Due Date of the entry. Entries are eligible if the date is not empty and not beyond the next 14 days from today. If the date is in the past, JustOn Cash Management corrects it to TODAY + 1 for it to be accepted by the bank.

Eligible entries for SEPA Credit Transfer

For an entry to be processed successfully via SEPA Credit Transfer, make sure that the following information is set accordingly:

Field Description
Account The associated account for the creditor
Type The type of the entry, must be Credit
Business Entity Lookup to the related business entity
Must match the business entity of the payment instrument.
Credit Approval (Optional) approval status, used to build approval processes for outgoing money transfers
Must be restricted or approved. Empty values are handled like approved.
Open Amount The overall open amount
For a credit, it must be a negative amount.
Payable Amount The amount to transfer (before a related payout is requested)
Must be less than 0 for the entry to be considered on credit order creation.
Statement Date The effective date of the (legally binding) original statement
Statement Payment Due Date The payment due date of the statement, that is, the agreed payout date
Requested Payment Method The requested payment method for the entry, must be SEPA
Using the integration with JustOn Billing & Invoice Management, the value is taken from the invoice, so the invoice payment method must already be set to SEPA.
Requested Payment Instrument Optionally, allows to select a particular active payment instrument according to the selected account. Falls back to the first active payment instrument of the account if empty.
Requested Bank Account Your (the debtor's) bank account – the source of the payout. Falls back to the Preferred Bank Account of the business entity if empty.
Payment Reference Describes the purpose of the payment, a human-readable description for the money transfer. Will be displayed in the bank account statements.

The field Statement Payment Due Date is used as a reference when selecting entries for credit transfer jobs. Entries are eligible if the date is not empty and not beyond the next 14 days from today, like Statement Payment Due Date <= TODAY + 14d.

About EBICS

The Electronic Banking Internet Communication Standard (EBICS) is a transmission protocol for sending payment information between clients and banks as well as between banks over the Internet. It uses established standards for securely transmitting encrypted data. For details, see EBICS.

All German banks that are associated with the German Banking Industry Committee (Die Deutsche Kreditwirtschaft/DK) support EBICS and therefore allow exchanging payment information using JustOn Cash Management.

JustOn Cash Management supports EBICS 3.0 (Rev. 3.0.2). EBICS 3.0 has introduced standardized Business Transaction Formats (BTF), which allow for working with German and other European banks – including French, Swiss and Austrian banks.

JustOn Cash Management supports CAMT.053 messages (see Bank Access Requirements). That is, it can retrieve banking data for completed bookings up to the day before the current date. Fetching interim transactions during the same day (CAMT.052 messages) is currently not possible.

Important Concepts

Other important concepts related to EBICS-compliant banking operations include

Public bank key
Your bank publishes the public bank key – a string to be used by your JustOn Cash Management instance to decode and encode the encrypted communication. You must validate it as part of the subscriber confirmation before using the bank access.
Subscriber keys

Your JustOn Cash Management instance creates your subscriber keys. The public subscriber key is to be used by your bank to decode and encode the encrypted communication. Your bank must validate it as part of the subscriber initialization.

The EBICS subscriber keys produced by JustOn Cash Management are valid for one year. If the subscriber keys are used (for uploading payment orders or retrieving bank statements) within the last 30 days of their validity, JustOn Cash Management automatically renews these keys, making them available for another year. If the expiry date has passed without renewing the keys, JustOn Cash Management disables the bank access, and users must repeat the EBICS initialization.

About SEPA Direct Debit

The European Payments Council (EPC) has established the single euro payments area (SEPA) to standardize cashless euro payments across Europe. It defines, among others, SEPA Direct Debit schemes (SDD): one primarily designed for B2C businesses (SDD Core), and one exclusively for B2B businesses (SDD B2B). The two schemes set common rules for transferring money from a debtor to a creditor, but vary in details (see SEPA Direct Debit).

SEPA Direct Debit is centered around a mandate, which allows the creditor to prove their request for collecting money. The collection is initiated by the creditor, submitting the order to their bank. The order includes information like mandate ID, amount, collection date and debtor IBAN. The bank then executes the order, withdrawing the money from the debtor's account and putting it to the creditor's account.

The common rules include:

  • The mandate is signed by the debtor before the first transaction (typically 14 days before the first collection).
  • The mandate allows one-off or recurrent collections and can be revoked by the debtor at any time.
  • The due date of a collection must not be more than 14 days in the future.

Depending on the scheme (Core or B2B), various timeframes and rules apply for the debtor to object to the money transfer and to order a reverse transaction.

The SEPA Direct Debit Core scheme is mandatory for transactions with consumers (B2C) and optional for transactions with businesses (B2B). Under SDD Core, a debtor can request a refund ("no-questions-asked") within eight weeks of the collection date. In case of an unauthorized transaction – which must be proven –, a debtor can ask for a refund within 13 months of the collection date.

The SEPA Direct Debit B2B scheme is exclusively for businesses. Under SDD B2B, the debtor is not entitled to obtain a refund for an authorized transaction. The debtor's bank, however, may still return a transaction under certain circumstances within three days. To ensure that a transaction is authorized under SDD B2B, the debtor's bank must check whether there is a valid mandate before executing the collection.

Unless specifically agreed with the bank, JustOn Cash Management uses the basic character set defined by the European Payment Council when creating SEPA payment orders. For details, see SEPA Requirements for an Extended Character Set (UNICODE Subset) - Best Practices.

About SEPA Credit Transfer

The European Payments Council (EPC) has established the single euro payments area (SEPA) to standardize cashless euro payments across Europe. It defines, among others, the SEPA Credit Transfer scheme (SCT). It defines a set of rules, practices and standards to achieve interoperability for SEPA payment instruments between participating banks and payment service providers in 36 European countries.

As opposed to SEPA Direct Debit, SEPA Credit Transfer does not require a mandate. For details, see SEPA Credit Transfer on the EPC website.

The payout is initiated by the debtor, submitting the order to their bank. The order includes information like amount, payout date and creditor IBAN. The bank then executes the order, withdrawing the money from the debtor's account and putting it to the creditor's account.

Unless specifically agreed with the bank, JustOn Cash Management uses the basic character set defined by the European Payment Council when creating SEPA payment orders. For details, see SEPA Requirements for an Extended Character Set (UNICODE Subset) - Best Practices.

SEPA Batch Booking

SEPA Direct Debit and SEPA Credit Transfer allow to combine multiple transactions using a Batch Booking parameter. This setting controls how the combined transactions are displayed on bank statements – usually, batched transactions appear as one bank statement item. Organizations use this option to avoid information disclosure.

Be aware that banks still process batched transactions individually. The subsequent handling does not change: each transaction results in a single payment, whether it is part of a batch or not.

JustOn Cash Management allows for enabling SEPA batch bookings for a specific bank account. The following settings control the behavior:

SEPA Direct Debit Batch Booking

Controls the batch booking mode for direct debit transactions.

Value Description
off No batch booking (default)
on Forced batch booking
SEPA Credit Transfer Batch Booking

Controls the batch booking mode for credit transfer transactions.

Value Description
off No batch booking (default)
on Forced batch booking
Initial Payment Status

Optionally, controls the initial status of the produced payment.

Value Description
Issued Default value, indicates that the request has been sent to the bank, sets open amount
Collected Indicates that the money has been moved, sets both open amount and collected amount

Use Collected as the initial payment status only if your bank does not produce individual transaction records for batch bookings (which would not allow automatic settlement), because this will immediately balance out the related entries.

SEPA Direct Debit Chargebacks

When using SEPA Direct Debit, return debits or other chargeback operations may occur if a direct debit transaction cannot be carried out or is rejected by the debtor. In this case, the debtor's bank will reverse the original direct debit – returning the corresponding amount to the debtor. This produces a credit to the debtor's account and a debit to the creditor's account. Any banking fees will also be charged to the creditor.

JustOn Cash Management uses specific amount fields to indicate the instructed (originally initiated) amount, the transaction amount, cumulated charges and the effective amount on bank statement items.

Field Description
Cumulated Charges Sum of charges that are included in the current banking transaction.
Effective Amount The absolute amount without charges and interests.
If set, will be used for further processing instead of Total Amount.
Instructed Amount The originally initiated amount before charges deduction.
The currency may differ from the reported currency.
Transaction Amount The amount of money moved in the current banking transaction plus internal charges. External charges are not included.

A SEPA Direct Debit chargeback can have different reasons. The following table lists the most common reason codes that you may come across. There are more, however, they are rarely used.

Reason Code Description
AC01 The IBAN is incorrect or unknown.
AC04 The account holder has closed the account.
AC06 Direct debit is not allowed on the account.
AM04 The account has insufficient funds.
MD01 There is no mandate or an invalid mandate.
MD06 The direct debit has been reversed by the account holder.
SL01 The bank refused the direct debit (due to daily limits, for example).

A SEPA Direct Debit chargeback appears as a separate item on the bank account statement. The return reason and any incurred fees are shown separately on the item.

If the original SEPA Direct Debit transaction has used an end-to-end ID, the SEPA Direct Debit chargeback will also have the same end-to-end ID. JustOn Cash Management then uses this ID to identify the originally generated payment and, consequently, sets the payment status to Reversed and withdraws the assigned amount.

Note that the corresponding payment record does not track any fees that may have been incurred. It is the creditor's responsibility to deal with these fees separately.

SEPA Payment Run

JustOn Cash Management can automate the SEPA order creation, executing SEPA payment runs. This allows for automatically initiating payments based on SEPA mandates via the EBICS-based banking connection on a regular basis.

To this end, JustOn Cash Management provides two dedicated Apex classes

  • DirectDebitPaymentRunJob for SEPA Direct Debit, and
  • CreditTransferPaymentRunJob for SEPA Credit Transfer.

These Apex classes are to be scheduled using the standard Salesforce Schedule Apex functionality. For details on setting up the SEPA payment run, see Configuring SEPA Payment Run.

For the SEPA payment run to work, it requires an eligible entry as well as an eligible payment instrument. Generally, the same conditions apply as for the manual SEPA order creation (see Using Direct Debit and Using Credit Transfer).

Eligible entries for SEPA Direct Debit

To collect an entry successfully via SEPA Direct Debit, make sure that the following information is set accordingly:

Field Description
Account The associated account for the debtor
Type The type of the entry, must be Debit
Business Entity Lookup to the related business entity
Must match the business entity of the payment instrument.
Open Amount The overall open amount
For a debit, it must be a positive amount.
Payable Amount The amount to pay (before a related payment is requested)
Must be larger than 0 for the entry to be considered on direct debit order creation.
Statement Date The effective date of the (legally binding) original statement
Statement Payment Due Date The payment due date of the statement, that is, the agreed collection date
Requested Payment Method The requested payment method for the entry, must be SEPA
Using the integration with JustOn Billing & Invoice Management, the value is taken from the invoice, so the invoice payment method must already be set to SEPA.
Requested Payment Instrument Optionally, allows to select a particular active payment instrument according to the selected account. Falls back to the first active payment instrument of the account if empty.
Requested Bank Account Your (the creditor's) bank account – the target of the collection. Falls back to the Preferred Bank Account of the business entity if empty.
Payment Reference Describes the purpose of the payment, a human-readable description for the money transfer. Will be displayed in the bank account statements.

The key date for SEPA transactions is the Statement Payment Due Date of the entry. Entries are eligible if the date is not empty and not beyond the next 14 days from today. If the date is in the past, JustOn Cash Management corrects it to TODAY + 1 for it to be accepted by the bank.

Eligible entries for SEPA Credit Transfer

For an entry to be processed successfully via SEPA Credit Transfer, make sure that the following information is set accordingly:

Field Description
Account The associated account for the creditor
Type The type of the entry, must be Credit
Business Entity Lookup to the related business entity
Must match the business entity of the payment instrument.
Credit Approval (Optional) approval status, used to build approval processes for outgoing money transfers
Must be restricted or approved. Empty values are handled like approved.
Open Amount The overall open amount
For a credit, it must be a negative amount.
Payable Amount The amount to transfer (before a related payout is requested)
Must be less than 0 for the entry to be considered on credit order creation.
Statement Date The effective date of the (legally binding) original statement
Statement Payment Due Date The payment due date of the statement, that is, the agreed payout date
Requested Payment Method The requested payment method for the entry, must be SEPA
Using the integration with JustOn Billing & Invoice Management, the value is taken from the invoice, so the invoice payment method must already be set to SEPA.
Requested Payment Instrument Optionally, allows to select a particular active payment instrument according to the selected account. Falls back to the first active payment instrument of the account if empty.
Requested Bank Account Your (the debtor's) bank account – the source of the payout. Falls back to the Preferred Bank Account of the business entity if empty.
Payment Reference Describes the purpose of the payment, a human-readable description for the money transfer. Will be displayed in the bank account statements.

The field Statement Payment Due Date is used as a reference when selecting entries for credit transfer jobs. Entries are eligible if the date is not empty and not beyond the next 14 days from today, like Statement Payment Due Date <= TODAY + 14d.

Payment instruments must meet the following conditions to be used for the SEPA payment run:

Field Description
Business Entity Lookup to the related business entity
A SEPA mandate cannot be used for different business entities or SEPA Creditor Identifiers.
Account Holder The name of the bank account holder (debtor)
IBAN The bank account number
BIC The SWIFT BIC of the bank account
Required if the debtor's or the creditor's bank is located in non-EEA SEPA countries Andorra, Monaco, San Marino, Switzerland, United Kingdom or Vatican City State.
Bank Name The name of the debtor's bank
Direct Debit Mandate Type The type of the direct debit mandate, either Core or B2B
Direct Debit Mandate Granted The date on which you received the debtor's SEPA mandate
Direct Debit Mandate Reference A unique string that identifies the SEPA mandate
Money Flow Incoming Must be unrestricted, is treated as unrestricted if empty
Type Must be SEPA Mandate (allows for direct debits and credit transfers)

As opposed to SEPA Direct Debit, SEPA Credit Transfer does not require a mandate. Nevertheless, you still need a payment instrument to hold the payment-relevant data for credit transfers.

Field Description
Business Entity The related business entity
Must match the business entity of the entry.
Account Holder The name of the PI holder, used to address the creditor by name
Type Must be SEPA Mandate (allows for direct debits and credit transfers) or Bank Account (allows for credit transfers only)
Money Flow Outgoing Must be refund-only or unrestricted, is treated as unrestricted if empty
IBAN The target bank account
BIC Required if the debtor's or the creditor's bank is located in non-EEA SEPA countries Andorra, Monaco, San Marino, Switzerland, United Kingdom or Vatican City State.
Is Active Must be true

Bank Data Download

Preview feature

Using EBICS, banks provide both machine-readable end-of-day bank statement data to be used for automatic payment reconciliation, as well as human-readable documents for regulatory reasons. JustOn Cash Management can, consequently

  • Request bank statements in the (structured) CAMT.053 format to be used for payment matching and settlement
  • Optionally, request and store bank statements in PDF format
  • Optionally, request and store other bank-related documents (like clearings, account balances, balance confirmations, etc.) in PDF format

Info

To retrieve PDF files, you must specifically request the corresponding EBICS order types with your bank (see Bank Access Requirements).

Once agreed upon with the bank, each EBICS data download involves different files. JustOn Cash Management relates the files to the relevant Salesforce records and, optionally if set up accordingly, saves the files in a dedicated library/folder structure (named by BIC/IBAN) in Salesforce Files.

Bank statement CAMT.053

Contains all relevant information about executed payment transactions in a machine-readable form. JustOn Cash Management parses the provided data and stores the information in bank statements and bank statement items for further processing.

Remember that bank statements contain general information for a fixed period of time – the banking day – like opening balance, closing balance, etc., whereas bank statement items contain detailed information about each bank account transaction like amount, debtor, creditor, etc.

For archival purposes, the downloaded file is assigned to the relevant bank statement and bank account records and, optionally, saved to the corresponding BIC/IBAN folder in Salesforce Files.

Bank statement PDF
Contains all relevant information about executed payment transactions in a human-readable form. JustOn Cash Management relates the PDF file with the relevant bank statement and bank account records and, optionally, saves it to the corresponding BIC/IBAN folder in Salesforce Files.
Other bank information PDF
Can contain other banking-related information (like clearings, account balances, balance confirmations, etc.) in a human-readable form. If the given PDF file is related to a specific bank account, JustOn Cash Management associates it with the relevant bank account record and saves it to the corresponding BIC/IBAN folder in Salesforce files. Otherwise, it is just stored to the relevant BIC library in Salesforce Files.
Transaction ZIP
Contains all files involved in one download transaction. JustOn Cash Management relates the ZIP file with the relevant job record for troubleshooting purposes and, optionally, saves it to the relevant BIC library in Salesforce Files.

For details on the bank data download configuration, see Enabling Bank Statement Download.