Azərbaycanda ödəniş şlüzü inteqrasiyasının etibarlı olması checkout səhifəsinin açılması ilə ölçülmür. Əsas sual budur: müştəri 3D Secure mərhələsindən qayıtmasa, provayder callback-i gec gəlsə, eyni bildiriş iki dəfə göndərilsə və ya bank çıxarışı sifarişlərinizlə uyğunlaşmasa, komandanız nə görəcək və sistem nə edəcək?

Website, müştəri portalı və ya mobil tətbiqin backend-i üçün ödənişi ayrıca əməliyyat domeni kimi qurmaq lazımdır. Provayderin API-sinə sadəcə “ödə” sorğusu göndərmək əvəzinə, daxili sifariş, payment attempt, webhook hadisəsi, refund və settlement qeydləri arasında izlənə bilən əlaqə yaradın. Bu yanaşma müştəri dəstəyini, mühasibatı və məhsul komandasını buraxılışdan sonra əl ilə axtarışdan qoruyur.

Checkout-dan əvvəl: daxili ödəniş modeli

İnteqrasiya provayderindən asılı olmayaraq sisteminiz öz identifikatorlarına sahib olmalıdır. Minimum modeldə order xidmət və ya məhsul üzrə biznes öhdəliyini, payment attempt isə konkret ödəniş cəhdini ifadə edir. Bir sifarişdə bir neçə cəhd ola bilər: kart rədd edilə, istifadəçi səhifəni bağlaya və sonra başqa kartla yenidən ödəyə bilər.

  • Sifariş yaradılan anda dəyişməyən daxili order ID yaradın.
  • Hər checkout başlanğıcı üçün ayrıca attempt ID və provayderə ötürülən merchant reference saxlayın.
  • Məbləği tam ədəd minor unit ilə və valyuta kodu ilə saxlayın; float hesablamalarından uzaq durun.
  • Provayderin transaction/reference ID-sini, cavab payload-ını və hadisə vaxtlarını saxlayın.
  • Sifarişin “ödənilib” görünməsi ilə pulun “settlement” mərhələsinə çatmasını eyni status hesab etməyin.

Sadə, lakin faydalı status modeli belə ola bilər: created → checkout_started → pending_authentication → authorized/captured → paid. Uğursuz qollar isə failed, cancelled, expired və unknown ola bilər. Refund ayrıca həyat dövrünə malikdir: requested → pending → refunded, həmçinin refund_failed və bəzi ödəniş üsullarında sonradan baş verə bilən reversal vəziyyəti nəzərə alınmalıdır. Provayderin status adlarını olduğu kimi biznes statusu etməyin; onları daxili, sənədləşdirilmiş vəziyyətlərə xəritələyin.

Webhook: nəticə üçün əsas mənbə

Uğurlu browser redirect-i ödənişin qəti sübutu deyil. Müştəri success səhifəsinə çatmaya, interneti kəsilə və ya authentication pəncərəsini bağlaya bilər. Buna görə sifarişin son statusunu provayderin serverdən-serverə göndərdiyi imzalı webhook müəyyən etməlidir. Redirect səhifəsi yalnız istifadəçiyə “ödəniş yoxlanılır” və ya “ödəniş təsdiqləndi” mesajını göstərmək üçündür.

Webhook endpoint üçün praktik qaydalar

  1. İmzanı yoxlayın. Provayderin təyin etdiyi secret, imza və ya HMAC mexanizmi ilə xam request body üzərində yoxlama aparın.
  2. Raw hadisəni saxlayın. Event ID, başlıqlar, payload, qəbul vaxtı və emal nəticəsi audit və təkrar emal üçün lazımdır. Həssas kart məlumatını tətbiq loqlarına yazmayın.
  3. Tez cavab verin. İmza yoxlanıldıqdan sonra hadisəni dayanıqlı növbəyə və ya verilənlər bazasına yazın, 2xx cavabı qaytarın, ağır işi background worker-də edin.
  4. İdempotent emal edin. Eyni event ID və ya provayder əməliyyat ID-si ikinci dəfə gələndə sifariş yenidən aktivləşməməli, iki dəfə email və ya iki dəfə refund yaranmamalıdır.
  5. Status keçidlərini məhdudlaşdırın. Məsələn, paid vəziyyətindəki attempt gec gələn “failed” bildirişi ilə geriyə dönməməlidir; istisnalar ayrıca araşdırma növbəsinə düşməlidir.

İdempotency yalnız webhook üçün deyil. “Ödəniş yarat”, “capture”, “cancel” və “refund” kimi vəziyyəti dəyişən API sorğularına daxili idempotency key verin. Bu, timeout alan backend-in eyni əməliyyatı təkrarlayarkən ikinci charge və ya ikinci refund yaratma riskini azaldır.

Rədd edilən və yarımçıq ödənişləri idarə edin

