ბანკის API-ით ონლაინ გადახდის ინტეგრაცია: 3D Secure და callback-ებიბანკის API-ით ონლაინ გადახდის ინტეგრაცია: 3D Secure და callback-ები

ონლაინ მაღაზიაში ან მომსახურების დაჯავშნაზე „ბანკის გადარიცხვით გადახდა“ ხშირად ნიშნავს დაკარგულ შეკვეთებს. თუ გინდა, რომ კლიენტმა გადაიხადოს იმავე წუთში, გჭირდება გადახდის სისტემა საიტზე — საქართველოში ყველაზე გავრცელებული გზით: საქართველოს ბანკი (BOG) ან TBC, 3D Secure-ით და სწორი სტატუსების დამუშავებით.

1) რატომ არ კმარა საბანკო გადარიცხვა და რას კარგავ მასზე

ბანკის გადარიცხვა მუშაობს, როცა შეკვეთების რაოდენობა მცირეა და ხელით დამუშავება გყოფნის. მაგრამ როგორც კი ონლაინ მაღაზიის გადახდები გახდება ყოველდღიური, იწყება სამი პრაქტიკული პრობლემა:

• კლიენტი იკარგება პროცესში. შეკვეთის შემდეგ ის უნდა გავიდეს აპში/ინტერნეტბანკში, მოძებნოს IBAN, ჩაწეროს დანიშნულება. ბევრს „ახლავე“ უნდა და არა „მერე გადავრიცხავ“.
• ვერ ავტომატიზებ სტატუსებს. გადარიცხვის მიღება არ ნიშნავს, რომ სისტემამ იცის: „შეკვეთა გადახდილია“. გიწევს ხელით მონიშვნა, SMS-ების/ამონაწერის შემოწმება, შეცდომების გასწორება.
• რთულია დავების მართვა. როცა კლიენტი ამბობს „გადავიხადე“, შენ იწყებ მტკიცებულებების ძებნას. ხოლო ბარათით გადახდაზე ბანკის პასუხი და ტრანზაქციის იდენტიფიკატორი უკვე პროცესშია.

თუ გაყიდვები გაქვს იმ პროდუქტზე/სერვისზე, სადაც გადაწყვეტილება იმპულსურია (ბილეთები, კურსები, ტანსაცმელი, სილამაზის სერვისები), ონლაინ გადახდის ინტეგრაცია ხშირად პირდაპირ ზრდის დასრულებულ შეკვეთებს — უბრალოდ იმიტომ, რომ ნაბიჯები ნაკლებია.

2) რა გჭირდება დაწყებამდე — იურიდიული პირი, საბანკო ანგარიში, მერჩანტის განაცხადი

BOG ინტეგრაცია და TBC ინტეგრაცია ორივე იწყება არა კოდით, არამედ „დოკუმენტებით და წვდომებით“. მინიმალური სია ასეთია:

1. იურიდიული პირი ან ინდ.მეწარმე. ბანკს სჭირდება, რომ მერჩანტის ანგარიში გაფორმდეს რეალურ ბიზნესზე.
2. საბანკო ანგარიში იმავე ბანკში ან შეთანხმებული ანგარიშსწორების ანგარიში. სად ჩამოგიჯდეს თანხა — ეს თავიდანვე უნდა იყოს გადაწყვეტილი.
3. მერჩანტის განაცხადი (acquiring). ეს არის ხელშეკრულება ბარათით მიღებაზე. აქვე განისაზღვრება:
   • საკომისიო მოდელი
   • ჩარიცხვის სიხშირე/გრაფიკი
   • რა ტიპის გადახდები გჭირდება: ერთჯერადი, განმეორებადი, წინასწარი ავტორიზაცია და ა.შ. (თუ საჭიროა)

პრაქტიკული რჩევა: განაცხადის შევსებამდე ჩამოწერე შენი სცენარები. მაგალითად: „ონლაინ მაღაზია, მიწოდება თბილისში/რეგიონში, შეკვეთის გაუქმება და თანხის დაბრუნება შესაძლებელია X საათში“. ბანკს ეს ეხმარება სწორი პარამეტრების დაყენებაში და შენც თავიდან იცილებ შუაში შეცვლებს.

