🚧

Upgrade to the latest version

These docs are for version 2023-12-01. We encourage you to upgrade to version 2024-10-16 to access new features. Please see the changelog for more information.

When the Payment Component is shown as part of a larger form, you may want to update the configuration defined by the Payin Config or Payment Method Config after it has been embedded in your payment flow.

This guide will explain how to:

1. Update the payment configuration
2. Know if the payment configuration was updated
3. Find out the brand of the card number

Update the payment configuration

When the Payment Component is rendered, a valid Payin Config or Payment Method Config is provided to configure the payin or payment method, respectively. The config determines the amount of the payin, billing contact details, level 2 and 3 data, and additional details.

If your checkout form allows the customer to make changes that could impact the amount of the payin or other details provided on the config, the config can be updated without having to re-render the payment component.

If you're rendering the component in HTML or directly via the DOM API, you can update the config attribute by using the JavaScript DOM attribute API.

Update the payin config

For example, if you need to update the amount of the payin config, you can create a new payin config via a backend API call. Then, update the payin-config-id attribute:

component.removeAttribute('payin-config-id');
component.setAttribute('payin-config-id', newPayinConfigId;

Update the payin config to a payment method config

Another example, if you need to switch from taking a payment to only storing a payment method, then the previously provided payin-config-id attribute can be removed and the payment-method-config-idattribute can be set:

component.removeAttribute('payin-config-id');
component.setAttribute('payment-method-config-id', paymentMethodConfigId;

Know if the payment configuration was updated

There are a few scenarios to account for that will not allow the config to be updated.

• The new config is not valid, due to permissions or other errors.
• The payment was submitted and the request is currently in flight.
• 3DS is implemented and the customer is currently in the 3DS flow.

The updating of the config will be handled gracefully to not disrupt the payment flow for the customer. The Payment Component will emit one of the following events to let you know if the update request was accepted or ignored.

Events

Using the Rainforest submit button

If your integration uses the default Payment Component submit button and the new config updated the amount, then the button will automatically update to display the new amount defined by the payin config.

Using your own submit button

If your integration is also hiding the Rainforest-controlled submit button, then you should disable your submit button until you have received the config-update-accepted event. This will prevent the possibility of the customer processing the payment on the old config while we are validating the new config.

Find out the brand of the card number

You can listen to the following event to be notified of the card brand as the customer is filling out their card number.

This can be helpful if your integration requires the amount of the payment to change depending on the card brand. For example, surcharging for Amex.

Event

The event payload will have a string payload indicating the detected card brand, with possible values VISA, MASTERCARD, DISCOVER, AMERICAN_EXPRESS, OTHER or NONE.

var component = document.querySelector('rainforest-payment')

component.addEventListener('card-brand-updated', (e) => {
    // get payload value
    var brand = e.detail[0];
  
    // ... your custom logic
});

Once the card brand is updated, you can update the payin config as necessary.

Find out if the method displayed was updated

If the Payment Component is embedded with multiple allowed methods, you can listen to the following event to be notified when the customer selects the payment method type to display the corresponding payment form.

This can be helpful if your integration requires the amount of the payment to change or additional information to be displayed depending on the payment method type the customer chooses to pay with.

Event