डेवलपर्स
तीन कॉल और एक webhook।
Gateway एक hosted checkout है, इसलिए इंटीग्रेशन जान-बूझकर छोटा रखा गया है: ऑर्डर बनाइए, ग्राहक को पेज पर भेजिए, signed नतीजे को verify कीजिए। नीचे जो कुछ है, वही पूरा दायरा है — पेमेंट UI, मेथड लॉजिक, 3-D Secure, वॉलेट और रसीदें बनाना और उन्हें अप-टू-डेट रखना हमारा काम है।
रूपरेखा
आप किस चीज़ के साथ इंटीग्रेट कर रहे हैं।
- HTTPS पर REST
- JSON इन, JSON आउट
- Bearer API keys
- Idempotency keys
- Signed webhooks
- Replay protection
- Test और live मोड
- iOS और Android SDKs
- Store plugins
- Embedded fields
Quickstart
शून्य से चुकाए गए ऑर्डर तक।
पूरा happy path। राशियाँ minor units में हैं, reference आपके अपने हैं, और ग्राहक को checkout URL पर redirect करना है। API base URL आपकी sandbox keys के साथ जारी होता है — उसे PROTOCORE_API_BASE के रूप में export कीजिए और नीचे की कॉल जैसी लिखी हैं वैसी ही चलेंगी।
ऑर्डर बनाइए
राशि, करेंसी और आपके अपने reference के साथ एक कॉल। idempotency key आप खुद जनरेट करते हैं — दोबारा भेजा गया अनुरोध दूसरा ऑर्डर बनाने के बजाय मूल ऑर्डर लौटाता है।
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 URL होता है — वही जो आपके sandbox के साथ जारी हुआ है, या आपका अपना डोमेन, जब आप उसे हमारी ओर पॉइंट कर दें। उस पर redirect कीजिए या SDK में खोलिए; मेथड, वॉलेट और 3-D Secure उसी पेज पर हैं, इसलिए आपकी ओर से कुछ बनाना नहीं पड़ता।
{
"id": "ord_2h4Kq9wRz",
"reference": "9F21-0716",
"amount": 4900,
"currency": "EUR",
"status": "pending",
"checkout_url": "https://<your-checkout-host>/c/2h4Kq9wRz"
}Signed नतीजे को verify कीजिए
पेमेंट पूरा होते ही आपके endpoint पर एक signed इवेंट पहुँचता है। किसी भी चीज़ पर भरोसा करने से पहले अपने webhook secret से सिग्नेचर verify कीजिए, फिर उस reference के आधार पर ऑर्डर पूरा कीजिए जो आपके पास पहले से है।
{
"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 में और भी बहुत कुछ है, लेकिन ज़्यादातर इंटीग्रेशन इस सेट से आगे कभी नहीं बढ़ते।
Webhooks
आपके बैकएंड को क्या-क्या सूचित किया जाता है।
हर इवेंट में वह ऑर्डर reference होता है जो आपने बनाया था, इसलिए आपका handler सिर्फ़ type पर एक switch और अपनी ओर एक lookup हो सकता है।
बॉडी पर भरोसा करने से पहले सिग्नेचर जाँचिए।
हर डिलीवरी में timestamp और raw body पर HMAC सिग्नेचर होता है। तुलना constant time में कीजिए, अपनी tolerance window से पुराना कुछ भी अस्वीकार कीजिए, और दोहराए गए event id को पहले से संसाधित मानिए — non-2xx रिस्पॉन्स पर हम retry करते हैं, इसलिए आपका 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
हर ऑर्डर निर्माण idempotency key लेता है। दोबारा भेजा गया अनुरोध — timeout, deploy या queue redelivery के बाद — दो बार चार्ज करने के बजाय मूल ऑर्डर लौटाता है।
Signed, replay-protected इवेंट
Webhooks में timestamp वाला HMAC सिग्नेचर और स्थिर event id होता है। जब तक आपका endpoint 2xx नहीं लौटाता, डिलीवरी backoff के साथ retry होती है, इसलिए deploy के दौरान कोई पेमेंट नहीं छूटता।
एक reference, शुरू से अंत तक
निर्माण के समय आपका दिया reference checkout, रसीद, webhook, payout और बाद के किसी भी रिफ़ंड में दिखता है। सिस्टम के बीच मैप करने के लिए कोई दूसरा पहचानकर्ता नहीं है।
Test मोड में भी वही कोड पाथ
Test keys उन्हीं फ़्लो को test sessions पर चलाती हैं। जो test में पास होता है, वही live जाता है — फ़र्क़ इतना है कि आप कौन-सी keys भेजते हैं, कौन-से endpoints कॉल करते हैं यह नहीं।
Test डेटा
ज़रूरी पाथ को कैसे परखें।
नीचे दिए गए हर पाथ के पीछे एक टेस्ट कार्ड है, जो sandbox जारी होने पर आपकी keys के साथ सूचीबद्ध होता है — नंबर यहाँ प्रकाशित करने के बजाय हर sandbox के लिए अलग होते हैं, ताकि स्कीम की टेस्ट रेंज बदलने पर भी वे सही रहें। व्यवहार दोनों स्थितियों में निर्धारित (deterministic) रहता है: टेस्ट में decline को जाँचना उतना ही आसान है जितना सफल लेन-देन को।
keys लें और शुरू करें।
API keys, webhook secrets और हर पद्धति चालू के साथ एक sandbox merchant — साथ में पूरा रेफ़रेंस, ताकि आपकी टीम कुछ भी साइन होने से पहले integrate कर सके।