Amtaar Partner API (2026-10-18)

A 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.

Authorization: Bearer amtk_live_<keyId>_<secret>

Keys 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.

• JSON in and out, UTF-8. Money is EGP with 2 decimals. Times are ISO-8601 UTC.
• Ids are prefixed strings (cus_, ord_, prop_, evt_, we_ …). Treat them as opaque.
• Lists are newest first with cursor pagination: ?limit=20&cursor=<nextCursor>.
• metadata: up to 20 string key/value pairs of yours on customers and orders, returned as given.
• 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.
• Rate limit: per key (default 300 requests/minute). RateLimit-* headers on every answer; 429 + Retry-After when exceeded.
• Every answer carries X-Request-ID (send your own to correlate) and Amtaar-Api-Version: 2026-10-18.

/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.

{ "error": { "type": "invalid_request", "code": "invalid_phone", "message": "…", "param": "phone", "requestId": "…" } }

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.

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.

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).

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.

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). Other 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.

An unpaid API order keeps its shares reserved until expiresAt (your hold time, default 24 h; card checkout 60 min).

Register endpoints with POST /webhook-endpoints (or ask Amtaar). Each event is POSTed as the Event object. Verify every delivery:

Amtaar-Signature: t=1760000000,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd
expected = hex(HMAC_SHA256(endpoint_secret, t + "." + raw_request_body))

Compare 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=<last event id>. Events are generated within about a minute of the change and kept 180 days.

Event 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.

You 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).

Who you are, what your key and account may do.

The investable catalogue and indicative pricing.

Investors you brought or linked.

Holdings, rental payouts, contracts and wallet of a linked customer.

Share purchases — placed by you, or by your customers in the Amtaar app.