Sign in

v1

latestOpenAPI 3.0.02026-07-244352379.2 KB
Order Payments

Retrieve all OrderPayments for an Order

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.

get/api/orders/{order_ref}/payments/

Headers

Authorizationstring 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-Accountstring 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-Versionstring

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

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

The minimum amount that can be charged is 0.01.

descriptionstring required

A string that describes the OrderPayment.

metadataobject 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_methodstring required

The unique reference hash for the existing Forage PaymentMethod that is to be charged in this transaction.

customer_idstring

⚠️ 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_idstring

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_settlementnumber

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_settlementnumber

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_idstring

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.

refstring

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_errorobject

The code and message values corresponding to the most recent Payments API error.

createdstring date-time

A UTC timestamp, represented as an ISO 8601 date-time string, of when the OrderPayment was created.

updatedstring date-time

A UTC timestamp, represented as an ISO 8601 date-time string, of when the OrderPayment was last modified.

success_datestring date-time

A UTC timestamp, represented as an ISO 8601 date-time string, of when the status of the OrderPayment is succeeded. This value is always null when the OrderPayment is first created.

refundsstring[]

An array of the unique reference hashes for any OrderRefunds associated with this OrderPayment.

tpp_lookup_idstring

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.

orderstring

A unique reference hash for the parent Order, as passed in the request to create the OrderPayment.

Example response

[
  {
    "merchant_fixed_settlement": 5.11,
    "platform_fixed_settlement": 5.11,
    "external_location_id": "6e3b2ff7-51c8-4c64-befa-2eac90f7c3e9",
    "ref": "cc3175bfea",
    "status": "requires_confirmation",
    "created": "2021-06-16T00:11:50.000000Z",
    "updated": "2021-06-16T00:11:50.000000Z",
    "success_date": "2021-06-16T00:11:50.000000Z",
    "refunds": [
      "ac47392bb1"
    ],
    "tpp_lookup_id": "pi_1DpdZq2eZvKYlo2CAYyzTr8j_secret_lxr4crBJP4txbrg7sqit0XQQO",
    "order": "340129aff3"
  }
]