Capture an EBT payment

Create a `ForageEbtPaymentElement`

`forage.create('ebt_pin_capture_payment')`

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 ForageEbtPaymentElement that is passed to the corresponding submit method to capture the payment.

Parameters

	Type	Description
`ebt_pin_capture_payment` required	string	The constant string `ebt_pin_capture_payment`.

Example

const ebtPaymentCaptureElement = forage.create('ebt_pin_capture_payment')

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

`forage.captureEbtPinPayment(ForageEbtPaymentElement, paymentRef)`

This Forage method captures an EBT payment when passed the below parameters:

	Type	Description
`ForageEbtPaymentElement` required	object	The object created in response to calling the method that creates a payment capture element.
`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 object.

Example

try {
  const ebtPaymentCaptureResult = await forage.captureEbtPinPayment(
    ebtPaymentCaptureElement,
    paymentRef
  )
  // handle successful ebtPaymentCaptureResult
} catch (forageErr) {
  if (forageErr?.errors?.length) {
    const [error] = forageErr.errors
    // unpack the first error
    const { httpStatusCode, message, code } = error ?? {}
  }
}

forage.captureEbtPinPayment(ForageEbtPaymentElement, 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',
    created: '2021-06-16T00:11:50.000000Z-07:00'
  },
  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.
`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.
`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:

{
  "errors": [
    {
      "httpStatusCode": 400,
      "code": "ebt_error_51",
      "message": "Insufficient funds - Insufficient Funds. Remaining balances are SNAP: N/A, EBT Cash: $100.00"
    }
  ]
}

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

try {
  const ebtPaymentCaptureResult = await forage.captureEbtPinPayment(
    ebtPaymentCaptureElement,
    paymentRef
  )
  // handle successful ebtPaymentCaptureResult
} catch (forageErr) {
  if (forageErr?.errors?.length) {
    const [error] = forageErr.errors
    // unpack the first error
    const { httpStatusCode, message, code } = error ?? {}

    switch (code) {
      case 'ebt_error_51':
        // handle insufficient funds!
        break
      default:
    }
  }
}

✅
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.

Create a ForageEbtPaymentElement

forage.create('ebt_pin_capture_payment')

Parameters

Example

Submit a ForageEbtPaymentElement

forage.captureEbtPinPayment(ForageEbtPaymentElement, paymentRef)

Example

Success response

Object fields

receipt response fields

Failure response

Create a `ForageEbtPaymentElement`

`forage.create('ebt_pin_capture_payment')`

Submit a `ForageEbtPaymentElement`

`forage.captureEbtPinPayment(ForageEbtPaymentElement, paymentRef)`

`receipt` response fields