v1
latestOpenAPI 3.0.02026-07-244352379.2 KBRetrieve all Payments for a merchant order ID
A GET request to /payments/ that includes the external_order_id query param retrieves a list of all of the Payments related to the order. The external_order_id corresponds to a merchant or platform's identifier for the order in their own database. Forage does not provide this value.
If a customer charges both SNAP and EBT Cash at checkout, then this endpoint could be useful to review the spending breakdown across Payment types.
Refund details: By default, the refunds field contains only refund reference strings. Include with_refunds to get complete refund information. You can pass it as &with_refunds (no =true required).
Query parameters
A unique, merchant or platform-provided identifier for the order that corresponds to their own database, as provided in the original request to create the Payment.
Only one external_order_id can be passed as a query param at a time.
You must build with Forage Version 2023-05-15 or later to use external_order_id. Either pass 2023-05-15 as the API-Version header on a per request basis, or set the version for all requests in the Forage dashboard.
Include this parameter to expand the refunds list to full Refund objects. This provides complete refund details including amount, status, reason, and other refund-specific information.
If omitted, the refunds field contains only refund reference strings. Pass as &with_refunds (no value needed). Examples may show with_refunds=true for clarity, but only the presence of the parameter is required.
Headers
An OAuth 2.0 bearer token that validates the request. You can use either a short-lived session token if the request is coming from the front-end, or an authentication token for server-side requests. Pass the token in this header after the word Bearer and a whitespace, for example Bearer <api_key>.
A unique merchant ID that Forage provides during onboarding, as in 123ab45c67. The Merchant ID can be found in the Forage sandbox or production dashboard.
The Forage version, represented as a string with the format of a YYYY-MM-DD date.
If not specified in the request header, then the version defaults to the value set in the Forage dashboard.
Response
OK - Success
Example response
{
"payments": [
{
"amount": 25.99,
"funding_type": "ebt_snap",
"payment_method": "ac47392bb1",
"delivery_address": {
"city": "San Francisco",
"country": "US",
"line1": "1856 Market St.",
"zipcode": "94106",
"state": "CA"
},
"is_delivery": true,
"description": "An EBT Payment",
"metadata": {},
"platform_fee": 0.05,
"platform_fixed_settlement": 5.11,
"merchant_fixed_settlement": 5.95,
"customer_id": "cus_1234567890",
"external_order_id": "1f2ee410-5b47-4130-aec2-40f5eb2108f5",
"merchant_destination_account": "1bdefaa456",
"pos_terminal": {
"provider_terminal_id": "tbd123"
},
"external_location_id": "6e3b2ff7-51c8-4c64-befa-2eac90f7c3e9",
"ref": "cc3175bfea",
"merchant": "9000055",
"status": "requires_confirmation",
"created": "2021-06-16T00:11:50.000000Z-07:00",
"updated": "2021-06-16T00:11:50.000000Z-07:00",
"expires_at": "2021-06-16T00:41:50.000000Z-07:00",
"success_date": "2021-06-16T00:11:50.000000Z-07:00",
"refunds": [
"ac47392bb1"
],
"receipt": {
"ref_number": "cc3175bfea",
"is_voided": true,
"snap_amount": "25.99",
"ebt_cash_amount": "10.99",
"other_amount": "5.99",
"sales_tax_applied": "5.16",
"balance": {
"snap": "72.94",
"non_snap": "32.16",
"updated": "2021-06-16T00:11:50.000000Z-07:00"
},
"last_4": "3456",
"message": "Approved",
"transaction_type": "Payment",
"created": "2021-06-16T00:11:50.000000Z-07:00"
},
"last_processing_error": null,
"previous_errors": []
}
]
}