Introduction

✅
Forage is PCI Level 1 compliant

This reference details comprehensive information about the Forage Payments API.

The Payments API is the foundation of accepting EBT SNAP online with Forage. You need to interact with the REST API no matter what integration type you choose. For example:

POST /payments/ creates a payment ref , a required parameter for SDK payment capture functions
POST /sessions/ initializes the Forage Checkout Fully Hosted UI
POST /capture_sessions/ starts a Forage Custom payment capture session

Using the navigation on the left, you can find details about all of the available endpoints to manage Forage resources. The resources that you need to interact with depend on your integration type, as detailed in the following sections.

📘
Learn more about Forage integration types
If you haven't decided whether to go with a Forage SDK, Fully Hosted, or Custom integration, check out the guide to integration types.

Forage resources

A list of the primary resources involved in each integration type

All integrations

Bearer Token: An OAuth 2.0 token that validates API requests
Report: A paginated list of records about a merchant’s EBT business, either transactions, payouts, payout transactions, or orders

SDKs

You can use a Forage SDK to build your own EBT checkout interface. SDK integrations interact with the following resources:

Payment: A one-time charge to a known payment method
Payment refund: A refund associated with a payment

📘
Learn more

Forage JS Reference

Android Overview

iOS Overview

Fully Hosted

A Fully Hosted integration embeds Forage's comprehensive prebuilt EBT checkout interface. Fully Hosted integrations interact with the following resources:

Session: An instance of the ready-to-use Forage Checkout UI with built-in balance inquiry and payment capture features
Order: A checkout cart that a customer submits for purchase via the Forage Checkout UI
Order Payment: A one-time charge, to a known payment method, that is associated with an order created via the Forage Checkout UI
Order Refund: A refund associated with an order created via the Forage Checkout UI

📘
Learn more

Forage guide to Fully Hosted

Custom

A Custom integration embeds Forage's prebuilt EBT PIN entry interface. Custom integrations interact with the following resources:

Payment Method: A reference to a form of payment that a customer uses to make a purchase, typically an EBT card
Balance Session: An instance of the ready-to-use Forage Checkout UI that initiates a balance inquiry
Capture Session: An instance of the ready-to-use Forage Checkout UI that captures a payment
Order Payment: A one-time charge, to a known payment method, that is associated with an order created via the Forage Checkout UI
Order: A checkout cart that a customer submits for purchase via the Forage Checkout UI
Order Refund: A refund associated with an order created via the Forage Checkout UI

✅
Any data created by your application’s requests or customers via the Forage Checkout UI — whether a Fully Hosted or Custom integration — is available through GET requests to the corresponding resource.

📘
Learn more

Forage guide to Custom

Authentication

Requests use the HTTP Authorization header to verify operations. The API accepts bearer tokens in this header. Refer to the authentication guide for complete details.

JSON conventions

Numeric values are returned as strings

The Forage API returns decimal amounts as strings. For example, the response body of a GET to /orders/{ref}/ for an order with a $25.99 SNAP charge includes a snap_total value of "25.99"(full example response below). You need to parse the string values to numbers to perform calculations.

{
  "snap_total": "25.99",
  "ebt_cash_total": "5.99",
  "remaining_total": "10.99",
  "platform_fee": "0.05",
  "product_list": [],
  "delivery_address": {
    "city": "Los Angeles",
    "country": "US",
    "line1": "4121 Santa Monica Blvd",
    "line2": "Unit 513",
    "zipcode": "90029",
    "state": "CA"
  },
  "is_delivery": true,
  "success_redirect_url": "https://www.joinforage.com/status=SUCCEEDED",
  "cancel_redirect_url": "https://www.joinforage.com/status=CANCELED",
  "supported_benefits": [
    "snap",
    "ebt_cash",
    "non_ebt"
  ],
  "psp_customer_id": "cus_AJ6yA7mRH34mJT",
  "customer_id": "0000012345",
  "external_order_id": "1f2ee410-5b47-4130-aec2-40f5eb2108f5",
  "ref": "93410bcaff",
  "status": "draft",
  "payments": [],
  "refunds": [],
  "receipt": {
    "ref_number": "45e3f12a90",
    "snap_amount": "25.99",
    "ebt_cash_amount": "10.99",
    "other_amount": "5.99",
    "sales_tax_applied": "5.16",
    "balance": {
      "snap": "25.99",
      "non_snap": "10.99",
      "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"
  }
}