Kriptovalyutalar
Torrent Gear
API ödənişləri provayderlərdən necə işləyir
Ödəniş API tətbiqiniz və provayderiniz arasında «ödəniş yaratmaq», «3DS təsdiqləmək», «vəsaiti qaytarmaq», «müştəriyə ödəmək» və «status almaq» üçün etibarlı, təkrarlanan çağırışlara çevirən müqavilədir. Kapot altında onlarla qayda var: tokenizasiya, idempotency, vebhuk, antifrod, növbə, SLA və audit. Aşağıda - əksər provayderlərdə bunun necə qurulduğunun praktik xəritəsi.
Əsas model: demək olar ki, həmişə hansı mövzular var
Payment/Charge - silinməyə cəhd (authorize + capture və ya dərhal purchase).
Payment Method - kart (PAN/token), bank hesabı/alias, pul kisəsi, yerli üsul.
Müştəri - müştərinin/ödəyicinin mahiyyəti (bəzən isteğe bağlıdır).
Payout/Transfer - müştəriyə/alıcıya gedən ödəniş.
Refund/Reversal - ilkin ödənişə qayıdış (closed-loop).
Webhook Event - status haqqında asenkron bildiriş.
Dispute/Chargeback - ödəniş şəbəkəsi üzrə mübahisə (kartlar üçün).
Order/Invoice - ödəniş ətrafında biznes kontekstidir.
Autentifikasiya və təhlükəsizlik
API-açarları/OAuth 2. 0/mTLS - server-server üçün.
Müştəri tokenləri - frontend üçün birdəfəlik tokenlər (sirləri parlatmamaq üçün).
Kart tokenizasiyası - PAN provayderə gedir; Siz yalnız token saxlayırsınız.
PCI DSS - PAN görürsünüzsə, PCI zonasındasınız; hosted/SDK-dan qaçmaq və istifadə etmək daha yaxşıdır.
HMAC webhook imzası - hadisə provayderdən gəldiyini yoxlamaq.
İki zonalı memarlıq - ictimai cəbhə (JS/SDK) və şəxsi arxa plan (açarlar, risk-məntiq).
Idempotency, növbələr və uyğunluq
Idempotency-Key başlığında: sorğunun təkrarı (taymaut zamanı) təkrarlanmır.
Outbox/Saga sizdə: «ödəniş göndərmək → ledger qeyd → webhuk gözləmək» razılaşdırılmışdır.
Backoff ilə retrajlar - yalnız müvəqqəti səhvlər üçün. Matris retryable/non-retryable - tələb olunur.
Tipik end nöqtələri (sxemlər və flow)
1) Kartlar (Visa/Mastercard və s.)
POST/payments - ödəniş yaratmaq ('amount', 'currency', 'payment _ method _ token', 'capture' = false/true).
POST /payments/{id}/confirm — шаг 3-D Secure 2 (challenge/redirect result).
POST/payments/{ id }/capture - avtorizasiyadan sonra tutulma (qismən/tam).
POST/payments/{ id }/refund - geri qaytarma (hissə-hissə, ilkin məbləğə qədər).
GET /payments/{id} — статус (authorized, captured, failed, requires_action).
3-D Secure/SCA: provayder challenge üçün 'requires _ action' + 'client _ secret '/URL qaytaracaq. Müştəri tərəfindən təsdiqləndikdən sonra cəbhə nəticəni backendinizə qaytaracaq → siz '/confirm 'sürükləyirsiniz.
2) A2A / Open Banking (Pay by Bank)
POST/payments → müştərinin bankına 'redirect _ url' ilə cavab.
Müştəri bankda qeydiyyatdan keçir → webhook 'payment. succeeded/failed`.
GET/payments/{ id} - son status (çox vaxt yalnız asenxron).
3) Lokal metodlar (PIX, PayID, FPX, iDEAL və s.)
POST/payments → 'qr _ code '/' deeplink '/' copy _ code' əldə edin.
İstifadəçiyə göstərin, webhook qəbulu üçün gözləyin.
Kodun taymautları və TTL müqavilənin bir hissəsidir.
4) Ödənişlər (payouts)
POST /payouts (`amount`, `currency`, `destination_token` или `card_token`/`bank_alias`).
GET /payouts/{id} — статусы (`queued`, `sent`, `paid`, `failed`).
Webhook 'payout. paid/failed '- həqiqət mənbəyi.
Qapalı döngə: alternativlərə qədər mənbəyə (reversal) ödəmək üstünlük verilir.
Webhucks: «həqiqət mənbəyi»
Hadisələr: 'payment. pending/authorized/captured/failed`, `payment. requires_action`, `refund. succeeded`, `payout. paid`, `dispute. created 'və s.
Çatdırılma: HMAC tərəfindən imzalanmış retrajlarla, tez-tez «ən azı bir dəfə» → prosessorun idempotentliyini saxlayın.
Best practice: vebhuk idarə → ledger yeniləmək → 2xx cavab. Hər hansı bir biznes məntiqi sonra - asenxron.
Xətaların və statusların emalı
HTTP kodları: '2xx' müvəffəqiyyət; '4xx' müştəri səhvi (validasiya, frod/bank uğursuzluğu, səhv token); '5xx' - provayder.
Причины отказов: `insufficient_funds`, `do_not_honor`, `stolen_card`, `limit_exceeded`, `risk_decline`, `bank_unavailable`.
Pəncərələr təkrarlanır: 3DS üçün - sonsuz geri çəkilə bilməz; A2A üçün - TTL redaktoru/kodu; payouts üçün - backoff.
Antifrod və risk
Device-fingerprinting və davranış məlumatları - JS/SDK provayderi və ya öz qatınız vasitəsilə.
Siyahılar: BIN-Risk, Qara/Ağ/ASN/Ölkələrin Metodları Siyahıları.
Tənzimlənən geytlar: yeni alətlərin limitləri, «cool-off», velocity, RG/AML-eşik yoxlamaları.
Siyasətlər: 'pass/step-up/hold/block' + qaydalara əsaslanır.
Rels xüsusiyyətləri
Kartlar: avtorizasiya vs klirinq (məbləğin dəyişməsi mümkündür), 3DS2, ilkin əməliyyat üzrə geri qaytarmalar, mübahisələr/çarjbeklər.
A2A/Open Banking: redirect/consent-flow, yüksək səviyyəli, aşağı qiymət; hər şey asinxron və bankdan çox asılıdır.
Lokal sürətli: QR/alias, ani vebhuk, TTL və ciddi birləşmə.
OCT/Push-to-Card (kart ödənişləri): kart tokenləri, emitentdən Fast Funds dəstəyi, 3DS olmadan lazımdır.
Version və uyğunluq
API versiyaları: '/v1 ', başlıqdakı «data-versiyalar» və ya ficheflaglar.
Backwards-compatible dəyişikliklər: yalnız dağıdıcı sahələr.
Deprekasiya: köhnə versiyaların çıxarılması qrafiki, miqrasiya qaydaları, miqrasiya zamanı vebhukların dublikatı.
Müşahidə və SLA
Metriklər: p95 avtorizasiya/ödəniş vaxtı, BIN/bank/metod üzrə approve rate, retrai payı, vebhuk-lag.
Qeydlər: 'request _ id', 'idempotency _ key', 'payment _ id' ilə əlaqələndirilir.
Alertlər: konkret bank/ölkə üzrə uğursuzluqların artması, vaxtların artması, hadisələrin dublikatları.
Yığma və maliyyə
Ledger: ikiqat qeyd, dəyişməz jurnallar, statuslar 'authorized/captured/refunded'.
Üçtərəfli məcmuə: sizin ledceriniz, provayder/bankın hesabatları.
Referanslar: 'provider _ reference', 'network _ reference', 'payout _ reference' saxlayın - bu, sapport saxlayır.
Sandbox, sertifikatlaşdırma və satış
Sandbox: Test tokenləri/kartları/bankları, 3DS/redaktorların simulyasiyası, vebhuk statusları üçün «düymələr».
Test halları: müvəffəqiyyət/uğursuzluq, 3DS çağırış, provayder vaxtı, təkrarlanan webhook, qismən capture/refund, redector ləğv, payout fail.
Go-live: prod açarları, vebhuk domenləri, IP-allowlist, antifrodu işə salın, limitləri və riskləri təyin edin.
Mini nümunələr (sxematik)
Ödəniş (kart) yarat
POST /v1/payments
{
"amount": 9232, "currency": "EUR", "payment_method_token": "pm_tok_123", "capture": true, "metadata": {"order_id": "ORD-1001"}
}
→ 200 { "id": "pay_abc", "status": "requires_action", "next_action": {"type":"redirect", "url":"..."} }Uğurlu qəbul haqqında vebhuk
POST /webhooks
{
"type": "payment. captured", "data": {"id":"pay_abc","amount":9232,"currency":"EUR","metadata":{"order_id":"ORD-1001"}}
}Ödəniş (payout)
POST /v1/payouts
{
"amount": 5000, "currency": "EUR", "destination_token": "dest_tok_456", "metadata": {"user_id":"u_77"}
}Giriş çek siyahısı
1. Açar arxitekturası: server sirləri ayrıca, müştəri - birdəfəlik.
2. Idempotency: hər bir write-zəngdə + idempotent webhook prosessorları.
3. Webhucks: HMAC imzası, retralar, tapşırıqların növbəsi, lag monitorinqi.
4. 3DS/SCA və redaktorlar: geri çəkilmə/taymaut emalı, frendli-UX yenidən cəhd.
5. Antifrod/limitlər: velocity, yeni rekvizitlər, qara siyahılar, RG/AML-eşiklər.
6. Ledger və yığma: ikiqat qeyd, üçtərəfli müqayisə, anomaliyalar alertləri.
7. Orkestr: ehtiyat provayder, BIN/ölkə/məbləğ üzrə marşrut qaydaları.
8. Monitorinq: daşbordlar approve rate/p95/retralar, banklar/metodlar üzrə alertlər.
9. Hüquqi/PCI: tokenizasiya, geri qaytarma siyasəti, payouts qapalı loop.
10. Deqradasiya planı: kill-switch kanal, növbələr, kritik əməliyyatlar üçün əl rejimi.
Tez-tez səhvlər
PAN-ı PCI və tokenizasiyasız saxlayın.
Taymaut zamanı idempotency → dubl ödənişlərinin/ödənişlərin olmaması.
Vebhukları nəzərə almadan sinxron cavabların məntiqi.
Bazarda bir provayder, heç bir fallback/kaskad.
3DS ləğv emalı/redaktor → itirilmiş səbətlər.
Zəif birləşmə → «asılmış» və «itirilmiş» əməliyyatlar.
Aydın SLA və alertlərin olmaması → problemi siz deyil, müştəri görür.
Mini-FAQ
Hangisi daha etibarlıdır: sinxron status və ya vebhuk?
Webhook - həqiqət mənbəyi; sinxron cavab - yalnız «qəbul/hərəkət lazımdır».
3DS olmadan edə bilərəmmi?
Tənzimləmə/riskdən asılıdır. EC/UK - SCA tələb olunur; yüksək risk üçün step-up daha yaxşıdır.
approve rate artırmaq üçün necə?
BIN/bank/metodu ilə orkestr, yerli relslər, ağıllı retralar, düzgün deskriptorlar, aşağı FPR antifrod.
Niyə payout «ani deyil»?
Relsdən (OST/A2A/lokal), alıcının bankından və limitlərdən asılıdır. dürüst SLA pəncərə və status axını verin.
API ödənişləri yalnız «ödəniş yaratmaq» deyil. Bu fənn: təhlükəsiz autentifikasiya → tokenizasiya → idempotency → asinxron vebhuk → ledger və yığma → antifrod/AML → orkestr və monitorinq. Bu sxem üzrə bir proses qurun, ehtiyat kanalları və şəffaf UX saxlayın - və ödəniş təbəqəniz sürətli, proqnozlaşdırıla bilən və bankların və provayderlərin uğursuzluqlarına davamlı olacaq.