Pientegra External API
Deposit ve withdrawal operasyonları için backend API, hosted payment page ve webhook integration reference.
Pientegra docs, partner sitelerin deposit ve withdrawal operasyonlarını Pientegra'ya bağlaması için gereken integration yüzeylerini kapsar. Ürün üç ana parçadan oluşur: backend-to-backend API, kullanıcıya açılan hosted deposit page ve async webhook delivery.
Bu ayrım önemlidir: deposit flow'da backend API bir depositUrl üretir ve kullanıcı
hosted payment page'e yönlendirilir. Withdrawal flow ise bugünkü External API'de
API-only payout request modelindedir; kullanıcıya Pientegra hosted withdrawal URL'i
dönmez.
API modeli
| Alan | Contract |
|---|---|
| Base URL | Pientegra ekibi entegrasyonunuza özel base URL'i sağlar. Production örneği: https://api.pientegra.com/api/v1 |
| Auth | Authorization: Bearer <raw-api-key> |
| Write safety | Tüm POST request'lerinde Idempotency-Key zorunlu |
| Payload | JSON, UTF-8, Content-Type: application/json |
| Money | amount minor unit olarak gönderilir; response tarafında string döner |
| Currency | TRY varsayılan ve aktif currency |
| Rate limit | External API için varsayılan 60 request / dakika / API key |
| Result delivery | Primary channel signed webhook; status endpoint'leri support ve reconciliation içindir |
Integration surface
| Surface | Ne için? | Docs |
|---|---|---|
| Backend-to-Backend API | Deposit intent ve withdrawal request oluşturma | API |
| Hosted Deposit Page | Kullanıcıya banka bilgisi ve payment CTA gösterme | Hosted Pages |
| Webhooks | Approval, rejection, sent ve returned sonuçlarını alma | Webhooks |
| Status Lookup | Support ve reconciliation için current state okuma | Status Lookup |
High-level flows
Deposit:
Partner backend -> POST /external/deposits -> depositUrl
Partner frontend -> Hosted Deposit Page
Pientegra -> intent.approved/rejected webhook -> Partner backendWithdrawal:
Partner backend -> POST /external/withdrawals -> withdrawalId
Pientegra operator review
Pientegra -> withdrawal.sent/rejected/returned webhook -> Partner backendNereden başlamalı?
Quickstart
İlk request, webhook handler ve retry modelini hızlıca kur.
Integration Types
Backend API, hosted page ve webhook rollerini ayır.
Authentication
API key formatını, secret handling'i ve failure mode'ları öğren.
Create Deposit
POST /external/deposits ile deposit intent oluştur.
Hosted Deposit Page
depositUrl ile kullanıcıyı payment page'e yönlendir.
Create Withdrawal
POST /external/withdrawals ile payout talebi başlat.
Webhook Security
HMAC-SHA256 signature verification ve replay protection.