Quickstart
Follow this guide to build a Custom Forage integration.
This step-by-step guide will walk you through the process to accept both SNAP and Cash EBT payments using a "Custom Checkout" integration type. In broad strokes, you need to make a few setup API requests and then redirect to Forage Checkout for balance check and final payment capture. The guide assumes that you have already received USDA approval to accept EBT payments. Furthermore, your application should already be registered with Forage's OAuth flow, which allows you to generate authentication tokens.
- Create an EBT payment method
- Be sure to use the request body for EBT cards.
- Keep track of the
ref
field in the response. You will use thisref
to include the EBT card in future requests, without transmitting the card number.
FNS prohibits balance inquiries on sites that offer guest checkout.
Skip to Step 6 if your site offers a guest checkout option.
If your site doesn't offer guest checkout, then it's up to you whether or not to add a balance inquiry feature. No FNS regulations apply.
- Note that you will pass the payment method
ref
from step 1 in this request body. You are requesting a balance check for this card.
- Redirect to Forage Checkout for balance check
- Use the
redirect_url
from the balance session response.
- Handle redirects from Forage Checkout back to your application
- There are two scenarios: 1) The balance check was canceled and your customer was redirected to the
cancel_redirect_url
you specified in step 2 or 2) The balance check was successful and your customer was redirected to thesuccess_redirect_url
you specified in step 2. - If your application deploys as a mobile app, you will need to catch and override the url redirects. There are multiple ways to accomplish this, but we will describe one way for iOS and Android below.
- If on iOS, we recommend using the navigation delegate property of WKWebView. When the web view begins to redirect, inspect the URL it is being redirected to and determine if it is either the
success_redirect_url
orcancel_redirect_url
passed in to create the session. In either case, close the web view and proceed through each corresponding flow. Discussion on implementation details can be found here. - If on Android, we recommend using the
shouldOverrideUrlLoading
function found here. Follow the same decision tree described above. More information on implementation can be found here.
- If on iOS, we recommend using the navigation delegate property of WKWebView. When the web view begins to redirect, inspect the URL it is being redirected to and determine if it is either the
- The balance(s) of the EBT card will be stored on the PaymentMethod object you created in step 1, so use this get request and inspect the
balance
field of the response.
- This request creates an Order object on the Payments API backend, which is identified by the
ref
field in the response. You need the Orderref
to create a Payment object. - Ensure that the
remaining_total
fields is set to 0 (all items are EBT eligible) and theproduct_list
is an empty list[]
(disable Forage's tax calculations for this Order). - The
customer_id
field should be passed asnull
. - The
redirect_url
will not work until after Step 7.
- Payment objects express how much should be charged to the SNAP and EBT Cash balances of the EBT card. Use the
funding_type
field to specify which balance of the EBT PaymentMethod you would like to charge. Payments are the way you associate an EBT PaymentMethod to the Order created in the last step.
- Redirect to Forage Checkout for PIN submission
- Use the
redirect_url
from the capture session response in step 6.
- Handle redirects from Forage Checkout back to your application
- There are two scenarios: 1) Order capture was canceled before it fully completed and your customer was redirected to the
cancel_redirect_url
you specified in step 6 or 2) All payments were successful and your customer was redirected to thesuccess_redirect_url
you specified in step 6. Typically the success URL is your receipt or order confirmation page. - Note that SNAP payment may have still processed even if your user is redirected to the
cancel_redirect_url
. You need to check the status of the Payment object to determine exactly what happened.
- Inspect Object statuses
- Get order details by ref - using the
ref
from the response in step 6, you should query the Order and check thestatus
field. If thestatus
issucceeded
, then all Payments have processed successfully. If the status isfailed
then check theOrder.receipt.message
field for the error message from the EBT network. - Get a payment by ref - using the
ref
from the response in step 7, you can query the Payment object and check thestatus
field.
Updated about 1 month ago