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:
- Determine the Forage version that includes the most critical features to your integration.
- Set that as the default version in the Forage dashboard API settings (sandbox, production)
- 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
API-Version
Request Header for any exceptions to the defaultTo 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 separatesnap_total
orebt_cash_total
request body parameters.- With this change, Forage automatically creates associated
OrderPayments
for the Capture Session.
- With this change, Forage automatically creates associated
- Added a
PATCH
endpoint to Update an OrderPayment.
2024-02-15
- Updated the reporting endpoints to use
cursor
instead ofoffset
pagination.
2024-01-08
- Updated the Create a PaymentRefund and Create a refund for part of an Order endpoints to fetch the refund response synchronously with populated receipt data.
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 a PaymentMethod:
/payment_methods/
- Create an OrderPayment:
/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 a Payment:
/payments/
- Create an OrderPayment:
/orders/{order_ref}/payments/
- Create an OrderRefund:
/orders/{order_ref}/refunds/
- Create a PaymentRefund:
/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"
]
}
'