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 populatedreceipt
data. Earlier versions return thereceipt
value asnull
, so to retrieve the data you need to sendGET
requests to/payments/{payment_ref}/refunds/{refund_ref}/
until thestatus
of the refund issucceeded
.
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:
- Collect the customer's PIN using Forage’s POS SDK.
- At the appropriate point in your refund workflow, call this endpoint to initiate the refund.
- 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
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.