binkly للمطوّرين

الدفع والمدفوعات والاسترداد عبر واجهة HTTP واحدة.

أنشئ صفحة دفع مستضافة من خادمك، وحوّل العميل إليها، وأكّد الطلب من إشعار ويب موقَّع. وتوجّه binkly كل دفعة إلى حسابات المزوّدين التي تربطها.

أنشئ حسابًا مرجع واجهة البرمجة

نسخة تجريبية للمطوّرين: قد تتغيّر واجهة v1. وضع الاختبار متاح لكل من يسجّل، أما المدفوعات الفعلية فتتطلب حسابًا تجاريًا معتمدًا.

# Create a hosted checkout, then send the customer to its "url"
curl https://api.binkly.tech/v1/checkout/sessions \
  -H "Authorization: Bearer sk_test_…" \
  -H "Idempotency-Key: order-1042" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 2400,
    "currency": "USD",
    "description": "Everyday Bottle",
    "client_reference_id": "order-1042",
    "success_url": "https://shop.example/thanks?cs={CHECKOUT_SESSION_ID}",
    "cancel_url": "https://shop.example/cart"
  }'

# Charge a payment method directly (test token shown)
curl https://api.binkly.tech/v1/payments \
  -H "Authorization: Bearer sk_test_…" \
  -H "Idempotency-Key: 7f3c2a90-pay" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 2400,
    "currency": "USD",
    "payment_method": "tok_success",
    "description": "Everyday Bottle",
    "customer_email": "sara@example.com"
  }'

# Refund part of a payment. Leave out "amount" to refund what is left.
curl https://api.binkly.tech/v1/payments/pay_…/refunds \
  -H "Authorization: Bearer sk_test_…" \
  -H "Idempotency-Key: 7f3c2a90-refund-1" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 32000 }'

المبالغ أعداد صحيحة بأصغر وحدة في العملة: 2400 تعني 24.00 دولارًا.

ما يمكنك بناؤه اليوم

حساب واحد، ومجموعة مفاتيح واحدة، ولوحة تحكم واحدة لكل ذلك.

صفحة دفع مستضافة

يعيد POST /v1/checkout/sessions رابط url لصفحة دفع binkly. تنتهي الجلسة بعد مدة تحدّدها، من 5 دقائق إلى 7 أيام.

واجهة المدفوعات

أنشئ المدفوعات واعرضها واسترجعها عبر /v1/payments، واسترد المبلغ كاملًا أو جزءًا منه.

زر binkly

زر «ادفع بـ binkly» لأي صفحة، يفتح الدفع في نافذة صغيرة ويُعلم صفحتك عند انتهائه.

إشعارات الويب والأحداث

أحداث موقَّعة للمدفوعات والاسترداد وجلسات الدفع المكتملة، مع GET /v1/events لاستدراك ما فاتك.

المفاتيح والأوضاع وإعادة المحاولة

أرسل مفتاحك السري رمزًا من نوع Bearer. المفاتيح التي تبدأ بـ sk_test_ تعمل في وضع الاختبار، ومفاتيح sk_live_ في التشغيل الفعلي، وبيانات كل وضع منفصلة عن الآخر.

أرسل ترويسة Idempotency-Key عند إنشاء دفعة أو استرداد أو جلسة دفع. وإذا أُعيد الطلب بالمفتاح نفسه تحصل على النتيجة الأولى بدلًا من خصم ثانٍ.

Authorization: Bearer sk_test_…
Idempotency-Key: <order id>
احتفظ بالمفاتيح السرية على خادمك، ولا تضعها في متصفح أو تطبيق

{
  "id": "pay_…",
  "object": "payment",
  "mode": "test",
  "amount": 2400,
  "currency": "USD",
  "status": "succeeded",
  "amount_refunded": 0,
  "fee": 0,
  "failure_code": null,
  "metadata": {},
  "created_at": "…"
}

الحالة واحدة من: processing أو succeeded أو failed أو partially_refunded أو refunded. مختصر.

كل حدث، موقَّع

