The Forage API is versioned. A new version is released when there is a backwards-incompatible change to the API.
The API version for all of your requests is set in your account API settings in the Forage dashboard. To prevent breaking changes, the default is the oldest supported API version.
Forage strongly recommends updating the version in your API settings to the most recent release.
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.
2023-05-15
- Introduced
psp_customer_id
to replace the originalcustomer_id
request parameter. Usepsp_customer_id
to share a credit/debit TPP customer ID with Forage. - Added a
customer_id
request parameter, required to perform balance checks. Usecustomer_id
to share a merchant’s ID for a customer with Forage.- POST requests to the following endpoints accept a
customer_id
:- Create a Fully Hosted Checkout session:
/sessions/
- Create a Custom Checkout session:
/capture_sessions/
- Create an order:
/orders
- Create a payment method:
/payment_methods/
- Create a payment for a given order:
/orders/{order_ref}/payments/
- Create a payment:
/payments/
- Create a Fully Hosted Checkout session:
- GET requests to the above endpoints return the
customer_id
, if available. - This change impacts balance checks. If you want Forage to perform a balance check, you must pass a
customer_id
.
- POST requests to the following endpoints accept a
- Added an
external_order_id
request parameter. Useexternal_order_id
to match a merchant’s order ID with a Forage order ID.- POST requests to the following endpoints accept an
external_order_id
:- Create a Fully Hosted Checkout session:
/sessions/
- Create a Custom Checkout session:
/capture_sessions/
- Create an order:
/orders
- Create a payment:
/payments/
- Create a payment for a given order:
/orders/{order_ref}/payments/
- Create a refund for a given order:
/orders/{order_ref}/refunds/
- Create a refund for a given payment:
/payments/{payment_ref}/refunds/
- Create a Fully Hosted Checkout session:
- GET requests to the above endpoints and to
/reporting
endpoints return theexternal_order_id
, if available.
- POST requests to the following endpoints accept an
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"
]
}
'