{ "openapi": "3.1.0", "info": { "title": "Amtaar Partner API", "version": "2026-10-18", "contact": { "name": "Amtaar partnerships", "email": "hi@amtaar.dev", "url": "https://amtaar.app/developers/" }, "description": "Server-to-server API for partners — banks, brokers and fintech apps — that bring investors to **Amtaar**, the Egyptian fractional real-estate platform.\n\nWith it a partner can show Amtaar properties in its own app, open or link its customers' Amtaar accounts, place share purchases (settled by the partner or paid by card), follow every order to completion, read holdings and rental income, and track its commissions — with webhooks for every change.\n\n## Environments\n\n| | Base URL | Keys start with |\n|---|---|---|\n| Sandbox | sent to you with your sandbox keys | `amtk_sandbox_` |\n| Live | `https://api.amtaar.co/open/v1` | `amtk_live_` |\n\nA key only works on the environment that issued it. This server is the **live** environment. Sandbox has extra `/sandbox/*` endpoints that move orders and KYC along so you can test webhooks end to end; it never moves real money.\n\n## Authentication\n\n```\nAuthorization: Bearer amtk_live__\n```\n\nKeys are issued by Amtaar (shown once — store them in a secret manager), carry **scopes**, and can be limited to your server IPs. What a key may do is also bounded by your partner account's **capabilities**, which Amtaar switches on as the partnership agreement allows: `createCustomers`, `linkExistingCustomers`, `partnerKycReliance`, `partnerSettlementOrders`, `cardCheckoutOrders`, `portfolioAccess`, `walletAccess`. `GET /me` shows yours.\n\n## Conventions\n\n- JSON in and out, UTF-8. Money is EGP with 2 decimals. Times are ISO-8601 UTC.\n- Ids are prefixed strings (`cus_`, `ord_`, `prop_`, `evt_`, `we_` …). Treat them as opaque.\n- Lists are newest first with cursor pagination: `?limit=20&cursor=`.\n- `metadata`: up to 20 string key/value pairs of yours on customers and orders, returned as given.\n- **Idempotency:** `POST /customers`, `POST /orders` and `POST /orders/{id}/settlement` *require* an `Idempotency-Key` header. Always retry a failed or timed-out call with the same key.\n- **Rate limit:** per key (default 300 requests/minute). `RateLimit-*` headers on every answer; `429` + `Retry-After` when exceeded.\n- Every answer carries `X-Request-ID` (send your own to correlate) and `Amtaar-Api-Version: 2026-10-18`.\n\n## Versioning\n\n`/v1` only changes in backward-compatible ways: new endpoints, new optional request fields, new response fields, new event types, new enum values. Ignore fields you do not know and handle unknown enum values gracefully. A breaking change would ship as `/v2`, with `/v1` kept running for at least 6 months.\n\n## Errors\n\n```json\n{ \"error\": { \"type\": \"invalid_request\", \"code\": \"invalid_phone\", \"message\": \"…\", \"param\": \"phone\", \"requestId\": \"…\" } }\n```\n\n`type` is one of `invalid_request` (400), `authentication_error` (401), `permission_denied` (403), `not_found` (404), `conflict` (409), `unprocessable` / `idempotency_error` (422), `rate_limited` (429), `api_error` (500), `service_unavailable` (503). `code` is the precise, stable reason — branch on it, not on `message`.\n\n## Typical flows\n\n**A. Referral — the customer buys in the Amtaar app.** `POST /customers` (opens or links the account, attributed to you) → send the customer to `links.app` → they sign in to the Amtaar app with the same mobile number, finish KYC and invest → you receive `customer.kyc_verified`, `order.created` … `order.completed` and `commission.created`.\n\n**B. Embedded purchase, settled by the partner.** `POST /customers` → `POST /quotes` to show the price → debit your customer → `POST /orders` with `funding.method = partner_settlement` and the settlement (reference + exact amount) → transfer the money to Amtaar's account → Amtaar Finance confirms it (`order.paid`) → ownership is issued when the unit's funding closes (`order.completed`).\n\n**C. Embedded purchase, paid by card.** `POST /orders` with `funding.method = card_checkout` → open `funding.checkoutUrl` (Paymob) in a web view → `order.paid` → `order.completed`.\n\n## Order lifecycle\n\n`awaiting_payment` → `payment_under_review` (settlement or transfer proof received, Finance checking) → `paid` (money confirmed; waiting for the unit to be fully funded and ownership to be issued) → `completed` (the customer owns the shares; contract follows).\nOther outcomes: `cancelled` (by you, by the customer, or because the hold expired unpaid — shares are released), `payment_rejected`, `cancellation_requested` (the customer asked to cancel a paid order; Amtaar reviews it), `refunded`.\n\nAn unpaid API order keeps its shares reserved until `expiresAt` (your hold time, default 24 h; card checkout 60 min).\n\n## Webhooks\n\nRegister endpoints with `POST /webhook-endpoints` (or ask Amtaar). Each event is POSTed as the Event object. Verify every delivery:\n\n```\nAmtaar-Signature: t=1760000000,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd\nexpected = hex(HMAC_SHA256(endpoint_secret, t + \".\" + raw_request_body))\n```\n\nCompare in constant time and reject timestamps older than 5 minutes. Answer `2xx` within 10 seconds (queue the work); anything else is retried after 1 m, 5 m, 15 m, 1 h, 3 h, 6 h, 12 h and 24 h. Deliveries can arrive more than once and out of order — deduplicate by `Amtaar-Event-Id` and re-read the object (`GET /orders/{id}`) when order matters. If you were offline, catch up with `GET /events?after=`. Events are generated within about a minute of the change and kept 180 days.\n\nEvent types: `customer.created`, `customer.linked`, `customer.kyc_verified`, `customer.unlinked`, `order.created`, `order.payment_under_review`, `order.paid`, `order.completed`, `order.cancelled`, `order.payment_rejected`, `order.refunded`, `order.cancellation_requested`, `payout.paid`, `commission.created`, `webhook.test`.\n\n## Data protection\n\nYou only see customers linked to you. Linking an *existing* Amtaar investor needs their consent: Amtaar texts them a code that you must collect from them. Holdings, payouts and wallet are only available with the matching capability and scope. Use the data only for the purposes in your partnership agreement; `DELETE /customers/{id}` removes the link (the Amtaar account stays)." }, "servers": [ { "url": "https://api.amtaar.co/open/v1", "description": "Live" } ], "security": [ { "apiKey": [] } ], "tags": [ { "name": "Account", "description": "Who you are, what your key and account may do." }, { "name": "Properties", "description": "The investable catalogue and indicative pricing." }, { "name": "Customers", "description": "Investors you brought or linked." }, { "name": "Portfolio", "description": "Holdings, rental payouts, contracts and wallet of a linked customer." }, { "name": "Orders", "description": "Share purchases — placed by you, or by your customers in the Amtaar app." }, { "name": "Commissions", "description": "What you earn under your partner agreement." }, { "name": "Events", "description": "Everything that happened, for polling or catching up after downtime." }, { "name": "Webhooks", "description": "Endpoints Amtaar pushes events to, and their deliveries." }, { "name": "Sandbox", "description": "Sandbox only — simulate what Amtaar staff and customers would do." } ], "paths": { "/me": { "get": { "tags": [ "Account" ], "summary": "Your account, key and capabilities", "description": "Use it as a health check for your key.", "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Account" } } } }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "429": { "$ref": "#/components/responses/E429" } }, "operationId": "getAccount" } }, "/properties": { "get": { "tags": [ "Properties" ], "summary": "List properties", "description": "Published properties, newest first. Drafts and internal test units never appear.\n\n**Scope:** `properties:read`", "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string", "example": "available" }, "description": "available, funded, resale — comma-separated." }, { "name": "city", "in": "query", "schema": { "type": "string" } }, { "name": "search", "in": "query", "schema": { "type": "string" }, "description": "Matches name (EN/AR), code, city, address, project." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "nextCursor from the previous page." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data", "hasMore" ], "properties": { "object": { "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Property" } }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": [ "string", "null" ], "description": "Pass as `cursor` to get the next page." } } } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "429": { "$ref": "#/components/responses/E429" } }, "x-scope": "properties:read", "operationId": "listProperties" } }, "/properties/{id}": { "get": { "tags": [ "Properties" ], "summary": "Get a property", "description": "By id (`prop_…`) or property code (`AMT-26-017`).\n\n**Scope:** `properties:read`", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Property id or code", "schema": { "type": "string", "example": "prop_6712c0ffee0123456789abcd" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Property" } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "429": { "$ref": "#/components/responses/E429" } }, "x-scope": "properties:read", "operationId": "getProperty" } }, "/quotes": { "post": { "tags": [ "Properties" ], "summary": "Price a purchase", "description": "Indicative price of N shares, with fees, exactly as an order would be priced now. Reserves nothing.\n\n**Scope:** `properties:read`", "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Quote" } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "422": { "$ref": "#/components/responses/E422" }, "429": { "$ref": "#/components/responses/E429" } }, "x-scope": "properties:read", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuoteRequest" }, "examples": { "quote": { "value": { "property": "AMT-26-017", "shares": 10 } } } } } }, "operationId": "createQuote" } }, "/customers": { "post": { "tags": [ "Customers" ], "summary": "Create or link a customer", "description": "Give the customer's Egyptian mobile number (the one they will use in the Amtaar app).\n\n- **New to Amtaar** → an Amtaar account is opened and attributed to you (`201`, status `onboarding` or `active`). Needs `createCustomers`.\n- **Already an Amtaar investor** → a link waiting for their consent is created (`201`, status `pending_consent`); nothing about them is shared until they confirm the code Amtaar texts them (`/consent`, `/consent/verify`). Needs `linkExistingCustomers`.\n- **Already linked to you** (same phone or same `externalId`) → the existing customer (`200`).\n\n`kyc` lets you vouch for your own regulated KYC of this person; it counts for API orders only if your account has `partnerKycReliance`. Otherwise the customer completes Amtaar KYC in the app.\n\n**Scope:** `customers:write`", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique value per operation (a UUID). Retrying with the same key and body returns the first answer and never repeats the action. Kept 24 hours.", "schema": { "type": "string", "minLength": 8, "maxLength": 255 } } ], "responses": { "201": { "description": "Created (or 200 when it already existed)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Customer" } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "409": { "$ref": "#/components/responses/E409" }, "422": { "$ref": "#/components/responses/E422" }, "429": { "$ref": "#/components/responses/E429" } }, "x-scope": "customers:write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerCreate" }, "examples": { "minimal": { "value": { "phone": "+201001234567", "externalId": "telda-user-88213" } }, "full": { "value": { "phone": "+201001234567", "externalId": "telda-user-88213", "email": "mona@example.com", "name": { "en": "Mona Ahmed", "ar": "منى أحمد" }, "language": "ar", "nationalId": "29001011234567", "kyc": { "provider": "Telda", "reference": "kyc_5f1a", "level": "full", "verifiedAt": "2026-09-01T10:00:00Z" }, "metadata": { "segment": "premium" } } } } } } }, "operationId": "createCustomer" }, "get": { "tags": [ "Customers" ], "summary": "List customers", "description": "Your customers, newest first.\n\n**Scope:** `customers:read`", "parameters": [ { "name": "externalId", "in": "query", "schema": { "type": "string" } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "pending_consent", "active", "unlinked" ] }, "description": "Link status." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "nextCursor from the previous page." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data", "hasMore" ], "properties": { "object": { "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Customer" } }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": [ "string", "null" ], "description": "Pass as `cursor` to get the next page." } } } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "429": { "$ref": "#/components/responses/E429" } }, "x-scope": "customers:read", "operationId": "listCustomers" } }, "/customers/{id}": { "get": { "tags": [ "Customers" ], "summary": "Get a customer", "description": "Includes KYC progress (`kyc.missingSteps`) and whether they can invest through the API (`canInvest`).\n\n**Scope:** `customers:read`", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Customer id", "schema": { "type": "string", "example": "cus_6712c0ffee0123456789abcd" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Customer" } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "429": { "$ref": "#/components/responses/E429" } }, "x-scope": "customers:read", "operationId": "getCustomer" }, "patch": { "tags": [ "Customers" ], "summary": "Update a customer", "description": "Change your `externalId`, `metadata` (merged; a null value removes a key) or your `kyc` attestation (null withdraws it). The person's own data is theirs to change in the app.\n\n**Scope:** `customers:write`", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Customer id", "schema": { "type": "string", "example": "cus_6712c0ffee0123456789abcd" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Customer" } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "409": { "$ref": "#/components/responses/E409" }, "429": { "$ref": "#/components/responses/E429" } }, "x-scope": "customers:write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerUpdate" } } } }, "operationId": "updateCustomer" }, "delete": { "tags": [ "Customers" ], "summary": "Unlink a customer", "description": "Stops all access and events for this customer. Their Amtaar account, holdings and attribution are not affected.\n\n**Scope:** `customers:write`", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Customer id", "schema": { "type": "string", "example": "cus_6712c0ffee0123456789abcd" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Customer" } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "429": { "$ref": "#/components/responses/E429" } }, "x-scope": "customers:write", "operationId": "unlinkCustomer" } }, "/customers/{id}/consent": { "post": { "tags": [ "Customers" ], "summary": "Text the consent code", "description": "For a `pending_consent` customer: Amtaar texts them a 6-digit code (valid 10 minutes; at most one per minute, five per link). In sandbox no SMS is sent and the code is returned as `sandboxCode`.\n\n**Scope:** `customers:write`", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Customer id", "schema": { "type": "string", "example": "cus_6712c0ffee0123456789abcd" } } ], "responses": { "202": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConsentRequest" } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "409": { "$ref": "#/components/responses/E409" }, "429": { "$ref": "#/components/responses/E429" }, "503": { "$ref": "#/components/responses/E503" } }, "x-scope": "customers:write", "operationId": "sendCustomerConsentCode" } }, "/customers/{id}/consent/verify": { "post": { "tags": [ "Customers" ], "summary": "Confirm the consent code", "description": "The code the customer read out to you. Five wrong tries cancel the code. On success the customer becomes linked (event `customer.linked`).\n\n**Scope:** `customers:write`", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Customer id", "schema": { "type": "string", "example": "cus_6712c0ffee0123456789abcd" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Customer" } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "409": { "$ref": "#/components/responses/E409" }, "429": { "$ref": "#/components/responses/E429" } }, "x-scope": "customers:write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string", "description": "6 digits", "pattern": "^\\d{6}$" } } } } } }, "operationId": "verifyCustomerConsentCode" } }, "/customers/{id}/holdings": { "get": { "tags": [ "Portfolio" ], "summary": "Holdings", "description": "Shares the customer owns per property, what they paid, and total rental income received.\n\n**Scope:** `portfolio:read` · **Capability:** `portfolioAccess` (switched on by Amtaar)", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Customer id", "schema": { "type": "string", "example": "cus_6712c0ffee0123456789abcd" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Portfolio" } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "429": { "$ref": "#/components/responses/E429" } }, "x-scope": "portfolio:read", "operationId": "getCustomerHoldings" } }, "/customers/{id}/payouts": { "get": { "tags": [ "Portfolio" ], "summary": "Rental payouts", "description": "Rental income paid to the customer's Amtaar wallet, newest first.\n\n**Scope:** `portfolio:read` · **Capability:** `portfolioAccess` (switched on by Amtaar)", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Customer id", "schema": { "type": "string", "example": "cus_6712c0ffee0123456789abcd" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "nextCursor from the previous page." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data", "hasMore" ], "properties": { "object": { "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Payout" } }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": [ "string", "null" ], "description": "Pass as `cursor` to get the next page." } } } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "429": { "$ref": "#/components/responses/E429" } }, "x-scope": "portfolio:read", "operationId": "listCustomerPayouts" } }, "/customers/{id}/contracts": { "get": { "tags": [ "Portfolio" ], "summary": "Investment contracts", "description": "Contract numbers and signing status. Documents are available to the customer in the Amtaar app.\n\n**Scope:** `portfolio:read` · **Capability:** `portfolioAccess` (switched on by Amtaar)", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Customer id", "schema": { "type": "string", "example": "cus_6712c0ffee0123456789abcd" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data", "hasMore" ], "properties": { "object": { "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Contract" } }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": [ "string", "null" ], "description": "Pass as `cursor` to get the next page." } } } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "429": { "$ref": "#/components/responses/E429" } }, "x-scope": "portfolio:read", "operationId": "listCustomerContracts" } }, "/customers/{id}/wallet": { "get": { "tags": [ "Portfolio" ], "summary": "Wallet balance", "description": "The customer's Amtaar wallet: cash (rental income, top-ups, refunds) and rewards; `reserved` is held for pending orders or withdrawals.\n\n**Scope:** `wallet:read` · **Capability:** `walletAccess` (switched on by Amtaar)", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Customer id", "schema": { "type": "string", "example": "cus_6712c0ffee0123456789abcd" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Wallet" } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "429": { "$ref": "#/components/responses/E429" } }, "x-scope": "wallet:read", "operationId": "getCustomerWallet" } }, "/orders": { "post": { "tags": [ "Orders" ], "summary": "Place an order", "description": "Reserves the shares at today's price and opens the order. The customer must be linked and able to invest (`canInvest`).\n\n- `partner_settlement` (needs `partnerSettlementOrders`): you collect the money from your customer. Include `funding.settlement` now if you already debited them, or call `/orders/{id}/settlement` before `expiresAt`. The amount must equal `amounts.payable`.\n- `card_checkout` (needs `cardCheckoutOrders`): open `funding.checkoutUrl` for the customer within 60 minutes.\n\nYour per-order and daily limits apply (see `GET /me`).\n\n**Scope:** `orders:write`", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique value per operation (a UUID). Retrying with the same key and body returns the first answer and never repeats the action. Kept 24 hours.", "schema": { "type": "string", "minLength": 8, "maxLength": 255 } } ], "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "409": { "$ref": "#/components/responses/E409" }, "422": { "$ref": "#/components/responses/E422" }, "429": { "$ref": "#/components/responses/E429" }, "503": { "$ref": "#/components/responses/E503" } }, "x-scope": "orders:write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderCreate" }, "examples": { "settled": { "summary": "Partner already debited the customer", "value": { "customer": "cus_6712c0ffee0123456789abcd", "property": "AMT-26-017", "shares": 10, "externalReference": "telda-ord-55120", "funding": { "method": "partner_settlement", "settlement": { "reference": "TRX-99812", "amount": 102667.12, "paidAt": "2026-10-18T09:30:00Z" } }, "metadata": { "campaign": "oct-launch" } } }, "card": { "summary": "Hosted card page", "value": { "customer": "cus_6712c0ffee0123456789abcd", "property": "prop_6935d973731247ba131fa5ae", "shares": 2, "funding": { "method": "card_checkout" } } } } } } }, "operationId": "createOrder" }, "get": { "tags": [ "Orders" ], "summary": "List orders", "description": "Orders you placed (`source=api`) and orders your linked customers placed in the Amtaar app (`source=app`).\n\n**Scope:** `orders:read`", "parameters": [ { "name": "customer", "in": "query", "schema": { "type": "string" } }, { "name": "status", "in": "query", "schema": { "type": "string" }, "description": "Public status, comma-separated." }, { "name": "source", "in": "query", "schema": { "type": "string", "enum": [ "api", "app" ] } }, { "name": "externalReference", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "nextCursor from the previous page." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data", "hasMore" ], "properties": { "object": { "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Order" } }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": [ "string", "null" ], "description": "Pass as `cursor` to get the next page." } } } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "429": { "$ref": "#/components/responses/E429" } }, "x-scope": "orders:read", "operationId": "listOrders" } }, "/orders/{id}": { "get": { "tags": [ "Orders" ], "summary": "Get an order", "description": "The current state — the source of truth when webhooks arrive out of order.\n\n**Scope:** `orders:read`", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Order id", "schema": { "type": "string", "example": "ord_6712c0ffee0123456789abcd" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "429": { "$ref": "#/components/responses/E429" } }, "x-scope": "orders:read", "operationId": "getOrder" } }, "/orders/{id}/settlement": { "post": { "tags": [ "Orders" ], "summary": "Report your settlement", "description": "For a `partner_settlement` order awaiting payment: the reference and exact amount of the transfer you are making to Amtaar. The order moves to `payment_under_review` until Amtaar Finance confirms the money arrived.\n\n**Scope:** `orders:write` · **Capability:** `partnerSettlementOrders` (switched on by Amtaar)", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Order id", "schema": { "type": "string", "example": "ord_6712c0ffee0123456789abcd" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique value per operation (a UUID). Retrying with the same key and body returns the first answer and never repeats the action. Kept 24 hours.", "schema": { "type": "string", "minLength": 8, "maxLength": 255 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "409": { "$ref": "#/components/responses/E409" }, "422": { "$ref": "#/components/responses/E422" }, "429": { "$ref": "#/components/responses/E429" } }, "x-scope": "orders:write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Settlement" } } } }, "operationId": "submitOrderSettlement" } }, "/orders/{id}/cancel": { "post": { "tags": [ "Orders" ], "summary": "Cancel an unpaid order", "description": "Only orders you placed, while `awaiting_payment`. The shares are released at once. A paid order can only be cancelled by the customer in the app (fees may apply).\n\n**Scope:** `orders:write`", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Order id", "schema": { "type": "string", "example": "ord_6712c0ffee0123456789abcd" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Unique value per operation (a UUID). Retrying with the same key and body returns the first answer and never repeats the action. Kept 24 hours.", "schema": { "type": "string", "minLength": 8, "maxLength": 255 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "409": { "$ref": "#/components/responses/E409" }, "429": { "$ref": "#/components/responses/E429" } }, "x-scope": "orders:write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "description": "Shown to Amtaar staff", "maxLength": 200 } } } } } }, "operationId": "cancelOrder" } }, "/commissions": { "get": { "tags": [ "Commissions" ], "summary": "Commission ledger", "description": "Every credit and debit on your partner ledger: signup fees, purchase commissions, bonuses, payouts to you, adjustments and reversals. `testMode` rows were recorded while your account was in test (dry-run) mode and are not payable.\n\n**Scope:** `commissions:read`", "parameters": [ { "name": "type", "in": "query", "schema": { "type": "string" }, "description": "signup_fee, purchase_commission, bonus, payout, adjustment, reversal — comma-separated." }, { "name": "from", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "nextCursor from the previous page." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data", "hasMore" ], "properties": { "object": { "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Commission" } }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": [ "string", "null" ], "description": "Pass as `cursor` to get the next page." } } } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "429": { "$ref": "#/components/responses/E429" } }, "x-scope": "commissions:read", "operationId": "listCommissions" } }, "/commissions/summary": { "get": { "tags": [ "Commissions" ], "summary": "Commission totals", "description": "Totals earned and paid out, and the balance Amtaar owes you (test-mode rows excluded).\n\n**Scope:** `commissions:read`", "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommissionSummary" } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "429": { "$ref": "#/components/responses/E429" } }, "x-scope": "commissions:read", "operationId": "getCommissionSummary" } }, "/events": { "get": { "tags": [ "Events" ], "summary": "List events", "description": "Newest first. With `after=` the list is oldest first from that event on — use it to catch up after downtime (repeat with `lastEventId` until `hasMore` is false).\n\n**Scope:** `events:read`", "parameters": [ { "name": "type", "in": "query", "schema": { "type": "string" }, "description": "Comma-separated event types." }, { "name": "after", "in": "query", "schema": { "type": "string" }, "description": "Event id to continue after." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "nextCursor from the previous page." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data", "hasMore" ], "properties": { "object": { "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Event" } }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": [ "string", "null" ], "description": "Pass as `cursor` to get the next page." } } } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "429": { "$ref": "#/components/responses/E429" } }, "x-scope": "events:read", "operationId": "listEvents" } }, "/events/{id}": { "get": { "tags": [ "Events" ], "summary": "Get an event", "description": "\n\n**Scope:** `events:read`", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Event id", "schema": { "type": "string", "example": "evt_6712c0ffee0123456789abcd" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "429": { "$ref": "#/components/responses/E429" } }, "x-scope": "events:read", "operationId": "getEvent" } }, "/webhook-endpoints": { "get": { "tags": [ "Webhooks" ], "summary": "List webhook endpoints", "description": "\n\n**Scope:** `webhooks:manage`", "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data", "hasMore" ], "properties": { "object": { "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEndpoint" } }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": [ "string", "null" ], "description": "Pass as `cursor` to get the next page." } } } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "429": { "$ref": "#/components/responses/E429" } }, "x-scope": "webhooks:manage", "operationId": "listWebhookEndpoints" }, "post": { "tags": [ "Webhooks" ], "summary": "Add a webhook endpoint", "description": "Live endpoints must be public `https` URLs. The signing `secret` is returned only in this answer. At most 10 endpoints.\n\n**Scope:** `webhooks:manage`", "parameters": [], "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpoint" } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "409": { "$ref": "#/components/responses/E409" }, "429": { "$ref": "#/components/responses/E429" } }, "x-scope": "webhooks:manage", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointCreate" }, "examples": { "all": { "value": { "url": "https://partner.example.com/amtaar/webhooks", "events": [ "order.paid", "order.completed", "customer.kyc_verified" ] } } } } } }, "operationId": "createWebhookEndpoint" } }, "/webhook-endpoints/{id}": { "get": { "tags": [ "Webhooks" ], "summary": "Get a webhook endpoint", "description": "\n\n**Scope:** `webhooks:manage`", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Endpoint id", "schema": { "type": "string", "example": "we_6712c0ffee0123456789abcd" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpoint" } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "429": { "$ref": "#/components/responses/E429" } }, "x-scope": "webhooks:manage", "operationId": "getWebhookEndpoint" }, "patch": { "tags": [ "Webhooks" ], "summary": "Update a webhook endpoint", "description": "Change url, events, description, or status (`enabled` re-enables an endpoint that was disabled after repeated failures).\n\n**Scope:** `webhooks:manage`", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Endpoint id", "schema": { "type": "string", "example": "we_6712c0ffee0123456789abcd" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpoint" } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "429": { "$ref": "#/components/responses/E429" } }, "x-scope": "webhooks:manage", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointUpdate" } } } }, "operationId": "updateWebhookEndpoint" }, "delete": { "tags": [ "Webhooks" ], "summary": "Delete a webhook endpoint", "description": "\n\n**Scope:** `webhooks:manage`", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Endpoint id", "schema": { "type": "string", "example": "we_6712c0ffee0123456789abcd" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "429": { "$ref": "#/components/responses/E429" } }, "x-scope": "webhooks:manage", "operationId": "deleteWebhookEndpoint" } }, "/webhook-endpoints/{id}/rotate-secret": { "post": { "tags": [ "Webhooks" ], "summary": "Roll the signing secret", "description": "The old secret stops working immediately; the new one is in this answer only.\n\n**Scope:** `webhooks:manage`", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Endpoint id", "schema": { "type": "string", "example": "we_6712c0ffee0123456789abcd" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpoint" } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "429": { "$ref": "#/components/responses/E429" } }, "x-scope": "webhooks:manage", "operationId": "rotateWebhookSecret" } }, "/webhook-endpoints/{id}/test": { "post": { "tags": [ "Webhooks" ], "summary": "Send a test event", "description": "Delivers a signed `webhook.test` event now and reports your server's answer.\n\n**Scope:** `webhooks:manage`", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Endpoint id", "schema": { "type": "string", "example": "we_6712c0ffee0123456789abcd" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "statusCode": { "type": [ "integer", "null" ] }, "error": { "type": [ "string", "null" ] }, "durationMs": { "type": "integer" }, "eventId": { "type": "string" }, "deliveryId": { "type": "string" } } } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "409": { "$ref": "#/components/responses/E409" }, "429": { "$ref": "#/components/responses/E429" } }, "x-scope": "webhooks:manage", "operationId": "testWebhookEndpoint" } }, "/webhook-deliveries": { "get": { "tags": [ "Webhooks" ], "summary": "List deliveries", "description": "Delivery attempts and their outcome, newest first.\n\n**Scope:** `webhooks:manage`", "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "pending", "succeeded", "failed" ] } }, { "name": "endpoint", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "nextCursor from the previous page." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data", "hasMore" ], "properties": { "object": { "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookDelivery" } }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": [ "string", "null" ], "description": "Pass as `cursor` to get the next page." } } } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "429": { "$ref": "#/components/responses/E429" } }, "x-scope": "webhooks:manage", "operationId": "listWebhookDeliveries" } }, "/webhook-deliveries/{id}/retry": { "post": { "tags": [ "Webhooks" ], "summary": "Retry a delivery", "description": "Queues a failed (or pending) delivery to be sent again now.\n\n**Scope:** `webhooks:manage`", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Delivery id", "schema": { "type": "string", "example": "whd_6712c0ffee0123456789abcd" } } ], "responses": { "202": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "429": { "$ref": "#/components/responses/E429" } }, "x-scope": "webhooks:manage", "operationId": "retryWebhookDelivery" } }, "/sandbox/customers/{id}/complete-kyc": { "post": { "tags": [ "Sandbox" ], "summary": "Complete KYC (sandbox)", "description": "Marks the customer as fully verified, as if they finished KYC in the app. Fires `customer.kyc_verified` within a minute.\n\n**Scope:** `customers:write`", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Customer id", "schema": { "type": "string", "example": "cus_6712c0ffee0123456789abcd" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Customer" } } } }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" } }, "x-scope": "customers:write", "operationId": "sandboxCompleteKyc" } }, "/sandbox/orders/{id}/simulate": { "post": { "tags": [ "Sandbox" ], "summary": "Move an order along (sandbox)", "description": "`paid` = Finance accepted the payment; `completed` = paid and ownership issued; `payment_rejected` = Finance rejected it.\n\n**Scope:** `orders:write`", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Order id", "schema": { "type": "string", "example": "ord_6712c0ffee0123456789abcd" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "409": { "$ref": "#/components/responses/E409" } }, "x-scope": "orders:write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "to" ], "properties": { "to": { "type": "string", "enum": [ "paid", "completed", "payment_rejected" ] } } } } } }, "operationId": "sandboxSimulateOrder" } } }, "webhooks": { "customer.created": { "post": { "summary": "customer.created", "description": "Sent when you opened a new Amtaar account (data.customer).", "parameters": [ { "name": "Amtaar-Signature", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Amtaar-Event-Id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Amtaar-Event-Type", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Amtaar-Delivery-Id", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" } } } }, "responses": { "200": { "description": "Any 2xx acknowledges the delivery." } }, "operationId": "onCustomerCreated" } }, "customer.linked": { "post": { "summary": "customer.linked", "description": "Sent when an existing investor confirmed the link (data.customer).", "parameters": [ { "name": "Amtaar-Signature", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Amtaar-Event-Id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Amtaar-Event-Type", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Amtaar-Delivery-Id", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" } } } }, "responses": { "200": { "description": "Any 2xx acknowledges the delivery." } }, "operationId": "onCustomerLinked" } }, "customer.kyc_verified": { "post": { "summary": "customer.kyc_verified", "description": "Sent when a linked customer finished Amtaar KYC (data.customer).", "parameters": [ { "name": "Amtaar-Signature", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Amtaar-Event-Id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Amtaar-Event-Type", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Amtaar-Delivery-Id", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" } } } }, "responses": { "200": { "description": "Any 2xx acknowledges the delivery." } }, "operationId": "onCustomerKycVerified" } }, "customer.unlinked": { "post": { "summary": "customer.unlinked", "description": "Sent when a customer was unlinked (data.customer).", "parameters": [ { "name": "Amtaar-Signature", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Amtaar-Event-Id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Amtaar-Event-Type", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Amtaar-Delivery-Id", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" } } } }, "responses": { "200": { "description": "Any 2xx acknowledges the delivery." } }, "operationId": "onCustomerUnlinked" } }, "order.created": { "post": { "summary": "order.created", "description": "Sent when an order exists — placed by you, or by your customer in the app (data.order).", "parameters": [ { "name": "Amtaar-Signature", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Amtaar-Event-Id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Amtaar-Event-Type", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Amtaar-Delivery-Id", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" } } } }, "responses": { "200": { "description": "Any 2xx acknowledges the delivery." } }, "operationId": "onOrderCreated" } }, "order.payment_under_review": { "post": { "summary": "order.payment_under_review", "description": "Sent when payment evidence arrived and Finance is checking it (data.order).", "parameters": [ { "name": "Amtaar-Signature", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Amtaar-Event-Id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Amtaar-Event-Type", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Amtaar-Delivery-Id", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" } } } }, "responses": { "200": { "description": "Any 2xx acknowledges the delivery." } }, "operationId": "onOrderPaymentUnderReview" } }, "order.paid": { "post": { "summary": "order.paid", "description": "Sent when the money is confirmed (data.order).", "parameters": [ { "name": "Amtaar-Signature", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Amtaar-Event-Id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Amtaar-Event-Type", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Amtaar-Delivery-Id", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" } } } }, "responses": { "200": { "description": "Any 2xx acknowledges the delivery." } }, "operationId": "onOrderPaid" } }, "order.completed": { "post": { "summary": "order.completed", "description": "Sent when the shares are issued to the customer (data.order).", "parameters": [ { "name": "Amtaar-Signature", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Amtaar-Event-Id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Amtaar-Event-Type", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Amtaar-Delivery-Id", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" } } } }, "responses": { "200": { "description": "Any 2xx acknowledges the delivery." } }, "operationId": "onOrderCompleted" } }, "order.cancelled": { "post": { "summary": "order.cancelled", "description": "Sent when the order was cancelled or expired unpaid; its shares are released (data.order).", "parameters": [ { "name": "Amtaar-Signature", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Amtaar-Event-Id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Amtaar-Event-Type", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Amtaar-Delivery-Id", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" } } } }, "responses": { "200": { "description": "Any 2xx acknowledges the delivery." } }, "operationId": "onOrderCancelled" } }, "order.payment_rejected": { "post": { "summary": "order.payment_rejected", "description": "Sent when Finance rejected the payment (data.order).", "parameters": [ { "name": "Amtaar-Signature", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Amtaar-Event-Id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Amtaar-Event-Type", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Amtaar-Delivery-Id", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" } } } }, "responses": { "200": { "description": "Any 2xx acknowledges the delivery." } }, "operationId": "onOrderPaymentRejected" } }, "order.refunded": { "post": { "summary": "order.refunded", "description": "Sent when the order was refunded (data.order).", "parameters": [ { "name": "Amtaar-Signature", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Amtaar-Event-Id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Amtaar-Event-Type", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Amtaar-Delivery-Id", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" } } } }, "responses": { "200": { "description": "Any 2xx acknowledges the delivery." } }, "operationId": "onOrderRefunded" } }, "order.cancellation_requested": { "post": { "summary": "order.cancellation_requested", "description": "Sent when the customer asked to cancel a paid order (data.order).", "parameters": [ { "name": "Amtaar-Signature", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Amtaar-Event-Id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Amtaar-Event-Type", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Amtaar-Delivery-Id", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" } } } }, "responses": { "200": { "description": "Any 2xx acknowledges the delivery." } }, "operationId": "onOrderCancellationRequested" } }, "payout.paid": { "post": { "summary": "payout.paid", "description": "Sent when rental income reached the customer's wallet (data.customer, data.payout). Needs portfolioAccess.", "parameters": [ { "name": "Amtaar-Signature", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Amtaar-Event-Id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Amtaar-Event-Type", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Amtaar-Delivery-Id", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" } } } }, "responses": { "200": { "description": "Any 2xx acknowledges the delivery." } }, "operationId": "onPayoutPaid" } }, "commission.created": { "post": { "summary": "commission.created", "description": "Sent when a row was added to your commission ledger (data.commission).", "parameters": [ { "name": "Amtaar-Signature", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Amtaar-Event-Id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Amtaar-Event-Type", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Amtaar-Delivery-Id", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" } } } }, "responses": { "200": { "description": "Any 2xx acknowledges the delivery." } }, "operationId": "onCommissionCreated" } } }, "components": { "securitySchemes": { "apiKey": { "type": "http", "scheme": "bearer", "bearerFormat": "amtk___", "description": "Your API key." } }, "responses": { "E400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "E401": { "description": "Missing, invalid, revoked or wrong-environment key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "E403": { "description": "Missing scope or capability, or not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "E404": { "description": "Not found (or not yours)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "E409": { "description": "Conflicts with the current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "E422": { "description": "Valid but cannot be done (limits, amount mismatch, idempotency key reuse)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "E429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "E500": { "description": "Our error — safe to retry with the same Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "E503": { "description": "A dependency is unavailable — retry later", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "schemas": { "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "type", "code", "message" ], "properties": { "type": { "type": "string", "enum": [ "invalid_request", "authentication_error", "permission_denied", "not_found", "conflict", "unprocessable", "idempotency_error", "rate_limited", "api_error", "service_unavailable" ] }, "code": { "type": "string", "description": "Stable machine reason", "examples": [ "invalid_phone", "missing_scope", "capability_not_enabled", "customer_not_eligible", "consent_required", "amount_mismatch", "order_not_cancellable", "idempotency_key_reused", "property_not_available", "order_limit_exceeded" ] }, "message": { "type": "string", "description": "Human-readable explanation" }, "param": { "type": "string", "description": "The request field at fault, when there is one" }, "details": { "type": "object", "description": "Extra context, e.g. missingSteps or expected amount" }, "requestId": { "type": "string", "description": "Quote it when contacting Amtaar" } } } } }, "Account": { "type": "object", "properties": { "object": { "const": "account" }, "partner": { "type": "object", "properties": { "name": { "type": "string" }, "mode": { "type": "string", "enum": [ "live", "test" ], "description": "test = commissions recorded but not payable" } } }, "environment": { "type": "string", "enum": [ "live", "sandbox" ] }, "apiKey": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "prefix": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "properties:read", "customers:read", "customers:write", "orders:read", "orders:write", "portfolio:read", "wallet:read", "commissions:read", "events:read", "webhooks:manage" ] } }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time", "description": "" } } }, "capabilities": { "type": "object", "properties": { "createCustomers": { "type": "boolean" }, "linkExistingCustomers": { "type": "boolean" }, "partnerKycReliance": { "type": "boolean" }, "partnerSettlementOrders": { "type": "boolean" }, "cardCheckoutOrders": { "type": "boolean" }, "portfolioAccess": { "type": "boolean" }, "walletAccess": { "type": "boolean" } } }, "limits": { "type": "object", "properties": { "requestsPerMinute": { "type": "integer" }, "maxOrderAmount": { "type": [ "number", "null" ] }, "dailyOrderAmountCap": { "type": [ "number", "null" ] }, "orderHoldMinutes": { "type": "integer" } } }, "links": { "type": "object", "properties": { "app": { "type": "string", "description": "Your Amtaar app download link (tracks attribution)" }, "appSecondary": { "type": [ "string", "null" ] } } }, "commission": { "type": "object", "properties": { "purchaseCommissionPercent": { "type": [ "number", "null" ] }, "commissionBase": { "type": [ "string", "null" ] }, "signupFee": { "type": [ "number", "null" ] } } } } }, "PropertyRef": { "type": "object", "properties": { "id": { "type": "string", "description": "prop_…" }, "code": { "type": [ "string", "null" ], "example": "AMT-26-017" }, "name": { "$ref": "#/components/schemas/LocalizedText" } } }, "LocalizedText": { "type": "object", "properties": { "en": { "type": [ "string", "null" ] }, "ar": { "type": [ "string", "null" ] } } }, "Property": { "type": "object", "properties": { "object": { "const": "property" }, "id": { "type": "string", "description": "prop_…" }, "code": { "type": [ "string", "null" ], "example": "AMT-26-017" }, "name": { "$ref": "#/components/schemas/LocalizedText" }, "description": { "$ref": "#/components/schemas/LocalizedText" }, "type": { "type": [ "string", "null" ], "example": "Office" }, "project": { "type": [ "string", "null" ] }, "developer": { "type": [ "string", "null" ] }, "location": { "type": "object", "properties": { "address": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "country": { "type": "string" }, "mapUrl": { "type": [ "string", "null" ] } } }, "areaSqm": { "type": [ "number", "null" ] }, "status": { "type": "string", "enum": [ "available", "funded", "resale" ], "description": "available = open for investment" }, "isRented": { "type": "boolean" }, "media": { "type": "object", "properties": { "cover": { "type": [ "string", "null" ] }, "images": { "type": "array", "items": { "type": "string" } } } }, "shares": { "type": "object", "properties": { "total": { "type": [ "integer", "null" ] }, "available": { "type": [ "integer", "null" ], "description": "Indicative; the order checks again atomically" }, "sold": { "type": [ "integer", "null" ] }, "reserved": { "type": [ "integer", "null" ] }, "minimumPerOrder": { "type": "integer" } } }, "pricing": { "type": "object", "properties": { "currency": { "type": "string" }, "pricePerShare": { "type": [ "number", "null" ] }, "managementFeePercent": { "type": "number", "description": "Added on top of the share price at purchase" } } }, "forecast": { "type": "object", "description": "Amtaar's projections, not guarantees", "properties": { "roiPercent": { "type": [ "number", "null" ] }, "rentalYieldPercent": { "type": [ "number", "null" ] }, "capitalGainPercent": { "type": [ "number", "null" ] }, "years": { "type": [ "number", "null" ] } } }, "fundingDeadline": { "type": [ "string", "null" ], "format": "date-time", "description": "" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "" } } }, "QuoteRequest": { "type": "object", "required": [ "property", "shares" ], "properties": { "property": { "type": "string", "description": "Property id or code" }, "shares": { "type": "integer", "minimum": 1 } } }, "Quote": { "type": "object", "properties": { "object": { "const": "quote" }, "property": { "$ref": "#/components/schemas/PropertyRef" }, "shares": { "type": "integer" }, "currency": { "type": "string" }, "pricePerShare": { "type": "number", "description": "Price of one share (EGP, 2 decimals)" }, "subtotal": { "type": "number", "description": "shares × price (EGP, 2 decimals)" }, "fees": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "example": "management_fee" }, "percent": { "type": "number" }, "amount": { "type": "number" } } } }, "total": { "type": "number", "description": "What the order would cost (EGP, 2 decimals)" }, "available": { "type": "boolean" }, "sharesAvailable": { "type": "integer" }, "note": { "type": "string" }, "quotedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "" } } }, "KycAttestation": { "type": "object", "required": [ "provider", "reference" ], "description": "Your own KYC of this person. Counts for API orders only with the partnerKycReliance capability.", "properties": { "provider": { "type": "string", "description": "Who verified (you, or your KYC vendor)" }, "reference": { "type": "string", "description": "Your KYC case id" }, "level": { "type": "string", "description": "e.g. full, simplified" }, "verifiedAt": { "type": "string", "format": "date-time" } } }, "CustomerCreate": { "type": "object", "required": [ "phone" ], "properties": { "phone": { "type": "string", "description": "Egyptian mobile, any common format (+2010…, 010…)", "example": "+201001234567" }, "externalId": { "type": "string", "description": "Your id for this person (unique per partner)", "maxLength": 128 }, "email": { "type": "string", "format": "email" }, "name": { "$ref": "#/components/schemas/LocalizedText" }, "language": { "type": "string", "enum": [ "en", "ar" ], "default": "en" }, "nationalId": { "type": "string", "description": "14-digit Egyptian national ID — only used to stop duplicate accounts; not stored" }, "kyc": { "$ref": "#/components/schemas/KycAttestation" }, "metadata": { "$ref": "#/components/schemas/Metadata" } } }, "CustomerUpdate": { "type": "object", "properties": { "externalId": { "type": [ "string", "null" ] }, "metadata": { "$ref": "#/components/schemas/Metadata" }, "kyc": { "oneOf": [ { "$ref": "#/components/schemas/KycAttestation" }, { "type": "null" } ] } } }, "Metadata": { "type": "object", "additionalProperties": { "type": "string", "maxLength": 500 }, "maxProperties": 20, "description": "Your key/value pairs" }, "Customer": { "type": "object", "properties": { "object": { "const": "customer" }, "id": { "type": "string", "description": "cus_…" }, "externalId": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "pending_consent", "onboarding", "active", "suspended", "unlinked" ], "description": "pending_consent = waiting for the code; onboarding = linked, cannot invest yet; active = can invest; suspended = account blocked by Amtaar" }, "origin": { "type": "string", "enum": [ "created", "linked" ] }, "phone": { "type": [ "string", "null" ], "description": "Masked until linked" }, "email": { "type": [ "string", "null" ] }, "name": { "$ref": "#/components/schemas/LocalizedText" }, "language": { "type": "string" }, "kyc": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "verified", "partner_verified", "pending" ] }, "amtaarVerified": { "type": "boolean" }, "partnerAttested": { "type": "boolean" }, "missingSteps": { "type": "array", "items": { "type": "string", "enum": [ "phone_verification", "email_verification", "pin_setup", "identity_verification" ] } }, "steps": { "type": "object", "properties": { "phoneVerified": { "type": "boolean" }, "emailVerified": { "type": "boolean" }, "pinCreated": { "type": "boolean" }, "identityVerified": { "type": "boolean" } } } } }, "canInvest": { "type": "boolean", "description": "Whether POST /orders will accept this customer now" }, "attribution": { "type": "object", "properties": { "attributedToYou": { "type": "boolean", "description": "Commissions on their purchases are yours" }, "attributedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "" } } }, "links": { "type": "object", "properties": { "app": { "type": "string", "description": "Send the customer here to install the Amtaar app" } } }, "nextAction": { "type": "object", "properties": { "type": { "type": "string" }, "description": { "type": "string" } } }, "metadata": { "$ref": "#/components/schemas/Metadata" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time", "description": "" }, "linkedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "" } } }, "ConsentRequest": { "type": "object", "properties": { "object": { "const": "consent_request" }, "customer": { "type": "string" }, "sentTo": { "type": "string", "description": "Masked mobile" }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time", "description": "" }, "sandboxCode": { "type": "string", "description": "Sandbox only" } } }, "OrderCreate": { "type": "object", "required": [ "customer", "property", "shares", "funding" ], "properties": { "customer": { "type": "string", "description": "cus_…" }, "property": { "type": "string", "description": "Property id or code" }, "shares": { "type": "integer", "minimum": 1 }, "externalReference": { "type": "string", "description": "Your order id (unique per partner)", "maxLength": 128 }, "funding": { "type": "object", "required": [ "method" ], "properties": { "method": { "type": "string", "enum": [ "partner_settlement", "card_checkout" ] }, "settlement": { "$ref": "#/components/schemas/Settlement" } } }, "metadata": { "$ref": "#/components/schemas/Metadata" } } }, "Settlement": { "type": "object", "required": [ "reference", "amount" ], "properties": { "reference": { "type": "string", "description": "Your transfer / transaction reference to Amtaar's account" }, "amount": { "type": "number", "description": "Must equal the order's amounts.payable (EGP, 2 decimals)" }, "paidAt": { "type": "string", "format": "date-time" }, "proofUrl": { "type": "string", "description": "https link to a transfer receipt, if you have one" }, "note": { "type": "string", "description": "Free text for Amtaar Finance", "maxLength": 300 } } }, "Order": { "type": "object", "properties": { "object": { "const": "order" }, "id": { "type": "string", "description": "ord_…" }, "number": { "type": "string", "description": "Amtaar order number", "example": "AM2610180001" }, "customer": { "type": "string", "description": "cus_…" }, "status": { "type": "string", "enum": [ "awaiting_payment", "payment_under_review", "paid", "completed", "cancelled", "payment_rejected", "cancellation_requested", "refunded" ] }, "source": { "type": "string", "enum": [ "api", "app" ] }, "externalReference": { "type": [ "string", "null" ] }, "items": { "type": "array", "items": { "type": "object", "properties": { "property": { "$ref": "#/components/schemas/PropertyRef" }, "shares": { "type": "integer" } } } }, "property": { "oneOf": [ { "$ref": "#/components/schemas/PropertyRef" }, { "type": "null" } ], "description": "Set when the order has one property (API orders always do)" }, "shares": { "type": "integer" }, "amounts": { "type": "object", "properties": { "currency": { "type": "string" }, "gross": { "type": "number", "description": "Shares + fees before discounts (EGP, 2 decimals)" }, "discount": { "type": "number", "description": "Promo and rewards (EGP, 2 decimals)" }, "walletApplied": { "type": "number", "description": "Paid from the customer's Amtaar wallet (EGP, 2 decimals)" }, "payable": { "type": "number", "description": "Still to be paid (EGP, 2 decimals)" } } }, "funding": { "type": "object", "properties": { "method": { "type": "string", "enum": [ "partner_settlement", "card_checkout", "in_app" ] }, "checkoutUrl": { "type": [ "string", "null" ] }, "settlement": { "oneOf": [ { "type": "object", "properties": { "reference": { "type": "string" }, "amount": { "type": "number" }, "paidAt": { "type": [ "string", "null" ], "format": "date-time", "description": "" }, "submittedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "" } } }, { "type": "null" } ] } } }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When the unpaid reservation ends" }, "cancellation": { "oneOf": [ { "type": "object", "properties": { "reason": { "type": [ "string", "null" ] }, "fee": { "type": [ "number", "null" ] }, "refundAmount": { "type": [ "number", "null" ] }, "cancelledAt": { "type": [ "string", "null" ], "format": "date-time", "description": "" } } }, { "type": "null" } ] }, "metadata": { "$ref": "#/components/schemas/Metadata" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time", "description": "" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "" }, "completedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "" } } }, "Portfolio": { "type": "object", "properties": { "object": { "const": "portfolio" }, "customer": { "type": "string" }, "currency": { "type": "string" }, "summary": { "type": "object", "properties": { "properties": { "type": "integer" }, "shares": { "type": "integer" }, "investedAmount": { "type": "number" }, "rentalIncomeReceived": { "type": "number" } } }, "holdings": { "type": "array", "items": { "$ref": "#/components/schemas/Holding" } } } }, "Holding": { "type": "object", "properties": { "object": { "const": "holding" }, "property": { "$ref": "#/components/schemas/PropertyRef" }, "shares": { "type": "integer" }, "investedAmount": { "type": "number" }, "currency": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "pending_funding" ] }, "firstPurchasedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "" } } }, "Payout": { "type": "object", "properties": { "object": { "const": "payout" }, "id": { "type": "string", "description": "pay_…" }, "property": { "$ref": "#/components/schemas/PropertyRef" }, "period": { "type": [ "object", "null" ], "properties": { "start": { "type": [ "string", "null" ], "format": "date-time", "description": "" }, "end": { "type": [ "string", "null" ], "format": "date-time", "description": "" } } }, "amount": { "type": "number" }, "currency": { "type": "string" }, "sharesEligible": { "type": [ "integer", "null" ] }, "status": { "type": "string", "enum": [ "paid" ] }, "paidAt": { "type": [ "string", "null" ], "format": "date-time", "description": "" } } }, "Contract": { "type": "object", "properties": { "object": { "const": "contract" }, "id": { "type": "string", "description": "ctr_…" }, "number": { "type": [ "string", "null" ], "example": "IC-2026-0466" }, "property": { "$ref": "#/components/schemas/PropertyRef" }, "shares": { "type": [ "integer", "null" ] }, "status": { "type": "string", "enum": [ "preparing", "awaiting_signature", "under_review", "signed" ] }, "signedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time", "description": "" } } }, "Wallet": { "type": "object", "properties": { "object": { "const": "wallet" }, "customer": { "type": "string" }, "currency": { "type": "string" }, "cash": { "type": "object", "properties": { "available": { "type": "number" }, "reserved": { "type": "number" } } }, "rewards": { "type": "object", "properties": { "available": { "type": "number" }, "reserved": { "type": "number" } } }, "total": { "type": "number", "description": "Available cash + available rewards" } } }, "Commission": { "type": "object", "properties": { "object": { "const": "commission" }, "id": { "type": "string", "description": "com_…" }, "type": { "type": "string", "enum": [ "signup_fee", "purchase_commission", "bonus", "payout", "adjustment", "reversal" ] }, "amount": { "type": "number", "description": "Your share (negative for payouts and reversals) (EGP, 2 decimals)" }, "currency": { "type": "string" }, "customerAmount": { "type": "number", "description": "Part credited to the customer instead, under your reward split (EGP, 2 decimals)" }, "customer": { "type": [ "string", "null" ], "description": "Set when the customer is linked to you through the API" }, "order": { "type": [ "string", "null" ] }, "reference": { "type": [ "string", "null" ] }, "testMode": { "type": "boolean" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time", "description": "" } } }, "CommissionSummary": { "type": "object", "properties": { "object": { "const": "commission_summary" }, "currency": { "type": "string" }, "earned": { "type": "object", "properties": { "signupFees": { "type": "number" }, "purchaseCommissions": { "type": "number" }, "bonuses": { "type": "number" }, "adjustments": { "type": "number" } } }, "counts": { "type": "object", "properties": { "signups": { "type": "integer" }, "purchases": { "type": "integer" } } }, "paidOut": { "type": "number" }, "balance": { "type": "number", "description": "Owed to you now" } } }, "Event": { "type": "object", "properties": { "object": { "const": "event" }, "id": { "type": "string", "description": "evt_…" }, "type": { "type": "string", "enum": [ "customer.created", "customer.linked", "customer.kyc_verified", "customer.unlinked", "order.created", "order.payment_under_review", "order.paid", "order.completed", "order.cancelled", "order.payment_rejected", "order.refunded", "order.cancellation_requested", "payout.paid", "commission.created", "webhook.test" ] }, "environment": { "type": "string", "enum": [ "live", "sandbox" ] }, "apiVersion": { "type": "string" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time", "description": "" }, "data": { "type": "object", "description": "customer / order / payout / commission objects, as in the API", "properties": { "customer": {}, "order": { "$ref": "#/components/schemas/Order" }, "payout": { "$ref": "#/components/schemas/Payout" }, "commission": { "$ref": "#/components/schemas/Commission" } } } } }, "WebhookEndpointCreate": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "type": "string", "enum": [ "*", "customer.created", "customer.linked", "customer.kyc_verified", "customer.unlinked", "order.created", "order.payment_under_review", "order.paid", "order.completed", "order.cancelled", "order.payment_rejected", "order.refunded", "order.cancellation_requested", "payout.paid", "commission.created", "webhook.test" ] }, "default": [ "*" ] }, "description": { "type": "string", "maxLength": 200 } } }, "WebhookEndpointUpdate": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "type": "string" } }, "description": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "enabled", "disabled" ] } } }, "WebhookEndpoint": { "type": "object", "properties": { "object": { "const": "webhook_endpoint" }, "id": { "type": "string", "description": "we_…" }, "url": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "events": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string", "enum": [ "enabled", "disabled" ] }, "disabledReason": { "type": [ "string", "null" ] }, "secretPrefix": { "type": "string" }, "secret": { "type": "string", "description": "Only when created or rotated" }, "lastSuccessAt": { "type": [ "string", "null" ], "format": "date-time", "description": "" }, "lastFailureAt": { "type": [ "string", "null" ], "format": "date-time", "description": "" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time", "description": "" } } }, "WebhookDelivery": { "type": "object", "properties": { "object": { "const": "webhook_delivery" }, "id": { "type": "string", "description": "whd_…" }, "endpoint": { "type": "string" }, "event": { "type": "string" }, "eventType": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "succeeded", "failed" ] }, "attempts": { "type": "integer" }, "nextAttemptAt": { "type": [ "string", "null" ], "format": "date-time", "description": "" }, "lastStatusCode": { "type": [ "integer", "null" ] }, "lastError": { "type": [ "string", "null" ] }, "deliveredAt": { "type": [ "string", "null" ], "format": "date-time", "description": "" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time", "description": "" } } } } } }