3) როგორ მუშაობს პროცესი მარტივად: შეკვეთა → გადამისამართება ბანკის გვერდზე → 3D Secure → callback → სტატუსის დადასტურება

ბიზნესისთვის პროცესი უნდა იყოს მარტივი, მაგრამ ტექნიკურად ორი მხარე აქვს: რა ხედავს კლიენტი და რა ხდება სერვერზე.

სცენარი ტიპურია:

1. შეკვეთა საიტზე. კლიენტი ავსებს კალათას/ფორმას და აჭერს „გადახდა“.
2. გადამისამართება ბანკის გვერდზე. საიტი ქმნის გადახდის ინიციაციას და კლიენტი გადადის ბანკის უსაფრთხო გვერდზე (ან ბანკის ფანჯარაში, დამოკიდებულია სქემაზე).
3. 3D Secure. კლიენტი ადასტურებს გადახდას (SMS/აპი/ბიომეტრია — როგორც ბანკს აქვს).
4. callback (server-to-server შეტყობინება). გადახდის დასრულების შემდეგ ბანკი აგზავნის შეტყობინებას შენს სერვერზე: რა მოხდა რეალურად.
5. სტატუსის დადასტურება. შენს სისტემაში შეკვეთა იღებს სწორ სტატუსს: paid / failed / pending / canceled (ზუსტი სახელები შენს სისტემაზეა დამოკიდებული).

მნიშვნელოვანი დეტალი: კლიენტის დაბრუნება „მადლობა“ გვერდზე კარგია UX-ისთვის, მაგრამ გადახდის ფაქტი საბოლოოდ callback-ით უნდა დააფიქსირო. თორემ გექნება შემთხვევები, როცა:

• კლიენტმა დახურა ბრაუზერი და „მადლობა“ გვერდზე არ დაბრუნდა, მაგრამ გადახდა შესრულდა;
• კლიენტმა „მადლობა“ გვერდი ნახა ქეშიდან/რეფრეშით, მაგრამ გადახდა რეალურად ჩაიშალა;
• ქსელური პრობლემა მოხდა და მხოლოდ ფრონტენდზე დაყრდნობით არასწორად მონიშნე შეკვეთა.

ეს არის ის ადგილი, სადაც „გადახდის სისტემა საიტზე“ ხდება არა უბრალოდ ღილაკი, არამედ სწორი ბიზნეს-ლოგიკა.

4) BOG და TBC — რა განსხვავებაა პრაქტიკაში, რას ვირჩევთ და რატომ

ორივე ბანკი რეალურად მუშაობს და ორივეს შეუძლია ონლაინ მაღაზიის გადახდები. განსხვავება უფრო „პრაქტიკაში“ ჩანს:

• Onboarding და კომუნიკაცია. სად უფრო სწრაფად გიპასუხებენ, როგორ მარტივად მოგცემენ ტესტ გარემოს/წვდომებს, რამდენად მკაფიოა დოკუმენტაცია. ეს ხშირად უფრო მნიშვნელოვანია, ვიდრე „რომელი APIა უკეთესი“.
• დამატებითი მეთოდები. ზოგი ბიზნესისთვის გადამწყვეტია Apple Pay/Google Pay, ზოგი — განვადება. ზოგჯერ ერთ ბანკში ეს მარტივად ეწყობა, მეორეში — მეტი შეთანხმება სჭირდება. დეტალები ბანკის შეთავაზებაზეა და იცვლება.
• ფინანსური პირობები. საკომისიო, ჩარიცხვის გრაფიკი, refund-ების პირობები — აქ არ არსებობს „ერთადერთი სწორი“. უნდა შეადარო შენს საშუალო ჩეკს და მარჟას.

