Save a payment method on the web

❗️

API version 2023-01-01 deprecating

This version will be deprecated on May 1, 2025. If your platform is on this version, you should upgrade to at least 2023-12-01 to simplify authorization and access new features.

You can use Rainforest's payment component to save a payment method without immediately taking a payment

• Create a PaymentMethodConfig in the Rainforest API to send information in advance about the payment method (user billing contact, metadata, etc.)
• Embed the payment component and configure it to save a payment method
• Add an event listener on the payment component to store the payment method identifier

Create the payment method config

First, create the payment method config to set up a payment method with information such as billing details and metadata before collecting the sensitive payment method details (i.e the card number) via the payment component.

A payment method config can only be associated to one active payment method. If the payment method fails to store, the same payment method config can be used to retry storing the payment method.

Billing contact

If the billing contact is provided in the payment method config, then billing contact fields in the payment component will be omitted. For a CARD payment method, the postal code will be omitted. For an ACH payment method, the name will be omitted.

If the billing contact is not provided in the payment method config, then the payment component will ask for the bare minimum fields required to process a CARD or ACH payment in the future.

Metadata

You can define arbitrary metadata in the payment method config to save on the payment method. The method metadata will be associated to all payins processed on the saved payment method.

🚧

Do not pass sensitive information (e.g. social security numbers, protected health information, etc.) in metadata.

Embed the payment component

The next step is to show Rainforest's payment component for the user to input their payment method details and store the payment method.

Session authentication

The page where you host the component should be secure and authenticated, so that you are sure the current user is authorized to process the payin.

Create a session to grant the payment component permissions to store a payment method and pass the session_key into the payment component. This session needs the ability to create payment methods and read payment method configs. Ensure the session's statements include at least the following permissions:

{
  "statements": [
    {
      "$.action": ["read"],
      "$.resource": ["payment_method_config"]
    },
    {
      "$.action": ["create"],
      "$.resource": ["payment_method"]
    }
  ]
}

JavaScript bundle

Load the Rainforest payment JavaScript bundle onto your page so that you can render the payment component.

<script type="module" src="https://static.rainforestpay.com/sandbox.payment.js"></script>

❗️

Developing locally?

If you're testing your integration on an environment that does not use localhost as the origin, you will need to first configure your browser to allow Rainforest to use secure web APIs, like cryptography, which are normally disallowed over an insecure connection. See our instructions for more detail.

Then render the payment comonent as HTML, providing the previously-created session_key and payment_method_config_id as attributes:

<rainforest-payment
    session-key="REPLACE_ME"
    payment-method-config-id="REPLACE_ME"
></rainforest-payment>

📘

Customizing the component

See the payment component studio for more attributes you can provide to customize the component's appearance and behavior.

Event listeners

Next, the payment component will emit one of three events after attempting to store the payment method.

Events

You should add an event listener on the approved event to obtain the payment_method_id from the event data. This identifier can be stored in your system to process payins. You can now redirect your user to some other part of your website.

var component = document.querySelector('rainforest-payment');
component.addEventListener('approved', function (data) {
    // Save the payment_method_id from the data and redirect your user
});

📘

Testing on sandbox

If you're integrating on sandbox, you can use our test ACH accounts and cards to simulate an approval or decline.

Listen to webhooks

You should also listen to the payment method webhooks to know when a payment method is ready for use and receive more details. If the payment method successfully saves, then a payment_method.active webhook will fire. If the payment method fails to save, then a payment_method.failed webhook will fire.

📘

Working with webhooks

See the payment method webhooksfor the various webhooks you can subscribe to and the webhooks overviewfor an introduction to configuring webhook listeners and validating webhook payloads.