action.skip

Payment Provider Integration

← About Payments and Payouts

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.

pay_app_pay_page
Example 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.

For details, see Configuring Payment Page.

Payment Automation

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.

Payment Token Storage

To support future payments and the automatic payment collection, JustOn Cash Management can save payment tokens as payment instruments. As part of the payment provider configuration, merchants can enable the option to save payment tokens for future use. The following settings are available:

Option Result
Disabled Payment data will not be saved, no display on the payment page.
Explicit Consent Displays a toggle switch to let buyers decide whether to save payment data or not, preset No.
Buyers must expressly agree to the payment data storage.
Explicit Opt-out Displays a toggle switch to let buyers decide whether to save payment data or not, preset Yes.
Buyers must expressly reject the payment data storage.
Indirect Consent Payment data will be saved when the payment is made, displays a text to inform buyers about this.
Buyers indirectly agree to the payment data storage when making the payment.

Once configured, the payment page exposes the selected option to buyers. The texts to be displayed with each option are configurable:

Context Relevant Text Field Default Value
Explicit consent
Explicit opt-out		 Storage Optional Consent Allow your payment data to be saved and used again for future payments.
Indirect consent Storage Indirect Consent By clicking **Pay** you allow [company] to save and use your payment data for future payments.
Successful data storage Storage Result Heading Payment Data
Data storage failure Storage Results Error Message We could not save your payment data. But this is not a problem, we will ask you to save it again when you make the next payment.

Payment Run

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 PSP Payment Run.

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

Eligible Entries

Entries must not be associated to payments. In addition, they must meet the following conditions to be eligible for being captured using the payment run:

Field Description
Account The associated account for the debtor
Type The type of the entry, must be Debit
Payable Amount The amount to be captured, which must be non-zero
Status The status of the entry, must be Open
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
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
Account The associated account for the debtor, must be the same as set for the entry
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.

Ultimately, both the entry and the payment instrument must relate to the same account. Otherwise, the entry will bot be subject to the payment run.

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 currently processes too many requests. It has temporarily rejected the current request and asked JustOn Cash Management to repeat it after some seconds – which may result in 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 Failed, 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 (saved in Number of Communication Failures), 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 5 – illustrates the behavior.

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

For the involved payment instruments, Last Capture Is Success is set false, and Last Capture Message to provider error. JustOn Cash Management creates an error report, including the information needed to understand and possibly solve the issue.

After JustOn Cash Management has deactivated the payment provider (according to the retry threshold and the number of communication failures), administrators must consult the error reports, solve the issue if possible, reset the failure count, and 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 Failed and the open amount 0, 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 Failed and the open amount 0, and excludes the payment instrument from future capture attempts within the same or future payment run executions (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:

Payment Run Result Notification Condition Description
No active payment instrument Payment Invitation The amount of the related (eligible) entry cannot be captured because there is no active payment instrument.
Success Payment Successful The amount of the related entry has been successfully captured using the related payment instrument.
Entry failure Entry Excluded The amount of the related entry could not be captured because of errors in the entry, which is therefore excluded from further payment runs.
Payment instrument failure Payment Instrument Deactivated The amount of the related entry could not be captured 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 instrument failure are saved to the corresponding payment instrument's Last Capture Notification field.

Refund Handling

If payments are processed via a payment service provider, any related refunds must be handled via the PSP as well. Basically, JustOn Cash Management supports two approaches:

  • Users can create refund records starting from the original payment record. Once these refunds are approved, the payment run can pick them up and send them to the payment provider.
  • Users can initialize refunds via the PSP.

Refund via Payment Run

The payment run can submit refund requests to the payment service provider based on previously processed payments. This functionality does not support refunds without a direct reference to existing payment transactions (so-called unreferenced refunds or credit transfers).

For the refund via payment run to work, it requires an eligible refund as well as an eligible payment:

Eligible Refunds

Field Description
Status The status of the refund must be Approved
Open Amount The amount must be positive
Refunded Amount The refunded amount must be zero
Payment Id Must relate to an eligible payment

Eligible Payment

Field Description
Status The status of the payment must be Collected or Final
Payment Id Has been given by the payment provider and is used again during refund submission
Payment Provider Must be a active payment provider

Refund Results

Issuing refunds using the payment run may yield one of the following results, respectively:

Success

The refund request has been successfully submitted to the payment provider. JustOn Cash Management has updated the refund record setting the status Pending and adding the provider-specific refund ID.

After the payment provider has actually paid the refund, JustOn Cash Management changes the refund status to Refunded.

Delayed

The payment provider currently processes too many requests. It has temporarily rejected the current request and asked JustOn Cash Management to repeat it after some seconds – which may result in a success or a failure. JustOn Cash Management has updated the refund record, setting the status Pending but without immediately adding a provider-specific refund ID. The refund identifier will be set if the refund is successful.

If there is no provider-specific refund ID after the payment run has completed, you are advised to review the error report to identify potential issues. Once the issues are resolved, users can re-approve the refund (see Approving Refund) for the next payment run.

Temporary Failure

The communication with the payment provider has failed. JustOn Cash Management has set the refund status Failed, and will retry to submit the refund on the next payment run execution.

If a payment provider causes too many (by default, 10) temporary failures in consecutive payment runs (saved in Number of Communication Failures), 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 5 – illustrates the behavior.

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

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 the refund, and has consequently set the refund status Failed.

Refund via Payment Provider

Typically, users initialize refunds based on the original payment in JustOn Cash Management. Certain circumstances, however, may require refunds to be initialized via a payment service provider. In this case, any transactions will synchronize with JustOn Cash Management via webhook notifications. Subsequently, JustOn Cash Management will update both payment and refund records accordingly:

  • Each webhook notification results in the creation of a Payment Notification record linked to the original Payment record. The payment notification captures current changes or data related to the payment and refund.
  • Based on the webhook notification, JustOn Cash Management creates or updates a corresponding Refund record, with the Open Amount in accordance with the refunded payment (see Refund Amount Values). This ensures the accurate reflection of the refund status in JustOn Cash Management.
  • Should the refund status update to Refunded, JustOn Cash Management will adjust the Open Amount and the Collected Amount of the related payment (see Payment Amount Values) in accordance with the refunded amount.
  • Any related entries might also be updated in response to the refund processing, ensuring that settled amounts remain up-to-date.

JustOn Cash Management supports refunds in response to payments made via Mollie.

Be aware that refunds initialized via payment service providers may require some manual processing, see Managing Payment Provider-Initiated Refunds.