Geliştiriciler
Üç çağrı ve bir webhook.
Gateway, barındırılan bir checkout sayfasıdır; bu yüzden entegrasyon bilerek küçük tutuldu: sipariş oluşturun, müşteriyi sayfaya yönlendirin, imzalı sonucu doğrulayın. Aşağıdakilerin hepsi bu kadar — ödeme arayüzü, yöntem mantığı, 3-D Secure, cüzdanlar ve makbuzlar bize ait; bunları geliştirmek ve güncel tutmak bizim işimiz.
Genel yapı
Entegre olacağınız yapı.
- HTTPS üzerinden REST
- JSON girdi, JSON çıktı
- Bearer API anahtarları
- Idempotency anahtarları
- İmzalı webhook'lar
- Replay koruması
- Test ve canlı modlar
- iOS ve Android SDK'ları
- E-ticaret eklentileri
- Gömülü alanlar
Hızlı başlangıç
Sıfırdan ödenmiş siparişe.
Mutlu yolun tamamı. Tutarlar minor unit cinsindendir, referanslar sizindir, checkout URL'si ise müşteriyi yönlendireceğiniz adrestir. API temel URL'si sandbox anahtarlarınızla birlikte verilir — PROTOCORE_API_BASE olarak export edin, aşağıdaki çağrılar aynen yazıldığı gibi çalışır.
Siparişi oluşturun
Tutar, para birimi ve kendi referansınızla tek bir çağrı. Idempotency anahtarını siz üretirsiniz — yeniden denenen istek ikinci bir sipariş oluşturmaz, orijinal siparişi döndürür.
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"
}'Müşteriyi checkout'a yönlendirin
Yanıt, kendi checkout host'unuzda bir checkout URL'si içerir — sandbox ile verilen host ya da bizi yönlendirdiğinizde kendi alan adınız. Müşteriyi buraya yönlendirin ya da SDK içinde açın; yöntemler, cüzdanlar ve 3-D Secure bu sayfada olduğundan sizin tarafınızda geliştirilecek bir şey yok.
{
"id": "ord_2h4Kq9wRz",
"reference": "9F21-0716",
"amount": 4900,
"currency": "EUR",
"status": "pending",
"checkout_url": "https://<your-checkout-host>/c/2h4Kq9wRz"
}İmzalı sonucu doğrulayın
Ödeme tamamlandığında endpoint'inize imzalı bir olay gelir. Hiçbir şeye güvenmeden önce imzayı webhook secret'ınıza karşı doğrulayın, ardından zaten bildiğiniz referans üzerinden siparişi karşılayın.
{
"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" }
}
}Referans
Gerçekten kullanacağınız endpoint'ler.
Dokümanlarda daha fazlası var, ancak çoğu entegrasyon bu kümenin ötesine geçmez.
Webhook'lar
Backend'inizin haberdar olduğu olaylar.
Her olay oluşturduğunuz sipariş referansını taşır; handler'ınız türe göre bir switch ve kendi tarafınızda bir sorgudan ibaret olabilir.
Gövdeye güvenmeden önce imzayı kontrol edin.
Her teslimat, ham gövde üzerinden hesaplanmış bir zaman damgası ve HMAC imzası taşır. Sabit zamanlı karşılaştırın, tolerans pencerenizden eski olanı reddedin, tekrar gelen olay kimliğini işlenmiş sayın — 2xx dışındaki yanıtlarda yeniden deniyoruz, bu yüzden handler'ınız da idempotent olmalı.
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;
}Garantiler
Üzerine inşa edebileceğiniz özellikler.
Idempotent oluşturma
Her sipariş oluşturma çağrısı bir idempotency anahtarı alır. Zaman aşımı, deploy ya da kuyruk yeniden teslimi sonrasında tekrarlanan istek iki kez tahsilat yapmaz, orijinal siparişi döndürür.
İmzalı, replay korumalı olaylar
Webhook'lar zaman damgalı HMAC imzası ve sabit bir olay kimliği taşır. Endpoint'iniz 2xx dönene kadar teslimatlar backoff ile yeniden denenir; deploy penceresi bir ödemeyi kaybettirmez.
Baştan sona tek referans
Oluştururken verdiğiniz referans checkout'ta, makbuzda, webhook'ta, payout'ta ve sonraki her iadede yer alır. Sistemler arasında eşlemeniz gereken ikinci bir tanımlayıcı yoktur.
Test modu aynı kod yolunu kullanır
Test anahtarları aynı akışları test oturumlarına karşı çalıştırır. Testte geçen, canlıya çıkan koddur — fark hangi anahtarları gönderdiğinizdir, hangi endpoint'leri çağırdığınız değil.
Test verileri
Önemli akışları nasıl denersiniz.
Aşağıdaki her senaryonun arkasında bir test kartı var; sandbox ortamı oluşturulurken anahtarlarınızla birlikte listelenir. Numaralar şema test aralıkları değiştiğinde de doğru kalsın diye burada yayımlanmaz, sandbox'a özeldir. Davranış her durumda deterministiktir: bir testte ret sonucunu doğrulamak, başarılı sonucu doğrulamak kadar kolaydır.
Anahtarları alın, başlayın.
API anahtarları, webhook secret'ları ve tüm yöntemleri açık bir sandbox merchant hesabı — ayrıca tam referans dokümantasyonu. Ekibiniz herhangi bir imza atılmadan önce entegrasyona başlayabilir.