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 not be resolved by the time you receive a response from the Forage server. Therefore, you will need to poll the GET /api/orders/<order_ref>/refunds/<refund_ref> endpoint in order to find out whether the refund succeeded or failed.