2024-08-30

1. Payout Summary

The Payout Summary API now displays ACH disbursement details instead of daily aggregations. Each API result corresponds directly to an ACH transfer to the customer’s bank account.

• For Daily Settlements: The API response remains largely unchanged, as daily disbursements continue to match previous daily aggregations.
• For Monthly Settlements: Previously, the report displayed daily aggregations, even if only one ACH was made for the month. The updated report now consolidates these into a single entry per ACH, reflecting the total amount disbursed for the month.

Field Changes for Payout Summary

• Deleted Fields
  • Deleted merchant_name.
  • Deleted tenant_name.
  • Deleted external_location_id.
• Renamed Fields
  • Renamed merchant_fns_number to fns_id.
  • Consolidated merchant_settlement_date and platform_settlement_date into the field payout_issued_date.
  • Renamed the field fee to forage_fee.
• New Fields
  • Added merchant_id - A ten character identifier for a merchant, provided by Forage. We now display this instead of the merchant name.
  • Added expected_deposit_date - A date-stamp of when Forage expects the payout to be deposited.
  • Added total_positive_adjustments - If any, the total arbitrary amount in USD that has been added to the settlement.
  • Added total_negative_adjustments - If any, the total arbitrary amount in USD that has been deducted from the settlement.

2. Payout Transaction Report

• In the Payout Transaction Report, “Payout” now refers to an ACH, rather than a daily aggregation.
• The query parameter payout_id now represents an ACH (Forage PayoutGroup) rather than a daily aggregation (Forage PlannedDisbursement). See https://{environment}.joinforage.app/reporting/payouts/{payout_id}/transactions/
• API response field names has changed for a few fields. merchant_payout_id and platform_payout_id now refer to a single ACH.
• For the Transaction Report response, API response field names have changed. See below.

Field Changes for Payout Transaction Report and Transaction Report

• Deleted Fields
  • Deleted retrieval_ref.
  • Deleted zipcode.
  • Deleted state_code.
• Renamed Fields
  • Renamed order_ref to order_id
  • Renamed payment_ref to payment_id
  • Renamed refund_ref to refund_id
  • Renamed merchant_fns_number to fns_id
  • Consolidated merchant_settlement_date and platform_settlement_date into payout_issued_date.
  • Renamed gross_merchandise_value to transaction_amount
  • Renamed fee to forage_fee
  • Renamed payout_id to merchant_payout_id / platform_payout_id. A transaction can now be included in both a merchant payout and a platform payout when platform settlement is enabled (for example, part of the funds are allocated to the merchant and part to the platform).
• New Fields
  • Added merchant_id - A ten character identifier for a merchant, provided by Forage. We now display this instead of the merchant name.
  • Added expected_deposit_date - A date-stamp of when Forage expects the payout to be deposited.
  • Added chargeback_id - A unique ID for the chargeback transaction. Used if the transaction_type is Chargeback.

2024-05-07

• All timestamp values in API response objects are now returned in UTC.

2024-03-05

• Updated the Create a Custom Payment Capture Session endpoint to accept a payment_details object instead of snap_total or ebt_cash_total parameters. This change allows Forage to automatically create OrderPayments for the Capture Session.

• Added a PATCH endpoint to Update an OrderPayment.

2024-02-15

• Changed the reporting endpoints to use cursor pagination instead of offset pagination.

2024-01-08

• Updated the Create a PaymentRefund and Create a refund for part of an Order endpoints to return the refund response synchronously with receipt data.

2023-05-15

1. customer_id Parameter

• Introduced a new customer_id parameter, required for balance checks.
• Use customer_id to share a merchant-specific customer ID with Forage.
• This parameter enables merchants to link their own customer identifiers with Forage systems.

POST Endpoints Supporting 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 Responses

• The above endpoints return customer_id if it was included in the request.

Impact on Balance Checks

• If you want Forage to perform a balance check, you must pass the customer_id parameter in the request.

2. psp_customer_id Parameter

• Introduced psp_customer_id to replace the original customer_id parameter.
• Use psp_customer_id to share a credit/debit TPP customer ID with Forage.
• This parameter is specific to payment processing with third-party providers (TPPs).

3. external_order_id Parameter

• Added an external_order_id to enable merchants to match their own order IDs with Forage order IDs.

POST Endpoints Supporting 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 Responses

• The above endpoints and /reporting endpoints return external_order_id, if available.

Initial API Release (unversioned)

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