Capture an EBT payment

📘

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

elementOptions

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:

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.