HomeGuidesReference
Log In
Reference

Order Payments

An OrderPayment object represents a one-time charge to an existing PaymentMethod that is applied to a specific Order.

✅

OrderPayment objects are only relevant to Custom and Fully Hosted integrations.

If you’re building with a Forage SDK, then use the Payments endpoints.

When you create a Session that initializes an instance of the Forage Checkout UI, Forage creates a corresponding Order. You can manage payments associated with the Order using the OrderPayment resource.

With the Forage Payments API, you can:

📘

OrderPayment endpoints are most critical to Custom integrations.

You need to create an OrderPayment after initializing a Custom Payment Capture Session to process the customer’s transaction. To get the transaction outcome, you need to send a request to retrieve the OrderPayment. Learn more in the Custom integration overview about how the Custom Payment Capture flow works.

OrderPayment object

{
  "ref": "93c7dad6b5",
  "funding_type": "ebt_snap",
  "amount": "20.00",
  "description": "EBT SNAP payment",
  "metadata": {},
  "payment_method": "485dffb5b0",
  "created": "2023-10-05T17:38:26.698516-07:00",
  "updated": "2023-10-05T17:38:26.698540-07:00",
  "status": "requires_confirmation",
  "last_processing_error": null,
  "success_date": null,
  "tpp_lookup_id": null,
  "customer_id": "abc123",
  "external_order_id": null,
  "refunds": [],
  "order": "dee3c3045e"
}

Properties

PropertyTypeDescription
refstringA unique reference hash for the Forage OrderPayment object.
funding_typestringA string that represents the type of tender. One of:

- benefit

- ebt_cash
- ebt_snap
amountstringA positive decimal number representing how much to charge the PaymentMethod in USD. Precision to the penny is supported. 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 an OrderPayment for each charge.
descriptionstringA string that describes the OrderPayment.
metadataobjectA set of optional, merchant-defined key-value pairs that can be added to an object.

For example, some merchants attach their credit card processor’s ID for the customer making the payment.

If there’s no additional information that you’d like to add, then pass an empty object as the value.
payment_methodstringThe unique reference hash for the existing Forage PaymentMethod that is to be charged in this transaction.
createdISO 8601 date-time stringA UTC-8 timestamp of when the OrderPayment was created.
updatedISO 8601 date-time stringA UTC-8 timestamp of when the OrderPayment was last updated.
statusstringThe 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_errorobjectThe code and message values corresponding to the most recent Payments API error.
success_dateISO 8601 date-time stringA UTC-8 timestamp of when the status of the OrderPayment is succeeded. This value is always null when the object is first created.
tpp_lookup_idstringThis 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.
customer_idstringA unique ID for the end customer making the payment.

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.

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 Capture Session for the same customer, then the customer_id should be the same in both requests.
external_order_idstringA 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 a merchant to map order IDs in their system to corresponding Forage Order IDs.
refundsarrayAn array of the unique reference hashes for any OrderRefunds associated with this OrderPayment.
orderstringA unique reference hash for the Order, as passed in the request to create the OrderPayment.
merchant_fixed_settlementnumberThe fixed amount in USD that should be restored to the merchant from EBT Cash payments prior to splitting by the platform_fee. Precision to the penny is supported.

This field is only returned if it was passed in the original request to create the OrderPayment.
platform_fixed_settlementnumberThe fixed amount in USD that should be restored to the platform from EBT Cash payments prior to splitting by the platform_fee. Precision to the penny is supported.

This field is only returned if it was passed in the original request to create the OrderPayment.
external_location_idstringA 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.

Example requests

Create an OrderPayment

curl --request POST \
     --url https://api.sandbox.joinforage.app/api/orders/{order_ref}/payments/ \
     --header 'Authorization: Bearer <authentication-token>' \
     --header 'Idempotency-Key: 123e4567e8' \
     --header 'Merchant-Account: <merchant-account>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "amount": 20.00,
  "funding_type": "ebt_snap",
  "description": "An EBT SNAP payment"
  "metadata": {},
  "customer_id": "abc123",
  "payment_method": "<payment-method-ref>"
}
'

📘

POST /orders/{order_ref}/payments/ documentation

Retrieve all OrderPayments for an Order

curl --request GET \
     --url https://api.sandbox.joinforage.app/api/orders/{order_ref}/payments/ \
     --header 'Authorization: Bearer <authentication-token>' \
     --header 'Merchant-Account: <merchant-account>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json'

📘

GET /orders/{order_ref}/payments/ documentation

Retrieve an OrderPayment

curl --request GET \
     --url https://api.sandbox.joinforage.app/api/orders/{order_ref}/payments/{payment_ref} \
     --header 'Authorization: Bearer <authentication-token>' \
     --header 'Merchant-Account: <merchant-account>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json'

📘

GET /orders/{order_ref}/payments/{payment_ref}/ documentation

Update an OrderPayment

curl --request POST \
     --url https://api.sandbox.joinforage.app/api/orders/{order_ref}/payments/{payment_ref}/ \
     --header 'Authorization: Bearer <authentication-token>' \
		 --header 'Idempotency-Key: 123e4567e8' \
     --header 'Merchant-Account: <merchant-account>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json'\
     --data '
{
  "amount": 20.00,
  "funding_type": "ebt_snap",
  "description": "An updated description"
  "metadata": {}, 
  "payment_method": "<payment-method-ref>"
}
'

📘

POST /orders/{order_ref}/payments/{payment_ref}/ documentation

Cancel an OrderPayment

curl --request POST \
     --url https://api.sandbox.joinforage.app/api/orders/{order_ref}/{payment_ref}/cancel/ \
     --header 'Authorization: Bearer <authentication-token>' \
     --header 'Merchant-Account: <merchant-account>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json'

📘

POST /orders/{order_ref}/payments/{payment_ref}/cancel/ documentation