Create an OrderPayment

post

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

Outdated Endpoint

This endpoint is not relevant to Forage versions 2024-03-05 and later.

With 2024-03-05, Forage creates OrderPayments under the hood with every request to create a Custom Payment Capture Session. We strongly recommend upgrading to the latest Forage version if you haven't already.

`OrderPayment` Requests Must Be Server-Side

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

A POST request to /orders/{order_ref}/payments/ tells Forage's servers how much to charge an existing PaymentMethod to create a payment associated with an existing Order.

On success, the API responds with a Forage OrderPayment object that represents the one-time charge. The PaymentMethod is not charged until the Order is captured, after a customer submits their PIN via the Forage Checkout UI to authorize the charge.

Use `customer_id`` For OrderPayments

Pass customer_id in the request to Create an OrderPayment

customer_id helps Forage's servers more quickly identify and associate the correct customer with the OrderPayment. While customer_id is not technically a required parameter, if you omit it then the request to create the OrderPayment could take longer to process. It is strongly recommended to pass customer_id.

Each customer should only have one unique customer_id. For example, if you create both an OrderPayment and a PaymentMethod for the same customer, then the customer_id should be the same in both requests to ensure continuity of stored payment methods.

Avoid Duplicate `OrderPayment` Requests

Only create one OrderPayment per PaymentMethod associated with an Order.

The API returns a 400 if it identifies a duplicate charge. If you need to increase the amount charged to a PaymentMethod already associated with an Order, then update the corresponding OrderPayment instead of creating a new one.

Path Params

order_ref

string

required

Defaults to cc3175bfea

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

Body Params

This object represents a one-time payment, charged to a single payment method, associated with a specific Forage Order.

funding_type

string

enum

required

Defaults to ebt_snap

A string that represents the type of tender. One of:

benefit
credit_tpp
ebt_cash
ebt_snap

Allowed:

amount

number

required

Defaults to 25.99

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.

description

string

required

Defaults to An EBT payment

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

Defaults to b16673fe21

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

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

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

201Created - Success

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

401Unauthorized

404Not Found - The requested resource was not found.

409Conflict

423Locked - The request could not be completed because the target resource is currently locked.

429Too Many Requests

500Internal Server Error