Query the Forage API to issue refunds

Forage integrates with your existing order management system through RESTful API. Your system can securely send requests to our Refunds resource.

The following sections provide details on the different refund flows (partial or full refund).

Start a Refund

The client (your server) will start a refund transaction with Forage's backend through RESTful API. A succesful response will yield a 201 status code. This means Forage created the refund and is processing it.

The API supports multiple types of refund requests:

Refund the whole order.
Partially refund an order.

Refund the whole order

An order can be made up of multiple payments, because of the split tender requirement. We make it easy to refund every payment within an order.

Client Request

curl -X 'POST' \
  'https://api.joinforage.app/orders/d32eb8aa69/refund_all' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer ${token}` \
  -H 'Merchant-Account: ${merchant identifier}' \
  -H 'Idempotency-Key: abc1234' \
  -d '{
    "reason": "failed to deliver",
    "metadata" : {}
  }'

Response

{
  "ref": "d32eb8aa69",
  "snap_total": 120.25,
  "non_snap_total": 79.75,
  "status": "succeeded",
  "payments": ["8d1b5637aa", "666e07397b"],
  "refunds": ["9d1f5651dc", "936e08ab66"]
}

refunds: These are references to the refund objects created for the refund_all request.

Partially refund an order

An order can be made up of multiple payments, because of the split tender requirement. We make it easy to refund single payments within an order.

Client Request

curl -X 'POST' \
  'https://api.joinforage.app/orders/d32eb8aa69/refunds/' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer ${token}` \
  -H 'Merchant-Account: ${merchant identifier}' \
  -H 'Idempotency-Key: abc1234' \
  -d '{
    "snap_amount": 120.25,
    "non_snap_amount": 0.0,
    "payment": "8d1b5637aa",
    "reason": "failed to deliver"
  }'

snap_amount: Set the amount to be refunded to the SNAP balance of the original payment method (SNAP EBT).
non_snap_amount: Set the amount to be refunded to the non-SNAP balance of the original payment method (EBT Cash).
payment: Reference the Payment object created during the original order payment session.
reason: Add a reason for the refund.

Response

{
  "ref":"9d1f5651dc"
  "snap_amount": 120.25,
  "non_snap_amount": 0.0,
  "payment": "8d1b5637aa",
  "reason": "failed to deliver",
  "status": "succeeded",
  "created": "2021-05-26T01:54:18.782Z",
  "updated": "2021-05-26T01:54:18.782Z",
  "receipt" : {...}
}

The Refund will be resolved by the time you receive a response from the Forage server. Therefore, there is no need to wait for the webhook to arrive in order to determine the outcome of the refund. The following section describes an optional webhook request that Forage will make to your application when a Refund is processed.

Refund Webhook

Forage will send a request to your server when the refund's "processing" status has changed to "succeeded" or "failed".

Forage Request

{
  "ref":"9d1f5651dc"
  "snap_amount": 120.25,
  "non_snap_amount": 0.0,
  "payment": "8d1b5637aa",
  "reason": "failed to deliver",
  "status": "succeeded",
  "created": "2021-05-26T01:54:18.782Z",
  "updated": "2021-05-26T01:54:18.782Z"
  "receipt" : {...}
}

receipt: This field will contain receipt information from Forage's server to be displayed to your user. See the Receipts page for more info.

Response

Respond with a 200 status code or else Forage will retry the request.