📘
Server-Side PIN Collection
You can also collect an EBT Card PIN to capture a payment server-side.

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

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

const paymentCaptureElement = forage.create('collect_pin')

📘
Mount The EBT Element
After creating the EBT Element, call the mount() method to attach it to the DOM. Refer to the 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 to create the `Payment`.

Example

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:

{
  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 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 string	The date-time when the payment was created.
`updated`	ISO 8601 date-time string	The date-time when the payment was updated.
`success_date`	ISO 8601 date-time string	The date-time when the payment was completed.
`refunds`	array	An array of refs to any Refund objects 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 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.

`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.
`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 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 object that describes the failure, as in the following example:

{
  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:

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 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, and listen for the "change" event's complete value to enable the button as in this snippet.
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.