Payments

Payments are money recorded against a patient - charges and refunds. Reads require the payments:read scope; recording a payment requires the separate payments:write scope (granted explicitly, never bundled with reads).

#The payment object

Field	Type	Description
`id`	string	Unique payment id.
`patient`	object \| null	Embedded patient summary.
`recorded_by`	object \| null	The user who recorded it (`id`, `name`).
`amount`	number \| null	Amount; positive for charges.
`currency`	string	ISO 4217 currency code (e.g. `ILS`).
`is_refund`	boolean	Whether this is a refund.
`methods`	string[]	Method types used: `cash`, `credit_card`, `check`, `bank_transfer`, `payment_app`.
`paid_at`	string \| null	ISO 8601 time of payment.
`created_at`	string \| null	ISO 8601 timestamp.
`updated_at`	string \| null	ISO 8601 timestamp.

No instrument details, ever

Only the method type is returned (credit_card, check, …). Card numbers, expiry, check numbers, and bank account details are never exposed through the API.

#List a patient's payments

GET

Returns a paginated list of the patient's payments and refunds.

curl https://api.smile-app.co.il/v1/patients/8842/payments \
  -H "Authorization: Bearer sk_live_..."

{
  "data": [
    {
      "id": "33010",
      "patient": { "id": "8842", "first_name": "Dana", "last_name": "Levi" },
      "recorded_by": { "id": "5", "name": "Front Desk" },
      "amount": 480.0,
      "currency": "ILS",
      "is_refund": false,
      "methods": ["credit_card"],
      "paid_at": "2026-07-01T09:35:00+03:00"
    }
  ],
  "next_cursor": null
}

#Retrieve a payment

GET

curl https://api.smile-app.co.il/v1/payments/33010 \
  -H "Authorization: Bearer sk_live_..."

#Record a payment

POST

Records a simplified payment and issues the accounting documents (receipt / tax invoice) in the same call: exactly one payment method, no multi-method split, no family split. The response embeds the issued and scheduled documents, including short-lived temp_url PDF links — so the receipt arrives in one round-trip.

Field	Type	Description
`amount`	number, required	Gross (VAT-inclusive) amount actually collected, in ILS. Positive, max 2 decimals.
`method`	string, required	`cash`, `credit_card`, `check`, `bank_transfer`, or `payment_app`.
`description`	string	Printed on the receipt (max 255).
`notes`	string	Free-text notes printed on the receipt (max 1000).
`billing_account_id`	integer	Target billing account. Optional when the clinic has exactly one, or the patient has a default.
`external_id`	string	Idempotency key, unique per clinic — e.g. your transaction id. Strongly recommended for machine callers.
`zero_vat`	boolean	Record with 0% VAT (default `false`).
`credit_card`	object	Only when `method=credit_card`; all fields optional: `brand` (`visa`/`mastercard`/`isracard`/`amex`/`diners`/`other`), `last_4` (exactly 4 digits — never a full card number), `expiry` (`MM/YY`), `mode` (`regular`/`installments`/`credit`), `num_payments` (required unless `regular`), `first_payment_amount` + `next_payment_amount` (computed when omitted), `transaction_ref`.
`check`	object	Required when `method=check`: `date` (value date, `YYYY-MM-DD`) plus optional `bank`, `branch`, `account`, `number`.
`bank_transfer`	object	Required when `method=bank_transfer`: `date` plus optional `bank`, `branch`, `account`.
`payment_app`	object	Required when `method=payment_app` (e.g. Bit): `date` plus optional `app`, `reference`.

curl -X POST https://api.smile-app.co.il/v1/patients/8842/payments \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 1180.00,
    "method": "credit_card",
    "description": "תוכנה לניהול מרפאה",
    "notes": "מנוי עד 14/08/2026",
    "external_id": "payplus:abc-123",
    "credit_card": { "brand": "visa", "last_4": "1234", "transaction_ref": "abc-123" }
  }'

{
  "data": {
    "id": "33011",
    "patient": { "id": "8842", "first_name": "Dana", "last_name": "Levi" },
    "recorded_by": null,
    "amount": 1180.0,
    "currency": "ILS",
    "is_refund": false,
    "methods": ["credit_card"],
    "paid_at": "2026-07-30T10:12:00+03:00",
    "documents": [
      {
        "type": "kabala",
        "status": "issued",
        "number": "2042",
        "amount": 1180.0,
        "amount_without_vat": 1000.0,
        "vat_amount": 180.0,
        "vat_rate": 0.18,
        "issued_at": "2026-07-30T10:12:01+03:00",
        "temp_url": "https://..."
      }
    ]
  }
}

Statuses and semantics:

201 — the payment was created and its documents issued.
200 — idempotent replay: this external_id was already recorded; the existing payment (with its documents) is returned. Retrying after a timeout is always safe when you pass an external_id.
409 — the external_id maps to a payment that was since cancelled inside Smile. Recreating it silently would resurrect a voided document, so the API refuses; use a new external_id if you really mean a new payment.
503 — a transient dependency (e.g. the tax-authority allocation service, required above a legal amount threshold) failed before anything was created. Retry later with the same external_id.

What this endpoint is not

Refunds, cancellations and backdating are not supported through the API — those remain deliberate, human actions inside Smile. The receipt date is always the recording time; check/transfer value dates are carried by their date fields.

payment.recorded and payment.cancelled webhooks - react to payments as they happen.

Payments

#The payment object

#List a patient's payments

#Retrieve a payment

#Record a payment

#Related