Capture an EBT payment

📘

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

elementOptions

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:

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

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.

📘

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.