დეველოპერის გზამკვლევი

Payze ინტეგრაციის გადატანა Quickpay-ზე

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

გადასვლების უმეტესობა ერთი-ორი დღის სამუშაოა. სამი რამ იცვლება; დანარჩენი თქვენს აპლიკაციაში იქ რჩება, სადაც არის.

სანამ დაიწყებთ

გჭირდებათ აქტიური სავაჭრო ანგარიში მინიმუმ ერთ ქართულ ბანკთან, Quickpay ანგარიში ამ მონაცემებით და API გასაღები.

გასაღები ბრენდზეა მიბმული და ორი ფორმით მოდის — qpk_test_... sandbox-ისთვის და qpk_live_... საწარმოო რეჟიმისთვის. სატესტო გასაღები მუშაობს მხოლოდ მაშინ, როცა ბრენდი სატესტო რეჟიმშია, ასე რომ სატესტო გაშვებას ნამდვილი ბარათის შემთხვევით ჩამოჭრა არ შეუძლია.

1. გადახდის შექმნა → `POST /v1/payments`

სადაც კი თქვენი კოდი ქმნის გადახდას, ის ახლა აგზავნის მოთხოვნას https://api.quickpay.ge/v1/payments-ზე Bearer ტოკენით. პასუხი შეიცავს payment_url-ს — გადაამისამართეთ მომხმარებელი იქ.

POST https://api.quickpay.ge/v1/payments
Authorization: Bearer qpk_live_...
Idempotency-Key: order-10432
Content-Type: application/json

{
  "amount": 149.99,
  "currency": "GEL",
  "gateway_slug": "bog_card",
  "merchant_order_id": "ORDER-10432",
  "description": "Order #10432",
  "customer_name": "Nini Beridze",
  "customer_email": "nini@example.ge",
  "customer_phone": "+995555123456",
  "return_url": "https://yourstore.ge/thank-you",
  "cancel_url": "https://yourstore.ge/cart",
  "webhook_url": "https://yourstore.ge/webhooks/quickpay"
}

მხოლოდ amount არის სავალდებულო. დანარჩენი ყველაფერი არასავალდებულოა და ნაჩვენებია, რადგან რეალურ ინტეგრაციათა უმეტესობას სჭირდება: return_url და cancel_url არის ის, სად ხვდება მომხმარებელი გადახდის ან გაუქმების შემდეგ, webhook_url გადაფარავს თქვენს ბრენდის დონის ბოლოწერტილს ამ ერთი გადახდისთვის, merchant_order_id ატარებს თქვენს საკუთარ შეკვეთის ნომერს, ხოლო customer_* ველები წინასწარ ავსებს checkout-ს.

gateway_slug არასავალდებულოა. გამოტოვეთ და მომხმარებელი თავად აირჩევს მეთოდს Quickpay-ის hosted checkout-ზე — ბარათი, განვადება, BNPL, კრიპტო, საბანკო გადარიცხვა. თუ საკუთარი გადახდის მეთოდის ამომრჩევი გქონდათ აშენებული, შეგიძლიათ წაშალოთ.

თანხები არის ათწილადები, არა უმცირესი ერთეულები. 149.99, არა 14999. ეს თითქმის ყოველ გადასვლას ერთხელ მაინც წაბორძიკებს. ლარი ნაგულისხმევია; USD, EUR და GBP ასევე მხარდაჭერილია.

Idempotency-Key ჰედერი იცავს ორმაგი ჩამოჭრისგან განმეორებითი მოთხოვნისას. იმავე გასაღებით გამეორება აბრუნებს 200-ს თავდაპირველი გადახდით; განსხვავებული თანხით ან ვალუტით გამეორება აბრუნებს 409-ს.

2. სტატუსის გამოკითხვა → ვებჰუკები

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

მოვლენები: payment.paid, payment.failed, payment.refunded, payment.partially_refunded, payment.refund_pending, payment.cancelled, payment.expired, პლუს subscription.charged, subscription.failed, invoice.paid და lead.submitted.

ყოველი მოთხოვნა ატარებს ხელმოწერის ჰედერს:

QUICKPAY-SIGNATURE: t=1754300000,v1=8f3a...

v1 არის HMAC-SHA256, გამოთვლილი სტრიქონზე "{timestamp}.{raw_json_body}", თქვენი ვებჰუკის საიდუმლოთი დაშიფრული:

