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

TypeDescription
ebt_pin_capture_payment

required

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

Parameters

TypeDescription
ForageEbtPaymentElement

required

objectThe object created in response to calling the method that creates a payment capture element.
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 object.

Example

try {
  const ebtPaymentCaptureResult = await forage.captureEbtPinPayment(ebtPaymentCaptureElement, paymentRef)
  // handle EBT payment capture result
} catch (forageErr: ForageError) {
  const [error] = forageError.errors // handle ForageErrorObj[] list
  const { httpStatusCode, message, code } = error
}

Returns

forage.captureEbtPinPayment(ForageEbtPaymentElement, paymentRef) returns a Promise.

On success, the Promise resolves with an object that contains the following 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.
receipt response fields

The USDA requires the information contained in the receipt response to be displayed to the EBT cardholder.

To calculate the total amount paid by the customer, add the snap_amount, ebt_cash_amount, other_amount, and sales_tax_applied. The total amount is settled with the merchant after applying Forage's fees.

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 for their order, represented as a numeric string.
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/refunded to any payment method that is not an EBT Card.

Forage JS does not handle non-EBT Card payments, so this value is irrelevant in the context of the JS SDK.
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.

Example return value

{
    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: '20',
        other_amount: '12.5',
        sales_tax_applied: '5.06',
        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
}

If the EBT payment capture fails, then the Promise rejects with a ForageError object that describes the failure.