توسعه‌دهندگان
سه فراخوانی و یک وب‌هوک.
Gateway یک checkout میزبانی‌شده است، برای همین یکپارچه‌سازی عمداً کوچک مانده: سفارش را بسازید، مشتری را به صفحهٔ پرداخت بفرستید، نتیجهٔ امضاشده را تأیید کنید. همهٔ آنچه باید پیاده کنید همین است — رابط پرداخت، منطق روش‌های پرداخت، 3-D Secure، کیف‌پول‌ها و رسیدها را ما می‌سازیم و به‌روز نگه می‌داریم.
ساختار کار
با چه چیزی یکپارچه می‌شوید.
- REST روی HTTPS
- ورودی JSON، خروجی JSON
- کلیدهای API از نوع Bearer
- کلیدهای Idempotency
- وب‌هوک‌های امضاشده
- محافظت در برابر replay
- حالت‌های test و live
- SDKهای iOS و Android
- افزونه‌های فروشگاهی
- فیلدهای embedded
شروع سریع
از هیچ تا یک سفارش پرداخت‌شده.
کل مسیر موفق. مبلغ‌ها بر حسب کوچک‌ترین واحد پول هستند، مرجع‌ها را خودتان تعیین می‌کنید و آدرس checkout همان جایی است که مشتری را به آن هدایت می‌کنید. آدرس پایهٔ API همراه کلیدهای sandbox شما صادر می‌شود — آن را به‌صورت PROTOCORE_API_BASE export کنید تا فراخوانی‌های زیر دقیقاً همان‌طور که نوشته شده‌اند اجرا شوند.
ساخت سفارش
یک فراخوانی با مبلغ، ارز و مرجع خودتان. کلید idempotency را خودتان تولید می‌کنید — درخواست تکراری، سفارش اولیه را برمی‌گرداند و سفارش دوم نمی‌سازد.
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"
}'ارسال مشتری به checkout
پاسخ شامل آدرس checkout روی هاست checkout خودتان است — همان که همراه sandbox صادر شده یا دامنهٔ خودتان، پس از آنکه آن را به ما وصل کنید. مشتری را به آن هدایت کنید یا در SDK بازش کنید؛ روش‌های پرداخت، کیف‌پول‌ها و 3-D Secure همه در همین صفحه هستند و چیزی نیست که سمت شما ساخته شود.
{
"id": "ord_2h4Kq9wRz",
"reference": "9F21-0716",
"amount": 4900,
"currency": "EUR",
"status": "pending",
"checkout_url": "https://<your-checkout-host>/c/2h4Kq9wRz"
}تأیید نتیجهٔ امضاشده
وقتی پرداخت کامل شود، یک رویداد امضاشده به endpoint شما می‌رسد. پیش از اعتماد به هر چیزی، امضا را با webhook secret خودتان تأیید کنید و بعد بر اساس مرجعی که از قبل دارید، سفارش را تحویل دهید.
{
"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" }
}
}مرجع
endpointهایی که واقعاً استفاده می‌کنید.
مستندات موارد بیشتری دارد، اما اغلب یکپارچه‌سازی‌ها هرگز از این مجموعه فراتر نمی‌روند.
وب‌هوک‌ها
بک‌اند شما از چه چیزهایی باخبر می‌شود.
هر رویداد مرجع سفارشی را که ساخته‌اید همراه دارد؛ پس handler شما می‌تواند فقط یک switch روی نوع رویداد و یک جستجو در داده‌های خودتان باشد.
پیش از اعتماد به بدنه، امضا را بررسی کنید.
هر ارسال شامل یک timestamp و امضای HMAC روی بدنهٔ خام است. مقایسه را در زمان ثابت انجام دهید، هر چیزی را که از بازهٔ تحمل شما قدیمی‌تر است رد کنید و شناسهٔ رویداد تکراری را قبلاً پردازش‌شده بدانید — در پاسخ‌های غیر 2xx دوباره تلاش می‌کنیم، پس handler شما هم باید idempotent باشد.
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;
}تضمین‌ها
ویژگی‌هایی که می‌توانید روی آن‌ها حساب کنید.
ساخت idempotent
ساخت هر سفارش یک کلید idempotency می‌گیرد. درخواست تکراری — پس از timeout، deploy یا ارسال مجدد از صف — سفارش اولیه را برمی‌گرداند و دوبار کسر نمی‌کند.
رویدادهای امضاشده و محافظت‌شده در برابر replay
وب‌هوک‌ها یک امضای HMAC زمان‌دار و یک شناسهٔ رویداد ثابت دارند. ارسال با backoff تکرار می‌شود تا endpoint شما با 2xx پاسخ دهد؛ پس بازهٔ deploy باعث از دست رفتن پرداخت نمی‌شود.
یک مرجع، از ابتدا تا انتها
مرجعی که هنگام ساخت سفارش می‌دهید در checkout، رسید، وب‌هوک، payout و هر بازپرداخت بعدی دیده می‌شود. شناسهٔ دومی وجود ندارد که بخواهید بین سیستم‌ها نگاشت کنید.
حالت test همان مسیر کد است
کلیدهای test همان جریان‌ها را روی sessionهای آزمایشی اجرا می‌کنند. آنچه در test پاس شود همان است که در محیط واقعی اجرا می‌شود — تفاوت فقط در کلیدی است که می‌فرستید، نه endpointهایی که صدا می‌زنید.
داده‌های آزمایشی
چطور مسیرهای مهم را تست کنید.
پشت هر مسیر زیر یک کارت آزمایشی قرار دارد که همراه کلیدهایتان، هنگام صدور سندباکس ارائه می‌شود. شماره‌ها برای هر سندباکس جداگانه‌اند و اینجا منتشر نمی‌شوند، تا با تغییر بازه‌های کارت آزمایشی شبکه‌های کارتی همچنان معتبر بمانند. رفتار سیستم در هر حالت قطعی و قابل پیش‌بینی است: نوشتن تست برای یک رد تراکنش به همان سادگی تست یک تراکنش موفق است.
کلیدها را بگیرید و شروع کنید.
یک merchant سندباکس با کلیدهای API، secretهای webhook و تمام روش‌های پرداخت فعال — به‌همراه مستندات کامل، تا تیم شما پیش از امضای هر قراردادی بتواند یکپارچه‌سازی را انجام دهد.