أضف عنوانًا لاستقبال الإشعارات من لوحة التحكم واختر الأحداث التي تهمّك. يحمل كل إشعار ترويسة Binkly-Signature بالشكل t=<unix time>,v1=<HMAC-SHA256> للنص "<t>.<raw body>"، موقَّعًا بسرّ العنوان (whsec_…).

إذا لم يردّ خادمك بحالة 2xx، تعيد binkly المحاولة على فترات متزايدة لنحو 20 ساعة.

payment.succeeded، payment.failed
refund.succeeded، refund.failed
checkout.session.completed
subscription.created، .renewed، .payment_failed، .updated، .canceled

{
  "id": "evt_…",
  "type": "checkout.session.completed",
  "mode": "test",
  "created_at": "…",
  "data": {
    "checkout_session": {
      "id": "cs_test_…",
      "client_reference_id": "order-1042",
      "amount": 2400,
      "currency": "USD"
    },
    "payment": { "id": "pay_…", "status": "succeeded" }
  }
}

import crypto from "node:crypto";

// raw: the request body exactly as received
function verify(raw, header, secret) {
  const p = Object.fromEntries(header.split(",").map((s) => s.split("=")));
  const expected = crypto.createHmac("sha256", secret)
    .update(`${p.t}.${raw}`).digest("hex");
  const fresh = Math.abs(Date.now() / 1000 - Number(p.t)) < 300;
  return fresh && p.v1?.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(p.v1), Buffer.from(expected));
}

مختصر. ارفض الأحداث ذات الطابع الزمني القديم لمنع إعادة الإرسال.

أضف الزر بوسمَي script

ينشئ خادمك جلسة دفع، وتعرض صفحتك زر binkly لها. يدفع العميل بما حفظه في محفظته (البطاقات أو محافظ الهاتف أو التحويلات البنكية أو الدفع لاحقًا عبر مزوّدين معتمدين) في نافذة صغيرة، وتُبلَّغ صفحتك عند الانتهاء.

بيانات البطاقة لا تمر بموقعك
تُفتح صفحة الدفع في نافذة فوق صفحتك، وتُفتح فيها أيضًا صفحة شركة الدفع أو البنك، فيبقى العميل معك
أكّد على خادمك عبر حدث checkout.session.completed
بالعربية والإنجليزية

<!-- 1. Where the button goes -->
<div id="binkly-button"></div>

<!-- 2. The script, then the checkout id from your server -->
<script src="https://wallet.binkly.tech/v1/binkly.js"></script>
<script>
  Binkly.button("#binkly-button", {
    checkout: "cs_test_…",
    onComplete: (e) => { location.href = "/thank-you?checkout=" + e.checkout; },
  });
</script>

الرسالة في المتصفح مؤشر وليست دليلًا: أكّد الدفعة على خادمك.

دع المساعدين الأذكياء يشترون لعملائك

يستطيع عميل محفظة binkly أن يربط مساعدًا ذكيًا ويمنحه مفتاحًا لا يتيح له إلا طلب الشراء. والعميل هو من يضع الحدود: عملة واحدة، وأقصى مبلغ للعملية الواحدة، وميزانية لكل يوم أو أسبوع أو شهر، والمتاجر المسموح الشراء منها، وتاريخ انتهاء. تنتظر كل عملية شراء موافقته في المحفظة، أو تُدفع فورًا إن كانت دون مبلغ يختاره. ولا يستطيع الوكيل أن يُبقي إلا عددًا قليلًا من الطلبات بانتظار العميل، فلا يُغرقه بالطلبات.

لا يحتاج متجرك إلى أي تغيير. يدفع المساعد صفحة الدفع نفسها التي يدفعها عملاؤك، وتصلك إشعارات checkout.session.completed نفسها. وتبيّن بيانات الدفعة الإضافية أن وكيلًا هو من اشترى (agent_purchase)، وتظهر ذلك لوحة التحكم.

