--- updatedAt: 2026-05-15T15:22:44.000Z agentTools: projectIndex: https://docs.joinforage.app/llms.txt --- # Capture an EBT payment > 📘 Server-Side PIN Collection > > You can also [collect an EBT Card PIN](https://docs.joinforage.app/reference/collect-an-ebt-card-pin-for-server-side-payment-capture) to [capture a payment server-side](https://docs.joinforage.app/reference/capture-a-payment). ## Create a `ForagePinElement` ### `forage.create('collect_pin')` This Forage method displays an input field that collects a customer's four-digit EBT Card PIN in order to capture an EBT payment. Forage does not store the PIN. Returns a `ForagePinElement` that is passed to the corresponding [submit method](#submit-the-element) to capture the payment. #### Parameters | Parameter | Type | Description | | ------------------------------------------------------------------- | ------ | ----------------------------------------------------------------------------------------------------------- | | `collect_pin`

required | string | The constant string `collect_pin`. | | `elementOptions` | object | A set of optional configurations for the `ForageCardElement`. Refer to [`elementOptions`](#elementoptions). | ##### `elementOptions` | Field | Type | Description | | ------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `style` | object | An object that sets certain CSS properties for the `ForagePinElement`. Current supported key-value pairs include:

- `borderColor`: A string that indicates the border color
- `borderWidth`: A string that specifies the border width | #### Example ```javascript const paymentCaptureElement = forage.create('collect_pin') ``` > 📘 Mount The EBT Element > > After creating the `EBT Element`, call the [`mount()`](https://docs.joinforage.app/reference/mount) method to attach it to the DOM. Refer to the [`EBT Element` lifecycle](https://docs.joinforage.app/reference/ebt-elements#ebt-element-lifecycle) for more details. ## Submit a `ForagePinElement` ### `forage.capturePayment(ForagePinElement, paymentRef)` This Forage method captures an EBT payment when passed the below parameters: | | Type | Description | | ------------------------------------------------------------------------ | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `ForagePinElement`

required | object | The object created in response to calling the method that creates a `ForagePinElement`. | | `paymentRef`

required | string | A string identifier that refers to an instance in Forage's database of a `Payment` object. You need to send a server-side [POST to the Forage `/payments/` endpoint](https://docs.joinforage.app/reference/payments) to create the `Payment`. | #### Example ```javascript try { const paymentCaptureResult = await forage.capturePayment( paymentCaptureElement, paymentRef ) const { ref: paymentRef, amount, receipt } = paymentCaptureResult } catch (error) { const { code, httpStatusCode, message } = error ?? {} } ``` `forage.capturePayment(ForagePinElement, paymentRef)` returns a `Promise`. #### Success response On success, the `Promise` resolves with an object, as in the following: ```javascript { amount: '100', funding_type: 'ebt_snap', description: 'An EBT payment', metadata: { customer_id: 'cus_1234567890' }, payment_method: 'b16673fe21', ref: 'cc3175bfea', status: 'requires_confirmation', created: '2021-06-16T00:11:50.000000Z-07:00', updated: '2021-06-16T00:11:50.000000Z-07:00', success_date: '2021-06-16T00:11:50.000000Z-07:00', refunds: ['ac47392bb1'], receipt: { ref_number: '45e3f12a90', snap_amount: '100', ebt_cash_amount: '0', other_amount: '0', sales_tax_applied: '0', balance: { snap: '100', non_snap: '100', updated: '2021-06-16T00:11:50.000000Z-07:00' }, last_4: '3456', message: 'Approved', transaction_type: 'Refund' }, tpp_lookup_id: null, customer_id: '5b53e4786e73d3da67d04f1bfe5269f72684085a23034f6b55e6887dcdb76417' } ``` ##### Object fields | | Type | Description | | ---------------- | ----------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `amount` | string | The payment amount. | | `funding_type` | string | A string representing the type of tender. One of `ebt_snap` or `ebt_cash`. | | `description` | string | A description of the payment. | | `metadata` | object | A set of arbitrary key-value data that contains additional information about the Payment object. Only returned if you set `metadata` in the [POST request](https://docs.joinforage.app/reference/create-a-payment) to create the Payment. | | `payment_method` | string | A string identifier that refers to an instance in Forage's database of a PaymentMethod, a tokenized representation of an EBT Card. | | `ref` | string | A string identifier that refers to an instance in Forage's database of a Payment object, a one-time charge to a previously created PaymentMethod. | | `status` | string | A constant string that represents a payment's status.

The lifecycle of a payment relies on asynchronous processes. This property describes a payment's state in the life cycle.

One of: `canceled`, `failed`, `processing`, `requires_confirmation`, `succeeded` | | `created` | [ISO 8601 date-time](https://www.iso.org/iso-8601-date-and-time-format.html) string | The date-time when the payment was created. | | `updated` | [ISO 8601 date-time](https://www.iso.org/iso-8601-date-and-time-format.html) string | The date-time when the payment was updated. | | `success_date` | [ISO 8601 date-time](https://www.iso.org/iso-8601-date-and-time-format.html) string | The date-time when the payment was completed. | | `refunds` | array | An array of refs to any [Refund objects](https://docs.joinforage.app/reference/payment-refunds#paymentrefund-object) associated with the payment. | | `tpp_lookup_id` | null | An id to look up a credit card associated with the payment. Always `null` in the context of Forage JS, because the library doesn't handle credit card payments. | | `receipt` | object | The information that you are required to display to the EBT cardholder after order/refund completion, according to [USDA FNS](https://www.fns.usda.gov/) federal regulations.

This field is null, in a rare case, if receipt data is not yet available. | | `customer_id` | string | A unique ID for the end customer making the payment that you shared when you [initialized Forage JS](https://docs.joinforage.app/reference/initialize-forage-js). | ##### `receipt` response fields The USDA requires the information contained in the `receipt` object to be displayed to the EBT cardholder. To calculate the order total, add the `snap_amount` or `ebt_cash_amount` to the credit card and/or other payment method amount that the customer applied to the order. | | Type | Description | | :------------------ | :---------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `ref_number` | string | The reference hash of the Payment object, a one-time charge to a previously created PaymentMethod. | | `snap_amount` | string | The amount charged/refunded to the SNAP balance of the EBT card, if any, represented as a numeric string. | | `ebt_cash_amount` | string | The amount charged/refunded to the Cash balance of the EBT Card, if any, represented as a numeric string. | | `sales_tax_applied` | string | The amount of sales tax charged to the customer. | | `balance` | object | The available SNAP and Cash balances on the EBT account associated with the EBT Card, the same as the [object returned during a balance check](https://docs.joinforage.app/reference/check-the-balance-of-an-ebt-card#returns). | | `other_amount` | string | The amount charged or refunded to any payment method that is not an EBT Card. This value is always `null` in the case of Forage JS. | | `last_4` | string | The last four digits of the EBT Card. | | `message` | string | A message from the EBT payment network that must be displayed to the EBT cardholder. | | `transaction_type` | string | A constant string that is used to identify the transaction associated with this receipt data. One of: `Order`, `Refund`. | | `created` | [ISO 8601 date-time](https://www.iso.org/iso-8601-date-and-time-format.html) string | The date-time when the payment was created. | > 📘 Additional `receipt` Response Fields > > The `receipt` response object also includes `sales_tax_applied` and `other_amount` fields. These values are always `'0'` for Forage JS. #### Failure response If the EBT payment capture fails, then the `Promise` rejects with a [`ForageError`](https://docs.joinforage.app/reference/errors) object that describes the failure, as in the following example: ```javascript { httpStatusCode: 400, code: 'ebt_error_51', message: 'Insufficient funds - Insufficient Funds. Remaining balances are SNAP: 1.23, EBT Cash: 4.56', details: { snapBalance: 1.23, cashBalance: 4.56 } } ``` You can catch and handle specific errors with `switch` statements in the function call, as in the following example: ```javascript try { const paymentCaptureResult = await forage.capturePayment( paymentCaptureElement, paymentRef ) // handle successful paymentCaptureResult } catch (error) { const { code, details, httpStatusCode, message } = error ?? {} switch (code) { case 'ebt_error_51': // handle insufficient funds! break case 'ebt_error_55': // entered the wrong PIN! break default: // handle unexpected errors } } ``` > 📘 Any Failed `Payment` Can Be Retried > > If a transaction fails, then attempt to process the original `Payment` object again before creating a new one, [updating it first](https://docs.joinforage.app/reference/update-a-payment) if you need to. > > You only need to create a new `Payment` if the old one is `canceled`. > ⚠️ Enable A "Submit" Button For Customer Input > > Find an example submit function in the [Forage JS quickstart](https://docs.joinforage.app/docs/forage-js-quickstart#authorize-an-ebt-payment), and 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) * [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) * [Tokenize a Payment Sheet](https://docs.joinforage.app/reference/tokenize-a-payment-sheet.md)