Protocore
צרו קשר

למפתחים

שלוש קריאות ו-webhook.

Gateway הוא checkout מאוחסן, ולכן האינטגרציה קטנה במכוון: יוצרים הזמנה, שולחים את הלקוח לדף, ומאמתים את התוצאה החתומה. זה כל המשטח כולו — ממשק התשלום, לוגיקת אמצעי התשלום, 3-D Secure, ארנקים וקבלות הם עלינו, ואנחנו גם שומרים אותם מעודכנים.

בקשת גישה ל-sandboxנסו את ה-checkout

במבט כולל

מול מה אתם משתלבים.

  • REST על גבי HTTPS
  • JSON בקלט, JSON בפלט
  • מפתחות API מסוג Bearer
  • מפתחות Idempotency
  • Webhooks חתומים
  • הגנה מפני Replay
  • מצבי test ו-live
  • SDK ל-iOS ול-Android
  • תוספים לחנויות
  • שדות מוטמעים

התחלה מהירה

מאפס להזמנה ששולמה.

כל המסלול התקין. הסכומים ביחידות הקטנות ביותר (minor units), ה-references הם שלכם, וכתובת ה-checkout היא היעד שאליו מפנים את הלקוח. כתובת הבסיס של ה-API ניתנת יחד עם מפתחות ה-sandbox — ייצאו אותה כ-PROTOCORE_API_BASE והקריאות שלהלן ירוצו בדיוק כפי שהן כתובות.

01

יצירת ההזמנה

קריאה אחת עם הסכום, המטבע וה-reference שלכם. את מפתח ה-idempotency אתם מייצרים בעצמכם — בקשה חוזרת מחזירה את ההזמנה המקורית ולא יוצרת הזמנה שנייה.

POST /v1/orders
curl -X POST "$PROTOCORE_API_BASE/v1/orders" \
  -H "Authorization: Bearer $PROTOCORE_API_KEY" \
  -H "Idempotency-Key: 9F21-0716" \
  -H "Content-Type: application/json" \
  -d '{
        "amount": 4900,
        "currency": "EUR",
        "reference": "9F21-0716",
        "line_items": [
          { "name": "Brand identity sprint", "amount": 3850 },
          { "name": "Typeface licensing",   "amount": 600 },
          { "name": "Rush delivery",        "amount": 400 }
        ],
        "return_url": "https://arcstudio.ro/thanks"
      }'
02

שליחת הלקוח ל-checkout

התגובה כוללת כתובת checkout על ה-host שלכם — זה שניתן עם ה-sandbox, או הדומיין שלכם לאחר שתפנו אותו אלינו. מפנים אליה, או פותחים אותה ב-SDK; בדף הזה נמצאים אמצעי התשלום, הארנקים ו-3-D Secure, כך שאין מה לבנות בצד שלכם.

201 Created
{
  "id": "ord_2h4Kq9wRz",
  "reference": "9F21-0716",
  "amount": 4900,
  "currency": "EUR",
  "status": "pending",
  "checkout_url": "https://<your-checkout-host>/c/2h4Kq9wRz"
}
03

אימות התוצאה החתומה

בסיום התשלום מגיע אירוע חתום ל-endpoint שלכם. אמתו את החתימה מול ה-webhook secret לפני שסומכים על כל דבר, ואז בצעו אספקה לפי ה-reference שכבר מוכר לכם.

POST /your/webhook — order.paid
{
  "type": "order.paid",
  "id": "evt_7Ka2Lm",
  "created": "2026-07-23T09:41:02Z",
  "data": {
    "id": "ord_2h4Kq9wRz",
    "reference": "9F21-0716",
    "amount": 4900,
    "currency": "EUR",
    "method": "usdc",
    "settlement": { "currency": "EUR", "amount": 4900, "rate": "0.9184" }
  }
}

מסמך עזר

ה-endpoints שבהם תשתמשו בפועל.

יש עוד בדוקומנטציה, אבל זו הקבוצה שרוב האינטגרציות אף פעם לא חורגות ממנה.

POST /v1/orders
יצירת הזמנה וקבלת כתובת ה-checkout שלה. דורש מפתח idempotency.
GET /v1/orders/:id
המצב הנוכחי של הזמנה — סטטוס, אמצעי תשלום, סליקה והחזרים.
POST /v1/orders/:id/refunds
החזר על ההזמנה, מלא או חלקי, עם סיבה חובה.
POST /v1/orders/:id/void
שחרור ההרשאה לפני הסליקה, כך שלא זז כסף כלל.
POST /v1/links
יצירת payment link — חד-פעמי או אוסף תשלומים, עם תפוגה אופציונלית.
GET /v1/payouts/:id
אצוות סליקה וההזמנות שמימנו אותה, עם פירוט עמלות.
POST /v1/customers/:id/cards
שמירת כרטיס ב-vault לחיוב בלחיצה אחת ולחיובים חוזרים; מחזיר token reference.
POST /v1/subscriptions
חיוב כרטיס שמור לפי לוח זמנים; כל מחזור מפיק הזמנה משלו.

