ڈویلپرز
تین کالز اور ایک webhook۔
Gateway ایک hosted checkout ہے، اس لیے integration جان بوجھ کر مختصر رکھا گیا ہے: order بنائیں، گاہک کو صفحے پر بھیجیں، دستخط شدہ نتیجے کی تصدیق کریں۔ نیچے دی گئی ہر چیز ہی پوری سطح ہے — payment UI، طریقوں کی منطق، 3-D Secure، wallets اور رسیدیں بنانا اور انہیں اپ ٹو ڈیٹ رکھنا ہماری ذمہ داری ہے۔
ساخت
آپ کس چیز کے ساتھ integrate کر رہے ہیں۔
- REST over HTTPS
- JSON in, JSON out
- Bearer API keys
- Idempotency keys
- دستخط شدہ webhooks
- Replay تحفظ
- Test اور live موڈ
- iOS & Android SDKs
- Store plugins
- Embedded fields
کوئک اسٹارٹ
صفر سے ادا شدہ order تک۔
مکمل کامیاب راستہ۔ رقوم minor units میں ہیں، references آپ کے اپنے ہیں، اور checkout URL وہ ہے جس پر آپ گاہک کو redirect کرتے ہیں۔ API base URL آپ کی sandbox keys کے ساتھ جاری ہوتا ہے — اسے PROTOCORE_API_BASE کے طور پر export کریں اور نیچے دی گئی کالز بالکل ویسے ہی چلیں گی جیسی لکھی ہیں۔
Order بنائیں
ایک کال، جس میں رقم، کرنسی اور آپ کا اپنا reference ہو۔ idempotency key آپ خود بناتے ہیں — دوبارہ بھیجی گئی درخواست دوسرا order بنانے کے بجائے اصل order ہی لوٹاتی ہے۔
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 host پر ایک checkout URL ہوتا ہے — وہ جو آپ کی sandbox کے ساتھ جاری ہوا، یا آپ کا اپنا ڈومین جب آپ اسے ہماری طرف پوائنٹ کر دیں۔ اس پر redirect کریں یا SDK میں کھولیں؛ طریقے، wallets اور 3-D Secure اسی صفحے پر ہیں، اس لیے آپ کی طرف کچھ بنانے کی ضرورت نہیں۔
{
"id": "ord_2h4Kq9wRz",
"reference": "9F21-0716",
"amount": 4900,
"currency": "EUR",
"status": "pending",
"checkout_url": "https://<your-checkout-host>/c/2h4Kq9wRz"
}دستخط شدہ نتیجے کی تصدیق کریں
ادائیگی مکمل ہونے پر ایک دستخط شدہ event آپ کے endpoint تک پہنچتا ہے۔ کسی بھی چیز پر بھروسا کرنے سے پہلے اپنے webhook secret سے signature کی تصدیق کریں، پھر اس reference کے مطابق fulfil کریں جو آپ کے پاس پہلے سے ہے۔
{
"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 جو آپ واقعی استعمال کریں گے۔
docs میں مزید بہت کچھ ہے، لیکن زیادہ تر integrations اسی مجموعے سے آگے نہیں بڑھتے۔
ویب ہکس
آپ کے backend کو کیا اطلاع ملتی ہے۔
ہر event میں وہ order reference ہوتا ہے جو آپ نے بنایا تھا، اس لیے آپ کا handler type پر ایک switch اور اپنی طرف ایک lookup ہو سکتا ہے۔
Body پر بھروسا کرنے سے پہلے signature چیک کریں۔
ہر delivery میں ایک timestamp اور raw body پر HMAC signature ہوتا ہے۔ موازنہ constant time میں کریں، اپنی tolerance window سے پرانی ہر چیز reject کریں، اور دہرائے گئے event id کو پہلے سے نمٹایا ہوا سمجھیں — ہم non-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 creates
Order بنانے کی ہر کال idempotency key لیتی ہے۔ دوبارہ بھیجی گئی درخواست — timeout، deploy یا queue redelivery کے بعد — دوسری بار charge کرنے کے بجائے اصل order لوٹاتی ہے۔
دستخط شدہ، replay سے محفوظ events
Webhooks میں timestamp والا HMAC signature اور مستقل event id ہوتا ہے۔ جب تک آپ کا endpoint 2xx نہ دے، deliveries backoff کے ساتھ دوبارہ کوشش کرتی ہیں، اس لیے deploy کی کھڑکی میں کوئی ادائیگی ضائع نہیں ہوتی۔
ایک reference، شروع سے آخر تک
تخلیق کے وقت دیا گیا reference checkout، رسید، webhook، payout اور بعد کے کسی بھی refund پر نظر آتا ہے۔ سسٹمز کے درمیان map کرنے کے لیے کوئی دوسرا identifier نہیں ہے۔
Test موڈ وہی code path ہے
Test keys انہی flows کو test sessions پر چلاتی ہیں۔ جو test میں پاس ہوتا ہے وہی ship ہوتا ہے — فرق صرف اس میں ہے کہ آپ کون سی keys بھیجتے ہیں، یہ نہیں کہ کون سے endpoints کال کرتے ہیں۔
ٹیسٹ ڈیٹا
اہم راستوں کو کیسے آزمائیں۔
ہر نیچے دیے گئے راستے کے پیچھے ایک ٹیسٹ کارڈ ہے، جو سینڈ باکس جاری ہونے پر آپ کی keys کے ساتھ درج ہوتا ہے — نمبر ہر سینڈ باکس کے لیے الگ ہیں اور یہاں شائع نہیں کیے جاتے، تاکہ اسکیم کی ٹیسٹ رینجز بدلنے پر بھی درست رہیں۔ رویہ ہر صورت میں متعین (deterministic) رہتا ہے: ٹیسٹ میں decline کی تصدیق بھی اتنی ہی آسانی سے ہوتی ہے جتنی کامیابی کی۔
keys لیں اور شروع کریں۔
API keys، webhook secrets اور تمام طریقے فعال کے ساتھ ایک سینڈ باکس merchant — ساتھ مکمل ریفرنس بھی، تاکہ آپ کی ٹیم کسی دستخط سے پہلے ہی انٹیگریشن کر سکے۔