Create a ForageEbtPaymentElement
ForageEbtPaymentElement
forage.create('ebt_pin_capture_payment')
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 themount()
method to attach it to the DOM. Refer to theEBT Element
lifecycle for more details.
Submit a ForageEbtPaymentElement
ForageEbtPaymentElement
forage.captureEbtPinPayment(ForageEbtPaymentElement, paymentRef)
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
receipt
response fieldsThe 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 fieldsThe
receipt
response object also includessales_tax_applied
andother_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.