Webhooks

על מה ה-backend שלכם שומע.

כל אירוע נושא את ה-reference של ההזמנה שיצרתם, כך שה-handler יכול להיות switch על הסוג ושליפה בצד שלכם.

order.paid
ההרשאה והגבייה (capture) הצליחו — בצעו אספקה לפי ה-reference.
order.failed
התשלום לא הושלם, עם סיבה שגורם תפעולי יכול לפעול לפיה.
order.refunded
הונפק החזר, מלא או חלקי, עם הסיבה וההערה שלו.
order.disputed
נפתח chargeback, כשהראיות כבר מצורפות להזמנה.
payout.settled
אצוות סליקה יצאה לחשבונכם, עם רשימת ההזמנות שמאחוריה.
subscription.charged
מחזור חוזר הפיק הזמנה וקבלה משלו.
אימות

בדקו את החתימה לפני שסומכים על ה-body.

כל משלוח כולל חותמת זמן וחתימת HMAC על ה-body הגולמי. השוו בזמן קבוע, דחו כל דבר ישן מחלון הסבילות שלכם, והתייחסו ל-event id כפול כאל אירוע שכבר טופל — אנחנו מנסים שוב על תגובות שאינן 2xx, ולכן גם ה-handler שלכם צריך להיות idempotent.

Node — אימות חתימה
import { createHmac, timingSafeEqual } from "node:crypto";

export function verify(rawBody, header, secret) {
  const [ts, sig] = header.split(",").map((p) => p.split("=")[1]);
  const expected = createHmac("sha256", secret)
    .update(`${ts}.${rawBody}`)
    .digest("hex");

  const a = Buffer.from(sig, "hex");
  const b = Buffer.from(expected, "hex");
  if (a.length !== b.length || !timingSafeEqual(a, b)) return false;

  // Reject replays outside a five-minute window.
  return Math.abs(Date.now() / 1000 - Number(ts)) < 300;
}

הבטחות

התכונות שאפשר לבנות עליהן.

01

יצירה idempotent

כל יצירת הזמנה מקבלת מפתח idempotency. בקשה חוזרת — אחרי timeout, deploy או שליחה חוזרת מתור — מחזירה את ההזמנה המקורית ולא מחייבת פעמיים.

02

אירועים חתומים עם הגנה מפני replay

ל-webhooks יש חתימת HMAC עם חותמת זמן ו-event id יציב. המשלוחים נשלחים שוב עם backoff עד שה-endpoint שלכם עונה 2xx, כך שחלון deploy לא מאבד תשלום.

03

reference אחד, מקצה לקצה

ה-reference שמסרתם בעת היצירה מופיע ב-checkout, בקבלה, ב-webhook, ב-payout ובכל החזר שיבוא אחר כך. אין מזהה שני שצריך למפות בין מערכות.

04

מצב test הוא אותו נתיב קוד

מפתחות test מריצים את אותם flows מול sessions של test. מה שעובר ב-test הוא מה שעולה לאוויר — ההבדל הוא באילו מפתחות שולחים, לא באילו endpoints קוראים.

נסו את ה-checkout

נתוני בדיקה

איך לתרגל את הנתיבים החשובים.

מאחורי כל נתיב מוצג כאן כרטיס בדיקה, והוא מופיע יחד עם המפתחות שלכם עם הנפקת ה-sandbox. המספרים נקבעים לכל sandbox ואינם מתפרסמים כאן, כך שהם נשארים נכונים גם כשטווחי הבדיקה של הסכמות משתנים. ההתנהגות דטרמיניסטית בכל מקרה: קל לבדוק דחייה בדיוק כמו אישור.

אושר מיידית
מאשר ומחייב ללא אתגר 3-D Secure — המסלול התקין.
אתגר 3-D Secure
מכריח אתגר שאפשר לעבור עד הסוף, כדי שתוכלו לבדוק את שלב החזרה.
דחייה רכה
נדחה בגלל יתרה לא מספקת, ואז מבצע ניסיון חוזר במסלול חלופי.
דחייה קשיחה
נדחה לצמיתות בגלל כרטיס שפג תוקפו, ללא ניסיון חוזר.
רשתות בדיקה ל-USDC
USDC ברשתות בדיקה של Ethereum, Base ו-Solana, במחיר בשער קבוע.
הדמיית העברה
סמנו העברת vIBAN לבדיקה כהתקבלה כדי להעביר את ההזמנה למצב שולם.

מקבלים מפתחות ומתחילים.

merchant ב-sandbox עם מפתחות API, סודות webhook וכל השיטות פעילות — וגם התיעוד המלא, כדי שהצוות שלכם יוכל לבצע אינטגרציה עוד לפני שנחתם משהו.

בקשת גישה ל-sandboxcontact@protocore.io