Set up payment method

Save a payment method without creating a subscription.

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. Pass this token to the OpenPayForm constructor in your frontend app to handle the payment setup.

Step 2: Implement the payment formCopied!

Use the OpenPayForm class to construct 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.

Pure Js Implementation Example - in the frontend, you can now render the form like this:

Javascript

// Initialization
const openPayForm = new OpenPayForm({
  checkoutSecureToken: 'checkout-secure-token-uuid',   // Token from Step 1
  formTarget: '#payment-form',
  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
})
// Elements 
openPayForm.createElement('card').mount('#card-element');// Create and renderthe card element

// Submission
document.querySelector('#submit')?.addEventListener('click', () => {
    openPayForm.submit();
});

HTML

<body>
  <div id="payment-form">
    <div class="billing-details">
         <label>
              <span>First Name</span>
              <input data-opid="firstName" placeholder="First Name" />
         </label>
         <label>
              <span>Last Name</span>
              <input data-opid="lastName" placeholder="Last Name" />
         </label>
         <label>
              <span>Email</span>
              <input data-opid="email" placeholder="Email" />
         </label>
         <label>
              <span>Promotion Code</span>
              <input data-opid="promotionCode" placeholder="Promotion Code" value="" />
         </label>
      	 <label>
              <span>Zip Code</span>
              <input data-opid="zipCode" placeholder="Zip Code" />
         </label>
         <label>
              <span>Country</span>
              <input data-opid="country" placeholder="Country" />
         </label>
      </div>
    <div id="card-element"></div>
    <button id="submit" type="button">Pay</button>
  </div>  
</body>

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:

Guide (.js)

Integrating payment elements

Note (For using staging environment for testing purpose) - please provide baseUrl prop with our staging environment. baseUrl is default to our production environment.

Example:

new OpenPayForm({
   baseUrl: isStagingEnv ? "https://cde.openpaystaging.com/": undefined
})

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.