Record a refund

Record a full refund you have already made through your own gateway.

POST{BASE_URL}/payments/sessions/{id}/refund

Records that you refunded a succeeded payment. Localoy moves no money — refund the customer through your gateway first, then call this. A refund is always for the full session amount. Requires the PAYMENT scope.

Path parameters

idstringrequired: The session ID.

Headers

Idempotency-Keystringoptional: Up to 255 characters. See Idempotency.

Body — optional

providerReferencestring | nulloptional: Your gateway's refund reference. Up to 200 characters.
reasonstring | nulloptional: Why the payment was refunded. Up to 500 characters.

Response

dataobjectrequired: The session's settlement record.
replayedbooleanrequired: true when the refund had already been recorded.

Effects#

The session becomes REFUNDED and the order is marked refunded.
Check-ins already recorded on an event ticket order are cleared. Activity bookings keep theirs.
Localoy sends payment.updated.

Status codes#

Status	Code	Meaning
`200`	—	Recorded, or `replayed: true` if already refunded.
`400`	—	A field is invalid.
`404`	`payment_session_not_found`	No session of yours in this environment has that ID.
`409`	`payment_invalid_transition`	Only a `SUCCEEDED` session can be refunded. `details.from`, `details.to`.
`409`	`payment_session_conflict`	Another request changed the session at the same time.

cURL

curl -X POST "$LOCALOY_BASE_URL/payments/sessions/cm5s3ss10n00000000000001/refund" \
  -H "Authorization: Bearer $LOCALOY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 0b9e4c2a-6f3d-4e1b-9a7c-5d8f2e1b3c40" \
  -d '{ "providerReference": "RFD-55120", "reason": "Customer cancelled" }'

Response · 200

{
  "success": true,
  "message": "Refund recorded.",
  "data": {
    "id": "cm5s3ss10n00000000000001",
    "status": "REFUNDED",
    "refundedAt": "2026-09-27T11:20:44.090Z",
    "…": "…"
  },
  "replayed": false
}

Response · 409

{
  "success": false,
  "message": "Only a succeeded payment can be refunded; this one is PENDING.",
  "code": "payment_invalid_transition",
  "details": { "from": "PENDING", "to": "REFUNDED" },
  "requestId": "3f0c9f8e-6a1d-4f5e-9b1a-2f1c0d9e7a41"
}