Connect your API to Wathba.اربطوا API خدمتكم بوثبة.

01How it fits togetherكيف تترابط الأجزاء

02Two independent choicesقراران مستقلان

Agree on both before any code. They are independent: the charging model does not decide the key type.نتفق عليهما قبل كتابة أي كود، وهما مستقلان: نموذج تحصيل الرسوم لا يحدد نوع مفتاح الوصول.

Charging: how your fee is collectedالتحصيل: كيف تُحصَّل رسومكم

Access: how Wathba acts for one accountالوصول: كيف تتصرف وثبة باسم حساب واحد

Any combination is valid: the charging model does not choose the key scope, and an administrative key alone never runs operations.أي تركيبة صالحة: نموذج التحصيل لا يحدد نطاق المفتاح، والمفتاح الإداري وحده لا ينفّذ العمليات.

03Example endpointsأمثلة على نقاط النهاية

Every read is scoped by ownership: a partner sees only its own accounts, and an account sees only its own operations. Member wallet accounting stays inside Wathba; a top-up is a funding and confirmation process, not an endpoint that credits a balance on request.كل قراءة محدودة بالملكية: لا يرى الشريك إلا حساباته، ولا يرى الحساب إلا عملياته. تبقى محاسبة محفظة العضو داخل وثبة، والشحن إجراء للتمويل والتأكيد لا نقطة نهاية تضيف رصيداً عند الطلب.

POST /partner/accounts
Authorization: Bearer <partner_credential>
Idempotency-Key: 7c1e-…                  # same key on every retry
Content-Type: application/json

{
  "client_reference": "wathba-m1042-p7",
  "external_project_ref": "proj_7",
  "business": { "…": "the fields your approval process needs" }
}

201 Created
{ "id": "acc_example", "status": "pending", "client_reference": "wathba-m1042-p7" }

POST /v1/operations
Authorization: Bearer <account_key>                 # Option A
# — or —
Authorization: Bearer <delegated_partner_key>       # Option B
X-Account-Id: acc_example                           # Option B
Idempotency-Key: 9f4a-…                             # same key on every retry
Content-Type: application/json

{ "client_reference": "op-8c2d", "type": "verification", "…": "…" }

202 Accepted
{ "operation_id": "op_example", "status": "pending", "client_reference": "op-8c2d" }

GET /v1/operations/op_example
Authorization: Bearer <same credential as the POST>
X-Account-Id: acc_example                           # Option B
200 OK
{ "operation_id": "op_example", "status": "succeeded", "client_reference": "op-8c2d" }

Names and states are illustrative. What matters: an operation returns an id, a status such as pending, succeeded or failed, and the client reference, so both sides can correlate it.الأسماء والحالات توضيحية. المهم أن تعيد العملية معرّفاً، وحالة مثل pending أو succeeded أو failed، ومرجع العميل، حتى يربطها الطرفان.

04Operation lifecycle and webhooksدورة حياة العملية والإشعارات Webhooks

POST https://<wathba-webhook-url>
X-Signature: sha256=<hmac of the raw body, shared secret>
Content-Type: application/json

{
  "event_id": "evt_example",
  "type": "operation.succeeded",
  "account_id": "acc_example",
  "project_ref": "proj_7",
  "operation_id": "op_example",
  "occurred_at": "2026-09-14T09:30:00Z"
}

05Ready to integrateجاهزون للتكامل

We go to production when every line is checked.ننتقل إلى الإنتاج عند استيفاء كل بند.

• Sandbox documentation and test credentials delivered securely, not by email or chat.وثائق بيئة الاختبار واعتمادات الاختبار مسلّمة بأمان، لا عبر البريد أو الدردشة.
• Account creation with the required approval, and the status readable by API.إنشاء الحساب مع الموافقة المطلوبة، وقراءة الحالة عبر API.
• One successful operation, with each party inside its own boundary.عملية ناجحة واحدة، مع بقاء كل طرف ضمن حدوده.
• Rejected and insufficient-balance behavior, where it applies.سلوك الرفض ونفاد الرصيد، حين ينطبق.
• A retry with the same idempotency key creates one account, one operation, one charge.إعادة المحاولة بنفس مفتاح التكرار تُنشئ حساباً واحداً وعملية واحدة ورسماً واحداً.
• A duplicate webhook is counted once.الإشعار المكرر يُحتسب مرة واحدة.
• Balance and usage reconcile between your records and Wathba’s, for prepaid partners.مطابقة الرصيد والاستخدام بين سجلاتكم وسجلات وثبة، للشركاء بالرصيد المسبق.
• Production approval, then the first member’s operation.اعتماد الإنتاج، ثم أول عملية لأحد الأعضاء.