Quickstart

Follow this guide to build a Custom Forage integration.

Suggest Edits

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.

  1. 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 this ref 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.

  1. Create Balance Check Session
  • 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.
  1. Redirect to Forage Checkout for balance check
  • Use the redirect_url from the balance session response.
  1. 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 the success_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 or cancel_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.
  1. Get a payment method by ref
  • 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.
  1. Create Payment Capture Session
  • This request creates an Order object on the Payments API backend, which is identified by the ref field in the response. You need the Order ref to create a Payment object.
  • Ensure that the remaining_total fields is set to 0 (all items are EBT eligible) and the product_list is an empty list [] (disable Forage's tax calculations for this Order).
  • The customer_id field should be passed as null.
  • The redirect_url will not work until after Step 7.
  1. Create a Payment for the Order.
  • 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.
  1. Redirect to Forage Checkout for PIN submission
  • Use the redirect_url from the capture session response in step 6.
  1. 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 the success_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.
  1. Inspect Object statuses
  • Get order details by ref - using the ref from the response in step 6, you should query the Order and check the status field. If the status is succeeded, then all Payments have processed successfully. If the status is failed then check the Order.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 the status field.

Updated about 1 month ago