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.

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.

No idempotency key. Unlike deals, payments, and orders, POST /v1/payment-requests has no idempotency reference of any kind: a repeat POST — including a blind retry after a network failure — mints a second, independently payable link. Both links can be paid. If a 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.
• 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. Not idempotent — see the warning at the top of this page.

Request body

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,
  "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.
• Pending links get pre-expiry reminder emails (unless disabled); a link that passes expires_at unpaid flips to expired and fires payment_request.expired.

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.

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.