Add Payment Method

Form for adding a new payment method (credit card or bank account).

---

Usage

const addPayment = client.components.addPaymentMethod({
  containerId: 'add-payment',
  customerId: 'cus_xxx',
  defaultType: 'CARD',
  onSuccess: (paymentMethod) => {
    console.log('Added:', paymentMethod.id);
  },
  onCancel: () => {
    console.log('Cancelled');
  },
});

---

Configuration

AddPaymentMethodConfig

Property	Type	Required	Description
containerId	string	Yes	ID of the container element
customerId	string	Yes	Customer ID to add payment method for
defaultType	'CARD' | 'ACH'	No	Default tab to show
currency	'usd' | 'cad'	No	Currency context
theme	ThemeConfig	No	Custom theme configuration
onSuccess	(pm: PaymentMethod) => void	No	Called when payment method is created
onCancel	() => void	No	Called when "Cancel" is clicked
onError	(error: Error) => void	No	Called on errors

---

Card Form

The card form uses Evervault for PCI-compliant card collection. Your application never touches raw card data.

Fields collected:

• Card number

• Expiration date (MM/YY)

• Cardholder name

• Billing address (street, city, state, postal code, country)

---

Bank Account Form (ACH)

The ACH form uses Plaid for secure bank account linking.

Process:

1. User clicks "Connect Bank Account"

2. Plaid Link opens in a modal

3. User selects their bank and authenticates

4. Account details are securely captured

---

Example

<div id="add-payment"></div>

<script type="module">
  import { AlternativeClient } from '@getalternative/partner-sdk';

  const client = new AlternativeClient({
    clientId: 'your-client-id',
    clientSecret: 'your-client-secret',
  });

  const form = client.components.addPaymentMethod({
    containerId: 'add-payment',
    customerId: 'cus_abc123',
    defaultType: 'CARD',
    onSuccess: (paymentMethod) => {
      // Payment method added successfully
      console.log('New payment method:', paymentMethod);

      // Navigate back to selection
      window.location.href = '/payment-methods';
    },
    onCancel: () => {
      window.history.back();
    },
    onError: (error) => {
      console.error('Failed to add payment method:', error);
    },
  });
</script>

---

Security

PCI Compliance

Card data is collected directly by Evervault and never touches your servers. This keeps your application out of PCI scope.

Bank Security

Bank credentials are handled entirely by Plaid. Your application only receives a secure token for the linked account.

---

Credit Card Support & Evervault

The SDK component is the only supported path for collecting card details

The addPaymentMethod component is the only supported way to add a credit card payment method. There is no REST API endpoint that accepts raw card numbers — the REST API's POST /customers/{id}/payment-methods/card endpoint requires a card_provider_token that has already been encrypted by Evervault. Obtaining that token requires the Evervault iframe, which the SDK component hosts on your behalf.

Partners building custom portals must use this SDK component for card collection. Attempting to call the card endpoint directly without a valid Evervault token will result in a 400 Bad Request with card_provider_token is required.

How the Evervault iframe works

When the card form renders, the SDK fetches Evervault credentials from the API and initializes a secure iframe hosted by Evervault. The customer enters their card details inside that iframe. Evervault encrypts the data and returns an opaque token; the SDK then passes that token — with provider: "evervault" — to POST /customers/{id}/payment-methods/card. At no point does plain-text card data pass through your application or Alternative Payments' servers.

This architecture keeps your integration out of PCI scope for card data handling.

Customization scope

You can customize the appearance of the addPaymentMethod component using the theme configuration (see Theming). The ThemeConfig properties — colors, typography, border radius, and so on — apply to the surrounding SDK component shell.

The Evervault iframe itself is rendered and controlled by Evervault. Its internal appearance cannot be customized through the SDK's theme configuration.

Bank accounts vs. credit cards

Bank account payment methods behave differently. The REST API endpoint POST /customers/{id}/payment-methods/bank accepts account details directly (routing number, account number, institution name, and so on) and does not require the SDK or an iframe. Partners can call this endpoint from their own server-side code independently of the Web SDK.

Method	SDK required?	REST API endpoint
Credit card	Yes — SDK component obtains the Evervault token	POST /customers/{id}/payment-methods/card (requires card_provider_token)
Bank account (ACH)	No	POST /customers/{id}/payment-methods/bank

Both endpoints require the payments:write OAuth scope.

Custom portal integrations

If you have built a custom payment portal using the checkout APIs, card collection still requires the addPaymentMethod SDK component. There is no path to add a card payment method without the Evervault iframe.