Set up payment method

Sometimes you might need to save a customer’s payment details for future use without initiating a subscription. In this guide, we’ll show you how to securely collect and store a payment method using the setup mode.

Step 1: Create a secure checkout tokenCopied!

First, you'll need to create a Checkout Session with mode: 'setup'. This is done using the same API endpoint as for subscription checkout, but we provide a different mode to signify that we are only setting up payment details, not charging the customer.

Checkout API Example:

Here’s how to generate a secure checkout session using mode: 'setup':

checkout = client.checkout.create_checkout_session(
    CreateCheckoutSessionRequest(
      customer_id=customer_id,   # (Optional) To create session specific customer
      line_items=[],             # No line items for setup mode
      mode=CheckoutMode.SETUP,   # Setup mode for saving payment info
    )
  )
secure_token = checkout.secure_token  # Token to be passed to frontend

Once the secure_token is generated, it’s ready to be used on the frontend to securely collect payment details. You’ll pass this token to the <ElementsForm /> component in your React app to handle the payment setup.

Step 2: Implement the payment formCopied!

Use the <ElementsForm /> component to display a secure form where customers can enter their payment details. The form operates the same way as a subscription form, but it only saves the payment method for future use.

React implementation example:

In your frontend, you can now render the form like this:

<ElementsForm
  checkoutSecureToken={`checkout-secure-token-uuid`}  // Token from Step 1
  onChange={() => setError(undefined)}                
  onLoad={onLoad}                                     // Called when the form is loaded
  onValidationError={(message) => setError(message)}  // Handle form validation errors
  onSetupPaymentMethodSuccess={(paymentMethodId) => {      // Callback for successful setup
    console.log("Payment Method ID:", paymentMethodId)  // Use the saved payment method ID
  }}
  onCheckoutError={onCheckoutError}                   // Handle any checkout errors
>
  {({ submit }) => (
    <>
      {/* Additional form elements or UI components */}
      <button onClick={submit}>Save Payment Method</button>  {/* Trigger form submission */}
    </>
  )}
</ElementsForm>

Key callbacks and props:

• checkoutSecureToken: The secure token generated from the backend to link the session.

• onSetupPaymentMethodSuccess: A callback that returns the paymentMethodId after the setup process is successful.

• onValidationError: Handles any validation errors from the form fields.

• onCheckoutError: Handles any errors during the setup process.

For detailed props and callbacks, please refer to the main guide:

Note if you are testing in staging/sandbox - provide baseUrl prop with our staging environment. baseUrl is default to our production environment.
Example:

<ElementsForm
  baseUrl={isStagingEnv ?   "https://cde.openpaystaging.com/": undefined}
>
   ...
</ElementsForm>

Step 3: Handling a successful setupCopied!

Once the customer successfully saves their payment method, the onSetupPaymentMethodSuccess callback is triggered. This callback provides a paymentMethodId, which can be saved in customer's details and can be used to perform further actions.