Reverse a recorded payment

Request

Locally reverses one payment action in full for the visit resolved from appointment_id. Partial reversal is not part of the contract. This is a local cancellation of posting in Altegio, not a payment-provider refund. Requires Idempotency-Key.

No step-up confirmation is part of this preview contract. Refund authorization is the explicit payments:refund scope plus the subject's finance permission, with idempotency and audit on every call. A future human-confirmation flow will be added only with a complete challenge contract.

Security

OAuth2(Required scopes: payments:refund) or RestrictedKey

Path

location_idintegerrequired

Identifier of the Location. Verified against the credential on every call — a Location the credential cannot access responds with 404.

payment_idstringrequired

Opaque payment id: t<number> for money transactions, l<number> for loyalty/deposit operations. Stable between requests.

appointment_idintegerrequired

Identifier of the appointment.

Idempotency-Keystring, <= 255 charactersrequired

Client-generated unique key for this logical request (UUID recommended). A retry with the same key and body returns the original result; the same key with a different body fails with 409 idempotency_key_reused. Keys are retained at least 24 hours and are scoped to credential, Location, and operation; after expiry the value may be reused for a new logical request.

curl -i -X POST \
  'https://developer.alteg.io/_mock/en/b2b-v3/openapi/locations/{location_id}/appointments/{appointment_id}/payments/{payment_id}/refund' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Idempotency-Key: string'

Responses

The payment after local reversal.

Headers

RateLimit-Remaininginteger, (int32), >= 0

Requests left in the most constrained policy window that applies to this request.

RateLimit-Resetinteger, (int32), >= 0

On 429, seconds until the most constrained policy frees up; it equals Retry-After there. On a successful response it reports the length of that policy's window rather than the time left in the current one, so treat it as the window size, not as a countdown — the counter to pace against is RateLimit-Remaining.

RateLimit-Policystring

Most constrained policy applied to the request, as <limit>;w=<window in seconds>.

Example:"10;w=60"

X-Request-Idstring

Request identifier for support and log correlation.

Bodyapplication/json

idstring^[tl][0-9]+$read-onlyrequired

objectstringread-onlyrequired

Value:"payment"

typestringrequired

membership_auto and prepaid_hold are read-only and never accepted by PaymentCreate.

Enum:"payment_method""account""deposit""loyalty_card""loyalty_program""gift_card""membership""referral_program""membership_auto""prepaid_hold"

amount_minorintegerrequired

Payment amount in minor units. For membership, this is 0; covered items are listed in covers_items.

currencystringread-onlyrequired

ISO 4217, server-controlled by the Location.

statusstringrequired

Enum:"completed""refunded"

created_atstring, (date-time)read-onlyrequired

UTC.

visit_idinteger or nullread-only

fee_minorinteger or null

Acquiring fee represented inside the payment; it is not exposed as a separate payment.

account_idinteger or null

payment_method_idinteger or null

covers_itemsArray of objects(PaymentCoversItem)

card_brand_idinteger or null

installment_countinteger or null

refundRefund (object) or nullread-only

One of:

A full local reversal of a payment action. This is not a payment-provider refund contract.

Response

{
  "id": "t9001",
  "object": "payment",
  "visit_id": 5001,
  "type": "payment_method",
  "payment_method_id": 71,
  "account_id": 13,
  "amount_minor": 250000,
  "fee_minor": 2500,
  "currency": "EUR",
  "card_brand_id": 1,
  "installment_count": null,
  "status": "refunded",
  "covers_items": [],
  "refund": {
    "id": "t9001",
    "object": "refund",
    "payment_id": "t9001",
    "amount_minor": 250000,
    "created_at": "2026-07-24T14:10:00Z"
  },
  "created_at": "2026-07-24T13:00:00Z"
}