რას ვირჩევთ ჩვენ პრაქტიკაში? მოკლე პასუხი: ვირჩევთ იმას, რაც შენს პროცესს ნაკლებად დაგინგრევს. თუ უკვე გაქვს ანგარიში ერთ ბანკში, ბუღალტერია აწყობილია და ოპერაციები იქაა — ხშირად აზრი აქვს თავიდანვე იქით წასვლას. თუ შენთვის კრიტიკულია კონკრეტული ფუნქცია (მაგ. განვადება ან კონკრეტული გადახდის მეთოდი), არჩევანი ამას მიჰყვება.

Weblier-ში, როცა ვაკეთებთ ონლაინ მაღაზიას ან შეკვეთების სისტემას, BOG ინტეგრაციაც და TBC ინტეგრაციაც ერთნაირი პრინციპით იგეგმება: ჯერ სტატუსების ლოგიკა და back-office პროცესი (როგორ ამუშავებ შეკვეთას), მერე ბანკის მხარე.

5) რა ღირს — მერჩანტის საკომისიო და ინტეგრაციის ვადა

ორი ტიპის „ღირებულებაა“, რომელსაც უნდა განასხვაო:

1. მერჩანტის საკომისიო (ბანკისთვის).
   ეს არის პროცენტი/ტარიფი თითო ტრანზაქციაზე და ზოგჯერ დამატებითი პირობები. აქ კონკრეტულ რიცხვებს წინასწარ ვერ დაგიდებ — დამოკიდებულია ბიზნესზე და შეთანხმებაზე:

• საკომისიო
• ჩარიცხვის სიხშირე/დაყოვნება
• refund-ის წესები/ვადები

1. ინტეგრაციის სამუშაო (საიტის მხარეს).
   ვადა დამოკიდებულია იმაზე, რა გაქვს უკვე გამზადებული:

• თუ სისტემა მზადაა (კალათა, შეკვეთა, მომხმარებლის მონაცემები, ადმინისტრატორის პანელი), მაშინ ინტეგრაცია ხშირად ჯდება სამუშაო დღეში.
• თუ ჯერ არც შეკვეთის ლოგიკა გაქვს და არც სტატუსები, მაშინ გადახდის დამატება ხდება მთლიანი ფუნქციონალის ნაწილად და დრო იზრდება.

აქ trade-off მარტივია: „სწრაფად ჩასმა“ შეიძლება იმუშაოს, მაგრამ თუ არ გაქვს სწორად დალაგებული სტატუსები (paid/pending/refunded), მერე refund-ებზე და მარაგზე/მიწოდებაზე დაიწყება ქაოსი.

6) ხშირი შეცდომები: callback-ის არასწორი დამუშავება, ტესტ-რეჟიმის გამოტოვება, გადახდის სტატუსის მხოლოდ ფრონტენდზე დაყრდნობა

ეს სამი შეცდომა ყველაზე ხშირად გვხვდება, როცა „გადახდის სისტემა საიტზე“ ჩასმულია ნაჩქარევად.

• callback-ის არასწორი დამუშავება.
  პრობლემა: სისტემა იღებს შეტყობინებას, მაგრამ ვერ აკავშირებს სწორ შეკვეთასთან (მაგ. არასწორი order_id, დუბლირებული შეტყობინებები, ან არ ინახავს ტრანზაქციის იდენტიფიკატორს).
  პრაქტიკული მიდგომა: თითო გადახდას მიაბი უნიკალური იდენტიფიკატორი, ჩაწერე ლოგში, და გაითვალისწინე, რომ callback შეიძლება მოვიდეს ერთზე მეტჯერ.
• ტესტ-რეჟიმის გამოტოვება.
  პრობლემა: პირველად „ცოცხალზე“ ამოწმებ, მერე აღმოჩნდება, რომ წარუმატებელი გადახდები არ იწერება ან pending ჩერდება.
  პრაქტიკული მიდგომა: ტესტში აუცილებლად გაიარე მინიმუმ ეს სცენარები:
  • წარმატებული გადახდა
  • წარუმატებელი გადახდა
  • გაუქმება (კლიენტმა დახურა)
  • callback მოვიდა, მაგრამ მომხმარებელი არ დაბრუნდა საიტზე
  • მომხმარებელი დაბრუნდა, მაგრამ callback დაგვიანდა
