> For the complete documentation index, see [llms.txt](https://docs.alternativepayments.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.alternativepayments.io/web-sdk/components/add-payment-method.md).

# Add Payment Method

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

***

## Usage

```typescript
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

```html
<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

{% hint style="success" %}
**PCI Compliance**

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

{% hint style="info" %}
**Bank Security**

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

***

## 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](/web-sdk/theming.md)). 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.

{% hint style="warning" %}
**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.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.alternativepayments.io/web-sdk/components/add-payment-method.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.