Retrieve all Payments for a merchant order ID

get

https://{environment}.joinforage.app/api/payments/

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 Params

external_order_id

string

required

Defaults to 1f2ee410-5b47-4130-aec2-40f5eb2108f5

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.

with_refunds

boolean

Defaults to false

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

Authorization

string

required

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>.

Merchant-Account

string

required

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.

API-Version

string

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.

Responses

200OK - Success

400Bad request - The request was not accepted because of an error in the request body or path.

401Unauthorized

404Not Found

409Conflict

429Too Many Requests

500Internal Server Error