[$t, $v1] = parse_signature($_SERVER['HTTP_QUICKPAY_SIGNATURE']);

if (abs(time() - $t) > 300) {
    return response('stale', 400);          // 5-minute skew limit
}

$expected = hash_hmac('sha256', "{$t}.{$rawBody}", $webhookSecret);

if (!hash_equals($expected, $v1)) {
    return response('bad signature', 400);
}

ხელი მოაწერეთ ნედლ request body-ს, ნებისმიერი JSON-პარსინგის ან ხელახალი კოდირების წინ. პეილოადის ხელახლა სერიალიზაცია ცვლის ბაიტებს და ხელმოწერა არასდროს დაემთხვევა. ეს არის ყველაზე გავრცელებული შეცდომა ნებისმიერი HMAC ვებჰუკის იმპლემენტაციაში — თუ ვერიფიკაცია ჩავარდება და ყველაფერი გამართული გეჩვენებათ, სავარაუდოდ სწორედ ეს არის მიზეზი.

თქვენმა ბოლოწერტილმა უნდა დააბრუნოს 2xx 30 წამში. ვერ მიწოდებული ვებჰუკები მეორდება 5-ჯერ, ასე რომ თქვენი დამმუშავებელი უნდა იყოს იდემპოტენტური — ერთსა და იმავე მოვლენას საბოლოოდ ორჯერ მიიღებთ.

3. თანხის დაბრუნება → `POST /v1/payments/{uuid}/refund`

სრული ან ნაწილობრივი. გამოტოვეთ amount, რომ დარჩენილი ბალანსი დაბრუნდეს. აბრუნებს განახლებულ გადახდის ობიექტს.

დაბრუნება შეიძლება payment.refund_pending-ში იდგეს დასრულებამდე, სისტემის მიხედვით. დაამუშავეთ ორივე — ესეც და payment.refunded-იც.

ტესტირება

ჩადეთ თქვენი ბრენდი სატესტო რეჟიმში, გამოიყენეთ <code>qpk_test_...</code> გასაღები და გაუშვით მთელი პროცესი თავიდან ბოლომდე. ნამდვილი მოთხოვნები სისტემისკენ არ იგზავნება.

დაშბორდი მოიცავს API Playground-ს მოთხოვნების გასაშვებად კოდის დაწერის გარეშე — ყველაზე სწრაფი გზა, დარწმუნდეთ თქვენი payload-ის ფორმაში, სანამ აპლიკაციის კოდს შეეხებით.

გაშვების საკონტროლო სია

ბანკის სავაჭრო მონაცემები შეყვანილია და მოდული გააქტიურებულია
sandbox გაშვება დასრულებულია ყოველი გადახდის მეთოდისთვის, რომლის შეთავაზებასაც აპირებთ
ვებჰუკის ბოლოწერტილი გაშვებულია და ხელმოწერის შემოწმება ნამდვილ payload-ზეა შემოწმებული
დამმუშავებელი დადასტურებულია, როგორც იდემპოტენტური — გაუშვით იგივე მოვლენა ორჯერ
დროის ცდომილების შემოწმება ჩართულია
ბრენდი გადართულია სატესტო რეჟიმიდან, qpk_test_ შეცვლილია qpk_live_-ით
მინიმალური თანხის ერთი ცოცხალი ტრანზაქცია, შემდეგ მისი დაბრუნება
ძველი სისტემის ვებჰუკის ბოლოწერტილი დატოვებულია გაშვებული ერთი კვირით, დაგვიანებული მოვლენების დასაჭერად

დამატებითი მასალა

სრული API დოკუმენტაცია
SDK-ები — PHP, Laravel, Node/TypeScript
მოთხოვნების ლიმიტი: 100 მოთხოვნა წუთში თითოეულ API გასაღებზე, ნაჩვენები X-RateLimit-Limit და X-RateLimit-Remaining ჰედერებით

რაღაცაზე გაჭედით? გამოგვიგზავნეთ დეტალები — აღწერეთ თქვენი მიმდინარე ინტეგრაცია და ჩვენ დაგეხმარებით მისი შესაბამისობის დადგენაში.

უკან, Payze-ის ალტერნატივის მიმოხილვაზე