Update an OrderPayment

patch

https://{environment}.joinforage.app/api/orders/{order_ref}/payments/{payment_ref}/

Update `OrderPayment` Server-Side Only

To keep your app secure, requests to update an OrderPayment should only be generated on the server-side.

A PATCH request to /orders/{order_ref}/payments/{payment_ref}/ updates an existing Forage OrderPayment.

On success, the API responds with the updated OrderPayment object.

The status property of the OrderPayment determines what data can be updated. If the status is processing, canceled, or succeeded, then only the following Payment fields can be modified:

metadata
external_order_id

During these statuses, Forage ignores attempts to update other OrderPayment fields.

Path Params

order_ref

string

required

A unique reference hash for the Forage Order object, returned when the order’s parent Session was created.

payment_ref

string

required

A unique reference hash for the Forage OrderPayment object, returned when the OrderPayment was created.

Body Params

Object which represents a single charge of a given amount to one payment method

amount

number

A positive decimal number that represents how much to charge the PaymentMethod in USD. Precision is supported to the penny. The minimum amount that can be charged is 0.01. To differentiate between a SNAP and an EBT Cash charge on the same EBT Card, use the funding_type field. If you need to charge both funding types, then create a Payment for each charge.

funding_type

string

enum

The payment instrument type. Use this field to differentiate between a SNAP (ebt_snap) and an EBT Cash (ebt_cash) charge on the same EBT Card. If you need to charge both funding types, then create a Payment for each charge. Use credit_payfac for all charges to HSA/FSA cards. credit_tpp is the funding type assigned to non-EBT payment objects created via a Fully Hosted Checkout integration.

Allowed:

payment_method

string

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

⚠️ Exception: POS integrations do not need to provide a payment_method when creating a payment.

delivery_address

object

⚠️ Exception: If the purchase is made in-store via a POS Terminal, then a delivery_address is not required when creating a Payment.

The address for delivery or pickup of the Order. Per FNS regulations, this value must always be provided. If the Order is for pickup, then use the merchant address.

is_delivery

boolean

⚠️ Exception: If the purchase is made in-store via a POS Terminal, then a is_delivery is not required when creating a Payment.

Whether the order is for delivery or pickup. This information is required per FNS regulations. Defaults to false if not provided.

description

string

A description of the payment.

metadata

object

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.

platform_fee

number

An optional field, for use by a platform supporting multiple merchants, that indicates the percentage cut of each payment that the platform charges as a fee.

platform_fixed_settlement

number

The fixed amount in USD that a platform takes from EBT Cash payments prior to splitting by the platform_fee. Precision is supported to the penny.

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.

tpp_lookup_id

string

An identifier for the credit/debit TPP.

For Stripe integrations, the client secret for a Stripe PaymentIntent.

customer_id

string

length ≤ 64

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

length ≤ 64

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_destination_account

string

A unique reference hash for the bank account that is to receive funds settlement for this payment. Use this field if you're settling funds across multiple merchant bank accounts. Reach out to your Forage account manager for details on generating a hash.

Defaults to the hash for the default merchant bank account if not provided.

pos_terminal

object

⚠️ This param is only supported for POS Terminal integrations. Do not use this param for online transactions.

An object that details information about the POS Terminal that processes the payment.

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.

Headers

Authorization

string

required

An OAuth 2.0 authentication token that validates the request. Send a POST to the /o/token/ endpoint to generate an authentication token. 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.

Idempotency-Key

string

required

An alphanumeric key that clients can use to identify repeated requests that are dropped in transit. Generate a distinct key for every unique request and only re-use keys for retries.

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

Personally Identifiable Information

200OK - Success

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

401Unauthorized

403Forbidden

404Not Found - The requested resource was not found.

409Conflict

429Too Many Requests

500Internal Server Error