Changelog

This page details every change introduced with every supported version of the Forage API. Each version is named after its release date, following the YYYY-MM-DD convention.

2024-08-30

• Payout Summary API now shows ACH information instead of daily aggregations. This means each result in the API corresponds to an ACH made to the customer’s bank account. The API response has been restructured.
  • The contents of the response is semantically the same for most as they are disbursed on a daily schedule.
  • Each entry in the old reports corresponded to an ACH for customers that receive daily settlements. For other merchants where disbursements are made on a monthly aggregated amount, in the old Payout Report, they would see a result for each day’s aggregation, but the one ACH they receive that month is a sum of that month’s daily aggregations. In the new report, they will only see one entry per ACH meaning they will only see one entry for a month (with the amount equal to the sum of that month’s transactions) because it's only disbursed once that month.
• Payout Transaction Report:
  • “Payout” in this case is now referring to an ACH rather than a daily aggregation
  • The meaning of the query parameter “payout_id” represents an ACH (Forage PayoutGroup) rather than a daily aggregation (Forage PlannedDisbursement): https://{environment}.joinforage.app/reporting/payouts/{payout_id}/transactions/
  • API response fields naming has changed for a few fields. merchant_payout_id and platform_payout_id now refer to a single ACH.
• Transaction Report Response
  • API response field names have changed

2024-05-07

• Updated all timestamp values in API response objects to UTC.

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

• Updated the reporting endpoints to use cursor instead of offset 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 original customer_id request parameter. Use psp_customer_id to share a credit/debit TPP customer ID with Forage.
• Added a customer_id request parameter, required to perform balance checks. Use customer_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/
  • 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.
• Added an external_order_id request parameter. Use external_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/
  • GET requests to the above endpoints and to /reporting endpoints return the external_order_id, if available.

Original unversioned release

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