Payment Provider Integration

The JustOn Self-Service Extension includes a payment page. Use this page to provide your users the option to complete their checkout process, directly paying for their purchases. To this end, the JustOn Self-Service Extension can integrate with payment service providers.

Info

To set up the payment page as part of the JustOn Self-Service Extension, follow the instructions given in Payment-Specific Site Setup.

This page

Provider-Specific Integration

Depending on the payment provider you use, you must specifically configure the account access. To this end, the JustOn Self-Service Extension provides the Payment Provider Setup page.

The setup page is divided into two sections:

  • The first section lists the existing settings and provides information like active flag, name, business entities and payment provider. From the list, you can delete existing settings.
  • The second section allows you to add a new or edit an existing setting.

Info

By default, you can create one active payment provider setting per business entity and payment provider, except for

  • Stripe: Allows for specifying individual payment settings per payment method for the same business entity
  • Mollie: Allows for specifying individual payment settings per profile ID for the same business entity
  • Context-specific payment settings: Allows for creating multiple invoice-specific payment settings, irrespective of specified business entities or payment methods per payment provider. If enabled, the distinction is made based on the (unique) configuration name.

For details about individual payment provider integrations, see

Note

Some payment methods, like credit card, are supported by multiple payment providers. When setting up the payment configurations, you must make sure that a payment method is not available multiple times at the same time, like credit card payment via Stripe and Cybersource.

You can, however, specify different business entities for the two payment configurations, like using CyberSource for business entity A and Stripe for business entity B, and then enable credit card payments accordingly.

Optional Advanced Features

Context-Specific Payment Settings

Usually, the business entity defined in your payment provider settings determines for which invoices the configuration – and consequently, the specified payment method – is available. Your business may, however, require specific payment providers or payment methods for individual contexts, like accounts, opportunities, subscriptions or other source objects based on which you create invoices. To this end, you

To allow setting a specific payment provider setting on the invoice:

  1. Create the following field on the Invoice object.

    API Name Description
    PaymentProviderOverride Specifies the intended payment provider setting(s). If multiple configurations apply, use a comma separated list of setting names.
    If empty, JustOn uses the business entity defined in the payment provider setting.

    Note

    For the invoice-specific payment provider setting to work as intended, you must enable Read access to the PaymentProviderOverride field on the invoice for the site guest user (see Configuring Payment-Specific Permission Set).

    For details about creating fields, see Managing Object Fields.

The type of the field and the way to have the value set depend on your use case.

One possible approach is, for example, to use a picklist that includes the intended payment provider settings as values, and have your users select from the available options.

In another use case, you may want to define payment provider settings for a given context, like an account or opportunity. To this end, you can

  • Create a PaymentProviderOverride field on your source object

  • Configure the PaymentProviderOverride invoice field as a formula, which specifies the source field. If you have created, for example, PaymentProviderOverride on the Account object, the formula would be:

    ONB2__Account__r.PaymentProviderOverride__c

This allows to set the name of the intended provider provider setting on your account, opportunity, subscription or other source object records, irrespective of the business entity specified in the setting.

Info

The payment page can display the configured payment methods of multiple payment providers. Think of the following example: You want to provide a specific account the option to pay via PayPal and credit card via CyberSource. To this end:

  • You create two payment provider settings with the same name: one for PayPal, and a second for CyberSource.
  • You specify the setting name in the PaymentProviderOverride field on the intended account record.

Based on the settings, the payment page includes links to the two payment methods.

Future Payments

Depending on the payment provider you use, the JustOn Self-Service Extension can expose the Future Payments option on the payment page. Future payments make use of provider-specific means to pre-authorize and execute recurring charges (or other subsequent payments) without the need to repeatedly prompt users for card or account numbers.

Info

Currently, Stripe and Mollie provide optional support for future payments. For details, see Configuring Stripe Integration and Configuring Mollie Integration.

With the future payments feature enabled, JustOn creates an account-specific Payment Instrument record, which holds the corresponding credit card or bank account information. The payment instrument records are accessible via the corresponding related list on the account detail page.

Based on the saved payment instruments, JustOn can execute payment runs in order to automatically collect pre-authorized subsequent payments.

Invoices with the payment method Bank Transfer are excluded from the automatic payment collection. Note that customers may modify their payment preferences, enabling credit cards and future payments after invoices have been issued. So to make existing open invoices subject to the payment run, you change the payment method to Credit Card.

Workflow

In broad outline, the automatic payment collection usually works as follows:

(1) A first invoice is issued to the customer.

(2) The customer pays for the invoice via credit card and allows to store the card data for future use. JustOn saves the card data in an account-specific payment instrument.

(3) A second invoice is issued to the customer: The customer is notified that the payment is collected automatically using the stored card data.

(4) Once the payment due date has been reached, the payment run job collects the payment using the stored payment instrument, creates a corresponding balance and sets the invoice Paid.

Invoices with the payment method Bank Transfer are excluded from the automatic payment collection. Note that customers may modify their payment preferences, enabling credit cards and future payments after invoices have been issued. So to make existing open invoices subject to the payment run, you change the payment method to Credit Card.

Postponing the payment due date for an invoice suspends applicable payment collections for the specified time.

JustOn allows a maximum of three failing payment instrument-based payment requests. With the fourth failed attempt, JustOn disables the payment instrument. If the fourth attempt succeeds, JustOn resets the retry count, allowing for three failing payment requests again.

For details about the payment run configuration, see Scheduling Payment Collection.

Note

By default, there is no option for your users to disable the automatic payment collection after they have opted to use future payments. If required or on your user's request, you deactivate individual payment instruments manually (see How to disable payment instruments?). Make sure to establish according business processes.

Future Payment Notification

JustOn allows for including information about automatic future payments in invoice emails. To do so, you configure the specific template detail Future Payment Notification. Once created, this template detail will be used for email texts when an account has an active payment instrument.

The following default placeholders are available:

Placeholder Description
[PaymentInstrumentType] The type of the payment, for example, Credit Card.
[PaymentInstrumentAccountHolder] The name of the card holder or bank account owner.
[PaymentInstrumentMaskedPAN] The masked account number (like credit card, IBAN) as provided by the payment provider.
[PaymentInstrumentValidUntil] The date until which the payment instrument is valid and can be captured.
[PaymentInstrumentPaymentInstitution] The name of the bank (only useful for the type Bank Account).
[PaymentInstrumentPaymentProvider] The payment provider who is handling this payment instrument.

Info

You can also define your custom placeholders with PaymentInstrument set as Source.

Payment Notification

In the following cases, JustOn sends email notifications about failed payments:

  • A payment transaction with a long processing time has finally failed, like, for example, SEPA Direct Debit via Stripe, which may take 3-5 days
  • A future payment has failed three times

The email notification makes use of the specific template detail Payment Notification. In addition, the JustOn Self-Service Extension provides payment-specific built-in placeholders for the payment notification.

Info

By default, JustOn renders the placeholders as TEXT. If you need a different rendering mode, you create a custom placeholder that sets your intended rendering option and specifies Payload as the value for Source. For details, see Custom Placeholders.

Placeholder Description
[message] The error message.
[amount] The payment amount.
[currency] The payment currency.
[bank_message] Additional message from the bank.
[cardholder] Name of the credit card holder
[expiration_date] Expiration date of the credit card
[type] Credit card type, like 'Visa'
[pan] Masked PAN of the credit card
[transaction_status] Additional error information
[validation_status] Card validation status
[risk_level] Riskiness of the payment (Stripe)
[country] Two-letter ISO code representing the country of the card (Stripe).

Info

Most placeholders are filled with information provided by the bank. The availability, meaning and contents of the placeholders depends on the payment provider and payment method.

Provider Transaction Fees

Usually, payment providers charge fees for their services – a fixed amount or a percentage provision per transaction. Businesses that integrate and use payment services may have to explicitly indicate the corresponding fees for accounting purposes. To this end, the Balance object includes the field ProviderFee. Once a payment transaction is successfully completed, JustOn writes the transaction fee as charged by the provider into the ProviderFee field of the generated payment balance record.

Info

Currently, the provider transaction fee is not supported by all payment services. At present, only PayPal provides the fee information by default. For other payment services, you can use formulas to calculate the provider transaction fee.

Calculate payment provider fee

Create a custom formula field on the Balance object to calculate, for example, the provider transaction fee for Stripe.

API Name Data Type Decimal Places Blank Field Handling
ON_ProviderFee Formula (Currency) 2 Treat blank fields as blanks 
BLANKVALUE(
    ONB2__ProviderFee__c,
    CASE(ONB2__PaymentProvider__c,
        "Stripe", ABS(ONB2__Amount__c) * 0.029 + 0.30,
        null
    )
)

Make sure to adjust the formula to the actual fees of your payment service provider.