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.

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, Payeezy and Stripe support future payments. For details, see Configuring Payeezy Integration or Configuring Stripe Integration, respectively.

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 payments.

Workflow

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

  • A first invoice is issued to the customer.
  • 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.
  • A second invoice is issued to the customer: The customer is notified that the payment is collected automatically using the stored card data.
  • 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.

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

Note

Be aware that 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. 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 build-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.
[gateway_message] Additional error information (Payeezy)
[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 Payeezy and 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,
        "Payeezy", ABS(ONB2__Amount__c) * 0.0189 + 0.23,
        "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.

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 configurations and provides information like active flag, name, tenants and payment provider. From the list, you can delete existing configurations.
  • The second section allows you to add a new or edit an existing configuration.

Info

By default, you can create one active payment configuration per tenant and payment provider, except for

  • Stripe: Allows for specifying individual payment configurations per payment method for the same tenant
  • Context-specific payment configurations: Allows for creating multiple invoice-specific payment configurations, irrespective of specified tenants 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

PayPal
Payeezy
CyberSource
Stripe

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 Payeezy and Cybersource.

You can, however, specify different tenants for the two payment configurations, like using CyberSource for Tenant A and Payeezy for Tenant B, and then enable credit card payments accordingly.

Context-Specific Payment Configuration

Usually, the tenant setting of your payment provider configuration determines for which invoices the configuration and hence, the specified payment method is available. Your business may, however, require specific payment providers or payment methods for 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 configuration on the invoice:

  1. Create the following field on the Invoice object.

    API Name Description
    PaymentProviderOverride Specifies the intended payment configuration.
    If empty, JustOn uses the tenant setting of the payment provider configuration.

    Note

    For the invoice-specific payment configuration to work as intended, you must enable Read access to the PaymentProviderOverride field on the invoice for the site guest user (see Configuring Additional Permissions for Payment Provider Integration).

    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 configurations as values, and have your users select from the available options.

In another use case, you may want to define payment configurations 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 configuration on your account, opportunity, subscription or other source object records, irrespective of the tenant specified in the configuration.

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 configurations with the same name: one for PayPal, and a second for CyberSource.
  • You specify the configuration name in the PaymentProviderOverride field on the intended account record.

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

Enabling Payment Refund

Depending on your payment service provider integration, you can use JustOn's balance management functionality to directly refund a payment made via the payment page of the JustOn Self-Service Extension.

Info

As of JustOn 2.60 and JustOn Self-Service 1.44, the payment refund is available with the Stripe integration.

Refunding a payment balance directly returns the specified amount to the customer. In JustOn, this operation creates a balance record of the type Refund for the account.

To enable the refund functionality, you add the button Refund to the Balance detail page:

  1. Navigate to the object management settings of the Balance object.
  2. Click Page Layouts.
  3. Click Edit in the row of the Balance Layout.
  4. Add the Refund button to the page layout.

    In Salesforce Lightning, drag the button from the Mobile & Lightning Actions palette to the Salesforce Mobile and Lightning Experience Actions section.

    In Salesforce Classic, drag the button from the Buttons palette to the Custom Buttons area.

  5. Click Save to save the modified page layout.

    For help about modifying page layouts, see Managing Pages.