Sign in

v1

latestOpenAPI 3.0.02026-07-244352379.2 KB
Payments

Create a Payment

⚠️ Payment Creation Must Be Server-Side

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

A POST request to /payments/ tells Forage’s servers how much to charge an existing PaymentMethod.

On success, the API responds with a Forage Payment object that represents the one-time charge. You need to pass the ref response value to an SDK function to authorize and capture the payment, one of:

📘 Use customer_id When Creating Payments

Pass customer_id in the request to Create a Payment. customer_id helps Forage's servers more quickly identify and associate the correct customer with the Payment. While customer_id is not technically a required parameter, if you omit it then the request to create the Payment 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 a Payment 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.

⚠️ Payments Expire After 30 Minutes

Payment objects expire after 30 minutes. If a Payment is not captured or canceled within 30 minutes of when it's created, then it expires. To attempt the transaction again, create a new Payment.

post/api/payments/

Headers

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

Idempotency-Keystring 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-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.

Request body

amountnumber required

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'ebt_snap' | 'ebt_cash' | 'credit_tpp' | 'credit_payfac' required

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.

payment_methodstring required

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.

is_deliveryboolean required

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

descriptionstring required

A description of the payment.

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

platform_feenumber

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_settlementnumber

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

tpp_lookup_idstring

An identifier for the credit/debit TPP.

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

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_destination_accountstring

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.

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.

Example request

{
  "tpp_lookup_id": "pi_1DpdZq2eZvKYlo2CAYyzTr8j_secret_lxr4crBJP4txbrg7sqit0XQQO",
  "external_location_id": "6e3b2ff7-51c8-4c64-befa-2eac90f7c3e9"
}

Response

OK - Success

amountnumber

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'ebt_snap' | 'ebt_cash' | 'credit_tpp' | 'credit_payfac'

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.

payment_methodstring

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.

is_deliveryboolean

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

descriptionstring

A description of the payment.

metadataMetadataObject

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_feenumber

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_settlementnumber

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

tpp_lookup_idstring

An identifier for the credit/debit TPP.

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

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_destination_accountstring

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.

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 Payment object.

Note: receipt.ref_number equals ref.

You need to pass this value to the front-end SDK method that captures the payment.

merchantstring

A string that represents a unique merchant ID that Forage provides during onboarding.

status'requires_confirmation' | 'processing' | 'canceled' | 'succeeded' | 'failed' | 'authorized'

The status of the Payment. One of:

  • canceled: The Paymentobject can't be used.
  • failed: If the error is temporary, then this Payment can be resubmitted for capture without modification. Check the receipt.message field for a description of the error.
  • processing: The outcome of the Payment is pending.
  • requires_confirmation: The Payment hasn't been submitted for processing.
  • succeeded: The Payment has been successfully processed and will be included in settlement. It can't be changed.
  • authorized: The Payment has been authorized, but not yet captured. Only applicable to HSA payments.
createdstring date-time

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

updatedstring date-time

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

expires_atstring date-time

A UTC timestamp of when the Payment will expire if it is not captured or canceled, set to 30 minutes from when the Payment is created.

If the status of the Payment is succeeded or canceled, then the expires_at value is null.

success_datestring date-time

A UTC timestamp of when the Payment was successfully processed, represented as an ISO 8601 date-time string. This value is null until the Payment enters the succeeded or partial_capture states.

refundsstring[]

References to the Refunds attached to this payment. The format depends on the with_refunds query parameter:

  • Default behavior (when with_refunds is false or omitted): Array of refund reference strings
  • Expanded behavior (when with_refunds=true): Array of full Refund objects with complete refund details
receiptobject

Most of the information that you're required to display to the customer, according to FNS regulations.

This field is null if the data that populates the receipt is not yet available.

The total amount paid by the customer is snap_amount + ebt_cash_amount + other_amount. This amount will be settled with the merchant after applying Forage's fees.

last_processing_errorobject

The code and message values corresponding to the most recent Payments API error. Always null when the Payment is created.

address_postal_code_check'pass' | 'fail' | 'unavailable' | 'unchecked'

The result of any check done on the delivery address zip code. One of:

  • pass: The provided information is correct and matches the data on file with the card issuer.
  • fail: The provided information is incorrect and does not match the data on file.
  • unavailable: The card issuer will not perform the check.
  • unchecked: The information was provided but has not yet been checked by the card issuer.
cvc_check'pass' | 'fail' | 'unavailable' | 'unchecked'

The result of any check done on the CVC. One of:

  • pass: The provided information is correct and matches the data on file with the card issuer.
  • fail: The provided information is incorrect and does not match the data on file.
  • unavailable: The card issuer will not perform the check.
  • unchecked: The information was provided but has not yet been checked by the card issuer.

Example response

{
  "amount": 25.99,
  "funding_type": "ebt_snap",
  "payment_method": "ac47392bb1",
  "delivery_address": {
    "city": "San Francisco",
    "country": "US",
    "line1": "1856 Market St.",
    "zipcode": "94106",
    "state": "CA"
  },
  "is_delivery": true,
  "description": "An EBT Payment",
  "metadata": {},
  "platform_fee": 0.05,
  "platform_fixed_settlement": 5.11,
  "merchant_fixed_settlement": 5.95,
  "customer_id": "cus_1234567890",
  "external_order_id": "1f2ee410-5b47-4130-aec2-40f5eb2108f5",
  "merchant_destination_account": "1bdefaa456",
  "pos_terminal": {
    "provider_terminal_id": "tbd123"
  },
  "external_location_id": "6e3b2ff7-51c8-4c64-befa-2eac90f7c3e9",
  "ref": "cc3175bfea",
  "merchant": "9000055",
  "status": "requires_confirmation",
  "created": "2021-06-16T00:11:50.000000Z-07:00",
  "updated": "2021-06-16T00:11:50.000000Z-07:00",
  "expires_at": "2021-06-16T00:41:50.000000Z-07:00",
  "success_date": "2021-06-16T00:11:50.000000Z-07:00",
  "refunds": [
    "ac47392bb1"
  ],
  "receipt": {
    "ref_number": "cc3175bfea",
    "is_voided": true,
    "snap_amount": "25.99",
    "ebt_cash_amount": "10.99",
    "other_amount": "5.99",
    "sales_tax_applied": "5.16",
    "balance": {
      "snap": "72.94",
      "non_snap": "32.16",
      "updated": "2021-06-16T00:11:50.000000Z-07:00"
    },
    "last_4": "3456",
    "message": "Approved",
    "transaction_type": "Payment",
    "created": "2021-06-16T00:11:50.000000Z-07:00"
  },
  "last_processing_error": null,
  "previous_errors": []
}