Record a payment on the appointment's visit

Request

Records a money, deposit, loyalty, gift card, membership, or referral-program payment against the visit resolved from appointment_id. This records that payment was received (cash, card terminal, cashless, or a loyalty instrument) — Altegio does not move funds through a payment provider on this call. amount_minor must not exceed amount_to_pay_minor; for membership, amount_minor is 0 and coverage is reported through covers_items. Gift card and membership addressed by number use the same anti-enumeration policy as searchLoyaltyInstrument (422 instrument_not_applicable, shared rate limit). Requires Idempotency-Key; a retry returns the original payment instead of recording it twice. A free visit (amount_to_pay_minor is 0) needs no payment; finalize it through setAppointmentStatus.

Security

OAuth2(Required scopes: payments:capture) 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.

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.

Bodyapplication/jsonrequired

typestringrequired

Value:"payment_method"

Discriminator

payment_method_idintegerrequired

From listPaymentMethods.

amount_minorintegerrequired

account_idintegerrequired

Account the payment settles to.

card_brand_idinteger

installment_countinteger

curl -i -X POST \
  'https://developer.alteg.io/_mock/en/b2b-v3/openapi/locations/{location_id}/appointments/{appointment_id}/payments' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: string' \
  -d '{
    "type": "payment_method",
    "payment_method_id": 71,
    "account_id": 13,
    "amount_minor": 250000,
    "card_brand_id": 1
  }'

Responses

The registered payment.

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"

Locationstring

URL of the created resource.

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": "completed",
  "covers_items": [],
  "refund": null,
  "created_at": "2026-07-24T13:00:00Z"
}