Download OpenAPI specification:
The Involink public API lets a merchant's own systems read invoices, transactions, and financial entries, create and send invoices, and receive signed webhooks when real business events happen — over a stable, versioned contract authenticated with a store-scoped API key.
Authentication: send your key in the x-api-key header. Keys are created and managed in the merchant Developer Portal. Every request is scoped to the one store the key belongs to; the store_id in the path must match the key's store.
Idempotency (v1.1): every write endpoint accepts an optional Idempotency-Key header (1–128 printable ASCII characters). Retrying a request with the same key within 24 hours returns the original response verbatim with an Idempotent-Replay: true header instead of re-executing the write. Reusing a key with a different payload returns 409 IDEMPOTENCY_KEY_REUSED; a concurrent duplicate returns 409 IDEMPOTENCY_REQUEST_IN_FLIGHT.
Entitlement (v1.1): if the store's subscription loses API access, requests return 403 API_ACCESS_DISABLED. Keys are NOT revoked — re-enabling the plan restores service with the same credentials.
Payments (v1.2): keys with the payments:initiate scope can request a CliQ payment from a payer alias — against an issued invoice or free-standing — via POST /stores/{store_id}/payments/rtp. Initiation REQUIRES the Idempotency-Key header. Outcomes arrive on the transaction.completed / transaction.rejected webhooks and via the transaction read endpoints. Stores with multiple payment accounts expose a resolution contract: GET /payments/accounts + an optional account_id on initiate (ACCOUNT_AMBIGUOUS tells you a choice is required).
Compliance (v1.3): keys with the compliance:read scope get full visibility into the JoFotara e-invoicing lifecycle they can already trigger via send: list submissions and read per-submission status with stable COMPLIANCE_* error categories, download the archived filing XML verbatim, and monitor the store's 30-day compliance health badge. A standalone precheck (POST /invoices/{invoice_id}/precheck, under invoices:write) validates an invoice against JoFotara rules before sending. Submission responses are served with Cache-Control: no-store — do not cache filing artifacts.
Versioning & deprecation policy: see docs/partner-api/versioning.md. This is v1, served at /external/v1. The legacy /api/v2/external path is a deprecated alias (see the versioning doc) and returns Deprecation/Sunset headers.
Requires the invoices:read scope.
| store_id required | integer >= 1 Must match the store the API key belongs to. |
| status | string |
| from | string <date-time> |
| to | string <date-time> |
| limit | integer [ 1 .. 100 ] Default: 50 Page size. Default 50, maximum 100. |
| cursor | string <= 256 characters Opaque pagination cursor: pass the previous page's |
| updated_since | string <date-time> Only return rows whose |
| Involink-API-Version | string Example: "1" The public API major version that served the request. Always |
| X-RateLimit-Limit | integer The key's per-minute request quota ( |
| X-RateLimit-Remaining | integer Requests left in the current one-minute window. |
| X-RateLimit-Reset | integer Unix time (seconds) when the current window resets. |
required | Array of objects (Invoice) |
| next_cursor required | string or null (NextCursor) Pass as |
{- "data": [
- {
- "id": 1042,
- "uuid": "3f6c2a1e-8b7d-4c1a-9a55-2d0f6f0b1c11",
- "invoice_number": "INV-2026-0042",
- "status": "sent",
- "invoice_type": "general_sales",
- "currency_code": "JOD",
- "amount": 116,
- "paid_amount": 0,
- "balance_due": 116,
- "contact_id": 77,
- "account_id": 5,
- "order_number": "PO-5521",
- "payment_terms": "net_30",
- "due_at": "2026-11-15T00:00:00.000Z",
- "invoiced_at": "2026-10-16T09:00:00.000Z",
- "paid_at": null,
- "created_at": "2026-10-16T08:59:12.000Z",
- "updated_at": "2026-10-16T09:00:01.000Z"
}
], - "next_cursor": "MjAyNi0xMC0xNlQxMDoyMDozMC4xMjNafDQy"
}Requires the invoices:write scope. Creates a draft invoice on behalf of the store owner (whose subscription + quota apply). VAT-bearing invoice types require a contact_id. Creates a draft only. Issuing, sending and JoFotara filing are separate calls; issue, channels and jofotara_auto_submit are rejected on this route.
| store_id required | integer >= 1 Must match the store the API key belongs to. |
| Idempotency-Key | string [ 1 .. 128 ] characters Optional idempotency key (1–128 printable ASCII characters). Retrying with the same key within 24 hours replays the original response with an |
| contact_id | integer Required for VAT-bearing invoice types (general_sales, special_sales, credit_general, credit_special). |
| account_id | integer Receiving account; defaults to the store default. |
| contact_alias_id | integer |
| account_alias_id | integer |
| tax_rate_id | integer |
| discount_id | integer |
| pdf_template_id | integer |
| language | string or null Enum: "en" "ar" "bi" null PDF rendering language override; |
| currency_code | string = 3 characters Default: "JOD" |
| invoice_type | string Default: "general_sales" Enum: "general_sales" "income" "special_sales" "credit_general" "credit_income" "credit_special" Omitted: |
| jofotara_payment | string Enum: "cash" "receivable" How JoFotara files the invoice (the 1 or 2 in |
| notes | string or null <= 2000 characters |
| footer | string or null <= 2000 characters |
| due_at | string <date-time> |
| payment_terms | string Enum: "due_on_receipt" "net_7" "net_15" "net_30" "net_60" "custom" Structured payment term; omitted defaults to |
| order_number | string or null <= 100 characters Buyer purchase-order / reference number, printed as "PO #" on the PDF. |
| to_email | string or null <email> <= 255 characters Accepted for compatibility with the send call's recipient overrides; ignored when creating a draft. Pass it to |
| to_name | string or null [ 1 .. 255 ] characters Same as |
required | Array of objects non-empty |
object (Invoice) The single external invoice shape, returned identically by list, create and send. |
{- "contact_id": 0,
- "account_id": 0,
- "contact_alias_id": 0,
- "account_alias_id": 0,
- "tax_rate_id": 0,
- "discount_id": 0,
- "pdf_template_id": 0,
- "language": "en",
- "currency_code": "JOD",
- "invoice_type": "general_sales",
- "jofotara_payment": "cash",
- "notes": "string",
- "footer": "string",
- "due_at": "2019-08-24T14:15:22Z",
- "payment_terms": "due_on_receipt",
- "order_number": "string",
- "to_email": "user@example.com",
- "to_name": "string",
- "items": [
- {
- "item_id": 1,
- "quantity": 999999999.999,
- "price": 0,
- "unit": "string",
- "tax_rate_id": 0
}
]
}{- "data": {
- "id": 1042,
- "uuid": "3f6c2a1e-8b7d-4c1a-9a55-2d0f6f0b1c11",
- "invoice_number": "INV-2026-0042",
- "status": "sent",
- "invoice_type": "general_sales",
- "currency_code": "JOD",
- "amount": 116,
- "paid_amount": 0,
- "balance_due": 116,
- "contact_id": 77,
- "account_id": 5,
- "order_number": "PO-5521",
- "payment_terms": "net_30",
- "due_at": "2026-11-15T00:00:00.000Z",
- "invoiced_at": "2026-10-16T09:00:00.000Z",
- "paid_at": null,
- "created_at": "2026-10-16T08:59:12.000Z",
- "updated_at": "2026-10-16T09:00:01.000Z"
}
}Requires the invoices:write scope. Transitions the invoice to sent and enqueues the customer notification over the requested channels. The store owner must have an active subscription and channel quota. Does not submit to JoFotara (compliance submission is a separate step).
| store_id required | integer >= 1 Must match the store the API key belongs to. |
| invoice_id required | integer >= 1 |
| Idempotency-Key | string [ 1 .. 128 ] characters Optional idempotency key (1–128 printable ASCII characters). Retrying with the same key within 24 hours replays the original response with an |
Array of strings or string One or more customer notification channels (e.g. email, sms, whatsapp). | |
| to_email | string or null <email> Override recipient email. |
| to_name | string or null Override recipient name. |
object (Invoice) The single external invoice shape, returned identically by list, create and send. |
{- "channels": [
- "string"
], - "to_email": "user@example.com",
- "to_name": "string"
}{- "data": {
- "id": 1042,
- "uuid": "3f6c2a1e-8b7d-4c1a-9a55-2d0f6f0b1c11",
- "invoice_number": "INV-2026-0042",
- "status": "sent",
- "invoice_type": "general_sales",
- "currency_code": "JOD",
- "amount": 116,
- "paid_amount": 0,
- "balance_due": 116,
- "contact_id": 77,
- "account_id": 5,
- "order_number": "PO-5521",
- "payment_terms": "net_30",
- "due_at": "2026-11-15T00:00:00.000Z",
- "invoiced_at": "2026-10-16T09:00:00.000Z",
- "paid_at": null,
- "created_at": "2026-10-16T08:59:12.000Z",
- "updated_at": "2026-10-16T09:00:01.000Z"
}
}Requires the transactions:read scope.
| store_id required | integer >= 1 Must match the store the API key belongs to. |
| status | string |
| from | string <date-time> |
| to | string <date-time> |
| limit | integer [ 1 .. 100 ] Default: 50 Page size. Default 50, maximum 100. |
| cursor | string <= 256 characters Opaque pagination cursor: pass the previous page's |
| updated_since | string <date-time> Only return rows whose |
| Involink-API-Version | string Example: "1" The public API major version that served the request. Always |
required | Array of objects (Transaction) |
| next_cursor required | string or null (NextCursor) Pass as |
{- "data": [
- {
- "id": 9001,
- "store_id": 12,
- "invoice_id": 1042,
- "type": "rtp",
- "status": "pending",
- "amount": 116,
- "currency_code": "JOD",
- "provider_code": "uwallet",
- "reference": "RTP-1042",
- "reference_number": null,
- "last_checked_at": null,
- "paid_at": null,
- "created_at": "2026-10-16T09:05:00.000Z",
- "updated_at": "2026-10-16T09:05:00.000Z"
}
], - "next_cursor": "MjAyNi0xMC0xNlQxMDoyMDozMC4xMjNafDQy"
}Requires the transactions:read scope. Poll this after initiating a payment.
| store_id required | integer >= 1 Must match the store the API key belongs to. |
| transaction_id required | integer >= 1 |
object (Transaction) The single external transaction shape, returned by list, detail and RTP initiation. Provider ( |
{- "data": {
- "id": 9001,
- "store_id": 12,
- "invoice_id": 1042,
- "type": "rtp",
- "status": "pending",
- "amount": 116,
- "currency_code": "JOD",
- "provider_code": "uwallet",
- "reference": "RTP-1042",
- "reference_number": null,
- "last_checked_at": null,
- "paid_at": null,
- "created_at": "2026-10-16T09:05:00.000Z",
- "updated_at": "2026-10-16T09:05:00.000Z"
}
}Requires the payments:initiate scope. Sanitized view of the store's enabled payment accounts, for choosing an account_id when initiation returns ACCOUNT_AMBIGUOUS. Merchant identifiers and provider configuration are never exposed.
| store_id required | integer >= 1 Must match the store the API key belongs to. |
Array of objects (PaymentAccount) |
{- "data": [
- {
- "id": 0,
- "name": "string",
- "display_name": "string",
- "provider_code": "string",
- "currency_code": "string",
- "is_default": true
}
]
}Requires the payments:initiate scope and the Idempotency-Key header (initiation is never safe to retry blind). Requests payment of amount from the payer's CliQ alias — either against an issued invoice (invoice_id) or free-standing. The response is the created pending transaction; the terminal outcome arrives on the transaction.completed / transaction.rejected webhooks or by polling the transaction. Initiation debits the store owner's monthly RTP allowance and is rate-limited per store and per payer alias.
| store_id required | integer >= 1 Must match the store the API key belongs to. |
| Idempotency-Key required | string [ 1 .. 128 ] characters REQUIRED for payment initiation. Retrying with the same key within 24 hours replays the original response with |
| amount required | number > 0 Amount to collect, in |
| currency | string = 3 characters Default: "JOD" |
| debtor_alias required | string <= 120 characters The payer's CliQ alias (mobile number or alias). Supplied per call; never stored. |
| debtor_alias_type | string Enum: "MOBL" "ALIAS" Optional; inferred from the alias format when omitted. |
| invoice_id | integer Optional issued invoice to collect against. Omit for a free-standing collection. |
| account_id | integer Optional payment account override; required when the store has several enabled accounts and no default ( |
| description | string <= 500 characters |
object (Transaction) The single external transaction shape, returned by list, detail and RTP initiation. Provider ( | |
| message | string |
object (Transaction) The single external transaction shape, returned by list, detail and RTP initiation. Provider ( | |
| message | string |
{- "amount": 0,
- "currency": "JOD",
- "debtor_alias": "string",
- "debtor_alias_type": "MOBL",
- "invoice_id": 0,
- "account_id": 0,
- "description": "string"
}{- "data": {
- "id": 9001,
- "store_id": 12,
- "invoice_id": 1042,
- "type": "rtp",
- "status": "pending",
- "amount": 116,
- "currency_code": "JOD",
- "provider_code": "uwallet",
- "reference": "RTP-1042",
- "reference_number": null,
- "last_checked_at": null,
- "paid_at": null,
- "created_at": "2026-10-16T09:05:00.000Z",
- "updated_at": "2026-10-16T09:05:00.000Z"
}, - "message": "string"
}Requires the financial:write scope.
| store_id required | integer >= 1 Must match the store the API key belongs to. |
| Idempotency-Key | string [ 1 .. 128 ] characters Optional idempotency key (1–128 printable ASCII characters). Retrying with the same key within 24 hours replays the original response with an |
| entry_type required | string Enum: "cost" "fee" "payment" "settlement_signal" "adjustment" |
| direction required | string Enum: "debit" "credit" |
| amount required | number > 0 |
| currency_code | string = 3 characters |
| occurred_at | string <date-time> |
| invoice_id | integer or null |
| transaction_id | integer or null |
| reference | string or null <= 160 characters |
object or null |
object (FinancialEntry) A ledger entry, as returned by |
{- "entry_type": "cost",
- "direction": "debit",
- "amount": 0,
- "currency_code": "str",
- "occurred_at": "2019-08-24T14:15:22Z",
- "invoice_id": 0,
- "transaction_id": 0,
- "reference": "string",
- "metadata": { }
}{- "data": {
- "id": 0,
- "store_id": 0,
- "entry_type": "cost",
- "direction": "debit",
- "amount": 0,
- "currency_code": "string",
- "occurred_at": "2019-08-24T14:15:22Z",
- "invoice_id": 0,
- "transaction_id": 0,
- "reference": "string",
- "metadata": { },
- "created_at": "2019-08-24T14:15:22Z"
}
}Requires the financial:read scope.
| store_id required | integer >= 1 Must match the store the API key belongs to. |
| from | string <date-time> |
| to | string <date-time> |
| currency_code | string = 3 characters |
object (FinancialSummary) |
{- "data": {
- "from": "2019-08-24T14:15:22Z",
- "to": "2019-08-24T14:15:22Z",
- "currency_code": "string",
- "totals": {
- "property1": {
- "debit": 0,
- "credit": 0,
- "net": 0
}, - "property2": {
- "debit": 0,
- "credit": 0,
- "net": 0
}
}, - "overall": {
- "debit": 0,
- "credit": 0,
- "net": 0
}
}
}Requires the invoices:write scope. Runs the same validation JoFotara submission runs — device, store tax profile, buyer, currency, line math, totals reconciliation, sequence — WITHOUT submitting anything. Returns blockers and warnings with stable COMPLIANCE_* categories so you can fix data before send. Safe to call repeatedly; nothing is mutated.
| store_id required | integer >= 1 Must match the store the API key belongs to. |
| invoice_id required | integer >= 1 |
| invoice_type | string Enum: "general_sales" "income" "special_sales" "credit_general" "credit_income" "credit_special" Override the invoice's own type for the check; defaults to the invoice's type. |
object (PrecheckResult) |
{- "invoice_type": "general_sales"
}{- "data": {
- "ok": true,
- "blockers": [
- {
- "category": "COMPLIANCE_DEVICE_MISSING",
- "severity": "blocker",
- "field": "string",
- "message": "string"
}
], - "warnings": [
- {
- "category": "COMPLIANCE_DEVICE_MISSING",
- "severity": "blocker",
- "field": "string",
- "message": "string"
}
]
}
}Requires the compliance:read scope. Newest first. Covers both invoice submissions and credit-note submissions (direction). Responses carry Cache-Control: no-store — never cache filing data.
| store_id required | integer >= 1 Must match the store the API key belongs to. |
| invoice_id | integer >= 1 |
| credit_note_id | integer >= 1 |
| status | string Enum: "accepted" "rejected" "error" "pending" |
| direction | string Enum: "invoice" "credit_note" |
| from | string <date-time> |
| to | string <date-time> |
| limit | integer [ 1 .. 50 ] Default: 20 Page size. Default 20, maximum 50. |
| cursor | string <= 256 characters Opaque pagination cursor: pass the previous page's |
| updated_since | string <date-time> Only return rows whose |
| Involink-API-Version | string Example: "1" The public API major version that served the request. Always |
required | Array of objects (ComplianceSubmission) |
| next_cursor required | string or null (NextCursor) Pass as |
{- "data": [
- {
- "id": 0,
- "invoice_id": 0,
- "credit_note_id": 0,
- "direction": "invoice",
- "invoice_type": "general_sales",
- "request_uuid": "a699086b-c336-457e-9191-0c825d6efbc8",
- "response_status": "accepted",
- "error_categories": [
- "string"
], - "response_qr_code": "string",
- "submitted_at": "2019-08-24T14:15:22Z",
- "retrieved_at": "2019-08-24T14:15:22Z",
- "created_at": "2019-08-24T14:15:22Z"
}
], - "next_cursor": "MjAyNi0xMC0xNlQxMDoyMDozMC4xMjNafDQy"
}Requires the compliance:read scope.
| store_id required | integer >= 1 Must match the store the API key belongs to. |
| submission_id required | integer >= 1 |
object (ComplianceSubmission) One archived JoFotara submission attempt. The submitted XML has its own download endpoint; raw provider response payloads are not exposed — |
{- "data": {
- "id": 0,
- "invoice_id": 0,
- "credit_note_id": 0,
- "direction": "invoice",
- "invoice_type": "general_sales",
- "request_uuid": "a699086b-c336-457e-9191-0c825d6efbc8",
- "response_status": "accepted",
- "error_categories": [
- "string"
], - "response_qr_code": "string",
- "submitted_at": "2019-08-24T14:15:22Z",
- "retrieved_at": "2019-08-24T14:15:22Z",
- "created_at": "2019-08-24T14:15:22Z"
}
}Requires the compliance:read scope. Returns the UBL 2.1 XML exactly as it was submitted to JoFotara — the merchant's own filing artifact, byte-for-byte. Served as an attachment with Cache-Control: no-store. Retrieval is stamped on the submission (retrieved_at).
| store_id required | integer >= 1 Must match the store the API key belongs to. |
| submission_id required | integer >= 1 |
{- "error": {
- "code": "EXTERNAL_API_SCOPE_FORBIDDEN",
- "message": "Missing required external API scope: invoices:write.",
- "details": {
- "required_scope": "invoices:write",
- "available_scopes": [
- "invoices:read"
]
}
}
}Requires the compliance:read scope. Traffic-light view of the store's JoFotara outcomes over the last 30 days, with per-status counts and an error-category histogram. Poll this to monitor integration health instead of re-reading every submission.
| store_id required | integer >= 1 Must match the store the API key belongs to. |
object (ComplianceHealth) |
{- "data": {
- "connected": true,
- "badge": "green",
- "last_submission_at": "2019-08-24T14:15:22Z",
- "last_submission_status": "string",
- "window_days": 0,
- "counts_30d": {
- "accepted": 0,
- "rejected": 0,
- "error": 0,
- "pending": 0
}, - "error_categories_30d": {
- "property1": 0,
- "property2": 0
}, - "needs_review": {
- "count": 0,
- "invoices": [
- {
- "id": 0,
- "invoice_number": "string"
}
]
}
}
}Signed event deliveries Involink POSTs to your endpoints. Configure endpoints and subscribed events in the Developer Portal. See the WebhookEnvelope schema for the discriminated set of event payloads.
| id required | string Unique event id (dedup key). Generated once per delivery and stable across retries, so a retried delivery carries the same |
| created_at required | string <date-time> When the event was created. |
| type required | string Value: "invoice.created" |
required | object (InvoiceCreatedData) |
{- "id": "evt_2b0c0b5e-61d0-4f4d-9a43-3a0b0f0c7f11",
- "type": "invoice.created",
- "created_at": "2026-10-16T09:00:00.000Z",
- "data": {
- "invoice_id": 1042,
- "invoice_number": "INV-2026-0042",
- "store_id": 12,
- "amount": 116,
- "currency": "JOD"
}
}| id required | string Unique event id (dedup key). Generated once per delivery and stable across retries, so a retried delivery carries the same |
| created_at required | string <date-time> When the event was created. |
| type required | string Value: "invoice.paid" |
required | object (InvoicePaidData) |
{- "id": "evt_7d1a9c3e-0b52-4e6f-8f0a-5c2d9e1b3a44",
- "type": "invoice.paid",
- "created_at": "2026-10-16T09:30:00.000Z",
- "data": {
- "invoice_id": 1042,
- "invoice_number": "INV-2026-0042",
- "store_id": 12,
- "amount": 116,
- "currency": "JOD",
- "status": "paid",
- "paid_amount": 116,
- "balance_due": 0,
- "paid_at": "2026-10-16T09:29:58.000Z"
}
}| id required | string Unique event id (dedup key). Generated once per delivery and stable across retries, so a retried delivery carries the same |
| created_at required | string <date-time> When the event was created. |
| type required | string Value: "transaction.completed" |
required | object (TransactionEventData) Shared |
{- "id": "evt_a41f5c0e-2d63-49b7-b1a8-9e7c3d5f6a20",
- "type": "transaction.completed",
- "created_at": "2026-10-16T09:29:58.000Z",
- "data": {
- "transaction_id": 9001,
- "store_id": 12,
- "invoice_id": 1042,
- "invoice_number": "RTP-1042",
- "amount": "116.000",
- "currency": "JOD",
- "status": "completed",
- "psp_status": null,
- "reason": null
}
}| id required | string Unique event id (dedup key). Generated once per delivery and stable across retries, so a retried delivery carries the same |
| created_at required | string <date-time> When the event was created. |
| type required | string Value: "transaction.rejected" |
required | object (TransactionEventData) Shared |
{- "id": "evt_c93e1b7a-5f08-4d2c-a6e4-1b8d0f2e9c35",
- "type": "transaction.rejected",
- "created_at": "2026-10-16T09:40:00.000Z",
- "data": {
- "transaction_id": 9002,
- "store_id": 12,
- "invoice_id": null,
- "invoice_number": null,
- "amount": "25.000",
- "currency": "JOD",
- "status": "rejected",
- "psp_status": "DCLN",
- "reason": null
}
}| id required | string Unique event id (dedup key). Generated once per delivery and stable across retries, so a retried delivery carries the same |
| created_at required | string <date-time> When the event was created. |
| type required | string Value: "financial.entry.created" |
required | object (FinancialEntryCreatedData) |
{- "id": "evt_5e8b2d4c-7a19-4c3f-8d60-2f4a6c8e0b17",
- "type": "financial.entry.created",
- "created_at": "2026-10-16T10:00:00.000Z",
- "data": {
- "entry_id": 311,
- "store_id": 12,
- "entry_type": "fee",
- "direction": "debit",
- "amount": 0.5,
- "currency": "JOD",
- "occurred_at": "2026-10-16T10:00:00.000Z",
- "source": "external_api",
- "invoice_id": null,
- "transaction_id": null,
- "reference": "bank fee Oct"
}
}| id required | string Unique event id (dedup key). Generated once per delivery and stable across retries, so a retried delivery carries the same |
| created_at required | string <date-time> When the event was created. |
| type required | string Value: "test.ping" |
required | object (TestPingData) |
{- "id": "evt_test_1760605200000",
- "type": "test.ping",
- "created_at": "2026-10-16T09:00:00.000Z",
- "data": {
- "store_id": 12,
- "endpoint_id": 7,
- "message": "Involink webhook test delivery"
}
}