JS SDK Reference

ForageCardCapture

Render an input field where a user can enter their EBT card number. Submitting the input's value will store and tokenize the EBT card number within Forage's secure vault. This object will add an <iframe> to the page's DOM.

Constructor

Create a ForageCardCapture Frame using the constructor function.

const forageCardCapture = new ForageCardCapture(
  'ebt-card-capture',
  'sandbox',
  {
    placeholder: 'Enter EBT Card',
    successColor: '#4F8A10',
    errorColor: '#D8000C'
  }
)

Constructor parameters

ParameterTypeDescription
nodeIdstringThe id assigned to a html element. The object will insert the input element within this html element.
environmentstringThis is the card vault's environment, and it is one of two values: sandbox or prod.
options (optional)objectOptional configurations.

Submit

This method submits the EBT card number to your Forage vault.

forageCardCapture.submit(
  'eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJhIjo0LCJleHAiOjE2Njg4MDcyNDF9.oQ2LMnhfTKEp-4dIuGuh3lec87_6rhKXfSJGMYMYNPA',
  '1234567',
  (statusCode, response) => handleForageCardInputSuccess(statusCode, response),
  (errorResponse) => handleForageCardInputError(errorResponse)
)

Submit parameters

ParameterTypeDescription
sessionTokenstringThe session token generated by your backend which authenticates your app against the Forage Payments API.
fnsNumberstringA 7 digit numeric string issued by the FNS to authorized SNAP merchants.
successCallbackfunctionThe logic to run if the card tokenization is successful.
errorCallbackfunctionThe logic to run if the card tokenization fails.

successCallback parameters

ParameterTypeDescription
statusCodenumberStatus code returned from Forage API.
responseobjectResponse returned from Forage API.

PropertyTypeDescription
refstringThe Forage PaymentMethod reference.
typestringThe type of card. This value will always be ebt.
balanceobjectThe balance of the EBT card. If the card has not been balance checked, this value is null.
cardobjectUseful card metadata, such as last_4 and created.

ForageBalanceCapture

Render an input field where a user can enter their EBT card PIN. Submitting the input's value will perform a balance check on the tokenized EBT card.

Constructor

Create a ForageBalanceCapture Frame using the constructor function.

const forageBalanceCapture = new ForageBalanceCapture(
  'balance-capture',
  'sandbox',
  {
    placeholder: 'Enter PIN',
    successColor: '#4F8A10',
    errorColor: '#D8000C'
  }
)

Constructor parameters

ParameterTypeDescription
nodeIdstringThe id assigned to a html element. The object will insert the input element within this html element.
environmentstringThis is the card vault's environment, and it is one of two values: sandbox or prod.
options (optional)objectOptional configurations.

Submit

Attempt to balance check a tokenized card and then call the appropriate callback function.

forageBalanceCapture.submit(
  'eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJhIjo0LCJleHAiOjE2Njg4MDcyNDF9.oQ2LMnhfTKEp-4dIuGuh3lec87_6rhKXfSJGMYMYNPA',
  '1234567',
  '2304587ef3',
  (statusCode, response) => handleForageBalanceCheckSuccess(statusCode, response),
  (errorResponse) => handleForageBalanceCheckError(errorResponse)
)

Submit parameters

ParameterTypeDescription
sessionTokenstringThe session token generated by your backend which authenticates your app against the Forage Payments API.
fnsNumberstringA 7 digit numeric string issued by the FNS to authorized SNAP merchants.
paymentMethodRefstringThe 10 character ref field of the PaymentMethod object you created when tokenizing the EBT card.
successCallbackfunctionThe logic to run if the balance check is successful.
errorCallbackfunctionThe logic to run if there are errors while executing a balance check.
idempotencyKey (optional)stringA key to be used to make balance requests idempotent (more info on idempotency).

successCallback parameters

ParameterTypeDescription
statusCodenumberStatus code returned from Forage API.
responseobjectResponse returned from Forage API.

ForagePaymentCapture