“Ödəniş alınmadı” mesajı əməliyyat baxımından kifayət etmir. Admin tərəfdə rədd səbəbi, provayder kodu, cəhd sayı, məbləğ, istifadə olunan kanal və son yenilənmə vaxtı görünməlidir. Müştəriyə isə kart məlumatını və ya daxili texniki kodu açıqlamadan aydın növbəti addım verin: yenidən cəhd etsin, başqa üsul seçsin və ya dəstəyə müraciət etsin.

Pending cəhdlər üçün periodik status sorğusu olan recovery job qurun. Job yalnız müəyyən müddət keçmiş, hələ qəti webhook almamış attempt-ləri provayder API-si ilə yoxlamalıdır. Bu prosesin nəticəsi və operatorun əl müdaxiləsi audit log-da saxlanmalıdır. Belə idarəetmə üçün checkout və arxa ofisi birlikdə düşünülmüş veb platformanın hazırlanması vacibdir; mobil kanal varsa eyni payment state API-si mobil tətbiqin hazırlanması zamanı da istifadə edilə bilər.

Refund: düymə deyil, nəzarətli iş axını

Refund üçün əməkdaşın sadəcə “geri qaytar” düyməsini sıxması təhlükəlidir. Kim refund yarada bilər, qismən refund mümkündürmü, maksimum məbləğ nədir, hansı sifarişlər təsdiq tələb edir və müştəri nə vaxt məlumatlandırılır — bunlar yazılı qayda olmalıdır.

  • Refund sorğusunu ilkin ödəniş attempt-i və provayder transaction ID-si ilə bağlayın.
  • Əvvəlki refund-ların cəmini hesablayın; qalıq məbləğdən çox qaytarmağa imkan verməyin.
  • İstək, təsdiq, göndəriş və yekun nəticəni ayrı statuslarda göstərin.
  • İki əməkdaşın eyni anda eyni refund-u yaratmasına qarşı idempotency və ya bloklama tətbiq edin.
  • Provayderin asinxron refund nəticəsini webhook ilə təsdiqləyin; API cavabını yekun maliyyə nəticəsi saymayın.

Reconciliation: provayder kabineti ilə sifarişləriniz niyə uyğun gəlməlidir?

Ödəniş uğurlu görünə bilər, amma həmin vəsait hələ bank hesabına settlement olunmaya, komissiya tutulmaya və ya sonradan dispute/refund baş verə bilər. Buna görə gündəlik və ya seçilmiş həcmdə üzləşdirmə prosesiniz olmalıdır: provayderin əməliyyat və payout/settlement hesabatlarını daxili payment attempt-lər, refund-lar və mühasibat qeydləri ilə müqayisə edin.

Uyğunlaşdırma açarları adətən merchant reference, provayder transaction ID-si, məbləğ, valyuta, əməliyyat tarixi və settlement reference-dir. Fərqləri “çatışmayan webhook”, “məbləğ fərqi”, “gözlənən settlement”, “naməlum provayder əməliyyatı” kimi kateqoriyalara bölün. İşçilər üçün filtrli istisna siyahısı və təkrar emal aləti yaradın. Bu, payment reconciliation software anlayışının praktik hissəsidir: məqsəd yeni mühasibat sistemi almaq deyil, maliyyə faktlarını izlənə bilən şəkildə uyğunlaşdırmaqdır.

Təhlükəsizlik və buraxılış checklist-i

Kart məlumatını öz serverinizdən keçirməmək üçün provayderin hosted payment page və ya uyğun embedded payment komponentindən istifadə etmək risk sahəsini azalda bilər, lakin merchant saytının təhlükəsizliyinə məsuliyyəti aradan qaldırmır. PCI SSC materialları redirect və iframe ssenarilərində də merchant səhifəsindəki script və zəiflik risklərinə diqqət tələb edir. PCI tələblərinizin hansı hissəsinin sizə tətbiq olunduğunu acquiring bank və ya uyğunluq məsləhətçisi ilə dəqiqləşdirin.

  • Sandbox-da uğur, rədd, istifadəçinin geri qayıtmaması, gecikmiş callback, duplicate callback və webhook-un müvəqqəti 5xx alması ssenarilərini test edin.
  • Prod secret-ləri vault və ya təhlükəsiz environment variable-larda saxlayın; test və prod açarlarını ayırın.
  • Webhook endpoint, queue, worker və reconciliation job üçün monitorinq və xəbərdarlıq qurun.
  • Admin səlahiyyətləri, refund audit log-u və əl ilə status düzəlişi qaydasını test edin.
  • Provayderin settlement faylları, komissiyaları, refund və dispute qaydalarını müqavilə mərhələsində yoxlayın.

POLADO-da veb platformaların hazırlanması xidməti çərçivəsində checkout UX-dən webhook worker-lərə, admin görünüşündən üzləşdirmə axınına qədər payment lifecycle-i layihələndiririk. Daha yüksək maliyyə və inteqrasiya tələbləri olan məhsullar üçün FinTech və trading sistemləri təcrübəsindən istifadə etmək olar. Buraxılışdan əvvəl payment provayderinizin sənədlərini, biznes qaydalarını və istisna ssenarilərini birlikdə texniki auditdən keçirmək üçün konsultasiya planlaşdırın.