Quickstart

Start a session

The client (your server) will start a session with Forage Checkout through RESTful API. Your server POSTs the order totals and where to redirect your customer after they complete Forage Checkout (either by successfully submitting payments or cancelling the order). A successful response from Forage's server will yield an Order object in the body, and you should store the reference number of the Order for your records.

The response will also contain a redirect_url. You should redirect your customer to the redirect_url to complete payment.

Below is an example request and response with added context:

Client Request

curl --request POST \
     --url https://api.sandbox.joinforage.app/api/sessions/ \
     --header 'Authorization: Bearer <authentication-token>' \
     --header 'Idempotency-Key: <idempotency-key>' \
     --header 'Merchant-Account: <merchant-id>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "delivery_address": {
    "city": "San Francisco",
    "country": "US",
    "line1": "1856 Market St.",
    "line2": "Unit 3",
    "zipcode": "94102",
    "state": "CA"
  },
  "is_delivery": true,
  "snap_total": 25.99,
  "ebt_cash_total": 25.99,
  "success_redirect_url": "<https://your-app.com/receipt>",
  "cancel_redirect_url": "<https://your-app.com/order-canceled>",
  "remaining_total": 5.99
}
'

delivery_address: The address where the order will either be delivered or picked up. Required by FNS.
is_delivery: Whether the order will be delivered or picked up. Required by FNS.
snap_total: The SNAP eligible portion of the order total in USD. Precision to the penny is supported.
ebt_cash_total: The EBT Cash eligible portion of the order total in USD. Precision to the penny is supported.
success_redirect_url : The page to redirect your customer to after successfully paying for their order. Can be an empty string "" if you would prefer to supply this URL after the order successfully completes (see below).
cancel_redirect_url : The page to redirect your customer to if they cancel their order before successful payment. Must be supplied on the initial session request
remaining_total: The portion of the Order total in USD that is not SNAP or EBT Cash eligible. This amount must be charged to a credit or debit card. Precision to the penny is supported.

Required Headers:

token: This alphanumeric string is unique to your client. Keep it a secret as it authorizes Forage to execute transactions.
merchant-identifier: This numeric string represents the authorized FNS merchant for whom you want to make the transaction.
idempotency-key: This alphanumeric string allows you to make the same sessions request twice, without creating multiple sessions on Forage's backend, as long as you pass the same value in this header for both requests. This feature is useful if any networking errors prevent the 201 CREATED response from reaching your servers after the session was created.

Response

{
  "ref": "9ebe44e3eb",
  "snap_total": 120.25,
  "ebt_cash_total": 79.75,
  "remaining_total": 10.00,
  "success_redirect_url": "https://your-app.com/receipt",
  "cancel_redirect_url": "https://your-app.com/order-canceled",
  "status": "draft",
  "redirect_url": "https://joinforage.app/sessions?order=9ebe44e3eb"
}

ref: Store a reference to this Order object for your records.
redirect_url: Redirect your customer to this page so they can complete payment.

Request transaction outcome from Forage

After a customer completes the Fully Hosted Checkout flow, request the transaction outcome from Forage. Pass the stored Order ref, in a GET to /orders/{ref}, as in the following example:

curl --request GET \
     --url https://api.sandbox.joinforage.app/api/orders/ref/ \
     --header 'accept: application/json'

Forage responds with a JSON object including details about the order, and redirects the customer to either the success_redirect_url or the cancel_redirect_url. You set these redirect values when you started the session.

{
  "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://your-app.com/receipt",
  "cancel_redirect_url": "https://your-app.com/order-canceled",
  "supported_benefits": [
    "snap",
    "ebt_cash",
    "non_ebt"
  ],
  "customer_id": "cus_AJ6yA7mRH34mJT",
  "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"
  }
}

How to start a session with a saved payment method

If you recognize a customer, then you can start a session and pre-populate it with a payment method that the customer saved during a past session.

Client Request

curl -X 'POST' \
     'https://api.sandbox.joinforage.app/api/sessions/' \
     -H 'Accept: application/json' \
     -H 'Content-Type: application/json' \
     -H 'Authorization: Bearer ${token}' \
     -H 'Merchant-Account: ${merchant identifier}' \
     -H 'Idempotency-Key: def6789' \
     -d '{
  "delivery_address": {
    "country": "US",
    "line1": "4121 Santa Monica Blvd",
    "city": "Los Angeles",
    "zipcode": "90029",
    "state": "CA"
  },
  "snap_total": 10,
  "ebt_cash_total": 20,
  "remaining_total": 0,
  "product_list": [],
  "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"
  ],
  "ebt_payment_method": "f629aa1bf3"
}'

Response

{
  "delivery_address": {
    "country": "US",
    "line1": "4121 Santa Monica Blvd",
    "city": "Los Angeles",
    "zipcode": "90029",
    "state": "CA"
  },
  "snap_total": 10,
  "ebt_cash_total": 20,
  "remaining_total": 0,
  "product_list": [],
  "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"
  ],
  "ebt_payment_method": "f629aa1bf3"
}