Quickstart
Pientegra entegrasyonunu minimum request, webhook handler ve retry modeliyle çalıştır.
Bu sayfa production integration'a başlamak için gereken minimum flow'u anlatır. Kod örnekleri server-side çalışmalıdır; API key browser, mobile app veya public client bundle içine konmaz.
0. Integration modelini seç
Pientegra'da deposit ve withdrawal aynı teknik kategoriye girmez:
| Flow | Model | Kullanıcı Pientegra sayfası görür mü? |
|---|---|---|
| Deposit | Backend API + hosted deposit page + webhook | Evet |
| Withdrawal | Backend API + webhook | Hayır |
| Status lookup | Backend API read | Hayır |
Detaylı ayrım için Integration Types sayfasına bakın.
1. Credentials'i hazırla
Pientegra tarafında her site için üç bilgi gerekir:
| Değer | Nerede kullanılır? |
|---|---|
API key | Pientegra External API request'lerinde Authorization: Bearer <api-key>. |
Webhook URL | Pientegra'nın event delivery yapacağı HTTPS endpoint. |
Webhook secret | Incoming webhook signature verification. |
Local config örneği:
# Base URL Pientegra ekibi tarafından entegrasyon başında size sağlanır.
# Production örneği:
PIENTEGRA_API_BASE="https://api.pientegra.com/api/v1"
PIENTEGRA_API_KEY="sk_live_<site-slug>_<secret>"
PIENTEGRA_WEBHOOK_SECRET="whsec_<secret>"2. İlk withdrawal request'ini gönder
Withdrawal flow en basit backend-to-backend senaryodur. Request kayıt oluşturur; nihai sonuç daha sonra webhook olarak gelir.
curl -X POST "$PIENTEGRA_API_BASE/external/withdrawals" \
-H "Authorization: Bearer $PIENTEGRA_API_KEY" \
-H "Idempotency-Key: 8c5e2c8a-7e3a-4b29-9c4f-3a1d8b1e9f00" \
-H "Content-Type: application/json" \
-d '{
"externalUserId": "user-12345",
"externalUserLabel": "Ahmet Y.",
"amount": "250000",
"currency": "TRY",
"targetIban": "TR320010009999901234567890",
"targetHolderName": "Ahmet Yılmaz"
}'Başarılı response:
{
"withdrawalId": "01927b3c-9c1f-7a3a-9c4f-8a3e1f8b1c00",
"referenceNo": "W-2026-0000123"
}Bu response sadece kaydın Pientegra tarafında alındığını gösterir. Kullanıcı
bakiyesini nihai olarak güncellemek için withdrawal.sent, withdrawal.rejected
veya withdrawal.returned webhook'unu bekleyin.
3. Deposit flow'u bağla
Deposit için Pientegra size depositUrl döner. Bu URL kullanıcıya popup veya
redirect ile gösterilir.
curl -X POST "$PIENTEGRA_API_BASE/external/deposits" \
-H "Authorization: Bearer $PIENTEGRA_API_KEY" \
-H "Idempotency-Key: 96f021e6-cf41-4311-8d88-620e32c69a20" \
-H "Content-Type: application/json" \
-d '{
"externalUserId": "user-12345",
"externalUserLabel": "Ahmet Y.",
"amount": "100000",
"currency": "TRY"
}'{
"intentId": "01927b3c-9c1f-7a3a-9c4f-8a3e1f8b1c00",
"referenceNo": "D-2026-0000123",
"depositUrl": "https://pay.tenant.example/d/eyJhbGciOi...",
"amount": "100000",
"currency": "TRY",
"expiresAt": "2026-04-28T12:30:00.000Z"
}Browser popup kullanacaksanız popup'ı kullanıcı click handler'ı içinde açın,
ardından backend'inizden depositUrl alıp popup location'ını set edin. Bu pattern
popup blocker riskini azaltır.
button.addEventListener('click', async () => {
const popup = window.open('about:blank', '_blank');
if (!popup) {
alert('Popup engellendi. Lütfen popup iznini açın.');
return;
}
try {
const res = await fetch('/api/pientegra/deposit', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ amount: '100000' }),
});
const { depositUrl } = await res.json();
popup.location = depositUrl;
} catch (error) {
popup.close();
throw error;
}
});4. Webhook handler'i ekle
Webhook endpoint'iniz Pientegra'dan gelen raw body'yi signature verification
için korumalı, event'i idempotent olarak işlemeli ve hızlı 2xx dönmelidir.
app.post('/pientegra/webhooks', express.raw({ type: 'application/json' }), async (req, res) => {
const signature = req.header('Pientegra-Signature');
const eventId = req.header('Pientegra-Event-Id');
const rawBody = req.body.toString('utf8');
if (!signature || !verifyPientegraSignature(process.env.PIENTEGRA_WEBHOOK_SECRET!, rawBody, signature)) {
return res.status(401).send('invalid signature');
}
if (await webhookEvents.exists(eventId)) {
return res.status(200).send('ok');
}
const event = JSON.parse(rawBody);
await webhookEvents.insert(eventId, event);
await backgroundJobs.enqueue('webhook-processing', event);
return res.status(200).send('ok');
});Signature verification detayı için Webhook Security sayfasına bakın. Deposit page yönlendirme detayları için Deposit Payment Page bölümünü kullanın.
5. Retry davranışını netleştir
Write request'lerde timeout veya 5xx alırsanız aynı Idempotency-Key ile
retry yapın. Yeni key kullanmak yeni bir işlem oluşturma niyetidir.
Webhook tarafında ise aynı eventId birden fazla kez gelebilir. eventId için
unique constraint veya Redis SETNX kullanın; duplicate event'i işlemeyip yine
2xx dönün.
Authentication
API key lifecycle ve server-side usage.
Idempotency
POST retry'larını duplicate yaratmadan yönet.
Integration Types
Backend API, hosted page ve webhook ayrımını netleştir.
Webhook Events
Hangi event'in hangi business action'ı tetikleyeceğini gör.
List & Reconcile
Time-windowed listing for nightly reconciliation.
Events & Replay
Webhook delivery ledger; DEAD event replay.
Webhook Config
Self-serve URL + signing secret rotation.