Payment Requests

Hosted pay-by-link requests collected through the workspace's own connected payment provider (Cardcom or Sumit). Minting a request returns a shareable pay_url; the payer completes checkout on the hosted page, the payment is verified with the provider, recorded on the contact's payments ledger, and an Israeli tax document is auto-issued (configurable). Lifecycle changes fire the opt-in payment_request.* webhooks.

All endpoints require authentication. Payment requests cannot be deleted, and there is no PATCH — a mistaken link is cancelled and a new one minted.

To charge a contact's saved card directly (no pay-link), see saved cards and charges.

Plan feature required: every route on this page requires the Workspace payments feature (workspace_payments) on the workspace's plan, in addition to API access. This is a different feature from the payments ledger gate on /v1/payments* — a workspace can hold either without the other. Without it, all calls return 403 with error_code: "FEATURE_NOT_INCLUDED_IN_PLAN" (the message embeds workspace_payments) — see feature-gated resource groups. Minting additionally requires a connected provider (Cardcom or Sumit in Settings → Integrations) — otherwise 400 NO_PAYMENT_PROVIDER.

Send idempotency_key on every create. Idempotency on POST /v1/payment-requests is opt-in: with an idempotency_key, a repeat POST — including a blind retry after a network failure — returns the original link with duplicate: true and mints nothing. Without one, a repeat POST mints a second, independently payable link, and both links can be paid; if a keyless create's outcome is uncertain, check GET /v1/payment-requests (filter by contact_id/deal_id) before minting again, and cancel extras via the cancel endpoint.

The payment request object

Status lifecycle: pending → paid | expired | cancelled. Money serializes as JSON numbers.

Main fields:

Computed fields:

• pay_url — the shareable hosted pay-page URL (https://app.otok.io/pay/<public_token>). Present on create/get/list; null on token rows; the cancel response is the bare row without computed fields.
• document — the issued tax-document pointer { provider, id, number, type, url } once paid (get/list); null while unpaid.
• Create only: checkout_url / checkout_error — see create — and duplicate.
• List rows only: joined contact_name / contact_phone / contact_email, plus refunded_total (total already refunded against this request's settled charge).

GET /api/v1/payment-requests

Dedicated query parameters with the deals/payments pagination family — see where deals and payments differ. Ordered by created_at descending.

curl -G "https://app.otok.io/api/v1/payment-requests" \
  -H "Authorization: Bearer otok_live_abc123..." \
  --data-urlencode 'status=pending'

Response 200 — { data, total, limit, offset }.

GET /api/v1/payment-requests/:id

Response 200 — the request with pay_url and (once paid) document. 404 — "Payment request not found". Non-UUID id → 400.

POST /api/v1/payment-requests

Mints a hosted-checkout pay-link and returns the row with its shareable pay_url. Idempotent only with idempotency_key — see the note at the top of this page.

Request body

Idempotency

With idempotency_key, the first POST mints the link and every replay of the same charge returns that original row with duplicate: true — no second link is minted and the provider is not contacted again. "The same charge" means the same payer contact, amount, currency, sale_id and product_id; reusing a key for anything else answers 409 IDEMPOTENCY_KEY_MISMATCH. Two concurrent requests with the same key: one wins, the other may briefly answer 409 IDEMPOTENCY_CLAIM_IN_FLIGHT — retry it after a moment and it replays. A replay's checkout_url / checkout_error are null; share pay_url.

Without a key, duplicate is always false.

Contact resolution

Like payments: contact_id wins; otherwise phone/email are upserted like POST /v1/contacts (with the same 409 CONTACT_MERGE_REQUIRED behavior); a deal_id alone is also valid — the deal's contact pays. None of the four → 400 "Provide contact_id, a phone/email to resolve the payer contact, or a deal_id".

Example

curl -X POST "https://app.otok.io/api/v1/payment-requests" \
  -H "Authorization: Bearer otok_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+972501234567",
    "name": "Dana Levi",
    "amount": 250,
    "currency": "ILS",
    "title": "Onboarding session",
    "expires_at": "2026-07-18T09:00:00Z"
  }'

Response 201 (abridged):

{
  "id": "0b1c2d3e-4f50-6172-8394-a5b6c7d8e9f0",
  "contact_id": "9c2f1a4e-3b7d-4e2a-9f0c-1d2e3f4a5b6c",
  "deal_id": null,
  "provider": "sumit",
  "status": "pending",
  "charge_kind": "checkout",
  "amount": 250,
  "currency": "ILS",
  "title": "Onboarding session",
  "vat_mode": "inclusive",
  "vat_rate": 18,
  "test_mode": false,
  "expires_at": "2026-07-18T09:00:00.000Z",
  "public_token": "pr_k3J9…",
  "pay_url": "https://app.otok.io/pay/pr_k3J9…",
  "checkout_url": "https://…provider-checkout…",
  "checkout_error": null,
  "duplicate": false,
  "created_at": "2026-07-15T09:00:00.000Z",
  "updated_at": "2026-07-15T09:00:00.000Z"
}

checkout_url/checkout_error report the provider checkout-session mint: on a provider failure the row is still created (pending) with checkout_error set and the link still works — the hosted pay page lazily (re)creates the provider session when the payer opens it. The URL to share is always pay_url.

Errors

After the mint

• The payer opens pay_url, pays on the hosted page, and the payment is verified with the provider before anything is recorded.
• A verified payment stamps paid_at, links contact_payment_id (a payment on the contact's ledger), auto-issues the tax document (per auto_issue_document/document_kind), emails the payer a receipt, and fires payment_request.paid.
• With product_id (and no sale_id), the payment records a sale for the product and the request's sale_id is set; with sale_id, the payment is allocated to that sale.
• Pending links get pre-expiry reminders (unless disabled); a link that passes expires_at unpaid flips to expired and fires payment_request.expired.
• Minting does not send the link anywhere — share pay_url yourself or use send-link.

POST /api/v1/payment-requests/:id/cancel

Withdraws the pay-link — the hosted page stops accepting payment. No request body. Pending requests only: the cancel is a compare-and-set on status, so already paid/expired/cancelled rows answer 409.

Response 201 — the cancelled row (status: "cancelled", cancelled_at stamped). Unlike the other reads, the cancel response is the bare row — no computed pay_url/document fields.

Late completions. Cancelling does not revoke an already-open checkout session: a payer who was on the hosted page when you cancelled can still complete. Such payments are verified and recorded rather than dropped — the row resurrects to paid and fires payment_request.paid. Treat payment_request.paid as authoritative even after a cancel.

POST /api/v1/payment-requests/:id/send-link

Sends a pending request's pay-link to its contact — the same delivery as the in-app Send button.

curl -X POST "https://app.otok.io/api/v1/payment-requests/0b1c2d3e-4f50-6172-8394-a5b6c7d8e9f0/send-link" \
  -H "Authorization: Bearer otok_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{ "channel": "whatsapp" }'

Response 201:

{ "sent": true, "channel": "whatsapp", "to": "0501234567", "message_id": "wamid.HBgM…" }

to is the address or phone number the link went to; message_id is the WhatsApp / SMS message id when the channel reports one (null for email).

• Once per channel. An API send goes out once per channel: a second send on a channel the link was already sent on (by you, the app, or a reminder) answers 409 LINK_ALREADY_SENT with the first sent_at — unless you send resend: true. Sending on a different channel is always allowed.
• Email leaves only from the workspace's verified sender address. WhatsApp inside the contact's 24-hour window sends a plain message; outside it, oToK uses its payment-link message template, which must be approved by Meta first. SMS needs the SMS channel enabled for the workspace.
• The first successful send sets the request's channel and the matching link_*_sent_at stamp.

POST /api/v1/payment-requests/:id/document

Issues the tax document for a paid request — use it when the automatic issue was switched off (auto_issue_document: false) or failed. No request body. The document kind is the request's document_kind (or the provider/account default).

curl -X POST "https://app.otok.io/api/v1/payment-requests/0b1c2d3e-4f50-6172-8394-a5b6c7d8e9f0/document" \
  -H "Authorization: Bearer otok_live_abc123..."

Response 201 — the request, with pay_url and the issued document ({ provider, id, number, type, url }).

A credit document kind (credit_invoice, credit_invoice_receipt, credit_receipt, credit_donation_receipt) gives money back on paper, so it requires an API key with refund access.

POST /api/v1/payment-requests/:id/refund

Refunds the payment a paid request settled — the same refund path as POST /v1/payments/:id/refund, addressed by the request instead of the ledger payment. Requires an API key with refund access.

curl -X POST "https://app.otok.io/api/v1/payment-requests/0b1c2d3e-4f50-6172-8394-a5b6c7d8e9f0/refund" \
  -H "Authorization: Bearer otok_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{ "reason": "requested_by_customer", "mode": "auto", "idempotency_key": "pr-refund-1" }'

Response 201 — the refund result ({ payment, entry, outcome, duplicate }, plus incidentId on a pending reversal) with payment_request_id. The request's list row shows the running refunded_total.

Errors are those of the payments refund, plus:

Webhooks

The four lifecycle events — payment_request.created / paid / expired / cancelled — are opt-in by listing at POST /v1/webhook-endpoints: an endpoint registered without an explicit events list receives none of them. Payloads follow the order-event conventions (full field set, explicit nulls, test_mode always present) — see payment-request event data. Refunds of a paid request fire the payment.refunded event of the payment it settled.

Choosing a payment terminal

POST /api/v1/payment-requests accepts optional terminal_number (positive integer). With Cardcom, use a terminal configured in the workspace settings; omission uses the default terminal. An unknown terminal, or a provider without terminal selection, returns 400.