لا يرى المساعد البطاقة ولا بيانات العميل أبدًا
تصحب كل دفعة يجريها وكيل وكالة موقَّعة: إثبات من binkly بتوقيع Ed25519 على الطريقة التي وافق بها العميل، تحتفظ به مع الطلب (GET /v1/payments/:id/agent-mandate، ويمكن التحقق منه عبر /.well-known/jwks.json)
حماية السعر: يذكر المساعد السعر الذي رآه، وترفض binkly أي صفحة دفع تطلب مبلغًا آخر، فلا تستطيع صفحة مخادعة أن تحمّله أكثر
يصل الإثبات إلى خادمك في إشعار agent_mandate.issued؛ وقبل الشراء يرى المساعد إن كانت binkly قد تحققت من نشاطك التجاري
Authorization: Bearer agk_test_…، ويلغيه العميل متى شاء
اربط Claude وChatGPT وغيرهما من تطبيقات الذكاء الاصطناعي بعنوان واحد، https://api.binkly.tech/mcp: يسجّل العميل الدخول إلى محفظته ويضع الحدود (OAuth 2.1، دون نسخ أي مفتاح). ويتوفر أيضًا خادم MCP محلي وBinklyAgent في @binkly/node

{
  "mcpServers": {
    "binkly": {
      "command": "npx",
      "args": ["-y", "@binkly/agent-mcp"],
      "env": { "BINKLY_AGENT_KEY": "agk_test_…" }
    }
  }
}

# Ask the customer to approve paying a checkout
curl https://api.binkly.tech/v1/agent/purchases \
  -H "Authorization: Bearer agk_test_…" \
  -H "Content-Type: application/json" \
  -d '{ "checkout": "cs_test_…", "note": "The coffee beans you buy every month" }'

# Then follow it until "succeeded" (or declined, expired…)
curl https://api.binkly.tech/v1/agent/purchases/agp_… \
  -H "Authorization: Bearer agk_test_…"

عند تجاوز حدٍّ ما، يذكر الرد أيّها (over_limit، over_budget…) ليخبر المساعد العميل.

الإضافات وتطبيقات المنصّات

تستخدم جميعها مكوّنات واجهة البرمجة نفسها: صفحة دفع مستضافة لكل طلب، وإشعار ويب موقَّع عند الدفع.

متاح

WooCommerce

بوابة دفع تدعم صفحة الدفع بالمكوّنات (Blocks). يُعلَّم الطلب مدفوعًا من إشعار الويب الموقَّع، ويعمل الاسترداد في الاتجاهين، ويحمل كل طلب مفتاح منع التكرار.

نزّل الإضافة (.zip)

متاح

أي موقع

زر binkly، أو رابط url لصفحة الدفع المستضافة، أو روابط دفع تنشئها من لوحة التحكم.

مثال الزر

قريبًا

Shopify

تطبيق مدفوعات لـ Shopify، يمكن تثبيته بعد أن توافق Shopify على binkly شريكًا للمدفوعات.

اطلب الوصول

قريبًا

زد

جاهز ومُختبَر، وسيُفعَّل بعد أن تُدرج زد binkly ضمن مزوّدي الدفع.

اطلب الوصول

ابنِ في وضع الاختبار، ثم انتقل إلى التشغيل الفعلي

لا تنتقل أموال حقيقية في وضع الاختبار، ويمكنك البدء قبل ربط أي مزوّد دفع.

1
احصل على مفتاح اختبار
أنشئ حسابًا وانسخ مفتاح sk_test_ من لوحة التحكم.
2
جرّب كل النتائج
ادفع برموز الاختبار tok_success وtok_declined وtok_insufficient_funds وtok_processing_error، ووجّه إشعارات الويب إلى خادمك.
3
ابدأ التشغيل الفعلي
اطلب الوصول إلى المدفوعات الفعلية. تراجع binkly نشاطك التجاري، وبعد الموافقة يبدأ مفتاح sk_live_ بالعمل.

اطلب وصولًا مبكرًا إلى المدفوعات الفعلية

أخبرنا عن نشاطك التجاري، فنراجعه ونرسل إليك دعوة بالبريد الإلكتروني لبدء التشغيل الفعلي.

تريد البدء اليوم؟ أنشئ حسابًا تجاريًا واستخدم وضع الاختبار فورًا.