Fully Hosted Checkout

Introduction

This section includes a more detailed description of Forage Checkout.

Customer perspective

Click through the slideshow below to see what the customer experiences. Each frame includes notes for context.

Developer perspective

The flowchart below summarizes the request and response flow between your website and Forage's payment server. Reference it in the subsections below.

48004800

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. This redirect is the transition from slide 1 to slide 2 in the Customer Perspective above.

Below is an example request and response with added context:

Client Request

curl -X 'POST' \
  'https://api.joinforage.app/sessions/' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer ${token}` \
  -H 'Merchant-Account: ${merchant identifier}' \
  -H 'Idempotency-Key: abc1234' \
  -d '{
    "snap_total": 120.25,
    "ebt_cash_total": 79.75,
    "remaining_total": 10.00,
    "success_redirect_url": "https://www.joinforage.com/receipt?order=12345&status=SUCCEEDED",
    "cancel_redirect_url": "https://www.joinforage.com/receipt?order=12345&status=CANCELED"
  }'
  • 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

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://www.joinforage.com/receipt?order=12345&status=SUCCEEDED",
  "cancel_redirect_url": "https://www.joinforage.com/receipt?order=12345&status=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.

Notify Client of payment completion

Forage will send a request to your server when your customer either successfully finishes the transaction or cancels it.

Forage Request

curl -X 'POST' \
  'https://${client url}' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d ' {
    "ref": "9ebe44e3eb",
    "snap_total": 120.25,
    "ebt_cash_total": 79.75,
    "remaining_total": 10.00,
    "status": "succeeded",
    "payments": ["8d1b5637aa", "666e07397b"],
    "payment_methods": ["a2aa41cdb9", "b0b0c88f09"],
    "receipt" : {...}
  }'
  • status: Forage will notify you of the order payment's status. It will be succeeded or cancelled.
  • payments: These are references to the Payment objects stored on Forage's servers. Forage Checkout supports split tender transactions. There will be one for each payment method that is charged. You will reference these to create refunds.
  • payment_methods: These are references to the payment methods stored during the order payment session. Store these and associate them with your customer to reuse them in a future session (see section, Start a session with saved payment methods).
  • receipt: This field will contain receipt information from Forage's server to be displayed to your user. See the Receipts page for more info.

Response

{
  "redirect_url": "https://${client url}"
}
  • client url: The page you want us to redirect your customer to. This is normally an order receipt page or the next stage in your checkout flow. This URL will be disregarded if you chose to supply a succecss_redirect_url in the initial session creation request.

Start a session with saved payment methods

The client (your server) can start a session and pre-populate it with payment methods that your customer saved during a past session (see section, Notify Client of payment completion.

Client Request

curl -X 'POST' \
  'https://api.joinforage.app/v1/sessions/' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer ${token}` \
  -H 'Merchant-Account: ${merchant identifier}' \
  -H 'Idempotency-Key: def6789' \
  -d '{
    "snap_total": 120.25,
    "ebt_cash_total": 79.75,
    "remaining_total": 10.00,
    "success_redirect_url": "https://www.joinforage.com/status=SUCCEEDED",
    "cancel_redirect_url": "https://www.joinforage.com/status=CANCELED",
    "payment_methods": ["a2aa41cdb9", "b0b0c88f09"]
  }'

Response

{
  "ref": "d32eb8aa69",
  "snap_total": 120.25,
    "ebt_cash_total": 79.75,
    "remaining_total": 10.00,
  "status": "draft",
  "success_redirect_url": "https://www.joinforage.com/status=SUCCEEDED",
  "cancel_redirect_url": "https://www.joinforage.com/status=CANCELED",
  "redirect_url": "https://joinforage.app/sessions?order=d32eb8aa69&payment_methods=a2aa41cdb9&payment_methods=b0b0c88f09",
  "payment_methods": ["a2aa41cdb9", "b0b0c88f09"]
}