HomeGuidesReference
Log In

Versioning

Forage versions the Payments API on a per endpoint basis. A new version is released when there is a backwards-incompatible change to the endpoint.

For example, Forage version 2024-03-05 updated the following endpoints:

  • Create a Custom Payment Capture Session
  • Update an OrderPayment

The version only impacted those endpoints.

If an endpoint is not included in a version update, then there is no corresponding version of that endpoint. For example, the Retrieve an Order endpoint was not included in the 2024-03-05 update, so there is no 2024-03-05 version of Retrieve an Order.

How to specify Forage versions

Because Payments API is versioned on a per endpoint basis, Forage recommends that you:

  1. Determine the Forage version that includes the most critical features to your integration.
  2. Set that as the default version in the Forage dashboard API settings (sandbox, production)
  3. If you need to use a version of an endpoint that differs from the default, then specify the API-Version Header in the request to override the dashboard settings.

Set the default version in the dashboard

Set the API version for all of your requests in the Forage dashboard API settings (sandbox, production). To prevent breaking changes, the dashboard defaults to the original unversioned release. If you’re new to Forage, then we strongly recommend updating your API settings to the most recent release.

If an endpoint does not yet support the dashboard-specified API version, then Forage automatically updates requests to that endpoint to the previous version nearest-in-time to that specified in the dashboard.

For example, if you set the 2024-03-05 version in the dashboard, then requests to Retrieve an Order default to the original unversioned release, the last version that updated the endpoint.

Use theAPI-Version Request Header for any exceptions to the default

To set an explicit API version for a request that overrides dashboard settings, send the API-Version header in the request, as in the following example:

curl --request POST \
     --url https://api.sandbox.joinforage.app/api/capture_sessions/ \
     --header 'API-Version: 2024-03-05'
     --header 'Authorization: Bearer <authentication_token>' \
     --header 'Idempotency-Key: <idempotency-key>' \
     --header 'Merchant-Account: <merchant-account>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '

{
    "success_redirect_url" : "https://www.joinforage.com/status=SUCCEEDED",
    "cancel_redirect_url" : "https://www.joinforage.com/status=CANCELED",
    "delivery_address": {
        "city": "San Francisco",
        "country": "US",
        "line1": "1857 Market St.",
        "state": "CA",
        "zipcode": "94117"
    },
    "is_delivery" : false,
    "supported_benefits": ["snap", "ebt_cash"],
    "payment_details": {
        "snap_payment": {
           "amount": 20.12,
           "metadata": {},
					 "payment_method": "fsdf45345"
           "description": "A SNAP payment",
           "funding_type": "ebt_snap"
        },
        "ebt_cash_payment": {
            "amount": 25.99,
            "metadata": {},
						"payment_method": "fsdf45345"
            "description": "An EBT Cash payment",
            "funding_type": "ebt_cash"
         }
    }
}

If you specify an API-Version in a request, then the version must exist for that endpoint. If the version does not exist for that endpoint, then Forage returns an error.

For example, if you specify 2024-03-05 in the API-Version Request Header to Retrieve an Order, then the request fails. This is because Retrieve an Order endpoint was not included in the 2024-03-05 update.

API version history

The sections below detail every supported version of the Forage API. Each version is named after its release date, following the YYYY-MM-DD convention.

2024-03-05

  • Updated the Create a Custom Payment Capture Session endpoint to accept a payment_details object instead of separate snap_total or ebt_cash_total request body parameters.
    • With this change, Forage automatically creates associated OrderPayments for the Capture Session.
  • Added a PATCH endpoint to Update an OrderPayment.

2024-02-15

2024-01-08

2023-05-15

Original unversioned release

  • Introduced split tender over SNAP, EBT Cash, and credit/debit cards.

How to override API version account settings

To override the API version in your account settings for specific requests, set the version in the API-Version request header, as in the following example:

curl --request POST \
     --url https://api.sandbox.joinforage.app/api/sessions/ \
     --header 'API-Version: 2021-12-19' \
     --header 'Merchant-Account: 1234567' \
     --header 'Authorization: Bearer sandbox_lsIZjMZ2eaS6H5SpBcsRI8mViRwKfA' \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --data '{
  "snap_total": 100,
  "ebt_cash_total": 20,
  "remaining_total": 0,
  "product_list": [],
  "success_redirect_url": "https://www.joinforage.com/status=SUCCEEDED",
  "cancel_redirect_url": "https://www.joinforage.com/status=CANCELED",
  "delivery_address": {
    "city": "San Francisco",
    "country": "US",
    "line1": "185y Market St",
    "line2": "",
    "state": "CA",
    "zipcode": "94103"
  },
  "is_delivery": false,
  "supported_benefits": [
    "snap",
    "ebt_cash",
    "non_ebt"
  ]
}
'