HomeGuidesReference
Log In

Capture an EBT 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 to capture the payment.

Parameters

ParameterTypeDescription
collect_pin

required

stringThe constant string collect_pin.
elementOptionsobjectA set of optional configurations for the ForageCardElement. Refer to elementOptions.
elementOptions
FieldTypeDescription
styleobjectAn 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')

👍

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:

TypeDescription
ForagePinElement

required

objectThe object created in response to calling the method that creates a ForagePinElement.
paymentRef

required

stringA 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
TypeDescription
amountstringThe payment amount.
funding_typestringA string representing the type of tender. One of ebt_snap or ebt_cash.
descriptionstringA description of the payment.
metadataobjectA 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_methodstringA string identifier that refers to an instance in Forage's database of a PaymentMethod, a tokenized representation of an EBT Card.
refstringA string identifier that refers to an instance in Forage's database of a Payment object, a one-time charge to a previously created PaymentMethod.
statusstringA 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
createdISO 8601 date-time stringThe date-time when the payment was created.
updatedISO 8601 date-time stringThe date-time when the payment was updated.
success_dateISO 8601 date-time stringThe date-time when the payment was completed.
refundsarrayAn array of refs to any Refund objects associated with the payment.
tpp_lookup_idnullAn 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.
receiptobjectThe 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_idstringA 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.

TypeDescription
ref_numberstringThe reference hash of the Payment object, a one-time charge to a previously created PaymentMethod.
snap_amountstringThe amount charged/refunded to the SNAP balance of the EBT card, if any, represented as a numeric string.
ebt_cash_amountstringThe amount charged/refunded to the Cash balance of the EBT Card, if any, represented as a numeric string.
sales_tax_appliedstringThe amount of sales tax charged to the customer.
balanceobjectThe 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_amountstringThe 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_4stringThe last four digits of the EBT Card.
messagestringA message from the EBT payment network that must be displayed to the EBT cardholder.
transaction_typestringA constant string that is used to identify the transaction associated with this receipt data. One of: Order, Refund.
createdISO 8601 date-time stringThe 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
  }
}

✅

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.