Render an input field where a user can enter their EBT card PIN. Submitting the input's value will capture an EBT payment using a tokenized EBT card.

Constructor

Create a ForagePaymentCapture frame using the constructor function.

const foragePaymentCapture = new ForagePaymentCapture(
  'payment-capture',
  'sandbox',
  {
    placeholder: 'Enter PIN',
    successColor: '#4F8A10',
    errorColor: '#D8000C'
  }
)

Constructor parameters

ParameterTypeDescription
nodeIdstringThe id assigned to a html element. The object will insert the input element within this html element.
environmentstringThis is the card vault's environment, and it is one of two values: sandbox or prod.
options (optional)objectOptional configurations.

Submit

Attempt to accept a PIN and capture an EBT payment and then call the appropriate callback function.

foragePaymentCapture.submit(
  'eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJhIjo0LCJleHAiOjE2Njg4MDcyNDF9.oQ2LMnhfTKEp-4dIuGuh3lec87_6rhKXfSJGMYMYNPA',
  '1234567',
  'e25212353f',
  (statusCode, response) => handleSnapForageSuccessResponse(statusCode, response),
  (errorResponse) => handleSnapForagePaymentError(errorResponse)
)

Submit parameters

ParameterTypeDescription
sessionTokenstringThe session token generated by your backend which authenticates your app against the Forage Payments API.
fnsNumberstringA 7 digit numeric string issued by the FNS to authorized SNAP merchants.
paymentRefstringThe 10 character ref field of the Payment object, which you should have created before instantiating the ForagePaymentCapture object.
successCallbackfunctionThe logic to run if capturing the Payment is successful.
errorCallbackfunctionThe logic to run if there is an error while capturing the Payment.

successCallback parameters

ParameterTypeDescription
statusCodenumberStatus code returned from Forage API.
responseobjectThe processed Forage Payment object. Important fields are amount, funding_type, and status.

Definitions

PropertyTypeDescription
cssobjectCustom css to be applied to the input field.
successColorstringHex color code for the input field border when the input is valid.
errorColorstringHex color code for the input field border when the input is not valid.
placeholderstringThe placeholder text when there is no content inside the input field.

ParameterTypeDescription
errorResponseobjectError Response object returned from the Forage API.

errorsarray[ForageErrorObj]An array of error objects returned from the Forage API.

httpStatusCodenumberFind the HTTP status codes that could be returned from the Forage API
codestringA short string indicating the error code reported from the Forage API.
messagestringA developer-facing message providing more details about the error.

PropertyTypeDescription
snapnumberAmount of SNAP balance on the EBT card.
non_snapnumberAmount of EBT Cash balance on the EBT card.
updateddatetimeTimestamp of the balance check request.

PropertyTypeDescription
last_4stringThe last 4 digits of the EBT card.
createddatetimeThe date and time that the EBT card was created.
tokenstringAn internal token.

PropertyTypeDescription
refstringThe Forage Payment reference ID.
merchantnumberThe Merchant's FNS number.
funding_typestringType of tender that was processed. Possible options are ebt_snap, ebt_cash, and credit_tpp.
amountnumberAmount that was processed.
descriptionstringA short description of the Payment.
metadataobjectObject that can be used to pass through metadata.
payment_methodstringThe Forage Payment Method reference ID for the Payment Method that was charged.
delivery_addressobjectDelivery address linked to the Payment.
is_deliverybooleanTrue if the Payment was for an order that will be delivered.
createddatetimeDate and time that the Payment was created.
updateddatetimeDate and time that the Payment was last updated.
statusstringCurrent status of the Payment. Possible values are requires_confirmation, processing, canceled, failed, and succeeded.
last_processed_errorobjectThe most recently returned error while attempting to process this Payment.
success_datedatetimeDate and time that the Payment was captured.
refundsarray[Refund]List of refunds that have been applied to this Payment.

PropertyTypeDescription
citystringCity of the address.
countrystringCountry code of the address.
line1stringFirst line of the address.
line2stringSecond line of the address.
statestringState of the address.
zipcodestringZip code of the address.