--- title: "Retrieve all OrderPayments for an Order" method: GET path: "/api/orders/{order_ref}/payments/" tags: ["Order Payments"] --- # Retrieve all OrderPayments for an Order `GET /api/orders/{order_ref}/payments/` A `GET` request to `/orders/{order_ref}/payments/` retrieves all `OrderPayments` associated with the provided `order_ref`. On success, the API responds with an array of `OrderPayments`. ## Headers - `Authorization` string, required - `Merchant-Account` string, required - `API-Version` string ## Response `200` __OK__ - Success - OrderPaymentResponse[] - `funding_type` 'benefit' | 'credit_tpp' | 'ebt_cash' | 'ebt_snap', required — A string that represents the type of tender. One of: - `benefit` - `credit_tpp` - `ebt_cash` - `ebt_snap` - `amount` number, required — A positive decimal number that represents how much to charge the `PaymentMethod` in USD. Precision is supported to the penny. This value must match the `ebt_cash_total` or `snap_total` value that was passed in the request that [created the Custom Capture Session](https://docs.joinforage.app/reference/create-capture-session), depending on the `funding_type`. If you need to charge both funding types, then create an `OrderPayment` for each charge, using the same `order_ref` returned when the order's parent [Payment Capture Session was created](https://docs.joinforage.app/reference/create-capture-session). The minimum amount that can be charged is `0.01`. - `description` string, required — A string that describes the `OrderPayment`. - `metadata` object, required — A required object containing merchant-defined key-value pairs to provide additional context for the payment. Merchants should use this field to store **reference information** relevant to the transaction (for example, order details, system identifiers, or tracking data). This helps link the payment to records within their system. Pass an empty object (`{}`) if no additional information is available. > ⚠️ Personally Identifiable Information > > **Do not include personally identifiable information (PII)** such as names, emails, or payment details. - `payment_method` string, required — The unique reference hash for the existing Forage [`PaymentMethod`](https://docs.joinforage.app/reference/payment-methods) that is to be charged in this transaction. - `customer_id` string — **⚠️ If you’re integrating Forage with a POS Terminal, then do not use this param. It is only supported for online transactions.** A unique identifier for the end customer making the payment. Forage automatically adds the `customer_id` to the Session's corresponding `Order` and `OrderPayments`. This field helps Forage's servers more quickly identify the customer associated with the request. While `customer_id` is not technically required, if you omit it then requests could take longer to process. **It is strongly recommended to pass customer_id.** If you're providing your internal customer ID, then we recommend that you hash the value before sending it on the payload. Each customer should only have one unique `customer_id`. For example, if you create both a `PaymentMethod` and a Forage `Session` (Fully Hosted or Custom) or `Payment` (SDK) for the same customer, then the `customer_id` should be the same in both requests to ensure continuity of stored payment methods. - `external_order_id` string — A unique identifier for the order as created by the merchant or platform (not Forage). When a merchant or platform passes this order ID to Forage, it persists in each Forage transaction related to the `Order`. This field enables merchants to map order IDs in their system to corresponding Forage `Order` IDs. **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. - `merchant_fixed_settlement` number — The fixed amount in USD that should be restored to the merchant from EBT Cash payments prior to splitting by the `platform_fee`. Precision is supported to the penny. - `platform_fixed_settlement` number — The fixed amount in USD that should be restored to the platform from EBT Cash payments prior to splitting by the `platform_fee`. Precision is supported to the penny. - `external_location_id` string — A unique identifier, provided by the merchant or platform (not Forage), that indicates the physical fulfillment location for the order. For example, this field could specify which location of a grocery store chain fulfilled an order. - `ref` string — A unique reference hash for the Forage `OrderPayment` object. _Note:_ `receipt.ref_number` equals `ref`. - `status` 'canceled' | 'failed' | 'processing' | 'requires_confirmation' | 'succeeded' — The status of the `OrderPayment`. One of: - `canceled`: The `OrderPayment` object can't be used. - `failed`: If the error is temporary, then this `OrderPayment` can be resubmitted for capture without modification. Check the `receipt.message` field for a description of the error. - `processing`: The outcome of the `OrderPayment` is pending. - `requires_confirmation`: The `OrderPayment` hasn't been submitted for processing. - `succeeded`: The `OrderPayment` has been successfully processed and will be included in settlement. It can't be changed. - `last_processing_error` object — The code and message values corresponding to the most recent [Payments API error](https://docs.joinforage.app/reference/errors#payments-api-errors). - `created` string, date-time — A UTC timestamp, represented as an [ISO 8601 date-time](https://www.iso.org/iso-8601-date-and-time-format.html) string, of when the `OrderPayment` was created. - `updated` string, date-time — A UTC timestamp, represented as an [ISO 8601 date-time](https://www.iso.org/iso-8601-date-and-time-format.html) string, of when the `OrderPayment` was last modified. - `success_date` string, date-time — A UTC timestamp, represented as an [ISO 8601 date-time](https://www.iso.org/iso-8601-date-and-time-format.html) string, of when the `status` of the `OrderPayment` is `succeeded`. This value is always `null` when the `OrderPayment` is first created. - `refunds` string[] — An array of the unique reference hashes for any `OrderRefunds` associated with this `OrderPayment`. - `tpp_lookup_id` string — This value is always null for `OrderPayments` resulting from Custom Sessions. It’s most relevant to Fully Hosted Sessions, which process credit/debit payments. A value that merchants can use to associate this payment with a credit/debit payment processed by a third party processor. For Stripe integrations, this is the client secret for a [`PaymentIntent`](https://stripe.com/docs/api/payment_intents). - `order` string — A unique reference hash for the parent `Order`, as passed in the request to create the `OrderPayment`. ## Other responses - `400` — __Bad request__ - The request was not accepted because of an error in the request body or path. - `401` — Unauthorized - `404` — __Not Found__ - The requested resource was not found. - `429` — Too Many Requests - `500` — Internal Server Error --- [API](https://skmtc.dev/joinforage/apis/forage-payments-api.md) · [All operations](https://skmtc.dev/joinforage/apis/forage-payments-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/joinforage/forage-payments-api/revisions/4b7212706fae/schema)