• გადახდის სტატუსის მხოლოდ ფრონტენდზე დაყრდნობა.
  პრობლემა: „მადლობა“ გვერდი არ არის მტკიცებულება. ზოგჯერ გვერდი იხსნება, მაგრამ გადახდა არ დასრულდა; ზოგჯერ პირიქით.
  პრაქტიკული მიდგომა: შეკვეთის სტატუსი იცვლება მხოლოდ სერვერზე, ბანკის დადასტურებული პასუხით. ფრონტენდზე უბრალოდ აჩვენე „ვამოწმებთ გადახდას“ და განაახლე სტატუსი API-დან.

თუ ამ სამს სწორად მოაგვარებ, დანარჩენი საკითხები (დიზაინი, ტექსტები, ღილაკები) უკვე მეორეხარისხოვანია.

7) განვადება და Apple/Google Pay — მოკლედ

ორი პოპულარული დამატებაა, რომლებიც ხშირად „შემდეგ ეტაპზე“ მოდის, მაგრამ ჯობს თავიდანვე გაითვალისწინო.

• განვადება.
  ეს ჩვეულებრივ არ არის „უბრალოდ კიდევ ერთი გადახდის მეთოდი“. ხშირად მოითხოვს დამატებით შეთანხმებას, UI-ში პირობების სწორ ჩვენებას, და პროცესში მეტი სტატუსის/დადასტურების ლოგიკას. თუ საშუალო ჩეკი მაღალია, განვადება რეალურად ცვლის კონვერსიას, მაგრამ ზრდის ოპერაციულ კითხვებს (გაუქმება, დაბრუნება, ნაწილობრივი დაბრუნება).
• Apple Pay / Google Pay.
  მომხმარებლისთვის ეს არის ნაკლები ველები და სწრაფი გადახდა. შენთვის — იგივე acquiring-ის ნაწილი, მაგრამ ხშირად აქვს დამატებითი მოთხოვნები დომენზე/ვერიფიკაციაზე და ტესტირებაზე. კარგი ამბავი: თუ ძირითადი ბარათით გადახდა სწორად გაქვს აწყობილი (callback, სტატუსები, ლოგები), დანამატები უკვე უფრო მარტივად ჯდება.

FAQ

კითხვა 1: მჭირდება თუ არა აუცილებლად იურიდიული პირი, რომ ონლაინ გადახდა ჩავრთო?
უმეტეს შემთხვევაში — დიახ. ბანკს მერჩანტის ანგარიში ბიზნესზე უფორმდება (შპს/ინდ.მეწარმე). კონკრეტულ გამონაკლისებს ბანკი გეტყვის, მაგრამ დაგეგმე, რომ რეგისტრაცია საჭირო იქნება.

კითხვა 2: შეიძლება ორი ბანკის გადახდაც ერთდროულად მქონდეს (BOG + TBC)?
ტექნიკურად შესაძლებელია, მაგრამ აზრი აქვს მხოლოდ მაშინ, თუ რეალური მიზეზი გაქვს: განსხვავებული პირობები, სარეზერვო არხი, ან კონკრეტული მეთოდი მხოლოდ ერთში. წინააღმდეგ შემთხვევაში UX რთულდება და მხარდაჭერაც ორმაგდება.

კითხვა 3: როდის უნდა შევცვალო შეკვეთის სტატუსი „გადახდილია“-ზე?
მხოლოდ მაშინ, როცა სერვერზე მიიღებ ბანკის დადასტურებულ პასუხს (callback/verification). მომხმარებლის ეკრანზე ნაჩვენები „წარმატება“ არ არის საკმარისი.

კითხვა 4: refund (თანხის დაბრუნება) როგორ იგეგმება?
დაგეგმე თავიდანვე: ვინ აკეთებს refund-ს (ადმინი/მენეჯერი), როგორ ინახავთ ტრანზაქციის იდენტიფიკატორს, და როგორ აისახება ეს შეკვეთაზე (refunded, partially_refunded). ბანკის პირობები და ვადები, რომ გუნდისთვის ერთი წესები იყოს.

დაიწყე პროექტი