Pro-code payment experiences

If pro-code development, when you need full control over every aspect of the user experience, managed LWCs of FinDock Payment Experiences, Pay Button and Payment Method Selector, can be implemented in a custom LWC component. This approach simplifies some of the Payment API handling you would otherwise need to develop when building complete LWCs from scratch.

If you need some helping getting started, we have LWC templates and scripts available through FinDock Labs.

The repository contains building blocks to help you build custom Lightning Web Components (LWC) for digital payment experiences using Experience Cloud and FinDock's managed LWCS for Payment Experiences. You can deploy the repository content directly to your org as a development baseline.

When building a custom LWC that leverage the Pay Button LWC, always keep in mind that your custom LWC must pass a complete payment intent request to the Pay Button component.

The Pay Button properties you can manipulate with your custom LWC are:

• button-label: the label (default "Pay") on the payment form button
• payment-intent: the JSON payload that represents the Payment Intent callout to the Payment API.
• show-error: boolean (default true) to hide the small red error message above the pay button. Useful when implementing your own error handling.
• onResult: an event handler that is called when the pay button returns a result from the Payment API callout. The result is an object with fields paymentIntentId, redirectUrl, errorMessage, and statusCode.

When the callout encounters an error, errorMessage and statusCode contain the specific error details returned from the Payment API. When the callout is successful, the payer is redirected automatically. You do not need to handle paymentIntentId and redirectUrl yourself.

customComponent.html

<template>
    <c-pay-button
        button-label={buttonLabel}
        payment-intent={paymentIntent}
        show-error={showError}
        onresult={handleResult}
    ></c-pay-button>
    <template lwc:if={resultText}>
        <p>{resultText}</p>
    </template>
</template>

customComponent.js

import { LightningElement } from 'lwc';

/**
 * Example Pay Button Wrapper
 *
 * A thin wrapper that renders the Pay Button with a hardcoded button label and
 * an example one-time payment intent payload, used to exercise the direct
 * payment intent path without Flow configuration.
 */
export default class CustomComponent extends LightningElement {
    buttonLabel = 'Pay now';
    showError = false;
    resultText;

    handleResult(event) {
        this.resultText = JSON.stringify(event.detail);
    }

    paymentIntent = {
        SuccessURL: 'https://example.com/success',
        FailureURL: 'https://example.com/failure',
        Payer: {
            Contact: {
                SalesforceFields: {
                    FirstName: 'Test',
                    LastName: 'Payment',
                    Email: 'test@findock.com',
                    MailingStreet: 'Any Street',
                    MailingCity: 'Any City',
                    MailingPostalCode: '00000',
                    MobilePhone: '012-3456789'
                }
            }
        },
        OneTime: {
            Amount: 10,
            CurrencyISOCode: 'EUR'
        },
        PaymentMethod: {
            Name: 'CreditCard',
            Processor: 'DummyExtension-PSP',
            Target: 'Account NL'
        }
    };
}

There are multiple ways to build your custom LWC for payment method selection. However, the configuration that needs to be passed to the Pay Button LWC must use a specific flat JSON structure. You can use the provided script to automatically build a configuration file based on an existing Salesforce org with FinDock fully configured.

Which methods appear in your custom LWC, and how they're configured, is defined statically in paymentMethodConfiguration.js configuration file. The configuration files contains an array for every payment method and processor combination you want to offer to payers. What the payer sees is rendered at runtime based on the configuration file.

You can either manually edit the configuration file or use the script from FinDock Labs. If you need to build a configuration file without access to a Salesforce org, the following table describes each of the fields you need to modify.

In addition to the above fields, the 'parameters' array can have one or more parameters, each with the following subset of fields.

For details on payment processors and related API parameters for supported methods, please refer to the processor-specific configuration article "Payment method parameters" section, such as for Stripe.

Below you can see an example configuration file with one payment processor, Stripe, and two payment methods.

import {labels} from './paymentFormLabels';

export const PAYMENT_METHOD_CONFIG = [
    {
        paymentProcessor: 'PaymentHub-Stripe',
        paymentMethod: 'CreditCard',
        target: 'Stripe-Main-Account',
        enabledOneTime: true,
        enabledRecurring: true,
        isDefaultOneTime: true,
        isDefaultRecurring: false,
        displayLabel: 'CreditCard',
        parameters: [
            {
                name: 'locale',
                value: 'nl-NL',
                visibleToCustomer: false,
                description: 'Expected input: language tags as outlined on https://www.oracle.com/java/technologies/javase/jdk13locales.html. Examples: nl-NL, en-US.'
            },
            {
                name: 'description',
                value: '',
                visibleToCustomer: true,
                displayLabel: 'description',
                required: false,
                description: "Description of the payment for the payer's bank."
            }
        ]
    },
    {
        paymentProcessor: 'PaymentHub-Stripe',
        paymentMethod: 'Ideal',
        target: 'Stripe-Main-Account',
        enabledOneTime: true,
        enabledRecurring: false,
        isDefaultOneTime: false,
        isDefaultRecurring: false,
        displayLabel: 'iDEAL | Wero',
        redirectInstruction: 'You will be redirected to your bank to complete the payment.'
    }
];

The output of the payer's choices is a payment method, processor and target (merchant account) selection, along with any required and optional parameters for the given method-processor combination. The details build the PaymentMethod block of the Payment Intent request to the Payment API. This output feeds into the Pay Button, or, alternatively, directly into a callout to the PaymentIntent endpoint of the Payment API.

Your payment method selection configuration dynamically builds the PaymentMethod block of a payment intent request. If you use a custom LWC for your pay-action that may be used with payment selection step, remember that the PaymentMethod block must be passed in the payment intent to the Pay Button component.

If a managed FinDock component encounters an error, the event is broadcast to the following Salesforce event-handling channels:

• Lightning Web Component dispatch events
  Dispatch events are best suited for advanced custom LWC development.
• Lighting Message Service
  This org-wide event channel that can be used with custom font-end Salesforce development.
• Flow Attribute Change Event This channel is a good approach for reactive Screen Flows

Payment errors generate a PAYMENT_ERROR message with the following content.

Message body

See the full Error and response codes list in the Payment API reference.