---
updatedAt: 2026-05-07T18:17:26.000Z
agentTools:
  projectIndex: https://docs.joinforage.app/llms.txt
---

# Tokenize a Payment Sheet

## Create a `ForagePaymentSheetElement`

### `forage.create('payment_sheet', {...})`

This Forage method displays an input field that collects a customer's HSA/FSA Card number in order to tokenize the card and save it for future use.

Returns a `ForagePaymentSheetElement` that is passed to the corresponding [submit method](#submit-a-foragepaymentsheetelement) to store a secure reference to the card number.

#### Parameters

<table>
  <thead>
    <tr>
      <th style={{textAlign:"left"}}>Parameter</th>
      <th style={{textAlign:"left"}}>Type</th>
      <th style={{textAlign:"left"}}>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td style={{textAlign:"left"}}><code>payment\_sheet</code><br /><br /><span style={{color:"red"}}>required</span></td>
      <td style={{textAlign:"left"}}>string</td>
      <td style={{textAlign:"left"}}>The constant string <code>payment\_sheet</code>.</td>
    </tr>

    <tr>
      <td style={{textAlign:"left"}}><code>paymentSheetConfig</code><br /><br /><span style={{color:"red"}}>required</span></td>
      <td style={{textAlign:"left"}}>object</td>
      <td style={{textAlign:"left"}}>Configuration settings for the <code>ForagePaymentSheetElement</code>. Refer to <a href="#paymentsheetconfig"><code>paymentSheetConfig</code></a>.</td>
    </tr>
  </tbody>
</table>

##### `paymentSheetConfig`

<table>
  <thead>
    <tr>
      <th>Field</th>
      <th>Type</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>paymentSheet</code><br /><br /><span style={{color:"red"}}>required</span></td>
      <td>object</td>
      <td>An object that sets the configuration of the payment sheet's <code>paymentType</code>, input labels, placeholder text, styles, and more. Refer to <a href="#paymentsheet">paymentSheet</a></td>
    </tr>
  </tbody>
</table>

##### `paymentSheet`

<table>
  <thead>
    <tr>
      <th style={{textAlign:"left"}}>Field</th>
      <th style={{textAlign:"left"}}>Type</th>
      <th style={{textAlign:"left"}}>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td style={{textAlign:"left"}}><code>paymentType</code><br /><br /><span style={{color:"red"}}>required</span></td>
      <td style={{textAlign:"left"}}>string</td>
      <td style={{textAlign:"left"}}>The constant string <code>HSAFSA</code></td>
    </tr>

    <tr>
      <td style={{textAlign:"left"}}><code>styles</code><br /><br /><span style={{color:"red"}}>required</span></td>
      <td style={{textAlign:"left"}}>object</td>
      <td style={{textAlign:"left"}}>An object that propagates styles to all fields in the <code>ForagePaymentSheetElement</code>.<br /><br />Current supported key-value pairs include:<br /><br />- <code>inputStyles</code>: <a href="https://developer.mozilla.org/en-US/docs/Web/API/CSSStyleDeclaration"><code>CSSStyleDeclaration</code></a> that will be applied to all input elements.<br />- <code>labelStyles</code>: <a href="https://developer.mozilla.org/en-US/docs/Web/API/CSSStyleDeclaration"><code>CSSStyleDeclaration</code></a> that will be applied to all label elements.</td>
    </tr>

    <tr>
      <td style={{textAlign:"left"}}><code>errorStyles</code><br /><br /><span style={{color:"red"}}>required</span></td>
      <td style={{textAlign:"left"}}>object</td>
      <td style={{textAlign:"left"}}>An object that propagates error styles to all fields in the <code>ForagePaymentSheetElement</code> when invalid input is detected on input blur. These styles are removed when input is detected.<br /><br />Current supported key-value pairs include:<br /><br />- <code>inputStyles</code>: <a href="https://developer.mozilla.org/en-US/docs/Web/API/CSSStyleDeclaration"><code>CSSStyleDeclaration</code></a> that will be applied to all input elements.<br />- <code>labelStyles</code>: <a href="https://developer.mozilla.org/en-US/docs/Web/API/CSSStyleDeclaration"><code>CSSStyleDeclaration</code></a> that will be applied to all label elements.</td>
    </tr>

    <tr>
      <td style={{textAlign:"left"}}><code>fields</code><br /><br /><span style={{color:"red"}}>required</span></td>
      <td style={{textAlign:"left"}}>object</td>
      <td style={{textAlign:"left"}}>An object defining configurations scoped to each field in the <code>ForagePaymentSheetElement</code>.<br /><br />Key-value pairs include:<br /><br />- <code>cardHolderName</code>: <a href="#fieldconfig"><code>fieldConfig</code></a><br />- <code>cardNumber</code>: <a href="#fieldconfig"><code>fieldConfig</code></a><br />- <code>cardExpiration</code>: <a href="#fieldconfig"><code>fieldConfig</code></a><br />- <code>cardCVV</code>: <a href="#fieldconfig"><code>fieldConfig</code></a><br />- <code>cardZipCode</code>: <a href="#fieldconfig"><code>fieldConfig</code></a></td>
    </tr>
  </tbody>
</table>

##### `fieldConfig`

<table>
  <thead>
    <tr>
      <th style={{textAlign:"left"}}>Field</th>
      <th style={{textAlign:"left"}}>Type</th>
      <th style={{textAlign:"left"}}>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td style={{textAlign:"left"}}><code>labelText</code><br /><br /><span style={{color:"red"}}>required</span></td>
      <td style={{textAlign:"left"}}>string</td>
      <td style={{textAlign:"left"}}>The text to display in the label element.</td>
    </tr>

    <tr>
      <td style={{textAlign:"left"}}><code>placeholderText</code><br /><br /><span style={{color:"gray"}}>optional</span></td>
      <td style={{textAlign:"left"}}>string</td>
      <td style={{textAlign:"left"}}>The text to display in the input element placeholder.</td>
    </tr>
  </tbody>
</table>

#### Example

```javascript
const foragePaymentSheet = forage.create('payment_sheet', {
        paymentSheet: {
          paymentType: 'HSAFSA',
          // common styles propagating to all fields
          styles: {
            inputStyles: {
              border: '3px solid black',
              borderRadius: '8px',
              padding: '10px',
            },
            labelStyles: {
              fontSize: '1rem',
              fontWeight: 'bold',
            },
          },
          // error styles to use when fields are invalid on blur event
          errorStyles: {
            inputStyles: {
              borderColor: 'red',
            },
          },
          fields: {
            cardHolderName: {
              labelText: 'Full name',
              placeholderText: 'John Doe',
              // styles scoped to the field
              styles: {
                inputStyles: {
                  border: '2px solid blue',
                },
              },
            },
            cardNumber: {
              labelText: 'Card number',
              placeholderText: '1234 1234 1234 1234',
            },
            cardExpiration: {
              labelText: 'Expiration date',
              placeholderText: 'MM/YY',
            },
            cardCVV: {
              labelText: 'Security code',
              placeholderText: 'CVV',
            },
            cardZipCode: {
              labelText: 'Zip code',
              placeholderText: '12345',
            },
          },
        },
      })
```

> 📘 Mount The `ForagePaymentSheetElement`
>
> After creating the `ForagePaymentSheetElement`, call the [`mount()`](https://docs.joinforage.app/reference/mount) method to attach it to the DOM. This element uses the same lifecycle as the EBT Elements. Refer to the [`EBT Element` lifecycle](https://docs.joinforage.app/reference/ebt-elements#ebt-element-lifecycle) for more details.

## Submit a `ForagePaymentSheetElement`

### `forage.tokenizeCard(ForagePaymentSheetElement, options?)`

This Forage method tokenizes a Payment Sheet card.

#### Parameters

<table>
  <thead>
    <tr>
      <th style={{textAlign:"left"}} />

      <th style={{textAlign:"left"}}>Type</th>
      <th style={{textAlign:"left"}}>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td style={{textAlign:"left"}}><code>ForagePaymentSheetElement</code><br /><br /><span style={{color:"red"}}>required</span></td>
      <td style={{textAlign:"left"}}>object</td>
      <td style={{textAlign:"left"}}>The object returned by calling <code>forage.create('payment\_sheet', \{...})</code>.</td>
    </tr>

    <tr>
      <td style={{textAlign:"left"}}><code>options</code></td>
      <td style={{textAlign:"left"}}>object</td>
      <td style={{textAlign:"left"}}>A set of optional configuration settings for the Card. Refer to <a href="#options">options</a>.</td>
    </tr>
  </tbody>
</table>

##### options

<table>
  <thead>
    <tr>
      <th style={{textAlign:"left"}} />

      <th style={{textAlign:"left"}}>Type</th>
      <th style={{textAlign:"left"}}>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td style={{textAlign:"left"}}><code>reusable</code></td>
      <td style={{textAlign:"left"}}>boolean</td>
      <td style={{textAlign:"left"}}>Whether the payment method can be reused. If <code>false</code>, then the payment method can only be used for a single transaction.<br /><br />Defaults to <code>true</code> if no <code>options</code> parameter is provided.</td>
    </tr>
  </tbody>
</table>

#### Example

```javascript
try {
  const tokenizationResult = await forage.tokenizeCard(
    foragePaymentSheet,
    { reusable: true }
  )
  const { ref, type, card } = tokenizationResult
} catch (error) {
  const { httpStatusCode, message, code } = error ?? {}
}
```

`forage.tokenizeCard(ForagePaymentSheetElement)` returns a `Promise`.

#### Success response

On success, the `Promise` resolves with an object, as in the following:

```javascript
{
  ref: 'ac47392bb1',
  type: 'credit',
  reusable: true,
  card: {
    brand: 'visa',
    exp_month: 12,
    exp_year: 2034,
    last_4: '3456',
    is_hsa_fsa: true,
    psp_customer_id: 'cus_SwmG7uYElJTytO',
    payment_method_id: 'pm_1S0si1P4HzVVeE0muBq9X46u',
    last_4: '3456',
    created: '2023-07-10T17:21:23.346019-07:00',
  },
}
```

#### Object fields

|            | Type    | Description                                                                                                                          |
| :--------- | :------ | :----------------------------------------------------------------------------------------------------------------------------------- |
| `ref`      | string  | A string identifier that refers to an instance in Forage's database of a PaymentMethod, a tokenized representation of a Credit Card. |
| `type`     | string  | A constant `credit` string.                                                                                                          |
| `reusable` | boolean | Whether the payment method can be reused. If `false`, then the payment method can only be used for a single transaction.             |
| `card`     | object  | An object with information about the card, as detailed in the [card response fields](#card-fields).                                  |

##### `card` fields

|                     | Type                                                                                | Description                                                                                                  |
| :------------------ | :---------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------- |
| `brand`             | string                                                                              | The brand of the card used.                                                                                  |
| `exp_month`         | number                                                                              | The card's expiration month.                                                                                 |
| `exp_year`          | number                                                                              | The card's expiration year.                                                                                  |
| `is_hsa_fsa`        | boolean                                                                             | `true` if the card is eligible for HSA/FSA purchases. Otherwise `false`.                                     |
| `psp_customer_id`   | string                                                                              | The Stripe identifier for the customer.                                                                      |
| `payment_method_id` | string                                                                              | A unique identifier for a Stripe PaymentMethod that represents a customer's credit/debit payment instrument. |
| `last_4`            | string                                                                              | The last four digits of the card number.                                                                     |
| `created`           | [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) date-time string | The date-time when the `card` object was created.                                                            |

#### Failure Response

If the card tokenization fails, then the `Promise` rejects with a [`ForageError`](https://docs.joinforage.app/reference/forage-js-errors) object that describes the failure, as in the following example:

```javascript
{
  httpStatusCode: 400,
  code: 'not_an_hsa_fsa_card',
  message: 'Not an HSA/FSA card'
}
```

You can catch and handle specific errors with switch statements in the function call, as in the below snippet:

```javascript
try {
  const tokenizationResult = await forage.tokenizeCard(
    foragePaymentSheet,
    { reusable: true }
  )
  const { ref, type, card } = tokenizationResult
  // handle successful tokenizeCard result
} catch (error) {
  const { code, details, httpStatusCode, message } = error ?? {}

  switch (code) {
    case 'not_an_hsa_fsa_card':
    // handle not_an_hsa_fsa_card!
    break
    case 'user_error':
    // handle user_error!
    break
    default:
    // handle unexpected errors
  }
}
```

> ⚠️ Enable A "Submit" Button For Customer Input
>
> Listen for the "change" event's complete value to [enable the button as in this snippet](https://docs.joinforage.app/reference/change#listen-for-complete).
>
> Allow customers to progress on their own. Do *not* use `complete` to automatically perform an action like submitting the form or advancing the cursor to the next input field.

# Sibling pages

* [Tokenize an EBT Card](https://docs.joinforage.app/reference/store-an-ebt-card.md)
* [Check the balance of an EBT card](https://docs.joinforage.app/reference/check-the-balance-of-an-ebt-card.md)
* [Capture an EBT payment](https://docs.joinforage.app/reference/capture-ebt-payment.md)
* [Collect an EBT Card PIN for server-side payment capture](https://docs.joinforage.app/reference/collect-an-ebt-card-pin-for-server-side-payment-capture.md)