Sign in

v1

latestOpenAPI 3.0.02026-07-244352379.2 KB
Payment Refunds

Create a PaymentRefund

⚠️ Refund Requests Must Be Server-Side

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

⚠️ API Version Requirements

You must use Forage version 2024-01-08 or higher for this endpoint to return populated receipt data. Earlier versions return the receipt value as null, so to retrieve the data you need to send GET requests to /payments/{payment_ref}/refunds/{refund_ref}/ until the status of the refund is succeeded.

A POST request to /payments/{payment_ref}/refunds/ tells Forage’s servers to refund an existing Payment object. Funds are refunded to the originally charged PaymentMethod.

On success, Forage automatically begins processing the refund, so this request has immediate financial side effects.

The API responds with a Forage PaymentRefund object that represents the transaction and an HTTP 201 status code.

Deferred refunds

ForageTerminalSDK integrations use this endpoint to complete deferred refunds. Here are the steps:

  1. Collect the customer's PIN using Forage’s POS SDK.
  2. At the appropriate point in your refund workflow, call this endpoint to initiate the refund.
  3. If an error occurs (e.g., an Invalid PIN), relay the message back to the POS client immediately so the user is notified promptly.

HTTP 201

HTTP 201 is returned even if the refund attempt fails because Forage creates a PaymentRefund object to preserve a record of the refund regardless of the transaction outcome. To confirm that the outcome is a success, check that the status of the PaymentRefund is succeeded.

If the status is failed, then for Forage version 2024-01-08 or higher inspect the receipt.message field of the response for a description of the error. For earlier Forage versions, send a GET to /payments/{payment_ref}/refunds/ to retrieve updated receipt data.

post/api/payments/{payment_ref}/refunds/

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 of the Payment to refund in USD. If a partial refund, then this value does not need to equal the amount field of the original Payment. Precision is supported to the penny.

The minimum amount that can be refunded is 0.01.

reasonstring required

A string that describes why the Payment is to be refunded.

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.

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

Example request

{
  "merchant_fixed_settlement": 5.11,
  "platform_fixed_settlement": 5.11,
  "pos_terminal": {
    "provider_terminal_id": "1234"
  }
}

Response

Created - Success

amountnumber required

A positive decimal number that represents how much of the Payment to refund in USD. If a partial refund, then this value does not need to equal the amount field of the original Payment. Precision is supported to the penny.

The minimum amount that can be refunded is 0.01.

reasonstring required

A string that describes why the Payment is to be refunded.

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.

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

refstring

A unique reference hash for the PaymentRefund.

payment_refstring

The unique reference hash for the Payment to be refunded, as passed in the path params of the request.

funding_type'ebt_snap' | 'ebt_cash' | 'credit_tpp' | 'credit_payfac'

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

  • benefit
  • credit_tpp
  • credit_payfac
  • ebt_cash
  • ebt_snap
createdstring date-time

A UTC timestamp that indicates when the OrderRefund was created, represented as an ISO 8601 date-time string.

updatedstring date-time

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

status'canceled' | 'failed' | 'processing' | 'succeeded'

The status of the refund. One of:

  • canceled: The PaymentRefund object can't be used.
  • failed: Check receipt.message for a description of the error.
  • processing: The outcome of the refund is pending. This status is not returned if you’re using Forage version 2024-01-08 or higher.
  • succeeded: The refund has been successfully processed and will be included in settlement. It can't be changed.
last_processing_errorobject nullable

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

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.

Example response

{
  "merchant_fixed_settlement": 5.11,
  "platform_fixed_settlement": 5.11,
  "pos_terminal": {
    "provider_terminal_id": "1234"
  },
  "ref": "45e3f12a90",
  "payment_ref": "b873fe62dc",
  "funding_type": "ebt_snap",
  "created": "2021-06-16T00:11:50.000000Z",
  "updated": "2021-06-16T00:11:50.000000Z",
  "status": "succeeded",
  "receipt": {
    "ref_number": "45e3f12a90",
    "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": "Refund",
    "created": "2021-06-16T00:11:50.000000Z-07:00"
  },
  "previous_errors": []
}