# საქართველოს ბანკის ტექნიკური დოკუმენტაცია > საქართველოს ბანკის საჯარო API სერვისების დოკუმენტაცია: ონლაინ გადახდები, ბმულით გადახდები, ბილინგი, ონლაინ განვადება, ბიზნეს ინტერნეტბანკი და ღია ბანკინგი. --- # შესავალი Source: https://api.bog.ge/docs/payments/introduction ## აგრეგატორის ინტეგრაციის პროტოკოლი ელ. კომერციის მომსახურებისთვის ## რა არის ონლაინ გადახდების API ონლაინ გადახდების API განკუთვნილია ნებისმიერ ელექტრონულ სისტემასთან უსაფრთხო გადახდების მოდულის სწრაფად და მარტივად ინტეგრაციისთვის. მისი საშუალებით მარტივდება გადახდის პროცესი, რაც ბიზნესს საშუალებას აძლევს მიიღოს გადახდები სხვადასხვა გადახდის მეთოდის გამოყენებით, მათ შორის საქართველოს ბანკისა და სხვა კომერციული ბანკების (VISA, MasterCard, American Express) ბარათებით. ## პროტოკოლი და ტექნიკური სპეციფიკაციები - **API არქიტექტურა** - RESTful - **კომუნიკაციის პროტოკოლი** - HTTP/1.1. ყველა API მეთოდის გამოძახება უნდა განხორციელდეს HTTPS-ის გამოყენებით, რათა უზრუნველყოფილი იყოს მონაცემთა უსაფრთხო გადაცემა. - **მონაცემთა ფორმატი** - JSON. ამარტივებს API მეთოდებთან ინტეგრაციას. - **ავთენტიფიკაცია და უსაფრთხოება** - ავთენტიფიკაციისთვის გამოიყენება OAuth 2.0, ხოლო JSON Web Tokens (JWT) უზრუნველყოფს მონაცემთა უსაფრთხო გაცვლას. - **სინქრონული API მოთხოვნები** - ყველა API მოთხოვნა მუშავდება დაუყოვნებლივ და დაბრუნებული response ასახავს API გამოძახების შედეგს. - **ასინქრონული webhook შეტყობინებები** - მიუხედავად იმისა, რომ API მოთხოვნები სინქრონულია, მნიშვნელოვანი მოვლენები, როგორიცაა გადახდის დადასტურება და განახლება, მუშავდება ასინქრონულად Callback-ის მეშვეობით, რაც უზრუნველყოფს საიმედო, real-time კომუნიკაციას. - **შეცდომების მართვა** - სტანდარტული HTTP სტატუს კოდები და დეტალური შეცდომის შეტყობინებები გამოიყენება წარმატებული ან შეცდომით დასრულებული ოპერაციების დასამუშავებლად, რაც დეველოპერებს ეხმარება პრობლემების სწრაფ დიაგნოსტირებაში. ## გადახდის პროცესის მოკლე აღწერა - **მომხმარებელი აინიცირებს გადახდას:** მომხმარებელი ირჩევს სასურველ პროდუქტს ან მომსახურებას (ან პროდუქტების / მომსახურებების კალათას) ბიზნესის ვებგვერდზე და აჭერს გადახდის ღილაკს. - **ბიზნესი აგზავნის შეკვეთის მოთხოვნას:** ბიზნესი აგზავნის [შეკვეთის მოთხოვნას](https://api.bog.ge/docs/payments/standard-process/create-order) ონლაინ გადახდების API-ში გადახდის პროცესის დასაწყებად. - **API აბრუნებს შეკვეთის მოთხოვნის დეტალებს:** გადახდის კარიბჭე აბრუნებს საჭირო პარამეტრებს — როგორიცაა შეკვეთის მოთხოვნის ID და გადამისამართების URL — რომელიც გადახდის პროცესის გაგრძელებას უზრუნველყოფს. - **მომხმარებელი გადამისამართდება ონლაინ გადახდის გვერდზე:** ბიზნესი მომხმარებელს ამისამართებს ონლაინ გადახდის გვერდზე, სადაც მომხმარებელი ირჩევს გადახდის მეთოდს, შეჰყავს ბარათის დეტალები ან ასრულებს გადახდას ინტერნეტ ბანკში ავტორიზაციით. - **გადახდის დამუშავება:** ონლაინ გადახდების სისტემა ამოწმებს გადახდის დეტალებს და უსაფრთხოდ ამუშავებს გადახდას. - **Callback შეტყობინება იგზავნება ბიზნესთან:** როგორც კი გადახდა დამუშავდება, ონლაინ გადახდის სისტემა აგზავნის [Callback](https://api.bog.ge/docs/payments/standard-process/callback)-ს, ბიზნესის მიერ შეკვეთის მოთხოვნაში მითითებულ Callback მისამართზე. :::note Callback-ის მიღება გადამწყვეტი ბიჯია გადახდის პროცესში. იგი ადასტურებს გადახდის სტატუსს (წარმატებული ან წარუმატებელი) და სხვა საჭირო დეტალებს. Callback-ში მიღებულ ინფორმაციაზე დაყრდნობით, ბიზნესმა უნდა უზრუნველყოს თავისი სისტემის განახლება. ::: - **ოპერაციის დასრულება:** Callback-ის მიღების შემდეგ, ბიზნესი ამთავრებს პროცესს, ადასტურებს შეკვეთას მომხმარებელთან და ასრულებს ყველა დაკავშირებულ საოპერაციო ნაბიჯს. :::note ონლაინ გადახდის გვერდზე გადამისამართებამდე ბიზნესს შეუძლია, გამოიყენოს ბარათის დამახსოვრების ფუნქციონალი, შემდგომში ოპერაციების ავტომატურ რეჟიმში ან ბარათის მონაცემების შეყვანის გარეშე განხორციელების მიზნით. ::: --- # აუტენტიფიკაცია Source: https://api.bog.ge/docs/payments/authentication ## რა დამჭირდება გადახდის API-ს გამოსაყენებლად ონლაინ გადახდების API-ს გამოსაყენებლად საჭიროა აუტენტიფიკაცია [HTTP Basic Auth](https://en.wikipedia.org/wiki/Basic_access_authentication)-ის გამოყენებით. ამისთვის თქვენ დაგჭირდებათ, იცოდეთ სისტემაში შესასვლელი რეკვიზიტები (Credentials), რომელიც თითოეული ბიზნესისთვის უნიკალურია. რეკვიზიტები მოიცავს ორ პარამეტრს: client_id და client_secret, რომელიც გამოიყენება, როგორც username-ი და password-ი, ბიზნესის აუტენტიფიკაციისას. ## როგორ გავიგოთ ბიზნესის სისტემაში შესასვლელი რეკვიზიტები მას შემდეგ, რაც კომპანია დარეგისტრირდება ბიზნესად საბანკო სისტემაში და შეავსებს ყველა საჭირო მონაცემს, მას მიენიჭება და გადაეცემა სისტემაში შესასვლელი რეკვიზიტები client_id და client_secret. რეკვიზიტები ბიზნესის უნიკალური მაიდენტიფიცირებელია. ამასთან, client_secret პაროლის მნიშვნელობის პარამეტრია - მისი სხვა პირისთვის გადაცემა, გასაჯაროება, დაუშვებელია. ამან შეიძლება ბიზნესისთვის საფრთხის ალბათობა მნიშვნელოვნად გაზარდოს! client_secret-ის ცვლილება ბიზნესის მიერ შეუძლებელია. ## მეთოდის აღწერა მოცემული მეთოდის საშუალებით, ბიზნესი გადის აუტენტიფიკაციის პროცესს. გამოძახების შედეგად, ონლაინ გადახდების სერვერის მიერ ბრუნდება Bearer Token, რომელიც ყველა შემდგომი მეთოდის გამოძახებისთვის არის აუტენტიფიკაციისთვის აუცილებელი პარამეტრი. ### Header-ის პარამეტრები - `Content-Type` — application/x-www-form-urlencoded, required - `Authorization` — Basic , required გადაეცემა „Basic „ + „:“ მნიშვნელობა კოდირებული Base64 ფორმატში (მაგ: „Basic ODI4Mjo3Njk3MDY0OTlmMDcwOWUyMzQ4NDU4NjNmOThiMjMxNA==“), სადაც და არის ბანკის მიერ ბიზნესისთვის გადაცემული, სისტემაში შესვლისთვის საჭირო, რეკვიზიტები. ### Body-ს პარამეტრები - `grant_type` — client_credentials, required მნიშვნელობად გადაეცემა ფიქსირებული ტექსტი: `client_credentials` **CURL** ```bash curl -X POST 'https://oauth2.bog.ge/auth/realms/bog/protocol/openid-connect/token' \ -u {client_id}:{client_secret} \ -H 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'grant_type=client_credentials' ``` ### Response - `access_token` — string ავტორიზაციის სერვერის მიერ დაბრუნებული Token-ის მნიშვნელობა - `token_type` — string Token-ის ტიპი (ბრუნდება ტექსტური მნიშვნელობა - `Bearer`) - `expires_in` — number აბრუნებს რიცხვით მნიშვნელობას, თუ რამდენი წამის განმავლობაში არის აქტიური Token. **RESPONSE** ```json { "access_token": "", "token_type": "Bearer", "expires_in": 1634719923245 } ``` --- # შეკვეთის მოთხოვნა Source: https://api.bog.ge/docs/payments/standard-process/create-order მეთოდის საშუალებით, ბიზნესი ონლაინ გადახდის სერვერზე აგზავნის გადახდის დეტალებს, ტექნიკურ მახასიათებლებსა და გადასახდელ თანხას. ოპერაციის წარმატებით დასრულების შემთხვევაში, პროცესის გასაგრძელებლად, მომხმარებელი უნდა გადაამისამართოთ ონლაინ გადახდის გვერდზე, `_links` პარამეტრში დაბრუნებულ `redirect` მისამართზე. ### Header-ის პარამეტრები - `Content-Type` — application/json, required - `Authorization` — Basic , required გადაეცემა `Bearer ` მნიშვნელობა, სადაც `jwt_token` არის აუტენტიფიკაციის მეთოდის Response-ის access_token პარამეტრში დაბრუნებული მნიშვნელობა. - `Idempotency-Key` — UUID v4 Idempotency-Key პარამეტრი უნდა იყოს უნიკალური ყველა ახალი API რექვესთისთვის. იმავე API-ზე Idempotency-Key-ის განმეორებით გამოყენებისას სერვერი დააბრუნებს იმავე სტატუს კოდსა და body-ს, რაც თავდაპირველი მოთხოვნისას. ეს ფუნქცია განსაკუთრებით სასარგებლოა თანმიმდევრული შედეგის უზრუნველსაყოფად, როდესაც საქმე გვაქვს ქსელური პრობლემებითა ან ხელახალი ცდებით გამოწვეულ დუბლირებულ მოთხოვნებთან. - `Accept-Language` — string განსაზღვრავს ონლაინ გადახდების გვერდზე გადამისამართების შემდეგ, რა ენის ინტერფეისი დახვდება მომხმარებელს. იღებს ორ მნიშვნელობას: - `ka` - ქართული (Default) - `en` - ინგლისური. - `Theme` — string განსაზღვრავს ონლაინ გადახდების გვერდზე გადამისამართების შემდეგ, რა თემის ინტერფეისი დახვდება მომხმარებელს. იღებს ორ მნიშვნელობას: - `light` - ღია (Default) - `dark` - მუქი. ### Body-ს პარამეტრები - `application_type` — "web" | "mobile" აპლიკაციის ტიპი, საიდანაც ხდება შეკვეთის შექმნა. გამოიყენება Apple Pay-ით და Google Pay-ით გადახდისას, როდესაც Apple Pay-ის ან Google Pay-ის ღილაკი განთავსებულია უშუალოდ მერჩანტის ვებ გვერდზე ან მობილურ აპლიკაციაში. აპლიკაციის ტიპის მნიშვნელობებია: - `web` - ვებ გვერდიდან შექმნილი შეკვეთის აპლიკაციის ტიპი. - `mobile` - მობილური აპლიკაციიდან შექმნილი შეკვეთის აპლიკაციის ტიპი. - `buyer` — object ინფორმაცია ბიზნესში მყიდველის შესახებ. - `buyer.full_name` — string მყიდველის სახელი და გვარი. - `buyer.masked_email` — string მყიდველის დაშიფრული ელ. ფოსტის მისამართი. - `buyer.masked_phone` — string მყიდველის დაშიფრული ტელეფონის ნომერი. - `callback_url` — string, required ბიზნესის ვებმისამართი (აუცილებლად https ტიპის), რომელსაც ავტომატურად გამოიძახებს ბანკი, ოპერაციის დასრულების შემდეგ, ბიზნესისთვის გადახდის მონაცემების მიწოდების მიზნით (Callback-ის დროს). - `external_order_id` — string გადახდის იდენტიფიკატორი ბიზნესის სისტემიდან. გადმოცემული მნიშვნელობის პირველი 25 სიმბოლო აისახება გადახდის დანიშნულებაში, როგორც გადამხდელის ამონაწერში, ისე კომპანიის ანგარიშზე თანხის ჩარიცხვის დანიშნულებაში. - `capture` — "automatic" | "manual" ტრანზაქციის ტიპი, რომელიც იღებს ორ მნიშვნელობას: - `automatic` - სტანდარტული ორდერის შექმნა, გადახდა მოხდება პრეავტორიზაციის გარეშე, ანუ მომხარებლის ანგარიშიდან თანხა მომენტალურად ჩამოიჭრება - `manual` - გადახდის შესრულების შემდეგ მომხარებლის ანგარიშზე თანხა დაიბლოკება და მომხმარებლისთვის არ იქნება ხელმისაწვდომი. გადახდის დასასრულებლად უნდა გამოიყენოთ პრეავტორიზაციის დასრულების მეთოდი და დაადასტუროთ/უარყოთ ოპერაცია. ამ ოპერაციის 30 დღეში შეუსრულებლობის შემთხვევაში, თანხას ავტომატურად მოეხსნება ბლოკი და ისევ იქნება ხელმისაწვდომი მომხარებლისთვის. ამ ფუნქციონალის გამოყენება შესაძლებელია მხოლოდ Apple Pay-ით, Google Pay-ით ან საბარათე გადახდაზე. - `purchase_units` — object, required ინფორმაცია შეკვეთის შესახებ. - `purchase_units.basket` — array, required ბიზნესში, მოცემული გადახდის ფარგლებში, შესყიდული პროდუქტების ან სერვისების კალათა. - `purchase_units.basket[].product_id` — string, required პროდუქტის/სერვისის იდენტიფიკატორი ბიზნესის სისტემაში. - `purchase_units.basket[].description` — string პროდუქტის/სერვისის დასახელება (აღწერა). - `purchase_units.basket[].quantity` — number, required თითოეული პროდუქტის/სერვისის რაოდენობა (მოცულობა). მინიმალური მნიშვნელობა არის 1. - `purchase_units.basket[].unit_price` — number, required პროდუქტის/სერვისის ერთეულის ფასი. - `purchase_units.basket[].unit_discount_price` — number აქციით გადახდის შემთხვევაში, შესყიდული პროდუქტის/სერვისის ერთეულის დაკლებული თანხის მოცულობა. - `purchase_units.basket[].vat` — number პროდუქტის/სერვისის დამატებული ღირებულების გადასახადი (დღგ). - `purchase_units.basket[].vat_percent` — number პროდუქტის/სერვისის დამატებული ღირებულების გადასახადის (დღგ) პროცენტი. - `purchase_units.basket[].total_price` — number მთლიანი თანხა. - `purchase_units.basket[].image` — string პროდუქტის/სერვისის სურათის ვებმისამართი (ლინკი). - `purchase_units.basket[].package_code` — string პროდუქტის კოდი. - `purchase_units.basket[].tin` — string საგადასახადო საიდენტიფიკაციო ნომერი (TIN). - `purchase_units.basket[].pinfl` — string გადამხდელის კოდი (PINFL). - `purchase_units.basket[].product_discount_id` — string პროდუქტის ფასდაკლების იდენტიფიკატორი. თუ მოწოდებული მნიშვნელობით ბანკში დარეგისტრირებულია ფასდაკლების აქცია, ფასდაკლების პირობების გათვალისწინებით, შეკვეთაზე გავრცელდება შესაბამისი აქცია. - `purchase_units.delivery` — object ინფორმაცია მიტანის სერვისის შესახებ. - `purchase_units.delivery.amount` — number მიტანის ღირებულება. - `purchase_units.total_amount` — number, required სრული გადასახდელი თანხის მოცულობა. - `purchase_units.total_discount_amount` — number აქციით გადახდის შემთხვევაში, დაკლებული თანხის მოცულობა. - `purchase_units.currency` — string ვალუტა, რომელშიც ხორციელდება გადახდა: - `GEL` - ქართული ლარი (ნაგულისმევი) - `USD` - ამერიკული დოლარი - `EUR` - ევრო - `GBP` - ბრიტანული გირვანქა. - `redirect_urls` — object ბიზნესის ვებმისამართები, რომლებზეც შესაძლოა, გადამისამართდეს მომხმარებელი ონლაინ გადახდის სისტემიდან ოპერაციის დასრულების შემდეგ. - `redirect_urls.success` — string ვებმისამართი ოპერაციის წარმატებით დასრულების შემთხვევაში. მნიშვნელობის არ გადმოცემის შემთხვევაში მომხმარებელი დარჩება ონლაინ გადახდების გვერდზე და გამოუჩნდება შესაბამისი ქვითარი. - `redirect_urls.fail` — string ვებმისამართი ოპერაციის წარუმატებლად დასრულების შემთხვევაში. მნიშვნელობის არ გადმოცემის შემთხვევაში მომხმარებელი დარჩება ონლაინ გადახდების გვერდზე და გამოუჩნდება შესაბამისი ქვითარი. - `ttl` — number შეკვეთის სიცოცხლის ხანგრძლივობა წუთებში (შეკვეთის შექმნიდან რამდენი წუთის განმავლობაში შეეძლება მომხმარებელს გადახდის შესრულება). მოცემული პარამეტრის ლოგიკა სხვა და სხვა ინდუსტრიის ბიზნესისთვის განსხვავებული შეიძლება იყოს. პარამეტრის მინიმალური შესაძლო მნიშვნელობაა `2`, მაქსიმალური კი - `1440` (24 საათი). პარამეტრის არ გადმოცემის შემთხვევაში სისტემა იგულისხმებს `15` წუთს. - `payment_method` — array გადახდის მეთოდები, რომლების გამოყენებასაც შეძლებს მომხმარებელი ამ შეკვეთაზე გადახდის განსახორციელებლად. აუცილებელია, ბიზნესს გააქტიურებული ჰქონდეს ყველა გადმოცემული მეთოდი. პარამეტრის არ გადმოცემის შემთხვევაში მომხმარებელს ონლაინ გადახდის გვერდზე გადამისამართების შემდეგ შეეძლება ყველა იმ გადახდის მეთოდით სარგებლობა, რომელიც გააქტიურებული აქვს ბიზნესს. შესაძლო მნიშვნელობები: - `card` - საბანკო ბარათით გადახდა - `google_pay` - Google Pay-ით და საბანკო ბარათით გადახდა (ამ მნიშვნელობის გადმოცემის შემთხვევაში, მომხმარებელს შეეძლება როგორც Google Pay-ით, ასევე საბანკო ბარათით გადახდა. აუცილებელია, რომ ბიზნესს გააქტიურებული ჰქონდეს ორივე გადახდის მეთოდი) - `apple_pay` - Apple Pay-ით და საბანკო ბარათით გადახდა (ამ მნიშვნელობის გადმოცემის შემთხვევაში, მომხმარებელს შეეძლება როგორც Apple Pay-ით, ასევე საბანკო ბარათით გადახდა. აუცილებელია, რომ ბიზნესს გააქტიურებული ჰქონდეს ორივე გადახდის მეთოდი) - `bog_p2p` - საქართველოს ბანკის, ინტერნეტ ან მობაილ ბანკის მომხმარებლით გადარიცხვა - `bog_loyalty` - საქართველოს ბანკის ქულებით MR/Plus გადახდა - `bnpl` - ნაწილ-ნაწილით გადახდა - `bog_loan` - სტანდარტული საბანკო განვადება - `gift_card` - სასაჩუქრე ბარათით გადახდა - `config` — object კონკრეტული გადახდის კონფიგურაცია. - `config.loan` — object გადახდის კონფიგურაცია. პარამეტრის გადმოცემა აუცილებელია თუ გსურთ, რომ შეკვეთის გადახდა მხოლოდ განვადებით ("payment_method":["bog_loan"] ) ან მხოლოდ ნაწილ-ნაწილით ("payment_method":["bnpl"] ) მოხდეს. - `config.loan.type` — string განვადების/ნაწილ-ნაწილის ფასდაკლების კოდი (კალკულატორის მიერ დაბრუნებული discount_code პარამეტრის მნიშვნელობა). - `config.loan.month` — number განვადების/ნაწილ-ნაწილის ხანგრძლივობა თვეებში (კალკულატორის მიერ დაბრუნებული month პარამეტრის მნიშვნელობა). - `config.campaign` — object აქციით გადახდის კონფიგურაცია. იმისთვის, რომ მომხმარებელმა შეძლოს ბიზნესზე დამატებული აქციით სარგებლობა, საჭიროა, შეკვეთის შექმნისას გადახდის მეთოდში საბარათე გადახდის მითითება ("payment_method":["card"] ). - `config.campaign.card` — string ბარათი, რომელზეც ვრცელდება აქცია: - `visa` - ვიზა - `mc` - მასტერქარდი - `solo` - სოლო ბარათი - `config.campaign.type` — string აქციის ტიპი: - `restrict` - ბარათის ტიპის შეზღუდვა - `client_discount` - ფასდაკლება კონკრეტულ ბარათის ტიპზე - `config.google_pay` — object გადახდის კონფიგურაცია. პარამეტრის გადმოცემა აუცილებელია თუ გსურთ, რომ შეკვეთის გადახდა ბიზნესის ვებგვერდზე განთავსებული Google Pay-ს ღილაკით მოხდეს. - `config.google_pay.google_pay_token` — string სრულყოფილი string მნიშვნელობა, რომელიც წარმოადგენს Google Pay-ის დაკრიპტულ გადახდის დეტალებს. მნიშვნელობა უნდა გადმოეცეს სრულყოფილად, როგორი სახითაც მიიღეთ Google Pay SDK-სგან, ცვლილებების გარეშე. - `config.google_pay.external` — boolean - `true` - გადახდა ინიცირდება ბიზნესის ვებგვერდზე განთავსებული Google Pay-ს ღილაკით - `false` - გადახდა ხდება ბანკის გადახდების გვერდიდან (ნაგულისმევი) - `config.apple_pay` — object გადახდის კონფიგურაცია. პარამეტრის გადმოცემა აუცილებელია თუ გსურთ, რომ შეკვეთის გადახდა ბიზნესის ვებგვერდზე განთავსებული Apple Pay-ს ღილაკით მოხდეს. - `config.apple_pay.external` — boolean - `true` - გადახდა ინიცირდება ბიზნესის ვებგვერდზე განთავსებული Apple Pay-ს ღილაკით - `false` - გადახდა ხდება ბანკის გადახდების გვერდიდან (ნაგულისმევი) - `config.account` — object გადახდის კონფიგურაცია. პარამეტრის გადმოცემა აუცილებელია თუ თქვენთვის კონფიგურირებულია რამდენიმე ელ.კომერციის POS ტერმინალი ერთსადაიმავე ვალუტაში: შესრულებული ოპერაციები გსურთ დააჯგუფოთ ბიზნესის საჭიროებებიდან გამომდინარე ან ანგარიშსწორება შესრულდეს ბიზნესის სხვადასხვა ანგარიშზე. - `config.account.tag` — string ელ.კომერციის POS ტერმინალის იდენტიფიკატორი. თუ მოწოდებული tag-ის მნიშვნელობა არ ემთხვევა POS-ის კონფიგურაციას ან tag მოწოდებული არ არის, ოპერაცია შესრულდება default POS ტერმინალზე და შესაბამის ანგარიშსწორების ანგარიშზე. შენიშვნა: ტეგის მნიშვნელობის შეთანხმება აუცილებელია დამატებითი POS-ის კონფიგურირებისას. - `config.split` — object თანხის გაყოფის კონფიგურაციის ობიექტი. ამ პარამეტრის გადმოცემა აუცილებელია, თუ გსურთ შეკვეთის თანხა ავტომატურად გაიყოს მითითებულ თანხებად ან პროცენტებად და გადაირიცხოს შესაბამის IBAN ანგარიშებზე. დამატებით იხ. [თანხის გაყოფის დეტალები](../split-payment) - `config.split.split_payments` — array თანხის გაყოფის ტრანზაქციების მასივი. თითოეული ობიექტი შეიცავს ერთი გადარიცხვის დეტალებს. - `config.split.split_payments[].iban` — string, required მიმღების ანგარიშის ნომერი IBAN ფორმატში, რომელზეც უნდა გადაირიცხოს გაყოფილი თანხა. - `config.split.split_payments[].amount` — number, required კონკრეტული თანხა, რომელიც უნდა გადაირიცხოს. თანხის ჯამი არ უნდა აღემატებოდეს შეკვეთის ძირითად თანხას. - `config.split.split_payments[].percent` — number, required პროცენტი შეკვეთის ძირითადი თანხიდან, რომელიც უნდა გადაირიცხოს. პროცენტების ჯამი არ უნდა აღემატებოდეს 100-ს. დასაშვებია მხოლოდ დადებითი რიცხვითი მნიშვნელობები 1-დან 100-მდე. - `config.split.split_payments[].description` — string გადარიცხვის დანიშნულება/აღწერა. :::note amount და percent ველების ერთდროულად მითითება ერთ ობიექტში დაუშვებელია. split_payments მასივის თითოეული ობიექტი სავალდებულოდ უნდა შეიცავდეს iban ველს და amount ან percent ველს. ::: **Standard Order** ```bash curl -X POST 'https://api.bog.ge/payments/v1/ecommerce/orders' \ -H 'Accept-Language: ka' \ -H 'Authorization: Bearer ' \ -H 'Content-Type: application/json' \ --data-raw '{ "callback_url": "https://example.com/callback", "external_order_id": "id123", "purchase_units": { "currency": "GEL", "total_amount": 1, "basket": [ { "quantity": 1, "unit_price": 1, "product_id": "product123" } ] }, "redirect_urls": { "fail": "https://example.com/fail", "success": "https://example.com/success" } }' ``` **With Account Tag** ```bash curl -X POST 'https://api.bog.ge/payments/v1/ecommerce/orders' \ -H 'Accept-Language: ka' \ -H 'Authorization: Bearer ' \ -H 'Content-Type: application/json' \ --data-raw '{ "callback_url": "https://example.com/callback", "external_order_id": "id123", "purchase_units": { "currency": "GEL", "total_amount": 1, "basket": [ { "quantity": 1, "unit_price": 1, "product_id": "product123" } ] }, "redirect_urls": { "fail": "https://example.com/fail", "success": "https://example.com/success" }, "config": { "account": { "tag": "category1" } } }' ``` **With Split Payment** ```bash curl -X POST 'https://api.bog.ge/payments/v1/ecommerce/orders' \ -H 'Accept-Language: ka' \ -H 'Authorization: Bearer ' \ -H 'Content-Type: application/json' \ --data-raw '{ "callback_url": "https://example.com/callback", "external_order_id": "id123", "purchase_units": { "currency": "GEL", "total_amount": 1, "basket": [ { "quantity": 1, "unit_price": 1, "product_id": "product123" } ] }, "redirect_urls": { "fail": "https://example.com/fail", "success": "https://example.com/success" }, "config": { "split": { "split_payments": [ { "amount": 0.30, "iban": "GE00BG0000000000000123", "description": "Split1" }, { "amount": 0.20, "iban": "GE00BG0000000000000321", "description": "Split2" } ] } } }' ``` **With Installment** ```bash curl -X POST 'https://api.bog.ge/payments/v1/ecommerce/orders' \ -H 'Accept-Language: ka' \ -H 'Authorization: Bearer ' \ -H 'Content-Type: application/json' \ --data-raw '{ "callback_url": "https://example.com/callback", "external_order_id": "id123", "purchase_units": { "currency": "GEL", "total_amount": 45, "basket": [ { "quantity": 1, "unit_price": 45, "product_id": "product123" } ] }, "redirect_urls": { "fail": "https://example.com/fail", "success": "https://example.com/success" }, "payment_method": [ "bog_loan" //"bnpl" ], "config":{ "loan":{ "type":"standard", //"zero" for bnpl "month":3 } } }' ``` ### Response - `id` — string ონლაინ გადახდის იდენტიფიკატორი. - `_links` — object ვებრესურსის მისამართები, რომლებიც გადახდის პროცესის შემდგომ ეტაპებზე გამოიყენება. ამჟამად ბრუნდება ორი რესურსი: - `_links.details.href` — string გადახდის დეტალების მისამართი, რომლის გამოძახებითაც შეგიძლიათ, გაიგოთ ინფორმაცია ონლაინ გადახდის შესახებ. - `_links.redirect.href` — string ვებგვერდის მისამართი, რომელზეც უნდა გადავიდეს მომხმარებელი პლასტიკური ბარათის ან ონლაინბანკინგის მონაცემების შესაყვანად და გადახდის პროცესის დასასრულებლად. **RESPONSE** ```json { "id": "{order_id}", "_links": { "details": { "href": "https://api.bog.ge/payments/v1/receipt/{order_id}" }, "redirect": { "href": "https://payment.bog.ge/?order_id={order_id}" } } } ``` --- # გადახდების დეტალების მიღება Source: https://api.bog.ge/docs/payments/standard-process/get-payment-details მეთოდის საშუალებით, ბიზნესს აქვს შესაძლებლობა, მიიღოს დეტალური ინფორმაცია ონლაინ გადახდის შესახებ, მისი იდენტიფიკატორის მიხედვით. ### Header-ის პარამეტრები - `Authorization` — Basic , required გადაეცემა `Bearer ` მნიშვნელობა, სადაც `jwt_token` არის აუტენტიფიკაციის მეთოდის Response-ის access_token პარამეტრში დაბრუნებული მნიშვნელობა. ### Path პარამეტრები - `order_id` — string, required შეკვეთის იდენტიფიკატორი, რომელიც ონლაინ მაღაზიას უბრუნდება შეკვეთის მოთხოვნის Response-ში. **CURL** ```bash curl -X GET 'https://api.bog.ge/payments/v1/receipt/:order_id' \ -H 'Authorization: Bearer ' ``` ## Response - `order_id` — string ონლაინ გადახდის იდენტიფიკატორი. - `industry` — string ბიზნესის ინდუსტრია, რომელიც მისი რეგისტრაციის დროს განისაზღვრება. - `capture` — string ავტორიზაციის მეთოდი. ყოველთვის - `automatic`. ტრანზაქციის ტიპი ორი შესაძლო მნიშვნელობით: - `automatic` - სტანდარტული ორდერი - `manual` - პრეავტორიზაციის ორდერი - `external_order_id` — string გადახდის იდენტიფიკატორი ბიზნესის სისტემიდან. გადმოცემული მნიშვნელობის პირველი 25 სიმბოლო აისახება გადახდის დანიშნულებაში, როგორც გადამხდელის ამონაწერში, ისე კომპანიის ანგარიშზე თანხის ჩარიცხვის დანიშნულებაში. - `client` — object ბიზნესის ინფორმაცია. - `client.id` — string ბიზნესის იდენტიფიკატორი ბანკის სისტემაში. - `client.brand_ka` — string ბიზნესის ქართული დასახელება. - `client.brand_en` — string ბიზნესის ინგლისური დასახელება. - `client.url` — string ბიზნესის ვებგვერდის მისამართი. - `zoned_create_date` — string შეკვეთის შექმნის თარიღი მსოფლიო კოორდინირებული დროით ( UTC), "YYYY-MM-DDTHH:MM:SS.ssssssZ" ფორმატში. - `zoned_expire_date` — string შეკვეთის ვადის გასვლის თარიღი მსოფლიო კოორდინირებული დროით (UTC), "YYYY-MM-DDTHH:MM:SS.ssssssZ" ფორმატში. - `order_status` — object შეკვეთის სტატუსი. - `order_status.key` — string სტატუსი იღებს შემდეგ მნიშვნელობებს: - `created` - გადახდის მოთხოვნა შექმნილია - `processing` - გადახდა მუშავდება - `completed` - გადახდის პროცესი დასრულდა წარმატებით - `rejected` - გადახდის პროცესი დასრულდა წარუმატებლად - `refund_requested` - მოთხოვნილია თანხის დაბრუნება - `refunded` - გადახდის თანხა დაბრუნებულია - `refunded_partially` - გადახდის თანხა ნაწილობრივ დაბრუნებულია - `auth_requested` - პრეავტორიზირებული გადახდა მოთხოვნილია - `blocked` - პრეავტორიზირებული გადახდის პროცესი დასრულდა წარმატებით, თუმცა თანხა ჯერ დაბლოკილია და ელოდება დადასტურებას - `partial_completed` - პრეავტორიზირებული გადახდა ნაწილობრივ თანხაზე წარმატებით დადასტურდა - `order_status.value` — string აღწერა. - `buyer` — object მყიდველის ინფორმაცია. - `buyer.full_name` — string მყიდველის სრული სახელი. - `buyer.email` — string მყიდველის ელ. ფოსტის მისამართი. - `buyer.phone_number` — string მყიდველის ტელეფონის ნომერი. - `purchase_units` — object ინფორმაცია შესყიდული პროდუქციის შესახებ. - `purchase_units.request_amount` — string შეკვეთის მოთხოვნილი თანხა. - `purchase_units.transfer_amount` — string შეკვეთის დამუშავებული თანხა. - `purchase_units.refund_amount` — string დაბრუნებული თანხა. - `purchase_units.currency_code` — string ვალუტა. - `purchase_units.items` — array შეძენილი პროდუქტების/სერვისების მასივი. - `purchase_units.items[].external_item_id` — string პროდუქტის/სერვისის იდენტიფიკატორი ბიზნესის სისტემაში. - `purchase_units.items[].description` — string პროდუქტის/სერვისის დასახელება (აღწერა). - `purchase_units.items[].quantity` — string თითოეული პროდუქტის/სერვისის რაოდენობა (მოცულობა). - `purchase_units.items[].unit_price` — string პროდუქტის/სერვისის ერთეულის ფასი. - `purchase_units.items[].unit_discount_price` — string აქციით გადახდის შემთხვევაში, შესყიდული პროდუქტის/სერვისის ერთეულის დაკლებული თანხის მოცულობა. - `purchase_units.items[].vat` — string პროდუქტის/სერვისის დამატებული ღირებულების გადასახადი (დღგ). - `purchase_units.items[].vat_percent` — string პროდუქტის/სერვისის დამატებული ღირებულების გადასახადის (დღგ) პროცენტი. - `purchase_units.items[].total_price` — string მთლიანი თანხა. - `purchase_units.items[].package_code` — string პროდუქტის კოდი. - `purchase_units.items[].tin` — string საგადასახადო საიდენტიფიკაციო ნომერი (TIN). - `purchase_units.items[].pinfl` — string გადამხდელის კოდი (PINFL). - `purchase_units.basket[].product_discount_id` — string პროდუქტის ფასდაკლების იდენტიფიკატორი. თუ მოწოდებული მნიშვნელობით ბანკში დარეგისტრირებულია ფასდაკლების აქცია, ფასდაკლების პირობების გათვალისწინებით, შეკვეთაზე გავრცელდება შესაბამისი აქცია. - `redirect_links` — object ბიზნესის ვებგვერდები, რომლებზეც შესაძლოა გადამისამართდეს მომხმარებელი ონლაინ გადახდის სისტემიდან, ოპერაციის დასრულების შემდეგ. - `redirect_links.fail` — string ვებმისამართი ოპერაციის წარუმატებლად დასრულების შემთხვევაში. - `redirect_links.success` — string ვებმისამართი ოპერაციის წარმატებით დასრულების შემთხვევაში. - `payment_detail` — object გადახდის დეტალები. - `payment_detail.transfer_method` — object გადახდის მეთოდი. - `payment_detail.transfer_method.key` — string გადახდის მეთოდი იღებს შემდეგ მნიშვნელობებს: - `card` - საბანკო ბარათით გადახდა - `google_pay` - Google Pay-ით გადახდა - `apple_pay` - Apple Pay-ით გადახდა - `bog_p2p` - საქართველოს ბანკის, ინტერნეტ ან მობაილ ბანკის მომხმარებლით გადარიცხვა - `bog_loyalty` - საქართველოს ბანკის ქულებით MR/Plus გადახდა - `bnpl` - ნაწილ-ნაწილით გადახდა - `bog_loan` - სტანდარტული საბანკო განვადება. - `payment_detail.transfer_method.value` — string აღწერა. - `payment_detail.transaction_id` — string ტრანზაქციის იდენტიფიკატორი. - `payment_detail.auth_code` — string გადახდის ავტორიზაციის იდენტიფიკატორი. მნიშვნელობა ასევე აისახება კომპანიის ანგარიშზე ანგარიშსწორების ამონაწერში. - `payment_detail.payer_identifier` — string გადამხდელის იდენტიფიკატორი, transfer_method-ის მიხედვით იღებს სხვა და სხვა მნიშვნელობას: - `card`/`google_pay` – ბრუნდება ბარათის დაშიფრული ნომერი (PAN) - `apple_pay` – ბრუნდება Apple-ის მიერ მინიჭებული ბარათის ნომერი, რომელიც უნიკალურია ყველა მოწყობილობისთვის - `bog_p2p`/`bog_loyalty` – ბრუნდება ანგარიშის სახელი - `bog_loan`/`bnpl` – ბრუნდება მომხმარებლის სახელი და გვარის პირველი ასო. - `payment_detail.payment_option` — string გადახდის გზა. შესაძლებელია დაბრუნდეს შემდეგი მნიშვნელობები: - `direct_debit` - ბარათით გადახდა - `recurrent` - დამახსოვრებული ბარათით გადახდა - `subscription` - დამახსოვრებული ბარათით ავტომატური ჩამოჭრა. - `payment_detail.card_type` — string იმ ბარათის ტიპი, რომლითაც მოხდა გადახდა. პარამეტრი მნიშვნელობას იღებს საბარათე გადახდის დროს: - `amex` - American Express - `mc` - Mastercard - `visa` - Visa. - `payment_detail.card_expiry_date` — string იმ ბარათის ვადის გასვლის თარიღი (თვე/წელი), რომლითაც მოხდა გადახდა. პარამეტრი მნიშვნელობას იღებს საბარათე გადახდის დროს. - `payment_detail.request_account_tag` — string ელ.კომერციის POS ტერმინალის შეკვეთაში მოთხოვნილი იდენტიფიკატორი - `payment_detail.transfer_account_tag` — string ელ.კომერციის იმ POS ტერმინალის იდენტიფიკატორი, რომელზეც შესრულდა გადახდა. - `payment_detail.saved_card_type` — string დამახსოვრებული ბარათის ტიპი. შესაძლო მნიშვნელობებია: - `recurrent` - ბარათი დამახსოვრებულია კლიენტის მიერ ინცირებული მომავალი გადახდისთვის. - `subscription` - ბარათი დამახსოვრებულია ავტომატური გადახდებისთვის ფიქსირებული თანხითა და დეტალებით. - `payment_detail.parent_order_id` — string თუ გადახდა მოხდა დამახსოვრებული ბარათით, აღნიშნულ ველში მითითებულია დამახსოვრებული ბარათის შეკვეთის იდენტიფიკატორი. - `payment_detail.code` — string გადახდის Response კოდი. - `payment_detail.code_description` — string გადახდის Response კოდის აღწერა. - `payment_detail.auth_code` — string საბარათე, Google Pay-ით ან Apple Pay-ით გადახდის ავტორიზაციის კოდი. - `discount` — object ინფორმაცია ფასდაკლების შესახებ, რომელიც გავრცელდა გადახდაზე - `discount.bank_discount_amount` — string ბანკის მიერ გავრცელებული ფასდაკლების თანხა - `discount.bank_discount_desc` — string ბანკის მიერ გავრცელებული ფასდაკლების აღწერა - `discount.system_discount_amount` — string საბარათე სისტემის მიერ გავრცელებული ფასდაკლების თანხა - `discount.system_discount_desc` — string საბარათე სისტემის მიერ გავრცელებული ფასდაკლების აღწერა - `discount.discounted_amount` — string თანხა ფასდაკლების შემდეგ - `discount.original_order_amount` — string საწყისი თანხა - `actions` — array შეკვეთასთან დაკავშირებული ქმედებების სია. - `actions[].action_id` — string ქმედების იდენტიფიკატორი. - `actions[].request_channel` — string წყარო, რომლიდანაც მოხდა ქმედების ინიციარება: - `public_api` - ონლაინ გადახდების API - `business_manager` - ბიზნეს მენეჯერის გვერდი - `support` - საქართველოს ბანკის შიდა სისტემა. - `actions[].action` — string ქმედების ტიპი: - `authorize` - პრეავტორიზირებული გადახდის დადასტურება - `partial_authorize` - პრეავტორიზირებული გადახდის დადასტურება არასრულ თანხაზე - `cancel_authorize` - პრეავტორიზირებული გადახდის უარყოფა - `refund` - თანხის დაბრუნება - `partial_refund` - თანხის ნაწილობრივი დაბრუნება. - `actions[].status` — string ქმედების სტატუსი: - `completed` - ქმედება დასრულდა წარმატებით - `rejected` - ქმედება დასრულდა წარმუმატებლად - `actions[].code` — string მოქმედების response კოდი. მოქმედების Response კოდების სია იხ. [აქ](../response-codes#მოქმედების-response-კოდები). - `actions[].code_description` — string მოქმედების response კოდის აღწერა. - `actions[].zoned_action_date` — string ქმედების ინიცირების თარიღი მსოფლიო კოორდინირებული დროით (UTC), "YYYY-MM-DDTHH:MM:SS.ssssssZ" ფორმატში. - `actions[].amount` — string თანხის მოცულობა, რომელზეც განხორციელდა ქმედება. - `lang` — string ონლაინ გადახდების გვერდზე გადამისამართების შემდეგ, რა ენის ინტერფეისი დახვდება მომხმარებელს. იღებს ორ მნიშვნელობას: - `ka` - ქართული - `en` - ინგლისური. - `reject_reason` — string გადახდის წარუმატებლად დასრულების მიზეზი. პარამეტრი მნიშვნელობას იღებს მხოლოდ მაშინ, თუ შეკვეთა წარუმატებლად დასრულდა ("order_status": "rejected"). იღებს შემდეგ მნიშვნელობებს: - `expiration` - შეკვეთას გაუვიდა ვადა - `unknown` - დაუდგენელი მიზეზი. - `გადახდის Response კოდის აღწერა` - ბარათით, Google pay-ით ან Apple pay-ით ინიცირებული გადახდების უარყოფის მიზეზი. Response კოდების სია იხილეთ [აქ](https://api.bog.ge/docs/docs/payments/response-codes). - `split` — object თანხის გაყოფის სტატუსისა და დეტალების ობიექტი. - `split.split_status` — string თანხის გაყოფის მოთხოვნის სტატუსი. შესაძლო მნიშვნელობები: - `created` - მოთხოვნა შექმნილია - `processing` - მოთხოვნა მუშავდება - `canceled` - მოთხოვნა გაუქმებულია - `completed` - მოთხოვნა წარმატებით შესრულდა - `rejected` - მოთხოვნა ვერ შესრულდა - `split.currency` — string თანხის გაყოფის ვალუტა (მაგ. GEL). - `split.request_channel` — string არხი, საიდანაც მოხდა თანხის გაყოფის ინიცირება. **RESPONSE** ```json { "order_id": "a767a276-cddd-43ec-9db3-9f9b39eee02d", "industry": "ecommerce", "capture": "automatic", "external_order_id": "123456", "client": { "id": "10000", "brand_ka": "საქართველოს ბანკი", "brand_en": "BOG", "url": "https://api.bog.ge" }, "create_date": "2022-11-01T13:19:43.021178", "zoned_create_date": "2022-11-01T13:19:43.021178Z", "expire_date": "2022-11-01T13:39:43.021178", "zoned_expire_date": "2022-11-01T13:39:43.021178Z", "order_status": { "key": "refunded", "value": "დაბრუნებული" }, "buyer": { "full_name": "John Doe", "email": "johndoe@gmail.com", "phone_number": "+995555000000" }, "purchase_units": { "request_amount": "100.5", "transfer_amount": "0.0", "refund_amount": "100.5", "currency_code": "GEL", "items": [ { "external_item_id": "id_1", "description": "product 1", "quantity": "1", "unit_price": "25.35", "unit_discount_price": "0", "vat": "0", "vat_percent": "0", "total_price": "25.35", "package_code": "A000123", "tin": null, "pinfl": null, "product_discount_id": "BF222R5" } ] }, "redirect_links": { "success": "https://payment.bog.ge/receipt?order_id=a767a276-cddd-43ec-9db3-9f9b39eee02d", "fail": "https://payment.bog.ge/receipt?order_id=a767a276-cddd-43ec-9db3-9f9b39eee02d" }, "payment_detail": { "transfer_method": { "key": "card", "value": "ბარათით გადახდა" }, "code": "100", "code_description": "Successful payment", "transaction_id": "230513868679", "payer_identifier": "548888xxxxxx9893", "payment_option": "direct_debit", "card_type": "mc", "card_expiry_date": "03/24", "request_account_tag": "1212", "transfer_account_tag": "gev2", "saved_card_type": "recurrent", "parent_order_id": "8d52130d-cb1b-45ea-b048-0f040a44e2a3", "pg_trx_id": "K4T2XMAZ9EBVQ3WN", "auth_code": "483921" }, "discount": { "bank_discount_amount": "string", "bank_discount_desc": "string", "discounted_amount": "string", "original_order_amount": "string", "system_discount_amount": "string", "system_discount_desc": "string" }, "actions": [ { "action_id": "b70968ca-eda9-47ae-8811-26fd1ab733f8", "request_channel": "public_api", "action": "authorize", "status": "completed", "action_date": "2022-11-28T13:42:40.668439", "zoned_action_date": "2022-11-28T13:42:40.668439Z", "amount": "100.5", "code": null, "code_description": null }, { "action_id": "a89b872a-9700-4025-b3fb-047cbba7a5e6", "request_channel": "business_manager", "action": "refund", "status": "completed", "action_date": "2022-11-28T13:58:03.427939", "zoned_action_date": "2022-11-28T13:58:03.427939Z", "amount": "100.5", "code": null, "code_description": null } ], "disputes": null, "split": null, "lang": "ka", "reject_reason": null } ``` --- # Callback Source: https://api.bog.ge/docs/payments/standard-process/callback Callback-ი არის ასინქრონული, server-to-server შეტყობინება, რომელიც ონლაინ გადახდების სისტემიდან თქვენს მიერ მითითებულ Callback URL მისამართზე იგზავნება. მისი მიზანია, საიმედოდ გაცნობოთ ტრანზაქციის საბოლოო სტატუსის შესახებ. სინქრონული API მოთხოვნებისგან განსხვავებით, სადაც ბიზნესის აპლიკაცია ითხოვს ინფორმაციას და ელოდება მყისიერ პასუხს, Callback-ის პროცესი ფონურ რეჟიმში მიმდინარეობს. ონლაინ გადახდების სისტემა ავტომატურად გამოაგზავნის POST მოთხოვნას ბიზნესის Callback URL-ზე, როდესაც გადახდა ან მასთან დაკავშირებული მოქმედება დასრულდება (წარმატებით ან წარუმატებლად), როგორიცაა თანხის ნაწილობრივი ან სრული დაბრუნება, პრეავტორიზაციის დადასტურება, თანხის გაყოფა. Callback-ის მიღებისა და დამუშავების ლოგიკა, მათ შორის მისი ხელმოწერის ვალიდაცია, ბიზნესის მხარეს უნდა იყოს იმპლემენტირებული. Callback-ის სათანადოდ დამუშავება კრიტიკულად მნიშვნელოვანი ნაბიჯია გადახდის სტატუსის დასადასტურებლად და ბიზნესის სისტემაში შეკვეთის უსაფრთხოდ განახლებისთვის. შეკვეთის მოთხოვნის დროს გადმოცემულ callback_url მისამართზე იგზავნება POST მეთოდით გადახდის დეტალები. პასუხის წარმატებით მიღების დასადასტურებლად, ბიზნესმა უნდა დააბრუნოს HTTP CODE 200. თუ ბიზნესმა წარმატებით ვერ მიიღო Callback, გადახდის სტატუსის გადასამოწმებლად და თავის სისტემაში შეკვეთის სტატუსის სწორად ასახვისთვის, უნდა გამოიყენოს [გადახდის დეტალების მიღების](https://api.bog.ge/docs/payments/standard-process/get-payment-details) მეთოდი. :::note **Callback და Redirect URL სხვადასხვა მიზანს ემსახურება:** **Redirect URL** - გადახდის დასრულების შემდეგ მომხმარებელს გადაამისამართებს ონლაინ გადახდის გვერდიდან ბიზნესის ვებგვერდზე, რაც აუმჯობესებს მომხმარებლის გამოცდილებას. თუმცა, ეს არ წარმოადგენს გადახდის საბოლოო სტატუსის გარანტიას, რადგან გადამისამართება შესაძლოა ვერ განხორციელდეს მომხმარებლის ქმედებების ან სხვა გარემოებების გამო. ამიტომ გადახდის დასრულების დადასტურება აუცილებელია server-to-server Callback-ის გამოყენებით. **Callbacks** - უზრუნველყოფს გადახდის სტატუსის დადასტურებას და გადახდის შესახებ ინფორმაციის უსაფრთხო მიწოდებას ონლაინ გადახდის სისტემის სერვერიდან ბიზნესის სერვერზე. Redirect URL-ისგან განსხვავებით, callback-ის მიღება არ არის დამოკიდებული მომხმარებლის ქმედებებზე და წარმოადგენს გადახდის სტატუსის შესახებ ინფორმაციის მიღების სანდო წყარო. ::: # Request ### Header-ის პარამეტრები - `Callback-Signature` — string ხელმოწერა დაგენერირებულია callback-ის request body-ზე `private key`-ით `SHA256withRSA` ალგორითმის გამოყენებით. იმისათვის, რომ ბიზნესი დარწმუნდეს callback-ში გადმოცემული ინფორმაციის ვალიდურობაში, request body-ისა და `public key`-ის დახმარებით უნდა დაავერიფიციროს ხელმოწერა. ვერიფიკაცია უნდა მოხდეს payload-ის დესერიალიზაციამდე, იმისათვის რომ request body-ის პარამეტრების თანმიმდევრობა დარჩეს უცვლელი. **PUBLIC KEY** ```bash -----BEGIN PUBLIC KEY----- MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAu4RUyAw3+CdkS3ZNILQh zHI9Hemo+vKB9U2BSabppkKjzjjkf+0Sm76hSMiu/HFtYhqWOESryoCDJoqffY0Q 1VNt25aTxbj068QNUtnxQ7KQVLA+pG0smf+EBWlS1vBEAFbIas9d8c9b9sSEkTrr TYQ90WIM8bGB6S/KLVoT1a7SnzabjoLc5Qf/SLDG5fu8dH8zckyeYKdRKSBJKvhx tcBuHV4f7qsynQT+f2UYbESX/TLHwT5qFWZDHZ0YUOUIvb8n7JujVSGZO9/+ll/g 4ZIWhC1MlJgPObDwRkRd8NFOopgxMcMsDIZIoLbWKhHVq67hdbwpAq9K9WMmEhPn PwIDAQAB -----END PUBLIC KEY----- ``` ### Body-ს პარამეტრები - `event` — string ქოლბექის ტიპი. მნიშვნელობა ყოველთვის არის `order_payment`. - `zoned_request_time` — string ქოლბექის გამოგზავნის თარიღი მსოფლიო კოორდინირებული დროით (UTC), "YYYY-MM-DDTHH:MM:SS.ssssssZ" ფორმატში. - `body` — object შეკვეთის მონაცემები. მოიცავს იმავე ველებს, რასაც შეიცავს [გადახდის დეტალები](https://api.bog.ge/docs/payments/standard-process/get-payment-details#response). **REQUEST BODY** ```json { "event": "order_payment", "zoned_request_time": "2022-11-23T18:06:37.240559Z", "body": { "order_id": "a767a276-cddd-43ec-9db3-9f9b39eee02d", "industry": "ecommerce", ... } } ``` --- # მომავალი გადახდებისთვის Source: https://api.bog.ge/docs/payments/saved-card/recurrent ბანკი ბიზნესს აძლევს საშუალებას, მომხმარებლის თანხმობის საფუძველზე, დაიმახსოვროს მისი ბარათი, რათა შემდგომში მომხმარებელმა შეძლოს, ბარათის მონაცემების მითითების გარეშე გადაიხადოს შეკვეთის საფასური. ამისთვის, ბიზნესმა შეკვეთის მოთხოვნის შემდეგ, გადახდების გვერდზე მომხმარებლის გადამისამართებამდე, უნდა გამოიძახოს შესაბამისი მეთოდი და გადასცეს მას შეკვეთის იდენტიფიკატორი. თუ მოცემულ შეკვეთაზე წარმატებით შესრულდება საბარათე გადახდა, შემდგომი შეკვეთების მოთხოვნისას ამავე იდენტიფიკატორის გამოყენებას შეძლებთ. ### Header-ის პარამეტრები - `Authorization` — Basic , required გადაეცემა `Bearer ` მნიშვნელობა, სადაც `jwt_token` არის აუტენტიფიკაციის მეთოდის Response-ის access_token პარამეტრში დაბრუნებული მნიშვნელობა. - `Idempotency-Key` — UUID v4 Idempotency-Key პარამეტრი უნდა იყოს უნიკალური ყველა ახალი API რექვესთისთვის. იმავე API-ზე Idempotency-Key-ის განმეორებით გამოყენებისას სერვერი დააბრუნებს იმავე სტატუს კოდსა და body-ს, რაც თავდაპირველი მოთხოვნისას. ეს ფუნქცია განსაკუთრებით სასარგებლოა თანმიმდევრული შედეგის უზრუნველსაყოფად, როდესაც საქმე გვაქვს ქსელური პრობლემებითა ან ხელახალი ცდებით გამოწვეულ დუბლირებულ მოთხოვნებთან. ### Path პარამეტრები - `order_id` — string, required შეკვეთის იდენტიფიკატორი, რომელიც ბრუნდება შეკვეთის მოთხოვნის Response-ში. ### Response - `Http Status: ` — 202 ACCEPTED მოთხოვნა მიღებულია. **CURL** ```bash curl -X PUT 'https://api.bog.ge/payments/v1/orders/:order_id/cards' \ -H 'Authorization: Bearer ' ``` --- # ავტომატური გადახდებისთვის Source: https://api.bog.ge/docs/payments/saved-card/offline ბანკი ბიზნესს აძლევს საშუალებას, მომხმარებლის თანხმობის საფუძველზე, დაიმახსოვროს მისი ბარათი, რათა შემდგომში შეძლოს ჩამოაჭრას თანხა ავტომატურად, მომხმარებლის მონაწილეობის გარეშე. ამისთვის, ბიზნესმა შეკვეთის მოთხოვნის შემდეგ, გადახდების გვერდზე მომხმარებლის გადამისამართებამდე, უნდა გამოიძახოს შესაბამისი მეთოდი და გადასცეს მას შეკვეთის იდენტიფიკატორი. თუ მოცემულ შეკვეთაზე წარმატებით შესრულდება საბარათე გადახდა, შემდგომი შეკვეთების მოთხოვნისას ამავე იდენტიფიკატორის გამოყენებას შეძლებთ. ### Header-ის პარამეტრები - `Authorization` — Basic , required გადაეცემა `Bearer ` მნიშვნელობა, სადაც `jwt_token` არის აუტენტიფიკაციის მეთოდის Response-ის access_token პარამეტრში დაბრუნებული მნიშვნელობა. - `Idempotency-Key` — UUID v4 Idempotency-Key პარამეტრი უნდა იყოს უნიკალური ყველა ახალი API რექვესთისთვის. იმავე API-ზე Idempotency-Key-ის განმეორებით გამოყენებისას სერვერი დააბრუნებს იმავე სტატუს კოდსა და body-ს, რაც თავდაპირველი მოთხოვნისას. ეს ფუნქცია განსაკუთრებით სასარგებლოა თანმიმდევრული შედეგის უზრუნველსაყოფად, როდესაც საქმე გვაქვს ქსელური პრობლემებითა ან ხელახალი ცდებით გამოწვეულ დუბლირებულ მოთხოვნებთან. ### Path პარამეტრები - `order_id` — string, required შეკვეთის იდენტიფიკატორი, რომელიც ბრუნდება შეკვეთის მოთხოვნის Response-ში. ### Response - `Http Status: ` — 202 ACCEPTED მოთხოვნა მიღებულია. **CURL** ```bash curl -X PUT 'https://api.bog.ge/payments/v1/orders/:order_id/subscriptions' \ -H 'Authorization: Bearer ' ``` --- # დამახსოვრებული ბარათის წაშლა Source: https://api.bog.ge/docs/payments/saved-card/delete მეთოდის საშუალებით ბიზნესს შეუძლია, წაშალოს დამახსოვრებული ბარათი. ### Header-ის პარამეტრები - `Authorization` — Basic , required გადაეცემა `Bearer ` მნიშვნელობა, სადაც `jwt_token` არის აუტენტიფიკაციის მეთოდის Response-ის access_token პარამეტრში დაბრუნებული მნიშვნელობა. - `Idempotency-Key` — UUID v4 Idempotency-Key პარამეტრი უნდა იყოს უნიკალური ყველა ახალი API რექვესთისთვის. იმავე API-ზე Idempotency-Key-ის განმეორებით გამოყენებისას სერვერი დააბრუნებს იმავე სტატუს კოდსა და body-ს, რაც თავდაპირველი მოთხოვნისას. ეს ფუნქცია განსაკუთრებით სასარგებლოა თანმიმდევრული შედეგის უზრუნველსაყოფად, როდესაც საქმე გვაქვს ქსელური პრობლემებითა ან ხელახალი ცდებით გამოწვეულ დუბლირებულ მოთხოვნებთან. ### Path პარამეტრები - `order_id` — string, required შეკვეთის იდენტიფიკატორი, რომელზეც თავდაპირველად მოხდა ბარათის დამახსოვრება. ### Response - `Http Status: ` — 202 ACCEPTED მოთხოვნა მიღებულია. **CURL** ```bash curl -X DELETE 'https://api.bog.ge/payments/v1/charges/card/:order_id' \ -H 'Authorization: Bearer ' ``` --- # დამახსოვრებული ბარათით გადახდა Source: https://api.bog.ge/docs/payments/saved-card/recurrent-payment მეთოდის საშუალებით ბიზნესს შეუძლია, მომხმარებელს გადაახდევინოს ბანკის ვებ-გვერდზე ბარათის მონაცემების მითითების გარეშე. მეთოდის გამოყენება მიზანშეწონილია, თუ მომხმარებელს რომელიმე წინა წარმატებული საბარათე გადახდის დროს დამახსოვრებული ჰქონდა ბარათი შემდგომი გადახდებისთვის. ### Path პარამეტრები - `parent_order_id` — string, required შეკვეთის იდენტიფიკატორი, რომელზეც მოხდა ბარათის დამახსოვრება შემდგომი გადახდებისთვის. :::note `Header`, `Body` და `Response` იგივეა, რაც [შეკვეთის მოთხოვნის](https://api.bog.ge/docs/payments/standard-process/create-order) დროს. ::: **CURL** ```bash curl -X POST 'https://api.bog.ge/payments/v1/ecommerce/orders/:parent_order_id' \ -H 'Accept-Language: ka' \ -H 'Authorization: Bearer ' \ -H 'Content-Type: application/json' \ --data-raw '{ "callback_url": "https://example.com/callback", "purchase_units": { "total_amount": 1, "basket": [ { "quantity": 1, "unit_price": 1, "product_id": "product123" } ] } }' ``` --- # დამახსოვრებული ბარათით ავტომატური ჩამოჭრა Source: https://api.bog.ge/docs/payments/saved-card/offline-payment მეთოდის საშუალებით, ბიზნესს შეუძლია მომხმარებელს თანხა ჩამოაჭრას მისი მონაწილეობის გარეშე. მეთოდის გამოყენება მიზანშეწონილია, თუ მომხმარებელს რომელიმე წინა წარმატებული საბარათე გადახდის დროს დამახსოვრებული ჰქონდა ბარათი ავტომატური ჩამოჭრისთვის. ### Header-ის პარამეტრები - `Content-Type` — application/json, required - `Authorization` — Basic , required გადაეცემა `Bearer ` მნიშვნელობა, სადაც `jwt_token` არის აუტენტიფიკაციის მეთოდის Response-ის access_token პარამეტრში დაბრუნებული მნიშვნელობა. - `Idempotency-Key` — UUID v4 Idempotency-Key პარამეტრი უნდა იყოს უნიკალური ყველა ახალი API რექვესთისთვის. იმავე API-ზე Idempotency-Key-ის განმეორებით გამოყენებისას სერვერი დააბრუნებს იმავე სტატუს კოდსა და body-ს, რაც თავდაპირველი მოთხოვნისას. ეს ფუნქცია განსაკუთრებით სასარგებლოა თანმიმდევრული შედეგის უზრუნველსაყოფად, როდესაც საქმე გვაქვს ქსელური პრობლემებითა ან ხელახალი ცდებით გამოწვეულ დუბლირებულ მოთხოვნებთან. ### Path პარამეტრები - `parent_order_id` — string, required შეკვეთის იდენტიფიკატორი, რომელზეც მოხდა ბარათის დამახსოვრება თანხის ავტომატური ჩამოჭრისთვის. ### Body-ს პარამეტრები - `callback_url` — string ბიზნესის ვებმისამართი, რომელსაც ავტომატურად გამოიძახებს ბანკი, ოპერაციის დასრულების შემდეგ, მისთვის გადახდის მონაცემების მიწოდების მიზნით (Callback-ის დროს). არ გადმოცემის შემთხვევაში, გამოიყენება `parent_order_id`-ის შესაბამისი შეკვეთის შექმნისას გადმოცემული მნიშვნელობა. - `external_order_id` — string გადახდის იდენტიფიკატორი ბიზნესის სისტემიდან (მაგალითად: შესყიდვების კალათის იდენტიფიკატორი). არ გადმოცემის შემთხვევაში, გამოიყენება `parent_order_id`-ის შესაბამისი შეკვეთის შექმნისას გადმოცემული მნიშვნელობა. :::note რაც შეეხება დანარჩენ პარამეტრებს (თანხა, ვალუტა, მყიდველის ინფორმაცია და სხვ.), რომლებიც საჭიროა შეკვეთის მოთხოვნისთვის, სისტემა ავტომატურად გამოიყენებს parent_order_id-ის შესაბამისი შეკვეთის შექმნისას გადმოცემულ მნიშვნელობებს. ::: **CURL** ```bash curl -X POST 'https://api.bog.ge/payments/v1/ecommerce/orders/:parent_order_id/subscribe' \ -H 'Authorization: Bearer ' \ -H 'Content-Type: application/json' ``` ### Response - `id` — string ონლაინ გადახდის იდენტიფიკატორი. - `_links` — object ვებრესურსის მისამართები, რომლებიც გადახდის პროცესის შემდგომ ეტაპებზე გამოიყენება. - `_links.details.href` — string გადახდის დეტალების მისამართი, რომლის გამოძახებითაც შეგიძლიათ, გაიგოთ ინფორმაცია ონლაინ გადახდის შესახებ. **RESPONSE** ```json { "id": "{order_id}", "_links": { "details": { "href": "https://api.bog.ge/payments/v1/receipt/{order_id}" } } } ``` --- # შესავალი Source: https://api.bog.ge/docs/payments/preauthorization/introduction მეთოდები საშუალებას გაძლევთ, დაასრულოთ [შეკვეთის მოთხოვნისას](https://api.bog.ge/docs/payments/standard-process/create-order) დაბლოკილი თანხის ჩამოჭრის პროცესი. მეთოდი აქტუალურია, მაშინ, როდესაც, შეკვეთის მოთხოვნისას, `capture` ველის მნიშვნელობა იყო `"manual"`. გადახდის დასრულებას აქვს სამი მეთოდი: თანხის სრული დადასტურება, ნაწილობრივი დადასტურება და უარყოფა. [პრეავტორიზაციის დადასტურება](https://api.bog.ge/docs/payments/preauthorization/approve) [პრეავტორიზაციის უარყოფა](https://api.bog.ge/docs/payments/preauthorization/reject) --- # პრეავტორიზაციის დადასტურება Source: https://api.bog.ge/docs/payments/preauthorization/approve დადასტურების სერვისი მოიცავს თანხის, როგორც სრულ, ისე ნაწილოვრივ დადასტურებას. ### Header-ის პარამეტრები - `Content-Type` — application/json, required - `Authorization` — Basic , required გადაეცემა `Bearer ` მნიშვნელობა, სადაც `jwt_token` არის აუტენტიფიკაციის მეთოდის `Response-ის access_token` პარამეტრში დაბრუნებული მნიშვნელობა. - `Idempotency-Key` — UUID v4 Idempotency-Key პარამეტრი უნდა იყოს უნიკალური ყველა ახალი API რექვესთისთვის. იმავე API-ზე Idempotency-Key-ის განმეორებით გამოყენებისას სერვერი დააბრუნებს იმავე სტატუს კოდსა და body-ს, რაც თავდაპირველი მოთხოვნისას. ეს ფუნქცია განსაკუთრებით სასარგებლოა თანმიმდევრული შედეგის უზრუნველსაყოფად, როდესაც საქმე გვაქვს ქსელური პრობლემებითა ან ხელახალი ცდებით გამოწვეულ დუბლირებულ მოთხოვნებთან. ### Path პარამეტრები - `order_id` — string, required შეკვეთის იდენტიფიკატორი, რომელიც ონლაინ მაღაზიას უბრუნდება შეკვეთის მოთხოვნის Response-ში. ### Body-ს პარამეტრები - `amount` — number დადასტურების ტიპის განმსაზღვრელი პარამეტრი. ზუსტი თანხის გამოგზავნის შემთხვევაშიც სრული დადასტურება ხდება, ხოლო ნაწილობრივ თანხის დროს ამ თანხაზე დადასტურდება. თუ სერვისის არ გადაეცემა `amount`, ამ შემთხვევაში დადასტურება მოხდება მთლიან თანხაზე. - `description` — string დადასტურების მიზეზი. **CURL** ```bash curl -X POST 'https://api.bog.ge/payments/v1/payment/authorization/approve/:order_id' \ -H 'Authorization: Bearer ' \ -H 'Content-Type: application/json' \ --data-raw '{ "amount": "10.5", "description": "string" }' ``` ### Response - `key` — string API მოთხოვნის სტატუსის იდენტიფიკატორი. - `message` — string API მოთხოვნის სტატუსის აღწერა. - `action_id` — string ქმედების იდენტიფიკატორი. **RESPONSE** ```json { "key": "request_received", "message": "Pre-authorization payment approval request received", "action_id": "e786283f-dc7f-48ba-bb75-12857f5a43ad" } ``` --- # პრეავტორიზაციის უარყოფა Source: https://api.bog.ge/docs/payments/preauthorization/reject სრული თანხის უარყოფის მეთოდი ### Header-ის პარამეტრები - `Content-Type` — application/json, required - `Authorization` — Basic , required გადაეცემა `Bearer ` მნიშვნელობა, სადაც `jwt_token` არის აუტენტიფიკაციის მეთოდის `Response-ის access_token` პარამეტრში დაბრუნებული მნიშვნელობა. - `Idempotency-Key` — UUID v4 Idempotency-Key პარამეტრი უნდა იყოს უნიკალური ყველა ახალი API რექვესთისთვის. იმავე API-ზე Idempotency-Key-ის განმეორებით გამოყენებისას სერვერი დააბრუნებს იმავე სტატუს კოდსა და body-ს, რაც თავდაპირველი მოთხოვნისას. ეს ფუნქცია განსაკუთრებით სასარგებლოა თანმიმდევრული შედეგის უზრუნველსაყოფად, როდესაც საქმე გვაქვს ქსელური პრობლემებითა ან ხელახალი ცდებით გამოწვეულ დუბლირებულ მოთხოვნებთან. ### Path პარამეტრები - `order_id` — string, required შეკვეთის იდენტიფიკატორი, რომელიც ონლაინ მაღაზიას უბრუნდება შეკვეთის მოთხოვნის Response-ში. ### Body-ს პარამეტრები - `description` — string უარყოფის მიზეზი. **CURL** ```bash curl -X POST 'https://api.bog.ge/payments/v1/payment/authorization/cancel/:order_id' \ -H 'Authorization: Bearer ' \ -H 'Content-Type: application/json' \ --data-raw '{ "description": "string" }' ``` ### Response - `key` — string API მოთხოვნის სტატუსის იდენტიფიკატორი. - `message` — string API მოთხოვნის სტატუსის აღწერა. - `action_id` — string ქმედების იდენტიფიკატორი. **RESPONSE** ```json { "key": "request_received", "message": "Pre-authorization payment cancellation request received", "action_id": "aa9478c7-f82f-45a9-8a30-e7b4275b1224" } ``` --- # ონლაინ განვადების მოდალი Source: https://api.bog.ge/docs/payments/external-orders/modal :::info განვადების მოდალის ინტეგრაცია გჭირდებათ მხოლოდ იმ შემთხვევაში, თუ გსურთ მომხმარებელმა განვადების პირობები თქვენს გვერდზე აირჩიოს. ::: ## ნაწილ-ნაწილის ვიზუალური სახელმძღვანელო თუ გსურთ თქვენს გვერდზე განათავსოთ ნაწილ-ნაწილის გადახდის ღილაკი, ისარგებლეთ ნაწილ-ნაწილის ვიზუალური სახელმძღვანელოთი. გადმოსაწერად დააჭირეთ [ { e.preventDefault(); const link = document.createElement('a'); link.href = '/docs/bnpl-button-guideline.pdf'; link.download = 'bnpl-button-guideline.pdf'; document.body.appendChild(link); link.click(); document.body.removeChild(link); }}>აქ](https://api.bog.ge/docs/docs/bnpl-button-guideline.pdf). ## ონლაინ განვადების მოდალი ონლაინ განვადების პირობების ასარჩევად, სპეციალური მოდალი დავამზადეთ. მოდალი არის ერთგვარი სესხის კალკულატორი, სადაც მომხმარებელს საშუალება აქვს, კალათის ღირებულებიდან გამომდინარე, საორიენტაციო ყოველთვიური გადასახადი და წლიური საპროცენტო განაკვეთი ნახოს. იქიდან გამომდინარე, რომ პირობები ყოველთვის ინდივიდუალურია და საქართველოს ბანკსა და მერჩანტს შორის დადებულ ხელშეკრულებას ეყრდნობა, ასევე სააქციო პირობები (მათ შორის 0%-იანი განვადების პირობა) განსხვავდება სტანდარტული პირობებისგან, ამ ინფორმაციის მსესხებლისთვის მიწოდება მნიშვნელოვანია. ყველა ეს ინფორმაცია მოდალზე არის დატანილი, რაც მომხმარებელს უფრო მეტად ეხმარება გადაწყვეტილების მიღებაში. შესაბამისად, განვადების აქტივაციამდე საჭიროა ერთგვარი სესხის კალკულატორი, რომელიც დამოუკიდებელი მიკროსერვისია და მერჩანტის საიტზე [ინტეგრაცია სჭირდება](https://api.bog.ge/docs/docs/payments/authentication). "საქართველოს ბანკი" გთავაზობს კალკულატორის მზა SDK-ს, რომელიც თავსებადია ყველა მოწყობილობაზე (Desktop, Mobile, Tablet) და საჭიროებს მზა კოდის ფრაგმენტის დამატებას საიტზე. ![Online Installment Modal](../../assets/installment-modal.png) ### მაგალითი: ### ინტეგრაცია განვადების მოდალის SDK ინტეგრაციის დასაწყებათ, დააკოპირეთ კოდი HTML გვერდში. `{client_id}`-ის მაგივრად ჩასვით თქვენი client_id. ```html ``` --- ### მოდალის ჩვენება ონლაინ განვადების მოდალის საჩვენებლად, გამოიყენეთ `BOG.Calculator.open` მეთოდი. #### პარამეტრები - `amount` — number, required განვადების თანხა - `bnpl` — boolean პარამეტრით განისაზღვრება მომხმარებელს გამოუჩნდეს `სტანდარტული განვადება` ან/და `ნაწილ-ნაწილ გადახდა`. - `true` - მომხმარებელს გამოუჩნდება მხოლოდ ნაწილ-ნაწილ გადახდა - `false` - მომხმარებელს გამოუჩნდება მხოლოდ სტანდარტული განვადება - `undefined` | `null` - მომხამრებელს გამოუჩნდება ორივე მეთოდი. - `onClose` — function მეთოდი, რომელიც გამოიძახება SDK-ს მიერ მომხმარებლის მხრიდან მოდალის დახურვის შემთხვევაში. - `onRequest` — function მეთოდი, რომელიც გამოიძახება SDK-ს მიერ მომხმარებლის მიერ პირობების არჩევის შემდეგ. ამ დროს უნდა მოხდეს განვადების [შეკვეთის მოთხოვნა](https://api.bog.ge/docs/docs/payments/standard-process/create-order). უნდა დაისეტოს `config.loan` პარამეტრი. მეთოდს გადმოეცემა არგუმენტები: - `selected` - ობიექტი, რომელშიც გადმოეცემა მომხმარებლის მიერ არჩეული მონაცემები. - `amount` - ყოველთვე გადასახდელი თანხა - `month` - სესხის თვეების რაოდენობა - `discount_code` - ფასდაკლების კოდი - `successCb` - მეთოდი, რომელიც უნდა გამოიძახოთ, თუ გსურთ, რომ განვადების პროცესი SDK-მ გააგრძელოს. - `closeCb` - მეთოდი, რომელიც უნდა გამოიძახოთ, თუ გსურთ მოდალის დახურვა. - `onComplete` — function მეთოდი, რომელიც გამოიძახება SDK-ს მიერ ონლაინ განვადების პროცესის დასრულების შემდეგ. ამ დროს მომხმარებლის გადამისამართება ავტომატურად ხდება მერჩანტის წარმატების ლინკზე. თუ გსურთ, რომ არ მოხდეს გადამისამართება, მათოდში დააბრუნეთ `false` მნიშვნელობა (`return false;`). მეთოდს არტუმენტად გადმოეცემა ობიექტი, პარამეტრებით: - `redirectUrl` - ლინკი, სადაც უნდა გადამისამართდეს მომხარებელი. ### არსებობს პროცესის გაგრძელების ორი მეთოდი. 1. თუ გსურთ, რომ ონლაინ განვადების პროცესის გაგრძელება მოხდეს SDK-ს მიერ, `onRequest` მეთოდში, orderId-ის [გენერაციის შემდეგ](https://api.bog.ge/docs/docs/payments/standard-process/create-order), გამოიძახეთ `successCb`, რომელსაც გადასცემთ დაგენერირებულ `orderId` პარამეტრს. პროცესის დასრულების შემდეგ, გამოიძახება `onComplete` მეთოდი. 2. თუ SDK მხოლოდ კალკულატორისთვის გჭირდებათ და მომხმარებლის მიერ სასურველი პირობის არჩევის შემდეგ თქვენ თვითონ გააგრძელებინოთ მომხმარებელს პროცესი, `onRequest` მეთოდში დააბრუნეთ `false` მნიშვნელობა (`return false;`), რა დროსაც SDK პროცესს აღარ გააგრძელებს. ამ დროს მოდალი ღია რჩება. თუ გსურთ მოდალის დახურვა, გამოიყენეთ `closeCb` ან `Bog.Calculator.close()` მეთოდი ```js BOG.Calculator.open({ amount: 500, onClose: () => { // Modal close callback }, onRequest: (selected, successCb, closeCb) => { const { amount, month, discount_code } = selected; fetch('url-to-backend-api', { method: 'POST', body: JSON.stringify(selected) }) .then(response => response.json()) .then(data => successCb(data.orderId)) .catch(err => closeCb()); }, onComplete: ({redirectUrl}) => { return false; } }) ``` --- SDK ასევე საშუალებას გაძლევთ თქვენს საიტზე დაამატოთ საქართველოს ბანკის ღილაკი. მეთოდს გადაეცით DOM ელემენტი, სადაც გსურთ ღილაკის ჩასმა. ```html
``` --- # Google Pay™-ს ღილაკი ბიზნესის ვებგვერდზე Source: https://api.bog.ge/docs/payments/external-orders/external-googlepay # Google Pay™-ს ღილაკი ბიზნესის ვებგვერდზე თქვენს ვებგვერდზე Google Pay™-ის ღილაკის განთავსებისთვის საჭიროა რამდენიმე ეტაპის გავლა. პირველ რიგში, თქვენი საიტი უნდა აკმაყოფილებდეს Google-ის მოთხოვნებს. ვინაიდან Google Pay-ის ღილაკი თავსდება არა საქართველოს ბანკის გადახდების გვერდზე, არამედ თქვენს ვებგვერდზე, გარემოს დაკონფიგურირება დამოუკიდებლად მოგიწევთ. ინფორმაციის მისაღებად ეწვით [Google-ის კონფიგურაციის გვერდს](https://support.google.com/pay/business/answer/7684271?hl=en). :::note კონფიგურაციისას გამოიყენეთ მოცემული პარამეტრები: ```json { "type": "PAYMENT_GATEWAY", "parameters": { "gateway": "georgiancard", "gatewayMerchantId": "BCR2DN4TXKPITITV", } } ``` ::: ამ საფეხურების გავლის შემდგომ შეძლებთ, თქვენი გვერდიდან Google-ის ღილაკით საქართველოს ბანკის გადახდა განახორციელოთ. შეკვეთის მოთხოვნა ხდება სტანდარტულად, იხილეთ [სტანდარტული პროცესი - შეკვეთის მოთხოვნა](https://api.bog.ge/docs/payments/standard-process/create-order) აუცილებელია შეკვეთის მოთხოვნის [`Body`](https://api.bog.ge/docs/payments/standard-process/create-order#body-ს-პარამეტრები) შეიცავდეს შემდეგ პარამეტრებს: ```json "payment_method": ["google_pay"], "config": { "google_pay": { "external": true, "google_pay_token": "{token}" } } ``` - `config.google_pay.external` — boolean გადმოეცით მნიშვნელობა true, როდესაც ოპერაციას აინიცირებთ ბიზნესის ვებ გვერდზე განთავსებული Google Pay-ის ღილაკით. - `config.google_pay.token` — string სრულყოფილი string მნიშვნელობა, რომელიც წარმოადგენს Google Pay-ის დაკრიპტულ გადახდის დეტალებს. მნიშვნელობა უნდა გადმოეცეს სრულყოფილად, როგორი სახითაც მიიღეთ Google Pay SDK-სგან, ცვლილებების გარეშე. {{ "google_pay_token": "{\'signature\':\'MEQCIHFtDlqJcskQXbwyvJLZQqS1LzeFds3OPilG9VoYKoe6AiA/j3MnWYkc6wT6plqYzN/pOLw0fJNbDDoTiV9fBJj92g\\u003d\\u003d\',\'intermediateSigningKey\':{\'signedKey\':\'{\\\'keyValue\\\':\\\'MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEnU1Do/xUEVVpjx5FXghsVh/siuHraLfqlfo7Hzt5weEImxxFxNzkUt2QZ+J4G5ihPoLmtA4z6Q1OGUmMo/+nvg\\\\u003d\\\\u003d\\\',\\\'keyExpiration\\\':\\\'1729068602000\\\'}\',\'signatures\':[\'MEUCIQCnUz4WvOz1Yg/oykSTgnFS2xyXZo6EH4/ZV2EiFwguPAIgS6rOk2dnM9gwpbOrfOWe6U1RI8Jt6IuBkF9lReCzw7w\\u003d\']},\'protocolVersion\':\'ECv2\',\'signedMessage\':\'{\\\'encryptedMessage\\\':\\\'sfd8Jk/Ky21GjWrHRyD90sm8O/Jzv7EieX10nzlP/ZVns4XuY67bMwloqpWl+35bGrU7EvGy54noxN0UJSvRAGjHro+u7jWxWmH6xVoSJuvXlmSStzBxgJHkFRznxuKcQ/PiFrvk1gO5bnrkYw5ZG/5mMJApNnT/5OrakITD61G3rNJvzpQEGepbC7C5iWPMRsh/YUwzZLBmfvp8QlQa5BTpydPHMFdJ2giIH/O0x5x7XJ9NR6ZBz5WfhTKaZnwKke+OwNNEse+OlFBO9nKdgmuhI9dOisKTHrbGPmd9Be9s3WSyEY1PVcZ9lKHrhbNPsKETRE7Kz1i1nOLjoNBq/xYuZIjvdiBJQME9TbwP5bnOsQ25v8ZXmAXz/fMLOZ/3RHOG6YuIwWiUPrFNbCqPxloNtgnPaOge48f6AzgKIBlppl+jDcALc/5JAWg5JUlZuTrLrnxBQ9AoTohUguKJqGXcHdY6tFfSKUp74pC2qXig+thK8slFZXJvdkfR3ocTlQUvIwzAhjww7Pw7On+LQoObGPs7AP8BZfnGyxMmqqNmL1iv0OUoazUSNuwFPTsdb5poKPslE4gIfBWj6HuxDZuF1TiNsK6HM1mTwzmcEFCvqBoD7vTjaNBAXHtbgaqZOGbvQlpmL9DZZLm+IqlbFw==\',\'ephemeralPublicKey\':\'BH8rPohRm5PX1b7j3yJlGoOYmbCKsjzoYc1qrPHQOiNqD9Nr/YFJH0Dxo59vSmJ/saZTleDz7zQr3kUNNwe1dQ3Q==\',\'tag\':\'u/oNSfxGFSyoSZJfY7A2dJp7aA9pvTOvJLtzc8lmztk==\'}\'}" }} ### Response - `id` — string ონლაინ გადახდის იდენტიფიკატორი. - `status` — string შეკვეთის სტატუსი. - `order_details` — object შეკვეთის მონაცემები. მოიცავს იმავე ველებს, რასაც შეიცავს [გადახდის დეტალები](https://api.bog.ge/docs/payments/standard-process/get-payment-details#response). ბრუნდება იმ შემთხვევაში, თუ გადახდის პროცესი სრულდება 3DS აუთენთიფიკაციის გარეშე. - `_links` — object ვებრესურსის მისამართები, რომლებიც გადახდის პროცესის შემდგომ ეტაპებზე გამოიყენება. ამჟამად ბრუნდება შემდეგი რესურსი: - `_links.details.href` — string გადახდის დეტალების მისამართი, რომლის გამოძახებითაც შეგიძლიათ, გაიგოთ ინფორმაცია ონლაინ გადახდის შესახებ. - `_links.redirect.href` — string ვებგვერდის მისამართი, რომელზეც უნდა გადამისამართდეს მომხმარებელი 3DS აუთენთიფიკაციისთვის. ბრუნდება იმ შემთხვევაში, თუ კლიენტს ჩართული აქვს 3DS აუთენთიფიკაცია. **RESPONSE** ```json { "id": "{order_id}", "status": "completed", "order_details": {...}, "_links": { "details": { "href": "https://api.bog.ge/payments/v1/receipt/{order_id}" }, "redirect": { "href": "https://payment.bog.ge/api/3ds/post-form?fieldName={field_name}&fieldValue={field_value}&baseUrl={base_url}" } } } ``` --- # Apple Pay™-ს ღილაკი ბიზნესის ვებგვერდზე Source: https://api.bog.ge/docs/payments/external-orders/external-applepay # Apple Pay™-ს ღილაკი ბიზნესის ვებგვერდზე თქვენს ვებგვერდზე Apple Pay™-ის ღილაკის განთავსებისთვის საჭიროა რამდენიმე ეტაპის გავლა. პირველ რიგში, თქვენი საიტი უნდა აკმაყოფილებდეს [Apple-ის მოთხოვნებს](https://developer.apple.com/apple-pay/acceptable-use-guidelines-for-websites/). ვინაიდან Apple Pay-ის ღილაკი თავსდება არა საქართველოს ბანკის გადახდების გვერდზე, არამედ თქვენს ვებგვერდზე, გარემოს დაკონფიგურირება დამოუკიდებლად მოგიწევთ. ინფორმაციის მისაღებად ეწვით [Apple-ის კონფიგურაციის გვერდს](https://developer.apple.com/documentation/apple_pay_on_the_web/configuring_your_environment). განათავსეთ Apple Pay-ის ვალიდაციის სერტიფიკატი თქვენს ვებ გვერდზე. ჩამოტვირთეთ სერტიფიკატი [აქ](https://webstatic.bog.ge/apple-developer-merchantid-domain-association). გაეცანით სერტიფიკატის განთავსების [დეტალურ ინსტრუქციას](https://developer.apple.com/documentation/applepaywebmerchantregistrationapi/preparing_merchant_domains_for_verification). სერტიფიკატის განთავსების შემდეგ, გთხოვთ [ecommercemerchants@bog.ge](mailto:ecommercemerchants@bog.ge) ელ. ფოსტაზე გაგვიზიარეთ თქვენი API Public Key და ვებ-გვერდის მისამართი, რომელზეც გსურთ Apple Pay-ის ღილაკის განთავსება. ამ საფეხურების გავლის შემდგომ შეძლებთ, თქვენი გვერდიდან Apple-ის ღილაკით საქართველოს ბანკის გადახდა განახორციელოთ. შეკვეთის მოთხოვნა ხდება სტანდარტულად, იხილეთ [სტანდარტული პროცესი - შეკვეთის მოთხოვნა](https://api.bog.ge/docs/payments/standard-process/create-order) :::note აუცილებელია [`Body`](https://api.bog.ge/docs/payments/standard-process/create-order#body-ს-პარამეტრები) შეიცავდეს შემდეგ პარამტრებს: ```json "payment_method": ["apple_pay"], "config": { "apple_pay": { "external": true } } ``` ::: ### Response - `id` — string ონლაინ გადახდის იდენტიფიკატორი. - `result` — json Apple-ს მიერ გადახდის ინიცირებაზე დაბრუნებული დეტალები. - `_links` — object ვებრესურსის მისამართები, რომლებიც გადახდის პროცესის შემდგომ ეტაპებზე გამოიყენება. ამჟამად ბრუნდება შემდეგი რესურსი: - `_links.accept.href` — string გადახდის დადასტურების მისამართი, რომლის გამოძახებაც აუცილებელია Apple Pay გადახდის დასასრულებლად. **RESPONSE** ```json { "id": "{order_id}", "result": {...}, "_links": { "accept": { "href": "https://api.bog.ge/payments/v1/ecommerce/orders/{order_id}/payment" } } } ``` --- # Apple Pay™-ს გადახდის დადასტურება Source: https://api.bog.ge/docs/payments/external-orders/complete-external-applepay # Apple Pay™-ს გადახდის დადასტურება მოცემული სერვისის გამოძახება აუცილებელია თქვენს ვებგვერდზე განთავსებული Apple Pay™-ის ღილაკით ინიცირებული გადახდის დასასრულებლად. ### Header-ის პარამეტრები - `Content-Type` — application/json, required - `Authorization` — Basic , required გადაეცემა `Bearer ` მნიშვნელობა, სადაც `jwt_token` არის აუტენტიფიკაციის მეთოდის Response-ის access_token პარამეტრში დაბრუნებული მნიშვნელობა. - `Idempotency-Key` — UUID v4 Idempotency-Key პარამეტრი უნდა იყოს უნიკალური ყველა ახალი API რექვესთისთვის. იმავე API-ზე Idempotency-Key-ის განმეორებით გამოყენებისას სერვერი დააბრუნებს იმავე სტატუს კოდსა და body-ს, რაც თავდაპირველი მოთხოვნისას. ეს ფუნქცია განსაკუთრებით სასარგებლოა თანმიმდევრული შედეგის უზრუნველსაყოფად, როდესაც საქმე გვაქვს ქსელური პრობლემებითა ან ხელახალი ცდებით გამოწვეულ დუბლირებულ მოთხოვნებთან. ### Path პარამეტრები - `order_id` — string, required შეკვეთის იდენტიფიკატორი, რომელიც ბრუნდება შეკვეთის მოთხოვნის Response-ში. ### Body-ს პარამეტრები - `apple_pay_token` — string, required სრულყოფილი string მნიშვნელობა, რომელიც წარმოადგენს Apple Pay-ის დაკრიპტულ გადახდის დეტალებს. მნიშვნელობა უნდა გადმოეცეს სრულყოფილად, როგორი სახითაც მიიღეთ Apple Pay SDK-სგან, ცვლილებების გარეშე. **CURL** ```bash curl -X POST 'https://api.bog.ge/payments/v1/ecommerce/orders/{order_id}/payment' \ -H 'Authorization: Bearer ' \ -H 'Content-Type: application/json' \ --data-raw '{ "apple_pay_token": "{\"token\":{\"paymentData\":{\"version\":\"EC_v1\"\"data\":\"V2VyIGRhc3MgRGFjaCBkZXIgdW5hdXRob3Jpc2llcnRlbiBWZXJicmVpdHVuZyB2b24gSW5mb3JtYXRpb25lbiBvZGVyIGRpZSBFcnN0ZWxsdW5nIHZvbiBLb3BpZW4gdW50ZXJzdMS8dHp0LCBtYWNodCBzaWNoIHN0cmFmYmFyLg==\",\"signature\":\"AGCSqGSIb3DQEHAqCAMIACAQExDTALBglghkgBZCrO6415UsR9xueflw3rEpZbft7zFVf19mAAAAAAAA\",\"header\":{\"publicKeyHash\":\"9mD12E4bF8dFlIF2k2ga/sD/ybcWraQH3aTx+RBDvVA4=\",\"ephemeralPublicKey\":\"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEGgfNfekFa1APW38avqjSzB+2mAq5hw3nXiQp51ZNwsMpB6H6YPQ26hZ78bnJdJvCqYYDiZaaa05tQLrXli09mg==\",\"transactionId\":\"f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2\"}},\"transactionIdentifier\":\"f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2\",\"paymentMethod\":{\"type\":\"PKPaymentMethodTypeCredit\",\"displayName\":\"Visa 1234\",\"network\":\"Visa\"}}}"; }' ``` ### Response - `id` — string ონლაინ გადახდის იდენტიფიკატორი. - `status` — string შეკვეთის სტატუსი. - `order_details` — object შეკვეთის მონაცემები. მოიცავს იმავე ველებს, რასაც შეიცავს [გადახდის დეტალები](https://api.bog.ge/docs/payments/standard-process/get-payment-details#response). - `_links` — object ვებრესურსის მისამართები, რომლებიც გადახდის პროცესის შემდგომ ეტაპებზე გამოიყენება. ამჟამად ბრუნდება შემდეგი რესურსი: - `_links.details.href` — string გადახდის დეტალების მისამართი, რომლის გამოძახებითაც შეგიძლიათ, გაიგოთ ინფორმაცია ონლაინ გადახდის შესახებ. **RESPONSE** ```json { "id": "{order_id}", "status": "completed", "order_details": {...}, "_links": { "details": { "href": "https://api.bog.ge/payments/v1/receipt/{order_id}" } } } ``` --- # თანხის დაბრუნება Source: https://api.bog.ge/docs/payments/refund ამ მეთოდის საშუალებით ბიზნესს შეუძლია სრულად ან ნაწილობრივ დააბრუნოს შეკვეთისას გადახდილი თანხა. ბარათით, Apple Pay-ით, Google Pay-ით, BOG ავტორიზაციითა და ქულებით შესრულებული გადახდების უკან დაბრუნება შესაძლებელია როგორც სრულად, ისე ნაწილობრივ. ნაწილობრივი დაბრუნების მეთოდის გამოძახება დასაშვებია მანამ, სანამ გადახდილი თანხა სრულად არ დაბრუნდება. ### Header-ის პარამეტრები - `Content-Type` — application/json, required - `Authorization` — Basic , required გადაეცემა `Bearer ` მნიშვნელობა, სადაც `jwt_token` არის აუტენტიფიკაციის მეთოდის Response-ის access_token პარამეტრში დაბრუნებული მნიშვნელობა. - `Idempotency-Key` — UUID v4 Idempotency-Key პარამეტრი უნდა იყოს უნიკალური ყველა ახალი API რექვესთისთვის. იმავე API-ზე Idempotency-Key-ის განმეორებით გამოყენებისას სერვერი დააბრუნებს იმავე სტატუს კოდსა და body-ს, რაც თავდაპირველი მოთხოვნისას. ეს ფუნქცია განსაკუთრებით სასარგებლოა თანმიმდევრული შედეგის უზრუნველსაყოფად, როდესაც საქმე გვაქვს ქსელური პრობლემებითა ან ხელახალი ცდებით გამოწვეულ დუბლირებულ მოთხოვნებთან. ### Path პარამეტრები - `order_id` — string, required შეკვეთის იდენტიფიკატორი, რომელიც ონლაინ მაღაზიას უბრუნდება შეკვეთის მოთხოვნის Response-ში. ### Body-ს პარამეტრები - `amount` — number დასაბრუნებელი თანხა. გადმოცემა აუცილებელია, თუ თანხა ბრუნდება ნაწილობრივად. პარამეტრის არ გადმოცემის შემთხვევაში, თანხა სრულად დაბრუნდება. მნიშვნელობა არ შეიძლება იყოს დამუშავებულ თანხაზე (transfer_amount) მეტი. **CURL** ```bash curl -X POST 'https://api.bog.ge/payments/v1/payment/refund/:order_id' \ -H 'Authorization: Bearer ' \ -H 'Content-Type: application/json' \ --data-raw '{ "amount": "10.5" }' ``` ### Response - `key` — string API მოთხოვნის სტატუსის იდენტიფიკატორი. - `message` — string API მოთხოვნის სტატუსის აღწერა. - `action_id` — string ქმედების იდენტიფიკატორი. **RESPONSE** ```json { "key": "request_received", "message": "Refund request received", "action_id": "5b666901-eb05-4f83-abeb-8311e175f337" } ``` --- # თანხის გაყოფა Source: https://api.bog.ge/docs/payments/split-payment ## თანხის გაყოფის დეტალები თანხის გაყოფის ფუნქციონალი გაძლევთ საშუალებას, შეკვეთიდან მიღებული თანხა მარტივად და ავტომატურად გაანაწილოთ თქვენს პარტნიორებს, სერვისის პროვაიდერებსა თუ მერჩანტებს შორის. ფუნქციონალი ხელმისაწვდომია მხოლოდ GEL ვალუტაში და შემდეგი Online გადახდის მეთოდებისთვის: - `card` - `google_pay` - `apple_pay` - `bog_loyalty` - `bog_p2p` თუ მომხმარებელი შეკვეთას გადაიხდის სხვა მეთოდით, თანხა სრულად ჩაირიცხება ძირითად ანგარიშსწორების ანგარიშზე და გაყოფა არ შესრულდება. ერთი შეკვეთის თანხის გაყოფა შესაძლებელია მაქსიმუმ 10 ნაწილად. ### წარმატებული გაყოფის პირობები: - ობიექტს გააქტიურებული უნდა ჰქონდეს თანხის გაყოფის ფუნქციონალი. - ობიექტის ძირითად ანგარიშსწორების ანგარიშზე უნდა იყოს საკმარისი ნაშთი ყველა გადარიცხვისა და საკომისიოს დასაფარად. - `iban` ველებში მითითებული ანგარიშები უნდა იყოს აქტიური, ადგილობრივი ბანკის და ეროვნულ ვალუტაში (GEL). - შეკვეთა გადახდილი უნდა იყოს ზემოთ ჩამოთვლილი ერთ-ერთი მეთოდით. თუ რომელიმე პირობა არ სრულდება, თანხის გაყოფის მთლიანი ოპერაცია წარუმატებელი იქნება და არცერთი გადარიცხვა არ შესრულდება. ## პრეავტორიზაციის დადასტურება პრეავტორიზაციის დადასტურებისას, მოთხოვნაში შესაძლებელია `split` ობიექტის გადმოცემა თანხის გასაყოფად. **მნიშვნელოვანია:** თუ პრეავტორიზაცია მხოლოდ ნაწილობრივ დასტურდება და გაყოფა ხდება ფიქსირებული თანხებით (`amount`), `split_payments` ობიექტებში მითითებული თანხების ჯამი არ უნდა აღემატებოდეს დასადასტურებელ თანხას. ## პრეავტორიზაციის გაუქმება პრეავტორიზაციის გაუქმებისას დამატებითი მოქმედებები არ არის საჭირო. ძირითადი ტრანზაქციის გაუქმებასთან ერთად, მასთან დაკავშირებული თანხის გაყოფის მოთხოვნაც ავტომატურად გაუქმდება და მიენიჭება `canceled` სტატუსი. ## გადახდის დაბრუნება შეკვეთის თანხის სრული ან ნაწილობრივი დაბრუნება (Refund) გავლენას არ ახდენს თანხის გაყოფის უკვე შესრულებულ ან მიმდინარე მოთხოვნაზე. გაყოფის ოპერაცია არ უქმდება და გადარიცხული თანხები უკან არ ბრუნდება. --- # Response კოდები Source: https://api.bog.ge/docs/payments/response-codes ## გადახდის Response კოდები | Code | აღწერა (EN) | აღწერა (GE) | |------|----------------------------------------------------------------------------------|----------------------------------------------------------------| | 100 | Successful payment | წარმატებული გადახდა | | 101 | Payment declined because card usage is limited. For detailed information, contact the card issuer bank | გადახდა უარყოფილია, რადგან ბარათის გამოყენება შეზღუდულია. დეტალური ინფორმაციისთვის დაუკავშირდით ბარათის მომსახურე ბანკს | | 102 | Saved card wasn't found | დამახსოვრებული ბარათი ვერ მოიძებნა | | 103 | Payment declined due to invalid card | გადახდა უარყოფილია, რადგან ბარათი არ არის ვალიდური | | 104 | Payment declined due to exceeding transaction limit | გადახდა უარყოფილია ტრანზაქციის რაოდენობის ლიმიტის გადაჭარბების გამო | | 105 | Payment declined because the card has expired | გადახდა უარყოფილია, რადგან ბარათი ვადაგასულია | | 106 | Payment declined due to exceeding the limit of the amount | გადახდა უარყოფილია თანხის ლიმიტის გადაჭარბების გამო | | 107 | Payment declined due to insufficient funds in the account | გადახდა უარყოფილია ანგარიშზე არასაკმარისი თანხის გამო | | 108 | Authentication Declined | გადახდის ავტორიზაციის უარყოფა | | 109 | Technical Issue | დაფიქსირდა ტექნიკური ხარვეზი | | 110 | Transaction Expired | ოპერაციის შესრულების დრო ამოიწურა | | 111 | Authentication timeout | გადახდის ავტორიზაციის დრო ამოიწურა | | 112 | General Error | საერთო შეცდომა | | 122 | Payment declined by the acquirer bank | გადახდა უარყოფილია მომსახურე ბანკის მიერ | | 199 | Unknown Response | უცნობი პასუხი | | 200 | Successful preauthorization | წარმატებული პრეავტორიზაცია | ## მოქმედების Response კოდები | Code | აღწერა (GE) | აღწერა (EN) | |------|----------------------------------------------------------------------------------|----------------------------------------------------------------| | 161 | თანხის დაბრუნება ვერ მოხერხდა. მეტი დეტალისთვის დაუკავშირდით ბარათის გამცემ ბანკს. | Refund could not be completed. Please contact the card issuing bank for more details. | | 162 | ბარათის გამცემი ბანკი უარყოფს თანხის დაბრუნებას. | The card issuing bank declined the refund. | | 163 | ანგარიშზე არ გაქვთ საკმარისი ნაშთი. | Not enough funds available in the account | | 164 | თანხის დაბრუნება ვერ მოხერხდა. მეტი დეტალისთვის დაუკავშირდით ბარათის გამცემ ბანკს. | Refund could not be completed. Please contact the card issuing bank for more details. | | 165 | თანხის დაბრუნება ვერ მოხერხდა. მეტი დეტალისთვის დაუკავშირდით ბარათის გამცემ ბანკს. | Refund could not be completed. Please contact the card issuing bank for more details. | | 166 | თანხის დაბრუნება ვერ მოხერხდა. მეტი დეტალისთვის დაუკავშირდით ბარათის გამცემ ბანკს. | Refund could not be completed. Please contact the card issuing bank for more details. | | 167 | ბარათი ვადაგასულია. დაუკავშირდით მომხმარებელს და დაუბრუნეთ თანხა აქტიურ ბარათზე. | Card expired. Contact the customer and refund the amount to an active card. | | 168 | თანხის დაბრუნება ვერ მოხერხდა. მეტი დეტალისთვის დაუკავშირდით ბარათის გამცემ ბანკს. | Refund could not be completed. Please contact the card issuing bank for more details. | | 169 | ბარათი ვადაგასულია ან მონაცემები არასწორია. გადაამოწმეთ ინფორმაცია მომხმარებელთან და თავიდან ცადეთ. | The card is expired or the details are incorrect. Please verify the information with the customer and try again. | | 179 | Unknown Response | Unknown Response | --- # Google Pay™ Source: https://api.bog.ge/docs/payments/googlepay # Google Pay ™ Google Pay ™ გაძლევთ საშუალებას მიიღოთ გადახდები მარტივად და სწრაფად, ისე რომ მომხმარებელს აღარ სჭირდება ბარათის დეტალების ჩაწერა. ბარათის მონაცემები უსაფრთხოდ ინახება Google-ის მიერ. გადახდის ეს მეთოდი ხელმისაწვდომია ყველა მოწყობილობისთვის (მობილური ტელეფონი/კომპიუტერი), განურჩევლად ვებ-ბრაუზერისა და ოპერაციულ სისტემისა. Google Pay™-ს გასააქტიურებლად შედით [ბიზნეს მენეჯერში](https://businessmanager.bog.ge/ka). გაითვალისწინეთ, რომ Google Pay™-ს გააქტიურებისას უნდა დაეთანხმოთ Google-ს [პირობებს](https://payments.developers.google.com/terms/sellertos). გააქტიურებისთანავე თქვენს მომხმარებლებს გადახდის გვერდზე გამოუჩნდებათ Google Pay ™-ს ღილაკი. საქართველოს ბანკი მხარს უჭერს როგორც “PAN only”, ისე “Cryptogram 3DS“ ავტორიზაციის მეთოდებს. თუ გადახდისთვის საჭიროა 3D უსაფრთხოება, ბანკი ავტომატურად იზრუნებს ამაზე. საქართველოს ბანკი მხარს უჭერს Visa, MasterCard და American Express-ის ბარათებს Google Pay ™-დან. Google Pay ™-ს გამოყენება უფასოა და გირჩევთ, რომ გამოიყენოთ ეს გადახდის მეთოდი თქვენი ტრანზაქციების რაოდენობის გასაზრდელად. --- # გამოყენებული ტერმინები Source: https://api.bog.ge/docs/payments/terms-used 1. ბიზნესი - საცალო ვაჭრობის ან მომსახურების კომპანია, რომელსაც გააჩნია ონლაინ/ელექტრონული სისტემა. 2. ონლაინ გადახდების გვერდი - ონლაინ გადახდების სისტემა, რომელიც საშუალებას გაძლევთ, მარტივად ჩააშენოთ გადახდების მოდული ნებისმიერი ტიპის ბიზნესში. 3. Callback - საბანკო სისტემიდან ბიზნესის მიერ გამოდგმული სერვისის გამოძახება, გადახდის შესახებ განახლებული ინფორმაციის მიწოდების მიზნით. 4. სისტემაში შესასვლელი რეკვიზიტები - ბანკის სისტემაში კლიენტის იდენტიფიკატორი (client_id) და საიდუმლო გასაღები (secret_key), რომელსაც ბანკი ანიჭებს კლიენტს, მისი ბიზნესად წარმატებით დარეგისტრირების შემდეგ. 5. ბარათის ნომერი (PAN) - პლასტიკური ბარათის წინა მხარეს გამოსახული 16 ციფრი. --- # აუტენტიფიკაცია Source: https://api.bog.ge/docs/payments-addons/authentication ## რა დამჭირდება გადახდის API-ს გამოსაყენებლად ონლაინ გადახდების API-ს გამოსაყენებლად საჭიროა აუტენტიფიკაცია [HTTP Basic Auth](https://en.wikipedia.org/wiki/Basic_access_authentication)-ის გამოყენებით. ამისთვის თქვენ დაგჭირდებათ, იცოდეთ სისტემაში შესასვლელი რეკვიზიტები (Credentials), რომელიც თითოეული ბიზნესისთვის უნიკალურია. რეკვიზიტები მოიცავს ორ პარამეტრს: client_id და client_secret, რომელიც გამოიყენება, როგორც username-ი და password-ი, ბიზნესის აუტენტიფიკაციისას. ## როგორ გავიგოთ ბიზნესის სისტემაში შესასვლელი რეკვიზიტები მას შემდეგ, რაც კომპანია დარეგისტრირდება ბიზნესად საბანკო სისტემაში და შეავსებს ყველა საჭირო მონაცემს, მას მიენიჭება და გადაეცემა სისტემაში შესასვლელი რეკვიზიტები client_id და client_secret. რეკვიზიტები ბიზნესის უნიკალური მაიდენტიფიცირებელია. ამასთან, client_secret პაროლის მნიშვნელობის პარამეტრია - მისი სხვა პირისთვის გადაცემა, გასაჯაროება, დაუშვებელია. ამან შეიძლება ბიზნესისთვის საფრთხის ალბათობა მნიშვნელოვნად გაზარდოს! client_secret-ის ცვლილება ბიზნესის მიერ შეუძლებელია. ## მეთოდის აღწერა მოცემული მეთოდის საშუალებით, ბიზნესი გადის აუტენტიფიკაციის პროცესს. გამოძახების შედეგად, ონლაინ გადახდების სერვერის მიერ ბრუნდება Bearer Token, რომელიც ყველა შემდგომი მეთოდის გამოძახებისთვის არის აუტენტიფიკაციისთვის აუცილებელი პარამეტრი. ### Header-ის პარამეტრები - `Content-Type` — application/x-www-form-urlencoded, required - `Authorization` — Basic , required გადაეცემა „Basic „ + „:“ მნიშვნელობა კოდირებული Base64 ფორმატში (მაგ: „Basic ODI4Mjo3Njk3MDY0OTlmMDcwOWUyMzQ4NDU4NjNmOThiMjMxNA==“), სადაც და არის ბანკის მიერ ბიზნესისთვის გადაცემული, სისტემაში შესვლისთვის საჭირო, რეკვიზიტები. ### Body-ს პარამეტრები - `grant_type` — client_credentials, required მნიშვნელობად გადაეცემა ფიქსირებული ტექსტი: `client_credentials` **CURL** ```bash curl -X POST 'https://oauth2.bog.ge/auth/realms/bog/protocol/openid-connect/token' \ -u {client_id}:{client_secret} \ -H 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'grant_type=client_credentials' ``` ### Response - `access_token` — string ავტორიზაციის სერვერის მიერ დაბრუნებული Token-ის მნიშვნელობა - `token_type` — string Token-ის ტიპი (ბრუნდება ტექსტური მნიშვნელობა - `Bearer`) - `expires_in` — number აბრუნებს რიცხვით მნიშვნელობას, თუ რამდენი წამის განმავლობაში არის აქტიური Token. **RESPONSE** ```json { "access_token": "", "token_type": "Bearer", "expires_in": 1634719923245 } ``` --- # თანხის შეტანა Source: https://api.bog.ge/docs/payments-addons/standard-process/create-top-up-order ამ მეთოდის საშუალებით ბიზნესი აინიცირებს თანხის შეტანის ოპერაციას და აგზავნის ტექნიკურ მახასიათებლებსა და გადასახდელ თანხას. ოპერაციის წარმატებით დასრულების შემთხვევაში, პროცესის გასაგრძელებლად, მომხმარებელი უნდა გადაამისამართოთ ონლაინ გადახდის გვერდზე, `_links` პარამეტრში დაბრუნებულ `redirect` მისამართზე. ### Header-ის პარამეტრები - `Content-Type` — application/json, required - `Authorization` — Basic , required გადაეცემა `Bearer ` მნიშვნელობა, სადაც `jwt_token` არის აუტენტიფიკაციის მეთოდის Response-ის access_token პარამეტრში დაბრუნებული მნიშვნელობა. - `Idempotency-Key` — UUID v4 Idempotency-Key პარამეტრი უნდა იყოს უნიკალური ყველა ახალი API რექვესთისთვის. იმავე API-ზე Idempotency-Key-ის განმეორებით გამოყენებისას სერვერი დააბრუნებს იმავე სტატუს კოდსა და body-ს, რაც თავდაპირველი მოთხოვნისას. ეს ფუნქცია განსაკუთრებით სასარგებლოა თანმიმდევრული შედეგის უზრუნველსაყოფად, როდესაც საქმე გვაქვს ქსელური პრობლემებითა ან ხელახალი ცდებით გამოწვეულ დუბლირებულ მოთხოვნებთან. - `Accept-Language` — string განსაზღვრავს ონლაინ გადახდების გვერდზე გადამისამართების შემდეგ, რა ენის ინტერფეისი დახვდება მომხმარებელს. იღებს ორ მნიშვნელობას: - `ka` - ქართული (default) - `en` - ინგლისური. - `Theme` — string განსაზღვრავს ონლაინ გადახდების გვერდზე გადამისამართების შემდეგ, რა თემის ინტერფეისი დახვდება მომხმარებელს. იღებს ორ მნიშვნელობას: - `light` - ღია (default) - `dark` - მუქი. ### Body-ს პარამეტრები - `application_type` — "web" | "mobile" აპლიკაციის ტიპი, საიდანაც ხდება შეკვეთის შექმნა. გამოიყენება Apple Pay-ით გადახდისას, როდესაც Apple Pay-ის ღილაკი განთავსებულია უშუალოდ მერჩანტის ვებ გვერდზე ან მობილურ აპლიკაციაში. აპლიკაციის ტიპის მნიშვნელობებია: - `web` - ვებ გვერდიდან შექმნილი შეკვეთის აპლიკაციის ტიპი. - `mobile` - მობილური აპლიკაციიდან შექმნილი შეკვეთის აპლიკაციის ტიპი. - `callback_url` — string, required ბიზნესის ვებმისამართი (აუცილებლად https ტიპის), რომელსაც ავტომატურად გამოიძახებს ბანკი, ოპერაციის დასრულების შემდეგ, ბიზნესისთვის გადახდის მონაცემების მიწოდების მიზნით (Callback-ის დროს). - `external_order_id` — string გადახდის იდენტიფიკატორი ბიზნესის სისტემიდან. გადმოცემული მნიშვნელობის პირველი 25 სიმბოლო აისახება გადახდის დანიშნულებაში, როგორც გადამხდელის ამონაწერში, ისე კომპანიის ანგარიშზე თანხის ჩარიცხვის დანიშნულებაში. - `money_units` — object, required შესასრულებელი ოპერაციის თანხა და ვალუტა. - `money_units.total_amount` — number, required შესასრულებელი ოპერაციის თანხა. - `money_units.currency` — string, required შესასრულებელი ოპერაციის ვალუტა. - `redirect_urls` — object ბიზნესის ვებმისამართები, რომლებზეც შესაძლოა, გადამისამართდეს მომხმარებელი ონლაინ გადახდის სისტემიდან ოპერაციის დასრულების შემდეგ. - `redirect_urls.success` — string ვებმისამართი, რომელზეც გადამისამართდება მომხმარებელი ოპერაციის წარმატებით დასრულების შემთხვევაში. მნიშვნელობის არ გადმოცემის შემთხვევაში მომხმარებელი დარჩება ონლაინ გადახდების გვერდზე და გამოუჩნდება შესაბამისი ქვითარი. - `redirect_urls.fail` — string ვებმისამართი, რომელზეც გადამისამართდება მომხმარებელი ოპერაციის წარუმატებლად დასრულების შემთხვევაში, მნიშვნელობის არ გადმოცემის შემთხვევაში მომხმარებელი დარჩება ონლაინ გადახდების გვერდზე და გამოუჩნდება შესაბამისი ქვითარი. - `ttl` — number შეკვეთის სიცოცხლის ხანგრძლივობა წუთებში (შეკვეთის შექმნიდან რამდენი წუთის განმავლობაში შეეძლება მომხმარებელს გადახდის შესრულება). მოცემული პარამეტრის ლოგიკა სხვა და სხვა ინდუსტრიის ბიზნესისთვის განსხვავებული შეიძლება იყოს. პარამეტრის მინიმალური შესაძლო მნიშვნელობაა `2`, მაქსიმალური კი - `1440` (24 საათი). პარამეტრის არ გადმოცემის შემთხვევაში სისტემა იგულისხმებს `15` წუთს. - `payment_method` — array გადახდის მეთოდები, რომლის გამოყენებასაც შეძლებს მომხმარებელი ამ შეკვეთაზე გადახდის განსახორციელებლად. აუცილებელია, ბიზნესს გააქტიურებული ჰქონდეს ყველა გადმოცემული მეთოდი. პარამეტრის არ გადმოცემის შემთხვევაში მომხმარებელს ონლაინ გადახდის გვერდზე გადამისამართების შემდეგ შეეძლება ყველა იმ გადახდის მეთოდით სარგებლობა, რომელიც გააქტიურებული აქვს ბიზნესს. შესაძლო მნიშვნელობები: - `card` - საბანკო ბარათით გადახდა - `apple_pay` - Apple Pay-ით და საბანკო ბარათით გადახდა (ამ მნიშვნელობის გადმოცემის შემთხვევაში, მომხმარებელს შეეძლება როგორც Apple Pay-ით, ასევე საბანკო ბარათით გადახდა. აუცილებელია, რომ ბიზნესს გააქტიურებული ჰქონდეს ორივე გადახდის მეთოდი) - `bog_p2p` - საქართველოს ბანკის, ინტერნეტ ან მობაილ ბანკის მომხმარებლით გადარიცხვა - `config` — object კონკრეტული გადახდის კონფიგურაცია. - `config.apple_pay` — object გადახდის კონფიგურაცია. პარამეტრის გადმოცემა აუცილებელია თუ გსურთ, რომ შეკვეთის გადახდა ბიზნესის ვებგვერდზე განთავსებული Apple Pay-ს ღილაკით მოხდეს. - `config.apple_pay.external` — boolean - `true` - გადახდა ინიცირდება ბიზნესის ვებგვერდზე განთავსებული Apple Pay-ს ღილაკით - `false` - გადახდა ხდება ბანკის გადახდების გვერდიდან (default) - `config.account` — object გადახდის კონფიგურაცია. პარამეტრის გადმოცემა აუცილებელია თუ თქვენთვის კონფიგურირებულია რამდენიმე ელ.კომერციის POS ტერმინალი ერთსადაიმავე ვალუტაში: შესრულებული ოპერაციები გსურთ დააჯგუფოთ ბიზნესის საჭიროებებიდან გამომდინარე ან ანგარიშსწორება შესრულდეს ბიზნესის სხვადასხვა ანგარიშზე. - `config.account.tag` — string ელ.კომერციის POS ტერმინალის იდენტიფიკატორი. თუ მოწოდებული tag-ის მნიშვნელობა არ ემთხვევა POS-ის კონფიგურაციას ან tag მოწოდებული არ არის, ოპერაცია შესრულდება default POS ტერმინალზე და შესაბამის ანგარიშსწორების ანგარიშზე. შენიშვნა: ტეგის მნიშვნელობის შეთანხმება აუცილებელია დამატებითი POS-ის კონფიგურირებისას. - `save_card` — string ბარათის დამახსოვრების მოთხოვნა. ველი გადმოეცემა იმ შემთხვევაში, თუ გსურთ გადახდისას გამოყენებული ბარათის დამახსოვრება. შესაძლო მნიშვნელობა: - `recurrent` - ბარათის დამახსოვრება მომავალი გადახდებისთვის. ბარათის დამახსოვრება მოხდება იმ შემთხვევაში, თუ მოთხოვნაზე საბარათე გადახდა წარმატებით შესრულდა. - `transaction_type` — string ოპერაციის ტიპის იდენტიფიკატორი. შესაძლო მნიშვნელობები: - `purchase` - სტანდარტული საბარათე გადახდა. - `aft` - ანგარიშზე ბალანსის შევსება. **CURL** ```bash curl -X POST 'https://api.bog.ge/payments/v1/funds-transfer/top-up' \ -H 'Accept-Language: ka' \ -H 'Authorization: Bearer ' \ -H 'Content-Type: application/json' \ --data-raw '{ "callback_url": "https://example.com/callback", "external_order_id": "id123", "money_units": { "currency": "string", "total_amount": 0 }, "redirect_urls": { "fail": "https://example.com/fail", "success": "https://example.com/success" } }' ``` ### Response - `id` — string ონლაინ გადახდის იდენტიფიკატორი. - `_links` — object ვებრესურსის მისამართები, რომლებიც გადახდის პროცესის შემდგომ ეტაპებზე გამოიყენება. ამჟამად ბრუნდება ორი რესურსი: - `_links.details.href` — string გადახდის დეტალების მისამართი, რომლის გამოძახებითაც შეგიძლიათ, გაიგოთ ინფორმაცია ონლაინ გადახდის შესახებ. - `_links.redirect.href` — string ვებგვერდის მისამართი, რომელზეც უნდა გადავიდეს მომხმარებელი პლასტიკური ბარათის ან ონლაინბანკინგის მონაცემების შესაყვანად და გადახდის პროცესის დასასრულებლად. **RESPONSE** ```json { "id": "{order_id}", "_links": { "details": { "href": "https://api.bog.ge/payments/v1/receipt/{order_id}" }, "redirect": { "href": "https://payment.bog.ge/?order_id={order_id}" } } } ``` --- # თანხის შეტანა დამახსოვრებული ბარათით Source: https://api.bog.ge/docs/payments-addons/standard-process/create-top-up-order-with-saved-card ამ მეთოდის საშუალებით ბიზნესი აინიცირებს თანხის შეტანის ოპერაციას მომხმარებლის დამახსოვრებული ბარათით და აგზავნის ტექნიკურ მახასიათებლებსა და გადასახდელ თანხას. ოპერაციის წარმატებით დასრულების შემთხვევაში, პროცესის გასაგრძელებლად, მომხმარებელი უნდა გადაამისამართოთ ონლაინ გადახდის გვერდზე, `_links` პარამეტრში დაბრუნებულ `redirect` მისამართზე. ### Path პარამეტრები - `parent_order_id` — string, required შეკვეთის იდენტიფიკატორი, რომელზეც მოხდა ბარათის დამახსოვრება შემდგომი გადახდებისთვის. :::note `Header`, `Body` და `Response` იგივეა, რაც [შეკვეთის მოთხოვნის](https://api.bog.ge/docs/payments-addons/standard-process/create-top-up-order) დროს. ::: **CURL** ```bash curl -X POST 'https://api.bog.ge/payments/v1/funds-transfer/top-up/:parent_order_id' \ -H 'Accept-Language: ka' \ -H 'Authorization: Bearer ' \ -H 'Content-Type: application/json' \ --data-raw '{ "callback_url": "https://example.com/callback", "external_order_id": "id123", "money_units": { "currency": "string", "total_amount": 0 }, "redirect_urls": { "fail": "https://example.com/fail", "success": "https://example.com/success" } }' ``` --- # დამახსოვრებული ბარათის წაშლა Source: https://api.bog.ge/docs/payments-addons/standard-process/delete მეთოდის საშუალებით ბიზნესს შეუძლია, წაშალოს დამახსოვრებული ბარათი. ### Header-ის პარამეტრები - `Authorization` — Basic , required გადაეცემა `Bearer ` მნიშვნელობა, სადაც `jwt_token` არის აუტენტიფიკაციის მეთოდის Response-ის access_token პარამეტრში დაბრუნებული მნიშვნელობა. - `Idempotency-Key` — UUID v4 Idempotency-Key პარამეტრი უნდა იყოს უნიკალური ყველა ახალი API რექვესთისთვის. იმავე API-ზე Idempotency-Key-ის განმეორებით გამოყენებისას სერვერი დააბრუნებს იმავე სტატუს კოდსა და body-ს, რაც თავდაპირველი მოთხოვნისას. ეს ფუნქცია განსაკუთრებით სასარგებლოა თანმიმდევრული შედეგის უზრუნველსაყოფად, როდესაც საქმე გვაქვს ქსელური პრობლემებითა ან ხელახალი ცდებით გამოწვეულ დუბლირებულ მოთხოვნებთან. ### Path პარამეტრები - `order_id` — string, required შეკვეთის იდენტიფიკატორი, რომელიც ბრუნდება თანხის შეტანის Response-ში. ### Response - `Http Status: ` — 202 ACCEPTED მოთხოვნა მიღებულია. **CURL** ```bash curl -X DELETE 'https://api.bog.ge/payments/v1/charges/card/:order_id' \ -H 'Authorization: Bearer ' ``` --- # თანხის გატანა Source: https://api.bog.ge/docs/payments-addons/standard-process/original-credit-transaction მეთოდის საშუალებით ბიზნესს შეუძლია, დააინიციროს თანხის გატანის ოპერაცია, მომხმარებლის მიერ უკვე დამახსოვრებულ ბარათზე. მეთოდის გამოყენება შესაძლებელია მხოლოდ იმ შემთხვევაში, თუ მომხმარებელს რომელიმე წინა წარმატებული საბარათე გადახდის დროს დამახსოვრებული ჰქონდა ბარათი. ### Header-ის პარამეტრები - `Content-Type` — application/json, required - `Authorization` — Basic , required გადაეცემა `Bearer ` მნიშვნელობა, სადაც `jwt_token` არის აუტენტიფიკაციის მეთოდის Response-ის access_token პარამეტრში დაბრუნებული მნიშვნელობა. - `Idempotency-Key` — UUID v4 Idempotency-Key პარამეტრი უნდა იყოს უნიკალური ყველა ახალი API რექვესთისთვის. იმავე API-ზე Idempotency-Key-ის განმეორებით გამოყენებისას სერვერი დააბრუნებს იმავე სტატუს კოდსა და body-ს, რაც თავდაპირველი მოთხოვნისას. ეს ფუნქცია განსაკუთრებით სასარგებლოა თანმიმდევრული შედეგის უზრუნველსაყოფად, როდესაც საქმე გვაქვს ქსელური პრობლემებითა ან ხელახალი ცდებით გამოწვეულ დუბლირებულ მოთხოვნებთან. - `Accept-Language` — string განსაზღვრავს ონლაინ გადახდების გვერდზე გადამისამართების შემდეგ, რა ენის ინტერფეისი დახვდება მომხმარებელს. იღებს ორ მნიშვნელობას: - `ka` - ქართული (default) - `en` - ინგლისური. - `Theme` — string განსაზღვრავს ონლაინ გადახდების გვერდზე გადამისამართების შემდეგ, რა თემის ინტერფეისი დახვდება მომხმარებელს. იღებს ორ მნიშვნელობას: - `light` - ღია (default) - `dark` - მუქი. ### Path პარამეტრები - `parent_order_id` — string, required შეკვეთის იდენტიფიკატორი, რომელზეც მოხდა ბარათის დამახსოვრება შემდგომი გადახდებისთვის. ### Body-ს პარამეტრები - `callback_url` — string, required ბიზნესის ვებმისამართი (აუცილებლად https ტიპის), რომელსაც ავტომატურად გამოიძახებს ბანკი, ოპერაციის დასრულების შემდეგ, ბიზნესისთვის გადახდის მონაცემების მიწოდების მიზნით (Callback-ის დროს). - `external_order_id` — string გადახდის იდენტიფიკატორი ბიზნესის სისტემიდან. - `money_units` — object, required შესასრულებელი ოპერაციის თანხა და ვალუტა. - `money_units.total_amount` — number, required შესასრულებელი ოპერაციის თანხა. - `money_units.currency` — string, required შესასრულებელი ოპერაციის ვალუტა. - `redirect_urls` — object ბიზნესის ვებმისამართები, რომლებზეც შესაძლოა, გადამისამართდეს მომხმარებელი ონლაინ გადახდის სისტემიდან ოპერაციის დასრულების შემდეგ. - `redirect_urls.success` — string ვებმისამართი, რომელზეც გადამისამართდება მომხმარებელი ოპერაციის წარმატებით დასრულების შემთხვევაში. მნიშვნელობის არ გადმოცემის შემთხვევაში მომხმარებელი დარჩება ონლაინ გადახდების გვერდზე და გამოუჩნდება შესაბამისი ქვითარი. - `redirect_urls.fail` — string ვებმისამართი, რომელზეც გადამისამართდება მომხმარებელი ოპერაციის წარუმატებლად დასრულების შემთხვევაში, მნიშვნელობის არ გადმოცემის შემთხვევაში მომხმარებელი დარჩება ონლაინ გადახდების გვერდზე და გამოუჩნდება შესაბამისი ქვითარი. **CURL** ```bash curl -X POST 'https://api.bog.ge/payments/v1/funds-transfer/payout/:parent_order_id' \ -H 'Accept-Language: ka' \ -H 'Authorization: Bearer ' \ -H 'Content-Type: application/json' \ --data-raw '{ "callback_url": "string", "external_order_id": "string", "money_units": { "currency": "string", "total_amount": 0 }, "redirect_urls": { "fail": "https://example.com/fail", "success": "https://example.com/success" } }' ``` ### Response - `id` — string ონლაინ გადახდის იდენტიფიკატორი. - `_links` — object ვებრესურსის მისამართები, რომლებიც გადახდის პროცესის შემდგომ ეტაპებზე გამოიყენება: - `_links.details.href` — string გადახდის დეტალების მისამართი, რომლის გამოძახებითაც შეგიძლიათ, გაიგოთ ინფორმაცია ონლაინ გადახდის შესახებ. **RESPONSE** ```json { "id": "{order_id}", "_links": { "details": { "href": "https://api.bog.ge/payments/v1/receipt/{order_id}" } } } ``` --- # თანხის დაბრუნება Source: https://api.bog.ge/docs/payments-addons/standard-process/refund ამ მეთოდის საშუალებით ბიზნესს შეუძლია სრულად ან ნაწილობრივ დააბრუნოს შეკვეთისას გადახდილი თანხა. ბარათით, Apple Pay-ით, და BOG ავტორიზაციით შესრულებული გადახდების უკან დაბრუნება შესაძლებელია როგორც სრულად, ისე ნაწილობრივ. ### Header-ის პარამეტრები - `Content-Type` — application/json, required - `Authorization` — Basic , required გადაეცემა `Bearer ` მნიშვნელობა, სადაც `jwt_token` არის აუტენტიფიკაციის მეთოდის Response-ის access_token პარამეტრში დაბრუნებული მნიშვნელობა. - `Idempotency-Key` — UUID v4 Idempotency-Key პარამეტრი უნდა იყოს უნიკალური ყველა ახალი API რექვესთისთვის. იმავე API-ზე Idempotency-Key-ის განმეორებით გამოყენებისას სერვერი დააბრუნებს იმავე სტატუს კოდსა და body-ს, რაც თავდაპირველი მოთხოვნისას. ეს ფუნქცია განსაკუთრებით სასარგებლოა თანმიმდევრული შედეგის უზრუნველსაყოფად, როდესაც საქმე გვაქვს ქსელური პრობლემებითა ან ხელახალი ცდებით გამოწვეულ დუბლირებულ მოთხოვნებთან. ### Path პარამეტრები - `order_id` — string, required შეკვეთის იდენტიფიკატორი, რომელიც ბრუნდება თანხის შეტანის Response-ში. ### Body-ს პარამეტრები - `amount` — number დასაბრუნებელი თანხა. გადმოცემა აუცილებელია, თუ თანხა ბრუნდება ნაწილობრივად. პარამეტრის არ გადმოცემის შემთხვევაში, თანხა სრულად დაბრუნდება. მნიშვნელობა არ შეიძლება იყოს დამუშავებულ თანხაზე (transfer_amount) მეტი. **CURL** ```bash curl -X POST 'https://api.bog.ge/payments/v1/payment/refund/:order_id' \ -H 'Authorization: Bearer ' \ -H 'Content-Type: application/json' \ --data-raw '{ "amount": "10.5" }' ``` ### Response - `key` — string API მოთხოვნის სტატუსის იდენტიფიკატორი. - `message` — string API მოთხოვნის სტატუსის აღწერა. - `action_id` — string ქმედების იდენტიფიკატორი. **RESPONSE** ```json { "key": "request_received", "message": "Refund request received", "action_id": "5b666901-eb05-4f83-abeb-8311e175f337" } ``` --- # გადახდების დეტალების მიღება Source: https://api.bog.ge/docs/payments-addons/standard-process/get-payment-details მეთოდის საშუალებით, ბიზნესს აქვს შესაძლებლობა, მიიღოს დეტალური ინფორმაცია ონლაინ გადახდის შესახებ, მისი იდენტიფიკატორის მიხედვით. ### Header-ის პარამეტრები - `Authorization` — Basic , required გადაეცემა `Bearer ` მნიშვნელობა, სადაც `jwt_token` არის აუტენტიფიკაციის მეთოდის Response-ის access_token პარამეტრში დაბრუნებული მნიშვნელობა. ### Path პარამეტრები - `order_id` — string, required შეკვეთის იდენტიფიკატორი, რომელიც ბრუნდება თანხის შეტანის ან თანხის გატანის response-ში. **CURL** ```bash curl -X GET 'https://api.bog.ge/payments/v1/receipt/:order_id' \ -H 'Authorization: Bearer ' ``` ## Response - `order_id` — string ონლაინ გადახდის იდენტიფიკატორი. - `industry` — string ბიზნესის ინდუსტრია, რომელიც მისი რეგისტრაციის დროს განისაზღვრება. - `external_order_id` — string გადახდის იდენტიფიკატორი ბიზნესის სისტემიდან. გადმოცემული მნიშვნელობის პირველი 25 სიმბოლო აისახება გადახდის დანიშნულებაში, როგორც გადამხდელის ამონაწერში, ისე კომპანიის ანგარიშზე თანხის ჩარიცხვის დანიშნულებაში. - `client` — object ბიზნესის ინფორმაცია. - `client.id` — string ბიზნესის იდენტიფიკატორი ბანკის სისტემაში. - `client.brand_ka` — string ბიზნესის ქართული დასახელება. - `client.brand_en` — string ბიზნესის ინგლისური დასახელება. - `client.url` — string ბიზნესის ვებგვერდის მისამართი. - `zoned_create_date` — string შეკვეთის შექმნის თარიღი მსოფლიო კოორდინირებული დროით ( UTC), "YYYY-MM-DDTHH:MM:SS.ssssssZ" ფორმატში. - `zoned_expire_date` — string შეკვეთის ვადის გასვლის თარიღი მსოფლიო კოორდინირებული დროით (UTC), "YYYY-MM-DDTHH:MM:SS.ssssssZ" ფორმატში. - `order_status` — object შეკვეთის სტატუსი. - `order_status.key` — string სტატუსი იღებს შემდეგ მნიშვნელობებს: - `created` - გადახდის მოთხოვნა შექმნილია - `processing` - გადახდა მუშავდება - `completed` - გადახდის პროცესი დასრულდა წარმატებით - `rejected` - გადახდის პროცესი დასრულდა წარუმატებლად - `refund_requested` - მოთხოვნილია თანხის დაბრუნება - `refunded` - გადახდის თანხა დაბრუნებულია - `refunded_partially` - გადახდის თანხა ნაწილობრივ დაბრუნებულია - `order_status.value` — string აღწერა. - `redirect_links` — object ბიზნესის ვებგვერდები, რომლებზეც შესაძლოა გადამისამართდეს მომხმარებელი ონლაინ გადახდის სისტემიდან, ოპერაციის დასრულების შემდეგ. - `redirect_links.fail` — string ვებმისამართი ოპერაციის წარუმატებლად დასრულების შემთხვევაში. - `redirect_links.success` — string ვებმისამართი ოპერაციის წარმატებით დასრულების შემთხვევაში. - `payment_detail` — object გადახდის დეტალები. - `payment_detail.transfer_method` — object გადახდის მეთოდი. - `payment_detail.transfer_method.key` — string გადახდის მეთოდი იღებს შემდეგ მნიშვნელობებს: - `card` - საბანკო ბარათით გადახდა - `apple_pay` - Apple Pay-ით გადახდა - `bog_p2p` - საქართველოს ბანკის, ინტერნეტ ან მობაილ ბანკის მომხმარებლით გადარიცხვა - `payment_detail.transfer_method.value` — string აღწერა. - `payment_detail.transaction_id` — string ტრანზაქციის იდენტიფიკატორი. - `payment_detail.auth_code` — string გადახდის ავტორიზაციის იდენტიფიკატორი. მნიშვნელობა ასევე აისახება კომპანიის ანგარიშზე ანგარიშსწორების ამონაწერში. - `payment_detail.payer_identifier` — string გადამხდელის იდენტიფიკატორი, transfer_method-ის მიხედვით იღებს სხვა და სხვა მნიშვნელობას: - `card` – ბრუნდება ბარათის დაშიფრული ნომერი (PAN) - `apple_pay` – ბრუნდება Apple-ის მიერ მინიჭებული ბარათის ნომერი, რომელიც უნიკალურია ყველა მოწყობილობისთვის - `bog_p2p` – ბრუნდება ანგარიშის სახელი - `payment_detail.payment_option` — string გადახდის გზა. შესაძლებელია დაბრუნდეს შემდეგი მნიშვნელობები: - `direct_debit` - ბარათით გადახდა - `recurrent` - დამახსოვრებული ბარათით გადახდა - `payment_detail.card_type` — string იმ ბარათის ტიპი, რომლითაც მოხდა გადახდა. პარამეტრი მნიშვნელობას იღებს საბარათე გადახდის დროს: - `amex` - American Express - `mc` - Mastercard - `visa` - Visa. - `payment_detail.card_expiry_date` — string იმ ბარათის ვადის გასვლის თარიღი (თვე/წელი), რომლითაც მოხდა გადახდა. პარამეტრი მნიშვნელობას იღებს საბარათე გადახდის დროს. - `payment_detail.request_account_tag` — string ელ.კომერციის POS ტერმინალის შეკვეთაში მოთხოვნილი იდენტიფიკატორი - `payment_detail.transfer_account_tag` — string ელ.კომერციის იმ POS ტერმინალის იდენტიფიკატორი, რომელზეც შესრულდა გადახდა. - `payment_detail.saved_card_type` — string დამახსოვრებული ბარათის ტიპი. შესაძლო მნიშვნელობებია: - `recurrent` - ბარათი დამახსოვრებულია კლიენტის მიერ ინცირებული მომავალი გადახდისთვის. - `payment_detail.parent_order_id` — string თუ გადახდა მოხდა დამახსოვრებული ბარათით, აღნიშნულ ველში მითითებულია დამახსოვრებული ბარათის შეკვეთის იდენტიფიკატორი. - `payment_detail.code` — string გადახდის Response კოდი. - `payment_detail.code_description` — string გადახდის Response კოდის აღწერა. - `actions` — array შეკვეთასთან დაკავშირებული ქმედებების სია. - `actions[].action_id` — string ქმედების იდენტიფიკატორი. - `actions[].request_channel` — string წყარო, რომლიდანაც მოხდა ქმედების ინიციარება: - `public_api` - ონლაინ გადახდების API - `business_manager` - ბიზნეს მენეჯერის გვერდი - `support` - საქართველოს ბანკის შიდა სისტემა. - `actions[].action` — string ქმედების ტიპი: - `refund` - თანხის დაბრუნება - `partial_refund` - თანხის ნაწილობრივი დაბრუნება. - `actions[].status` — string ქმედების სტატუსი: - `completed` - ქმედება დასრულდა წარმატებით - `rejected` - ქმედება დასრულდა წარმუმატებლად - `actions[].code` — string მოქმედების response კოდი. მოქმედების Response კოდების სია იხ. [აქ](../response-codes#მოქმედების-response-კოდები). - `actions[].code_description` — string მოქმედების response კოდის აღწერა. - `actions[].zoned_action_date` — string ქმედების ინიცირების თარიღი მსოფლიო კოორდინირებული დროით (UTC), "YYYY-MM-DDTHH:MM:SS.ssssssZ" ფორმატში. - `actions[].amount` — string თანხის მოცულობა, რომელზეც განხორციელდა ქმედება. - `lang` — string ონლაინ გადახდების გვერდზე გადამისამართების შემდეგ, რა ენის ინტერფეისი დახვდება მომხმარებელს. იღებს ორ მნიშვნელობას: - `ka` - ქართული - `en` - ინგლისური. - `reject_reason` — string გადახდის წარუმატებლად დასრულების მიზეზი. პარამეტრი მნიშვნელობას იღებს მხოლოდ მაშინ, თუ შეკვეთა წარუმატებლად დასრულდა ("order_status": "rejected"). იღებს შემდეგ მნიშვნელობებს: - `expiration` - შეკვეთას გაუვიდა ვადა - `unknown` - დაუდგენელი მიზეზი. - `გადახდის Response კოდის აღწერა` - ბარათით, Google pay-ით ან Apple pay-ით ინიცირებული გადახდების უარყოფის მიზეზი. Response კოდების სია იხილეთ [აქ](https://api.bog.ge/docs/docs/payments-addons/response-codes). **RESPONSE** ```json { "order_id": "a767a276-cddd-43ec-9db3-9f9b39eee02d", "industry": "ecommerce", "external_order_id": "123456", "client": { "id": "10000", "brand_ka": "საქართველოს ბანკი", "brand_en": "BOG", "url": "https://api.bog.ge" }, "zoned_create_date": "2022-11-01T13:19:43.021178Z", "zoned_expire_date": "2022-11-01T13:39:43.021178Z", "order_status": { "key": "refunded", "value": "დაბრუნებული" }, "purchase_units": { "request_amount": "100.5", "transfer_amount": "0.0", "refund_amount": "100.5", "currency_code": "GEL", "items" : [] }, "redirect_links": { "success": "https://payment.bog.ge/receipt?order_id=a767a276-cddd-43ec-9db3-9f9b39eee02d", "fail": "https://payment.bog.ge/receipt?order_id=a767a276-cddd-43ec-9db3-9f9b39eee02d" }, "payment_detail": { "transfer_method": { "key": "card", "value": "ბარათით გადახდა" }, "code": "100", "code_description": "Successful payment", "transaction_id": "230513868679", "payer_identifier": "548888xxxxxx9893", "payment_option": "direct_debit", "card_type": "mc", "card_expiry_date": "03/24", "request_account_tag": "1212", "transfer_account_tag": "gev2", "saved_card_type": "recurrent", "parent_order_id": "8d52130d-cb1b-45ea-b048-0f040a44e2a3" }, "actions": [ { "action_id": "b70968ca-eda9-47ae-8811-26fd1ab733f8", "request_channel": "public_api", "action": "authorize", "status": "completed", "zoned_action_date": "2022-11-28T13:42:40.668439Z", "amount": "100.5" }, { "action_id": "a89b872a-9700-4025-b3fb-047cbba7a5e6", "request_channel": "business_manager", "action": "refund", "status": "completed", "zoned_action_date": "2022-11-28T13:58:03.427939Z", "amount": "100.5" } ], "lang": "ka", "capture": "automatic", "reject_reason": null } ``` --- # Callback Source: https://api.bog.ge/docs/payments-addons/standard-process/callback Callback-ი არის ასინქრონული, server-to-server შეტყობინება, რომელიც ონლაინ გადახდების სისტემიდან თქვენს მიერ მითითებულ Callback URL მისამართზე იგზავნება. მისი მიზანია, საიმედოდ გაცნობოთ ტრანზაქციის საბოლოო სტატუსის შესახებ. სინქრონული API მოთხოვნებისგან განსხვავებით, სადაც ბიზნესის აპლიკაცია ითხოვს ინფორმაციას და ელოდება მყისიერ პასუხს, Callback-ის პროცესი ფონურ რეჟიმში მიმდინარეობს. ონლაინ გადახდების სისტემა ავტომატურად გამოაგზავნის POST მოთხოვნას ბიზნესის Callback URL-ზე, როდესაც გადახდა ან მასთან დაკავშირებული მოქმედება დასრულდება (წარმატებით ან წარუმატებლად), როგორიცაა თანხის ნაწილობრივი ან სრული დაბრუნება, პრეავტორიზაციის დადასტურება, თანხის გაყოფა. Callback-ის მიღებისა და დამუშავების ლოგიკა, მათ შორის მისი ხელმოწერის ვალიდაცია, ბიზნესის მხარეს უნდა იყოს იმპლემენტირებული. Callback-ის სათანადოდ დამუშავება კრიტიკულად მნიშვნელოვანი ნაბიჯია გადახდის სტატუსის დასადასტურებლად და ბიზნესის სისტემაში შეკვეთის უსაფრთხოდ განახლებისთვის. შეკვეთის მოთხოვნის დროს გადმოცემულ callback_url მისამართზე იგზავნება POST მეთოდით გადახდის დეტალები. პასუხის წარმატებით მიღების დასადასტურებლად, ბიზნესმა უნდა დააბრუნოს HTTP CODE 200. თუ ვერ მოხერხდა callback-ის წარმატებით მიღება, გადახდის სტატუსის გადასამოწმებლად, ბიზნესს შეუძლია გამოიყენოს [გადახდის დეტალების მიღების მეთოდი](https://api.bog.ge/docs/payments-addons/standard-process/get-payment-details). # Request ### Header-ის პარამეტრები - `Callback-Signature` — string ხელმოწერა დაგენერირებულია callback-ის request body-ზე `private key`-ით `SHA256withRSA` ალგორითმის გამოყენებით. იმისათვის, რომ ბიზნესი დარწმუნდეს callback-ში გადმოცემული ინფორმაციის ვალიდურობაში, request body-ისა და `public key`-ის დახმარებით უნდა დაავერიფიციროს ხელმოწერა. ვერიფიკაცია უნდა მოხდეს payload-ის დესერიალიზაციამდე, იმისათვის რომ request body-ის პარამეტრების თანმიმდევრობა დარჩეს უცვლელი. **PUBLIC KEY** ```bash -----BEGIN PUBLIC KEY----- MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAu4RUyAw3+CdkS3ZNILQh zHI9Hemo+vKB9U2BSabppkKjzjjkf+0Sm76hSMiu/HFtYhqWOESryoCDJoqffY0Q 1VNt25aTxbj068QNUtnxQ7KQVLA+pG0smf+EBWlS1vBEAFbIas9d8c9b9sSEkTrr TYQ90WIM8bGB6S/KLVoT1a7SnzabjoLc5Qf/SLDG5fu8dH8zckyeYKdRKSBJKvhx tcBuHV4f7qsynQT+f2UYbESX/TLHwT5qFWZDHZ0YUOUIvb8n7JujVSGZO9/+ll/g 4ZIWhC1MlJgPObDwRkRd8NFOopgxMcMsDIZIoLbWKhHVq67hdbwpAq9K9WMmEhPn PwIDAQAB -----END PUBLIC KEY----- ``` ### Body-ს პარამეტრები - `event` — string ქოლბექის ტიპი. მნიშვნელობა ყოველთვის არის `order_payment`. - `zoned_request_time` — string ქოლბექის გამოგზავნის თარიღი მსოფლიო კოორდინირებული დროით (UTC), "YYYY-MM-DDTHH:MM:SS.ssssssZ" ფორმატში. - `body` — object შეკვეთის მონაცემები. მოიცავს იმავე ველებს, რასაც [გადახდის დეტალები](https://api.bog.ge/docs/payments-addons/standard-process/get-payment-details#response). **REQUEST BODY** ```json { "event": "order_payment", "zoned_request_time": "2022-11-23T18:06:37.240559Z", "body": { "order_id": "a767a276-cddd-43ec-9db3-9f9b39eee02d", "industry": "ecommerce", ... } } ``` --- # Apple Pay™-ს ღილაკი ბიზნესის ვებგვერდზე Source: https://api.bog.ge/docs/payments-addons/external-orders/external-applepay # Apple Pay™-ს ღილაკი ბიზნესის ვებგვერდზე თქვენს ვებგვერდზე Apple Pay™-ის ღილაკის განთავსებისთვის საჭიროა რამდენიმე ეტაპის გავლა. პირველ რიგში, თქვენი საიტი უნდა აკმაყოფილებდეს [Apple-ის მოთხოვნებს](https://developer.apple.com/apple-pay/acceptable-use-guidelines-for-websites/). ვინაიდან Apple Pay-ის ღილაკი თავსდება არა საქართველოს ბანკის გადახდების გვერდზე, არამედ თქვენს ვებგვერდზე, გარემოს დაკონფიგურირება დამოუკიდებლად მოგიწევთ. ინფორმაციის მისაღებად ეწვით [Apple-ის კონფიგურაციის გვერდს](https://developer.apple.com/documentation/apple_pay_on_the_web/configuring_your_environment). განათავსეთ Apple Pay-ის ვალიდაციის სერტიფიკატი თქვენს ვებ გვერდზე. ჩამოტვირთეთ სერტიფიკატი [აქ](https://webstatic.bog.ge/apple-developer-merchantid-domain-association). გაეცანით სერტიფიკატის განთავსების [დეტალურ ინსტრუქციას](https://developer.apple.com/documentation/applepaywebmerchantregistrationapi/preparing_merchant_domains_for_verification). სერტიფიკატის განთავსების შემდეგ, გთხოვთ [ecommercemerchants@bog.ge](mailto:ecommercemerchants@bog.ge) ელ. ფოსტაზე გაგვიზიარეთ თქვენი API Public Key და ვებ-გვერდის მისამართი, რომელზეც გსურთ Apple Pay-ის ღილაკის განთავსება. ამ საფეხურების გავლის შემდგომ შეძლებთ, თქვენი გვერდიდან Apple-ის ღილაკით საქართველოს ბანკის გადახდა განახორციელოთ. შეკვეთის მოთხოვნა ხდება სტანდარტულად, იხილეთ [სტანდარტული პროცესი - შეკვეთის მოთხოვნა](https://api.bog.ge/docs/payments-addons/standard-process/create-top-up-order) :::note აუცილებელია [`Body`](https://api.bog.ge/docs/payments-addons/standard-process/create-top-up-order#body-ს-პარამეტრები) შეიცავდეს შემდეგ პარამტრებს: ```json "payment_method": ["apple_pay"], "config": { "apple_pay": { "external": true } } ``` ::: ### Response - `id` — string ონლაინ გადახდის იდენტიფიკატორი. - `result` — json Apple-ს მიერ გადახდის ინიცირებაზე დაბრუნებული დეტალები. - `_links` — object ვებრესურსის მისამართები, რომლებიც გადახდის პროცესის შემდგომ ეტაპებზე გამოიყენება. ამჟამად ბრუნდება შემდეგი რესურსი: - `_links.accept.href` — string გადახდის დადასტურების მისამართი, რომლის გამოძახებაც აუცილებელია Apple Pay გადახდის დასასრულებლად. **RESPONSE** ```json { "id": "{order_id}", "result": {...}, "_links": { "accept": { "href": "https://api.bog.ge/payments/v1/ecommerce/orders/{order_id}/payment" } } } ``` --- # Apple Pay™-ს გადახდის დადასტურება Source: https://api.bog.ge/docs/payments-addons/external-orders/complete-external-applepay # Apple Pay™-ს გადახდის დადასტურება მოცემული სერვისის გამოძახება აუცილებელია თქვენს ვებგვერდზე განთავსებული Apple Pay™-ის ღილაკით ინიცირებული გადახდის დასასრულებლად. ### Header-ის პარამეტრები - `Content-Type` — application/json, required - `Authorization` — Basic , required გადაეცემა `Bearer ` მნიშვნელობა, სადაც `jwt_token` არის აუტენტიფიკაციის მეთოდის Response-ის access_token პარამეტრში დაბრუნებული მნიშვნელობა. - `Idempotency-Key` — UUID v4 Idempotency-Key პარამეტრი უნდა იყოს უნიკალური ყველა ახალი API რექვესთისთვის. იმავე API-ზე Idempotency-Key-ის განმეორებით გამოყენებისას სერვერი დააბრუნებს იმავე სტატუს კოდსა და body-ს, რაც თავდაპირველი მოთხოვნისას. ეს ფუნქცია განსაკუთრებით სასარგებლოა თანმიმდევრული შედეგის უზრუნველსაყოფად, როდესაც საქმე გვაქვს ქსელური პრობლემებითა ან ხელახალი ცდებით გამოწვეულ დუბლირებულ მოთხოვნებთან. ### Path პარამეტრები - `order_id` — string, required შეკვეთის იდენტიფიკატორი, რომელიც ბრუნდება შეკვეთის მოთხოვნის Response-ში. ### Body-ს პარამეტრები - `apple_pay_token` — string, required Apple-ის ტოკენი. **CURL** ```bash curl -X POST 'https://api.bog.ge/payments/v1/ecommerce/orders/{order_id}/payment' \ -H 'Authorization: Bearer ' \ -H 'Content-Type: application/json' \ --data-raw '{ "apple_pay_token": "{\"token\":{\"paymentData\":{\"version\":\"EC_v1\"\"data\":\"V2VyIGRhc3MgRGFjaCBkZXIgdW5hdXRob3Jpc2llcnRlbiBWZXJicmVpdHVuZyB2b24gSW5mb3JtYXRpb25lbiBvZGVyIGRpZSBFcnN0ZWxsdW5nIHZvbiBLb3BpZW4gdW50ZXJzdMS8dHp0LCBtYWNodCBzaWNoIHN0cmFmYmFyLg==\",\"signature\":\"AGCSqGSIb3DQEHAqCAMIACAQExDTALBglghkgBZCrO6415UsR9xueflw3rEpZbft7zFVf19mAAAAAAAA\",\"header\":{\"publicKeyHash\":\"9mD12E4bF8dFlIF2k2ga/sD/ybcWraQH3aTx+RBDvVA4=\",\"ephemeralPublicKey\":\"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEGgfNfekFa1APW38avqjSzB+2mAq5hw3nXiQp51ZNwsMpB6H6YPQ26hZ78bnJdJvCqYYDiZaaa05tQLrXli09mg==\",\"transactionId\":\"f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2\"}},\"transactionIdentifier\":\"f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2\",\"paymentMethod\":{\"type\":\"PKPaymentMethodTypeCredit\",\"displayName\":\"Visa 1234\",\"network\":\"Visa\"}}}"; }' ``` ### Response - `id` — string ონლაინ გადახდის იდენტიფიკატორი. - `status` — string შეკვეთის სტატუსი. - `order_details` — object შეკვეთის მონაცემები. მოიცავს იმავე ველებს, რასაც შეიცავს [გადახდის დეტალები](https://api.bog.ge/docs/payments-addons/standard-process/get-payment-details#response). - `_links` — object ვებრესურსის მისამართები, რომლებიც გადახდის პროცესის შემდგომ ეტაპებზე გამოიყენება. ამჟამად ბრუნდება შემდეგი რესურსი: - `_links.details.href` — string გადახდის დეტალების მისამართი, რომლის გამოძახებითაც შეგიძლიათ, გაიგოთ ინფორმაცია ონლაინ გადახდის შესახებ. **RESPONSE** ```json { "id": "{order_id}", "status": "completed", "order_details": {...}, "_links": { "details": { "href": "https://api.bog.ge/payments/v1/receipt/{order_id}" } } } ``` --- # Response კოდები Source: https://api.bog.ge/docs/payments-addons/response-codes ## გადახდის Response კოდები | Code | აღწერა (EN) | აღწერა (GE) | |------|----------------------------------------------------------------------------------|----------------------------------------------------------------| | 100 | Successful payment | წარმატებული გადახდა | | 101 | Payment declined because card usage is limited. For detailed information, contact the card issuer bank | გადახდა უარყოფილია, რადგან ბარათის გამოყენება შეზღუდულია. დეტალური ინფორმაციისთვის დაუკავშირდით ბარათის მომსახურე ბანკს | | 102 | Saved card wasn't found | დამახსოვრებული ბარათი ვერ მოიძებნა | | 103 | Payment declined due to invalid card | გადახდა უარყოფილია, რადგან ბარათი არ არის ვალიდური | | 104 | Payment declined due to exceeding transaction limit | გადახდა უარყოფილია ტრანზაქციის რაოდენობის ლიმიტის გადაჭარბების გამო | | 105 | Payment declined because the card has expired | გადახდა უარყოფილია, რადგან ბარათი ვადაგასულია | | 106 | Payment declined due to exceeding the limit of the amount | გადახდა უარყოფილია თანხის ლიმიტის გადაჭარბების გამო | | 107 | Payment declined due to insufficient funds in the account | გადახდა უარყოფილია ანგარიშზე არასაკმარისი თანხის გამო | | 108 | Authentication Declined | გადახდის ავტორიზაციის უარყოფა | | 109 | Technical Issue | დაფიქსირდა ტექნიკური ხარვეზი | | 110 | Transaction Expired | ოპერაციის შესრულების დრო ამოიწურა | | 111 | Authentication timeout | გადახდის ავტორიზაციის დრო ამოიწურა | | 112 | General Error | საერთო შეცდომა | | 122 | Payment declined by the acquirer bank | გადახდა უარყოფილია მომსახურე ბანკის მიერ | | 199 | Unknown Response | უცნობი პასუხი | | 200 | Successful preauthorization | წარმატებული პრეავტორიზაცია | ## მოქმედების Response კოდები | Code | აღწერა (GE) | აღწერა (EN) | |------|----------------------------------------------------------------------------------|----------------------------------------------------------------| | 161 | თანხის დაბრუნება ვერ მოხერხდა. მეტი დეტალისთვის დაუკავშირდით ბარათის გამცემ ბანკს. | Refund could not be completed. Please contact the card issuing bank for more details. | | 162 | ბარათის გამცემი ბანკი უარყოფს თანხის დაბრუნებას. | The card issuing bank declined the refund. | | 163 | ანგარიშზე არ გაქვთ საკმარისი ნაშთი. | Not enough funds available in the account | | 164 | თანხის დაბრუნება ვერ მოხერხდა. მეტი დეტალისთვის დაუკავშირდით ბარათის გამცემ ბანკს. | Refund could not be completed. Please contact the card issuing bank for more details. | | 165 | თანხის დაბრუნება ვერ მოხერხდა. მეტი დეტალისთვის დაუკავშირდით ბარათის გამცემ ბანკს. | Refund could not be completed. Please contact the card issuing bank for more details. | | 166 | თანხის დაბრუნება ვერ მოხერხდა. მეტი დეტალისთვის დაუკავშირდით ბარათის გამცემ ბანკს. | Refund could not be completed. Please contact the card issuing bank for more details. | | 167 | ბარათი ვადაგასულია. დაუკავშირდით მომხმარებელს და დაუბრუნეთ თანხა აქტიურ ბარათზე. | Card expired. Contact the customer and refund the amount to an active card. | | 168 | თანხის დაბრუნება ვერ მოხერხდა. მეტი დეტალისთვის დაუკავშირდით ბარათის გამცემ ბანკს. | Refund could not be completed. Please contact the card issuing bank for more details. | | 169 | ბარათი ვადაგასულია ან მონაცემები არასწორია. გადაამოწმეთ ინფორმაცია მომხმარებელთან და თავიდან ცადეთ. | The card is expired or the details are incorrect. Please verify the information with the customer and try again. | | 179 | Unknown Response | Unknown Response | --- # გამოყენებული ტერმინები Source: https://api.bog.ge/docs/payments-addons/terms-used 1. ბიზნესი - საცალო ვაჭრობის ან მომსახურების კომპანია, რომელსაც გააჩნია ონლაინ/ელექტრონული სისტემა. 2. ონლაინ გადახდების გვერდი - ონლაინ გადახდების სისტემა, რომელიც საშუალებას გაძლევთ, მარტივად ჩააშენოთ გადახდების მოდული ნებისმიერი ტიპის ბიზნესში. 3. Callback - საბანკო სისტემიდან ბიზნესის მიერ გამოდგმული სერვისის გამოძახება, გადახდის შესახებ განახლებული ინფორმაციის მიწოდების მიზნით. 4. სისტემაში შესასვლელი რეკვიზიტები - ბანკის სისტემაში კლიენტის იდენტიფიკატორი (client_id) და საიდუმლო გასაღები (secret_key), რომელსაც ბანკი ანიჭებს კლიენტს, მისი ბიზნესად წარმატებით დარეგისტრირების შემდეგ. 5. ბარათის ნომერი (PAN) - პლასტიკური ბარათის წინა მხარეს გამოსახული 16 ციფრი. --- # შესავალი Source: https://api.bog.ge/docs/link-payment/introduction ## შესავალი საქართველოს ბანკის ონლაინ გადახდების API გთავაზობთ გადახდების დამუშავების ციფრულ პლატფორმებში ინტეგრაციის მარტივ და უსაფრთხო მეთოდს. ბმულით გადახდის API საშუალებას აძლევს მერჩანტებს, შექმნან უნიკალური გადახდის ბმულები, რომლებიც მომხმარებელს გადაამისამართებს ბანკის გადახდის გვერდზე, რაც ამარტივებს გადახდების მიღებას ელექტრონული ფოსტის, SMS-ის ან ნებისმიერი სხვა ციფრული არხის მეშვეობით. ეს გადაწყვეტა ბიზნესს საშუალებას აძლევს, მიიღოს გადახდები VISA, Mastercard და American Express ბარათებით, Apple Pay-ით, Google Pay-ით, BOG APP-ით და საქართველოს ბანკის ლოიალობის ქულებით (Plus, MR). - **როგორ მუშაობს**: API-ის მთავარი მიზანია, გაუმარტივოს მერჩანტებს ონლაინ გადახდების მიღება. ის ამარტივებს გადახდის დამუშავების კომპლექსურ პროცესს და ამცირებს PCI DSS სტანდარტთან შესაბამისობის მოთხოვნებს, ბარათის სენსიტიური მონაცემების დამუშავებისთვის ბანკის დაცული ინფრასტრუქტურის გამოყენების გზით. ეს ბიზნესს საშუალებას აძლევს, ეფექტურად მოითხოვოს და მიიღოს გადახდები ტრადიციული ელ. კომერციის გადახდის სისტემის გარეშე. - **ძირითადი მახასიათებლები**: API-ს აქვს წინასწარი შეკვეთის (გადახდის ბმულის) შექმნის, გადახდის უსაფრთხო გვერდზე გადამისამართების და ბარათების, ელ. საფულის და სხვა გადახდის მეთოდების გამოყენებით გადახდების დამუშავების მხარდაჭერა. - **მხარდაჭერილი სერვისები**: ძირითადი სერვისია pre-order-ის (Pre-order) შექმნა. API ეკოსისტემა ასევე მოიცავს სერვისებს თანხის დაბრუნების, გადახდის დეტალების შემოწმებისა და გადახდის ბმულის დეაქტივაციისთვის. - **შეტყობინებები**: სისტემა იყენებს ასინქრონულ webhook-ებს — სერვერიდან სერვერზე გამოძახებებს მერჩანტის მიერ მითითებულ callback_url-ზე — რათა უზრუნველყოს შეტყობინებები გადახდის საბოლოო შედეგების შესახებ, როგორიცაა წარმატებული ან წარუმატებელი ტრანზაქციები, თანხის დაბრუნება, გადახდის ბმულის ვადის გასვლა. --- # აუტენტიფიკაცია და ავტორიზაცია Source: https://api.bog.ge/docs/link-payment/authentication ## აუტენტიფიკაცია და ავტორიზაცია ეს მეთოდი ბიზნესს საშუალებას აძლევს, გაიაროს აუტენტიფიკაციის პროცესი. API-ის გამოძახებისას, ონლაინ გადახდების სერვერი აბრუნებს Bearer Token-ს, რომელიც წარმოადგენს აუცილებელ აუტენტიფიკაციის პარამეტრს ყველა შემდგომი მეთოდის გამოსაყენებლად. ### OAuth 2.0 კლიენტის მონაცემები - **Token URL**: `POST https://oauth2.bog.ge/auth/realms/bog/protocol/openid-connect/token` - **Grant Type**: `client_credentials` - **Headers**: `Authorization: Basic `, `Content-Type: application/x-www-form-urlencoded` - **Body**: `grant_type=client_credentials` - **Response**: `access_token`, `token_type`=Bearer, `expires_in` (წამებში) **REQUEST** ```bash curl -X POST 'https://oauth2.bog.ge/auth/realms/bog/protocol/openid-connect/token' \ -u {client_id}:{client_secret} \ -H 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'grant_type=client_credentials' ``` **RESPONSE** ```json { "access_token": "", "token_type": "Bearer", "expires_in": 1634719923245 } ``` --- # ძირითადი მახასიათებლები Source: https://api.bog.ge/docs/link-payment/conventions ## ძირითადი მახასიათებლები - **კონტენტის ტიპი**: `application/json`; character set UTF-8 - **თარიღი/დრო**: ISO 8601 ფორმატი დროის ზონის მითითებით (timezone offset) ან Z (e.g., `2026-04-21T13:45:00Z`) - **იდენტიფიკატორები**: UUID v4, თუ სხვა რამ არ არის მითითებული - **იდემპოტენტურობა**: `Idempotency-Key` header POST/PUT მეთოდებისთვის, უსაფრთხო ხელახალი მცდელობისთვის - **ლოკალიზაცია**: `Accept-Language` header (`ka`, `en`) ## Common Headers - `Authorization: Bearer ` - `Content-Type: application/json` - `Accept: application/json` - `Idempotency-Key: ` (არასავალდებულო, მაგრამ რეკომენდებული) - `Accept-Language: ka|en` (არასავალდებულო) --- # Pre-order-ის შექმნა Source: https://api.bog.ge/docs/link-payment/link-payment-api/create-pre-order Pre-order-ის შექმნის სერვისი ქმნის უნიკალურ გადახდის ბმულს მოწოდებული დეტალების საფუძველზე. ეს ბმული მომხმარებელს გადაამისამართებს დაცულ, ბანკის გადახდის გვერდზე, სადაც მას შეუძლია დაასრულოს გადახდა სხვადასხვა მეთოდის გამოყენებით. **მეთოდი:** `POST /v1/preorder` **Headers:** იხ. [Common Headers](https://api.bog.ge/docs/link-payment/conventions#common-headers) #### Body-ის პარამეტრები - `callback_url` — string, required HTTPS URL, რომელზეც ბანკის სერვერი აგზავნის ასინქრონულ შეტყობინებებს (callbacks) ოპერაციის საბოლოო სტატუსის შესახებ. - `description` — string, required შეკვეთის ან მომსახურების მოკლე აღწერა. - `external_order_id` — string შეკვეთის უნიკალური იდენტიფიკატორი, რომელიც გენერირებულია ბიზნესის სისტემის მიერ. - `purchase_units` — object, required ობიექტი, რომელიც შეიცავს გადახდის თანხისა და ვალუტის დეტალებს. - `purchase_units.currency` — string, required ვალუტის სამასოიანი კოდი (მაგ., 'GEL'). - `purchase_units.total_amount` — number, required ტრანზაქციის სრული თანხა. - `ttl` — integer TTL - დრო წუთებში, რომლის განმავლობაშიც წინასწარი შეკვეთის (pre-order) ლინკი ვალიდურია. მინიმალური: 2 წუთი. მაქსიმალური: 1440 წუთი (24 საათი). Default: 15 წუთი. **REQUEST** ```bash curl --location 'https://api.bog.ge/payments/v1/pre-orders' \ --header 'accept: */*' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer ' \ --data '{ "callback_url": "https://example.com/callback", "description": "service fee", "external_order_id": "id123", "purchase_units": { "currency": "GEL", "total_amount": 1 }, "ttl": 1440 }' ``` #### Response - `id` — string წინასწარი შეკვეთის უნიკალური იდენტიფიკატორი, რომელიც ბანკის სისტემის მიერ გენერირდება. ეს იდენტიფიკატორი შესაძლოა გამოყენებულ იქნას მომავალი მიმართვებისთვის, როგორიცაა გადახდის სტატუსის შემოწმება. - `_links` — object რესურსთან დაკავშირებული ჰიპერმედია ბმულების კონტეინერი. - `_links.payment_link` — object ობიექტი, რომელიც შეიცავს URL მისამართს მომხმარებლის მიერ გადახდის დასასრულებლად. - `_links.payment_link.href` — string სრული URL მისამართი, რომელიც ახდენს მომხმარებლის გადამისამართებას ბანკის დაცულ გადახდის გვერდზე. **RESPONSE** ```json { "id": "c0fb0f1d-7715-485a-b753-10cf148708e3", "_links": { "payment_link": { "href": "https://link.bog.ge/HnisFqRnzJz" } } } ``` --- # Pre-order-ის დეტალები Source: https://api.bog.ge/docs/link-payment/link-payment-api/get-pre-order-detail ეს მეთოდი გამოიყენება უკვე შექმნილი pre-order-ის მიმდინარე სტატუსისა და დეტალური ინფორმაციის მისაღებად. უნიკალური pre_order_id-ის მითითებით, მერჩანტს შეუძლია შეამოწმოს, გადახდის ბმული კვლავ აქტიურია, გადახდილია თუ ვადაგასულია, და ნახოს დაკავშირებული გადახდის დეტალები. **მეთოდი:** `GET v1/pre-orders/{pre_order_id}/detail` #### Headers: იხ. [Common Headers](https://api.bog.ge/docs/link-payment/conventions#common-headers) - `Authorization` — Bearer Token, required სავალდებულო. JWT access_token API-ის გამოძახების ავთენტიფიკაციისთვის. #### Path Parameters - `pre_order_id` — string, required სავალდებულო. Pre-order-ის უნიკალური იდენტიფიკატორი, რომელიც დაბრუნდა pre-order-ის შექმნისას. #### Response Parameters - `pre_order_id` — string Pre-order-ის უნიკალური იდენტიფიკატორი. - `zoned_create_date` — string თარიღი და დრო, როდესაც შეიქმნა Pre-order, UTC ფორმატში (ISO 8601). - `zoned_expire_date` — string თარიღი და დრო, როდესაც იწურება Pre-order-ის ვადა, UTC ფორმატში (ISO 8601). - `pre_order_status` — object ობიექტი, რომელიც შეიცავს გადახდის ბმულის მიმდინარე სტატუსს. - `pre_order_status.key` — string წინასწარი შეკვეთის სტატუსი: `active`, `performed`, `deactivated`, `expired` - `pre_order_status.value` — string წინასწარი შეკვეთის სტატუსის აღწერა. - `transaction_status` — object / null დაკავშირებული გადახდის ტრანზაქციის სტატუსი. ეს ველი იქნება null, თუ გადახდის მცდელობა არ განხორციელებულა. - `payment_detail` — object ობიექტი, რომელიც შეიცავს გამოყენებული გადახდის მეთოდის დეტალებს. - `payment_detail.transfer_method` — object გადარიცხვისთვის გამოყენებული მეთოდი (მაგ., ბარათით გადახდა). - `payment_detail.transfer_method.key` — string გადახდის მეთოდი: `card`, `google_pay`, `apple_pay`, `bog_p2p`, `bog_loyalty` - `payment_detail.transfer_method.value` — string გადახდის მეთოდის აღწერა. - `payment_detail.transaction_id` — string / null RRN - გადახდის ტრანზაქციის უნიკალური იდენტიფიკატორი, თუ ის განხორციელდა. - `payment_detail.payer_identifier` — string / null გადამხდელის იდენტიფიკატორი, როგორიცაა ბარათის დაფარული ნომერი. - `payment_detail.order_id` — string / null UUID - გადახდის ტრანზაქციის უნიკალური იდენტიფიკატორი, თუ ის განხორციელდა, გენერირებული ბანკის სისტემის მიერ. - `purchase_units` — object ობიექტი, რომელიც შეიცავს წინასწარ შეკვეთასთან დაკავშირებულ თანხას. - `purchase_units.request_amount` — string თავდაპირებლად მოთხოვნილი თანხა წინასწარ შეკვეთაში. - `purchase_units.transfer_amount` — string / null თანხა, რომელიც წარმატებით გადაირიცხა. - `purchase_units.refund_amount` — string / null თანხა, რომელიც დაბრუნდა, ასეთის არსებობის შემთხვევაში. - `purchase_units.currency_code` — string ტრანზაქციის ვალუტის სამასოიანი კოდი (მაგ., "GEL"). - `purchase_units.items` — array / null შეკვეთაში შემავალი ერთეულების სია. null, თუ არ არის მოწოდებული. - `lang` — string გადახდის გვერდის ენის პარამეტრი (მაგ., "ka" ქართულისთვის). - `invoice_payment_url` — string გადახდის გვერდის მოკლე URL (გადახდის ბმული). - `description` — string აღწერა, რომელიც მითითებული იყო წინასწარი შეკვეთის შექმნისას. - `external_order_id` — string ბიზნესის მიერ მოწოდებული შეკვეთის უნიკალური იდენტიფიკატორი. **RESPONSE** ```json { "pre_order_id": "0873d2db-5bf5-4845-91a3-f25e65f4749d", "zoned_create_date": "2026-04-21T11:09:31.458943Z", "zoned_expire_date": "2026-04-22T11:09:31.458943Z", "pre_order_status": { "key": "performed", "value": "Performed" }, "transaction_status": { "key": "refunded_partially", "value": "Partially refunded" }, "payment_detail": { "transfer_method": { "key": "card", "value": "Card Payment" }, "transaction_id": "611115529598", "payer_identifier": "411634***8449", "order_id": "d300e690-83ba-4f88-afbf-3d3fdaeda95b" }, "purchase_units": { "request_amount": "1.0", "transfer_amount": "0.4", "refund_amount": "0.6", "currency_code": "GEL", "items": null }, "lang": "ka", "invoice_payment_url": "https://link.bog.ge/HnisFqRnzJz", "description": "string", "external_order_id": "string" } ``` --- # deactivate-pre-order Source: https://api.bog.ge/docs/link-payment/link-payment-api/deactivate-pre-order # Pre-order-ის დეაქტივაცია ეს მეთოდი ბიზნესს საშუალებას აძლევს, გააუქმოს აქტიური გადახდის ბმული მის დაგეგმილ ვადაზე ადრე. დეაქტივაციის შემდეგ, ბმული აღარ იქნება ვალიდური და მომხმარებელი ვეღარ შეძლებს გადახდის გვერდზე შესვლას გადახდის დასასრულებლად. - `Method` — POST HTTP მეთოდი, რომელიც ამ მისამართისთვის გამოიყენება. - `Endpoint URI` — string `/v1/pre-order/{pre_order_id}/deactivate` - `Description` — string აქტიური pre-order-ის ბმულის დეაქტივაცია, რაც მომავალში გადახდის ნებისმიერ მცდელობას დაბლოკავს. #### Path Parameters - `pre_order_id` — string, required გასაუქმებელი წინასწარი შეკვეთის უნიკალური იდენტიფიკატორი. #### Headers: See [Common Headers](../conventions#common-headers) - `Authorization` — Bearer Token, required API მოთხოვნის ავთენტიფიკაციისთვის განკუთვნილი JWT `access_token`. #### Request Body ამ მისამართზე გასაგზავნი მოთხოვნა არ საჭიროებს body-ს. #### Response (200 OK): წარმატებული დეაქტივაციის შემთხვევაში, სისტემა დააბრუნებს დამადასტურებელ შეტყობინებას. - `result` — object ობიექტი, რომელიც შეიცავს დეაქტივაციის მოთხოვნის შედეგს. - `result.key` — string შედეგის აღმნიშვნელი გასაღები (მაგ., "success") - `result.message` — string შედეგის აღწერა. ```json { "result": { "key": "success", "message": "Successful pre-order deactivation" } } ``` --- # refund-pre-order Source: https://api.bog.ge/docs/link-payment/link-payment-api/refund-pre-order # Pre-order-ზე თანხის დაბრუნება ეს მეთოდი აინიცირებს თანხის დაბრუნებას წინასწარ შეკვეთაზე შესრულებულ გადახდაზე. პროცესი ასინქრონულია, რაც გულისხმობს, რომ API ადასტურებს თანხის დაბრუნების მოთხოვნის მიღებას, ხოლო თანხის დაბრუნების ფაქტობრივი დამუშავება ფონურ რეჟიმში ხორციელდება. - `Method` — POST HTTP მეთოდი, რომელიც ამ მისამართისთვის გამოიყენება. - `Endpoint URI` — string `/pa-payment-services-public/v1/pre-order/refund/{pre_order_id}` - `Description` — string წარმატებული გადახდისთვის მითითებული თანხის დაბრუნების მოთხოვნის გაგზავნა. #### Path Parameters - `pre_order_id` — string, required Pre-order-ის უნიკალური იდენტიფიკატორი, რომლისთვისაც მოთხოვნილია თანხის დაბრუნება. #### Headers: See [Common Headers](https://api.bog.ge/docs/link-payment/conventions#common-headers) - `Authorization` — Bearer Token, required API მოთხოვნის ავთენტიფიკაციისთვის განკუთვნილი JWT `access_token`. - `Content-Type` — string, required მნიშვნელობა უნდა იყოს `application/json`. #### Request Body - `amount` — number, required დასაბრუნებელი კონკრეტული თანხა. ეს შეიძლება იყოს საწყისი ტრანზაქციის ნაწილობრივი ან სრული თანხა. ```json { "amount": 50.00 } ``` #### Response (202 Accepted) წარმატებული პასუხი ნიშნავს, რომ თანხის დაბრუნების მოთხოვნა მიღებულია დასამუშავებლად. - `key` — string მოთხოვნის სტატუსის აღმნიშვნელი key (მაგ., "request_received"). - `message` — string შეტყობინება, რომელიც ადასტურებს, რომ თანხის დაბრუნების მოთხოვნა მიღებულია და მუშავდება. - `action_id` — string თანხის დაბრუნების მოქმედების უნიკალური იდენტიფიკატორი. ```json { "key": "request_received", "message": "Refund request has been received and is being processed", "action_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } ``` --- # Callback Source: https://api.bog.ge/docs/link-payment/callback ## Callback Callback (ქოლბექი) არის ასინქრონული, სერვერებს შორის შეტყობინება, რომელიც იგზავნება გადახდების სისტემიდან თქვენს მიერ მითითებულ callback_url-ზე. მისი მიზანია, საიმედოდ აცნობოს თქვენს სისტემას ტრანზაქციის საბოლოო სტატუსი (მაგ., წარმატებული გადახდა, თანხის დაბრუნება). ეს მექანიზმი გადამწყვეტია შეკვეთის სტატუსის უსაფრთხოდ და ავტომატურად განახლებისთვის, რადგან პროცესი მომხმარებლის ჩარევის გარეშე მიმდინარეობს და მონაცემების საიმედო მიწოდებას უზრუნველყოფს. შეტყობინების მიღებისას, თქვენმა სისტემამ უნდა გადაამოწმოს ციფრული ხელმოწერა, რათა დარწმუნდეს, რომ ინფორმაცია ნამდვილი და უცვლელია. ამის შემდეგ, წარმატებული მიღების დასადასტურებლად, სისტემამ უნდა დააბრუნოს HTTP 200 OK პასუხი. ### მოთხოვნის აღწერა (შემომავალი Callback) გადახდის სისტემა გამოაგზავნის HTTP POST მოთხოვნას callback_url-ზე, რომელიც თქვენ მიუთითეთ წინასწარი შეკვეთის (Pre-order) შექმნისას. ეს მოთხოვნა შეიცავს ტრანზაქციის საბოლოო სტატუსსა და დეტალებს. #### Headers | Header | ტიპი | აღწერა | |--------|------|-------------| | Callback-Signature | String | **არასავალდებულო, მაგრამ რეკომენდებული.** Base64-ით კოდირებული ხელმოწერა, რომელიც გენერირებულია მოთხოვნის საწყისი ტანის (raw request body) ბანკის პირადი გასაღებით დაშიფვრის შედეგად, SHA256withRSA ალგორითმის გამოყენებით. თქვენ უნდა გადაამოწმოთ ეს ხელმოწერა მოწოდებული საჯარო გასაღებით, რათა დარწმუნდეთ Callback-ის ავთენტურობასა და მონაცემთა მთლიანობაში. | #### Request Body | პარამეტრი | ტიპი | აღწერა | |-----------|------|-------------| | event | String | შეტყობინების ტიპი. გადახდის სტატუსის განახლებისთვის, მნიშვნელობა ყოველთვის არის `link_payment`. | | zoned_request_time | String | დროის შტამპი, რომელიც აღნიშნავს, როდის გაიგზავნა Callback-ი, UTC ფორმატში (მაგ., "YYYY-MM-DDTHH:MM:SS.ssssssZ"). | | body | Object | ობიექტი, რომელიც შეიცავს შეკვეთისა და გადახდის დეტალურ მონაცემებს, "წინასწარი შეკვეთის დეტალების მიღების" მეთოდის პასუხის მსგავსად. | **REQUEST** ```json { "event": "link_payment", "zoned_request_time": "2026-04-22T11:09:31.458943Z", "body": { "pre_order_id": "0873d2db-5bf5-4845-91a3-f25e65f4749d", "zoned_create_date": "2026-04-21T11:09:31.458943Z", "zoned_expire_date": "2026-04-22T11:09:31.458943Z", "pre_order_status": { "key": "performed", "value": "Performed" }, "transaction_status": { "key": "refunded_partially", "value": "Partially refunded" }, "payment_detail": { "transfer_method": { "key": "card", "value": "Card Payment" }, "transaction_id": "611115529598", "payer_identifier": "411634***8449", "order_id": "d300e690-83ba-4f88-afbf-3d3fdaeda95b" }, "purchase_units": { "request_amount": "1.0", "transfer_amount": "0.4", "refund_amount": "0.6", "currency_code": "GEL", "items": null }, "lang": "ka", "invoice_payment_url": "https://link.bog.ge/HnisFqRnzJz", "description": "string", "external_order_id": "id123" } } ``` --- # გამოყენებული ტერმინები Source: https://api.bog.ge/docs/link-payment/glossary 1. **კლიენტის მონაცემები (Client Credentials)** — OAuth 2.0-ის პროცესი, რომლის დროსაც კლიენტი თავად გადის ავთენტიფიკაციას. 2. **იდემპოტენტურობა (Idempotency)** — განმეორებითი მოთხოვნის უსაფრთხო მექანიზმი, რომელიც თავიდან აცილებს დუბლირებულ გვერდით ეფექტებს. 3. **TTL (Time to Live)** —პერიოდი, რომლის განმავლობაშიც შეტყობინება ვალიდურია არხში. --- # შესავალი Source: https://api.bog.ge/docs/paymentgateway/introduction :::caution NOTICE დოკუმენტი განკუთვნილია სერვის-პროვაიდერებისათვის. ::: ## რა არის Payment Gateway? Payment Gateway არის ონლაინ სერვისი, რომელიც საშუალებას აძლევს ბიზნესს და ინდივიდებს მიიღონ გადახდები მომხმარებლებისგან მათი ვებსაიტების ან მობილური აპლიკაციების საშუალებით. ## მიზანი დოკუმენტი შეიცავს ინფორმაციას კომუნიკაციის მეთოდების, ხელმისაწვდომი ოპერაციების, გაცვლის ფორმატების, ავთენტიფიკაციის, წინასწარ განსაზღვრულ პარამეტრებსა და სტატუსის კოდებზე და ა.შ.. ## პროტოკოლის აღწერა დოკუმენტი აღწერს სისტემას, რომელშიც მომხმარებელი ურთიერთქმედებს სერვის-პროვაიდერთან ინტერფეისის საშუალებით. უფრო კონკრეტულად, მომხმარებელს შეუძლია საქართველოს ბანკის სერვერის მეშვეობით გააგზავნოს ვებ-მოთხოვნა სერვის-პროვაიდერთან, რაზეც ამ უკანასკნელს პასუხის გაცემის ვალდებულება ეკისრება. ხოლო მიღებული პასუხი დამუშავდება BOG-ის მიერ და გამოჩნდება მომხმარებლისთვის შესაბამის ადგილას. მომხმარებელს შეუძლია განახორციელოს ოპერაციების თვითნებური რაოდენობა. გარდა ამისა, ზოგიერთი გადახდის არხი შეზღუდავს ამ რიცხვს ორი ოპერაციით (ინფორმაცია ვალისა და/ან გადახდის შესახებ), თუმცა ამის გვერდის ავლა შესაძლებელია სერვისის ინტეგრაციისთვის საჭირო დროის ხარჯზე. პროტოკოლი იმუშავებს ვებ-აპთან ერთად, რომელიც მისცემს სერვის-პროვაიდერებს შესაძლებლობას განსაზღვრონ მრავალი ოპერაცია ერთი გადახდის ნაკადზე ინტერფეისის საშუალებით. ყველა სერვის-პროვაიდერს ექნება შესაძლებლობა განაგოს ისევე როგორც ოპერაციების რაოდენობა, ასევე სერვისის შესაბამასისი მახასიათებლებიც კი. ## მოთხოვნები სერვის-პროვაიდერისადმი სერვისის პროვაიდერს მოეთხოვება შექმნას ვებ-სერვერი, რომელიც შეიძლება იყოს საჯაროდ ხელმისაწვდომი ან მხოლოდ VPN არხის საშუალებით. იმ შემთხვევაში, თუ ვებ სერვერი საჯაროდ ხელმისაწვდომია, საჭიროა, რომ მას ჰქონდეს HTTPS მხარდაჭერა. სერვისის პროვაიდერს უფლება აქვს გამოიყენოს სურვილამებრ შერჩეული ნებისმიერი API endpoint. Მაგალითად. http://serviceprovider:8088/api/mock შესაძლებელია შემდეგი HTTP მეთოდების განსაზღვრა სერვის-პროვაიდერის ოპერაციებზე: GET, POST, PUT, PATCH & DELETE; თუმცა BOG არ გამოიყენებს HTTP მოთხოვნის body-ის წინასწარ შერჩეული ოპერაციებისთვის რაიმე ინფორმაციის გადასაცემად, მიუხედავად სერვისის პროვაიდერის მიერ არჩეული HTTP მეთოდისა. --- # ავთენტიფიკაცია Source: https://api.bog.ge/docs/paymentgateway/authentication ## რას გულისხმობს ავთენტიფიკაცია? სექცია განსაზღვრავს ავთენტიფიკაციის სხვადასხვა მეთოდებს, რომლებიც მხარდაჭერილია BOG პროტოკოლის მიერ. სავალდებულოა, რომ სერვისის პროვაიდერმა გამოიყენოს აქ ჩამოთვლილი ავთენტიფიკაციის ერთ-ერთი მეთოდი. უფრო მეტიც, უსაფრთხოების გაზრდის მიზნით რეკომენდირებულია ავთენტიფიკაციის რამდენიმე მეთოდის ერთდროულად გამოყენება. ## რისკები წინამდებარე დოკუმენტი არ ისახავს მიზნად გადახდის სისტემის მონაწილეებზე დაკისრებული რისკების შეფასებას ელექტრონულ გადახდებთან და შესაბამის პასუხისმგებლობებთან დაკავშირებით. დოკუმენტი აღწერს უსაფრთხოების რეჟიმებს, რომლებიც გამოიყენება გადახდის სისტემის დასაცავად. ## მხარდაჭერილი მეთოდები - [HTTP Basic](https://api.bog.ge/docs/paymentgateway/auth-methods/basic) - [OAuth 2.0 - Client Credentials](https://api.bog.ge/docs/paymentgateway/auth-methods/oauth2) - [API Key](https://api.bog.ge/docs/paymentgateway/auth-methods/apikey) - [HMAC-SHA256](https://api.bog.ge/docs/paymentgateway/auth-methods/hmac-sha256) --- # HTTP Basic Source: https://api.bog.ge/docs/paymentgateway/auth-methods/basic თუ სერვისის პროვაიდერი გადაწყვეტს [HTTP Basic Auth](https://datatracker.ietf.org/doc/html/rfc7235)-ის ავთენტიფიკაციის მეთოდის გამოყენებას, მაშინ მან უნდა მიიღოს Authorization header-ი, რომლის მნიშვნელობაც იყენებს ძირითადი ავტორიზაციის ფორმატს. ### Header-ის პარამეტრები - `Authorization` — Basic , required გადაეცემა „Basic „ + „:“ მნიშვნელობა კოდირებული Base64 ფორმატში (მაგ: `Basic ODI4Mjo3Njk3MDY0OTlmMDcwOWUyMzQ4NDU4NjNmOThiMjMxNA==`), სადაც და არის სერვის-პროვაიდერის მიერ ბანკინსთვის გადაცემული, სისტემაში შესვლისთვის საჭირო, რეკვიზიტები. --- # OAuth 2.0 - Client Credentials Source: https://api.bog.ge/docs/paymentgateway/auth-methods/oauth2 სერვისის პროვაიდერს შეუძლია შექმნას ავტორიზაციის ვებ-სერვისი, რომელიც მხარს უჭერს OAuth 2.0 ([D. Hardt, Ed., 2012](https://datatracker.ietf.org/doc/html/rfc6749)) Client Credentials-ის გრანტის ტიპს. ბანკი სერვის-პროვაიდერთან კომუნიკაციისთვის გამოიყენებს HTTP POST მეთოდს შემდეგი ფორმატით: ### Header-ის პარამეტრები - `Content-Type` — application/x-www-form-urlencoded, required ### Body-ს პარამეტრები - `grant_type` — client_credentials, required მნიშვნელობად გადაეცემა ფიქსირებული ტექსტი: `client_credentials` - `client_id` — <client_id>, required - `client_secret` — <client_secret>, required **CURL** ```bash curl --location --request POST 'http://localhost:8080/ess-api/authenticate' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'grant_type=client_credentials' \ --data-urlencode 'client_id=client_id' \ --data-urlencode 'client_secret=client_secret' ``` ### Response სერვის-პროვაიდერმა უნდა დააბრუნოს შემდეგი JSON პასუხი: - `access_token` — string ავტორიზაციის სერვერის მიერ დაბრუნებული Token-ის მნიშვნელობა - `created_at` — string UNIX დროის შტამპი – მილიწამების რაოდენობა, რაც გავიდა 1970 წლის 1 იანვრიდან დღემდე UTC-ის დროის სარტყელით. - `expires_in` — number აბრუნებს რიცხვით მნიშვნელობას, თუ რამდენი წამის განმავლობაში არის აქტიური Token. - `token_type` — number Token-ის ტიპი (ბრუნდება ტექსტური მნიშვნელობა - `Bearer`). **RESPONSE** ```json { "access_token": "xx82194x21412xxx219124x678x888x2xxx1900xx", "created_at": 1693236686855, "expires_in": 300, "token_type": "Bearer" } ``` ამ უკანასკნელი სერვერის არსებობის შემთხვევაში, საქართველოს ბანკი ყოველი ოპერაციის გამოძახების დროს სერვის-პროვაიდერს გადასცემს შემდეგ Header-ის მნიშვნელობას: - `Authorization` — Bearer , required გადაეცემა „Bearer „ + „<token>“ (მაგ: „Bearer xx82194x21412xxx219124x678x888x2xxx1900xx“), სადაც `token` არის სერვის-პროვიადერის ავტორიზაციის სერვერის მიერ დაბრუნებული პარამეტრი. --- # API Key Source: https://api.bog.ge/docs/paymentgateway/auth-methods/apikey სერვის-პროვაიდერს შეუძლია ბანკს მიაწოდოს API გასაღები, რომელიც გამოყენებული იქნება თითოეული ოპერაციის ფარგლებში. თუ გასაღები მოცემულია, მაშინ BOG თითოეულ ოპერაციას გამოაყოლებს HTTP Header-ს: - `Auth-Key` — , required `API_KEY` არის სერვის-პროვაიდერის მიერ მოცემული გასაღები. --- # HMAC-SHA256 Source: https://api.bog.ge/docs/paymentgateway/auth-methods/hmac-sha256 სერვისის პროვაიდერს შეუძლია დამატებით მიაწოდოს BOG-ს ჰეშინგის საიდუმლო გასაღები, რომელიც გამოყენებული იქნება HTTP Request Body-ის ჰეშირებისთვის HTTP POST & PATCH მეთოდებისთვის, ხოლო HTTP GET, PUT & DELETE მოთხოვნების შემთხვევაში – Query-ის ჰეშირებისთვის. თუ ზემოაღნიშნული პარამეტრი მოწოდებულია, სერვის-პროვაიდერმა უნდა მიიღოს HTTP header: `Hash` და გადაამოწმოს იგი. ჰეშირებისთვის გამოყენებული იქნება HMAC-SHA256 ალგორითმი, სადაც HMAC-SHA256 ეხება ჰეშზე დაფუძნებულ შეტყობინებების ავთენტიფიკაციის კოდს ([Krawczyk, Bellare, Canetti, 1997](https://www.ietf.org/rfc/rfc2104.txt)) დაშიფვრის მეთოდს საიდუმლო გასაღებთან და კრიპტოგრაფიულ ფუნქციასთან ერთად- SHA256 ([Eastlake, E. Huawei, Hansen, 2011](https://datatracker.ietf.org/doc/html/rfc6234)). გარდა ამისა, ჰეშის კოდი შეიცავს მხოლოდ დიდ ასოებს და ციფრებს, თექვსმეტობით ფორმატში. - `Hash` — , required `HASH` არის HTTP Request Body-ის ან Query-ის დაჰეშილი მნიშვნელობა. მაგალითად, თუ სერვის-პროვაიდერის მიერ მოწოდებული საიდუმლო გასაღებია: `8bbe50a7d61af79211148c09e40e1bffaefdf319dce665bc5a31b55ec28a508b` და თუ HTTP GET მოთხოვნა არის ფორმის: `http://serviceprovider:8088/api/mock/get-categories?personalNumber=01234567890&birthDate=11.01.2002` მაშინ მისი შესაბამისი კრიპტოგრაფიული მესიჯი იქნება მისი Query (რადგან GET მოთხოვნაა): `personalNumber=01234567890&birthDate=11.01.2002` რომელიც მოგვცემს შემდეგ `HASH`-ის მნიშვნელობას: `841A782048F51A798331E4A534A240911D541B869CB0E2CF1BB58F086873C079` --- # არჩევითი ოპერაციები Source: https://api.bog.ge/docs/paymentgateway/operations :::caution NOTICE მორგებული ოპერაციები არჩევითია. ე.ი. სერვის-პროვაიდერმა შეიძლება საერთოდ არ განსაზღვროს რაიმე ოპერაცია. ::: ## ცვლადების სავალდებულო სტანდარტები კომპანიის მასშტაბით სტანდარტების შესანარჩუნებლად, BOG მოითხოვს, რომ სერვის-პროვაიდერებმა გამოიყენონ კონკრეტული ცვლადის სახელები, რომლებიც შეესაბამება მათ მნიშვნელობებს. Მაგალითად. თუ მომხმარებელი იყენებს თავის პირად ნომერს სერვის-პროვაიდერისგან გარკვეული ინფორმაციის მისაღებად (მაგ. დავალიანება), მაშინ ამ უკანასკნელმა უნდა გამოიყენოს personalNumber, როგორც API-ს მიერ მოთხოვნილი ცვლადის სახელი. იხილეთ სავალდებულო ცვლადების სტანდარტების სრული სია ქვემოთ: - **personalNumber** – გამოიყენება როგორც პირადი ნომრის იდენტიფიკატორი. - **customerId** – გამოიყენება როგორც მომხმარებლის იდენტიფიკატორი. - **debt** – მომხმარებელმა მომსახურების მიმწოდებლის მიმართ მცირე ერთეულებით დავალიანება. - **debtList** – მონაცემთა მოდელების სია, რომელიც შეიცავს კლიენტის მიერ მომსახურების მიმწოდებლისადმი კუთვნილ თანხებს (და შესაძლოა სხვა ველებს) მცირე ერთეულებში. - **amount** – თანხა, რომელიც მომხმარებელს სურს გადაიხადოს მცირე ერთეულებით. ## მონაცემთა გაცვლის ფორმატი ყველა მორგებული ოპერაცია, რომელიც დაუკავშირდება სერვის-პროვაიდერის API-ს, გაგზავნის ყველა მოთხოვნის პარამეტრს, როგორც HTTP Query პარამეტრებს, ასევე HTTP Header-ის მნიშვნელობებს, რომლებიც გამოიყენება ავტორიზაციისთვის. სერვის-პროვაიდერმა კი, თითოეულ ოპერაციას უნდა უპასუხოს წინასწარ განსაზღვრული ფორმატით: - `status.code` — number წინასწარ განსაზღვრული სტატუსის [კოდი](https://api.bog.ge/docs/paymentgateway/error-codes). - `status.value` — string სტატუსის მნიშვნელობა (სურვილისამებრ). - `timestamp` — number UNIX დროის შტამპი – მილიწამების რაოდენობა, რაც გავიდა 1970 წლის 1 იანვრიდან დღემდე UTC-ის დროის სარტყელით. - `receiptId` — string receiptId არის გადახდის უნიკალური იდენტიფიკატორი, რომელიც დაბრუნდა სერვის-პროვაიდერისგან წარმატებული გადახდის ოპერაციის შემდეგ. - `response` — object JSON მონაცემები - დაბრუნებული ნებისმიერი თვითნებური ოპერაციიდან. ველი სავალდებულოა ყოველი ოპერაციისთვის. **RESPONSE** ```json { "status":{ "code":0, "value":"OK" }, "timestamp":1693236686855, "receiptId":"", "response":{"wrapper":{"categoryCodes":["A1","B"]}} } ``` :::note სერვის-პროვაიდერის მიერ შექმნილ ოპერაციებთან ერთად, ასევე არსებობს BOG-ის მიერ წინასწარ განსაზღვრული ოპერაციები, რომელთაგან საჭიროა მხოლოდ [გადახდის](https://api.bog.ge/docs/paymentgateway/pre-defined-ops/payment) ოპერაცია, ყველა დანარჩენი არასავალდებულოა. ::: --- # გადახდა Source: https://api.bog.ge/docs/paymentgateway/pre-defined-ops/payment ოპერაციების ნებისმიერი რაოდენობა შეიძლება განისაზღვროს სერვის-პროვაიდერის მიერ, თუმცა გადახდის ოპერაცია ყოველთვის შესრულდება საოპერაციო ჯაჭვის ბოლოს, თუ კი მომხმარებელი გადაწყვეტს გადახდას. შესაბამისად, სერვის-პროვაიდერი ვალდებულია უზრუნველყოს გადახდის ოპერაციის იმპლემენტაცია. ### Body-ს პარამეტრები - `transactionId` — string, required ბანკის მიერ შექმნილი ტრანზაქციის უნიკალური იდენტიფიკატორი. - `amount` — number, required თანხა მცირე ერთეულებში (თეთრი, ცენტი, და ა.შ.). - `currency` — string, required ვალუტა ([ISO 4217 currency code](https://www.iban.com/currency-codes)), მაგალითად `GEL`. - `parameters` — object, required პარამეტრების ობიექტი, რომლის თითოეული ელემენტი მოიცავს `key` & `value` წყვილს, სადაც `key` არის პარამეტრის დასახელება, ხოლო `value` - მნიშვნელობა. **REQUEST BODY** ```json { "transactionId": "00000000", "amount": 500000, "currency": "GEL", "parameters": { "personalNumber": "01234567890", "birthDate": "11.01.2002" } } ``` ### Response სერვის-პროვაიდერმა უნდა დააბრუნოს შემდეგი JSON პასუხი: - `status.code` — number წინასწარ განსაზღვრული სტატუსის [კოდი](https://api.bog.ge/docs/paymentgateway/error-codes). - `status.value` — string სტატუსის მნიშვნელობა (სურვილისამებრ). - `timestamp` — number UNIX დროის შტამპი – მილიწამების რაოდენობა, რაც გავიდა 1970 წლის 1 იანვრიდან დღემდე UTC-ის დროის სარტყელით. - `receiptId` — string receiptId არის გადახდის უნიკალური იდენტიფიკატორი, რომელიც დაბრუნდა სერვის-პროვაიდერისგან წარმატებული გადახდის ოპერაციის შემდეგ. **RESPONSE** ```json { "status":{ "code":0, "value":"OK" }, "timestamp":1693236686855, "receiptId":"1234" } ``` --- # ტრანზაქციის სტატუსი Source: https://api.bog.ge/docs/paymentgateway/pre-defined-ops/payment-status როდესაც გადახდის სტატუსის ოპერაცია გამოძახებულია BOG-ის მიერ, მოსალოდნელია, რომ სერვის-პროვაიდერი უპასუხებს ჩამოთვლილთაგან ერთ-ერთი სტატუსის კოდით: [12, 13, 14](https://api.bog.ge/docs/paymentgateway/error-codes). ### Body-ს პარამეტრები - `transactionId` — string, required ბანკის მიერ შექმნილი ტრანზაქციის უნიკალური იდენტიფიკატორი. **CURL** ```bash curl --location --request GET 'http://serviceprovider:8088/api/mock/payment-status?transactionId=00000000' ``` ### Response სერვის-პროვაიდერმა უნდა დააბრუნოს შემდეგი JSON პასუხი: - `status.code` — number წინასწარ განსაზღვრული სტატუსის [კოდი](https://api.bog.ge/docs/paymentgateway/error-codes) ავტორიზაციის სერვერის მიერ დაბრუნებული Token-ის მნიშვნელობა - `status.value` — string სტატუსის მნიშვნელობა (სურვილისამებრ) - `timestamp` — number UNIX დროის შტამპი – მილიწამების რაოდენობა, რაც გავიდა 1970 წლის 1 იანვრიდან დღემდე UTC-ის დროის სარტყელით. **RESPONSE** ```json { "status":{ "code":12, "value":"Transaction was successful" }, "timestamp":1693236686855 } ``` --- # ტრანზაქციის გაუქმება Source: https://api.bog.ge/docs/paymentgateway/pre-defined-ops/cancel-payment ტრანზაქციის გაუქმების ოპერაციის გამოძახებისას, სერვის-პროვაიდერი ვალდებულია გააუქმოს გადახდა BOG-დან მოცემული ტრანზაქციის იდენტიფიკატორით. ### Body-ს პარამეტრები - `transactionId` — string, required ბანკის მიერ შექმნილი ტრანზაქციის უნიკალური იდენტიფიკატორი. **CURL** ```bash curl --location --request GET 'http://serviceprovider:8088/api/mock/cancel-status?transactionId=00000000' ``` ### Response სერვის-პროვაიდერმა უნდა დააბრუნოს შემდეგი JSON პასუხი: - `status.code` — number წინასწარ განსაზღვრული სტატუსის [კოდი](https://api.bog.ge/docs/paymentgateway/error-codes) - `status.value` — string სტატუსის მნიშვნელობა (სურვილისამებრ) - `timestamp` — number UNIX დროის შტამპი – მილიწამების რაოდენობა, რაც გავიდა 1970 წლის 1 იანვრიდან დღემდე UTC-ის დროის სარტყელით. **RESPONSE** ```json { "status":{ "code":0, "value":"OK" }, "timestamp":1693236686855 } ``` --- # გადახდების შესახებ ინფორმაციის მიწოდება Source: https://api.bog.ge/docs/paymentgateway/pre-defined-ops/send-payment-info გადახდების შესახებ ინფორმაციის მიწოდების ოპერაცია შესრულდება ერთხელ დღის ბოლოს, სადაც BOG გამოგიგზავნით ინფორმაციას წინა დღეს განხორციელებული წარმატებული გადახდების შესახებ (24 საათის განმავლობაში), UTC+4h (თბილისი) დროის ზონის მიხედვით. ვინაიდან Request Body შეიცავს როგორც შემაჯამებელ, ასევე ინდივიდუალურ ინფორმაციას გადახდების შესახებ, არსებობს რისკი იმისა, რომ Request Body გასცდეს ზომის ლიმიტს. ამის გამო, გაგზავნა-გადახდის-ინფორმაციის ოპერაცია შესრულდება სერიებად, სადაც n-ე პარტიის დროის ინტერვალი იწყება Tn-დან (ჩათვლით), ხოლო n-1 პარტიის დროის ინტერვალი მთავრდება Tn-ზე (ჩაუთვლელად), სადაც Tn-1 < Tn. ე.ი. პარტიები გაიგზავნება შემდგომში 24 საათიანი დროის ქვეჯგუფების საფუძველზე. უფრო მეტიც, მონაცემების თითო პარტიაში გაგზავნის შეუსრულებლობის შემთხვევაში, მხოლოდ ერთხელ მოხდება მოთხოვნის თავიდან მცდელობა. ### Body-ს პარამეტრები - `timezoneId` — string, required [დროის სარტყელის იდენტიფიკატორი.](https://docs.oracle.com/middleware/1221/wcs/tag-ref/MISC/TimeZones.html) - `timespan.from` — number, required (ჩათვლით) UNIX დროის შტამპი – მილიწამების რაოდენობა, რაც გავიდა 1970 წლის 1 იანვრიდან დღემდე UTC-ის დროის სარტყელით. - `timespan.to` — number, required (ჩაუთვლელად) UNIX დროის შტამპი – მილიწამების რაოდენობა, რაც გავიდა 1970 წლის 1 იანვრიდან დღემდე UTC-ის დროის სარტყელით. - `summary[?].totalAmount` — string, required ჯამური თანხა მცირე ერთეულებში (თეთრი, ცენტი, და ა.შ.). - `summary[?].currencyCode` — string, required [ვალუტა](https://www.iban.com/currency-codes) - `summary[?].count` — string, required ტრანზაქციების რაოდენობა. - `paymentList[?].transactionId` — string, required ბანკის მიერ შექმნილი ტრანზაქციის უნიკალური იდენტიფიკატორი. - `paymentList[?].currencyCode` — string, required [ვალუტა](https://www.iban.com/currency-codes) - `paymentList[?].amount` — string, required თანხა მცირე ერთეულებში (თეთრი, ცენტი, და ა.შ.). **REQUEST BODY** ```json { "timezoneId": "Asia/Tbilisi", "timespan": { "from": 1693598400000, "to": 1693684799000 }, "summary": [ { "totalAmount": 5000000, "currency": "GEL", "count": 2 }, { "totalAmount": 100000, "currency": "USD", "count": 1 } ], "paymentList":[ { "transactionId": "00000000", "currencyCode": "GEL", "amount": 2500000 }, { "transactionId": "00000001", "currencyCode": "GEL", "amount": 2500000 }, { "transactionId": "00000002", "currencyCode": "USD", "amount": 100000 } ] } ``` ### Response სერვის-პროვაიდერმა უნდა დააბრუნოს შემდეგი JSON პასუხი: - `status.code` — number წინასწარ განსაზღვრული სტატუსის [კოდი](https://api.bog.ge/docs/paymentgateway/error-codes). - `status.value` — string სტატუსის მნიშვნელობა (სურვილისამებრ). - `timestamp` — number UNIX დროის შტამპი – მილიწამების რაოდენობა, რაც გავიდა 1970 წლის 1 იანვრიდან დღემდე UTC-ის დროის სარტყელით. **RESPONSE** ```json { "status":{ "code":0, "value":"OK" }, "timestamp":1693236686855 } ``` --- # პასუხის მოსალოდნელი დრო Source: https://api.bog.ge/docs/paymentgateway/expected-response-times პასუხის მოსალოდნელი დრო, ე.ი. თითოეული ოპერაციისთვის რეაგირების დროის ლიმიტები, მოცემულია ქვემოთ. - **OAuth Client Credentials** – 15 წამი. - **არჩევითი ოპერაციები** – 10 წამი. - **გადახდა** – 30 წამი. - **ტრანზაქციის სტატუსი** – 15 წამი. - **ტრანზაქციის გაუქმება** – 15 წამი. - **გადახდების შესახებ ინფორმაციის მიწოდება** – 60 წამი. თუ სერვის-პროვაიდერი არ დააბრუნებს პასუხს თითოეული ოპერაციისთვის მოცემულ ვადაში, ჩაითვლება, რომ მოთხოვნა წარუმატებელია. --- # გამოყენებული ტერმინები Source: https://api.bog.ge/docs/paymentgateway/terms-used ## განმარტებები, აბრევიატურები და აკრონიმები - **BOG** - საქართველოს ბანკი - **სერვის-პროვაიდერი** - კომპანია, რომელიც უზრუნველყოფს მომსახურებას გარკვეული გადახდისთვის და სურს გადაიხადოს BOG გადახდის სისტემის მეშვეობით. - **მომხმარებელი** - პირი, რომელიც იყენებს BOG-ის მომხმარებლის ინტერფეისს სერვის-პროვაიდერთან დასაკავშირებლად, ვალების შესახებ ინფორმაციის მისაღებად, გადახდების განსახორციელებლად და ა.შ. --- # გამონაკლისი შემთხვევები Source: https://api.bog.ge/docs/paymentgateway/error-flow შემდეგი მონაკვეთი შეიცავს ინფორმაციას სხვადასხვა მარშრუტებთან დაკავშირებით, რომელიც BOG-ის გადახდის სისტემას შეუძლია აიღოს გადახდის ოპერაციის ფარგლებში მოცემული გარემოებების მიხედვით. გაითვალისწინეთ, რომ BOG-ის მხრიდან სტატუსის „ტრანზაქცია მიმდინარეობს“ ([კოდი 14](https://api.bog.ge/docs/paymentgateway/error-codes)) დამუშავება, შეიძლება შეიცვალოს. ![განახლებული პროტოკოლის შეცდომის მარშრუტი](./media/protocol-error-flow.png) --- # შეცდომის კოდები Source: https://api.bog.ge/docs/paymentgateway/error-codes |კოდი | აღწერა | |-----|--------------------------------| |0 |OK| |1 |Access Denied| |2 |Invalid username or password| |3 |Invalid hash code| |4 |Missing parameter| |5 |Invalid parameter| |6 |Customer does not exist| |7 |Invalid Amount| |8 |Payment id is not unique| |9 |Payment is not possible| |10 |Unknown service| |11 |Unknown operation type| |12 |Transaction was successful| |13 |Invalid transaction| |14 |Transaction in progress| |99 |General error| ამავე დროს, სერვის-პროვაიდერმა შეიძლება შემოიღოს შეცდომათა ისეთი კოდები, რომლებიც არ არიან ამ ცხრილში. კოდები არ უნდა შედიოდნენ 0-99 დიაპაზონში. უნდა აღინიშნოს ისიც რომ პროტოკოლი არ აძლევს გარანტიას სერვის-პროვაიდერს რომ მის მიერ გამოგზავნილი კოდის (გარდა ამ დოკუმენტით განსაზღვრული მნიშვნელობებისა) შესაბამის ტექსტს დაინახავს ყველა მომხმარებელი. ამიტომ საკუთარი კოდების დაბრუნება მხოლოდ განსაკუთრებულ შემთხვევებშია მიზანშეწონილი. --- # აუტენთიფიკაცია Source: https://api.bog.ge/docs/installment/authentication # აუტენთიფიკაცია ⚠️(Deprecated) ## რა დამჭირდება განვადების API-ს გამოსაყენებლად ონლაინ განვადების API-ს გამოსაყენებლად საჭიროა ავთენტიფიკაცია [HTTP Basic Auth](https://en.wikipedia.org/wiki/Basic_access_authentication)-ის გამოყენებით. ამისთვის თქვენ დაგჭირდებათ, იცოდეთ სისტემაში შესასვლელი რეკვიზიტები (Credentials), რომელიც თითოეული მერჩანტისთვის უნიკალურია. რეკვიზიტები მოიცავს ორ პარამეტრს: client_id და secret_key, რომელიც გამოიყენება, როგორც username-ი და password-ი, მერჩანტის ავთენტიფიკაციისას. ეს პარამეტრები გადმოეცემა კომპანიას, ბანკში მერჩანტად რეგისტრაციისას (იხილეთ: [როგორ გავიგოთ მერჩანტის სისტემაში შესასვლელი რეკვიზიტები](introduction#%E1%83%A0%E1%83%9D%E1%83%92%E1%83%9D%E1%83%A0-%E1%83%92%E1%83%90%E1%83%95%E1%83%98%E1%83%92%E1%83%9D%E1%83%97-%E1%83%9B%E1%83%94%E1%83%A0%E1%83%A9%E1%83%90%E1%83%9C%E1%83%A2%E1%83%98%E1%83%A1-%E1%83%A1%E1%83%98%E1%83%A1%E1%83%A2%E1%83%94%E1%83%9B%E1%83%90%E1%83%A8%E1%83%98-%E1%83%A8%E1%83%94%E1%83%A1%E1%83%90%E1%83%A1%E1%83%95%E1%83%9A%E1%83%94%E1%83%9A%E1%83%98-%E1%83%A0%E1%83%94%E1%83%99%E1%83%95%E1%83%98%E1%83%96%E1%83%98%E1%83%A2%E1%83%94%E1%83%91%E1%83%98)) მაგალითი: ```properties client_id: 1006 secret_key: 581ba5eeadd657c8ccddc74c839bd3ad Header: Authorization: Basic MTY2Njo1ODFiYTVlZWFkZDY1N2M4Y2NkZGM3NGM4MzliZDNhZA== ``` ### მეთოდის აღწერა მოცემული მეთოდის საშუალებით, მერჩანტი გადის ავთენტიფიკაციას. გამოძახების შედეგად, ონლაინ განვადების სერვერის მიერ ბრუნდება Bearer Token, რომელიც ყველა შემდგომი მეთოდის გამოძახებისთვის არის ავთენტიფიკაციისათვის აუცილებელი პარამეტრი. ### Header-ის პარამეტრები - `Content-Type` — application/x-www-form-urlencoded, required - `Authorization` — Basic , required გადაეცემა „Basic „ + „:“ მნიშვნელობა კოდირებული Base64 ფორმატში (მაგ: „Basic ODI4Mjo3Njk3MDY0OTlmMDcwOWUyMzQ4NDU4NjNmOThiMjMxNA==“), სადაც და არის, ბანკის მიერ მერჩანტისთვის გადაცემული, სისტემაში შესვლისთვის საჭირო რეკვიზიტები ### Body-ს პარამეტრები - `grant_type` — client_credentials, required მნიშვნელობად გადაეცემა ფიქსირებული ტექსტი: `client_credentials` **request** ```api POST /v1/oauth2/token HTTP/1.1 Content-Type: application/x-www-form-urlencoded Authorization: Basic ``` ```properties grant_type=client_credentials ``` ### Response - `access_token` — string ავტორიზაციის სერვერის მიერ დაბრუნებული Token-ის მნიშვნელობა - `token_type` — string Token-ის ტიპი (ბრუნდება ტექსტური მნიშვნელობა - `bearer`) - `app_id` — string არ გამოიყენება - `expires_in` — number აბრუნებს რიცხვით მნიშვნელობას, თუ რამდენი წამის განმავლობაში არის აქტიური Token. **response** ```json { "access_token": "", "token_type": "Bearer", "app_id": "1A2019", "expires_in": 1634719923245 } ``` --- # Callback Source: https://api.bog.ge/docs/installment/callback # Callback ⚠️(Deprecated) განსხვავებით სხვა მეთოდებისგან, როდესაც გამოძახების ინიციატორი იყო ონლაინ მაღაზია, `callback` მეთოდის გამოძახება ონლაინ განვადების სისტემიდან ხდება, ხოლო ინფორმაციის მიღება და დამუშავების ლოგიკა ონლაინ მაღაზიის მხარეს უნდა იყოს რეალიზებული. ეს მეთოდი საშუალებას გაძლევთ, რეალურ დროში მიიღოთ ინფორმაცია განვადების სტატუსის ცვლილების შესახებ. თითოეული ონლაინ მაღაზიისთვის callback მისამართების გაწერა ხდება მისი ბანკში მერჩანტად დარეგისტრირების დროს. განვადების სისტემაში ხდება ორი ტიპის `callback` url-ის გაწერა: - [განვადების სტატუსის შეცვლისას](#განვადების-სტატუსის-callback) - [განვადების გაუქმების](#განვადების-გაუქმების-callback) შემდგომში, უკვე განვადების სტატუსის ყოველი ცვლილების დროს, წინასწარ გაწერილ callback მისამართზე იგზავნება POST მეთოდით განვადების დეტალები. პასუხის წარმატებით მიღების დასადასტურებლად, მერჩანტმა უნდა დააბრუნოს HTTP CODE `200`. ინფორმაციის წარუმატებლად გაგზავნის შემთხვევაში, ყოველ 15 წამში, იგზავნება განმეორებითი მოთხოვნა, სანამ მცდელობის რაოდენობა არ მიაღწევს 5-ს ან მერჩანტი არ დააბრუნებს HTTP CODE `200` სტატუსს. თუ ვერ მოხერხდა callback-ის წარმატებით გამოძახება (გამოძახებისთვის განკუთვნილი დრო ამოიწურა ან მერჩანტმა დააბრუნა `200`-სგან განსხვავებული კოდი), მომხმარებელი გადამისამართდება reject_redirect_url-ზე და ქოლბექი აღარ გაიგზავნება. ამ შემთხვევაში, მერჩანტმა უნდა გამოიძახოს განვადების დეტალების მეთოდი განვადების სტატუსის მისაღებად. :::note თუ უკვე იყენებთ [ონლაინ გადახდებს](https://api.bog.ge/docs/docs/ipay/introduction), ონლაინ განვადების ქოლბექ მისამართები იქნება იგივე რაც ონლაინ გადახდების შემთხვევაში, მაგრამ პარამეტრები იქნება განსხვავებული. ::: ### Body-ს პარამეტრები - `status` — string განვადების სტატუსი. იღებს შემდეგ მნიშვნელობებს: - success - განვადების პროცესი დასრულდა წარმატებით. - error - განვადების პროცესი დასრულდა წარუმატებლად. - `order_id` — string შეკვეთის იდენტიფიკატორი, რომელიც ონლაინ მაღაზიას უბრუნდება შეკვეთის მოთხოვნის Response-ში. - `shop_order_id` — string მერჩანტის გადახდის იდენტიფიკატორი. - `payment_method` — string გადახდის მეთოდი. განვადების შემთხვევაში ყოველთვის ბრუნდება `BOG_LOAN` **request** ```api POST / ბანკში მერჩანტად რეგისტრაციისას მითითებული მისამართი Content-Type: application/x-www-form-urlencoded ``` ```json { "status": "success" | "error", "order_id": "{order_id}", "shop_order_id": "{shop_order_id}", "payment_method": "BOG_LOAN" } ``` ### Response - `Http_Status` — string მეთოდის გამოძახება ითვლება წარმატებულად, თუ მერჩანტის სერვერიდან დაბრუნდა 200 HTTP სტატუსი. **response** ```json { "Http_Status":"200 OK" } ``` ### განვადების სტატუსის callback **RESPONSE** ```properties Content-Type: application/x-www-form-urlencoded Request Method: POST ``` ```properties status: success | error order_id: string shop_order_id: string payment_method: BOG_LOAN | UNKNOWN ``` ### განვადების გაუქმების callback **RESPONSE** ```properties Content-Type: application/x-www-form-urlencoded Request Method: POST ``` ```properties status: reverse_success order_id: string shop_order_id: string payment_method: BOG_LOAN ``` --- # შეკვეთის მოთხოვნა Source: https://api.bog.ge/docs/installment/create-order # შეკვეთის მოთხოვნა ⚠️(Deprecated) მეთოდის საშუალებით, ონლაინ მაღაზია ონლაინ განვადების სერვერზე აგზავნის გადახდის დეტალებს, ტექნიკურ მახასიათებლებსა და გადასახდელ თანხას. ოპერაციის წარმატებით დასრულების შემთხვევაში, პროცესის გასაგრძელებლად, მომხმარებელი უნდა გადაამისამართოთ ონლაინ განვადების გვერდზე, `links` პარამეტრში დაბრუნებულ `REDIRECT` მისამართზე. ### Header-ის პარამეტრები - `Content-Type` — application/json, required - `Authorization` — Bearer , required გადაეცემა „Bearer “ მნიშვნელობა, სადაც jwt_token არის ავთენტიფიკაციის მეთოდის Response-ის access_token პარამეტრში დაბრუნებული მნიშვნელობა. ### Body-ს პარამეტრები - `intent` — string, required პარამეტრი განსაზღვრავს, რომელი გადახდის მეთოდით იხდის მომხმარებელი. განვადების ინტეგრაციის დროს ყოველთვის გადაეცემა `LOAN` მნიშვნელობა. - `installment_month` — string, required მომხმარებლის მიერ არჩეული განვადების თვეების რაოდენობა. განვადების თვეებისა და ტიპების მისაღებად უნდა გამოიყენოთ [განვადების კალკულატორის](get-discounts.md) სერვისი. - `installment_type` — string, required მომხმარებლის მიერ არჩეული განვადების ტიპი. - `shop_order_id` — string, required შეკვეთის იდენტიფიკატორი ონლაინ მაღაზიის სისტემიდან (მაგალითად: შესყიდვების კალათის იდენტიფიკატორი). - `success_redirect_url` — string, required მისამართი რომელზეც მომხმარებელი გადამისამართდება განვადების წარმატებით გააქტიურების შემთხვევაში. განვადების გააქტიურების შემდეგ მერჩანტთან იგზავნება ქოლბექი, რომელზეც უნდა დააბრუნოს `200` HTTP კოდი და ამის შემდეგ მომხმარებელი გადამისამართდება მითითებულ მისამართზე. იმ შემთხვევაში, თუ მერჩანტმა დააბრუნა სხვა HTTP კოდი, მომხმარებელი გადამისამართდება `reject_redirect_url`-ზე, სტატუსი დარჩება წარმატებული და მერჩანტმა სტატუსის გასაგებად [განვადების დეტალების](installment-details.md) სერვისი უნდა გამოიძახოს. - `fail_redirect_url` — string, required მისამართი, რომელზეც მომხმარებელი გადამისამართდება იმ შემთხვევაში, თუ განვადების აქტივაციის დროს დაფიქსირდება შეცდომა. - `reject_redirect_url` — string, required მისამართი, რომელზეც მომხმარებელი გადამისამართდება იმ შემთხვევაში, თუ რომელიმე აქტივაციისგან განსხვავებულ ეტაპზე დაფიქსირდა შეცდომა, ან განვადების აქტივაციის შემდეგ მერჩანტმა `200` HTTP კოდისგან განსხვავებული კოდი დააბრუნა, ან ქოლბექი გავიდა ტაიმაუტზე. - `validate_items` — boolean მოცემული პარამეტრის მიხედვით, ერთმანეთს შეედარება კალათაში მოთავსებული ნივთების ფასების ჯამი და შეკვეთის ჯამური თანხა. პარამეტრის არგადმოცემის შემთხვევაში მნიშვნელობა იქნება `true` - `true` გადმოცემის შემთხვევაში, ერთმანეთს შეედარება ნივთების ფასების ჯამი და შეკვეთის ჯამური რაოდენობა. სხვაობის შემთხვევაში დაფიქსირდება შეცდომა. - `false` გადმოცემის შემთხვევაში, ნივთების ფასების ჯამი და შეკვეთის ჯამური თანხა ერთმანეთს არ შეედარება, მაგრამ კალათაში მოთავსებული ნივთების ფასი უნდა იყოს 0-ზე მეტი. - `locale` — ka განსაზღვრავს, ონლაინ განვადების გვერდზე გადამისამართების შემდეგ, რომელი ენის ინტერფეისი დახვდება მომხმარებელს. ამჟამად ხელმისაწვდომია მხოლოდ `ka` - ქართული. - `purchase_units` — array, required მოცემულია ინფორმაცია განვადების თანხისა და ვალუტის შესახებ. - `amount` — object, required განვადების თანხის ობიექტი. - `currency_code` — string, required განვადების ვალუტა. - `value` — number, required განვადების თანხის მნიშვნელობა. - `cart_items` — array, required ონლაინ მაღაზიაში, მოცემული გადახდის ფარგლებში, შესყიდული პროდუქტების სია, რომელიც მოიცავს შემდეგ ატრიბუტებს - `total_item_amount` — string, required პროდუქტის ჯამური ფასი. მაგალითად, თუ პროდუქტის ფასი არის 50 ₾ და რაოდენობა 2, პარამეტრში უნდა გადასცეთ 100₾ - `item_description` — string, required შესყიდული პროდუქტის დასახელება (აღწერა) - `total_item_qty` — number, required შესყიდული პროდუქტის რაოდენობა - `item_vendor_code` — string, required შესყიდული პროდუქტის იდენტიფიკატორი ონლაინ მაღაზიის სისტემაში - `product_image_url` — string პროდუქტის სურათის ვებმისამართი (URL) - `item_site_detail_url` — string პროდუქტის ვებმისამართი ონლაინ მაღაზიის გვერდზე **request** ```api POST /v1/installment/checkout HTTP/1.1 Content-Type: application/json Authorization: Bearer ``` ```json { "intent": "LOAN", "installment_month": 6, "installment_type": "STANDARD", "shop_order_id": "123456", "success_redirect_url": "https://demo.ipay.ge/success", "fail_redirect_url": "https://demo.ipay.ge/fail", "reject_redirect_url": "https://demo.ipay.ge/reject", "validate_items": true, "locale": "ka", "purchase_units": [ { "amount": { "currency_code": "GEL", "value": "500.00" } } ], "cart_items": [ { "total_item_amount": "10.50", "item_description": "test_product", "total_item_qty": "1", "item_vendor_code": "123456", "product_image_url": "https://example.com/product.jpg", "item_site_detail_url": "https://example.com/product" } ] } ``` ### Response - `status` — string ონლაინ განვადების სტატუსი. - `links` — array ვებრესურსის მისამართები, რომელიც განვადების პროცესის შემდგომ ეტაპებზე გამოიყენება. ამჟამად links პარამეტრი აბრუნებს ორ რესურსს: - განვადების დეტალების მისამართი, რომლის საშუალებითაც შეგვიძლია გავიგოთ ინფორმაცია ონლაინ განვადების შესახებ (ამ რესურსის rel პარამეტრი იღებს მნიშვნელობას - self). - ვებგვერდის მისამართი, რომელზეც უნდა გადავიდეს მომხმარებელი ონლაინბანკინგის მონაცემების შესაყვანად და განვადების პროცესის დასასრულებლად (ამ რესურსის rel პარამეტრი იღებს მნიშვნელობას - target). - `href` — string ვებრესურსის მისამართი - `rel` — string ვებრესურსის უნიკალური დასახელება - `method` — string http - ვებრესურსზე გადასასვლელი მეთოდი (GET, REDIRECT…) - `order_id` — string ონლაინ განვადების შეკვეთის იდენტიფიკატორი. **response** ```json { "status": "CREATED", "links": [ { "href": "https://installment-test.bog.ge/v1/installment/checkout/{order_id}", "rel": "self", "method": "GET" }, { "href": "https://installment-test.bog.ge/?order_id={order_id}&locale=ka", "rel": "target", "method": "REDIRECT" } ], "order_id": "{order_id}" } ``` --- # სამართავი პანელი Source: https://api.bog.ge/docs/installment/dashboard # ონლაინ განვადების სამართავი პანელი ⚠️(Deprecated) `საქართველოს ბანკის` ონლაინ განვადების სამართავად პანელი მოგიმზადეთ. ეს სამართავი პანელი ვებაპლიკაციაა, რომელშიც მომხმარებელი თავისი ბიზნეს ინტერნეტბანკის მონაცემებით შედის. მომხმარებლებს შეუძლიათ, ჩვენი სამართავი პანელიდან თვალი ადევნონ, საკუთარი ელ.კომერციის პლატფორმებიდან, `საქართველოს ბანკის` ონლაინ განვადებით შესრულებულ ოპერაციებს. თითოეული განვადების დეტალების, მათი უნიკალური იდენტიფიკატორის, კალათის ღირებულების, შემადგენლობის თუ მიმდინარე სტატუსის ნახვა სამართავი პანელიდან მარტივად არის შესაძლებელი. აქედანვე შეძლებთ განვადების გაუქმების მოთხოვნას ან მომხმარებლის მიერ მობილბანკიდან მოთხოვნილი გაუქმების დადასტურებას. ჩვენ ასევე გაწვდით მონაცემების სტატისტიკას, სადაც შეძლებთ, გაეცნოთ განვადების დამტკიცების, გააქტიურებისა და გაუქმების კოეფიციენტებს. პანელზე ასევე დაგხვდებათ თითოეული სტატუსისა და თარიღის ჭრილში შესრულებული განვადებების სტატისტიკური ინფორმაციაც. სამართავი პანელის სანახავად ეწვიეთ ვებგვერდს - [merchant.bog.ge](https://merchant.bog.ge). თქვენს პროფილზე შესასვლელად გამოიყენეთ [bonline.bog.ge](https://bonline.bog.ge)-ს მომხმარებელი და პაროლი. ![Online Installment Dashboard](../assets/installment-dashboard.png) --- # განვადების კალკულატორი Source: https://api.bog.ge/docs/installment/get-discounts # განვადების კალკულატორი ⚠️(Deprecated) [შეკვეთის მოთხოვნამდე](create-order.md) აუცილებელია, მომხმარებელს არჩეული ჰქონდეს განვადების ვადა და ფასდაკლების მეთოდი. ამიტომ [შეკვეთის მოთხოვნის](create-order.md) სერვისის გამოძახებამდე უნდა გამოიყენოთ განვადების კალკულაციის მეთოდი, რომელიც, სასურველი პროდუქციის ღირებულების მიხედვით, გვიბრუნებს განვადების ყველა შესაძლო ვადის (თვეებში), ტიპისა და ყოველთვიურად გადასახდელი თანხის სამეულებს. დაბრუნებული სიიდან მომხმარებელმა უნდა აირჩიოს სასურველი და [შეკვეთის მოთხოვნა](create-order.md) სერვისს გადასცეთ. ასევე ამ სიის მისაღებად შეგიძლიათ გამოიყენოთ ბანკის [JS SDK](modal.md) :::note გაითვალისწინეთ ფასდაკლებების ტიპები და თვეების რაოდენობა მერჩანტზე ინდივიდუალურად იწერება. შესაბამისად, სხვადასხვა მერჩანტისთვის განსხვავებული მნიშვნელობები შეიძლება დაბრუნდეს. ::: ### Header-ის პარამეტრები - `Content-Type` — application/json, required - `Authorization` — Bearer , required გადაეცემა „Bearer “ მნიშვნელობა, სადაც jwt_token არის ავთენტიფიკაციის მეთოდის Response-ის access_token პარამეტრში დაბრუნებული მნიშვნელობა. ### Body-ს პარამეტრები - `amount` — object, required განვადების ჯამური თანხა - `client_id` — string, required მერჩანტის უნიკალური იდენტიფიკატორი, რომელიც კომპანიას რეგისტრაციის შემდეგ გადაეცემა **request** ```api POST /v1/services/installment/calculate HTTP/1.1 ``` ```properties amount=1000.00 client_id=1006 ``` ### Response - `discounts` — array მოცემული განვადების ფარგლებში, შესაძლო ყველა პირობის სია, რომელიც მოიცავს შემდეგ ატრიბუტებს: - `month` — number განვადების ხანგრძლივობა თვეებში - `amount` — string განვადების ყოველთვიური გადასახდელი თანხა - `discount_code` — string განვადების ფასდაკლების კოდი **response** ```json [ { "month": 3, "amount": "333.33", "discount_code": "ZERO" }, { "month": 4, "amount": "250.0", "discount_code": "ZERO" }, { "month": 6, "amount": "175.72", "discount_code": "STANDARD" }, { "month": 12, "amount": "93.50", "discount_code": "STANDARD" }, { "month": 24, "amount": "52.73", "discount_code": "STANDARD" }, { "month": 36, "amount": "39.44", "discount_code": "STANDARD" }, { "month": 48, "amount": "33", "discount_code": "STANDARD" } ] ``` --- # განვადების დეტალების მიღება Source: https://api.bog.ge/docs/installment/installment-details # განვადების დეტალების მიღება ⚠️(Deprecated) მეთოდის საშუალებით, ონლაინ მაღაზიას აქვს შესაძლებლობა, შეკვეთის იდენტიფიკატორის მიხედვით, მიიღოს დეტალური ინფორმაცია მომხმარებლის მიერ შესრულებული ონლაინ განვადების სტატუსის შესახებ. ### Header-ის პარამეტრები - `Content-Type` — application/json, required - `Authorization` — Bearer , required გადაეცემა „Bearer “ მნიშვნელობა, სადაც jwt_token არის ავთენტიფიკაციის მეთოდის Response-ის access_token პარამეტრში დაბრუნებული მნიშვნელობა. - `order_id` — number, required ონლაინ განვადების შეკვეთის იდენტიფიკატორი, რომელიც ონლაინ მაღაზიას უბრუნდება შეკვეთის მოთხოვნის Response-ში. **request** ```api GET /v1/installment/checkout/ HTTP/1.1 Content-Type: application/x-www-form-urlencoded Authorization: Basic ``` ## Response - `order_id` — string, required შეკვეთის იდენტიფიკატორი, რომელიც მოცემული მეთოდის Request-ში გადაეცემა. - `status` — string, required შეკვეთის სტატუსი. იღებს შემდეგ მნიშვნელობებს: - `success` - განვადების პროცესი დასრულდა წარმატებით - `in_progress` - განვადების პროცესი მიმდინარეობს და დასრულებული არაა. თუ შეკვეთის გენერაციიდან 45 წუთში მომხმარებელმა არ დაასრულა განვადების პროცესი, შეკვეთა გადავა `error` სტატუსზე - `error` - განვადების პროცესი დასრულდა წარუმატებლად - `installment_status` — string, required განვადების სტატუსი - `success` - განვადება წარმატებით გააქტიურდა. ამ შემთხვევაში ორდერის სტატუსიც `success` არის - `reject` - განვადება არ დამტკიცდა. ორდერერის სტატუსი იქნება `error`. - `reverse_success` - განვადება გაუქმებულია მომხმარებლის მოთხოვნის საფუძველზე ან მერჩანტმა პირდაპირ გააუქმა [სამართავი პანელის დეშბორდიდან](https://merchant.bog.ge/). - `fail` - განვადება არ გააქტიურდა. ორდერის სტატუსი იქნება `error` - `unknown` - განვადების მოცემული სტატუსი იქნება იმ შემთხვევაში, თუ განვადება არაა დასრულებული და ორდერის სტატუსი არის `in_progress`. - `ipay_payment_id` — string, required გადახდის იდენტიფიკატორი `ipay` სისტემაში (ჩანს, ასევე, გადახდის ქვითარზე). - `shop_order_id` — string, required მერჩანტის შეკვეთის იდენტიფიკატორი - `payment_method` — string, required გადახდის მეთოდი. განვადების შემთხვევაში ყოველთვის ბრუნდება `BOG_LOAN`. **response** ```json { "order_id": "{order_id}", "status": "success" | "in_progress" | "error", "installment_status": "success" | "reject" | "reverse_success" | "fail" | "unknown", "ipay_payment_id": "{ipay_payment_id}", "shop_order_id": "{shop_order_id}", "payment_method": "BOG_LOAN" } ``` --- # შესავალი Source: https://api.bog.ge/docs/installment/introduction # შესავალი ⚠️(Deprecated) iPay-ის ინტეგრაცია აღარ არის შესაძლებელი. საქართველოს ბანკის გადახდის მეთოდების ინტეგრაციისთვის გამოიყენეთ [გადახდების მენეჯერის ტექნიკური დოკუმენტაცია.](https://api.bog.ge/docs/docs/payments/introduction) ### რა არის ონლაინ განვადების API განვადება ერთ-ერთი მნიშვნელოვანი პროდუქტია საცალო ბიზნესში და ბოლო დროს განსაკუთრებით მოთხოვნადი გახდა ციფრულ ინდუსტრიაში. "საქართველოს ბანკი" გთავაზობთ მარტივი ინტეგრაციით გამორჩეულ გადაწყვეტილებას. ონლაინ განვადებების API გაძლევთ საშუალებას, მარტივად ჩააშენოთ განვადებების მოდული ნებისმიერი ტიპის ონლაინ მაღაზიაში ან ელექტრონული გადახდების სისტემაში. ### რა არის საჭირო ინტეგრაციისთვის განვადების ინტეგრაციის დასაწყებად აუცილებელია, რომ ონლაინ მაღაზიის მფლობელ ორგანიზაციას ჰქონდეს [bonline.bog.ge](https://bonline.bog.ge) ანგარიში და სისტემაში შესასვლელი რეკვიზიტები. "ჰქონდეს [bonline.bog.ge](https://bonline.bog.ge) ანგარიში" ნიშნავს, რომ ორგანიზაციას აქვს მოქმედი ანგარიში "საქართველოს ბანკში" და იურიდიული პირის ინტერნეტ ბანკში შესვლის უფლება. ### პროტოკოლი და ტექნიკური სპეციფიკაცია API-ს არქიტექტურული მიდგომა - Restful. ონლაინ განვადების აპლიკაციის პროტოკოლი: HTTP/1.1. უსაფრთხოების გაზრდის მიზნით, აუცილებელია API-ს ყველა მეთოდის გამოძახება https-ის გამოყენებით, რომელიც წარმოადგენს http პროტოკოლის გაფართოებას. სერვისის გამოძახების ტიპი - სინქრონული. უსაფრთხოების პროტოკოლი - OAuth 2.0. მხარეებს შორის ინფორმაციის გაცვლის უსაფრთხოების სტანდარტი - JSON Web Tokens (JWT). **base** ```url https://installment.bog.ge/v1/ ``` ### როგორ გავიგოთ მერჩანტის სისტემაში შესასვლელი რეკვიზიტები მას შემდეგ, რაც კომპანია დარეგისტრირდება მერჩანტად საბანკო სისტემაში და შეავსებს ყველა საჭირო მონაცემს, მას მიენიჭება და გადაეცემა სისტემაში შესასვლელი რეკვიზიტები client_id და secret_key. მერჩანტად რეგისტრაციისთვის, კომპანიის წარმომადგენელმა უნდა შეავსოს შესაბამისი ფორმა ვებგვერდზე bonline.ge ან დაუკავშირდეს ბანკის წარმომადგენელს და მიაწოდოს საჭირო მონაცემები. რეკვიზიტები მერჩანტის უნიკალური მაიდენტიფიცირებელია. ამასთან, secret_key პაროლის მნიშვნელობის პარამეტრია - მისი სხვა პირისთვის გადაცემა, გასაჯაროება დაუშვებელია. ამან შეიძლება ონლაინ მაღაზიისთვის საფრთხის რისკი მნიშვნელოვნად გაზარდოს! Secret_key-ს ცვლილება მერჩანტის მიერ შეუძლებელია. **base** ```properties client_id = XXXX (მერჩანტის უნიკალური იდენტიფიკატორი) secret_key = XXXXXXXXXXXXXXXXXXXXXXXXXXXX (API პაროლი) ``` :::caution გასათვალისწინებელია, რომ **secret_key**-ს გაზიარება გარეშე უცხო პირისთვის მაღალი რისკის შემცველია და შეიძლება საფრთხის შემცველი იყოს თქვენი ორგანიზაციისთვის. ::: ### მოსამზადებელი სამუშაო წარმოგიდგენთ ონლაინ განვადების რეგისტრაციისა და მოსამზადებელი სამუშაოების სრული ციკლის მოკლე მიმოხილვას: - მერჩანტი ავსებს API-ს რეგისტრაციის ფორმას ვებგვერდზე [bonline.bog.ge](https://bonline.bog.ge), ხოლო დასრულების შემდეგ უბრუნდება client_id და secret_key, რაც გულისხმობს იმას, რომ ინტეგრაციის დაწყება ტექნიკურად შესაძლებელია - მერჩანტი ირჩევს ინტეგრაციის სასურველ მიდგომას (მარტივი ინტეგრაცია, SDK, API) - ინტეგრაციის შემდეგ, აუცილებელია პროდუქტის საფუძვლიანი შემოწმება ბანკის მიერ მომზადებულ სატესტო გარემოში და საცდელი ტრანზაქციის შესრულება - წარმატებული სატესტო ტრანზაქციის შემდეგ, მერჩანტი საიტის/საწყობის მხარეს ასახავს ინფორმაციას - ამის შემდეგ, სატესტო მონაცემები შეიცვლება რეალური მონაცემებით და განვადება მზად იქნება გასაშვებად! ### ინტეგრაციის პროცესის მოკლე აღწერა წარმოგიდგენთ ონლაინ განვადების ინტეგრაციის სრული ციკლის მოკლე მიმოხილვას: - მომხმარებელი აჭერს განვადების ღილაკს, ონლაინ მაღაზიის საიტზე და ირჩევს განვადების თვესა და ტიპს (სტანდარტული, ფასდათმობით და 0%) - ონლაინ მაღაზია აგზავნის მოთხოვნას ბანკის სერვერზე (შეკვეთის შექმნა) - ბანკის სერვერი აბრუნებს გადახდისთვის საჭირო პარამეტრებს და განვადების საიტზე გადმომისამართების ლინკს `https://installment.bog.ge/?order_id=xxx....xxx&locale=ka` - მომხმარებელი გადამისამართდება ონლაინ განვადების საიტზე - განვადების საიტზე სრულდება განავდების აქტივაციისთვის საჭირო ქმედებები - ბანკის სერვერი უბრუნებს პასუხს ონლაინ მაღაზიას (callback) - ონლაინ მაღაზია ამოწმებს განვადების სტატუსს და აბრუნებს შესაბამის HTTP კოდს - ბანკის სერვერი ამისამართებს მომხმარებელს ონლაინ მაღაზიის საიტზე განვადების სტატუსის მიხედვით (success, error) :::note [იხილე სწრაფი და მარტივი ინტერგრაციის მეთოდები კოდის წერის გარეშე](plugins) ::: --- # ონლაინ განვადების მოდალი Source: https://api.bog.ge/docs/installment/modal ## ონლაინ განვადების მოდალი ⚠️(Deprecated) ონლაინ განვადების პირობების ასარჩევად, სპეციალური მოდალი დავამზადეთ. მოდალი არის ერთგვარი სესხის კალკულატორი, სადაც მომხმარებელს საშუალება აქვს, კალათის ღირებულებიდან გამომდინარე, საორიენტაციო ყოველთვიური გადასახადი და წლიური საპროცენტო განაკვეთი ნახოს. იქიდან გამომდინარე, რომ პირობები ყოველთვის ინდივიდუალურია და საქართველოს ბანკსა და მერჩანტს შორის დადებულ ხელშეკრულებას ეყრდნობა, ასევე სააქციო პირობები (მათ შორის 0%-იანი განვადების პირობა) განსხვავდება სტანდარტული პირობებისგან, ამ ინფორმაციის მსესხებლისთვის მიწოდება მნიშვნელოვანია. ყველა ეს ინფორმაცია მოდალზე არის დატანილი, რაც მომხმარებელს უფრო მეტად ეხმარება გადაწყვეტილების მიღებაში. შესაბამისად, განვადების აქტივაციამდე საჭიროა ერთგვარი სესხის კალკულატორი, რომელიც დამოუკიდებელი მიკროსერვისია და მერჩანტის საიტზე [ინტეგრაცია სჭირდება](authentication). "საქართველოს ბანკი" გთავაზობს კალკულატორის მზა SDK-ს, რომელიც თავსებადია ყველა მოწყობილობაზე (Desktop, Mobile, Tablet) და საჭიროებს მზა კოდის ფრაგმენტის დამატებას საიტზე. ![Online Installment Modal](../assets/installment-modal.png) ### მაგალითი: ### ინტეგრაცია განვადების მოდალის SDK ინტეგრაციის დასაწყებათ, დააკოპირეთ კოდი HTML გვერდში. `{client_id}`-ის მაგივრად ჩასვით თქვენი client_id. ```html ``` --- ### მოდალის ჩვენება ონლაინ განვადების მოდალის საჩვენებლად, გამოიყენეთ `BOG.Calculator.open` მეთოდი. #### პარამეტრები - `amount` — number, required განვადების თანხა - `bnpl` — boolean პარამეტრით განისაზღვრება მომხმარებელს გამოუჩნდეს `სტანდარტული განვადება` ან/და `ნაწილ-ნაწილ გადახდა`. - `true` - მომხმარებელს გამოუჩნდება მხოლოდ ნაწილ-ნაწილ გადახდა - `false` - მომხმარებელს გამოუჩნდება მხოლოდ სტანდარტული განვადება - `undefined` | `null` - მომხამრებელს გამოუჩნდება ორივე მეთოდი. - `onClose` — function მეთოდი, რომელიც გამოიძახება SDK-ს მიერ მომხმარებლის მხრიდან მოდალის დახურვის შემთხვევაში. - `onRequest` — function მეთოდი, რომელიც გამოიძახება SDK-ს მიერ მომხმარებლის მიერ პირობების არჩევის შემდეგ. ამ დროს უნდა მოხდეს განვადების [შეკვეთის მოთხოვნა](create-order) მეთოდს გადმოეცემა არგუმენტები: - `selected` - ობიექტი, რომელშიც გადმოეცემა მომხმარებლის მიერ არჩეული მონაცემები. - `amount` - ყოველთვე გადასახდელი თანხა - `month` - სესხის თვეების რაოდენობა - `discount_code` - ფასდაკლების კოდი - `successCb` - მეთოდი, რომელიც უნდა გამოიძახოთ, თუ გსურთ, რომ განვადების პროცესი SDK-მ გააგრძელოს. - `closeCb` - მეთოდი, რომელიც უნდა გამოიძახოთ, თუ გსურთ მოდალის დახურვა. - `onComplete` — function მეთოდი, რომელიც გამოიძახება SDK-ს მიერ ონლაინ განვადების პროცესის დასრულების შემდეგ. ამ დროს მომხმარებლის გადამისამართება ავტომატურად ხდება მერჩანტის წარმატების ლინკზე. თუ გსურთ, რომ არ მოხდეს გადამისამართება, მათოდში დააბრუნეთ `false` მნიშვნელობა (`return false;`). მეთოდს არტუმენტად გადმოეცემა ობიექტი, პარამეტრებით: - `redirectUrl` - ლინკი, სადაც უნდა გადამისამართდეს მომხარებელი. ### არსებობს პროცესის გაგრძელების ორი მეთოდი. 1. თუ გსურთ, რომ ონლაინ განვადების პროცესის გაგრძელება მოხდეს SDK-ს მიერ, `onRequest` მეთოდში, orderId-ის [გენერაციის შემდეგ](create-order), გამოიძახეთ `successCb`, რომელსაც გადასცემთ დაგენერირებულ `orderId` პარამეტრს. პროცესის დასრულების შემდეგ, გამოიძახება `onComplete` მეთოდი. 2. თუ SDK მხოლოდ კალკულატორისთვის გჭირდებათ და მომხმარებლის მიერ სასურველი პირობის არჩევის შემდეგ თქვენ თვითონ გააგრძელებინოთ მომხმარებელს პროცესი, `onRequest` მეთოდში დააბრუნეთ `false` მნიშვნელობა (`return false;`), რა დროსაც SDK პროცესს აღარ გააგრძელებს. ამ დროს მოდალი ღია რჩება. თუ გსურთ მოდალის დახურვა, გამოიყენეთ `closeCb` ან `Bog.Calculator.close()` მეთოდი ```js BOG.Calculator.open({ amount: 500, onClose: () => { // Modal close callback }, onRequest: (selected, successCb, closeCb) => { const { amount, month, discount_code } = selected; fetch('url-to-backend-api', { method: 'POST', body: JSON.stringify(selected) }) .then(response => response.json()) .then(data => successCb(data.orderId)) .catch(err => closeCb()); }, onComplete: ({redirectUrl}) => { return false; } }) ``` --- SDK ასევე საშუალებას გაძლევთ თქვენს საიტზე დაამატოთ საქართველოს ბანკის ღილაკი. მეთოდს გადაეცით DOM ელემენტი, სადაც გსურთ ღილაკის ჩასმა. ```html
``` --- # პლაგინები და ტექნიკური მხარდაჭერა Source: https://api.bog.ge/docs/installment/plugins ## პლაგინები და ტექნიკური მხარდაჭერა ⚠️(Deprecated) განვადების ინტეგრაციისთვის აუცილებელი არ არის, იყოთ გამოცდილი დეველოპერი. "საქართველოს ბანკს" ჰყავს პარტნიორი ორგანიზაციები, რომლებიც გთავაზობენ მზა პროდუქტს, რომელიც მხოლოდ ინსტალაციას საჭიროებს. აუცილებელი პირობაა, რომ თქვენი ონლაინ მაღაზია ტექნიკურად აკმაყოფილებდეს მათ მოთხოვნებს და დაწერილი იყოს შესაბამისი ტექნოლოგიების გამოყენებით. 1. WooCommerce Payment Gateway - პლაგინი, რომელიც მზად არის ინსტალაციისთვის. მერჩანტს პლაგინის აქტივაციისთვის სჭირდება API Key. დოკუმენტაციის სრული აღწერისთვის გადადით ბმულზე - [plugandpay.ge](https://plugandpay.ge/product/woocommerce-bog-installments-payment-gateway/) 2. CScart სისტემაზე დაწერილი ონლაინ მაღაზიის საიტისთვის განკუთვნილი პლაგინი. დოკუმენტაციის სრული აღწერისთვის გადადით ბმულზე - [cscart.ge](https://cscart.ge/ka/%E1%83%9D%E1%83%9C%E1%83%9A%E1%83%90%E1%83%98%E1%83%9C-%E1%83%9B%E1%83%90%E1%83%A6%E1%83%90%E1%83%96%E1%83%98%E1%83%98%E1%83%A1-%E1%83%9B%E1%83%9D%E1%83%93%E1%83%A3%E1%83%9A%E1%83%94%E1%83%91%E1%83%98/%E1%83%A1%E1%83%90%E1%83%A5%E1%83%90%E1%83%A0%E1%83%97%E1%83%95%E1%83%94%E1%83%9A%E1%83%9D%E1%83%A1-%E1%83%91%E1%83%90%E1%83%9C%E1%83%99%E1%83%98%E1%83%A1-%E1%83%9D%E1%83%9C%E1%83%9A%E1%83%90%E1%83%98%E1%83%9C-%E1%83%92%E1%83%90%E1%83%9C%E1%83%95%E1%83%90%E1%83%93%E1%83%94%E1%83%91%E1%83%90/) 3. b2c - პლატფორმა, რომელიც დაგეხმარებათ სრულყოფილი ონლაინ პლატფორმის აწყობაში, რომელშიც ავტომატურად იქნება განთავსებული "საქართველოს ბანკის" ონლაინ განვადება. დამატებითი ინფორმაციისთვის იხილეთ ბმული - [b2c.ge](https://www.b2c.ge/) --- # რეგულაციები და შეზღუდვები Source: https://api.bog.ge/docs/installment/regulation ## რეგულაციები და შეზღუდვები ⚠️(Deprecated) რეგულაციებისა და შეზღუდვების გაცნობამდე, აუცილებელია, რომ გავარჩიოთ ორი მნიშვნელოვანი პირობა "საქართველოს ბანკის" ონლაინ განვადების პროცესში, რომელიც ვრცელდება განვადების ამღებ პირზე. 1. მომხმარებელს შესაძლოა ჰქონდეს წინასწარ დამტკიცებული ლიმიტი. პირობითი სახელით - **ლიმიტი**. 2. მომხმარებელს შესაძლოა საერთოდ არ ჰქონდეს წინასწარ დამტკიცებული ლიმიტი ან ჰქონდეს არასაკმარისი. ასეთ დროს მომხმარებელი ითხოვს ახალ განაცხადს, რაც გულისხმობს მომხმარებლისგან თანხმობების მიღებას საკრედიტო ბიუროსა და შემოსავლების სამსახურში გადამოწმებაზე. პირობითი სახელით - **განაცხადი**. წარმატებით დამტკიცებული **განაცხადის** შემთხვევაშიც პროცესი ანალოგიურია. მაგალითად, მომხმარებლის სესხის ლიმიტი არის 200 ლარი, რომელიც არ ჰყოფნის სასურველი ნივთის შესაძენად. ამის გამო, მან მოითხოვა სესხი 1000 ლარის ოდენობით, რომელიც უკვე სრულად იქნება საკმარისი სასურველი ნივთის შესაძენად. მოთხოვნილი თანხის დამტკიცების შემთხვევაში, მომხმარებლისათვის 200-ლარიანი ლიმიტი შეიცვლება, გახდება 1000 და პროცესი ჩვეულებრივად გაგრძელდება. ასევე მნიშვნელოვანია, რომ ეროვნული ბანკის მიერ დადგენილი წესის მიხედვით, თუ მომხმარებელს მოთხოვნილი აქვს 3-თვიანი განვადება, რომლის ყოველთვიური შენატანი ცდება მისი შემოსავლების კოეფიციენტს, სისტემა ავტომატურად გადაითვლის მასზე მორგებულ საუკეთესო პირობას, ანუ მოთხოვნილ ვადასთან ყველაზე ახლოს მყოფი ვადით შესთავაზებს მოთხოვნილ განვადებას. თუ **განაცხადის** შემდეგ დამტკიცებული ლიმიტი არცერთი ვადით კვლავ არ აღმოჩნდა საკმარისი ნივთის სრულად შესაძენად, ავტომატურად დათვლილი კოეფიციენტით სისტემა ავტომატურად შესთავაზებს მომხმარებელს თანამონაწილეობის დამატებას. ### რეგულაციები განვადების ინტეგრაციამდე გასათვალისწინებელია რამდენიმე შეზღუდვა, რომელიც მოქმედებს "საქართველოს ბანკში" ეროვნული ბანკის რეგულაციებთან შესაბამისობაში. 1. განვადების მომთხოვნი პირი უნდა იყოს საქართველოს მოქალაქე. 2. ასაკი უნდა აღემატებოდეს 18 წელს. 3. თუ მომხმარებელი არ არის გადამოწმებული "კრედიტ ინფოში", საკრედიტო ისტორიის შემოწმების მიზნით, ვალდებულია, გადამოწმდეს. ისტორიას სისტემა თავად ამოწმებს, უბრალოდ, შესაბამის ტექსტს უნდა დაეთანხმოს მომხმარებელი. 4. თუ მომხმარებელს არ აქვს წინასწარ დამტკიცებული განვადება, ახალი **განაცხადის** შევსების დროს, გადამოწმდება შემოსავლების სამსახურში. ამ შემთხვევაშიც, სისტემა თავად გადაამოწმებს, მომხმარებელი, უბრალოდ, ეთანხმება შესაბამის ტექსტს. 5. განვადების მინიმალური და მაქსიმალური ლიმიტები განისაზღვრება - 45 ლარიდან 15000 ლარამდე (ამ შეზღუდვას ონლაინ განვადების პლატფორმა თავად ახდენს და მერჩანტის მხრიდან ჩარევას არ საჭიროებს). 6. განვადების მინიმალური და მაქსიმალური თვე განისაზღვრება - 3-დან 48 თვემდე (ამ შეზღუდვას ონლაინ განვადების პლატფორმა თავად ახდენს და მერჩანტის მხრიდან ჩარევას არ საჭიროებს) [დამატებითი ინფორმაცია რეგულაციებთან დაკავშირებით](https://matsne.gov.ge/ka/document/view/4822603?publication=0) ### შეზღუდვები შეზღუდვების ნაწილი მოიცავს "საქართველოს ბანკის" მიერ დადგენილ წესებს - კერძოდ, ღამის 12 საათიდან დილის 5 საათამდე განვადებით სარგებლობა არ არის შესაძლებელი, რადგან ამ დროს მიმდინარეობს საოპერაციო დღის დახურვა. მომხმარებელი შეძლებს **ლიმიტის** გადათვლას ან ახალი **განაცხადის** მოთხოვნა/დამტკიცებას, თუმცა განვადებას ვერ გაიაქტიურებს და მისით სარგებლობა შესაძლებელი იქნება 5 საათის შემდეგ. ერთი უნიკალური მომხმარებლის მიერ **განაცხადის** მოთხოვნა შესაძლებელია 24 საათში ერთხელ, განვადების ანუ **ლიმიტის** აქტივაციის მცდელობა შეუზღუდავია. განვადების გაუქმება შესაძლებელია განვადების აღებიდან 14 კალენდარული დღის ვადაში. --- # გამოყენებული ტერმინები Source: https://api.bog.ge/docs/installment/terms-used # გამოყენებული ტერმინები ⚠️(Deprecated) - განვადების მოდული - არის ონლაინ სისტემა, რომელიც საშუალებას გაძლევთ, მარტივად ჩააშენოთ განვადების გაცემის ფუნქციონალი ნებისმიერი ტიპის ონლაინ მაღაზიაში. - ონლაინ მაღაზია - ვებგვერდი ან აპლიკაცია, რომლის საშუალებითაც მომხმარებელს შეუძლია, შეიძინოს სასურველი ნივთი ან მომსახურება, ინტერნეტის გამოყენებით. - მერჩანტი - საცალო ვაჭრობის ან მომსახურების კომპანია, რომელსაც გააჩნია ონლაინ მაღაზია. - Callback - საბანკო სისტემიდან ონლაინ მაღაზიის მიერ გამოდგმული სერვისის გამოძახება, განვადების შესახებ განახლებული ინფორმაციის მიწოდების მიზნით. - სისტემაში შესასვლელი რეკვიზიტები - ბანკის სისტემაში კლიენტის იდენტიფიკატორი (client_id) და საიდუმლო გასაღები (secret_key), რომელსაც გადასცემს ბანკის მომხმარებელი ონლაინ მაღაზიას, მისი მერჩანტად წარმატებით დარეგისტრირების შემდეგ. --- # გამოყენებადი ნაშთი Source: https://api.bog.ge/docs/bonline/accounts # გამოყენებადი ნაშთი მეთოდის საშუალებით შესაძლებელია საბანკო ანგარიშის მიმდინარე და ხელმისაწვდომი ნაშთის გაგება. ## Query პარამეტრები - `accountNumber` — string, required ანგარიშის ნომერი. - `currency` — string, required ანგარიშის ვალუტა ISO 4217 ფორმატში (მაგალითად: USD, GEL). - `initStatementBalance` — boolean არჩევითი. თუ `true`, პასუხს დაემატება `StatementBalance` ველი. **REQUEST** ```api GET api/accounts/{accountNumber}/{currency} ``` ## დაბრუნებული პარამეტრები - `AvailableBalance` — decimal number ანგარიშზე ხელმისაწვდომი ნაშთი, დაბლოკილ სტატუსში არსებული ოპერაციების გათვალისწინებით. - `CurrentBalance` — decimal number მიმდინარე ნაშთი ანგარიშზე, დაბლოკილ სტატუსში არსებული ოპერაციების გარეშე. - `StatementBalance` — decimal number წინა ამონაწერის ნაშთი. ბრუნდება მხოლოდ მაშინ, როცა query პარამეტრი `initStatementBalance` მითითებულია `true`-ად. **JSON** ```json { "AvailableBalance": 1.0, "CurrentBalance": 2.0 } ``` **XML** ```xml 1 2 ``` --- # აუტენთიფიკაცია შესავალი Source: https://api.bog.ge/docs/bonline/auth/auth-introduction სერვისების გამოსაძახებლად პირველ რიგში თქვენი აპლიკაცია უნდა დაარეგისტრიროთ შემდეგ გვერდზე: [bonline.bog.ge/admin/api](https://bonline.bog.ge/admin/api/) რეგისტრაციისას უნდა მიუთითოთ აპლიკაციის სახელი, დასახელება უცხოურ ენაზე და თქვენთვის სასურველი ლოგოს მისამართი (სასურველია https პროტოკოლზე და ზომა არაუმეტეს 400x80 პიქსელისა). თუ არეგისტრირებთ web კლიენტს მაშინ ასევე უნდა მიუთითო გადამისამართების მისამართი რომელზეც მოხდება გადამისამართება აუტენტიფიკაციის დროს. რეგისტრაციის შემდეგ აპლიკაციის დეტალების გვერდზე გამოჩნდება აპლიკაციის იდენტიფიკატორები: (`client id`, `redirect uri` და `client secret` მხოლოდ web კლიენტის დროს), (`client id` და `client secret` მხოლოდ ტოკენით აუტენთიფიკაციის დროს) რომლებიც დაგჭირდებათ აუტენთიფიკაციის მოთხოვნის დროს. აუტენთიფიკაციის სამი მეთოდი არსებობს: - [დესკტოპ აპლიკაციების](desktop-authentication) - [ვებ აპლიკაციების](web-authentication) - [ტოკენით](token-authentication) --- # დესკტოპ აპლიკაციების Source: https://api.bog.ge/docs/bonline/auth/desktop-authentication # დესკტოპ აპლიკაციების აუტენთიფიკაცია დესკტოპ აპლიკაციისთვის ავთენტიფიკაცია ხორციელდება შემდეგი სქემით: 1. მომხმარებელი გადაიყვანეთ მისამართზე https://account.bog.ge/auth/realms/bog/protocol/openid-connect/auth, query string-ში მითითებული შემდეგი პარამეტრებით: - `client_id` - თქვენი აპლიკაციის `client id` - `response_type` - მნიშვნელობად გადაეცემა ფიქსირებული ტექსტი: `token` - `scope` - მნიშვნელობად გადაეცემა ფიქსირებული ტექსტი: `corp` - `redirect_uri` - მნიშვნელობად გადაეცემა თქვენი აპლიკაციის `redirect uri` - `kc_locale` - ინტერფეისის ენა: `ka` -ქართული ენის შემთხვევაში, ამ პარამეტრის გარეშე ინგლისური ენის შესაბამისი ინტერფეისი გამოჩნდება. მაგალითად, თუ თქვენი აპლიკაციის `client id` არის `implicitclient`, ხოლო `redirect uri` არის `https://example.com/callback` მაშინ ამ მისამართს ექნება ასეთი სახე (url კოდირების შემდეგ): https://account.bog.ge/auth/realms/bog/protocol/openid-connect/auth?client_id=implicitclient&response_type=token&scope=corp&redirect_uri=https%3A%2F%2Fexample.com%3A44312%2Fcallback&state=e46fcdf4-a4bf-4dc6-8a42-e1b12e27826b&kc_locale=ka 2. მომხმარებელი გადამისამართდება redirect_uri მისამართზე, query string-ში მითითებული შემდეგი პარამეტრით: - `access_token` - დროებითი ტოკენი - `expires_in` - ამოწურვის დრო - `token_type` - ტოკენის ტიპი 3. გაიარეთ ავთენტიფიკაცია HTTP Basic Auth-ის გამოყენებით. სერვისის გამოძახების შედეგად, სერვერის მიერ ბრუნდება Bearer Token, რომელიც შემდგომი მეთოდების გამოძახებისთვის არის ავთენტიფიკაციის პარამეტრი. ## Header-ის პარამეტრები - `Content-Type` — string, required გადაეცემა „application/x-www-form-urlencoded“ მნიშვნელობა - `Authorization ` — string, required ავთენტიფიკაცია `HTTP Basic Auth`-ის გამოყენებით. სახელად გამოიყენება თქვენი აპლიკაციის `client_id`, ხოლო პაროლად თქვენი აპლიკაციის `client_secret`. ## Body-ის პარამეტრები - `grant_type` — string, required მნიშვნელობად გადაეცემა ფიქსირებული ტექსტი: `client_credentials` - `code` — string, required დროებითი კოდი - `redirect_uri` — string, required მნიშვნელობად გადაეცემა თქვენი აპლიკაციის `redirect_uri`. ## დაბრუნებული პარამეტრები - `access_token` — string ავტორიზაციის სერვერის მიერ დაბრუნებული Token-ის მნიშვნელობა. - `token_type` — string Token-ის ტიპი (ბრუნდება ტექსტური მნიშვნელობა - `bearer`). - `app_id` — string არ გამოიყენება. - `expires_in` — string აბრუნებს რიცხვით მნიშვნელობას, თუ რამდენი წამის განმავლობაში არის აქტიური Token. - `refresh_expires_in` — string მაქსიმალური დრო, რომლის ამოწურვის შემდეგაც Token გახდება არავალიდური. გვაძლევს საშუალებას, ტოკენის განახლების დრო უფრო მცირე იყოს, ვიდრე სესიის. - `not-before-policy` — string გამოიყენება განახლების ან სესიის Token-ის კომპრომეტირების შემთხვევაში, როგორც დამატებითი დაცვის მექანიზმი. - `scope` — string OAuth 2.0 ავტორიზაციის სტანდარტული მექანიზმია. კონტექსტი, რომლის ფარგლებში Token-ს აქვს ქმედების უფლება. --- # ტოკენით Source: https://api.bog.ge/docs/bonline/auth/token-authentication # ტოკენით აუტენთიფიკაცია ხორციელდება შემდეგი სქემით: გააგზავნეთ POST მოთხოვნა შემდეგ მისამართზე: `https://account.bog.ge/auth/realms/bog/protocol/openid-connect/token` შემდეგი პარამეტრებით მოთხოვნის ტანში, application/x-www-form-urlencoded Content-Type-ით: - `grant_type` - "client_credentials" - `client_id` - თქვენი აპლიკაციის client_id - `client_secret` - თქვენი აპლიკაციის client_secret ეს მოთხოვნა უნდა გამოიძახოთ Basic`Authorization`Header-ით სადაც მომხმარებლის სახელად და პაროლად გამოიყენებთ თქვენი აპლიკაციის client_id-ის და client secret-ს ამის შემდეგ თქვენ შეგიძლიათ გამოიძახოთ სერვისები დაბრუნებული access_token-ის გამოყენებით. ამისათვის თქვენს მოთხოვნებს უნდა დაამატოთ `AuthorizationHeader` ასეთი სახით: `Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6ImEzck1VZ01Gdjl0UGNsTGE2eUYzekFrZnF1RSJ9.eyJpc..........` --- # ვებ აპლიკაციების Source: https://api.bog.ge/docs/bonline/auth/web-authentication # ვებაპლიკაციისთვის ვებაპლიკაციისთვის ავთენტიფიკაცია ხორციელდება შემდეგი სქემით: 1. მომხმარებელი გადაიყვანეთ მისამართზე https://account.bog.ge/auth/realms/bog/protocol/openid-connect/auth, query string-ში მითითებული შემდეგი პარამეტრებით: - `client_id` - თქვენი აპლიკაციის `client_id`. - `response_type` - მნიშვნელობად გადაეცემა ფიქსირებული ტექსტი: `code`. - `scope` - მნიშვნელობად გადაეცემა ფიქსირებული ტექსტი: `corp`. - `redirect_uri` - მნიშვნელობად გადაეცემა თქვენი აპლიკაციის `redirect uri`. - `kc_locale` - ინტერფეისის ენა. `ka` -ქართული ენის შემთხვევაში, ამ პარამეტრის გარეშე ინგლისური ენის შესაბამისი ინტერფეისი გამოჩნდება. მაგალითად, თუ თქვენი აპლიკაციის `client id` არის `codeclient`, ხოლო `redirect uri` არის `https://example.com/callback` მაშინ ამ მისამართს ექნება ასეთი სახე (url კოდირების შემდეგ): https://account.bog.ge/auth/realms/bog/protocol/openid-connect/auth?client_id=codeclient&response_type=code&scope=corp&redirect_uri=https%3A%2F%2Fexample.com%3A44312%2Fcallback 2. მომხმარებელი დაადასტურებს აპლიკაციის მოთხოვნას. 3. მომხმარებელი გადამისამართდება redirect_uri მისამართზე, query string-ში მითითებული შემდეგი პარამეტრით: code - დროებითი კოდი. 4. გაიარეთ ავთენტიფიკაცია HTTP Basic Auth-ის გამოყენებით. სერვისის გამოძახების შედეგად, სერვერის მიერ ბრუნდება Bearer Token, რომელიც შემდგომი მეთოდების გამოძახებისთვის არის ავთენტიფიკაციის პარამეტრი. ## Header-ის პარამეტრები - `Content-Type` — string, required გადაეცემა „application/x-www-form-urlencoded“ მნიშვნელობა - `Authorization` — string, required ავთენტიფიკაცია `HTTP Basic Auth`-ის გამოყენებით. სახელად გამოიყენება თქვენი აპლიკაციის `client_id`, ხოლო პაროლად თქვენი აპლიკაციის `client_secret`. ## Body-ის პარამეტრები - `grant_type` — string, required მნიშვნელობად გადაეცემა ფიქსირებული ტექსტი: `client_credentials` - `code` — string, required დროებითი კოდი - `redirect_uri` — string, required მნიშვნელობად გადაეცემა თქვენი აპლიკაციის `redirect_uri`. ## დაბრუნებული პარამეტრები - `access_token` — string ავტორიზაციის სერვერის მიერ დაბრუნებული Token-ის მნიშვნელობა. - `token_type` — string Token-ის ტიპი (ბრუნდება ტექსტური მნიშვნელობა - `bearer`). - `app_id` — string არ გამოიყენება. - `expires_in` — string აბრუნებს რიცხვით მნიშვნელობას, თუ რამდენი წამის განმავლობაში არის აქტიური Token. - `refresh_expires_in` — string მაქსიმალური დრო, რომლის ამოწურვის შემდეგაც Token გახდება არავალიდური. გვაძლევს საშუალებას, ტოკენის განახლების დრო უფრო მცირე იყოს, ვიდრე სესიის. - `not-before-policy` — string გამოიყენება განახლების ან სესიის Token-ის კომპრომეტირების შემთხვევაში, როგორც დამატებითი დაცვის მექანიზმი. - `scope` — string OAuth 2.0 ავტორიზაციის სტანდარტული მექანიზმია. კონტექსტი, რომლის ფარგლებში Token-ს აქვს ქმედების უფლება. --- # საბალანსო უწყისის ატვირთვის მეთოდი Source: https://api.bog.ge/docs/bonline/balance-sheet # საბალანსო უწყისის ატვირთვის მეთოდი ## Query პარამეტრები - `StartDate` — date, required საწყისი თარიღი - `EndDate` — date, required დასრულების თარიღი - `BalanceSheetEntries` — object, required საბალანსო უწყისის დეტალები - `AccountNumber` — string, required ანგარიშის ნომერი - `AccountDescription` — string, required დასახელება - `OpeningDebit` — decimal number, required საწყისი დებეტი - `OpeningCredit` — decimal number, required საწყისი კრედიტი - `DebitTurnover` — decimal number, required ბრუნვა დებეტი - `CreditTunover` — decimal number, required ბრუნვა კრედიტი - `NetTurnover` — decimal number, required ბრუნვის სხვაობა - `ClosingDebit` — decimal number, required საბოლოო დებეტი - `ClosingCredit` — decimal number, required საბოლოო კრედიტი - `OpeningQuantityDebit` — decimal number, required საწყისი (რაოდენ.) დებეტი - `OpeningQuantityCredit` — decimal number, required საწყისი (რაოდენ.) კრედიტი - `QuantityDebit` — decimal number, required ბრუნვა (რაოდენ.) დებეტი - `QuantityCredit` — decimal number, required ბრუნვა (რაოდენ.) კრედიტი - `QuantityNetTurnover` — decimal number, required ბრუნვის სხვაობა - `ValueCalculated` — boolean, required - `IdentityCode` — string, required - `QuantityFinalDebit` — decimal number, required - `QuantityFinalCredit` — decimal number, required **JSON** ```api POST api/BalanceSheet Content-Type: application/json ``` ```json { "StartDate": "2021-06-21T12:36:58.1691656+04:00", "EndDate": "2021-06-21T12:36:58.1691656+04:00", "BalanceSheetEntries": [ { "AccountNumber": "sample string 1", "AccountDescription": "sample string 2", "OpeningDebit": 1.0, "OpeningCredit": 1.0, "DebitTurnover": 1.0, "CreditTunover": 1.0, "NetTurnover": 1.0, "ClosingDebit": 1.0, "ClosingCredit": 1.0, "OpeningQuantityDebit": 1.0, "OpeningQuantityCredit": 1.0, "QuantityDebit": 1.0, "QuantityCredit": 1.0, "QuantityNetTurnover": 1.0, "ValueCalculated": true, "IdentityCode": "sample string 4", "QuantityFinalDebit": 1.0, "QuantityFinalCredit": 1.0 }, { "AccountNumber": "sample string 1", "AccountDescription": "sample string 2", "OpeningDebit": 1.0, "OpeningCredit": 1.0, "DebitTurnover": 1.0, "CreditTunover": 1.0, "NetTurnover": 1.0, "ClosingDebit": 1.0, "ClosingCredit": 1.0, "OpeningQuantityDebit": 1.0, "OpeningQuantityCredit": 1.0, "QuantityDebit": 1.0, "QuantityCredit": 1.0, "QuantityNetTurnover": 1.0, "ValueCalculated": true, "IdentityCode": "sample string 4", "QuantityFinalDebit": 1.0, "QuantityFinalCredit": 1.0 } ] } ``` **XML** ```api POST api/BalanceSheet Content-Type: application/json ``` ```xml sample string 2 sample string 1 1 1 1 1 sample string 4 1 1 1 1 1 1 1 1 1 1 true sample string 2 sample string 1 1 1 1 1 sample string 4 1 1 1 1 1 1 1 1 1 1 true 2021-06-21T12:36:58.1691656+04:00 2021-06-21T12:36:58.1691656+04:00 ``` ## დაბრუნებული პარამეტრები --- # ანაბრების სია Source: https://api.bog.ge/docs/bonline/deposits/agreements # ანაბრების სია მეთოდის საშუალებით შესაძლებელია მიმდინარე ანაბრების სიის მიღება. პარამეტრები არ გადაეცემა. ## დაბრუნებული პარამეტრები - `name` — string ანაბრის სახელი ან, თუ არ აქვს სახელი, ანაბრის ტიპი - `accountNo` — string ანაბრის ანგარიშის ნომერი - `balance` — decimal number თანხა ანაბარზე - `rate` — decimal number წლიური პროცენტი - `agreeNo` — string ხელშეკრულების ნომერი - `maturityDate` — date ანაბრის დასრულების თარიღი - `startDate` — date ანაბრის გახსნის თარიღი - `interestAccrued` — decimal number დარიცხული სარგებელი - `ccy` — string ანაბრის ვალუტა - `depositType` — string ანაბრის ტიპი - `nextWithdrawalDate` — date სარგებლის მომდევნო დარიცხვის თარიღი - `interestWithPeriodType` — string სარგებლის დარიცხვის პერიოდულობა - `accrualBalance` — decimal number მინიმალური თანხა, რაზეც დაერიცხა სარგებელი - `agreements` — object სარგებლის დარიცხვის რეინჯები - `irr` — decimal number შიდა განაკვეთის პროცენტი - `rate` — decimal number წლიური პროცენტი - `balance` — string თანხის რეინჯი ტექსტურად **JSON** ```api GET api/deposits/agreements ``` ```json [ { "name": "sample string 1", "accountNo": "sample string 2", "balance": 1.0, "rate": 1.0, "agreeNo": "sample string 3", "maturityDate": "2026-06-10T07:17:56.690Z", "startDate": "2026-06-10T07:17:56.690Z", "interestAccrued": 1.0, "ccy": "sample string 4", "depositType": "sample string 5", "nextWithdrawalDate": "2026-06-10T07:17:56.690Z", "interestWithPeriodType": "sample string 6", "accrualBalance": 1.0, "agreements": [ { "irr": 1.0, "rate": 1.0, "balance": "sample string 1" } ] } ] ``` --- # ანაბრების თანხები ვალუტის მიხედვით Source: https://api.bog.ge/docs/bonline/deposits/available-amount # ანაბრების თანხები ვალუტის მიხედვით მეთოდის საშუალებით შესაძლებელია ანაბრების თანხების ჯამის მიღება ვალუტების მიხედვით. პარამეტრები არ გადაეცემა. ## დაბრუნებული პარამეტრები - `ccy` — string ვალუტა - `totalAvailableAmount` — decimal number მოცემულ ვალუტაში ყველა ანაბრის თანხების ჯამი **JSON** ```api GET api/deposits/available-amount ``` ```json [ { "ccy": "sample string 1", "totalAvailableAmount": 1.0 } ] ``` --- # პაკეტური გადარიცხვის გაუქმება Source: https://api.bog.ge/docs/bonline/documents/bulk-delete # პაკეტური გადარიცხვის გაუქმება მეთოდის საშუალებით შესაძლებელია პაკეტის გაუქმება, რაც გულისხმობს პაკეტში შემავალი ყველა დოკუმენტის გაუქმებას. ## Query პარამეტრები - `key` — integer, required - დოკუმენტის უნიკალური იდენტიფიკატორი business online. ## დაბრუნებული პარამეტრები# - — Http Status 200 OK. მეთოდის გამოძახება ითვლება წარმატებულად, თუ სერვერიდან დაბრუნდა 200 HTTP სტატუსი. **REQUEST** ```api DELETE api/documents/bulk/{key} ``` --- # ეროვნულ ვალუტაში პაკეტური გადარიცხვის შექმნა Source: https://api.bog.ge/docs/bonline/documents/bulk-domestic # მოთხოვნა მეთოდის საშუალებით შესაძლებელია, ეროვნულ ვალუტაში, ერთი ან რამდენიმე ინდივიდუალური დოკუმენტის პაკეტის შექმნა. ## Query პარამეტრები ## პარამეტრები - `Nomination` — string, required გადარიცხვის საფუძველი, დანიშნულება (მაქსიმუმ 250 სიმბოლო) - `PayerInn` — string, max-length: 11 გადამხდელი ფიზიკური პირის პირადი ნომერი ან იურიდიული პირის საიდენტიფიკაციო კოდი. ივსება მხოლოდ ბიუჯეტის სასარგებლოდ მესამე პირის ნაცვლად/მაგივრად გადარიცხვის შესრულებისას და ეთითება მესამე პირის საიდენტიფიკაციო კოდი. - `PayerName` — string გადამხდელის დასახელება. ივსება მხოლოდ ბიუჯეტის სასარგებლოდ მესამე პირის ნაცვლად/მაგივრად გადარიცხვის შესრულებისას და ეთითება მესამე პირის საიდენტიფიკაციო კოდი. - `DispatchType` — string გადარიცხვის მეთოდი. მხოლოდ გამავალი გადარიცხვებისთვის. აუცილებელი ველი. იღებს შემდეგ მნიშვნელობებს: - `BULK` - სტანდარტული გადარიცხვა. შესაძლებელია მხოლოდ 10 000 ლარამდე ოპერაციის დროს. - `MT103` - ინდივიდუალური გადარიცხვა - `ValueDate` — date, required საბუთის ბანკში გატარების თარიღი. - `IsSalary` — boolean არასავალდებულო ველი, სასურველია შეივსოს სახელფასო გადარიცხვისას: - `TRUE` - ხელფასის გადარიცხვისას. - `FALSE` - სხვა შემთხვევაში. - `UniqueId` — globally unique identifier, required გარე (გამომძახებელი) სისტემის უნიკალური იდენტიფიკატორი (Guid). - `Amount` — decimal number, required დოკუმენტის თანხა. - `DocumentNo` — string, required დოკუმენტის ნომერი. - `SourceAccountNumber` — string, required გამგზავნის ანგარიში IBAN-ის ფორმატში. - `BeneficiaryAccountNumber` — string, required მიმღების ანგარიში. საქართველოს ბანკში ან სხვა ბანკში ეროვნული ვალუტის გადარიცხვისას – მხოლოდ IBAN-ის ფორმატი. ხაზინაში გადარიცხვისას - სახაზინო კოდი. უცხოური ვალუტის გადარიცხვისას - ანგარიშის ნომერი არსებული ფორმატით. - `BeneficiaryBankCode` — string მიმღები ბანკის RTGS კოდი (სავალდებულო). - `BeneficiaryInn` — string, max-length: 11 ფიზიკური პირის შემთხვევაში მიმღების პირადი ნომერი, იურიდიული პირის შემთხვევაში მისი საიდენტიფიკაციო კოდი. - `CheckInn` — boolean “საქართველოს ბანკში“ გადარიცხვის დროს, შემოწმდეს თუ არა მიმღების ანგარიშის თავსებადობა მის საიდენტიფიკაციო კოდთან. იღებს ორ მნიშვნელობას: - `TRUE` - დამატებით შემოწმდება მიმღების ანგარიშის ნომრის მითითებული საიდენტიფიკაციო კოდით. თუ ანგარიშის ნომერი არ ეკუთვნის მითითებულ საიდენტიფიკაციო კოდზე არსებულ ანგარიშს, დაფიქსირდება შეცდომა. - `FALSE` - გადარიცხვა შემოწმდება სტანდარტული წესით. სხვა ბანკში გადარიცხვისას ამ ველის მნიშვნელობა უნდა იყოს `False`. - `BeneficiaryName` — string მიმღების დასახელება. - `AdditionalInformation` — string დამატებითი ინფორმაცია. არ გამოიყენება ეროვნული ვალუტის გადარიცხვისას. - `CommissionAccountNumber` — string საკომისიოს ანგარიში. მხოლოდ IBAN-ის ფორმატი, მაგ: GE11BG1111111111111111GEL. ანგარიშის არასწორად მითითების შემთხვევაში საკომისიო (არსებობის შემთხვევაში) ჩამოიჭრება იმ ანგარიშიდან, რომლიდანაც გადარიცხვა ხდება. - `IsPayerResident` — boolean გადამხდელის რეზიდენტობა. ლოგიკური მნიშვნელობა (Boolean): True — რეზიდენტი, False — არარეზიდენტი. ივსება მხოლოდ ბიუჯეტის სასარგებლოდ მესამე პირის ნაცვლად გადარიცხვის შესრულებისას. ამ შემთხვევაში, მიუთითეთ მესამე პირის (ვის ნაცვლადაც იხდით) რეზიდენტობა. - `PayerTaxRegistrationCode` — string რეგისტრაციის კოდი. ივსება მხოლოდ ბიუჯეტის სასარგებლოდ მესამე პირის ნაცვლად გადარიცხვის შესრულებისას. - `PayerPenaltyNumber` — string ოქმის ნომერი. ივსება მხოლოდ ბიუჯეტის სასარგებლოდ მესამე პირის ნაცვლად გადარიცხვის შესრულებისას. - `AttachmentIds` — array of string დანართების ჰეშების სია. თითოეული ჰეში (`externalFileHash`) მიიღება [ფაილის ატვირთვის](../files/upload.md) ენდპოინტიდან. ივსება მხოლოდ მაშინ, თუ დოკუმენტს დანართის მიბმა გსურთ. - `CheckUniqueId` — boolean თუ `true`, დოკუმენტის შექმნამდე შემოწმდება, ბოლო 7 დღის განმავლობაში იმავე `UniqueId`-ით დოკუმენტი უკვე შეიქმნა თუ არა. დუბლიკატის აღმოჩენისას ახალი დოკუმენტი არ იქმნება და ბრუნდება შედეგის კოდი `702`. **JSON** ```api POST api/documents/bulk/domestic?fileName={fileName} Content-Type: application/json ``` ```json [ { "Nomination": "sample string 2", "PayerInn": "sample string 3", "PayerName": "sample string 4", "DispatchType": "sample string 5", "ValueDate": "2021-06-17T16:12:22.399993+04:00", "IsSalary": true, "UniqueId": "938a8f0a-567d-4436-81a7-4b63768bc2f6", "Amount": 9.0, "DocumentNo": "sample string 10", "SourceAccountNumber": "sample string 11", "BeneficiaryAccountNumber": "sample string 12", "BeneficiaryBankCode": "sample string 13", "BeneficiaryInn": "sample string 14", "CheckInn": true, "BeneficiaryName": "sample string 16", "AdditionalInformation": "sample string 17" }, { "Nomination": "sample string 2", "PayerInn": "sample string 3", "PayerName": "sample string 4", "DispatchType": "sample string 5", "ValueDate": "2021-06-17T16:12:22.399993+04:00", "IsSalary": true, "UniqueId": "938a8f0a-567d-4436-81a7-4b63768bc2f6", "Amount": 9.0, "DocumentNo": "sample string 10", "SourceAccountNumber": "sample string 11", "BeneficiaryAccountNumber": "sample string 12", "BeneficiaryBankCode": "sample string 13", "BeneficiaryInn": "sample string 14", "CheckInn": true, "BeneficiaryName": "sample string 16", "AdditionalInformation": "sample string 17" } ] ``` **XML** ```api POST api/documents/bulk/domestic?fileName={fileName} Content-Type: application/xml ``` ```xml sample string 17 9 sample string 12 sample string 13 sample string 14 sample string 16 true GEL sample string 10 sample string 11 938a8f0a-567d-4436-81a7-4b63768bc2f6 sample string 5 true sample string 2 sample string 3 sample string 4 2021-06-17T16:12:22.399993+04:00 sample string 17 9 sample string 12 sample string 13 sample string 14 sample string 16 true GEL sample string 10 sample string 11 938a8f0a-567d-4436-81a7-4b63768bc2f6 sample string 5 true sample string 2 sample string 3 sample string 4 2021-06-17T16:12:22.399993+04:00 ``` ## დაბრუნებული პარამეტრები# - — integer პაკეტის უნიკალური იდენტიფიკატორი business online-ში. **JSON** ```json 1 ``` **XML** ```xml 1 ``` --- # უცხოურ ვალუტაში პაკეტური გადარიცხვის შექმნა Source: https://api.bog.ge/docs/bonline/documents/bulk-foreign # მოთხოვნა მეთოდის საშუალებით შესაძლებელია, უცხოურ ვალუტაში, ერთი ან რამდენიმე ინდივიდუალური დოკუმენტის პაკეტის შექმნა. ## Query პარამეტრები - `fileName` — string, required პაკეტის დასახელება ## პარამეტრები - `Charges` — string, required გადარიცხვის მეთოდი. იღებს შემდეგ მნიშვნელობებს: - `SHA` - (SWIFT) თანხის გამგზავნი იხდის მხოლოდ გამგზავნი ბანკის მიერ დადგენილ ყველა საკომისიოს. - `OUR` - (SWIFT) თანხის გამგზავნი იხდის გადარიცხვასთან დაკავშირებულ ყველა საკომისიოს. - `BULK` - (RTGS) სტანდარტული გადარიცხვა. შესაძლებელია მხოლოდ 10 000 USD/EUR-მდე ოპერაციის დროს. - `MT103` - (RTGS) ინდივიდუალური გადარიცხვა. RTGS გადარიცხვა შესაძლებელია მხოლოდ ქართულ ბანკებში, USD ან EUR ვალუტაში. - `CommissionAccountNumber` — string საკომისიოს ანგარიში. - `BeneficiaryBankName` — string მიმღები ბანკის დასახელება. SWIFT გადარიცხვისას BeneficiaryBankCode ან BeneficiaryBankName ველის შევსება სავალდებულოა. RTGS გადარიცხვის შემთხვევაში ველი უნდა დარჩეს ცარიელი. - `IntermediaryBankCode` — string შუამავალი ბანკის SWIFT კოდი. RTGS გადარიცხვის შემთხვევაში ველი უნდა დარჩეს ცარიელი. - `IntermediaryBankName` — string შუამავალი ბანკის დასახელება. RTGS გადარიცხვის შემთხვევაში ველი უნდა დარჩეს ცარიელი. - `PaymentDetail` — string გადარიცხვის საფუძველი, დანიშნულება (მაქსიმუმ 4x34 136 სიმბოლო). - `ValueDate` — date, required ვალუტირების თარიღი. - `BeneficiaryRegistrationCountryCode` — string მიმღების რეგისტრაციის ქვეყანა. - `BeneficiaryActualCountryCode` — string მიმღების ფაქტობრივი ქვეყანა. - `RecipientAddress` — string მიმღების მისამართი. RTGS გადარიცხვის შემთხვევაში ველი უნდა დარჩეს ცარიელი. - `RecipientCity` — string მიმღების ქალაქი. RTGS გადარიცხვის შემთხვევაში ველი უნდა დარჩეს ცარიელი. - `RegReportingValue` — string დამატებითი დანიშნულების ველი (გამოიყენება არაბეთის გაერთიანებულ საემიროებში გადარიცხვისას). - `UniqueId` — globally unique identifier, required გარე (გამომძახებელ) სისტემაში დოკუმენტის უნიკალური იდენტიფიკატორი (Guid). - `Amount` — decimal number, required დოკუმენტის თანხა. - `Currency` — string, required დოკუმენტის ვალუტა. - `DocumentNo` — string, required დოკუმენტის ნომერი. - `SourceAccountNumber` — string, required გამგზავნის ანგარიში IBAN-ის ფორმატში. - `BeneficiaryAccountNumber` — string, required მიმღების ანგარიში. საქართველოს ბანკში ან სხვა ბანკში ეროვნული ვალუტის გადარიცხვისას – მხოლოდ IBAN-ის ფორმატი. ხაზინაში გადარიცხვისას - სახაზინო კოდი. უცხოური ვალუტის გადარიცხვისას - ანგარიშის ნომერი არსებული ფორმატით. - `BeneficiaryBankCode` — string მიმღები ბანკის BIC კოდი. RTGS გადარიცხვის შემთხვევაში ველი უნდა დარჩეს ცარიელი. - `BeneficiaryInn` — string, max-length: 11 ფიზიკური პირის შემთხვევაში მიმღების პირადი ნომერი, იურიდიული პირის შემთხვევაში მისი საიდენტიფიკაციო კოდი. - `CheckInn` — boolean “საქართველოს ბანკში“ გადარიცხვის დროს, შემოწმდეს თუ არა მიმღების ანგარიშის თავსებადობა მის საიდენტიფიკაციო კოდთან. იღებს ორ მნიშვნელობას: - `TRUE` - დამატებით შემოწმდება მიმღების ანგარიშის ნომრის მითითებული საიდენტიფიკაციო კოდით. თუ ანგარიშის ნომერი არ ეკუთვნის მითითებულ საიდენტიფიკაციო კოდზე არსებულ ანგარიშს, დაფიქსირდება შეცდომა. - `FALSE` - გადარიცხვა შემოწმდება სტანდარტული წესით. სხვა ბანკში გადარიცხვისას ამ ველის მნიშვნელობა უნდა იყოს `False`. - `BeneficiaryName` — string მიმღების დასახელება. - `AdditionalInformation` — string დამატებითი ინფორმაცია. არ გამოიყენება ეროვნული ვალუტის გადარიცხვისას. - `PurposeCode` — string გადარიცხვის დანიშნულების კოდი. გამოიყენება სავალუტო ოპერაციების რეპორტინგისთვის. - `AttachmentIds` — array of string დანართების ჰეშების სია. თითოეული ჰეში (`externalFileHash`) მიიღება [ფაილის ატვირთვის](../files/upload.md) ენდპოინტიდან. ივსება მხოლოდ მაშინ, თუ დოკუმენტს დანართის მიბმა გსურთ. - `CheckUniqueId` — boolean თუ `true`, დოკუმენტის შექმნამდე შემოწმდება, ბოლო 7 დღის განმავლობაში იმავე `UniqueId`-ით დოკუმენტი უკვე შეიქმნა თუ არა. დუბლიკატის აღმოჩენისას ახალი დოკუმენტი არ იქმნება და ბრუნდება შედეგის კოდი `702`. **JSON** ```api POST api/documents/bulk/foreign?fileName={fileName} Content-Type: application/json ``` ```json [ { "Charges": "sample string 1", "CommissionAccountNumber": "sample string 2", "BeneficiaryBankName": "sample string 3", "IntermediaryBankCode": "sample string 4", "IntermediaryBankName": "sample string 5", "PaymentDetail": "sample string 6", "ValueDate": "2021-06-17T17:55:21.9971829+04:00", "BeneficiaryRegistrationCountryCode": "sample string 8", "BeneficiaryActualCountryCode": "sample string 9", "RecipientAddress": "sample string 10", "RecipientCity": "sample string 11", "RegReportingValue": "sample string 12", "UniqueId": "16928efd-7fc0-4dd4-8643-64b4e1ae6725", "Amount": 14.0, "Currency": "sample string 15", "DocumentNo": "sample string 16", "SourceAccountNumber": "sample string 17", "BeneficiaryAccountNumber": "sample string 18", "BeneficiaryBankCode": "sample string 19", "BeneficiaryInn": "sample string 20", "CheckInn": true, "BeneficiaryName": "sample string 22", "AdditionalInformation": "sample string 23" }, { "Charges": "sample string 1", "CommissionAccountNumber": "sample string 2", "BeneficiaryBankName": "sample string 3", "IntermediaryBankCode": "sample string 4", "IntermediaryBankName": "sample string 5", "PaymentDetail": "sample string 6", "ValueDate": "2021-06-17T17:55:21.9971829+04:00", "BeneficiaryRegistrationCountryCode": "sample string 8", "BeneficiaryActualCountryCode": "sample string 9", "RecipientAddress": "sample string 10", "RecipientCity": "sample string 11", "RegReportingValue": "sample string 12", "UniqueId": "16928efd-7fc0-4dd4-8643-64b4e1ae6725", "Amount": 14.0, "Currency": "sample string 15", "DocumentNo": "sample string 16", "SourceAccountNumber": "sample string 17", "BeneficiaryAccountNumber": "sample string 18", "BeneficiaryBankCode": "sample string 19", "BeneficiaryInn": "sample string 20", "CheckInn": true, "BeneficiaryName": "sample string 22", "AdditionalInformation": "sample string 23" } ] ``` **XML** ```api POST api/documents/bulk/foreign?fileName={fileName} Content-Type: application/xml ``` ```xml sample string 23 14 sample string 18 sample string 19 sample string 20 sample string 22 true sample string 15 sample string 16 sample string 17 16928efd-7fc0-4dd4-8643-64b4e1ae6725 sample string 9 sample string 3 sample string 8 sample string 1 sample string 2 sample string 4 sample string 5 sample string 6 sample string 10 sample string 11 sample string 12 2021-06-17T17:55:21.9971829+04:00 sample string 23 14 sample string 18 sample string 19 sample string 20 sample string 22 true sample string 15 sample string 16 sample string 17 16928efd-7fc0-4dd4-8643-64b4e1ae6725 sample string 9 sample string 3 sample string 8 sample string 1 sample string 2 sample string 4 sample string 5 sample string 6 sample string 10 sample string 11 sample string 12 2021-06-17T17:55:21.9971829+04:00 ``` ## დაბრუნებული პარამეტრები# - — integer პაკეტის უნიკალური იდენტიფიკატორი business online-ში. **JSON** ```json 1 ``` **XML** ```xml 1 ``` --- # პაკეტური გადარიცხვის სტატუსი Source: https://api.bog.ge/docs/bonline/documents/bulk-status # პაკეტური გადარიცხვის სტატუსი მეთოდის საშუალებით შესაძლებელია დოკუმენტების პაკეტისა და ყველა დოკუმენტის ცალ-ცალკე სტატუსის გაგება, პაკეტის უნიკალური იდენტიფიკატორის მიხედვით. ## Query პარამეტრები - `key` — integer, required დოკუმენტის უნიკალური იდენტიფიკატორი business online. **REQUEST** ```api GET api/documents/bulk/status/{key} ``` ## დაბრუნებული პარამეტრები# - `Status` — string დოკუმენტის სტატუსი. - `DocumentStatuses` — string პაკეტურ გადარიცხვაში არსებული დოკუმენტების მასივი, შემდეგი ატრიბუტებით: - `UniqueId ` — globally unique identifier უნიკალური იდენტიფიკატორი (Guid) გარე სისტემაში. - `UniqueKey ` — integer დოკუმენტის უნიკალური იდენტიფიკატორი business online-ში. - `Status` — string დოკუმენტის სტატუსი. - `BulkLineStatus` — string გამოიყენება პაკეტური გადარიცხვის დროს. - `RejectCode` — string უარყოფის კოდი. - `ResultCode` — integer ოპერაციის შედეგის კოდი (ლინკით ResultCode გვერდზე). - `Match` — integer თანხვედრის % შიდა გადარიცხვის დროს თქვენ მიერ აკრეფილი მიმღები ი/პ-ის შემთხვევაში მოწმდება ბანკში IBAN-ის ანგარიშის მფლობელის დასახელებასთან, ფ/პ-ის შემთხვევაში კი – სახელთან და გვართან. შედარების შედეგად ბრუნდება დამთხვევის პროცენტული მაჩვენებელი. **JSON** ```json { "Status": "sample string 1", "DocumentStatuses": [ { "UniqueId": "54079737-2913-48d5-a0ed-f22895c33116", "UniqueKey": 1, "Status": "sample string 2", "BulkLineStatus": "sample string 3", "RejectCode": 1, "ResultCode": 1, "Match": 1.0 }, { "UniqueId": "54079737-2913-48d5-a0ed-f22895c33116", "UniqueKey": 1, "Status": "sample string 2", "BulkLineStatus": "sample string 3", "RejectCode": 1, "ResultCode": 1, "Match": 1.0 } ] } ``` **XML** ```xml sample string 3 1 1 1 sample string 2 54079737-2913-48d5-a0ed-f22895c33116 1 sample string 3 1 1 1 sample string 2 54079737-2913-48d5-a0ed-f22895c33116 1 sample string 1 ``` --- # კონვერტაცია Source: https://api.bog.ge/docs/bonline/documents/conversion # მოთხოვნა მეთოდის საშუალებით შესაძლებელია საკუთარ ანგარიშებს შორის ერთი ან რამდენიმე კონვერტაციის დოკუმენტის შექმნა. ## პარამეტრები - `UniqueId` — globally unique identifier, required გარე (გამომძახებელ) სისტემაში დოკუმენტის უნიკალური იდენტიფიკატორი (Guid). - `DocumentNo` — string დოკუმენტის ნომერი. - `SourceAccountNumber` — string გასაყიდი ვალუტის ანგარიში. - `SourceCurrency` — string გასაყიდი ვალუტა. - `DestinationAccountNumber` — string საყიდელი ვალუტის ანგარიში. - `DestinationCurrency` — string საყიდელი ვალუტა. - `Amount` — decimal number თანხა. - `Rate` — decimal number კონვერტაციის კურსი. გადაეცემა ბანკთან ინდივიდუალურად შეთანხმებული კურსის გამოყენების შემთხვევაში. - `AdditionalInfo` — string დამატებითი ინფორმაცია. არ გამოიყენება ეროვნული ვალუტის გადარიცხვისას. - `CheckUniqueId` — boolean თუ `true`, დოკუმენტის შექმნამდე შემოწმდება, ბოლო 7 დღის განმავლობაში იმავე `UniqueId`-ით დოკუმენტი უკვე შეიქმნა თუ არა. დუბლიკატის აღმოჩენისას ახალი დოკუმენტი არ იქმნება და ბრუნდება შედეგის კოდი `702`. **JSON** ```api POST api/documents/conversion Content-Type: application/json ``` ```json [ { "UniqueId": "fdbf64d0-d481-426f-9799-9a6920728e0c", "DocumentNo": "sample string 2", "SourceAccountNumber": "sample string 3", "SourceCurrency": "sample string 4", "DestinationAccountNumber": "sample string 5", "DestinationCurrency": "sample string 6", "Amount": 7.0, "Rate": 8.0, "AdditionalInfo": "sample string 9" }, { "UniqueId": "fdbf64d0-d481-426f-9799-9a6920728e0c", "DocumentNo": "sample string 2", "SourceAccountNumber": "sample string 3", "SourceCurrency": "sample string 4", "DestinationAccountNumber": "sample string 5", "DestinationCurrency": "sample string 6", "Amount": 7.0, "Rate": 8.0, "AdditionalInfo": "sample string 9" } ] ``` **XML** ```api POST api/documents/conversion Content-Type: application/xml ``` ```xml sample string 9 7 sample string 5 sample string 6 sample string 2 8 sample string 3 sample string 4 fdbf64d0-d481-426f-9799-9a6920728e0c sample string 9 7 sample string 5 sample string 6 sample string 2 8 sample string 3 sample string 4 fdbf64d0-d481-426f-9799-9a6920728e0c ``` ## დაბრუნებული პარამეტრები - `UniqueId` — globally unique identifier უნიკალური იდენტიფიკატორი (Guid) გარე სისტემაში. - `UniqueKey` — integer დოკუმენტის უნიკალური იდენტიფიკატორი business online-ში. - `ResultCode` — integer ოპერაციის შედეგის კოდი (ლინკით ResultCode გვერდზე). [result code](../result/result-codes.md) - `Match` — decimal number შიდა გადარიცხვის დროს, თანხვედრის % თქვენ მიერ აკრეფილი მიმღების დასახელებასთან. იურიდიული პირის შემთხვევაში მოწმდება ბანკში IBAN-ის ანგარიშის მფლობელის დასახელებასთან, ფიზიკური პირის შემთხვევაში კი – სახელთან და გვართან. შედარების შედეგად ბრუნდება დამთხვევის პროცენტული მაჩვენებელი. **JSON** ```json [ { "UniqueId": "93fb404b-5f8e-486b-8b35-610d71a41675", "UniqueKey": 2, "ResultCode": 1, "Match": 1.0 }, { "UniqueId": "93fb404b-5f8e-486b-8b35-610d71a41675", "UniqueKey": 2, "ResultCode": 1, "Match": 1.0 } ] ``` **XML** ```xml 1 1 93fb404b-5f8e-486b-8b35-610d71a41675 2 1 1 93fb404b-5f8e-486b-8b35-610d71a41675 2 ``` --- # დოკუმენტის შექმნის კოდები Source: https://api.bog.ge/docs/bonline/documents/document-codes # დოკუმენტის შექმნის კოდები მეთოდის საშუალებით შეგვიძლია დოკუმენტის შექმნის ყველა კოდისა და მათი აღწერის მიღება. ## დაბრუნებული პარამეტრები - `DocumentTypeName` — string დოკუმენტის ტიპი - `ResultType` — string შედეგის ტიპი - `ResultDescription` — string აღწერა - `ResultCode` — integer შედეგის კოდი **JSON** ```api GET api/documents/code ``` ```json [ { "DocumentTypeName": "sample string 1", "ResultType": "sample string 2", "ResultDescription": "sample string 3", "ResultCode": 4 }, { "DocumentTypeName": "sample string 1", "ResultType": "sample string 2", "ResultDescription": "sample string 3", "ResultCode": 4 } ] ``` **XML** ```api GET api/documents/code ``` ```xml sample string 1 4 sample string 3 sample string 2 sample string 1 4 sample string 3 sample string 2 ``` --- # ინდივიდუალური დოკუმენტის გაუქმება Source: https://api.bog.ge/docs/bonline/documents/document-delete # ინდივიდუალური დოკუმენტის გაუქმება მეთოდის საშუალებით შესაძლებელია ინდივიდუალური დოკუმენტის გაუქმება. ## Query პარამეტრები - `key` — integer, required დოკუმენტის უნიკალური იდენტიფიკატორი business online-ში ერთი ან რამდენიმე. ## დაბრუნებული პარამეტრები - — Http Status 200 OK. მეთოდის გამოძახება ითვლება წარმატებულად, თუ სერვერიდან დაბრუნდა 200 HTTP სტატუსი. **REQUEST** ```api DELETE api/documents/{keys} ``` --- # ეროვნულ ვალუტაში ინდივიდუალური დოკუმენტის შექმნა Source: https://api.bog.ge/docs/bonline/documents/domestic # მოთხოვნა მეთოდის საშუალებით შესაძლებელია, ეროვნულ ვალუტაში, ერთი ან რამდენიმე ინდივიდუალური დოკუმენტის შექმნა. ## პარამეტრები - `Nomination` — string, required გადარიცხვის საფუძველი, დანიშნულება / მაქსიმუმ 250 სიმბოლო - `PayerInn` — string, max-length: 11, required გადამხდელი ფიზიკური პირის პირადი ნომერი ან იურიდიული პირის საიდენტიფიკაციო კოდი. ივსება მხოლოდ ბიუჯეტის სასარგებლოდ მესამე პირის ნაცვლად/მაგივრად გადარიცხვის შესრულებისას და ეთითება მესამე პირის საიდენტიფიკაციო კოდი. - `PayerName` — string გადამხდელის დასახელება. ივსება მხოლოდ ბიუჯეტის სასარგებლოდ მესამე პირის ნაცვლად/მაგივრად გადარიცხვის შესრულებისას და ეთითება მესამე პირის საიდენტიფიკაციო კოდი. - `DispatchType` — string გადარიცხვის მეთოდი. მხოლოდ გამავალი გადარიცხვებისთვის. აუცილებელი ველი. იღებს შემდეგ მნიშვნელობებს: - BULK - სტანდარტული გადარიცხვა. შესაძლებელია მხოლოდ 10 000 ლარამდე ოპერაციის დროს. - MT103 ინდივიდუალური გადარიცხვა. - `ValueDate` — date, required საბუთის ბანკში გატარების თარიღი. - `IsSalary` — boolean არასავალდებულო ველი, სასურველია შეივსოს სახელფასო გადარიცხვისას: - TRUE - ხელფასის გადარიცხვისას. - FALSE - სხვა შემთხვევაში. - `UniqueId` — globally unique identifier, required გარე (გამომძახებელი) სისტემის უნიკალური იდენტიფიკატორი (Guid). - `Amount` — decimal number, required დოკუმენტის თანხა. - `DocumentNo` — string, required დოკუმენტის ნომერი, მაქს. სიგრძე = 16. - `SourceAccountNumber` — string, required გამგზავნის ანგარიში, ანგარიშიდან / მხოლოდ IBAN-ის ფორმატი, მაგ: GE11BG1111111111111111GEL - `BeneficiaryAccountNumber` — string, required მიმღების ანგარიში. საქართველოს ბანკში ან სხვა ბანკში ეროვნული ვალუტის გადარიცხვისას – მხოლოდ IBAN-ის ფორმატი. ხაზინაში გადარიცხვისას - სახაზინო კოდი. უცხოური ვალუტის გადარიცხვისას - ანგარიშის ნომერი არსებული ფორმატით. - `BeneficiaryBankCode` — string, required მიმღები ბანკის RTGS კოდი (სავალდებულო). - `BeneficiaryInn` — string, required ფიზიკური პირის შემთხვევაში მიმღების პირადი ნომერი, იურიდიული პირის შემთხვევაში მისი საიდენტიფიკაციო კოდი. - `CheckInn` — boolean “საქართველოს ბანკში“ გადარიცხვის დროს, შემოწმდეს თუ არა მიმღების ანგარიშის თავსებადობა მის საიდენტიფიკაციო კოდთან. იღებს ორ მნიშვნელობას: - `TRUE` - დამატებით შემოწმდება მიმღების ანგარიშის ნომრის მითითებული საიდენტიფიკაციო კოდით. თუ ანგარიშის ნომერი არ ეკუთვნის მითითებულ საიდენტიფიკაციო კოდზე არსებულ ანგარიშს, დაფიქსირდება შეცდომა. - `FALSE` - გადარიცხვა შემოწმდება სტანდარტული წესით. სხვა ბანკში გადარიცხვისას ამ ველის მნიშვნელობა უნდა იყოს `False`. - `BeneficiaryName` — string მიმღების დასახელება. - `CommissionAccountNumber` — string საკომისიოს ანგარიში, მხოლოდ ინდივიდუალური გადარიცხვისთვის. IBAN-ის ფორმატი, მაგ: GE11BG1111111111111111GEL, ანგარიშის არასწორედ მითითების შემთხვევაში საკომისიო (არსებობის შეთხვევაში) ჩამოიწღება იმ ანგარიშიდან რომლიდანაც გადარიცხვა ხდება - `IsPayerResident` — boolean გადამხდელის რეზიდენტობა. ლოგიკური მნიშვნელობა (Boolean): True — რეზიდენტი, False — არარეზიდენტი. ივსება მხოლოდ ბიუჯეტის სასარგებლოდ მესამე პირის ნაცვლად გადარიცხვის შესრულებისას. ამ შემთხვევაში, მიუთითეთ მესამე პირის (ვის ნაცვლადაც იხდით) რეზიდენტობა. - `PayerTaxRegistrationCode` — string რეგისტრაციის კოდი. ივსება მხოლოდ ბიუჯეტის სასარგებლოდ მესამე პირის ნაცვლად გადარიცხვის შესრულებისას. - `PayerPenaltyNumber` — string ოქმის ნომერი. ივსება მხოლოდ ბიუჯეტის სასარგებლოდ მესამე პირის ნაცვლად გადარიცხვის შესრულებისას. - `AdditionalInformation` — string დამატებითი ინფორმაცია. არ გამოიყენება ეროვნული ვალუტის გადარიცხვისას. - `AttachmentIds` — array of string დანართების ჰეშების სია. თითოეული ჰეში (`externalFileHash`) მიიღება [ფაილის ატვირთვის](../files/upload.md) ენდპოინტიდან. ივსება მხოლოდ მაშინ, თუ დოკუმენტს დანართის მიბმა გსურთ. - `CheckUniqueId` — boolean თუ `true`, დოკუმენტის შექმნამდე შემოწმდება, ბოლო 7 დღის განმავლობაში იმავე `UniqueId`-ით დოკუმენტი უკვე შეიქმნა თუ არა. დუბლიკატის აღმოჩენისას ახალი დოკუმენტი არ იქმნება და ბრუნდება შედეგის კოდი `702`. **JSON** ```api POST api/documents/domestic Content-Type: application/json ``` ```json [ { "Nomination": "sample string 2", "PayerInn": "sample string 3", "PayerName": "sample string 4", "DispatchType": "sample string 5", "ValueDate": "2021-06-17T10:31:50.2269037+04:00", "IsSalary": true, "UniqueId": "066a7743-256a-4b40-b937-78e241dd31ae", "Amount": 9.0, "DocumentNo": "sample string 10", "SourceAccountNumber": "sample string 11", "BeneficiaryAccountNumber": "sample string 12", "BeneficiaryBankCode": "sample string 13", "BeneficiaryInn": "sample string 14", "CheckInn": true, "BeneficiaryName": "sample string 16", "AdditionalInformation": "sample string 17", "CommissionAccountNumber": "sample string 18", "IsPayerResident": true, "PayerTaxRegistrationCode": "sample string 19", "PayerPenaltyNumber": "sample string 20", "AttachmentIds": ["sample string 21"] }, { "Nomination": "sample string 2", "PayerInn": "sample string 3", "PayerName": "sample string 4", "DispatchType": "sample string 5", "ValueDate": "2021-06-17T10:31:50.2269037+04:00", "IsSalary": true, "UniqueId": "066a7743-256a-4b40-b937-78e241dd31ae", "Amount": 9.0, "DocumentNo": "sample string 10", "SourceAccountNumber": "sample string 11", "BeneficiaryAccountNumber": "sample string 12", "BeneficiaryBankCode": "sample string 13", "BeneficiaryInn": "sample string 14", "CheckInn": true, "BeneficiaryName": "sample string 16", "AdditionalInformation": "sample string 17", "CommissionAccountNumber": "sample string 18", "IsPayerResident": true, "PayerTaxRegistrationCode": "sample string 19", "PayerPenaltyNumber": "sample string 20", "AttachmentIds": ["sample string 21"] } ] ``` **XML** ```api POST api/documents/domestic Content-Type: application/xml ``` ```xml sample string 17 9 sample string 12 sample string 13 sample string 14 sample string 16 true GEL sample string 10 sample string 11 a9ee0b25-6d72-4774-b7d0-0c8415fe9ebf sample string 5 true sample string 2 sample string 3 sample string 4 2021-06-17T11:22:01.4869236+04:00 sample string 18 true sample string 19 sample string 20 sample string 21 sample string 17 9 sample string 12 sample string 13 sample string 14 sample string 16 true GEL sample string 10 sample string 11 a9ee0b25-6d72-4774-b7d0-0c8415fe9ebf sample string 5 true sample string 2 sample string 3 sample string 4 2021-06-17T11:22:01.4869236+04:00 sample string 18 true sample string 19 sample string 20 sample string 21 ``` ## დაბრუნებული პარამეტრები# - `UniqueId` — globally unique identifier უნიკალური იდენტიფიკატორი (Guid) გარე სისტემაში. - `UniqueKey` — integer დოკუმენტის უნიკალური იდენტიფიკატორი business online-ში. - `ResultCode` — integer ოპერაციის შედეგის კოდი (ლინკით ResultCode გვერდზე). [result code](../result/result-codes.md) - `Match` — decimal number შიდა გადარიცხვის დროს, თანხვედრის % თქვენ მიერ აკრეფილი მიმღების დასახელებასთან. იურიდიული პირის შემთხვევაში მოწმდება ბანკში IBAN-ის ანგარიშის მფლობელის დასახელებასთან, ფიზიკური პირის შემთხვევაში კი – სახელთან და გვართან. შედარების შედეგად ბრუნდება დამთხვევის პროცენტული მაჩვენებელი. **JSON** ```json [ { "UniqueId": "57adca88-0aff-4eb7-9648-4785106e77f6", "UniqueKey": 2, "ResultCode": 1, "Match": 1.0 }, { "UniqueId": "57adca88-0aff-4eb7-9648-4785106e77f6", "UniqueKey": 2, "ResultCode": 1, "Match": 1.0 } ] ``` **XML** ```xml 1 1 57adca88-0aff-4eb7-9648-4785106e77f6 2 1 1 57adca88-0aff-4eb7-9648-4785106e77f6 2 ``` --- # უცხოურ ვალუტაში ინდივიდუალური დოკუმენტის შექმნა Source: https://api.bog.ge/docs/bonline/documents/foreign # მოთხოვნა მეთოდის საშუალებით შესაძლებელია, უცხოურ ვალუტაში, ერთი ან რამდენიმე ინდივიდუალური დოკუმენტის შექმნა. ## პარამეტრები - `Charges` — string, required გადარიცხვის მეთოდი. იღებს შემდეგ მნიშვნელობებს: - `SHA` - (SWIFT) თანხის გამგზავნი იხდის მხოლოდ გამგზავნი ბანკის მიერ დადგენილ ყველა საკომისიოს. - `OUR` - (SWIFT) თანხის გამგზავნი იხდის გადარიცხვასთან დაკავშირებულ ყველა საკომისიოს. - `BULK` - (RTGS) სტანდარტული გადარიცხვა. შესაძლებელია მხოლოდ 10 000 USD/EUR-მდე ოპერაციის დროს. - `MT103` - (RTGS) ინდივიდუალური გადარიცხვა. RTGS გადარიცხვა შესაძლებელია მხოლოდ ქართულ ბანკებში, USD ან EUR ვალუტაში. - `BeneficiaryBankName` — string მიმღები ბანკის დასახელება. SWIFT გადარიცხვისას BeneficiaryBankCode ან BeneficiaryBankName ველის შევსება სავალდებულოა. RTGS გადარიცხვის შემთხვევაში ველი უნდა დარჩეს ცარიელი. - `IntermediaryBankCode` — string შუამავალი ბანკის SWIFT კოდი. RTGS გადარიცხვის შემთხვევაში ველი უნდა დარჩეს ცარიელი. - `IntermediaryBankName` — string შუამავალი ბანკის დასახელება. RTGS გადარიცხვის შემთხვევაში ველი უნდა დარჩეს ცარიელი. - `PaymentDetail` — string გადარიცხვის საფუძველი, დანიშნულება (მაქსიმუმ 4x34 136 სიმბოლო). - `ValueDate` — date, required ვალუტირების თარიღი. - `BeneficiaryRegistrationCountryCode` — string მიმღების რეგისტრაციის ქვეყანა. - `BeneficiaryActualCountryCode` — string მიმღების ფაქტობრივი ქვეყანა. - `RecipientAddress` — string მიმღების მისამართი. RTGS გადარიცხვის შემთხვევაში ველი უნდა დარჩეს ცარიელი. - `RecipientCity` — string მიმღების ქალაქი. RTGS გადარიცხვის შემთხვევაში ველი უნდა დარჩეს ცარიელი. - `RegReportingValue` — string დამატებითი დანიშნულების ველი (გამოიყენება არაბეთის გაერთიანებულ საემიროებში გადარიცხვისას). - `UniqueId` — globally unique identifier, required გარე (გამომძახებელ) სისტემაში დოკუმენტის უნიკალური იდენტიფიკატორი (Guid). - `Amount` — decimal number, required დოკუმენტის თანხა. - `Currency` — string, required დოკუმენტის ვალუტა. - `DocumentNo` — string, required დოკუმენტის ნომერი. - `SourceAccountNumber` — string, required გამგზავნის ანგარიში, ანგარიშიდან / მხოლოდ IBAN-ის ფორმატი, მაგ: GE11BG1111111111111111GEL - `BeneficiaryAccountNumber` — string, required მიმღების ანგარიში. საქართველოს ბანკში ან სხვა ბანკში ეროვნული ვალუტის გადარიცხვისას – მხოლოდ IBAN-ის ფორმატი. ხაზინაში გადარიცხვისას - სახაზინო კოდი. უცხოური ვალუტის გადარიცხვისას - ანგარიშის ნომერი არსებული ფორმატით. - `BeneficiaryBankCode` — string მიმღები ბანკის BIC კოდი. RTGS გადარიცხვის შემთხვევაში ველი უნდა დარჩეს ცარიელი. - `BeneficiaryInn` — string, max-length: 11 ფიზიკური პირის შემთხვევაში მიმღების პირადი ნომერი, იურიდიული პირის შემთხვევაში მისი საიდენტიფიკაციო კოდი. - `CheckInn` — string “საქართველოს ბანკში“ გადარიცხვის დროს, შემოწმდეს თუ არა მიმღების ანგარიშის თავსებადობა მის საიდენტიფიკაციო კოდთან. იღებს ორ მნიშვნელობას: - `TRUE` - დამატებით შემოწმდება მიმღების ანგარიშის ნომრის მითითებული საიდენტიფიკაციო კოდით. თუ ანგარიშის ნომერი არ ეკუთვნის მითითებულ საიდენტიფიკაციო კოდზე არსებულ ანგარიშს, დაფიქსირდება შეცდომა. - `FALSE` - გადარიცხვა შემოწმდება სტანდარტული წესით. სხვა ბანკში გადარიცხვისას ამ ველის მნიშვნელობა უნდა იყოს `False`. - `BeneficiaryName` — string მიმღების დასახელება. - `CommissionAccountNumber` — string საკომისიოს ანგარიში, მხოლოდ ინდივიდუალური გადარიცხვისთვის / მხოლოდ IBAN-ის ფორმატი, მაგ: GE11BG1111111111111111GEL, ანგარიშის არასწორედ მითითების შემთხვევაში საკომისიო (არსებობის შეთხვევაში) ჩამოიწღება იმ ანგარიშიდან რომლიდანაც გადარიცხვა ხდება - `AdditionalInformation` — string დამატებითი ინფორმაცია. არ გამოიყენება ეროვნული ვალუტის გადარიცხვისას. - `AttachmentIds` — array of string დანართების ჰეშების სია. თითოეული ჰეში (`externalFileHash`) მიიღება [ფაილის ატვირთვის](../files/upload.md) ენდპოინტიდან. ივსება მხოლოდ მაშინ, თუ დოკუმენტს დანართის მიბმა გსურთ. - `PurposeCode` — string გადარიცხვის დანიშნულების კოდი. გამოიყენება სავალუტო ოპერაციების რეპორტინგისთვის. - `CheckUniqueId` — boolean თუ `true`, დოკუმენტის შექმნამდე შემოწმდება, ბოლო 7 დღის განმავლობაში იმავე `UniqueId`-ით დოკუმენტი უკვე შეიქმნა თუ არა. დუბლიკატის აღმოჩენისას ახალი დოკუმენტი არ იქმნება და ბრუნდება შედეგის კოდი `702`. **JSON** ```api POST api/documents/foreign Content-Type: application/json ``` ```json [ { "Charges": "sample string 1", "CommissionAccountNumber": "sample string 2", "BeneficiaryBankName": "sample string 3", "IntermediaryBankCode": "sample string 4", "IntermediaryBankName": "sample string 5", "PaymentDetail": "sample string 6", "ValueDate": "2021-06-17T12:03:37.4722861+04:00", "BeneficiaryRegistrationCountryCode": "sample string 8", "BeneficiaryActualCountryCode": "sample string 9", "RecipientAddress": "sample string 10", "RecipientCity": "sample string 11", "RegReportingValue": "sample string 12", "UniqueId": "c6b8cc64-072d-4849-9b7a-a40dc5faa3af", "Amount": 14.0, "Currency": "sample string 15", "DocumentNo": "sample string 16", "SourceAccountNumber": "sample string 17", "BeneficiaryAccountNumber": "sample string 18", "BeneficiaryBankCode": "sample string 19", "BeneficiaryInn": "sample string 20", "CheckInn": true, "BeneficiaryName": "sample string 22", "AdditionalInformation": "sample string 23", "AttachmentIds": ["sample string 24"] }, { "Charges": "sample string 1", "CommissionAccountNumber": "sample string 2", "BeneficiaryBankName": "sample string 3", "IntermediaryBankCode": "sample string 4", "IntermediaryBankName": "sample string 5", "PaymentDetail": "sample string 6", "ValueDate": "2021-06-17T12:03:37.4722861+04:00", "BeneficiaryRegistrationCountryCode": "sample string 8", "BeneficiaryActualCountryCode": "sample string 9", "RecipientAddress": "sample string 10", "RecipientCity": "sample string 11", "RegReportingValue": "sample string 12", "UniqueId": "c6b8cc64-072d-4849-9b7a-a40dc5faa3af", "Amount": 14.0, "Currency": "sample string 15", "DocumentNo": "sample string 16", "SourceAccountNumber": "sample string 17", "BeneficiaryAccountNumber": "sample string 18", "BeneficiaryBankCode": "sample string 19", "BeneficiaryInn": "sample string 20", "CheckInn": true, "BeneficiaryName": "sample string 22", "AdditionalInformation": "sample string 23", "AttachmentIds": ["sample string 24"] } ] ``` **XML** ```api POST api/documents/foreign Content-Type: application/xml ``` ```xml sample string 23 14 sample string 18 sample string 19 sample string 20 sample string 22 true sample string 15 sample string 16 sample string 17 c6b8cc64-072d-4849-9b7a-a40dc5faa3af sample string 9 sample string 3 sample string 8 sample string 1 sample string 2 sample string 4 sample string 5 sample string 6 sample string 10 sample string 11 sample string 12 2021-06-17T12:03:37.4722861+04:00 sample string 24 sample string 23 14 sample string 18 sample string 19 sample string 20 sample string 22 true sample string 15 sample string 16 sample string 17 c6b8cc64-072d-4849-9b7a-a40dc5faa3af sample string 9 sample string 3 sample string 8 sample string 1 sample string 2 sample string 4 sample string 5 sample string 6 sample string 10 sample string 11 sample string 12 2021-06-17T12:03:37.4722861+04:00 sample string 24 ``` ## დაბრუნებული პარამეტრები - `UniqueId` — globally unique identifier უნიკალური იდენტიფიკატორი (Guid) გარე სისტემაში. - `UniqueKey` — integer დოკუმენტის უნიკალური იდენტიფიკატორი business online-ში. - `ResultCode` — integer ოპერაციის შედეგის კოდი (ლინკით ResultCode გვერდზე). [result code](../result/result-codes.md) - `Match` — decimal number შიდა გადარიცხვის დროს, თანხვედრის % თქვენ მიერ აკრეფილი მიმღების დასახელებასთან. იურიდიული პირის შემთხვევაში მოწმდება ბანკში IBAN-ის ანგარიშის მფლობელის დასახელებასთან, ფიზიკური პირის შემთხვევაში კი – სახელთან და გვართან. შედარების შედეგად ბრუნდება დამთხვევის პროცენტული მაჩვენებელი. **JSON** ```json [ { "UniqueId": "7afaebef-5c0a-4876-aa47-13370f16fc8c", "UniqueKey": 2, "ResultCode": 1, "Match": 1.0 }, { "UniqueId": "7afaebef-5c0a-4876-aa47-13370f16fc8c", "UniqueKey": 2, "ResultCode": 1, "Match": 1.0 } ] ``` **XML** ```xml 1 1 7afaebef-5c0a-4876-aa47-13370f16fc8c 2 1 1 7afaebef-5c0a-4876-aa47-13370f16fc8c 2 ``` --- # ინდივიდუალური დოკუმენტების სტატუსები Source: https://api.bog.ge/docs/bonline/documents/status # ინდივიდუალური დოკუმენტების სტატუსები მეთოდის საშუალებით შესაძლებელია დოკუმენტების სტატუსების გაგება, მათი უნიკალური იდენტიფიკატორების მიხედვით. ## Query პარამეტრები - `key` — integer, required დოკუმენტის უნიკალური იდენტიფიკატორი business online-ში, ერთი ან რამდენიმე. **REQUEST** ```api GET api/documents/status/{key} ``` ## დაბრუნებული პარამეტრები# - `UniqueId` — globally unique identifier გარე (გამომძახებელ) სისტემაში დოკუმენტის უნიკალური იდენტიფიკატორი (Guid). - `UniqueKey` — integer დოკუმენტის უნიკალური იდენტიფიკატორი business online-ში. - `Status` — string დოკუმენტის სტატუსი. - `BulkLineStatus` — string გამოიყენება პაკეტური გადარიცხვის დროს. - `RejectCode` — integer უარყოფის კოდი. - `ResultCode` — integer ოპერაციის შედეგის კოდი. [result code](../result/result-codes.md) - `Match` — decimal number შიდა გადარიცხვის დროს, თანხვედრის % თქვენ მიერ აკრეფილი მიმღების დასახელებასთან. იურიდიული პირის შემთხვევაში მოწმდება ბანკში IBAN-ის ანგარიშის მფლობელის დასახელებასთან, ფიზიკური პირის შემთხვევაში კი – სახელთან და გვართან. შედარების შედეგად ბრუნდება დამთხვევის პროცენტული მაჩვენებელი. **JSON** ```json { "UniqueId": "11cca9ac-1a45-413b-a86a-d491f33f3668", "UniqueKey": 1, "Status": "sample string 2", "BulkLineStatus": "sample string 3", "RejectCode": 1, "ResultCode": 1, "Match": 1.0 } ``` **XML** ```xml sample string 3 1 1 1 sample string 2 11cca9ac-1a45-413b-a86a-d491f33f3668 1 ``` --- # ინდივიდუალური დოკუმენტების სტატუსები Source: https://api.bog.ge/docs/bonline/documents/statuses # ინდივიდუალური დოკუმენტების სტატუსები მეთოდის საშუალებით შესაძლებელია დოკუმენტების სტატუსების გაგება, მათი უნიკალური იდენტიფიკატორების მიხედვით. ## Query პარამეტრები - `key` — ერთი ან რამდენიმე integer, required დოკუმენტის უნიკალური იდენტიფიკატორი business online-ში, ერთი ან რამდენიმე. **REQUEST** ```api GET api/documents/statuses/{keys} ``` ## დაბრუნებული პარამეტრები# - `UniqueId` — globally unique identifier გარე (გამომძახებელ) სისტემაში დოკუმენტის უნიკალური იდენტიფიკატორი (Guid). - `UniqueKey` — integer დოკუმენტის უნიკალური იდენტიფიკატორი business online-ში. - `Status` — string დოკუმენტის სტატუსი. - `BulkLineStatus` — string გამოიყენება პაკეტური გადარიცხვის დროს. - `RejectCode` — integer უარყოფის კოდი. - `ResultCode` — integer ოპერაციის შედეგის კოდი (ლინკით ResultCode გვერდზე). [result code](../result/result-codes.md) - `Match` — decimal number შიდა გადარიცხვის დროს, თანხვედრის % თქვენ მიერ აკრეფილი მიმღების დასახელებასთან. იურიდიული პირის შემთხვევაში მოწმდება ბანკში IBAN-ის ანგარიშის მფლობელის დასახელებასთან, ფიზიკური პირის შემთხვევაში კი – სახელთან და გვართან. შედარების შედეგად ბრუნდება დამთხვევის პროცენტული მაჩვენებელი. **JSON** ```json [ { "UniqueId": "79d46ee2-2150-4fc0-b0b6-d22ea3476551", "UniqueKey": 1, "Status": "sample string 2", "BulkLineStatus": "sample string 3", "RejectCode": 1, "ResultCode": 1, "Match": 1.0 }, { "UniqueId": "79d46ee2-2150-4fc0-b0b6-d22ea3476551", "UniqueKey": 1, "Status": "sample string 2", "BulkLineStatus": "sample string 3", "RejectCode": 1, "ResultCode": 1, "Match": 1.0 } ] ``` **XML** ```xml sample string 3 1 1 1 sample string 2 79d46ee2-2150-4fc0-b0b6-d22ea3476551 1 sample string 3 1 1 1 sample string 2 79d46ee2-2150-4fc0-b0b6-d22ea3476551 1 ``` --- # მიმდინარე დღის აქტივობები Source: https://api.bog.ge/docs/bonline/documents/todayactivities # მიმდინარე დღის აქტივობები მეთოდის საშუალებით შესაძლებელია მიმდინარე დღის ყველა აქტივობის ნახვა. :::note ეს მეთოდი შეზღუდულია მოთხოვნების ლიმიტით — დაშვებულია დღეში 800 მოთხოვნა (ანგარიშისა და ვალუტის მიხედვით). ლიმიტის გადაჭარბებისას დაბრუნდება `429 Too Many Requests`, `Retry-After` ჰედერით (წამებში). ::: ## Query პარამეტრები - `accountNumber` — string, required ანგარიშის ნომერი - `currency` — string, required ვალუტა **REQUEST** ```api GET api/documents/todayactivities/{accountNumber}/{currency} ``` ## დაბრუნებული პარამეტრები# - `Id` — integer უნიკალური იდენტიფიკატორი - `DocKey` — integer დოკუმენტის უნიკალური იდენტიფიკატორი business online-ში - `DocNo` — string დოკუმენტის ნომერი - `PostDate` — date დოკუმენტის შექმნის თარიღი - `ValueDate` — date ვალუტირების თარიღი - `EntryType` — string გატარების ტიპი. იღებს შემდეგ მნიშვნელობებს: - PMC - სალარო ოპერაცია - PLC - საბარათე ოპერაცია - CDS - ანაბრის ოპერაცია - LND - სესხის ოპერაცია - PBS - ფეიბოქსის ოპერაცია - INC - ინკასო - PMD - ეროვნული ვალუტის გადარიცხვა - PMI - უცხოური ვალუტის გადარიცხვა - COM - საკომისიო - `EntryComment` — string გატარების კომენტარი, ოპერაციის შინაარსი - `EntryCommentEn` — string გატარების კომენტარი, ოპერაციის შინაარსი თარგმანი ინგლისურ ენაზე. - `Nomination` — string დოკუმენტის დანიშნულება - `Credit` — decimal number კრედიტი - `Debit` — decimal number დებიტი - `Amount` — decimal number თანხა - `AmountBase` — decimal number თანხა ექვივალენტი ლარში - `PayerName` — string გადამხდელის დასახელება - `PayerInn` — string გადამხდელის საიდენტიფიკაციო კოდი - `Sender` — object გამომგზავნის/გამგზავნის ინფორმაცია - `Name` — string დასახელება - `Inn` — string საიდენტიფიკაციო კოდი - `AccountNumber` — string ანგარიშის ნომერი - `BankCode` — string ბანკის კოდი - `BankName` — string ბანკის დასახელება - `Beneficiary` — object მიმღების ინფორმაცია - `Inn` — string საიდენტიფიკაციო კოდი - `AccountNumber` — string ანგარიშის ნომერი - `BankCode` — string ბანკის კოდი - `BankName` — string ბანკის დასახელება **JSON** ```json [ { "Id": 1, "DocKey": 2, "DocNo": "sample string 3", "PostDate": "2021-06-18T14:01:32.6806428+04:00", "ValueDate": "2021-06-18T14:01:32.6806428+04:00", "EntryType": "sample string 6", "EntryComment": "sample string 7", "EntryCommentEn": "sample string 8", "Nomination": "sample string 9", "Credit": 10.0, "Debit": 11.0, "Amount": 12.0, "AmountBase": 13.0, "PayerName": "sample string 14", "PayerInn": "sample string 15", "Sender": { "Name": "sample string 1", "Inn": "sample string 2", "AccountNumber": "sample string 3", "BankCode": "sample string 4", "BankName": "sample string 5" }, "Beneficiary": { "Name": "sample string 1", "Inn": "sample string 2", "AccountNumber": "sample string 3", "BankCode": "sample string 4", "BankName": "sample string 5" } }, { "Id": 1, "DocKey": 2, "DocNo": "sample string 3", "PostDate": "2021-06-18T14:01:32.6806428+04:00", "ValueDate": "2021-06-18T14:01:32.6806428+04:00", "EntryType": "sample string 6", "EntryComment": "sample string 7", "EntryCommentEn": "sample string 8", "Nomination": "sample string 9", "Credit": 10.0, "Debit": 11.0, "Amount": 12.0, "AmountBase": 13.0, "PayerName": "sample string 14", "PayerInn": "sample string 15", "Sender": { "Name": "sample string 1", "Inn": "sample string 2", "AccountNumber": "sample string 3", "BankCode": "sample string 4", "BankName": "sample string 5" }, "Beneficiary": { "Name": "sample string 1", "Inn": "sample string 2", "AccountNumber": "sample string 3", "BankCode": "sample string 4", "BankName": "sample string 5" } } ] ``` **XML** ```xml 12 13 sample string 3 sample string 4 sample string 5 sample string 2 sample string 1 10 11 2 sample string 3 sample string 7 sample string 8 sample string 6 1 sample string 9 2021-06-18T14:01:32.6806428+04:00 sample string 3 sample string 4 sample string 5 sample string 2 sample string 1 2021-06-18T14:01:32.6806428+04:00 12 13 sample string 3 sample string 4 sample string 5 sample string 2 sample string 1 10 11 2 sample string 3 sample string 7 sample string 8 sample string 6 1 sample string 9 2021-06-18T14:01:32.6806428+04:00 sample string 3 sample string 4 sample string 5 sample string 2 sample string 1 2021-06-18T14:01:32.6806428+04:00 ``` --- # ფაილის ატვირთვა Source: https://api.bog.ge/docs/bonline/files/upload # ფაილის ატვირთვა მეთოდის საშუალებით შესაძლებელია ფაილის ატვირთვა. ფაილი იგზავნება `multipart/form-data` ფორმატში, `file` ველით. წარმატებული მოთხოვნის შემთხვევაში ბრუნდება ატვირთული ფაილის ჰეში (`externalFileHash`), რომელიც შემდგომ გამოიყენება გადარიცხვის დოკუმენტებში დანართის მისაბმელად (`AttachmentIds` ველი). დასაშვები გაფართოებები: `docx`, `docm`, `dotx`, `dotm`, `docb`, `xls`, `xlsb`, `xlsm`, `xlsx`, `jpg`, `jpeg`, `png`, `ppt`, `gif`, `txt`, `pdf`, `zip`, `rar`, `tar`, `gzip`, `ico`, `dat`, `csv`, `xml`, `enc`, `svg`. დაუშვებელი გაფართოების ან ცარიელი ფაილის შემთხვევაში ბრუნდება HTTP სტატუს კოდი `400 Bad Request` შეტყობინებით `File extension is not allowed`. ## პარამეტრები - `file` — file, required ასატვირთი ფაილი. იგზავნება `multipart/form-data` ფორმის `file` ველით. **FORM-DATA** ```api POST api/files/upload Content-Type: multipart/form-data ``` ``` file: (binary) ``` ## დაბრუნებული პარამეტრები - `externalFileHash` — string ატვირთული ფაილის უნიკალური ჰეში. გამოიყენება გადარიცხვის დოკუმენტის შექმნისას `AttachmentIds` ველში. **JSON** ```json "sample string 1" ``` --- # Postman კოლექციები(NEW!) Source: https://api.bog.ge/docs/bonline/introduction-token სწრაფი დაწყებისა და API-ის საუკეთესო პრაქტიკების დასანერგად მოვამზადეთ Postman კოლექციები, რომლებიც მოიცავს API-ს ყველა endpoint-ს სრული კონფიგურაციით. - 📦 [ { e.preventDefault(); const link = document.createElement('a'); link.href = '/docs/files/BOG_BusinessOnline_API_KA.postman_collection.json'; link.download = 'BOG_BusinessOnline_API_KA.postman_collection.json'; document.body.appendChild(link); link.click(); document.body.removeChild(link); }}>**BOG Business Online API [KA]**](https://api.bog.ge/docs/docs/files/BOG_BusinessOnline_API_KA.postman_collection.json) — ქართულენოვანი ვერსია — v1.0.5 **კოლექციაში შედის:** - ავთენტიფიკაციის სამივე მეთოდი — Client Credentials Flow, Implicit Flow, Authorization Code Flow (Refresh Token-ის მხარდაჭერით) - ყველა დოკუმენტის endpoint — ეროვნული, უცხოური, კონვერტაცია, პაკეტური - ამონაწერი V1 და V2 (Pagination-ის მხარდაჭერით) - ვალუტის კურსები და ნაშთის შემოწმება - შეცდომების სცენარები (401, 404, 400) **ძირითადი მახასიათებლები:** - `ACCESS_TOKEN` ავტომატურად ინახება და გამოიყენება ყველა request-ში - `x-correlationid` header ავტომატურად იწერება Console-ში - `TODAY_DATE`, `LAST_DOCUMENT_KEY`, `LAST_BULK_KEY` ავტომატურად შეივსება Test Script-ების საშუალებით **დასაწყებად** შეავსეთ კოლექციის შემდეგი ცვლადები: | ცვლადი | აღწერა | |---|---| | `CLIENT_ID` | [bonline.bog.ge/admin/api](https://bonline.bog.ge/admin/api/)-დან | | `CLIENT_SECRET` | [bonline.bog.ge/admin/api](https://bonline.bog.ge/admin/api/)-დან | | `ACCOUNT_IBAN` | თქვენი ანგარიშის IBAN | | `BENEFICIARY_IBAN` | მიმღების IBAN | | `BENEFICIARY_BANK_CODE` | მიმღები ბანკის RTGS კოდი (BOG: `BAGAGE22`) | პირველ request-ად გაუშვით **1.1.1 [CC] ტოკენის მოთხოვნა** — შემდეგ ყველა სხვა endpoint ავტომატურად ავტორიზებული იქნება. --- # მიმოხილვა Source: https://api.bog.ge/docs/bonline/introduction ## რა არის ბიზნეს ინტერნეტბანკის API API შესაძლებლობას გაძლევთ ჩააშენოთ საქართველოს ბანკის ბიზნეს ინტერნეტბანკში არსებული ფუნქციონალი თქვენს საბუღალტრო ან სხვა ბიზნეს პროგრამაში და გაუმარტივოთ ყოველდღიური ოპერაციები თქვენს მომხმარებლებს, რომლებიც პროგრამიდან გაუსვლელად შეძლებენ ბიზნეს ინტერნეტბანკის ისეთ ფუნქციონალზე წვდომას, როგორიცაა: - **გადარიცხვის დოკუმენტების შექმნა** - მომხმარებლები თქვენს პროგრამაშივე შეძლებენ ეროვნულ და უცხოურ ვალუტაში გადარიცხვებისა და კონვერტაციის ინდივიდუალური და პაკეტური დოკუმენტების შექმნას. - **ამონაწერის მართვა** - მომხმარებლებს აღარ დასჭირდებათ ამონაწერის ატვირთვა. თქვენს პროგრამაში ხელმისაწვდომი იქნება ზოგადი ინფორმაცია პირველ 1000 ჩანაწერზე. მომხმარებლებს საშუალება ექნებათ თვალი ადევნონ ამონაწერის გლობალურ თუ ყოველდღიურ ნაშთებს მათთვის სასურველ პერიოდზე. - **ნაშთის შემოწმება ანგარიშზე** - მომხმარებლების საოპერაციო სივრცეში გამოჩნდება მათ ანგარიშებზე არსებული გამოყენებადი და მიმდინარე ნაშთები. - **ვალუტის კურსების კონტროლი** - თქვენს პროგრამაშივე იქნება ინტეგრირებული ინფორმაცია ეროვნული ბანკის სავალუტე კურსების, მათი ისტორიის, ბანკის კომერციული ან კროს კურსების შესახებ. - **დოკუმენტის ხელმოწერა** - ამ ფუნქციონალის ჩართვის შემთხვევაში კომპანიის თანამშრომლებს ექნებათ უფლება, თავად შექმნან გადარიცხვის დოკუმენტები თქვენი პროგრამიდან და ერთჯერადი კოდით თავადვე დაადასტურონ ხელმოწერით. - **ავტომატური დადასტურება** - შექმნასთან ერთად, თქვენ ასევე შეგიძლიათ მოითხოვოთ გადარიცხვების ავტომატიზაცია და ხელმოწერის გარეშე დაადასტუროთ ტრანზაქციები. ## რა არის საჭირო ინტეგრაციისთვის სერვისების ინტეგრაციის გასამარტივებლად ჩვენ სატესტო გარემო და გამარტივებული დოკუმენტაცია მოგიმზადეთ, რომლის მეშვეობითაც API სერვისების ჩაშენება პროგრამირების საბაზისო ცოდნით არის შესაძლებელი. ინტეგრაციისთვის აუცილებელია, რომ ორგანიზაციას ჰქონდეს [bonline.bog.ge](https://bonline.bog.ge) ანგარიში და სისტემაში შესასვლელი რეკვიზიტები. გამოსაძახებლად, პირველ რიგში, თქვენი აპლიკაცია უნდა დაარეგისტრიროთ შემდეგ ვებგვერდზე: [bonline.bog.ge/admin/api](https://bonline.bog.ge/admin/api/) რეგისტრაციისას უნდა მიუთითოთ აპლიკაციის სახელი, დასახელება უცხოურ ენაზე და თქვენთვის სასურველი ლოგოს მისამართი (სასურველია https პროტოკოლზე და ზომა არაუმეტეს 400x80 პიქსელისა). თუ არეგისტრირებთ web კლიენტს, მაშინ ასევე უნდა მიუთითოთ ვებმისამართი, რომელზეც მოხდება გადამისამართება აუტენტიფიკაციის დროს. რეგისტრაციის შემდეგ აპლიკაციის დეტალების გვერდზე გამოჩნდება აპლიკაციის იდენტიფიკატორები, რომლებიც დაგჭირდებათ აუტენთიფიკაციის მოთხოვნის დროს: - `client id` - `client secret ` - `redirect uri` (მხოლოდ web კლიენტის დროს) სერვისების სატესტო გარემოზე წვდომის მოსაპოვებლად მიმართეთ თქვენს ბიზნეს ბანკირს ან შეავსეთ განაცხადი. ## პროტოკოლი და ტექნიკური სპეციფიკაცია API-ს არქიტექტურული მიდგომა - `Restful`. ონლაინ განვადების აპლიკაციის პროტოკოლი: `HTTP/1.1`. უსაფრთხოების გაზრდის მიზნით, აუცილებელია API-ს ყველა მეთოდის გამოძახება https-ის გამოყენებით, რომელიც წარმოადგენს http პროტოკოლის გაფართოებას. სერვისის გამოძახების ტიპი - სინქრონული. უსაფრთხოების პროტოკოლი - `OAuth 2.0.` მხარეებს შორის ინფორმაციის გაცვლის უსაფრთხოების სტანდარტი - `JSON Web Tokens (JWT)`. API-ს მისამართი (BASE URL): `https://api.businessonline.ge/api` ყველა გამოძახების შემდეგ დაგიბრუნდებათ Header, სახელად x-correlationid, რომლის მნიშვნელობა უნიკალურია და რომელიც ამ მოთხოვნის იდენტიფიკატორია. რეკომენდებულია ამ იდენტიფიკატორის თქვენ მხარეს შენახვა, რადგან ხარვეზის შემთხვევაში ეს დაგვეხმარება თქვენი მოთხოვნის ზუსტად პოვნაში. დამატებითი ინფორმაციისთვის დაგვიკავშირდით ელექტრონულ ფოსტაზე: `customerservice@bog.ge` ## მოთხოვნების ლიმიტი (Rate Limit) API დაცულია მოთხოვნების ლიმიტით (rate limit). ნაგულისხმევად, ყველა მეთოდზე მოქმედებს ბაზისური ლიმიტი — თითო client-ზე წამში 5 მოთხოვნა; ცალკეულ მეთოდებს დამატებით უფრო მკაცრი ლიმიტები აქვთ (იხ. ცხრილი). ლიმიტის გადაჭარბებისას მოთხოვნა უარყოფილი იქნება `429 Too Many Requests` სტატუსით და პასუხს თან ერთვის `Retry-After` ჰედერი, რომელიც მიუთითებს, რამდენ წამში შეგიძლიათ მოთხოვნის ხელახლა გაგზავნა. | მეთოდი | ლიმიტი | | --- | --- | | ყველა მეთოდი (ნაგულისხმევი) | წამში 5 მოთხოვნა (თითო client-ზე) | | ვალუტის კურსები (`api/rates/*`, `api/v2/rates/{currency}`, `api/v2/crossrates/{sellCurrency}/{buyCurrency}`) | წუთში 60 მოთხოვნა (თითოეულ მეთოდზე ცალ-ცალკე) | | მიმდინარე დღის აქტივობები (`api/v2/documents/todayactivities/...`) | დღეში 800 მოთხოვნა (ანგარიშისა და ვალუტის მიხედვით) | ლიმიტი ითვლება აპლიკაციისა (client) და კონკრეტული მეთოდის მიხედვით, მოძრავი ფანჯრის (sliding window) პრინციპით. --- # თანხის მოთხოვნის შექმნა Source: https://api.bog.ge/docs/bonline/money-request/create # თანხის მოთხოვნის შექმნა მეთოდის საშუალებით შესაძლებელია თანხის მოთხოვნის შექმნა. მოთხოვნა იგზავნება მიმღებთან, რომელიც ადასტურებს გადარიცხვას. წარმატებული მოთხოვნის შემთხვევაში ბრუნდება HTTP სტატუს კოდი `201 Created`, დასაბრუნებელი ინფორმაცია (body) ცარიელია. ## პარამეტრები - `AccountNumber` — string, required თქვენი ანგარიშის ნომერი IBAN-ის ფორმატში, რომელზეც ჩაირიცხება მოთხოვნილი თანხა. მაგ: GE11BG1111111111111111 - `Currency` — string, required ვალუტა ISO 4217 ფორმატში (მაგალითად: GEL, USD, EUR). - `Amount` — decimal number, required მოთხოვნის თანხა. - `IsPhysical` — boolean, required მიმღების ტიპი. იღებს ორ მნიშვნელობას: - `TRUE` - ფიზიკური პირი. - `FALSE` - იურიდიული პირი. - `PhoneNumber` — string მიმღები ფიზიკური პირის ტელეფონის ნომერი. ივსება მხოლოდ ფიზიკური პირის შემთხვევაში (`IsPhysical=true`) — ზუსტად ერთი უნდა შეივსოს: `PhoneNumber` ან `Pin`. - `Pin` — string მიმღები ფიზიკური პირის პირადი ნომერი. ივსება მხოლოდ ფიზიკური პირის შემთხვევაში (`IsPhysical=true`) — ზუსტად ერთი უნდა შეივსოს: `PhoneNumber` ან `Pin`. - `RecipientIdentifier` — string მიმღები იურიდიული პირის საიდენტიფიკაციო კოდი. სავალდებულოა იურიდიული პირის შემთხვევაში (`IsPhysical=false`) — ამ დროს `PhoneNumber` და `Pin` ცარიელი უნდა იყოს. - `Description` — string, required მოთხოვნის დანიშნულება. **JSON** ```api POST api/moneyrequest/create Content-Type: application/json ``` ```json { "AccountNumber": "sample string 1", "Currency": "sample string 2", "Amount": 1.0, "IsPhysical": true, "PhoneNumber": "sample string 3", "Pin": "sample string 4", "RecipientIdentifier": "sample string 5", "Description": "sample string 6" } ``` --- # ერთჯერადი კოდის მოთხოვნა Source: https://api.bog.ge/docs/bonline/otp/request # ერთჯერადი კოდის მოთხოვნა ## პარამეტრები - `ObjectKey` — integer, required ობიექტის იდენთიფიკატორი - `ObjectType` — object, required ობიექტის ტიპი - `ObjectType.Payment` — integer, required გადახდა **JSON** ```api POST api/otp/request Content-Type: application/json ``` ```json { "ObjectKey": 1, "ObjectType": 0 } ``` **XML** ```api POST api/otp/request Content-Type: application/xml ``` ```xml 1 Payment ``` --- # ბანკის კომერციული კურსი Source: https://api.bog.ge/docs/bonline/rates/commercial-currency # ბანკის კომერციული კურსი მეთოდის საშუალებით შესაძლებელია საქართველოს ბანკში მოცემული ვალუტის ყიდვის და გაყიდვის მიმდინარე კომერციული კურსის გაგება, ქართულ ლართან მიმართებაში. :::note ეს მეთოდი შეზღუდულია მოთხოვნების ლიმიტით — დაშვებულია წუთში 60 მოთხოვნა. ლიმიტის გადაჭარბებისას დაბრუნდება `429 Too Many Requests`, `Retry-After` ჰედერით (წამებში). ::: ## Query პარამეტრები - `currency` — string, required ვალუტა ISO 4217 ფორმატში (მაგალითად: USD, GEL) **REQUEST** ```api GET api/rates/commercial/{currency} ``` ## დაბრუნებული პარამეტრები - `Sell` — decimal number მოცემული ვალუტის ბანკში გაყიდვის კომერციული კურსი. - `Buy` — decimal number მოცემული ვალუტის ბანკში ყიდვის კომერციული კურსი. **JSON** ```json { "Sell": 1.0, "Buy": 1.0 } ``` **XML** ```xml 1 1 ``` --- # კროს კურსი Source: https://api.bog.ge/docs/bonline/rates/commercial-sellCurrency-buyCurrency # კროს კურსი მეთოდის საშუალებით შესაძლებელია საქართველოს ბანკში გასაყიდი ვალუტის, საყიდელ ვალუტასთან მიმართებაში კომერციული კურსის გაგება. :::note ეს მეთოდი შეზღუდულია მოთხოვნების ლიმიტით — დაშვებულია წუთში 60 მოთხოვნა. ლიმიტის გადაჭარბებისას დაბრუნდება `429 Too Many Requests`, `Retry-After` ჰედერით (წამებში). ::: ## Query პარამეტრები - `sellCurrency` — string, required გასაყიდი ვალუტა ISO 4217 ფორმატში (მაგალითად: USD, GEL) - `buyCurrency` — string, required საყიდელი ვალუტა ISO 4217 ფორმატში (მაგალითად: USD, GEL) **REQUEST** ```api GET api/rates/commercial/{sellCurrency}/{buyCurrency} ``` ## დაბრუნებული პარამეტრები - — decimal number მოცემული ვალუტისთვის ეროვნული ბანკის მიერ დადგენილი კურსი **JSON** ```json 1.0 ``` **XML** ```xml 1 ``` --- # კროს კურსი Source: https://api.bog.ge/docs/bonline/rates/cross-rates # კროს კურსი მეთოდის საშუალებით შესაძლებელია საქართველოს ბანკში გასაყიდი ვალუტის, საყიდელ ვალუტასთან მიმართებაში დიჯიტალ არხების კურსის გაგება. კურსთან ერთად ბრუნდება საბაზო ვალუტაც. :::note მეთოდი მოითხოვს ავტორიზაციას (Bearer token). ასევე, მეთოდი შეზღუდულია მოთხოვნების ლიმიტით — დაშვებულია წუთში 60 მოთხოვნა. ლიმიტის გადაჭარბებისას დაბრუნდება `429 Too Many Requests`, `Retry-After` ჰედერით (წამებში). ::: ## Query პარამეტრები - `sellCurrency` — string, required გასაყიდი ვალუტა ISO 4217 ფორმატში (მაგალითად: USD, GEL) - `buyCurrency` — string, required საყიდელი ვალუტა ISO 4217 ფორმატში (მაგალითად: USD, GEL) **REQUEST** ```api GET api/v2/crossrates/{sellCurrency}/{buyCurrency} ``` ## დაბრუნებული პარამეტრები - `rate` — decimal number გასაყიდი ვალუტის საყიდელ ვალუტასთან მიმართებაში დიჯიტალ არხების კურსი. - `baseCcy` — string საბაზო ვალუტა ISO 4217 ფორმატში, რომლის მიმართაც არის გამოსახული კურსი. **JSON** ```json { "rate": 0.9200, "baseCcy": "USD" } ``` --- # ეროვნული ბანკის კურსების ისტორია Source: https://api.bog.ge/docs/bonline/rates/nbg-hist # ეროვნული ბანკის კურსების ისტორია მეთოდის საშუალებით შესაძლებელია სასურველი პერიოდისა და ვალუტისთვის, ქართულ ლართან მიმართებაში, ეროვნული ბანკის მიერ დადგენილი, მიმდინარე კურსის გაგება. მეთოდი აბრუნებს, გადაცემული პერიოდის, თითოეული თარიღისთვის ვალუტის კურსს. :::note ეს მეთოდი შეზღუდულია მოთხოვნების ლიმიტით — დაშვებულია წუთში 60 მოთხოვნა. ლიმიტის გადაჭარბებისას დაბრუნდება `429 Too Many Requests`, `Retry-After` ჰედერით (წამებში). ::: ## Query პარამეტრები - `currency` — string, required ვალუტა ISO 4217 ფორმატში (მაგალითად: USD, GEL) - `startDate` — date, required პერიოდის საწყისი თარიღი - `endDate` — date, required პერიოდის საბოლოო თარიღი **REQUEST** ```api GET api/rates/nbg/{currency}/{startDate}/{endDate} ``` ## დაბრუნებული პარამეტრები ერთი ან რამდენიმე - `Date` — date თარიღი - `Rate` — decimal number მოცემული ვალუტისთვის ეროვნული ბანკის მიერ დადგენილი კურსი. - `Currency` — string ანგარიშის ვალუტა ISO 4217 ფორმატში (მაგალითად: USD, GEL) **JSON** ```json [ { "Date": "2021-06-21T11:46:16.4280359+04:00", "Rate": 2.0, "Currency": "sample string 3" }, { "Date": "2021-06-21T11:46:16.4280359+04:00", "Rate": 2.0, "Currency": "sample string 3" } ] ``` **XML** ```xml sample string 3 2021-06-21T11:46:16.4280359+04:00 2 sample string 3 2021-06-21T11:46:16.4280359+04:00 2 ``` --- # ეროვნული ბანკის კურსი მითითებულ ვალუტისთვის Source: https://api.bog.ge/docs/bonline/rates/nbg # ეროვნული ბანკის კურსი მითითებულ ვალუტისთვის მეთოდის საშუალებით შესაძლებელია სასურველი ვალუტისთვის, ქართულ ლართან მიმართებაში, ეროვნული ბანკის მიერ დადგენილი, მიმდინარე კურსის გაგება. :::note ეს მეთოდი შეზღუდულია მოთხოვნების ლიმიტით — დაშვებულია წუთში 60 მოთხოვნა. ლიმიტის გადაჭარბებისას დაბრუნდება `429 Too Many Requests`, `Retry-After` ჰედერით (წამებში). ::: ## Query პარამეტრები - `currency` — string, required ვალუტა ISO 4217 ფორმატში (მაგალითად: USD, GEL) **REQUEST** ```api GET api/rates/nbg/{currency} ``` ## დაბრუნებული პარამეტრები - — decimal number მოცემული ვალუტისთვის ეროვნული ბანკის მიერ დადგენილი კურსი. **JSON** ```json 1.0 ``` **XML** ```xml 1 ``` --- # ვალუტის კურსების დეტალები Source: https://api.bog.ge/docs/bonline/rates/rate-details # ვალუტის კურსების დეტალები მეთოდის საშუალებით შესაძლებელია მითითებული ვალუტისთვის, ქართულ ლართან მიმართებაში, ერთ მოთხოვნაში დაბრუნდეს კურსების სრული ნაკრები: ეროვნული ბანკის კურსი, სტანდარტული ყიდვა/გაყიდვის კურსი და დიჯიტალ არხების ყიდვა/გაყიდვის კურსი. დიჯიტალ კურსი კლიენტზეა მიბმული — თუ ავტორიზებულ კლიენტს აქვს ინდივიდუალური (სპეც) კურსი, დაბრუნდება მისი სპეც კურსი, წინააღმდეგ შემთხვევაში — ჩვეულებრივი დიჯიტალ არხების კურსი. :::note მეთოდი მოითხოვს ავტორიზაციას (Bearer token). კურსები გამოითვლება ავტორიზებული კლიენტის მიხედვით. ასევე, მეთოდი შეზღუდულია მოთხოვნების ლიმიტით — დაშვებულია წუთში 60 მოთხოვნა. ლიმიტის გადაჭარბებისას დაბრუნდება `429 Too Many Requests`, `Retry-After` ჰედერით (წამებში). ::: ## Query პარამეტრები - `currency` — string, required ვალუტა ISO 4217 ფორმატში (მაგალითად: USD, EUR) **REQUEST** ```api GET api/v2/rates/{currency} ``` ## დაბრუნებული პარამეტრები - `nbgRate` — decimal number მოცემული ვალუტისთვის ეროვნული ბანკის მიერ დადგენილი კურსი. - `standardBuyRate` — decimal number მოცემული ვალუტის ბანკში ყიდვის სტანდარტული კურსი. - `standardSellRate` — decimal number მოცემული ვალუტის ბანკში გაყიდვის სტანდარტული კურსი. - `digitalBuyRate` — decimal number მოცემული ვალუტის ბანკში ყიდვის დიჯიტალ არხების კურსი. თუ კლიენტს აქვს სპეც კურსი, დაბრუნდება მისი სპეც კურსი. - `digitalSellRate` — decimal number მოცემული ვალუტის ბანკში გაყიდვის დიჯიტალ არხების კურსი. თუ კლიენტს აქვს სპეც კურსი, დაბრუნდება მისი სპეც კურსი. **JSON** ```json { "nbgRate": 2.7000, "standardBuyRate": 2.6500, "standardSellRate": 2.7500, "digitalBuyRate": 2.6600, "digitalSellRate": 2.7400 } ``` --- # პაკეტური გადარიცხვის სტატუსი Source: https://api.bog.ge/docs/bonline/result/bulk-transfer-statuses
Status Description
N დასამუშავებელი
S ხელმოწერილი
C გაუქმებულია მომხმარებლის მიერ
P ხელმოსაწერი
D დუბლირებული ფაილი
Z დოკუმენტი ხელმოწერის პროცესშია
I ინდივიდუალური დოკუმენტები შექმნილია
A მიმდინარეობს პაკეტური გადარიცხვის ხელმოწერა
B მიმდინარეობს დოკუმენტების შექმნა
U მიმდინარეობს ფაილის ატვირთვა, შემოწმება
R წაშლილი
--- # დოკუმენტის სტატუსი Source: https://api.bog.ge/docs/bonline/result/document-statuses
სტატუსი აღწერა
C გაუქმებულია მომხმარებლის მიერ
N დაუსრულებელი
D გაუქმებულია ბანკის მიერ
P შესრულებული
A ხელმოსაწერი
S ხელმოწერილი
T მუშავდება
R უარყოფილი
Z ხელმოწერის პროცესში
--- # შეცდომის კოდები Source: https://api.bog.ge/docs/bonline/result/reject-codes
Code აღწერა
22 გაუქმებულია, დამატებითი ინფორმაციისთვის დაგვიკავშირდით 2444444
21 მიმღების ანგარიში და დასახელება არ ედრება
20 დასადასტურებელი ბარათი
19 ვადაგასული ბარათი
18 დაბლოკილი ბარათი
17 არასაკმარისი თანხა
16 ფონტი არ იკითხება
15 არასწორი დანიშნულება
14 მიმღების ანგარიში არასწორია
13 არ არის მითითებული სახაზინო კოდი
12 არასწორი IBAN-ის ფორმატი
--- # შედეგის კოდები Source: https://api.bog.ge/docs/bonline/result/result-codes
api.label.result.code დოკუმენტის ტიპი აღწერა შედეგის ტიპი
-999 უცხოური ვალუტის გადარიცხვა ოპერაციის შესრულებისას დაფიქსირდა შეცდომა Error
-999 ოპერაციის შესრულებისას დაფიქსირდა შეცდომა Error
-998 უარყოფილია დოკუმენტის ვადის გასვლის გამო Warn
-99 კომუნალური გადახდები გადახდა ვერ შესრულდა, მოგვიანებით სცადეთ Error
-82 მითითებულ ანგარიშზე გადარიცხვა არ არის შესაძლებელი, რადგან ანგარიშის მფლობელს ბანკში გასაახლებელი აქვს პირადი ინფორმაცია Error
-21 უცხოური ვალუტის გადარიცხვა document.result.code.foreign.transfer.incorrect.amount Error
-21 document.result.code.foreign.transfer.incorrect.amount Error
-20 უცხოური ვალუტის გადარიცხვა document.result.code.foreign.transfer.incorrect.receiver.country Error
-20 document.result.code.foreign.transfer.incorrect.receiver.country Error
-19 უცხოური ვალუტის გადარიცხვა document.result.code.foreign.transfer.incorrect.receiver.status Error
-19 document.result.code.foreign.transfer.incorrect.receiver.status Error
-18 უცხოური ვალუტის გადარიცხვა document.result.code.foreign.transfer.not.enough.balance.on.account Warn
-18 document.result.code.foreign.transfer.not.enough.balance.on.account Warn
-17 უცხოური ვალუტის გადარიცხვა მიმღების ანგარიში არასწორია Error
-17 მიმღების ანგარიში არასწორია Error
-16 უცხოური ვალუტის გადარიცხვა საკომისიოს ანგარიში არასწორია Error
-16 საკომისიოს ანგარიში არასწორია Error
-15 უცხოური ვალუტის გადარიცხვა საკომისიოს პარამეტრების არასწორია Error
-15 საკომისიოს პარამეტრების არასწორია Error
-14 კომუნალური გადახდები გამგზავნის ანგარიში არასწორია Error
-14 უცხოური ვალუტის გადარიცხვა სისტემური ფაზა (მიმდინარეობს დღის დახურვა) Error
-14 სისტემური ფაზა (მიმდინარეობს დღის დახურვა) Error
-13 უცხოური ვალუტის გადარიცხვა document.result.code.foreign.transfer.template.not.found Error
-13 document.result.code.foreign.transfer.template.not.found Error
-12 უცხოური ვალუტის გადარიცხვა ვალუტა არასწორია Error
-12 ვალუტა არასწორია Error
-11 უცხოური ვალუტის გადარიცხვა ვალუტირების თარიღი არასწორია Error
-11 ვალუტირების თარიღი არასწორია Error
-10 უცხოური ვალუტის გადარიცხვა დამატებითი ინფორმაციის ფორმატი არასწორია. სიმბოლოების რაოდენობა არ უნდა აღემატებოდეს 210-ს. Error
-10 დამატებითი ინფორმაციის ფორმატი არასწორია. სიმბოლოების რაოდენობა არ უნდა აღემატებოდეს 210-ს. Error
-9 უცხოური ვალუტის გადარიცხვა გადარიცხვის დანიშნულების ფორმატი არავალიდურია. დასაშვები სიმბოლოებია a-z A-Z 0-9 /-?)., ' + : Error
-9 გადარიცხვის დანიშნულების ფორმატი არავალიდურია. დასაშვები სიმბოლოებია a-z A-Z 0-9 /-?)., ' + : Error
-8 კომუნალური გადახდები document.result.code.electronic.payment.https.error Warn
-8 უცხოური ვალუტის გადარიცხვა მიმღების ანგარიში არასწორია Error
-8 მიმღების ანგარიში არასწორია Error
-7 უცხოური ვალუტის გადარიცხვა მიმღები ბანკის მონაცემები არასწორია, თავიდან სცადეთ Error
-7 მიმღები ბანკის მონაცემები არასწორია, თავიდან სცადეთ Error
-6 უცხოური ვალუტის გადარიცხვა შუამავალის ინფორმაცია ცარიელია Error
-6 შუამავალის ინფორმაცია ცარიელია Error
-5 უცხოური ვალუტის გადარიცხვა მიმღების დასახელება არავალიდურია Error
-5 მიმღების დასახელება არავალიდურია Error
-4 უცხოური ვალუტის გადარიცხვა გამგზავნის დასახელება ცარიელია Error
-4 გამგზავნის დასახელება ცარიელია Error
-3 უცხოური ვალუტის გადარიცხვა გამგზავნის ანგარიში არასწორია Error
-3 გამგზავნის ანგარიში არასწორია Error
-2 უცხოური ვალუტის გადარიცხვა მოცემულ ანგარიშზე, მოცემული პარამეტრებით გადარიცხვა დაუშვებელია Error
-2 მოცემულ ანგარიშზე, მოცემული პარამეტრებით გადარიცხვა დაუშვებელია Error
-1 უცხოური ვალუტის გადარიცხვა გამგზავნი და მიმღების ანგარიშების ვალუტა არასწორია Error
-1 გამგზავნი და მიმღების ანგარიშების ვალუტა არასწორია Error
0 დოკუმენტი მზად არის ხელმოსაწერად Success
1 დოკუმენტი არ მოიძებნა Error
2 დოკუმენტის ტიპი არ მოიძებნა Error
4 კონვერტაცია კონვერტაციის კურსი არასწორია Error
28 გარე გამვალ გადარიცხვაში გამოყენებულია CheckInn პარამეტრი. ეს პარამეტრი გამოიყენება მხოლოდ საქართველოს ბანკში გადარიცხვის დროს Error
29 მიმღების ანგარიშის ნომერი და საიდენთიფიკაციო კოდი არასწორია Error
30 მიმღების ანგარიშის ნომერი ან/და ბანკის კოდი ცარიელია Error
31 გამგზავნის ან მიმღების ბანკის კოდი არასწორია Error
32 გადარიცხვა არ არის შესაძლებელი Error
33 საქართველოში გამგზავნის საიდენტიფიკაციო კოდი არ მოიძებნა Error
33 გამგზავნის ანგარიში არასწორია Error
34 გამგზავნის ანგარიშის ვალუტა არასწორია Error
35 მითითბული ანგარიშიდან შეუძლებელია ოპერაციის შესრულება Error
36 გამგზავნის საიდენტიფიკაციო კოდი არასწორია Error
37 მიმღების ანგარიში ცარიელია Error
38 მიმღების ანგარიშის სიგრძე დასშვებზე მეტია Error
39 მიმღების ანგარიში არასწორია Error
40 სახაზინო კოდი არასწორია Error
41 მიმღების ს/კ არასწორია Error
42 მიმღების დასახელება არავალიდურია Error
43 მიმღების დასახელება არ უნდა აღემატებოდეს 160 სიმბოლოს Error
44 მიმღების ანგარიში არასწორია Error
45 მიმღების ანგარიშის ვალუტა არასწორია Error
46 მითითბულ ანგარიშებს შორის შეუძლებელია ოპერაციის შესრულება Error
47 დოკუმენტის ხელმოწერის ვადა ამოიწურა Error
48 ვალუტირების თარიღი არასწორია Error
49 გადარიცხვის ვალუტა არასწორია Error
50 თანხის ფორმატი არასწორია Error
51 საკომისიო თანხის ფორმატი არასწორია Error
52 გადამხდელის საიდენტიფიკაციო კოდი არასწორია Error
53 გადამხდელის დასახელება არ უნდა აღემატებოდეს 160 სიმბოლოს Error
54 გადარიცხვის დანიშნულება ცარიელია Error
55 დანიშნულების ველი არ უნდა აღემატებოდეს 250 სიმბოლოს Error
56 დამატებითი ინფორმაციის ველი არ უნდა აღემატებოდეს 250 სიმბოლოს Error
57 დოკუმენტის ვალიდაციისას დაფიქსირდა შეცდომა Error
58 საკომისიოს ანგარიში არასწორია Error
59 გადამხდელის სახელი და გადამხდელის კოდი ივსება მხოლოდ ბიუჯეტის სასარგებლოდ მესამე პირის ნაცვლად/მაგივრად გადარიცხვის შესრულებისას Error
60 მიმღების საიდენთიფიკაციო კოდი ცარიელია Error
61 საქართველოს ბანკში საიდენტიფიკაციო კოდის სიმბოლოების რაოდენობა არ უნდა აღემატებოდეს 14-ს Error
61 საქართველოში საიდენტიფიკაციო კოდის სიმბოლოების რაოდენობა არ უნდა აღემატებოდეს 14-ს Error
71 უცხოური ვალუტის გადარიცხვა გამგზავნი და მიმღების ანგარიშების ვალუტა არასწორია Error
72 მოცემულ ანგარიშზე, მოცემული პარამეტრებით გადარიცხვა დაუშვებელია Error
73 უცხოური ვალუტის გადარიცხვა გამგზავნის ანგარიში არასწორია Error
74 უცხოური ვალუტის გადარიცხვა გამგზავნის დასახელება ცარიელია Error
75 უცხოური ვალუტის გადარიცხვა მიმღების დასახელება არავალიდურია Error
76 უცხოური ვალუტის გადარიცხვა შუამავალის ინფორმაცია ცარიელია Error
77 უცხოური ვალუტის გადარიცხვა მიმღები ბანკის მონაცემები არასწორია, თავიდან სცადეთ Error
78 უცხოური ვალუტის გადარიცხვა მიმღების ანგარიში არასწორია Error
79 უცხოური ვალუტის გადარიცხვა გადარიცხვის დანიშნულების ფორმატი არავალიდურია. დასაშვები სიმბოლოებია a-z A-Z 0-9 /-?)., ' + : Error
80 უცხოური ვალუტის გადარიცხვა დამატებითი ინფორმაციის ფორმატი არასწორია. სიმბოლოების რაოდენობა არ უნდა აღემატებოდეს 210-ს. Error
81 უცხოური ვალუტის გადარიცხვა ვალუტირების თარიღი არასწორია Error
81 საქართველოს ბანკში ვალუტირების თარიღი არასწორია Error
82 უცხოური ვალუტის გადარიცხვა ვალუტა არასწორია Error
83 უცხოური ვალუტის გადარიცხვა არასაკმარისი თანხა Error
83 საკუთარ ანგარიშებს შორის არასაკმარისი თანხა Error
84 უცხოური ვალუტის გადარიცხვა სისტემური ფაზა (მიმდინარეობს დღის დახურვა) Error
85 უცხოური ვალუტის გადარიცხვა საკომისიოს პარამეტრების არასწორია Error
86 უცხოური ვალუტის გადარიცხვა საკომისიოს ანგარიში არასწორია Error
87 უცხოური ვალუტის გადარიცხვა მიმღების ანგარიში არასწორია Error
90 მიმღების დასახელება გრძელია Error
91 დანიშნულება გრძელია Error
92 უცხოური ვალუტის გადარიცხვა მიმღების ქვეყნის კოდი არავალიდურია Error
96 უცხოური ვალუტის გადარიცხვა დანიშნულების აღწერა არა ვალიდურია, გთხოვთ სწორად მიუთითოთ კოდი Error
110 კონვერტაცია თანხის ფორმატი არასწორია Error
111 კონვერტაცია გადარიცხვის ვალუტა არასწორია Error
112 კონვერტაცია გამგზავნის ანგარიში არასწორია Error
113 კონვერტაცია მიმღების ანგარიში არასწორია Error
114 კონვერტაცია გამგზავნი და მიმღების ანგარიშები ერთიდაიგივეა Error
115 კონვერტაცია გამგზავნი და მიმღების ანგარიშების ვალუტა ერთიდაიგივეა Error
116 კონვერტაცია გამგზავნი და მიმღები სხვადასხვა კლიენტია Error
117 კონვერტაცია გამგზავნი და მიმღები ფილიალი სხვადასხვაა, აირჩიეთ სხვა ანგარიშები ან მიმართეთ ბანკს Error
118 კონვერტაცია დოკუმენტში პარამეტრები არასწორია Error
119 კონვერტაცია დანიშნულება დასაშვებზე გრძელია Error
120 კონვერტაცია ოპერაციის ვალუტისთვის ვერ მოიძებნა კურსი Error
121 კონვერტაცია ოპერაციის ვალუტა არასწორია Error
122 კონვერტაცია ოპერაციის შესრულებისას დაფიქსირდა შეცდომა Error
123 კონვერტაცია ოპერაციის შესრულებისას დაფიქსირდა შეცდომა Error
124 გამგზავნის ანგარიში არასწორია. გთხოვთ გაასწოროთ და კიდევ სცადოთ Error
147 არასწორი IBAN-ის ფორმატი Error
150 აუცილებელი ველი Error
151 ველის მნიშვნელობა უნდა იყოს რიცვითი Error
152 ველის ფორმატი არასწორია Error
153 ს/კ სიგრძე არ უნდა აღემატებოდეს 11 სიმბოლოს Error
154 ველის მნიშვნელობა არ მოიძებნა Error
155 ხელფასის გადარიცხვა ხორციელდება მხოლოდ ფიზიკურ პირზე Error
157 უცხოური ვალუტის გადარიცხვა document.bulk.result.code.pmi.recip.name.length Error
158 უცხოური ვალუტის გადარიცხვა document.bulk.result.code.pmi.regreporting.required.field Error
333 სამუშაო ნაშთი არ არის საკმარისი. გსურთ საბუთის შექმნა? Warn
363 დოკუმენტი დუბლირებულია. გსურთ საბუთის შექმნა? Warn
444 თანხა არ არის საკმარისი Warn
500 ზოგადი შეცდომა Error
666 error.message.documents.wrong.content.symbols Error
669 ატვირთეთ ინვოისი ან კონტრაქტი Error
670 მიმღების ანგარიში არასწორია Error
671 საქართველოში მიმღების ანგარიში არასწორია Error
671 ანგარიშის ნომერი არასწორია Error
673 უცხოური ვალუტის გადარიცხვა document.bulk.result.code.pmi.recipient.required.fields Error
674 უცხოური ვალუტის გადარიცხვა თქვენ არ გაქვთ მოცემულ ანგარიშზე გადარიცხვის უფლება Error
674 საქართველოს ბანკში თქვენ არ გაქვთ მოცემულ ანგარიშზე გადარიცხვის უფლება Error
674 საქართველოში თქვენ არ გაქვთ მოცემულ ანგარიშზე გადარიცხვის უფლება Error
674 თქვენ არ გაქვთ მოცემულ ანგარიშზე გადარიცხვის უფლება Error
675 document.result.code.source.account.invalid Error
676 document.result.code.has.not.access.to.source.account Error
677 უცხოური ვალუტის გადარიცხვა document.result.code.nomination.is.mandatory Error
677 საქართველოს ბანკში document.result.code.nomination.is.mandatory Error
677 საქართველოში document.result.code.nomination.is.mandatory Error
678 უცხოური ვალუტის გადარიცხვა document.result.code.dispatch.type.is.mandatory Error
678 საქართველოში document.result.code.dispatch.type.is.mandatory Error
679 document.result.code.wrong.comission.account Error
701 დოკუმენტის მნიშვნელობებმა ვალიდაციები ვერ გაიარა Warn
999 ოპერაციის შესრულებისას დაფიქსირდა შეცდომა Error
1001 არ გაქვთ გადარიცხვის უფლება Error
1002 მიმღები ბანკის მონაცემები არასწორია, თავიდან სცადეთ Error
9999 document.result.code.unknown.error Error
--- # დოკუმენტის ხელმოწერა Source: https://api.bog.ge/docs/bonline/sign/document # დოკუმენტის ხელმოწერა ## პარამეტრები - `Otp` — string, required ერთჯერადი კოდი - `ObjectKey` — integer, required დოკუმენტის იდენთიფიკატორი **JSON** ```api POST api/sign/document Content-Type: application/json ``` ```json { "Otp": "sample string 1", "ObjectKey": 2 } ``` **XML** ```api POST api/sign/document Content-Type: application/xml ``` ```xml 2 sample string 1 ``` --- # ამონაწერის ჩანაწერები მითითებულ გვერდზე Source: https://api.bog.ge/docs/bonline/statement/paging # ამონაწერის ჩანაწერები მითითებულ გვერდზე მეთოდის საშუალებით შესაძლებელია კონკრეტული ანგარიშისთვის უკვე დაგენერირებული ამონაწერიდან 1000 ჩანაწერის ნახვა. ## Query პარამეტრები - `accountNumber` — string, required ანგარიშის ნომერი - `currency` — string, required ანგარიშის ვალუტა - `id` — integer, required ამონაწერის უნიკალური იდენტიფიკატორი - `page` — integer, required ამონაწერის ჩანაწერების გვერდი **REQUEST** ```api GET api/statement/{accountNumber}/{currency}/{id}/{page} ``` ## დაბრუნებული პარამეტრები - `EntryDate` — date გატარების თარიღი - `EntryDocumentNumber` — string გატარების ნომერი - `EntryAccountNumber` — string გატარების ანგარიშის ნომერი - `EntryAmountDebit` — decimal number გატარების თანხა (დებიტი) - `EntryAmountDebitBase` — decimal number დებეტი ექვივალენტი ლარში - `EntryAmountCredit` — decimal number გატარების თანხა (კრედიტი) - `EntryAmountCreditBase` — decimal number კრედიტი ექვივალენტი ლარში - `EntryAmountBase` — decimal number თანხა ექვივალენტი ლარში - `EntryAmount` — decimal number შემოსვლის თანხა - `EntryComment` — string გატარების კომენტარი, ოპერაციის შინაარსი - `EntryDepartment` — string - `EntryAccountPoint` — string - `DocumentProductGroup` — string ოპერაციის ტიპი, დოკუმენტის პროდუქტის ჯგუფი - `DocumentValueDate` — date დოკუმენტის ვალუტირების თარიღი - `SenderDetails` — object გამომგზავნის/გამგზავნის ინფორმაცია - `Name` — string დასახელება - `Inn` — string საიდენტიფიკაციო კოდი - `AccountNumber` — string ანგარიშის ნომერი - `BankCode` — string ბანკის კოდი - `BankName` — string ბანკის დასახელება - `BeneficiaryDetails` — object მიმღების ინფორმაცია - `Name` — string დასახელება - `Inn` — string საიდენტიფიკაციო კოდი - `AccountNumber` — string ანგარიშის ნომერი - `BankCode` — string ბანკის კოდი - `BankName` — string ბანკის დასახელება - `DocumentTreasuryCode` — string სახაზინო კოდი - `DocumentNomination` — string გადარიცხვის საფუძველი, დანიშნულება / მაქსიმუმ 250 სიმბოლო - `DocumentInformation` — string დამატებითი ინფორმაცია - `DocumentSourceAmount` — decimal number საწყისი თანხა - `DocumentSourceCurrency` — string საწყისი ვალუტა - `DocumentDestinationAmount` — decimal number საბოლოო თანხა - `DocumentDestinationCurrency` — string საბოლოო ვალუტა - `DocumentReceiveDate` — date მიღების თარიღი - `DocumentBranch` — string - `DocumentDepartment` — string - `DocumentActualDate` — date - `DocumentExpiryDate` — date - `DocumentRateLimit` — decimal number - `DocumentRate` — decimal number კონვერტაციის კურსი - `DocumentRegistrationRate` — decimal number დოკუმენტის რეგისტრაციის კურსი. - `DocumentSenderInstitution` — string - `DocumentIntermediaryInstitution` — string - `DocumentBeneficiaryInstitution` — string - `DocumentPayee` — string გადამხდელი - `DocumentCorrespondentAccountNumber` — string საკორესპონდენტო ანგარიში - `DocumentCorrespondentBankCode` — string საკორესპონდენტო ბანკის კოდი - `DocumentCorrespondentBankName` — string საკორესპონდენტო ბანკის სახელი - `DocumentKey` — decimal number დოკუმენტის უნიკალური ნომერი (ბანკში) - `EntryId` — decimal number გატარების უნიკალური ნომერი - `DocumentPayerName` — string გადამხდელის სახელი - `DocumentPayerInn` — string გადამხდელის – ფიზიკური პირის პირადი ნომერი, იურიდიული პირის საიდენტიფიკაციო კოდი ივსება მხოლოდ! ბიუჯეტის სასარგებლოდ მესამე პირის ნაცვლად/მაგივრად გადარიცხვის შესრულებისას, მიუთითეთ მესამე პირის საიდენტიფიკაციო კოდი - `DocComment` — string კომენტარი **JSON** ```json [ { "EntryDate": "2021-06-21T10:56:19.8506404+04:00", "EntryDocumentNumber": "sample string 1", "EntryAccountNumber": "sample string 2", "EntryAmountDebit": 1.0, "EntryAmountDebitBase": 1.0, "EntryAmountCredit": 1.0, "EntryAmountCreditBase": 1.0, "EntryAmountBase": 1.0, "EntryAmount": 1.0, "EntryComment": "sample string 3", "EntryDepartment": "sample string 4", "EntryAccountPoint": "sample string 5", "DocumentProductGroup": "sample string 6", "DocumentValueDate": "2021-06-21T10:56:19.8506404+04:00", "SenderDetails": { "Name": "sample string 1", "Inn": "sample string 2", "AccountNumber": "sample string 3", "BankCode": "sample string 4", "BankName": "sample string 5" }, "BeneficiaryDetails": { "Name": "sample string 1", "Inn": "sample string 2", "AccountNumber": "sample string 3", "BankCode": "sample string 4", "BankName": "sample string 5" }, "DocumentTreasuryCode": "sample string 7", "DocumentNomination": "sample string 8", "DocumentInformation": "sample string 9", "DocumentSourceAmount": 1.0, "DocumentSourceCurrency": "sample string 10", "DocumentDestinationAmount": 1.0, "DocumentDestinationCurrency": "sample string 11", "DocumentReceiveDate": "2021-06-21T10:56:19.8506404+04:00", "DocumentBranch": "sample string 12", "DocumentDepartment": "sample string 13", "DocumentActualDate": "2021-06-21T10:56:19.8506404+04:00", "DocumentExpiryDate": "2021-06-21T10:56:19.8506404+04:00", "DocumentRateLimit": 1.0, "DocumentRate": 1.0, "DocumentRegistrationRate": 1.0, "DocumentSenderInstitution": "sample string 14", "DocumentIntermediaryInstitution": "sample string 15", "DocumentBeneficiaryInstitution": "sample string 16", "DocumentPayee": "sample string 17", "DocumentCorrespondentAccountNumber": "sample string 18", "DocumentCorrespondentBankCode": "sample string 19", "DocumentCorrespondentBankName": "sample string 20", "DocumentKey": 1.0, "EntryId": 1.0, "DocumentPayerName": "sample string 21", "DocumentPayerInn": "sample string 22", "DocComment": "sample string 23" }, { "EntryDate": "2021-06-21T10:56:19.8506404+04:00", "EntryDocumentNumber": "sample string 1", "EntryAccountNumber": "sample string 2", "EntryAmountDebit": 1.0, "EntryAmountDebitBase": 1.0, "EntryAmountCredit": 1.0, "EntryAmountCreditBase": 1.0, "EntryAmountBase": 1.0, "EntryAmount": 1.0, "EntryComment": "sample string 3", "EntryDepartment": "sample string 4", "EntryAccountPoint": "sample string 5", "DocumentProductGroup": "sample string 6", "DocumentValueDate": "2021-06-21T10:56:19.8506404+04:00", "SenderDetails": { "Name": "sample string 1", "Inn": "sample string 2", "AccountNumber": "sample string 3", "BankCode": "sample string 4", "BankName": "sample string 5" }, "BeneficiaryDetails": { "Name": "sample string 1", "Inn": "sample string 2", "AccountNumber": "sample string 3", "BankCode": "sample string 4", "BankName": "sample string 5" }, "DocumentTreasuryCode": "sample string 7", "DocumentNomination": "sample string 8", "DocumentInformation": "sample string 9", "DocumentSourceAmount": 1.0, "DocumentSourceCurrency": "sample string 10", "DocumentDestinationAmount": 1.0, "DocumentDestinationCurrency": "sample string 11", "DocumentReceiveDate": "2021-06-21T10:56:19.8506404+04:00", "DocumentBranch": "sample string 12", "DocumentDepartment": "sample string 13", "DocumentActualDate": "2021-06-21T10:56:19.8506404+04:00", "DocumentExpiryDate": "2021-06-21T10:56:19.8506404+04:00", "DocumentRateLimit": 1.0, "DocumentRate": 1.0, "DocumentRegistrationRate": 1.0, "DocumentSenderInstitution": "sample string 14", "DocumentIntermediaryInstitution": "sample string 15", "DocumentBeneficiaryInstitution": "sample string 16", "DocumentPayee": "sample string 17", "DocumentCorrespondentAccountNumber": "sample string 18", "DocumentCorrespondentBankCode": "sample string 19", "DocumentCorrespondentBankName": "sample string 20", "DocumentKey": 1.0, "EntryId": 1.0, "DocumentPayerName": "sample string 21", "DocumentPayerInn": "sample string 22", "DocComment": "sample string 23" } ] ``` **XML** ```xml sample string 3 sample string 4 sample string 5 sample string 2 sample string 1 sample string 23 2021-06-21T10:56:19.8506404+04:00 sample string 16 sample string 12 sample string 18 sample string 19 sample string 20 sample string 13 1 sample string 11 2021-06-21T10:56:19.8506404+04:00 sample string 9 sample string 15 1 sample string 8 sample string 17 sample string 22 sample string 21 sample string 6 1 1 2021-06-21T10:56:19.8506404+04:00 1 sample string 14 1 sample string 10 sample string 7 2021-06-21T10:56:19.8506404+04:00 sample string 2 sample string 5 1 1 1 1 1 1 sample string 3 2021-06-21T10:56:19.8506404+04:00 sample string 4 sample string 1 1 sample string 3 sample string 4 sample string 5 sample string 2 sample string 1 sample string 3 sample string 4 sample string 5 sample string 2 sample string 1 sample string 23 2021-06-21T10:56:19.8506404+04:00 sample string 16 sample string 12 sample string 18 sample string 19 sample string 20 sample string 13 1 sample string 11 2021-06-21T10:56:19.8506404+04:00 sample string 9 sample string 15 1 sample string 8 sample string 17 sample string 22 sample string 21 sample string 6 1 1 2021-06-21T10:56:19.8506404+04:00 1 sample string 14 1 sample string 10 sample string 7 2021-06-21T10:56:19.8506404+04:00 sample string 2 sample string 5 1 1 1 1 1 1 sample string 3 2021-06-21T10:56:19.8506404+04:00 sample string 4 sample string 1 1 sample string 3 sample string 4 sample string 5 sample string 2 sample string 1 ``` --- # ამონაწერის ჩანაწერები მითითებულ გვერდზე Source: https://api.bog.ge/docs/bonline/statement/pagingV2 # ამონაწერის ჩანაწერები მითითებულ გვერდზე მეთოდი გამოიყენება მითითებული ანგარიშის საბანკო ამონაწერის ჩანაწერების ეტაპობრივად (გვერდებად) მისაღებად. სერვისი ამუშავებს მოთხოვნას რეალურ დროში და აბრუნებს ტრანზაქციების დეტალურ ჩამონათვალს არსებული საბანკო მონაცემებიდან. ერთ მოთხოვნაზე შესაძლებელია მაქსიმუმ 1000 ჩანაწერის მიღება. გვერდების გამოტოვება არ შეიძლება — მაგალითად, თუ უკვე მიღებულია მე-3 გვერდი, მომდევნო მოთხოვნა უნდა იყოს მე-4-ზე; მე-6 გვერდის მოთხოვნა მე-3-ის შემდეგ დაუშვებელია. ## Query პარამეტრები - `accountNumber` — string, required ანგარიშის ნომერი - `currency` — string, required ანგარიშის ვალუტა - `id` — integer, required ამონაწერის უნიკალური იდენტიფიკატორი - `page` — integer, required ამონაწერის ჩანაწერების გვერდი **REQUEST** ```api GET api/v2/statement/{accountNumber}/{currency}/{id}/{page} ``` ## დაბრუნებული პარამეტრები - `Id` — integer უნიკალური იდენტიფიკატორი - `Count` — integer ჩანაწერების რაოდენობა - `TotalCount` — integer მოთხოვნილ პერიოდში არსებული ჩანაწერების საერთო რაოდენობა, გვერდების დაყოფის მიუხედავად. - `Records` — object ჩანაწერები, ტრანზაქციის დეტალები - `EntryDate` — date გატარების თარიღი - `EntryDocumentNumber` — string გატარების ნომერი - `EntryAccountNumber` — string გატარების ანგარიშის ნომერი - `EntryAmountDebit` — decimal number გატარების თანხა (დებიტი) - `EntryAmountDebitBase` — decimal number დებეტი ექვივალენტი ლარში - `EntryAmountCredit` — decimal number გატარების თანხა (კრედიტი) - `EntryAmountCreditBase` — decimal number კრედიტი ექვივალენტი ლარში - `EntryAmountBase` — decimal number თანხა ექვივალენტი ლარში - `EntryAmount` — decimal number შემოსვლის თანხა - `EntryComment` — string გატარების კომენტარი, ოპერაციის შინაარსი - `DocumentProductGroup` — string ოპერაციის ტიპი, დოკუმენტის პროდუქტის ჯგუფი - `DocumentValueDate` — date დოკუმენტის ვალუტირების თარიღი - `SenderDetails` — object გამომგზავნის/გამგზავნის ინფორმაცია - `Name` — string დასახელება - `Inn` — string საიდენტიფიკაციო კოდი - `AccountNumber` — string ანგარიშის ნომერი - `BankCode` — string ბანკის კოდი - `BankName` — string ბანკის დასახელება - `BeneficiaryDetails` — object მიმღების ინფორმაცია - `Name` — string დასახელება - `Inn` — string საიდენტიფიკაციო კოდი - `AccountNumber` — string ანგარიშის ნომერი - `BankCode` — string ბანკის კოდი - `BankName` — string ბანკის დასახელება - `DocumentTreasuryCode` — string სახაზინო კოდი - `DocumentNomination` — string გადარიცხვის საფუძველი, დანიშნულება / მაქსიმუმ 250 სიმბოლო - `DocumentInformation` — string დამატებითი ინფორმაცია - `DocumentSourceAmount` — decimal number საწყისი თანხა - `DocumentSourceCurrency` — string საწყისი ვალუტა - `DocumentDestinationAmount` — decimal number საბოლოო თანხა - `DocumentDestinationCurrency` — string საბოლოო ვალუტა - `DocumentReceiveDate` — date მიღების თარიღი - `DocumentRate` — decimal number კონვერტაციის კურსი (ეროვნული ბანკის მიერ დადგენილი კურსი) - `DocumentKey` — decimal number დოკუმენტის უნიკალური ნომერი (ბანკში) - `EntryId` — decimal number გატარების უნიკალური ნომერი - `DocumentPayerName` — string გადამხდელის სახელი - `DocumentPayerInn` — string გადამხდელის – ფიზიკური პირის პირადი ნომერი, იურიდიული პირის საიდენტიფიკაციო კოდი ივსება მხოლოდ! ბიუჯეტის სასარგებლოდ მესამე პირის ნაცვლად/მაგივრად გადარიცხვის შესრულებისას, მიუთითეთ მესამე პირის საიდენტიფიკაციო კოდი - `DocComment` — string გატარების კომენტარი, ოპერაციის შინაარსი. შედგება გატარების რამდენიმე ატრიბუტის მნიშვნელობის გაერთიანებით. (მაგალითად: "ავტომატური გადახდების მომსახურებით გადასახდელის გადახდა, 22/12/2021 , სს ""სადაზღვევო კომპანია"", : სახელი გვარი GE75BG00000000000000000GEL სს ""საქართველოს ბანკი"" BAGAGE22") - `AuthDate` — date ოპერაციის ავტორიზაციის თარიღი. **JSON** ```json [ { "entryDate": "2021-06-21T10:56:19.8506404+04:00", "entryDocumentNumber": "sample string 1", "entryAccountNumber": "sample string 2", "entryAmountDebit": 1.0, "entryAmountDebitBase": 1.0, "entryAmountCredit": 1.0, "entryAmountCreditBase": 1.0, "entryAmountBase": 1.0, "entryAmount": 1.0, "entryComment": "sample string 3", "documentProductGroup": "sample string 6", "documentValueDate": "2021-06-21T10:56:19.8506404+04:00", "senderDetails": { "name": "sample string 1", "inn": "sample string 2", "accountNumber": "sample string 3", "bankCode": "sample string 4", "bankName": "sample string 5" }, "beneficiaryDetails": { "name": "sample string 1", "inn": "sample string 2", "accountNumber": "sample string 3", "bankCode": "sample string 4", "bankName": "sample string 5" }, "documentTreasuryCode": "sample string 7", "documentNomination": "sample string 8", "documentInformation": "sample string 9", "documentSourceAmount": 1.0, "documentSourceCurrency": "sample string 10", "documentDestinationAmount": 1.0, "documentDestinationCurrency": "sample string 11", "documentReceiveDate": "2021-06-21T10:56:19.8506404+04:00", "documentRate": 1.0, "documentKey": 1.0, "entryId": 1.0, "documentPayerName": "sample string 21", "documentPayerInn": "sample string 22", "authDate": "2021-06-21T10:56:19.8506404+04:00", "docComment": "sample string 23" }, { "entryDate": "2021-06-21T10:56:19.8506404+04:00", "entryDocumentNumber": "sample string 1", "entryAccountNumber": "sample string 2", "entryAmountDebit": 1.0, "entryAmountDebitBase": 1.0, "entryAmountCredit": 1.0, "entryAmountCreditBase": 1.0, "entryAmountBase": 1.0, "entryAmount": 1.0, "entryComment": "sample string 3", "documentProductGroup": "sample string 6", "documentValueDate": "2021-06-21T10:56:19.8506404+04:00", "senderDetails": { "name": "sample string 1", "inn": "sample string 2", "accountNumber": "sample string 3", "bankCode": "sample string 4", "bankName": "sample string 5" }, "beneficiaryDetails": { "name": "sample string 1", "inn": "sample string 2", "accountNumber": "sample string 3", "bankCode": "sample string 4", "bankName": "sample string 5" }, "documentTreasuryCode": "sample string 7", "documentNomination": "sample string 8", "documentInformation": "sample string 9", "documentSourceAmount": 1.0, "documentSourceCurrency": "sample string 10", "documentDestinationAmount": 1.0, "documentDestinationCurrency": "sample string 11", "documentReceiveDate": "2021-06-21T10:56:19.8506404+04:00", "documentRate": 1.0, "documentKey": 1.0, "entryId": 1.0, "documentPayerName": "sample string 21", "documentPayerInn": "sample string 22", "authDate": "2021-06-21T10:56:19.8506404+04:00", "docComment": "sample string 23" } ] ``` **XML** ```xml 2021-06-21T10:56:19.8506404+04:00 sample string 3 sample string 4 sample string 5 sample string 2 sample string 1 sample string 23 1 sample string 11 sample string 9 1 sample string 8 sample string 22 sample string 21 sample string 6 1 2021-06-21T10:56:19.8506404+04:00 1 sample string 10 sample string 7 2021-06-21T10:56:19.8506404+04:00 sample string 2 1 1 1 1 1 1 sample string 3 2021-06-21T10:56:19.8506404+04:00 sample string 1 1 sample string 3 sample string 4 sample string 5 sample string 2 sample string 1 2021-06-21T10:56:19.8506404+04:00 sample string 3 sample string 4 sample string 5 sample string 2 sample string 1 sample string 23 1 sample string 11 sample string 9 1 sample string 8 sample string 22 sample string 21 sample string 6 1 2021-06-21T10:56:19.8506404+04:00 1 sample string 10 sample string 7 2021-06-21T10:56:19.8506404+04:00 sample string 2 1 1 1 1 1 1 sample string 3 2021-06-21T10:56:19.8506404+04:00 sample string 1 1 sample string 3 sample string 4 sample string 5 sample string 2 sample string 1 ``` --- # ამონაწერის გენერაცია Source: https://api.bog.ge/docs/bonline/statement/statement :::caution აღნიშნული მეთოდის მხარდაჭერა აღარ ხორციელდება. ახალი ვერსიის სანახავად, იხილეთ [ანგარიშზე ამონაწერი პერიოდის მიხედვით](https://api.bog.ge/docs/docs/bonline/statement/statementV2.md) ::: # ამონაწერის გენერაცია მეთოდის საშუალებით შესაძლებელია კონკრეტული ანგარიშისთვის, სასურველ პერიოდში, ამონაწერის გენერირება და არაუმეტეს პირველი 1000 ჩანაწერის დაბრუნება. ## Query პარამეტრები - `accountNumber` — string, required ანგარიშის ნომერი - `currency` — string, required ანგარიშის ვალუტა - `startDate` — date, required დაწყების თარიღი - `endDate` — date, required დასრულების თარიღი **REQUEST** ```api GET api/statement/{accountNumber}/{currency}/{startDate}/{endDate} ``` ## დაბრუნებული პარამეტრები - `Id` — integer უნიკალური იდენტიფიკატორი - `Count` — integer ჩანაწერების რაოდენობა - `Records` — object ჩანაწერები, ტრანზაქციის დეტალები - `EntryDate` — date გატარების თარიღი - `EntryDocumentNumber` — string გატარების ნომერი - `EntryAccountNumber` — string გატარების ანგარიშის ნომერი - `EntryAmountDebit` — decimal number გატარების თანხა (დებიტი) - `EntryAmountDebitBase` — decimal number დებეტი ექვივალენტი ლარში - `EntryAmountCredit` — decimal number გატარების თანხა (კრედიტი) - `EntryAmountCreditBase` — decimal number კრედიტი ექვივალენტი ლარში - `EntryAmountBase` — decimal number თანხა ექვივალენტი ლარში - `EntryAmount` — decimal number შემოსვლის თანხა - `EntryComment` — string გატარების კომენტარი, ოპერაციის შინაარსი - `EntryDepartment` — string - `EntryAccountPoint` — string - `DocumentProductGroup` — string ოპერაციის ტიპი, დოკუმენტის პროდუქტის ჯგუფი - `DocumentValueDate` — date დოკუმენტის საბუთის ბანკში გატარების თარიღი - `SenderDetails` — object გამომგზავნის/გამგზავნის ინფორმაცია - `Name` — string დასახელება - `Inn` — string საიდენტიფიკაციო კოდი - `AccountNumber` — string ანგარიშის ნომერი - `BankCode` — string ბანკის კოდი - `BankName` — string ბანკის დასახელება - `BeneficiaryDetails` — object მიმღების ინფორმაცია - `Name` — string დასახელება - `Inn` — string საიდენტიფიკაციო კოდი - `AccountNumber` — string ანგარიშის ნომერი - `BankCode` — string ბანკის კოდი - `BankName` — string ბანკის დასახელება - `DocumentTreasuryCode` — string სახაზინო კოდი - `DocumentNomination` — string გადარიცხვის საფუძველი, დანიშნულება / მაქსიმუმ 250 სიმბოლო - `DocumentInformation` — string დამატებითი ინფორმაცია - `DocumentSourceAmount` — decimal number საწყისი თანხა - `DocumentSourceCurrency` — string საწყისი ვალუტა - `DocumentDestinationAmount` — decimal number საბოლოო თანხა - `DocumentDestinationCurrency` — string საბოლოო ვალუტა - `DocumentReceiveDate` — date მიღების თარიღი - `DocumentBranch` — string - `DocumentDepartment` — string - `DocumentActualDate` — date - `DocumentExpiryDate` — date - `DocumentRateLimit` — decimal number - `DocumentRate` — decimal number კონვერტაციის კურსი - `DocumentRegistrationRate` — decimal number დოკუმენტის რეგისტრაციის კურსი. - `DocumentSenderInstitution` — string - `DocumentIntermediaryInstitution` — string - `DocumentBeneficiaryInstitution` — string - `DocumentPayee` — string გადამხდელი - `DocumentCorrespondentAccountNumber` — string საკორესპონდენტო ანგარიში - `DocumentCorrespondentBankCode` — string საკორესპონდენტო ბანკის კოდი - `DocumentCorrespondentBankName` — string საკორესპონდენტო ბანკის სახელი - `DocumentKey` — decimal number დოკუმენტის უნიკალური ნომერი (ბანკში) - `EntryId` — decimal number გატარების უნიკალური ნომერი - `DocumentPayerName` — string გადამხდელის სახელი - `DocumentPayerInn` — string გადამხდელის – ფიზიკური პირის პირადი ნომერი, იურიდიული პირის საიდენტიფიკაციო კოდი ივსება მხოლოდ! ბიუჯეტის სასარგებლოდ მესამე პირის ნაცვლად/მაგივრად გადარიცხვის შესრულებისას, მიუთითეთ მესამე პირის საიდენტიფიკაციო კოდი - `DocComment` — string კომენტარი **JSON** ```json { "Id": 1, "Count": 2, "Records": [ { "EntryDate": "2021-06-18T16:26:53.4094325+04:00", "EntryDocumentNumber": "sample string 1", "EntryAccountNumber": "sample string 2", "EntryAmountDebit": 1.0, "EntryAmountDebitBase": 1.0, "EntryAmountCredit": 1.0, "EntryAmountCreditBase": 1.0, "EntryAmountBase": 1.0, "EntryAmount": 1.0, "EntryComment": "sample string 3", "EntryDepartment": "sample string 4", "EntryAccountPoint": "sample string 5", "DocumentProductGroup": "sample string 6", "DocumentValueDate": "2021-06-18T16:26:53.4094325+04:00", "SenderDetails": { "Name": "sample string 1", "Inn": "sample string 2", "AccountNumber": "sample string 3", "BankCode": "sample string 4", "BankName": "sample string 5" }, "BeneficiaryDetails": { "Name": "sample string 1", "Inn": "sample string 2", "AccountNumber": "sample string 3", "BankCode": "sample string 4", "BankName": "sample string 5" }, "DocumentTreasuryCode": "sample string 7", "DocumentNomination": "sample string 8", "DocumentInformation": "sample string 9", "DocumentSourceAmount": 1.0, "DocumentSourceCurrency": "sample string 10", "DocumentDestinationAmount": 1.0, "DocumentDestinationCurrency": "sample string 11", "DocumentReceiveDate": "2021-06-18T16:26:53.4094325+04:00", "DocumentBranch": "sample string 12", "DocumentDepartment": "sample string 13", "DocumentActualDate": "2021-06-18T16:26:53.4094325+04:00", "DocumentExpiryDate": "2021-06-18T16:26:53.4094325+04:00", "DocumentRateLimit": 1.0, "DocumentRate": 1.0, "DocumentRegistrationRate": 1.0, "DocumentSenderInstitution": "sample string 14", "DocumentIntermediaryInstitution": "sample string 15", "DocumentBeneficiaryInstitution": "sample string 16", "DocumentPayee": "sample string 17", "DocumentCorrespondentAccountNumber": "sample string 18", "DocumentCorrespondentBankCode": "sample string 19", "DocumentCorrespondentBankName": "sample string 20", "DocumentKey": 1.0, "EntryId": 1.0, "DocumentPayerName": "sample string 21", "DocumentPayerInn": "sample string 22", "DocComment": "sample string 23" }, { "EntryDate": "2021-06-18T16:26:53.4094325+04:00", "EntryDocumentNumber": "sample string 1", "EntryAccountNumber": "sample string 2", "EntryAmountDebit": 1.0, "EntryAmountDebitBase": 1.0, "EntryAmountCredit": 1.0, "EntryAmountCreditBase": 1.0, "EntryAmountBase": 1.0, "EntryAmount": 1.0, "EntryComment": "sample string 3", "EntryDepartment": "sample string 4", "EntryAccountPoint": "sample string 5", "DocumentProductGroup": "sample string 6", "DocumentValueDate": "2021-06-18T16:26:53.4094325+04:00", "SenderDetails": { "Name": "sample string 1", "Inn": "sample string 2", "AccountNumber": "sample string 3", "BankCode": "sample string 4", "BankName": "sample string 5" }, "BeneficiaryDetails": { "Name": "sample string 1", "Inn": "sample string 2", "AccountNumber": "sample string 3", "BankCode": "sample string 4", "BankName": "sample string 5" }, "DocumentTreasuryCode": "sample string 7", "DocumentNomination": "sample string 8", "DocumentInformation": "sample string 9", "DocumentSourceAmount": 1.0, "DocumentSourceCurrency": "sample string 10", "DocumentDestinationAmount": 1.0, "DocumentDestinationCurrency": "sample string 11", "DocumentReceiveDate": "2021-06-18T16:26:53.4094325+04:00", "DocumentBranch": "sample string 12", "DocumentDepartment": "sample string 13", "DocumentActualDate": "2021-06-18T16:26:53.4094325+04:00", "DocumentExpiryDate": "2021-06-18T16:26:53.4094325+04:00", "DocumentRateLimit": 1.0, "DocumentRate": 1.0, "DocumentRegistrationRate": 1.0, "DocumentSenderInstitution": "sample string 14", "DocumentIntermediaryInstitution": "sample string 15", "DocumentBeneficiaryInstitution": "sample string 16", "DocumentPayee": "sample string 17", "DocumentCorrespondentAccountNumber": "sample string 18", "DocumentCorrespondentBankCode": "sample string 19", "DocumentCorrespondentBankName": "sample string 20", "DocumentKey": 1.0, "EntryId": 1.0, "DocumentPayerName": "sample string 21", "DocumentPayerInn": "sample string 22", "DocComment": "sample string 23" } ] } ``` **XML** ```xml 2 1 sample string 3 sample string 4 sample string 5 sample string 2 sample string 1 sample string 23 2021-06-18T16:26:53.4094325+04:00 sample string 16 sample string 12 sample string 18 sample string 19 sample string 20 sample string 13 1 sample string 11 2021-06-18T16:26:53.4094325+04:00 sample string 9 sample string 15 1 sample string 8 sample string 17 sample string 22 sample string 21 sample string 6 1 1 2021-06-18T16:26:53.4094325+04:00 1 sample string 14 1 sample string 10 sample string 7 2021-06-18T16:26:53.4094325+04:00 sample string 2 sample string 5 1 1 1 1 1 1 sample string 3 2021-06-18T16:26:53.4094325+04:00 sample string 4 sample string 1 1 sample string 3 sample string 4 sample string 5 sample string 2 sample string 1 sample string 3 sample string 4 sample string 5 sample string 2 sample string 1 sample string 23 2021-06-18T16:26:53.4094325+04:00 sample string 16 sample string 12 sample string 18 sample string 19 sample string 20 sample string 13 1 sample string 11 2021-06-18T16:26:53.4094325+04:00 sample string 9 sample string 15 1 sample string 8 sample string 17 sample string 22 sample string 21 sample string 6 1 1 2021-06-18T16:26:53.4094325+04:00 1 sample string 14 1 sample string 10 sample string 7 2021-06-18T16:26:53.4094325+04:00 sample string 2 sample string 5 1 1 1 1 1 1 sample string 3 2021-06-18T16:26:53.4094325+04:00 sample string 4 sample string 1 1 sample string 3 sample string 4 sample string 5 sample string 2 sample string 1 ``` --- # ანგარიშზე ამონაწერი პერიოდის მიხედვით Source: https://api.bog.ge/docs/bonline/statement/statementV2 # ანგარიშზე ამონაწერი პერიოდის მიხედვით სერვისი უზრუნველყოფს მითითებული ანგარიშის საბანკო ამონაწერის მიღებას არჩეულ თარიღის შუალედში. ერთ მოთხოვნაზე შესაძლებელია მაქსიმუმ 1000 ტრანზაქციის მიღება. თუ არჩეულ პერიოდში ტრანზაქციების რაოდენობა აღემატება აღნიშნულ ზღვარს, დამატებითი მონაცემების მისაღებად საჭიროა მომდევნო [მოთხოვნის](https://api.bog.ge/docs/docs/bonline/statement/pagingV2) გაგზავნა შესაბამისი გვერდის პარამეტრით (pagination-ის გამოყენებით). ## Query პარამეტრები - `accountNumber` — string, required ანგარიშის ნომერი - `currency` — string, required ანგარიშის ვალუტა - `startDate` — date, required დაწყების თარიღი, ფორმატი: 2025-12-31 - `endDate` — date, required დასრულების თარიღი, ფორმატი: 2025-12-31 **REQUEST** ```api GET api/v2/statement/{accountNumber}/{currency}/{startDate}/{endDate} ``` ## დაბრუნებული პარამეტრები - `Id` — integer უნიკალური იდენტიფიკატორი - `Count` — integer ჩანაწერების რაოდენობა - `TotalCount` — integer მოთხოვნილ პერიოდში არსებული ჩანაწერების საერთო რაოდენობა, გვერდების დაყოფის მიუხედავად. - `Records` — object ჩანაწერები, ტრანზაქციის დეტალები - `EntryDate` — date გატარების თარიღი - `EntryDocumentNumber` — string გატარების ნომერი - `EntryAccountNumber` — string გატარების ანგარიშის ნომერი - `EntryAmountDebit` — decimal number გატარების თანხა (დებიტი) - `EntryAmountDebitBase` — decimal number დებეტი ექვივალენტი ლარში - `EntryAmountCredit` — decimal number გატარების თანხა (კრედიტი) - `EntryAmountCreditBase` — decimal number კრედიტი ექვივალენტი ლარში - `EntryAmountBase` — decimal number თანხა ექვივალენტი ლარში - `EntryAmount` — decimal number შემოსვლის თანხა - `EntryComment` — string გატარების კომენტარი, ოპერაციის შინაარსი - `DocumentProductGroup` — string ოპერაციის ტიპი, დოკუმენტის პროდუქტის ჯგუფი - `DocumentValueDate` — date დოკუმენტის საბუთის ბანკში გატარების თარიღი - `SenderDetails` — object გამომგზავნის/გამგზავნის ინფორმაცია - `Name` — string დასახელება - `Inn` — string საიდენტიფიკაციო კოდი - `AccountNumber` — string ანგარიშის ნომერი - `BankCode` — string ბანკის კოდი - `BankName` — string ბანკის დასახელება - `BeneficiaryDetails` — object მიმღების ინფორმაცია - `Name` — string დასახელება - `Inn` — string საიდენტიფიკაციო კოდი - `AccountNumber` — string ანგარიშის ნომერი - `BankCode` — string ბანკის კოდი - `BankName` — string ბანკის დასახელება - `DocumentTreasuryCode` — string სახაზინო კოდი - `DocumentNomination` — string გადარიცხვის საფუძველი, დანიშნულება / მაქსიმუმ 250 სიმბოლო - `DocumentInformation` — string დამატებითი ინფორმაცია - `DocumentSourceAmount` — decimal number საწყისი თანხა - `DocumentSourceCurrency` — string საწყისი ვალუტა - `DocumentDestinationAmount` — decimal number საბოლოო თანხა - `DocumentDestinationCurrency` — string საბოლოო ვალუტა - `DocumentReceiveDate` — date მიღების თარიღი - `DocumentRate` — decimal number კონვერტაციის კურსი (ეროვნული ბანკის მიერ დადგენილი კურსი) - `DocumentKey` — decimal number დოკუმენტის უნიკალური ნომერი (ბანკში) - `EntryId` — decimal number გატარების უნიკალური ნომერი - `DocumentPayerName` — string გადამხდელის სახელი - `DocumentPayerInn` — string გადამხდელის – ფიზიკური პირის პირადი ნომერი, იურიდიული პირის საიდენტიფიკაციო კოდი ივსება მხოლოდ! ბიუჯეტის სასარგებლოდ მესამე პირის ნაცვლად/მაგივრად გადარიცხვის შესრულებისას, მიუთითეთ მესამე პირის საიდენტიფიკაციო კოდი - `DocComment` — string გატარების კომენტარი, ოპერაციის შინაარსი. შედგება გატარების რამდენიმე ატრიბუტის მნიშვნელობის გაერთიანებით. (მაგალითად: "ავტომატური გადახდების მომსახურებით გადასახდელის გადახდა, 22/12/2021 , სს ""სადაზღვევო კომპანია"", : სახელი გვარი GE75BG00000000000000000GEL სს ""საქართველოს ბანკი"" BAGAGE22") - `AuthDate` — date ოპერაციის ავტორიზაციის თარიღი. **JSON** ```json { "id": 1, "count": 2, "totalCount": 2, "records": [ { "entryDate": "2021-06-18T16:26:53.4094325+04:00", "entryDocumentNumber": "sample string 1", "entryAccountNumber": "sample string 2", "entryAmountDebit": 1.0, "entryAmountDebitBase": 1.0, "entryAmountCredit": 1.0, "entryAmountCreditBase": 1.0, "entryAmountBase": 1.0, "entryAmount": 1.0, "entryComment": "sample string 3", "documentProductGroup": "sample string 6", "documentValueDate": "2021-06-18T16:26:53.4094325+04:00", "senderDetails": { "name": "sample string 1", "inn": "sample string 2", "accountNumber": "sample string 3", "bankCode": "sample string 4", "bankName": "sample string 5" }, "beneficiaryDetails": { "name": "sample string 1", "inn": "sample string 2", "accountNumber": "sample string 3", "bankCode": "sample string 4", "bankName": "sample string 5" }, "documentTreasuryCode": "sample string 7", "documentNomination": "sample string 8", "documentInformation": "sample string 9", "documentSourceAmount": 1.0, "documentSourceCurrency": "sample string 10", "documentDestinationAmount": 1.0, "documentDestinationCurrency": "sample string 11", "documentReceiveDate": "2021-06-18T16:26:53.4094325+04:00", "documentRate": 1.0, "documentKey": 1.0, "entryId": 1.0, "documentPayerName": "sample string 21", "documentPayerInn": "sample string 22", "authDate": "2021-06-21T10:56:19.8506404+04:00", "docComment": "sample string 23" }, { "entryDate": "2021-06-18T16:26:53.4094325+04:00", "entryDocumentNumber": "sample string 1", "entryAccountNumber": "sample string 2", "entryAmountDebit": 1.0, "entryAmountDebitBase": 1.0, "entryAmountCredit": 1.0, "entryAmountCreditBase": 1.0, "entryAmountBase": 1.0, "entryAmount": 1.0, "entryComment": "sample string 3", "documentProductGroup": "sample string 6", "documentValueDate": "2021-06-18T16:26:53.4094325+04:00", "senderDetails": { "name": "sample string 1", "inn": "sample string 2", "accountNumber": "sample string 3", "bankCode": "sample string 4", "bankName": "sample string 5" }, "beneficiaryDetails": { "name": "sample string 1", "inn": "sample string 2", "accountNumber": "sample string 3", "bankCode": "sample string 4", "bankName": "sample string 5" }, "documentTreasuryCode": "sample string 7", "documentNomination": "sample string 8", "documentInformation": "sample string 9", "documentSourceAmount": 1.0, "documentSourceCurrency": "sample string 10", "documentDestinationAmount": 1.0, "documentDestinationCurrency": "sample string 11", "documentReceiveDate": "2021-06-18T16:26:53.4094325+04:00", "documentRate": 1.0, "documentKey": 1.0, "entryId": 1.0, "documentPayerName": "sample string 21", "documentPayerInn": "sample string 22", "authDate": "2021-06-21T10:56:19.8506404+04:00", "docComment": "sample string 23" } ] } ``` **XML** ```xml 2 2 1 2021-06-21T10:56:19.8506404+04:00 sample string 3 sample string 4 sample string 5 sample string 2 sample string 1 sample string 23 1 sample string 11 sample string 9 1 sample string 8 sample string 22 sample string 21 sample string 6 1 2021-06-18T16:26:53.4094325+04:00 1 sample string 10 sample string 7 2021-06-18T16:26:53.4094325+04:00 sample string 2 1 1 1 1 1 1 sample string 3 2021-06-18T16:26:53.4094325+04:00 sample string 1 1 sample string 3 sample string 4 sample string 5 sample string 2 sample string 1 2021-06-21T10:56:19.8506404+04:00 sample string 3 sample string 4 sample string 5 sample string 2 sample string 1 sample string 23 1 sample string 11 sample string 9 1 sample string 8 sample string 22 sample string 21 sample string 6 1 2021-06-18T16:26:53.4094325+04:00 1 sample string 10 sample string 7 2021-06-18T16:26:53.4094325+04:00 sample string 2 1 1 1 1 1 1 sample string 3 2021-06-18T16:26:53.4094325+04:00 sample string 1 1 sample string 3 sample string 4 sample string 5 sample string 2 sample string 1 ``` --- # ამონაწერი გადაფასებით Source: https://api.bog.ge/docs/bonline/statement/statementV2Revaluation # ამონაწერი გადაფასებით სერვისი უზრუნველყოფს მითითებული ანგარიშის საბანკო ამონაწერის მიღებას არჩეულ თარიღის შუალედში, გადაფასების (Revaluation) ჩანაწერების ჩათვლით. გადაფასების ჩანაწერების მისაღებად საჭიროა პარამეტრის `revaluation=true` მითითება. ერთ მოთხოვნაზე შესაძლებელია მაქსიმუმ 1000 ტრანზაქციის მიღება. თუ არჩეულ პერიოდში ტრანზაქციების რაოდენობა აღემატება აღნიშნულ ზღვარს, დამატებითი მონაცემების მისაღებად საჭიროა მომდევნო [მოთხოვნის](https://api.bog.ge/docs/docs/bonline/statement/pagingV2) გაგზავნა შესაბამისი გვერდის პარამეტრით (pagination-ის გამოყენებით). ## Query პარამეტრები - `accountNumber` — string, required ანგარიშის ნომერი - `currency` — string, required ანგარიშის ვალუტა - `startDate` — date, required დაწყების თარიღი, ფორმატი: 2025-12-31 - `endDate` — date, required დასრულების თარიღი, ფორმატი: 2025-12-31 - `includeToday` — boolean დღევანდელი ოპერაციების ჩათვლა (path, არასავალდებულო) - `orderByDate` — boolean თარიღით დალაგება (path, არასავალდებულო) - `take` — integer ჩანაწერების ლიმიტი (query, არასავალდებულო) - `revaluation` — boolean გადაფასების ჩანაწერების ჩვენება (query, არასავალდებულო) **REQUEST** ```api GET api/v2/statement/{accountNumber}/{currency}/{startDate}/{endDate}/{includeToday}/{orderByDate}?take={take}&revaluation={revaluation} ``` ## დაბრუნებული პარამეტრები - `Id` — integer უნიკალური იდენტიფიკატორი - `Count` — integer ჩანაწერების რაოდენობა - `TotalCount` — integer მოთხოვნილ პერიოდში არსებული ჩანაწერების საერთო რაოდენობა, გვერდების დაყოფის მიუხედავად. - `Records` — object ჩანაწერები, ტრანზაქციის დეტალები - `EntryDate` — date გატარების თარიღი - `EntryDocumentNumber` — string გატარების ნომერი - `EntryAccountNumber` — string გატარების ანგარიშის ნომერი - `EntryAmountDebit` — decimal number გატარების თანხა (დებიტი) - `EntryAmountDebitBase` — decimal number დებეტი ექვივალენტი ლარში - `EntryAmountCredit` — decimal number გატარების თანხა (კრედიტი) - `EntryAmountCreditBase` — decimal number კრედიტი ექვივალენტი ლარში - `EntryAmountBase` — decimal number თანხა ექვივალენტი ლარში - `EntryAmount` — decimal number შემოსვლის თანხა - `EntryComment` — string გატარების კომენტარი, ოპერაციის შინაარსი - `DocumentProductGroup` — string ოპერაციის ტიპი, დოკუმენტის პროდუქტის ჯგუფი - `DocumentValueDate` — date დოკუმენტის საბუთის ბანკში გატარების თარიღი - `SenderDetails` — object გამომგზავნის/გამგზავნის ინფორმაცია - `Name` — string დასახელება - `Inn` — string საიდენტიფიკაციო კოდი - `AccountNumber` — string ანგარიშის ნომერი - `BankCode` — string ბანკის კოდი - `BankName` — string ბანკის დასახელება - `BeneficiaryDetails` — object მიმღების ინფორმაცია - `Name` — string დასახელება - `Inn` — string საიდენტიფიკაციო კოდი - `AccountNumber` — string ანგარიშის ნომერი - `BankCode` — string ბანკის კოდი - `BankName` — string ბანკის დასახელება - `DocumentTreasuryCode` — string სახაზინო კოდი - `DocumentNomination` — string გადარიცხვის საფუძველი, დანიშნულება / მაქსიმუმ 250 სიმბოლო - `DocumentInformation` — string დამატებითი ინფორმაცია - `DocumentSourceAmount` — decimal number საწყისი თანხა - `DocumentSourceCurrency` — string საწყისი ვალუტა - `DocumentDestinationAmount` — decimal number საბოლოო თანხა - `DocumentDestinationCurrency` — string საბოლოო ვალუტა - `DocumentReceiveDate` — date მიღების თარიღი - `DocumentRate` — decimal number კონვერტაციის კურსი (ეროვნული ბანკის მიერ დადგენილი კურსი) - `DocumentKey` — decimal number დოკუმენტის უნიკალური ნომერი (ბანკში) - `EntryId` — decimal number გატარების უნიკალური ნომერი - `DocumentPayerName` — string გადამხდელის სახელი - `DocumentPayerInn` — string გადამხდელის – ფიზიკური პირის პირადი ნომერი, იურიდიული პირის საიდენტიფიკაციო კოდი ივსება მხოლოდ! ბიუჯეტის სასარგებლოდ მესამე პირის ნაცვლად/მაგივრად გადარიცხვის შესრულებისას, მიუთითეთ მესამე პირის საიდენტიფიკაციო კოდი - `DocComment` — string გატარების კომენტარი, ოპერაციის შინაარსი. შედგება გატარების რამდენიმე ატრიბუტის მნიშვნელობის გაერთიანებით. (მაგალითად: "ავტომატური გადახდების მომსახურებით გადასახდელის გადახდა, 22/12/2021 , სს ""სადაზღვევო კომპანია"", : სახელი გვარი GE75BG00000000000000000GEL სს ""საქართველოს ბანკი"" BAGAGE22") - `AuthDate` — date ოპერაციის ავტორიზაციის თარიღი. **JSON** ```json { "id": 1, "count": 2, "totalCount": 2, "records": [ { "entryDate": "2021-06-18T16:26:53.4094325+04:00", "entryDocumentNumber": "sample string 1", "entryAccountNumber": "sample string 2", "entryAmountDebit": 1.0, "entryAmountDebitBase": 1.0, "entryAmountCredit": 1.0, "entryAmountCreditBase": 1.0, "entryAmountBase": 1.0, "entryAmount": 1.0, "entryComment": "sample string 3", "documentProductGroup": "sample string 6", "documentValueDate": "2021-06-18T16:26:53.4094325+04:00", "senderDetails": { "name": "sample string 1", "inn": "sample string 2", "accountNumber": "sample string 3", "bankCode": "sample string 4", "bankName": "sample string 5" }, "beneficiaryDetails": { "name": "sample string 1", "inn": "sample string 2", "accountNumber": "sample string 3", "bankCode": "sample string 4", "bankName": "sample string 5" }, "documentTreasuryCode": "sample string 7", "documentNomination": "sample string 8", "documentInformation": "sample string 9", "documentSourceAmount": 1.0, "documentSourceCurrency": "sample string 10", "documentDestinationAmount": 1.0, "documentDestinationCurrency": "sample string 11", "documentReceiveDate": "2021-06-18T16:26:53.4094325+04:00", "documentRate": 1.0, "documentKey": 1.0, "entryId": 1.0, "documentPayerName": "sample string 21", "documentPayerInn": "sample string 22", "authDate": "2021-06-21T10:56:19.8506404+04:00", "docComment": "sample string 23" }, { "entryDate": "2021-06-18T16:26:53.4094325+04:00", "entryDocumentNumber": "sample string 1", "entryAccountNumber": "sample string 2", "entryAmountDebit": 1.0, "entryAmountDebitBase": 1.0, "entryAmountCredit": 1.0, "entryAmountCreditBase": 1.0, "entryAmountBase": 1.0, "entryAmount": 1.0, "entryComment": "sample string 3", "documentProductGroup": "sample string 6", "documentValueDate": "2021-06-18T16:26:53.4094325+04:00", "senderDetails": { "name": "sample string 1", "inn": "sample string 2", "accountNumber": "sample string 3", "bankCode": "sample string 4", "bankName": "sample string 5" }, "beneficiaryDetails": { "name": "sample string 1", "inn": "sample string 2", "accountNumber": "sample string 3", "bankCode": "sample string 4", "bankName": "sample string 5" }, "documentTreasuryCode": "sample string 7", "documentNomination": "sample string 8", "documentInformation": "sample string 9", "documentSourceAmount": 1.0, "documentSourceCurrency": "sample string 10", "documentDestinationAmount": 1.0, "documentDestinationCurrency": "sample string 11", "documentReceiveDate": "2021-06-18T16:26:53.4094325+04:00", "documentRate": 1.0, "documentKey": 1.0, "entryId": 1.0, "documentPayerName": "sample string 21", "documentPayerInn": "sample string 22", "authDate": "2021-06-21T10:56:19.8506404+04:00", "docComment": "sample string 23" } ] } ``` **XML** ```xml 2 2 1 2021-06-21T10:56:19.8506404+04:00 sample string 3 sample string 4 sample string 5 sample string 2 sample string 1 sample string 23 1 sample string 11 sample string 9 1 sample string 8 sample string 22 sample string 21 sample string 6 1 2021-06-18T16:26:53.4094325+04:00 1 sample string 10 sample string 7 2021-06-18T16:26:53.4094325+04:00 sample string 2 1 1 1 1 1 1 sample string 3 2021-06-18T16:26:53.4094325+04:00 sample string 1 1 sample string 3 sample string 4 sample string 5 sample string 2 sample string 1 2021-06-21T10:56:19.8506404+04:00 sample string 3 sample string 4 sample string 5 sample string 2 sample string 1 sample string 23 1 sample string 11 sample string 9 1 sample string 8 sample string 22 sample string 21 sample string 6 1 2021-06-18T16:26:53.4094325+04:00 1 sample string 10 sample string 7 2021-06-18T16:26:53.4094325+04:00 sample string 2 1 1 1 1 1 1 sample string 3 2021-06-18T16:26:53.4094325+04:00 sample string 1 1 sample string 3 sample string 4 sample string 5 sample string 2 sample string 1 ``` --- # ამონაწერის გლობალური და ყოველდღიური ნაშთები Source: https://api.bog.ge/docs/bonline/statement/summary # ამონაწერის გლობალური და ყოველდღიური ნაშთები მეთოდის საშუალებით შესაძლებელია კონკრეტულ ანგარიშისთვის დაგენერირებული ამონაწერის ჯამური ინფორმაციის ნახვა, გენერაციის დროს დაბრუნებული იდენტიფიკატორის მიხედვით. მეთოდი აბრუნებს ჯამურ ინფორმაციას სრულად და თითოეული დღის მიხედვით. ## Query პარამეტრები - `accountNumber` — string, required ანგარიშის ნომერი - `currency` — string, required ანგარიშის ვალუტა - `id` — date, required ამონაწერის უნიკალური იდენტიფიკატორი **REQUEST** ```api GET api/statement/summary/{accountNumber}/{currency}/{id} ``` ## დაბრუნებული პარამეტრები - `GlobalSummary` — object ამონაწერის პერიოდის ბალანსი - `AccountNumber` — string ანგარიშის ნომერი - `Currency` — string ვალუტა - `StartDate` — date პირველი ტრანზაქციის თარიღი - `EndDate` — date ბოლო ტრანზაქციის თარიღი - `PeriodStartDate` — date პერიოდის დაწყების თარიღი - `PeriodEndDate` — date პერიოდის დასრულების თარიღი - `InAmount` — decimal number შემომავალი თანხის რაოდენობა - `InAmountBase` — decimal number შემომავალი თანხის რაოდენობა ეროვნულ ვალუტაში - `InRate` — decimal number შემომავალი თანხის კონვერტაციის კურსი - `OutAmount` — decimal number გამავალი თანხის რაოდენობა - `OutAmountBase` — decimal number გამავალი თანხის ექვივალენტი ეროვნულ ვალუტაში - `OutRate` — decimal number გამავალი თანხის კონვერტაციის კურსი - `CreditSum` — decimal number გატარების თანხის ჯამი (კრედიტი) - `DebitSum` — decimal number გატარების თანხის ჯამი (დებიტი) - `DailySummaries` — object ამონაწერის ყოველდღიური ბალანსები ერთი ან რამდენიმე - `Balance` — decimal number ნაშთი - `BalanceBase` — decimal number ნაშტის ექვივალენტი ეროვნულ ვალუტაში - `CreditSum` — decimal number გატარების თანხის ჯამი (კრედიტი) - `DebitSum` — decimal number გატარების თანხის ჯამი (დებიტი) - `Rate` — decimal number კონვერტაციის კურსი - `EntryCount` — integer EntryCount - `Date` — date Date **JSON** ```json { "GlobalSummary": { "AccountNumber": "sample string 1", "Currency": "sample string 2", "StartDate": "2021-06-21T10:43:17.358503+04:00", "EndDate": "2021-06-21T10:43:17.358503+04:00", "PeriodStartDate": "2021-06-21T10:43:17.358503+04:00", "PeriodEndDate": "2021-06-21T10:43:17.358503+04:00", "InAmount": 7.0, "InAmountBase": 8.0, "InRate": 9.0, "OutAmount": 10.0, "OutAmountBase": 11.0, "OutRate": 12.0, "CreditSum": 13.0, "DebitSum": 14.0 }, "DailySummaries": [ { "Balance": 1.0, "BalanceBase": 2.0, "CreditSum": 3.0, "DebitSum": 4.0, "Rate": 5.0, "EntryCount": 6, "Date": "2021-06-21T10:43:17.358503+04:00" }, { "Balance": 1.0, "BalanceBase": 2.0, "CreditSum": 3.0, "DebitSum": 4.0, "Rate": 5.0, "EntryCount": 6, "Date": "2021-06-21T10:43:17.358503+04:00" } ] } ``` **XML** ```xml 1 2 3 2021-06-21T10:43:17.358503+04:00 4 6 5 1 2 3 2021-06-21T10:43:17.358503+04:00 4 6 5 sample string 1 13 sample string 2 14 2021-06-21T10:43:17.358503+04:00 7 8 9 10 11 12 2021-06-21T10:43:17.358503+04:00 2021-06-21T10:43:17.358503+04:00 2021-06-21T10:43:17.358503+04:00 ``` --- # ამონაწერის გლობალური და ყოველდღიური ნაშთები Source: https://api.bog.ge/docs/bonline/statement/summaryV2 # ამონაწერის გლობალური და ყოველდღიური ნაშთები მეთოდის საშუალებით შესაძლებელია კონკრეტულ ანგარიშისთვის ამონაწერის ჯამური ინფორმაციის ნახვა. მეთოდი აბრუნებს ჯამურ ინფორმაციას სრულად და თითოეული დღის მიხედვით. ## Query პარამეტრები - `accountNumber` — string, required ანგარიშის ნომერი - `currency` — string, required ანგარიშის ვალუტა - `startDate` — date, required დაწყების თარიღი, ფორმატი: 2025-12-31 - `endDate` — date, required დასრულების თარიღი, ფორმატი: 2025-12-31 **REQUEST** ```api GET api/v2/statement/summary/{accountNumber}/{currency}/{startDate}/{endDate} ``` ## დაბრუნებული პარამეტრები - `GlobalSummary` — object ამონაწერის პერიოდის ბალანსი - `AccountNumber` — string ანგარიშის ნომერი - `Currency` — string ვალუტა - `StartDate` — date პირველი ტრანზაქციის თარიღი - `EndDate` — date ბოლო ტრანზაქციის თარიღი - `PeriodStartDate` — date პერიოდის დაწყების თარიღი - `PeriodEndDate` — date პერიოდის დასრულების თარიღი - `InAmount` — decimal number შემომავალი თანხის რაოდენობა - `InAmountBase` — decimal number შემომავალი თანხის რაოდენობა ეროვნულ ვალუტაში - `InRate` — decimal number შემომავალი თანხის კონვერტაციის კურსი (ეროვნული ბანკის მიერ დადგენილი კურსი) - `OutAmount` — decimal number გამავალი თანხის რაოდენობა - `OutAmountBase` — decimal number გამავალი თანხის ექვივალენტი ეროვნულ ვალუტაში - `OutRate` — decimal number გამავალი თანხის კონვერტაციის კურსი (ეროვნული ბანკის მიერ დადგენილი კურსი) - `CreditSum` — decimal number გატარების თანხის ჯამი (კრედიტი) - `DebitSum` — decimal number გატარების თანხის ჯამი (დებიტი) - `DailySummaries` — object ამონაწერის ყოველდღიური ბალანსები ერთი ან რამდენიმე - `Balance` — decimal number ნაშთი - `BalanceBase` — decimal number ნაშტის ექვივალენტი ეროვნულ ვალუტაში - `CreditSum` — decimal number გატარების თანხის ჯამი (კრედიტი) - `DebitSum` — decimal number გატარების თანხის ჯამი (დებიტი) - `Rate` — decimal number კონვერტაციის კურსი (ეროვნული ბანკის მიერ დადგენილი კურსი) - `EntryCount` — integer EntryCount - `Date` — date Date **JSON** ```json { "globalSummary": { "accountNumber": "sample string 1", "currency": "sample string 2", "startDate": "2021-06-21T10:43:17.358503+04:00", "endDate": "2021-06-21T10:43:17.358503+04:00", "periodStartDate": "2021-06-21T10:43:17.358503+04:00", "periodEndDate": "2021-06-21T10:43:17.358503+04:00", "inAmount": 7.0, "inAmountBase": 8.0, "inRate": 9.0, "outAmount": 10.0, "outAmountBase": 11.0, "outRate": 12.0, "creditSum": 13.0, "debitSum": 14.0 }, "dailySummaries": [ { "balance": 1.0, "balanceBase": 2.0, "creditSum": 3.0, "debitSum": 4.0, "rate": 5.0, "entryCount": 6, "date": "2021-06-21T10:43:17.358503+04:00" }, { "balance": 1.0, "balanceBase": 2.0, "creditSum": 3.0, "debitSum": 4.0, "rate": 5.0, "entryCount": 6, "date": "2021-06-21T10:43:17.358503+04:00" } ] } ``` **XML** ```xml 1 2 3 2021-06-21T10:43:17.358503+04:00 4 6 5 1 2 3 2021-06-21T10:43:17.358503+04:00 4 6 5 sample string 1 13 sample string 2 14 2021-06-21T10:43:17.358503+04:00 7 8 9 10 11 12 2021-06-21T10:43:17.358503+04:00 2021-06-21T10:43:17.358503+04:00 2021-06-21T10:43:17.358503+04:00 ``` --- # მიმდინარე დღის ამონაწერი Source: https://api.bog.ge/docs/bonline/statement/todayactivities # მიმდინარე დღის აქტივობები მეთოდის საშუალებით შესაძლებელია მიმდინარე დღის ყველა აქტივობის ნახვა. :::note ეს მეთოდი შეზღუდულია მოთხოვნების ლიმიტით — დაშვებულია დღეში 800 მოთხოვნა (ანგარიშისა და ვალუტის მიხედვით). ლიმიტის გადაჭარბებისას დაბრუნდება `429 Too Many Requests`, `Retry-After` ჰედერით (წამებში). ::: ## Query პარამეტრები - `accountNumber` — string, required ანგარიშის ნომერი - `currency` — string, required ვალუტა **REQUEST** ```api GET api/v2/documents/todayactivities/{accountNumber}/{currency} ``` ## დაბრუნებული პარამეტრები# - `Id` — integer უნიკალური იდენტიფიკატორი - `DocKey` — integer დოკუმენტის უნიკალური იდენტიფიკატორი business online-ში - `DocNo` — string დოკუმენტის ნომერი - `PostDate` — date დოკუმენტის შექმნის თარიღი - `ValueDate` — date ვალუტირების თარიღი - `EntryType` — string გატარების ტიპი. იღებს შემდეგ მნიშვნელობებს: - PMC - სალარო ოპერაცია - PLC - საბარათე ოპერაცია - CDS - ანაბრის ოპერაცია - LND - სესხის ოპერაცია - PBS - ფეიბოქსის ოპერაცია - INC - ინკასო - PMD - ეროვნული ვალუტის გადარიცხვა - PMI - უცხოური ვალუტის გადარიცხვა - COM - საკომისიო - `EntryComment` — string გატარების კომენტარი, ოპერაციის შინაარსი - `EntryCommentEn` — string გატარების კომენტარი, ოპერაციის შინაარსი თარგმანი ინგლისურ ენაზე. - `Nomination` — string დოკუმენტის დანიშნულება - `Credit` — decimal number კრედიტი - `Debit` — decimal number დებიტი - `Amount` — decimal number თანხა - `AmountBase` — decimal number თანხა ექვივალენტი ლარში - `PayerName` — string გადამხდელის დასახელება - `PayerInn` — string გადამხდელის საიდენტიფიკაციო კოდი - `Sender` — object გამომგზავნის/გამგზავნის ინფორმაცია - `Name` — string დასახელება - `Inn` — string საიდენტიფიკაციო კოდი - `AccountNumber` — string ანგარიშის ნომერი - `BankCode` — string ბანკის კოდი - `BankName` — string ბანკის დასახელება - `Beneficiary` — object მიმღების ინფორმაცია - `Inn` — string საიდენტიფიკაციო კოდი - `AccountNumber` — string ანგარიშის ნომერი - `BankCode` — string ბანკის კოდი - `BankName` — string ბანკის დასახელება **JSON** ```json [ { "id": 1, "docKey": 2, "docNo": "sample string 3", "postDate": "2021-06-18T14:01:32.6806428+04:00", "valueDate": "2021-06-18T14:01:32.6806428+04:00", "entryType": "sample string 6", "entryComment": "sample string 7", "entryCommentEn": "sample string 8", "nomination": "sample string 9", "credit": 10.0, "debit": 11.0, "amount": 12.0, "amountBase": 13.0, "payerName": "sample string 14", "payerInn": "sample string 15", "sender": { "name": "sample string 1", "inn": "sample string 2", "accountNumber": "sample string 3", "bankCode": "sample string 4", "bankName": "sample string 5" }, "beneficiary": { "name": "sample string 1", "inn": "sample string 2", "accountNumber": "sample string 3", "bankCode": "sample string 4", "bankName": "sample string 5" } }, { "id": 1, "docKey": 2, "docNo": "sample string 3", "postDate": "2021-06-18T14:01:32.6806428+04:00", "valueDate": "2021-06-18T14:01:32.6806428+04:00", "entryType": "sample string 6", "entryComment": "sample string 7", "entryCommentEn": "sample string 8", "nomination": "sample string 9", "credit": 10.0, "debit": 11.0, "amount": 12.0, "amountBase": 13.0, "payerName": "sample string 14", "payerInn": "sample string 15", "sender": { "name": "sample string 1", "inn": "sample string 2", "accountNumber": "sample string 3", "bankCode": "sample string 4", "bankName": "sample string 5" }, "beneficiary": { "name": "sample string 1", "inn": "sample string 2", "accountNumber": "sample string 3", "bankCode": "sample string 4", "bankName": "sample string 5" } } ] ``` **XML** ```xml 12 13 sample string 3 sample string 4 sample string 5 sample string 2 sample string 1 10 11 2 sample string 3 sample string 7 sample string 8 sample string 6 1 sample string 9 2021-06-18T14:01:32.6806428+04:00 sample string 3 sample string 4 sample string 5 sample string 2 sample string 1 2021-06-18T14:01:32.6806428+04:00 12 13 sample string 3 sample string 4 sample string 5 sample string 2 sample string 1 10 11 2 sample string 3 sample string 7 sample string 8 sample string 6 1 sample string 9 2021-06-18T14:01:32.6806428+04:00 sample string 3 sample string 4 sample string 5 sample string 2 sample string 1 2021-06-18T14:01:32.6806428+04:00 ``` --- # process Source: https://api.bog.ge/docs/obidentity/process # Identity Assurance სერვისთან ინტეგრაციის ტექნიკური დოკუმენტაცია ## შესავალი ეს დოკუმენტაცია აღწერს, თუ როგორ უნდა მოხდეს თქვენი აპლიკაციის ინტეგრაცია ღია ფინანსების Identity Assurance სერვისთან. სერვისი საშუალებას აძლევს ერთ ფინანსურ ინსტიტუტს (შემდგომში „დაყრდნობილი მხარე“) მიიღოს მომხმარებლის ვინაობის შესახებ დადასტურებული ინფორმაცია სხვა ფინანსური ინსტიტუტისგან (შემდგომში „იდენტობის პროვაიდერი“). პროცესი ეფუძნება **OpenID Connect for Identity Assurance 1.0** სტანდარტს და სრულად თავსებადია **Financial-grade API (FAPI)** უსაფრთხოების პროფილთან. --- ## ძირითადი კონცეფციები **დაყრდნობილი მხარე (Relying Party):** თქვენი აპლიკაცია ან სერვისი, რომელსაც სურს მომხმარებლის ვინაობის გადამოწმება. **იდენტობის პროვაიდერი (Identity Provider):** ორგანიზაცია (მაგ. ბანკი), რომელიც ადასტურებს მომხმარებლის ვინაობას და აწვდის ამის შესახებ ინფორმაციას. **შემოწმებული მტკიცებები (Verified Claims):** მომხმარებლის შესახებ ინფორმაცია (სახელი, გვარი, პირადი ნომერი და ა.შ.), რომლის სისწორეც დადასტურებულია იდენტობის პროვაიდერის მიერ. **მტკიცებულება (Evidence):** ინფორმაცია იმის შესახებ, თუ რა დოკუმენტს ან მეთოდს დაეყრდნო იდენტობის პროვაიდერი მომხმარებლის ვინაობის გადამოწმებისას (მაგ., პირადობის მოწმობა, პასპორტი). **ნდობის ჩარჩო (Trust Framework):** წესების ერთობლიობა, რომლის მიხედვითაც მოხდა ვინაობის გადამოწმება. საქართველოსთვის სავალდებულოა `ge_aml` ჩარჩოს გამოყენება, რაც გულისხმობს უკანონო შემოსავლების ლეგალიზაციის წინააღმდეგ მიმართული კანონმდებლობის დაცვას. --- ## ინტეგრაციის პროცესი: ინტეგრაციის პროცესი სტანდარტული OpenID Connect (OIDC) პროცესის შესაბამისია, თუმცა მოიცავს სპეციფიკურ პარამეტრებს შემოწმებული მტკიცებების გამოსათხოვად. ### ეტაპი 1: წინაპირობები 1. **სამართლებრივი შეთანხმება:** დაყრდნობილი მხარე უნდა იყოს „მესამე პირის/შუამავლის საშუალებით მომხმარებლის იდენტიფიკაციისა და ვერიფიკაციისას მონაცემთა გაცვლის“ შეთანხმების მონაწილე. 2. **კლიენტის რეგისტრაცია:** დაყრდნობილმა მხარემ უნდა მიიღოს უნიკალური `client_id` და ავთენტიფიკაციისთვის საჭირო მონაცემები იდენტობის პროვაიდერისგან. 3. **Identity Assurance სერვისების გამოყენება**: კლიენტის (დაყრდნობილი მხარის) ავთენტიფიკაცია ხორციელდება დაცული საკომუნიკაციო არხით, რომელიც მოითხოვს ორივე მხარის მიერ X.509 ფორმატის სერტიფიკატების წარდგენას (mTLS), ღია ბანკინგისთვის განსაზღვრული სტანდარტების შესაბამისად. ### ეტაპი 2: ავთენტიფიკაციის მოთხოვნის ფორმირება დაყრდნობილმა მხარემ მომხმარებელი უნდა გადაამისამართოს იდენტობის პროვაიდერის `authorization_endpoint`-ზე შემდეგი პარამეტრებით: - `response_type=code` - `client_id` - `scope=openid` (და სხვა საჭირო scope-ები, მაგ. `https://openfinance.ge/ns/scope/kyc`) - `redirect_uri` - `state` - `code_challenge` (თუ გამოიყენება PKCE) - `code_challenge_method` (თუ გამოიყენება PKCE) - `nonce` - **`claims` (ყველაზე მნიშვნელოვანი პარამეტრი):** JSON ობიექტი, რომელიც აღწერს, თუ რა შემოწმებული ინფორმაცია გჭირდებათ. `claims` პარამეტრი უნდა იყოს შესაბამისობაში OpenID Connect for Identity Assurance 1.0 და საქართველოს ღია ბანკინგის ასოციაციის მიერ შემუშავებულ სტანდარტთან User Identification and Authentication Service Standard 0.3.RC3: 1. https://openid.net/specs/openid-connect-4-identity-assurance-1_0.html 2. https://openfinance.ge/en/standards #### `claims` პარამეტრის მაგალითი: ```json { "userinfo": { "verified_claims": { "verification": { "trust_framework": { "value": "ge_aml", "essential": true } }, "claims": { "given_name": null, "family_name": null, "personal_number": null, "birthdate": null } } } } ``` ### ეტაპი 3: ტოკენის მოთხოვნა მომხმარებლის წარმატებული ავთენტიფიკაციის შემდეგ, იდენტობის პროვაიდერი დააბრუნებს `authorization_code`, რომელიც უნდა გამოიყენოთ `token_endpoint`-ზე ტოკენის მისაღებად. შეგიძლიათ იხელმძღვანელოთ OIDC პროტოკოლის სტანდარტით. `token_endpoint` ბოლოწერტილზე მოთხოვნისთვის საჭიროა შემდეგი პარამეტრები: - `code` - `client_id` - `grant_type=authorization_code` - `redirect_uri` - `code_verifier` (თუ გამოიყენება PKCE) ### ეტაპი 4: მომხმარებლის ინფორმაციის მიღება მომხმარებლის ინფორმაციის მისაღებად, გამოიყენეთ `userinfo_endpoint`. სერვისი დააბრუნებს მომხმარებლის შესახებ `claims` პარამეტრით მოთხოვნილ ინფორმაციას, მათ შორის შემოწმებულ მტკიცებებს. `userinfo` ბოლოწერტილზე მოთხოვნისთვის საჭიროა ჰედერში `Authorization` გადაეცეს Bearer {`access_token`}, რომელიც მიიღეთ `token_endpoint`-დან. --- # technical-information Source: https://api.bog.ge/docs/obidentity/technical-information # მისამართები ### სატესტო გარემოს OpenID პროვაიდერის კონფიგურაცია: https://account-ob-test.bog.ge/auth/realms/bog-test/.well-known/ob-openid-configuration ### პროდაქშენ გარემოს OpenID პროვაიდერის კონფიგურაცია: https://ob-identity.bog.ge/auth/realms/bog/.well-known/ob-openid-configuration --- # შესავალი Source: https://api.bog.ge/docs/sandbox/payments/introduction ## აგრეგატორის ინტეგრაციის პროტოკოლი ელ. კომერციის მომსახურებისთვის - Sandbox სატესტო გარემო ## რა არის Sandbox სატესტო გარემო? Sandbox გარემო არის იზოლირებული სატესტო სივრცე, რომელიც საშუალებას გაძლევთ უსაფრთხოდ დააინტეგრიროთ და გადაამოწმოთ თქვენი ელექტრონული კომერციის გადახდის პროცესები ონლაინ გადახდების API-ის გამოყენებით, რეალური ტრანზაქციებისა და თანხის მოძრაობის გარეშე. Sandbox-ში შეგიძლიათ შეკვეთის, გადახდის, ქოლბექის და დაბრუნების ოპერაციების სიმულირება სატესტო რეკვიზიტების (Credentials) და სატესტო ბარათების გამოყენებით. Sandbox გეხმარებათ ინტეგრაციის სცენარების გადამოწმებაში, ქოლბექების სწორად დამუშავებაში და შეცდომების აღმოჩენაში Live გარემოში გადასვლამდე. :::tip · გამოიყენეთ მხოლოდ Sandbox რეკვიზიტები · გამოიყენეთ ამ დოკუმენტაციაში მითითებული სატესტო ბარათები · შეამოწმეთ გადახდის სრული პროცესი: შეკვეთის შექმნა, გადახდის ავტორიზაცია, Callback, თანხის დაბრუნება, ბარათის დამახსოვრება, პრეავტორიზაციის დადასტურება · გადაამოწმეთ Callback-ების დამუშავება და idempotency ლოგიკა ::: :::danger caution · არ გამოიყენოთ რეალური ბარათის მონაცემები და რეალური რეკვიზიტები (Credentials) · არ გამოიყენოთ Sandbox მონაცემები აღრიცხვისთვის ან რეპორტინგისთვის · არ გამოიყენოთ Sandbox სტრეს-ტესტირებისთვის ან წარმადობის ტესტირებისთვის ::: Sandbox გარემო განკუთვნილია მხოლოდ ფუნქციური და ინტეგრაციის ტესტირებისთვის. Sandbox და Live გარემოები სრულად იზოლირებულია ერთმანეთისგან.Sandbox მონაცემები არასოდეს ჩნდება Live გარემოში, და პირიქით. ყოველთვის გადაამოწმეთ, რომ თითოეული გარემოსთვის სწორ რეკვიზიტებს და მისამართებს იყენებთ. ## რა არის ონლაინ გადახდების API ონლაინ გადახდების API განკუთვნილია ნებისმიერ ელექტრონულ სისტემასთან უსაფრთხო გადახდების მოდულის სწრაფად და მარტივად ინტეგრაციისთვის. მისი საშუალებით მარტივდება გადახდის პროცესი, რაც ბიზნესს საშუალებას აძლევს მიიღოს გადახდები სხვადასხვა გადახდის მეთოდის გამოყენებით, მათ შორის საქართველოს ბანკისა და სხვა კომერციული ბანკების (VISA, MasterCard, American Express) ბარათებით. ## პროტოკოლი და ტექნიკური სპეციფიკაციები - **API არქიტექტურა** - RESTful - **კომუნიკაციის პროტოკოლი** - HTTP/1.1. ყველა API მეთოდის გამოძახება უნდა განხორციელდეს HTTPS-ის გამოყენებით, რათა უზრუნველყოფილი იყოს მონაცემთა უსაფრთხო გადაცემა. - **მონაცემთა ფორმატი** - JSON. ამარტივებს API მეთოდებთან ინტეგრაციას. - **ავთენტიფიკაცია და უსაფრთხოება** - ავთენტიფიკაციისთვის გამოიყენება OAuth 2.0, ხოლო JSON Web Tokens (JWT) უზრუნველყოფს მონაცემთა უსაფრთხო გაცვლას. - **სინქრონული API მოთხოვნები** - ყველა API მოთხოვნა მუშავდება დაუყოვნებლივ და დაბრუნებული response ასახავს API გამოძახების შედეგს. - **ასინქრონული webhook შეტყობინებები** - მიუხედავად იმისა, რომ API მოთხოვნები სინქრონულია, მნიშვნელოვანი მოვლენები, როგორიცაა გადახდის დადასტურება და განახლება, მუშავდება ასინქრონულად Callback-ის მეშვეობით, რაც უზრუნველყოფს საიმედო, real-time კომუნიკაციას. - **შეცდომების მართვა** - სტანდარტული HTTP სტატუს კოდები და დეტალური შეცდომის შეტყობინებები გამოიყენება წარმატებული ან შეცდომით დასრულებული ოპერაციების დასამუშავებლად, რაც დეველოპერებს ეხმარება პრობლემების სწრაფ დიაგნოსტირებაში. ## გადახდის პროცესის მოკლე აღწერა - **მომხმარებელი აინიცირებს გადახდას:** მომხმარებელი ირჩევს სასურველ პროდუქტს ან მომსახურებას (ან პროდუქტების / მომსახურებების კალათას) ბიზნესის ვებგვერდზე და აჭერს გადახდის ღილაკს. - **ბიზნესი აგზავნის შეკვეთის მოთხოვნას:** ბიზნესი აგზავნის [შეკვეთის მოთხოვნას](https://api.bog.ge/docs/payments/standard-process/create-order) ონლაინ გადახდების API-ში გადახდის პროცესის დასაწყებად. - **API აბრუნებს შეკვეთის მოთხოვნის დეტალებს:** გადახდის კარიბჭე აბრუნებს საჭირო პარამეტრებს — როგორიცაა შეკვეთის მოთხოვნის ID და გადამისამართების URL — რომელიც გადახდის პროცესის გაგრძელებას უზრუნველყოფს. - **მომხმარებელი გადამისამართდება ონლაინ გადახდის გვერდზე:** ბიზნესი მომხმარებელს ამისამართებს ონლაინ გადახდის გვერდზე, სადაც მომხმარებელი ირჩევს გადახდის მეთოდს, შეჰყავს ბარათის დეტალები ან ასრულებს გადახდას ინტერნეტ ბანკში ავტორიზაციით. - **გადახდის დამუშავება:** ონლაინ გადახდების სისტემა ამოწმებს გადახდის დეტალებს და უსაფრთხოდ ამუშავებს გადახდას. - **Callback შეტყობინება იგზავნება ბიზნესთან:** როგორც კი გადახდა დამუშავდება, ონლაინ გადახდის სისტემა აგზავნის [Callback](https://api.bog.ge/docs/payments/standard-process/callback)-ს, ბიზნესის მიერ შეკვეთის მოთხოვნაში მითითებულ Callback მისამართზე. :::note Callback-ის მიღება გადამწყვეტი ბიჯია გადახდის პროცესში. იგი ადასტურებს გადახდის სტატუსს (წარმატებული ან წარუმატებელი) და სხვა საჭირო დეტალებს. Callback-ში მიღებულ ინფორმაციაზე დაყრდნობით, ბიზნესმა უნდა უზრუნველყოს თავისი სისტემის განახლება. ::: - **ოპერაციის დასრულება:** Callback-ის მიღების შემდეგ, ბიზნესი ამთავრებს პროცესს, ადასტურებს შეკვეთას მომხმარებელთან და ასრულებს ყველა დაკავშირებულ საოპერაციო ნაბიჯს. :::note ონლაინ გადახდის გვერდზე გადამისამართებამდე ბიზნესს შეუძლია, გამოიყენოს ბარათის დამახსოვრების ფუნქციონალი, შემდგომში ოპერაციების ავტომატურ რეჟიმში ან ბარათის მონაცემების შეყვანის გარეშე განხორციელების მიზნით. ::: --- # აუტენტიფიკაცია Source: https://api.bog.ge/docs/sandbox/payments/authentication :::caution note Sandbox გარემოში ავტორიზაცია უნდა განხორციელდეს მხოლოდ Sandbox API რეკვიზიტების გამოყენებით. Sandbox-ში გენერირებული ავტორიზაციის ტოკენები მოქმედებს მხოლოდ ამ გარემოში და არ უნდა იქნას გამოყენებული Live გარემოში. Sandbox ტოკენები რეალური ავტორიზაციის პროცესების სიმულაციას ახდენს, თუმცა არ იძლევა წვდომას რეალურ ფინანსურ ოპერაციებზე. ::: ## რა დამჭირდება გადახდის API-ს გამოსაყენებლად ონლაინ გადახდების API-ს გამოსაყენებლად საჭიროა აუტენტიფიკაცია [HTTP Basic Auth](https://en.wikipedia.org/wiki/Basic_access_authentication)-ის გამოყენებით. ამისთვის თქვენ დაგჭირდებათ, იცოდეთ სისტემაში შესასვლელი რეკვიზიტები (Credentials), რომელიც თითოეული ბიზნესისთვის უნიკალურია. რეკვიზიტები მოიცავს ორ პარამეტრს: client_id და client_secret, რომელიც გამოიყენება, როგორც username-ი და password-ი, ბიზნესის აუტენტიფიკაციისას. ## როგორ გავიგოთ ბიზნესის სისტემაში შესასვლელი რეკვიზიტები მას შემდეგ, რაც კომპანია დარეგისტრირდება ბიზნესად საბანკო სისტემაში და შეავსებს ყველა საჭირო მონაცემს, მას მიენიჭება და გადაეცემა სისტემაში შესასვლელი რეკვიზიტები client_id და client_secret. რეკვიზიტები ბიზნესის უნიკალური მაიდენტიფიცირებელია. ამასთან, client_secret პაროლის მნიშვნელობის პარამეტრია - მისი სხვა პირისთვის გადაცემა, გასაჯაროება, დაუშვებელია. ამან შეიძლება ბიზნესისთვის საფრთხის ალბათობა მნიშვნელოვნად გაზარდოს! client_secret-ის ცვლილება ბიზნესის მიერ შეუძლებელია. ## მეთოდის აღწერა მოცემული მეთოდის საშუალებით, ბიზნესი გადის აუტენტიფიკაციის პროცესს. გამოძახების შედეგად, ონლაინ გადახდების სერვერის მიერ ბრუნდება Bearer Token, რომელიც ყველა შემდგომი მეთოდის გამოძახებისთვის არის აუტენტიფიკაციისთვის აუცილებელი პარამეტრი. ### Header-ის პარამეტრები - `Content-Type` — application/x-www-form-urlencoded, required - `Authorization` — Basic , required გადაეცემა „Basic „ + „:“ მნიშვნელობა კოდირებული Base64 ფორმატში (მაგ: „Basic ODI4Mjo3Njk3MDY0OTlmMDcwOWUyMzQ4NDU4NjNmOThiMjMxNA==“), სადაც და არის ბანკის მიერ ბიზნესისთვის გადაცემული, სისტემაში შესვლისთვის საჭირო, რეკვიზიტები. ### Body-ს პარამეტრები - `grant_type` — client_credentials, required მნიშვნელობად გადაეცემა ფიქსირებული ტექსტი: `client_credentials` **CURL** ```bash curl -X POST 'https://oauth2-sandbox.bog.ge/auth/realms/bog/protocol/openid-connect/token' \ -u {client_id}:{client_secret} \ -H 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'grant_type=client_credentials' ``` ### Response - `access_token` — string ავტორიზაციის სერვერის მიერ დაბრუნებული Token-ის მნიშვნელობა - `token_type` — string Token-ის ტიპი (ბრუნდება ტექსტური მნიშვნელობა - `Bearer`) - `expires_in` — number აბრუნებს რიცხვით მნიშვნელობას, თუ რამდენი წამის განმავლობაში არის აქტიური Token. **RESPONSE** ```json { "access_token": "", "token_type": "Bearer", "expires_in": 1634719923245 } ``` --- # შეკვეთის მოთხოვნა Source: https://api.bog.ge/docs/sandbox/payments/standard-process/create-order :::caution note Sandbox-ში ყველა შეკვეთის მოთხოვნა ქმნის სიმულირებულ order ID-ებსა და redirect URL-ებს. შეგიძლიათ უსაფრთხოდ შეამოწმოთ სრული checkout პროცესი, მათ შორის გადამისამართება, ბარათის მონაცემების შეყვანა და ქოლბექების დამუშავება, რეალური გადახდების განხორციელების გარეშე. მხარდაჭერილი სატესტო მნიშვნელობებისთვის გამოიყენეთ [სატესტო ბარათების](../test-cards) გვერდი. ::: მეთოდის საშუალებით, ბიზნესი ონლაინ გადახდის სერვერზე აგზავნის გადახდის დეტალებს, ტექნიკურ მახასიათებლებსა და გადასახდელ თანხას. ოპერაციის წარმატებით დასრულების შემთხვევაში, პროცესის გასაგრძელებლად, მომხმარებელი უნდა გადაამისამართოთ ონლაინ გადახდის გვერდზე, `_links` პარამეტრში დაბრუნებულ `redirect` მისამართზე. ### Header-ის პარამეტრები - `Content-Type` — application/json, required - `Authorization` — Basic , required გადაეცემა `Bearer ` მნიშვნელობა, სადაც `jwt_token` არის აუტენტიფიკაციის მეთოდის Response-ის access_token პარამეტრში დაბრუნებული მნიშვნელობა. - `Idempotency-Key` — UUID v4 Idempotency-Key პარამეტრი უნდა იყოს უნიკალური ყველა ახალი API რექვესთისთვის. იმავე API-ზე Idempotency-Key-ის განმეორებით გამოყენებისას სერვერი დააბრუნებს იმავე სტატუს კოდსა და body-ს, რაც თავდაპირველი მოთხოვნისას. ეს ფუნქცია განსაკუთრებით სასარგებლოა თანმიმდევრული შედეგის უზრუნველსაყოფად, როდესაც საქმე გვაქვს ქსელური პრობლემებითა ან ხელახალი ცდებით გამოწვეულ დუბლირებულ მოთხოვნებთან. - `Accept-Language` — string განსაზღვრავს ონლაინ გადახდების გვერდზე გადამისამართების შემდეგ, რა ენის ინტერფეისი დახვდება მომხმარებელს. იღებს ორ მნიშვნელობას: - `ka` - ქართული (Default) - `en` - ინგლისური. - `Theme` — string განსაზღვრავს ონლაინ გადახდების გვერდზე გადამისამართების შემდეგ, რა თემის ინტერფეისი დახვდება მომხმარებელს. იღებს ორ მნიშვნელობას: - `light` - ღია (Default) - `dark` - მუქი. ### Body-ს პარამეტრები - `application_type` — "web" | "mobile" აპლიკაციის ტიპი, საიდანაც ხდება შეკვეთის შექმნა. გამოიყენება Apple Pay-ით და Google Pay-ით გადახდისას, როდესაც Apple Pay-ის ან Google Pay-ის ღილაკი განთავსებულია უშუალოდ მერჩანტის ვებ გვერდზე ან მობილურ აპლიკაციაში. აპლიკაციის ტიპის მნიშვნელობებია: - `web` - ვებ გვერდიდან შექმნილი შეკვეთის აპლიკაციის ტიპი. - `mobile` - მობილური აპლიკაციიდან შექმნილი შეკვეთის აპლიკაციის ტიპი. - `buyer` — object ინფორმაცია ბიზნესში მყიდველის შესახებ. - `buyer.full_name` — string მყიდველის სახელი და გვარი. - `buyer.masked_email` — string მყიდველის დაშიფრული ელ. ფოსტის მისამართი. - `buyer.masked_phone` — string მყიდველის დაშიფრული ტელეფონის ნომერი. - `callback_url` — string, required ბიზნესის ვებმისამართი (აუცილებლად https ტიპის), რომელსაც ავტომატურად გამოიძახებს ბანკი, ოპერაციის დასრულების შემდეგ, ბიზნესისთვის გადახდის მონაცემების მიწოდების მიზნით (Callback-ის დროს). - `external_order_id` — string გადახდის იდენტიფიკატორი ბიზნესის სისტემიდან. გადმოცემული მნიშვნელობის პირველი 25 სიმბოლო აისახება გადახდის დანიშნულებაში, როგორც გადამხდელის ამონაწერში, ისე კომპანიის ანგარიშზე თანხის ჩარიცხვის დანიშნულებაში. - `capture` — "automatic" | "manual" ტრანზაქციის ტიპი, რომელიც იღებს ორ მნიშვნელობას: - `automatic` - სტანდარტული ორდერის შექმნა, გადახდა მოხდება პრეავტორიზაციის გარეშე, ანუ მომხარებლის ანგარიშიდან თანხა მომენტალურად ჩამოიჭრება - `manual` - გადახდის შესრულების შემდეგ მომხარებლის ანგარიშზე თანხა დაიბლოკება და მომხმარებლისთვის არ იქნება ხელმისაწვდომი. გადახდის დასასრულებლად უნდა გამოიყენოთ პრეავტორიზაციის დასრულების მეთოდი და დაადასტუროთ/უარყოთ ოპერაცია. ამ ოპერაციის 30 დღეში შეუსრულებლობის შემთხვევაში, თანხას ავტომატურად მოეხსნება ბლოკი და ისევ იქნება ხელმისაწვდომი მომხარებლისთვის. ამ ფუნქციონალის გამოყენება შესაძლებელია მხოლოდ Apple Pay-ით, Google Pay-ით ან საბარათე გადახდაზე. - `purchase_units` — object, required ინფორმაცია შეკვეთის შესახებ. - `purchase_units.basket` — array, required ბიზნესში, მოცემული გადახდის ფარგლებში, შესყიდული პროდუქტების ან სერვისების კალათა. - `purchase_units.basket[].product_id` — string, required პროდუქტის/სერვისის იდენტიფიკატორი ბიზნესის სისტემაში. - `purchase_units.basket[].description` — string პროდუქტის/სერვისის დასახელება (აღწერა). - `purchase_units.basket[].quantity` — number, required თითოეული პროდუქტის/სერვისის რაოდენობა (მოცულობა). მინიმალური მნიშვნელობა არის 1. - `purchase_units.basket[].unit_price` — number, required პროდუქტის/სერვისის ერთეულის ფასი. - `purchase_units.basket[].unit_discount_price` — number აქციით გადახდის შემთხვევაში, შესყიდული პროდუქტის/სერვისის ერთეულის დაკლებული თანხის მოცულობა. - `purchase_units.basket[].vat` — number პროდუქტის/სერვისის დამატებული ღირებულების გადასახადი (დღგ). - `purchase_units.basket[].vat_percent` — number პროდუქტის/სერვისის დამატებული ღირებულების გადასახადის (დღგ) პროცენტი. - `purchase_units.basket[].total_price` — number მთლიანი თანხა. - `purchase_units.basket[].image` — string პროდუქტის/სერვისის სურათის ვებმისამართი (ლინკი). - `purchase_units.basket[].package_code` — string პროდუქტის კოდი. - `purchase_units.basket[].tin` — string საგადასახადო საიდენტიფიკაციო ნომერი (TIN). - `purchase_units.basket[].pinfl` — string გადამხდელის კოდი (PINFL). - `purchase_units.basket[].product_discount_id` — string პროდუქტის ფასდაკლების იდენტიფიკატორი. თუ მოწოდებული მნიშვნელობით ბანკში დარეგისტრირებულია ფასდაკლების აქცია, ფასდაკლების პირობების გათვალისწინებით, შეკვეთაზე გავრცელდება შესაბამისი აქცია. - `purchase_units.delivery` — object ინფორმაცია მიტანის სერვისის შესახებ. - `purchase_units.delivery.amount` — number მიტანის ღირებულება. - `purchase_units.total_amount` — number, required სრული გადასახდელი თანხის მოცულობა. - `purchase_units.total_discount_amount` — number აქციით გადახდის შემთხვევაში, დაკლებული თანხის მოცულობა. - `purchase_units.currency` — string ვალუტა, რომელშიც ხორციელდება გადახდა: - `GEL` - ქართული ლარი (ნაგულისმევი) - `USD` - ამერიკული დოლარი - `EUR` - ევრო - `GBP` - ბრიტანული გირვანქა. - `redirect_urls` — object ბიზნესის ვებმისამართები, რომლებზეც შესაძლოა, გადამისამართდეს მომხმარებელი ონლაინ გადახდის სისტემიდან ოპერაციის დასრულების შემდეგ. - `redirect_urls.success` — string ვებმისამართი ოპერაციის წარმატებით დასრულების შემთხვევაში. მნიშვნელობის არ გადმოცემის შემთხვევაში მომხმარებელი დარჩება ონლაინ გადახდების გვერდზე და გამოუჩნდება შესაბამისი ქვითარი. - `redirect_urls.fail` — string ვებმისამართი ოპერაციის წარუმატებლად დასრულების შემთხვევაში. მნიშვნელობის არ გადმოცემის შემთხვევაში მომხმარებელი დარჩება ონლაინ გადახდების გვერდზე და გამოუჩნდება შესაბამისი ქვითარი. - `ttl` — number შეკვეთის სიცოცხლის ხანგრძლივობა წუთებში (შეკვეთის შექმნიდან რამდენი წუთის განმავლობაში შეეძლება მომხმარებელს გადახდის შესრულება). მოცემული პარამეტრის ლოგიკა სხვა და სხვა ინდუსტრიის ბიზნესისთვის განსხვავებული შეიძლება იყოს. პარამეტრის მინიმალური შესაძლო მნიშვნელობაა `2`, მაქსიმალური კი - `1440` (24 საათი). პარამეტრის არ გადმოცემის შემთხვევაში სისტემა იგულისხმებს `15` წუთს. - `payment_method` — array გადახდის მეთოდები, რომლების გამოყენებასაც შეძლებს მომხმარებელი ამ შეკვეთაზე გადახდის განსახორციელებლად. აუცილებელია, ბიზნესს გააქტიურებული ჰქონდეს ყველა გადმოცემული მეთოდი. პარამეტრის არ გადმოცემის შემთხვევაში მომხმარებელს ონლაინ გადახდის გვერდზე გადამისამართების შემდეგ შეეძლება ყველა იმ გადახდის მეთოდით სარგებლობა, რომელიც გააქტიურებული აქვს ბიზნესს. შესაძლო მნიშვნელობები: - `card` - საბანკო ბარათით გადახდა :::note **Sandbox სატესტო გარემოში ამ ეტაპზე ხელმისაწვდომია მხოლოდ საბარათე გადახდის მეთოდი.**
სხვა გადახდის მეთოდებიც მალე დაემატება. ::: - `google_pay` - Google Pay-ით და საბანკო ბარათით გადახდა (ამ მნიშვნელობის გადმოცემის შემთხვევაში, მომხმარებელს შეეძლება როგორც Google Pay-ით, ასევე საბანკო ბარათით გადახდა. აუცილებელია, რომ ბიზნესს გააქტიურებული ჰქონდეს ორივე გადახდის მეთოდი) - `apple_pay` - Apple Pay-ით და საბანკო ბარათით გადახდა (ამ მნიშვნელობის გადმოცემის შემთხვევაში, მომხმარებელს შეეძლება როგორც Apple Pay-ით, ასევე საბანკო ბარათით გადახდა. აუცილებელია, რომ ბიზნესს გააქტიურებული ჰქონდეს ორივე გადახდის მეთოდი) - `bog_p2p` - საქართველოს ბანკის, ინტერნეტ ან მობაილ ბანკის მომხმარებლით გადარიცხვა - `bog_loyalty` - საქართველოს ბანკის ქულებით MR/Plus გადახდა - `bnpl` - ნაწილ-ნაწილით გადახდა - `bog_loan` - სტანდარტული საბანკო განვადება - `gift_card` - სასაჩუქრე ბარათით გადახდა - `config` — object კონკრეტული გადახდის კონფიგურაცია. - `config.loan` — object გადახდის კონფიგურაცია. პარამეტრის გადმოცემა აუცილებელია თუ გსურთ, რომ შეკვეთის გადახდა მხოლოდ განვადებით ("payment_method":["bog_loan"] ) ან მხოლოდ ნაწილ-ნაწილით ("payment_method":["bnpl"] ) მოხდეს. - `config.loan.type` — string განვადების/ნაწილ-ნაწილის ფასდაკლების კოდი (კალკულატორის მიერ დაბრუნებული discount_code პარამეტრის მნიშვნელობა). - `config.loan.month` — number განვადების/ნაწილ-ნაწილის ხანგრძლივობა თვეებში (კალკულატორის მიერ დაბრუნებული month პარამეტრის მნიშვნელობა). - `config.campaign` — object აქციით გადახდის კონფიგურაცია. იმისთვის, რომ მომხმარებელმა შეძლოს ბიზნესზე დამატებული აქციით სარგებლობა, საჭიროა, შეკვეთის შექმნისას გადახდის მეთოდში საბარათე გადახდის მითითება ("payment_method":["card"] ). - `config.campaign.card` — string ბარათი, რომელზეც ვრცელდება აქცია: - `visa` - ვიზა - `mc` - მასტერქარდი - `solo` - სოლო ბარათი - `config.campaign.type` — string აქციის ტიპი: - `restrict` - ბარათის ტიპის შეზღუდვა - `client_discount` - ფასდაკლება კონკრეტულ ბარათის ტიპზე - `config.google_pay` — object გადახდის კონფიგურაცია. პარამეტრის გადმოცემა აუცილებელია თუ გსურთ, რომ შეკვეთის გადახდა ბიზნესის ვებგვერდზე განთავსებული Google Pay-ს ღილაკით მოხდეს. - `config.google_pay.google_pay_token` — string სრულყოფილი string მნიშვნელობა, რომელიც წარმოადგენს Google Pay-ის დაკრიპტულ გადახდის დეტალებს. მნიშვნელობა უნდა გადმოეცეს სრულყოფილად, როგორი სახითაც მიიღეთ Google Pay SDK-სგან, ცვლილებების გარეშე. - `config.google_pay.external` — boolean - `true` - გადახდა ინიცირდება ბიზნესის ვებგვერდზე განთავსებული Google Pay-ს ღილაკით - `false` - გადახდა ხდება ბანკის გადახდების გვერდიდან (ნაგულისმევი) - `config.apple_pay` — object გადახდის კონფიგურაცია. პარამეტრის გადმოცემა აუცილებელია თუ გსურთ, რომ შეკვეთის გადახდა ბიზნესის ვებგვერდზე განთავსებული Apple Pay-ს ღილაკით მოხდეს. - `config.apple_pay.external` — boolean - `true` - გადახდა ინიცირდება ბიზნესის ვებგვერდზე განთავსებული Apple Pay-ს ღილაკით - `false` - გადახდა ხდება ბანკის გადახდების გვერდიდან (ნაგულისმევი) - `config.account` — object გადახდის კონფიგურაცია. პარამეტრის გადმოცემა აუცილებელია თუ თქვენთვის კონფიგურირებულია რამდენიმე ელ.კომერციის POS ტერმინალი ერთსადაიმავე ვალუტაში: შესრულებული ოპერაციები გსურთ დააჯგუფოთ ბიზნესის საჭიროებებიდან გამომდინარე ან ანგარიშსწორება შესრულდეს ბიზნესის სხვადასხვა ანგარიშზე. - `config.account.tag` — string ელ.კომერციის POS ტერმინალის იდენტიფიკატორი. თუ მოწოდებული tag-ის მნიშვნელობა არ ემთხვევა POS-ის კონფიგურაციას ან tag მოწოდებული არ არის, ოპერაცია შესრულდება default POS ტერმინალზე და შესაბამის ანგარიშსწორების ანგარიშზე. შენიშვნა: ტეგის მნიშვნელობის შეთანხმება აუცილებელია დამატებითი POS-ის კონფიგურირებისას. **CURL** ```bash curl -X POST 'https://api-sandbox.bog.ge/payments/v1/ecommerce/orders' \ -H 'Accept-Language: ka' \ -H 'Authorization: Bearer ' \ -H 'Content-Type: application/json' \ --data-raw '{ "callback_url": "https://example.com/callback", "external_order_id": "id123", "purchase_units": { "currency": "GEL", "total_amount": 1, "basket": [ { "quantity": 1, "unit_price": 1, "product_id": "product123" } ] }, "redirect_urls": { "fail": "https://example.com/fail", "success": "https://example.com/success" } }' ``` ### Response - `id` — string ონლაინ გადახდის იდენტიფიკატორი. - `_links` — object ვებრესურსის მისამართები, რომლებიც გადახდის პროცესის შემდგომ ეტაპებზე გამოიყენება. ამჟამად ბრუნდება ორი რესურსი: - `_links.details.href` — string გადახდის დეტალების მისამართი, რომლის გამოძახებითაც შეგიძლიათ, გაიგოთ ინფორმაცია ონლაინ გადახდის შესახებ. - `_links.redirect.href` — string ვებგვერდის მისამართი, რომელზეც უნდა გადავიდეს მომხმარებელი პლასტიკური ბარათის ან ონლაინბანკინგის მონაცემების შესაყვანად და გადახდის პროცესის დასასრულებლად. **RESPONSE** ```json { "id": "{order_id}", "_links": { "details": { "href": "https://api-sandbox.bog.ge/payments/v1/receipt/{order_id}" }, "redirect": { "href": "https://payment-sandbox.bog.ge/?order_id={order_id}" } } } ``` --- # გადახდების დეტალების მიღება Source: https://api.bog.ge/docs/sandbox/payments/standard-process/get-payment-details მეთოდის საშუალებით, ბიზნესს აქვს შესაძლებლობა, მიიღოს დეტალური ინფორმაცია ონლაინ გადახდის შესახებ, მისი იდენტიფიკატორის მიხედვით. ### Header-ის პარამეტრები - `Authorization` — Basic , required გადაეცემა `Bearer ` მნიშვნელობა, სადაც `jwt_token` არის აუტენტიფიკაციის მეთოდის Response-ის access_token პარამეტრში დაბრუნებული მნიშვნელობა. ### Path პარამეტრები - `order_id` — string, required შეკვეთის იდენტიფიკატორი, რომელიც ონლაინ მაღაზიას უბრუნდება შეკვეთის მოთხოვნის Response-ში. **CURL** ```bash curl -X GET 'https://api-sandbox.bog.ge/payments/v1/receipt/:order_id' \ -H 'Authorization: Bearer ' ``` ## Response - `order_id` — string ონლაინ გადახდის იდენტიფიკატორი. - `industry` — string ბიზნესის ინდუსტრია, რომელიც მისი რეგისტრაციის დროს განისაზღვრება. - `capture` — string ავტორიზაციის მეთოდი. ყოველთვის - `automatic`. ტრანზაქციის ტიპი ორი შესაძლო მნიშვნელობით: - `automatic` - სტანდარტული ორდერი - `manual` - პრეავტორიზაციის ორდერი - `external_order_id` — string გადახდის იდენტიფიკატორი ბიზნესის სისტემიდან. გადმოცემული მნიშვნელობის პირველი 25 სიმბოლო აისახება გადახდის დანიშნულებაში, როგორც გადამხდელის ამონაწერში, ისე კომპანიის ანგარიშზე თანხის ჩარიცხვის დანიშნულებაში. - `client` — object ბიზნესის ინფორმაცია. - `client.id` — string ბიზნესის იდენტიფიკატორი ბანკის სისტემაში. - `client.brand_ka` — string ბიზნესის ქართული დასახელება. - `client.brand_en` — string ბიზნესის ინგლისური დასახელება. - `client.url` — string ბიზნესის ვებგვერდის მისამართი. - `zoned_create_date` — string შეკვეთის შექმნის თარიღი მსოფლიო კოორდინირებული დროით ( UTC), "YYYY-MM-DDTHH:MM:SS.ssssssZ" ფორმატში. - `zoned_expire_date` — string შეკვეთის ვადის გასვლის თარიღი მსოფლიო კოორდინირებული დროით (UTC), "YYYY-MM-DDTHH:MM:SS.ssssssZ" ფორმატში. - `order_status` — object შეკვეთის სტატუსი. - `order_status.key` — string სტატუსი იღებს შემდეგ მნიშვნელობებს: - `created` - გადახდის მოთხოვნა შექმნილია - `processing` - გადახდა მუშავდება - `completed` - გადახდის პროცესი დასრულდა წარმატებით - `rejected` - გადახდის პროცესი დასრულდა წარუმატებლად - `refund_requested` - მოთხოვნილია თანხის დაბრუნება - `refunded` - გადახდის თანხა დაბრუნებულია - `refunded_partially` - გადახდის თანხა ნაწილობრივ დაბრუნებულია - `auth_requested` - პრეავტორიზირებული გადახდა მოთხოვნილია - `blocked` - პრეავტორიზირებული გადახდის პროცესი დასრულდა წარმატებით, თუმცა თანხა ჯერ დაბლოკილია და ელოდება დადასტურებას - `partial_completed` - პრეავტორიზირებული გადახდა ნაწილობრივ თანხაზე წარმატებით დადასტურდა - `order_status.value` — string აღწერა. - `buyer` — object მყიდველის ინფორმაცია. - `buyer.full_name` — string მყიდველის სრული სახელი. - `buyer.email` — string მყიდველის ელ. ფოსტის მისამართი. - `buyer.phone_number` — string მყიდველის ტელეფონის ნომერი. - `purchase_units` — object ინფორმაცია შესყიდული პროდუქციის შესახებ. - `purchase_units.request_amount` — string შეკვეთის მოთხოვნილი თანხა. - `purchase_units.transfer_amount` — string შეკვეთის დამუშავებული თანხა. - `purchase_units.refund_amount` — string დაბრუნებული თანხა. - `purchase_units.currency_code` — string ვალუტა. - `purchase_units.items` — array შეძენილი პროდუქტების/სერვისების მასივი. - `purchase_units.items[].external_item_id` — string პროდუქტის/სერვისის იდენტიფიკატორი ბიზნესის სისტემაში. - `purchase_units.items[].description` — string პროდუქტის/სერვისის დასახელება (აღწერა). - `purchase_units.items[].quantity` — string თითოეული პროდუქტის/სერვისის რაოდენობა (მოცულობა). - `purchase_units.items[].unit_price` — string პროდუქტის/სერვისის ერთეულის ფასი. - `purchase_units.items[].unit_discount_price` — string აქციით გადახდის შემთხვევაში, შესყიდული პროდუქტის/სერვისის ერთეულის დაკლებული თანხის მოცულობა. - `purchase_units.items[].vat` — string პროდუქტის/სერვისის დამატებული ღირებულების გადასახადი (დღგ). - `purchase_units.items[].vat_percent` — string პროდუქტის/სერვისის დამატებული ღირებულების გადასახადის (დღგ) პროცენტი. - `purchase_units.items[].total_price` — string მთლიანი თანხა. - `purchase_units.items[].package_code` — string პროდუქტის კოდი. - `purchase_units.items[].tin` — string საგადასახადო საიდენტიფიკაციო ნომერი (TIN). - `purchase_units.items[].pinfl` — string გადამხდელის კოდი (PINFL). - `purchase_units.basket[].product_discount_id` — string პროდუქტის ფასდაკლების იდენტიფიკატორი. თუ მოწოდებული მნიშვნელობით ბანკში დარეგისტრირებულია ფასდაკლების აქცია, ფასდაკლების პირობების გათვალისწინებით, შეკვეთაზე გავრცელდება შესაბამისი აქცია. - `redirect_links` — object ბიზნესის ვებგვერდები, რომლებზეც შესაძლოა გადამისამართდეს მომხმარებელი ონლაინ გადახდის სისტემიდან, ოპერაციის დასრულების შემდეგ. - `redirect_links.fail` — string ვებმისამართი ოპერაციის წარუმატებლად დასრულების შემთხვევაში. - `redirect_links.success` — string ვებმისამართი ოპერაციის წარმატებით დასრულების შემთხვევაში. - `payment_detail` — object გადახდის დეტალები. - `payment_detail.transfer_method` — object გადახდის მეთოდი. - `payment_detail.transfer_method.key` — string გადახდის მეთოდი იღებს შემდეგ მნიშვნელობებს: - `card` - საბანკო ბარათით გადახდა :::note **Sandbox სატესტო გარემოში ამ ეტაპზე ხელმისაწვდომია მხოლოდ საბარათე გადახდის მეთოდი.**
სხვა გადახდის მეთოდებიც მალე დაემატება. ::: - `google_pay` - Google Pay-ით გადახდა - `apple_pay` - Apple Pay-ით გადახდა - `bog_p2p` - საქართველოს ბანკის, ინტერნეტ ან მობაილ ბანკის მომხმარებლით გადარიცხვა - `bog_loyalty` - საქართველოს ბანკის ქულებით MR/Plus გადახდა - `bnpl` - ნაწილ-ნაწილით გადახდა - `bog_loan` - სტანდარტული საბანკო განვადება. - `payment_detail.transfer_method.value` — string აღწერა. - `payment_detail.transaction_id` — string ტრანზაქციის იდენტიფიკატორი. - `payment_detail.auth_code` — string გადახდის ავტორიზაციის იდენტიფიკატორი. მნიშვნელობა ასევე აისახება კომპანიის ანგარიშზე ანგარიშსწორების ამონაწერში. - `payment_detail.payer_identifier` — string გადამხდელის იდენტიფიკატორი, transfer_method-ის მიხედვით იღებს სხვა და სხვა მნიშვნელობას: - `card`/`google_pay` – ბრუნდება ბარათის დაშიფრული ნომერი (PAN) - `apple_pay` – ბრუნდება Apple-ის მიერ მინიჭებული ბარათის ნომერი, რომელიც უნიკალურია ყველა მოწყობილობისთვის - `bog_p2p`/`bog_loyalty` – ბრუნდება ანგარიშის სახელი - `bog_loan`/`bnpl` – ბრუნდება მომხმარებლის სახელი და გვარის პირველი ასო. - `payment_detail.payment_option` — string გადახდის გზა. შესაძლებელია დაბრუნდეს შემდეგი მნიშვნელობები: - `direct_debit` - ბარათით გადახდა - `recurrent` - დამახსოვრებული ბარათით გადახდა - `subscription` - დამახსოვრებული ბარათით ავტომატური ჩამოჭრა. - `payment_detail.card_type` — string იმ ბარათის ტიპი, რომლითაც მოხდა გადახდა. პარამეტრი მნიშვნელობას იღებს საბარათე გადახდის დროს: - `amex` - American Express - `mc` - Mastercard - `visa` - Visa. - `payment_detail.card_expiry_date` — string იმ ბარათის ვადის გასვლის თარიღი (თვე/წელი), რომლითაც მოხდა გადახდა. პარამეტრი მნიშვნელობას იღებს საბარათე გადახდის დროს. - `payment_detail.request_account_tag` — string ელ.კომერციის POS ტერმინალის შეკვეთაში მოთხოვნილი იდენტიფიკატორი - `payment_detail.transfer_account_tag` — string ელ.კომერციის იმ POS ტერმინალის იდენტიფიკატორი, რომელზეც შესრულდა გადახდა. - `payment_detail.saved_card_type` — string დამახსოვრებული ბარათის ტიპი. შესაძლო მნიშვნელობებია: - `recurrent` - ბარათი დამახსოვრებულია კლიენტის მიერ ინცირებული მომავალი გადახდისთვის. - `subscription` - ბარათი დამახსოვრებულია ავტომატური გადახდებისთვის ფიქსირებული თანხითა და დეტალებით. - `payment_detail.parent_order_id` — string თუ გადახდა მოხდა დამახსოვრებული ბარათით, აღნიშნულ ველში მითითებულია დამახსოვრებული ბარათის შეკვეთის იდენტიფიკატორი. - `payment_detail.code` — string გადახდის Response კოდი. - `payment_detail.code_description` — string გადახდის Response კოდის აღწერა. - `payment_detail.auth_code` — string საბარათე, Google Pay-ით ან Apple Pay-ით გადახდის ავტორიზაციის კოდი. - `discount` — object ინფორმაცია ფასდაკლების შესახებ, რომელიც გავრცელდა გადახდაზე - `discount.bank_discount_amount` — string ბანკის მიერ გავრცელებული ფასდაკლების თანხა - `discount.bank_discount_desc` — string ბანკის მიერ გავრცელებული ფასდაკლების აღწერა - `discount.system_discount_amount` — string საბარათე სისტემის მიერ გავრცელებული ფასდაკლების თანხა - `discount.system_discount_desc` — string საბარათე სისტემის მიერ გავრცელებული ფასდაკლების აღწერა - `discount.discounted_amount` — string თანხა ფასდაკლების შემდეგ - `discount.original_order_amount` — string საწყისი თანხა - `actions` — array შეკვეთასთან დაკავშირებული ქმედებების სია. - `actions[].action_id` — string ქმედების იდენტიფიკატორი. - `actions[].request_channel` — string წყარო, რომლიდანაც მოხდა ქმედების ინიციარება: - `public_api` - ონლაინ გადახდების API - `business_manager` - ბიზნეს მენეჯერის გვერდი - `support` - საქართველოს ბანკის შიდა სისტემა. - `actions[].action` — string ქმედების ტიპი: - `authorize` - პრეავტორიზირებული გადახდის დადასტურება - `partial_authorize` - პრეავტორიზირებული გადახდის დადასტურება არასრულ თანხაზე - `cancel_authorize` - პრეავტორიზირებული გადახდის უარყოფა - `refund` - თანხის დაბრუნება - `partial_refund` - თანხის ნაწილობრივი დაბრუნება. - `actions[].status` — string ქმედების სტატუსი: - `completed` - ქმედება დასრულდა წარმატებით - `rejected` - ქმედება დასრულდა წარმუმატებლად - `actions[].code` — string მოქმედების response კოდი. მოქმედების Response კოდების სია იხ. [აქ](../response-codes#მოქმედების-response-კოდები). - `actions[].code_description` — string მოქმედების response კოდის აღწერა. - `actions[].zoned_action_date` — string ქმედების ინიცირების თარიღი მსოფლიო კოორდინირებული დროით (UTC), "YYYY-MM-DDTHH:MM:SS.ssssssZ" ფორმატში. - `actions[].amount` — string თანხის მოცულობა, რომელზეც განხორციელდა ქმედება. - `lang` — string ონლაინ გადახდების გვერდზე გადამისამართების შემდეგ, რა ენის ინტერფეისი დახვდება მომხმარებელს. იღებს ორ მნიშვნელობას: - `ka` - ქართული - `en` - ინგლისური. - `reject_reason` — string გადახდის წარუმატებლად დასრულების მიზეზი. პარამეტრი მნიშვნელობას იღებს მხოლოდ მაშინ, თუ შეკვეთა წარუმატებლად დასრულდა ("order_status": "rejected"). იღებს შემდეგ მნიშვნელობებს: - `expiration` - შეკვეთას გაუვიდა ვადა - `unknown` - დაუდგენელი მიზეზი. - `გადახდის Response კოდის აღწერა` - ბარათით, Google pay-ით ან Apple pay-ით ინიცირებული გადახდების უარყოფის მიზეზი. Response კოდების სია იხილეთ [აქ](https://api.bog.ge/docs/docs/payments/response-codes). **RESPONSE** ```json { "order_id": "a767a276-cddd-43ec-9db3-9f9b39eee02d", "industry": "ecommerce", "capture": "automatic", "external_order_id": "123456", "client": { "id": "10000", "brand_ka": "საქართველოს ბანკი", "brand_en": "BOG", "url": "https://api.bog.ge" }, "create_date": "2022-11-01T13:19:43.021178", "zoned_create_date": "2022-11-01T13:19:43.021178Z", "expire_date": "2022-11-01T13:39:43.021178", "zoned_expire_date": "2022-11-01T13:39:43.021178Z", "order_status": { "key": "refunded", "value": "დაბრუნებული" }, "buyer": { "full_name": "John Doe", "email": "johndoe@gmail.com", "phone_number": "+995555000000" }, "purchase_units": { "request_amount": "100.5", "transfer_amount": "0.0", "refund_amount": "100.5", "currency_code": "GEL", "items": [ { "external_item_id": "id_1", "description": "product 1", "quantity": "1", "unit_price": "25.35", "unit_discount_price": "0", "vat": "0", "vat_percent": "0", "total_price": "25.35", "package_code": "A000123", "tin": null, "pinfl": null, "product_discount_id": "BF222R5" } ] }, "redirect_links": { "success": "https://payment.bog.ge/receipt?order_id=a767a276-cddd-43ec-9db3-9f9b39eee02d", "fail": "https://payment.bog.ge/receipt?order_id=a767a276-cddd-43ec-9db3-9f9b39eee02d" }, "payment_detail": { "transfer_method": { "key": "card", "value": "ბარათით გადახდა" }, "code": "100", "code_description": "Successful payment", "transaction_id": "230513868679", "payer_identifier": "548888xxxxxx9893", "payment_option": "direct_debit", "card_type": "mc", "card_expiry_date": "03/24", "request_account_tag": "1212", "transfer_account_tag": "gev2", "saved_card_type": "recurrent", "parent_order_id": "8d52130d-cb1b-45ea-b048-0f040a44e2a3", "pg_trx_id": "K4T2XMAZ9EBVQ3WN", "auth_code": "483921" }, "discount": { "bank_discount_amount": "string", "bank_discount_desc": "string", "discounted_amount": "string", "original_order_amount": "string", "system_discount_amount": "string", "system_discount_desc": "string" }, "actions": [ { "action_id": "b70968ca-eda9-47ae-8811-26fd1ab733f8", "request_channel": "public_api", "action": "authorize", "status": "completed", "action_date": "2022-11-28T13:42:40.668439", "zoned_action_date": "2022-11-28T13:42:40.668439Z", "amount": "100.5", "code": null, "code_description": null }, { "action_id": "a89b872a-9700-4025-b3fb-047cbba7a5e6", "request_channel": "business_manager", "action": "refund", "status": "completed", "action_date": "2022-11-28T13:58:03.427939", "zoned_action_date": "2022-11-28T13:58:03.427939Z", "amount": "100.5", "code": null, "code_description": null } ], "disputes": null, "split": null, "lang": "ka", "reject_reason": null } ``` --- # Callback Source: https://api.bog.ge/docs/sandbox/payments/standard-process/callback :::caution note Sandbox-ში Callback გამოძახებები სიმულირებულია. ყოველთვის განახორციელეთ Callback-ების უსაფრთხოდ დამუშავება და გადაამოწმეთ ხელმოწერის ვალიდაციის ლოგიკა, თუნდაც Sandbox გარემოში ტესტირების დროს. ::: Callback-ი არის ასინქრონული, server-to-server შეტყობინება, რომელიც ონლაინ გადახდების სისტემიდან თქვენს მიერ მითითებულ Callback URL მისამართზე იგზავნება. მისი მიზანია, საიმედოდ გაცნობოთ ტრანზაქციის საბოლოო სტატუსის შესახებ. სინქრონული API მოთხოვნებისგან განსხვავებით, სადაც ბიზნესის აპლიკაცია ითხოვს ინფორმაციას და ელოდება მყისიერ პასუხს, Callback-ის პროცესი ფონურ რეჟიმში მიმდინარეობს. ონლაინ გადახდების სისტემა ავტომატურად გამოაგზავნის POST მოთხოვნას ბიზნესის Callback URL-ზე, როდესაც გადახდა ან მასთან დაკავშირებული მოქმედება დასრულდება (წარმატებით ან წარუმატებლად), როგორიცაა თანხის ნაწილობრივი ან სრული დაბრუნება, პრეავტორიზაციის დადასტურება, თანხის გაყოფა. Callback-ის მიღებისა და დამუშავების ლოგიკა, მათ შორის მისი ხელმოწერის ვალიდაცია, ბიზნესის მხარეს უნდა იყოს იმპლემენტირებული. Callback-ის სათანადოდ დამუშავება კრიტიკულად მნიშვნელოვანი ნაბიჯია გადახდის სტატუსის დასადასტურებლად და ბიზნესის სისტემაში შეკვეთის უსაფრთხოდ განახლებისთვის. შეკვეთის მოთხოვნის დროს გადმოცემულ callback_url მისამართზე იგზავნება POST მეთოდით გადახდის დეტალები. პასუხის წარმატებით მიღების დასადასტურებლად, ბიზნესმა უნდა დააბრუნოს HTTP CODE 200. თუ ბიზნესმა წარმატებით ვერ მიიღო Callback, გადახდის სტატუსის გადასამოწმებლად და თავის სისტემაში შეკვეთის სტატუსის სწორად ასახვისთვის, უნდა გამოიყენოს [გადახდის დეტალების მიღების](https://api.bog.ge/docs/payments/standard-process/get-payment-details) მეთოდი. :::note **Callback და Redirect URL სხვადასხვა მიზანს ემსახურება:** **Redirect URL** - გადახდის დასრულების შემდეგ მომხმარებელს გადაამისამართებს ონლაინ გადახდის გვერდიდან ბიზნესის ვებგვერდზე, რაც აუმჯობესებს მომხმარებლის გამოცდილებას. თუმცა, ეს არ წარმოადგენს გადახდის საბოლოო სტატუსის გარანტიას, რადგან გადამისამართება შესაძლოა ვერ განხორციელდეს მომხმარებლის ქმედებების ან სხვა გარემოებების გამო. ამიტომ გადახდის დასრულების დადასტურება აუცილებელია server-to-server Callback-ის გამოყენებით. **Callbacks** - უზრუნველყოფს გადახდის სტატუსის დადასტურებას და გადახდის შესახებ ინფორმაციის უსაფრთხო მიწოდებას ონლაინ გადახდის სისტემის სერვერიდან ბიზნესის სერვერზე. Redirect URL-ისგან განსხვავებით, callback-ის მიღება არ არის დამოკიდებული მომხმარებლის ქმედებებზე და წარმოადგენს გადახდის სტატუსის შესახებ ინფორმაციის მიღების სანდო წყარო. ::: # Request ### Header-ის პარამეტრები - `Callback-Signature` — string ხელმოწერა დაგენერირებულია callback-ის request body-ზე `private key`-ით `SHA256withRSA` ალგორითმის გამოყენებით. იმისათვის, რომ ბიზნესი დარწმუნდეს callback-ში გადმოცემული ინფორმაციის ვალიდურობაში, request body-ისა და `public key`-ის დახმარებით უნდა დაავერიფიციროს ხელმოწერა. ვერიფიკაცია უნდა მოხდეს payload-ის დესერიალიზაციამდე, იმისათვის რომ request body-ის პარამეტრების თანმიმდევრობა დარჩეს უცვლელი. **PUBLIC KEY** ```bash -----BEGIN PUBLIC KEY----- MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAqczfAuhtxw2iF68kS0Hy bGSv0ZlDAjsXh6VC8avDl3Vxa9qCn6Pzl37Tl2Z21WodiISLeXdhCtOMTeLNUBeb CYD31y2/MwnhLYqlCk2bOh29fyPc1iT5Eu/k/1IaNRrK9/UVZaTkhOMeEm+aL4y8 5XsE4UjqftEmwrAdbO2G4cCpuoMC9ZXG9gAdr2BFN6i2Vt9eCen5Poj7E1ik7s8T GyzploVV0NflhwBGeWnvQANUQGr87gsP5k2JG1z5EwnMybJQ7i3XT726rJMaV6QW sY5hP72Mtv1I1zL2d9FXm9FWOzbpcXCyxuEBXvqqOHzogri8C7KRRYKyk97Ri7D6 8wIDAQAB -----END PUBLIC KEY----- ``` ### Body-ს პარამეტრები - `event` — string ქოლბექის ტიპი. მნიშვნელობა ყოველთვის არის `order_payment`. - `zoned_request_time` — string ქოლბექის გამოგზავნის თარიღი მსოფლიო კოორდინირებული დროით (UTC), "YYYY-MM-DDTHH:MM:SS.ssssssZ" ფორმატში. - `body` — object შეკვეთის მონაცემები. მოიცავს იმავე ველებს, რასაც შეიცავს [გადახდის დეტალები](https://api.bog.ge/docs/payments/standard-process/get-payment-details#response). **REQUEST BODY** ```json { "event": "order_payment", "zoned_request_time": "2022-11-23T18:06:37.240559Z", "body": { "order_id": "a767a276-cddd-43ec-9db3-9f9b39eee02d", "industry": "ecommerce", ... } } ``` --- # მომავალი გადახდებისთვის Source: https://api.bog.ge/docs/sandbox/payments/saved-card/recurrent ბანკი ბიზნესს აძლევს საშუალებას, მომხმარებლის თანხმობის საფუძველზე, დაიმახსოვროს მისი ბარათი, რათა შემდგომში მომხმარებელმა შეძლოს, ბარათის მონაცემების მითითების გარეშე გადაიხადოს შეკვეთის საფასური. ამისთვის, ბიზნესმა შეკვეთის მოთხოვნის შემდეგ, გადახდების გვერდზე მომხმარებლის გადამისამართებამდე, უნდა გამოიძახოს შესაბამისი მეთოდი და გადასცეს მას შეკვეთის იდენტიფიკატორი. თუ მოცემულ შეკვეთაზე წარმატებით შესრულდება საბარათე გადახდა, შემდგომი შეკვეთების მოთხოვნისას ამავე იდენტიფიკატორის გამოყენებას შეძლებთ. ### Header-ის პარამეტრები - `Authorization` — Basic , required გადაეცემა `Bearer ` მნიშვნელობა, სადაც `jwt_token` არის აუტენტიფიკაციის მეთოდის Response-ის access_token პარამეტრში დაბრუნებული მნიშვნელობა. - `Idempotency-Key` — UUID v4 Idempotency-Key პარამეტრი უნდა იყოს უნიკალური ყველა ახალი API რექვესთისთვის. იმავე API-ზე Idempotency-Key-ის განმეორებით გამოყენებისას სერვერი დააბრუნებს იმავე სტატუს კოდსა და body-ს, რაც თავდაპირველი მოთხოვნისას. ეს ფუნქცია განსაკუთრებით სასარგებლოა თანმიმდევრული შედეგის უზრუნველსაყოფად, როდესაც საქმე გვაქვს ქსელური პრობლემებითა ან ხელახალი ცდებით გამოწვეულ დუბლირებულ მოთხოვნებთან. ### Path პარამეტრები - `order_id` — string, required შეკვეთის იდენტიფიკატორი, რომელიც ბრუნდება შეკვეთის მოთხოვნის Response-ში. ### Response - `Http Status: ` — 202 ACCEPTED მოთხოვნა მიღებულია. **CURL** ```bash curl -X PUT 'https://api-sandbox.bog.ge/payments/v1/orders/:order_id/cards' \ -H 'Authorization: Bearer ' ``` --- # ავტომატური გადახდებისთვის Source: https://api.bog.ge/docs/sandbox/payments/saved-card/offline ბანკი ბიზნესს აძლევს საშუალებას, მომხმარებლის თანხმობის საფუძველზე, დაიმახსოვროს მისი ბარათი, რათა შემდგომში შეძლოს ჩამოაჭრას თანხა ავტომატურად, მომხმარებლის მონაწილეობის გარეშე. ამისთვის, ბიზნესმა შეკვეთის მოთხოვნის შემდეგ, გადახდების გვერდზე მომხმარებლის გადამისამართებამდე, უნდა გამოიძახოს შესაბამისი მეთოდი და გადასცეს მას შეკვეთის იდენტიფიკატორი. თუ მოცემულ შეკვეთაზე წარმატებით შესრულდება საბარათე გადახდა, შემდგომი შეკვეთების მოთხოვნისას ამავე იდენტიფიკატორის გამოყენებას შეძლებთ. ### Header-ის პარამეტრები - `Authorization` — Basic , required გადაეცემა `Bearer ` მნიშვნელობა, სადაც `jwt_token` არის აუტენტიფიკაციის მეთოდის Response-ის access_token პარამეტრში დაბრუნებული მნიშვნელობა. - `Idempotency-Key` — UUID v4 Idempotency-Key პარამეტრი უნდა იყოს უნიკალური ყველა ახალი API რექვესთისთვის. იმავე API-ზე Idempotency-Key-ის განმეორებით გამოყენებისას სერვერი დააბრუნებს იმავე სტატუს კოდსა და body-ს, რაც თავდაპირველი მოთხოვნისას. ეს ფუნქცია განსაკუთრებით სასარგებლოა თანმიმდევრული შედეგის უზრუნველსაყოფად, როდესაც საქმე გვაქვს ქსელური პრობლემებითა ან ხელახალი ცდებით გამოწვეულ დუბლირებულ მოთხოვნებთან. ### Path პარამეტრები - `order_id` — string, required შეკვეთის იდენტიფიკატორი, რომელიც ბრუნდება შეკვეთის მოთხოვნის Response-ში. ### Response - `Http Status: ` — 202 ACCEPTED მოთხოვნა მიღებულია. **CURL** ```bash curl -X PUT 'https://api-sandbox.bog.ge/payments/v1/orders/:order_id/subscriptions' \ -H 'Authorization: Bearer ' ``` --- # დამახსოვრებული ბარათის წაშლა Source: https://api.bog.ge/docs/sandbox/payments/saved-card/delete მეთოდის საშუალებით ბიზნესს შეუძლია, წაშალოს დამახსოვრებული ბარათი. ### Header-ის პარამეტრები - `Authorization` — Basic , required გადაეცემა `Bearer ` მნიშვნელობა, სადაც `jwt_token` არის აუტენტიფიკაციის მეთოდის Response-ის access_token პარამეტრში დაბრუნებული მნიშვნელობა. - `Idempotency-Key` — UUID v4 Idempotency-Key პარამეტრი უნდა იყოს უნიკალური ყველა ახალი API რექვესთისთვის. იმავე API-ზე Idempotency-Key-ის განმეორებით გამოყენებისას სერვერი დააბრუნებს იმავე სტატუს კოდსა და body-ს, რაც თავდაპირველი მოთხოვნისას. ეს ფუნქცია განსაკუთრებით სასარგებლოა თანმიმდევრული შედეგის უზრუნველსაყოფად, როდესაც საქმე გვაქვს ქსელური პრობლემებითა ან ხელახალი ცდებით გამოწვეულ დუბლირებულ მოთხოვნებთან. ### Path პარამეტრები - `order_id` — string, required შეკვეთის იდენტიფიკატორი, რომელზეც თავდაპირველად მოხდა ბარათის დამახსოვრება. ### Response - `Http Status: ` — 202 ACCEPTED მოთხოვნა მიღებულია. **CURL** ```bash curl -X DELETE 'https://api-sandbox.bog.ge/payments/v1/charges/card/:order_id' \ -H 'Authorization: Bearer ' ``` --- # დამახსოვრებული ბარათით გადახდა Source: https://api.bog.ge/docs/sandbox/payments/saved-card/recurrent-payment მეთოდის საშუალებით ბიზნესს შეუძლია, მომხმარებელს გადაახდევინოს ბანკის ვებ-გვერდზე ბარათის მონაცემების მითითების გარეშე. მეთოდის გამოყენება მიზანშეწონილია, თუ მომხმარებელს რომელიმე წინა წარმატებული საბარათე გადახდის დროს დამახსოვრებული ჰქონდა ბარათი შემდგომი გადახდებისთვის. ### Path პარამეტრები - `parent_order_id` — string, required შეკვეთის იდენტიფიკატორი, რომელზეც მოხდა ბარათის დამახსოვრება შემდგომი გადახდებისთვის. :::note `Header`, `Body` და `Response` იგივეა, რაც [შეკვეთის მოთხოვნის](https://api.bog.ge/docs/payments/standard-process/create-order) დროს. ::: **CURL** ```bash curl -X POST 'https://api-sandbox.bog.ge/payments/v1/ecommerce/orders/:parent_order_id' \ -H 'Accept-Language: ka' \ -H 'Authorization: Bearer ' \ -H 'Content-Type: application/json' \ --data-raw '{ "callback_url": "https://example.com/callback", "purchase_units": { "total_amount": 1, "basket": [ { "quantity": 1, "unit_price": 1, "product_id": "product123" } ] } }' ``` --- # დამახსოვრებული ბარათით ავტომატური ჩამოჭრა Source: https://api.bog.ge/docs/sandbox/payments/saved-card/offline-payment მეთოდის საშუალებით, ბიზნესს შეუძლია მომხმარებელს თანხა ჩამოაჭრას მისი მონაწილეობის გარეშე. მეთოდის გამოყენება მიზანშეწონილია, თუ მომხმარებელს რომელიმე წინა წარმატებული საბარათე გადახდის დროს დამახსოვრებული ჰქონდა ბარათი ავტომატური ჩამოჭრისთვის. ### Header-ის პარამეტრები - `Content-Type` — application/json, required - `Authorization` — Basic , required გადაეცემა `Bearer ` მნიშვნელობა, სადაც `jwt_token` არის აუტენტიფიკაციის მეთოდის Response-ის access_token პარამეტრში დაბრუნებული მნიშვნელობა. - `Idempotency-Key` — UUID v4 Idempotency-Key პარამეტრი უნდა იყოს უნიკალური ყველა ახალი API რექვესთისთვის. იმავე API-ზე Idempotency-Key-ის განმეორებით გამოყენებისას სერვერი დააბრუნებს იმავე სტატუს კოდსა და body-ს, რაც თავდაპირველი მოთხოვნისას. ეს ფუნქცია განსაკუთრებით სასარგებლოა თანმიმდევრული შედეგის უზრუნველსაყოფად, როდესაც საქმე გვაქვს ქსელური პრობლემებითა ან ხელახალი ცდებით გამოწვეულ დუბლირებულ მოთხოვნებთან. ### Path პარამეტრები - `parent_order_id` — string, required შეკვეთის იდენტიფიკატორი, რომელზეც მოხდა ბარათის დამახსოვრება თანხის ავტომატური ჩამოჭრისთვის. ### Body-ს პარამეტრები - `callback_url` — string ბიზნესის ვებმისამართი, რომელსაც ავტომატურად გამოიძახებს ბანკი, ოპერაციის დასრულების შემდეგ, მისთვის გადახდის მონაცემების მიწოდების მიზნით (Callback-ის დროს). არ გადმოცემის შემთხვევაში, გამოიყენება `parent_order_id`-ის შესაბამისი შეკვეთის შექმნისას გადმოცემული მნიშვნელობა. - `external_order_id` — string გადახდის იდენტიფიკატორი ბიზნესის სისტემიდან (მაგალითად: შესყიდვების კალათის იდენტიფიკატორი). არ გადმოცემის შემთხვევაში, გამოიყენება `parent_order_id`-ის შესაბამისი შეკვეთის შექმნისას გადმოცემული მნიშვნელობა. :::note რაც შეეხება დანარჩენ პარამეტრებს (თანხა, ვალუტა, მყიდველის ინფორმაცია და სხვ.), რომლებიც საჭიროა შეკვეთის მოთხოვნისთვის, სისტემა ავტომატურად გამოიყენებს parent_order_id-ის შესაბამისი შეკვეთის შექმნისას გადმოცემულ მნიშვნელობებს. ::: **CURL** ```bash curl -X POST 'https://api-sandbox.bog.ge/payments/v1/ecommerce/orders/:parent_order_id/subscribe' \ -H 'Authorization: Bearer ' \ -H 'Content-Type: application/json' ``` ### Response - `id` — string ონლაინ გადახდის იდენტიფიკატორი. - `_links` — object ვებრესურსის მისამართები, რომლებიც გადახდის პროცესის შემდგომ ეტაპებზე გამოიყენება. - `_links.details.href` — string გადახდის დეტალების მისამართი, რომლის გამოძახებითაც შეგიძლიათ, გაიგოთ ინფორმაცია ონლაინ გადახდის შესახებ. **RESPONSE** ```json { "id": "{order_id}", "_links": { "details": { "href": "https://api-sandbox.bog.ge/payments/v1/receipt/{order_id}" } } } ``` --- # შესავალი Source: https://api.bog.ge/docs/sandbox/payments/preauthorization/introduction მეთოდები საშუალებას გაძლევთ, დაასრულოთ [შეკვეთის მოთხოვნისას](https://api.bog.ge/docs/payments/standard-process/create-order) დაბლოკილი თანხის ჩამოჭრის პროცესი. მეთოდი აქტუალურია, მაშინ, როდესაც, შეკვეთის მოთხოვნისას, `capture` ველის მნიშვნელობა იყო `"manual"`. გადახდის დასრულებას აქვს სამი მეთოდი: თანხის სრული დადასტურება, ნაწილობრივი დადასტურება და უარყოფა. [პრეავტორიზაციის დადასტურება](https://api.bog.ge/docs/payments/preauthorization/approve) [პრეავტორიზაციის უარყოფა](https://api.bog.ge/docs/payments/preauthorization/reject) --- # პრეავტორიზაციის დადასტურება Source: https://api.bog.ge/docs/sandbox/payments/preauthorization/approve დადასტურების სერვისი მოიცავს თანხის, როგორც სრულ, ისე ნაწილოვრივ დადასტურებას. ### Header-ის პარამეტრები - `Content-Type` — application/json, required - `Authorization` — Basic , required გადაეცემა `Bearer ` მნიშვნელობა, სადაც `jwt_token` არის აუტენტიფიკაციის მეთოდის `Response-ის access_token` პარამეტრში დაბრუნებული მნიშვნელობა. - `Idempotency-Key` — UUID v4 Idempotency-Key პარამეტრი უნდა იყოს უნიკალური ყველა ახალი API რექვესთისთვის. იმავე API-ზე Idempotency-Key-ის განმეორებით გამოყენებისას სერვერი დააბრუნებს იმავე სტატუს კოდსა და body-ს, რაც თავდაპირველი მოთხოვნისას. ეს ფუნქცია განსაკუთრებით სასარგებლოა თანმიმდევრული შედეგის უზრუნველსაყოფად, როდესაც საქმე გვაქვს ქსელური პრობლემებითა ან ხელახალი ცდებით გამოწვეულ დუბლირებულ მოთხოვნებთან. ### Path პარამეტრები - `order_id` — string, required შეკვეთის იდენტიფიკატორი, რომელიც ონლაინ მაღაზიას უბრუნდება შეკვეთის მოთხოვნის Response-ში. ### Body-ს პარამეტრები - `amount` — number დადასტურების ტიპის განმსაზღვრელი პარამეტრი. ზუსტი თანხის გამოგზავნის შემთხვევაშიც სრული დადასტურება ხდება, ხოლო ნაწილობრივ თანხის დროს ამ თანხაზე დადასტურდება. თუ სერვისის არ გადაეცემა `amount`, ამ შემთხვევაში დადასტურება მოხდება მთლიან თანხაზე. - `description` — string დადასტურების მიზეზი. **CURL** ```bash curl -X POST 'https://api-sandbox.bog.ge/payments/v1/payment/authorization/approve/:order_id' \ -H 'Authorization: Bearer ' \ -H 'Content-Type: application/json' \ --data-raw '{ "amount": "10.5", "description": "string" }' ``` ### Response - `key` — string API მოთხოვნის სტატუსის იდენტიფიკატორი. - `message` — string API მოთხოვნის სტატუსის აღწერა. - `action_id` — string ქმედების იდენტიფიკატორი. **RESPONSE** ```json { "key": "request_received", "message": "Pre-authorization payment approval request received", "action_id": "e786283f-dc7f-48ba-bb75-12857f5a43ad" } ``` --- # პრეავტორიზაციის უარყოფა Source: https://api.bog.ge/docs/sandbox/payments/preauthorization/reject სრული თანხის უარყოფის მეთოდი ### Header-ის პარამეტრები - `Content-Type` — application/json, required - `Authorization` — Basic , required გადაეცემა `Bearer ` მნიშვნელობა, სადაც `jwt_token` არის აუტენტიფიკაციის მეთოდის `Response-ის access_token` პარამეტრში დაბრუნებული მნიშვნელობა. - `Idempotency-Key` — UUID v4 Idempotency-Key პარამეტრი უნდა იყოს უნიკალური ყველა ახალი API რექვესთისთვის. იმავე API-ზე Idempotency-Key-ის განმეორებით გამოყენებისას სერვერი დააბრუნებს იმავე სტატუს კოდსა და body-ს, რაც თავდაპირველი მოთხოვნისას. ეს ფუნქცია განსაკუთრებით სასარგებლოა თანმიმდევრული შედეგის უზრუნველსაყოფად, როდესაც საქმე გვაქვს ქსელური პრობლემებითა ან ხელახალი ცდებით გამოწვეულ დუბლირებულ მოთხოვნებთან. ### Path პარამეტრები - `order_id` — string, required შეკვეთის იდენტიფიკატორი, რომელიც ონლაინ მაღაზიას უბრუნდება შეკვეთის მოთხოვნის Response-ში. ### Body-ს პარამეტრები - `description` — string უარყოფის მიზეზი. **CURL** ```bash curl -X POST 'https://api-sandbox.bog.ge/payments/v1/payment/authorization/cancel/:order_id' \ -H 'Authorization: Bearer ' \ -H 'Content-Type: application/json' \ --data-raw '{ "description": "string" }' ``` ### Response - `key` — string API მოთხოვნის სტატუსის იდენტიფიკატორი. - `message` — string API მოთხოვნის სტატუსის აღწერა. - `action_id` — string ქმედების იდენტიფიკატორი. **RESPONSE** ```json { "key": "request_received", "message": "Pre-authorization payment cancellation request received", "action_id": "aa9478c7-f82f-45a9-8a30-e7b4275b1224" } ``` --- # თანხის დაბრუნება Source: https://api.bog.ge/docs/sandbox/payments/refund ამ მეთოდის საშუალებით ბიზნესს შეუძლია სრულად ან ნაწილობრივ დააბრუნოს შეკვეთისას გადახდილი თანხა. ბარათით, Apple Pay-ით, Google Pay-ით, BOG ავტორიზაციითა და ქულებით შესრულებული გადახდების უკან დაბრუნება შესაძლებელია როგორც სრულად, ისე ნაწილობრივ. ნაწილობრივი დაბრუნების მეთოდის გამოძახება დასაშვებია მანამ, სანამ გადახდილი თანხა სრულად არ დაბრუნდება. ### Header-ის პარამეტრები - `Content-Type` — application/json, required - `Authorization` — Basic , required გადაეცემა `Bearer ` მნიშვნელობა, სადაც `jwt_token` არის აუტენტიფიკაციის მეთოდის Response-ის access_token პარამეტრში დაბრუნებული მნიშვნელობა. - `Idempotency-Key` — UUID v4 Idempotency-Key პარამეტრი უნდა იყოს უნიკალური ყველა ახალი API რექვესთისთვის. იმავე API-ზე Idempotency-Key-ის განმეორებით გამოყენებისას სერვერი დააბრუნებს იმავე სტატუს კოდსა და body-ს, რაც თავდაპირველი მოთხოვნისას. ეს ფუნქცია განსაკუთრებით სასარგებლოა თანმიმდევრული შედეგის უზრუნველსაყოფად, როდესაც საქმე გვაქვს ქსელური პრობლემებითა ან ხელახალი ცდებით გამოწვეულ დუბლირებულ მოთხოვნებთან. ### Path პარამეტრები - `order_id` — string, required შეკვეთის იდენტიფიკატორი, რომელიც ონლაინ მაღაზიას უბრუნდება შეკვეთის მოთხოვნის Response-ში. ### Body-ს პარამეტრები - `amount` — number დასაბრუნებელი თანხა. გადმოცემა აუცილებელია, თუ თანხა ბრუნდება ნაწილობრივად. პარამეტრის არ გადმოცემის შემთხვევაში, თანხა სრულად დაბრუნდება. მნიშვნელობა არ შეიძლება იყოს დამუშავებულ თანხაზე (transfer_amount) მეტი. **CURL** ```bash curl -X POST 'https://api-sandbox.bog.ge/payments/v1/payment/refund/:order_id' \ -H 'Authorization: Bearer ' \ -H 'Content-Type: application/json' \ --data-raw '{ "amount": "10.5" }' ``` ### Response - `key` — string API მოთხოვნის სტატუსის იდენტიფიკატორი. - `message` — string API მოთხოვნის სტატუსის აღწერა. - `action_id` — string ქმედების იდენტიფიკატორი. **RESPONSE** ```json { "key": "request_received", "message": "Refund request received", "action_id": "5b666901-eb05-4f83-abeb-8311e175f337" } ``` --- # სატესტო ბარათები Source: https://api.bog.ge/docs/sandbox/payments/test-cards :::caution note აქ ჩამოთვლილი სატესტო ბარათები მოქმედებს მხოლოდ Sandbox გარემოში. ისინი საშუალებას გაძლევთ, გააკეთოთ წარმატებული და უარყოფილი გადახდის სცენარების სიმულირება. აღნიშნული ბარათის მონაცემები არ მუშაობს Live გარემოში და წარმოადგენს მხოლოდ სიმულირებულ ქცევას. ::: :::info ბარათის ვადის გასვლის თარიღში და CVV კოდში გამოიყენეთ ნებისმიერი რიცხვი ::: ### VISA ბარათები | ბარათის ნომერი | სტანდარტული შეკვეთა და გადახდა | დაბრუნება | პრეავტორიზაცია (დასრულება) | ავტომატური გადახდა (Subscription) | განმეორებადი გადახდა | აღწერა | |---|---|---|---|---|---|---| | | გადახდა წარმატებულია | დაბრუნება წარმატებულია | პრეავტორიზაცია დადასტურებულია | გადახდა წარმატებულია | გადახდა წარმატებულია | VISA სატესტო ბარათი ყველა წარმატებული ოპერაციისთვის | | | გადახდა უარყოფილია (არასაკმარისი თანხა) | – | – | – | – | VISA სატესტო ბარათი უარყოფილი გადახდის სიმულაციისთვის | | | გადახდა წარმატებულია | დაბრუნება უარყოფილია | პრეავტორიზაცია უარყოფილია | გადახდა უარყოფილია (ავთენტიკაცია უარყოფილია) | გადახდა უარყოფილია (ავთენტიკაცია უარყოფილია) | VISA სატესტო ბარათი წარმატებული გადახდისა და ბარათის შენახვისთვის, შემდგომ უარყოფილი ოპერაციებით | ### Mastercard ბარათები | ბარათის ნომერი | სტანდარტული შეკვეთა და გადახდა | დაბრუნება | პრეავტორიზაცია (დასრულება) | ავტომატური გადახდა (Subscription) | განმეორებადი გადახდა | აღწერა | |---|---|---|---|---|---|---| | | გადახდა წარმატებულია | დაბრუნება წარმატებულია | პრეავტორიზაცია დადასტურებულია | გადახდა წარმატებულია | გადახდა წარმატებულია | Mastercard სატესტო ბარათი ყველა წარმატებული ოპერაციისთვის | | | გადახდა უარყოფილია (არასაკმარისი თანხა) | – | – | – | – | Mastercard სატესტო ბარათი უარყოფილი გადახდის სიმულაციისთვის | | | გადახდა წარმატებულია | დაბრუნება უარყოფილია | პრეავტორიზაცია უარყოფილია | გადახდა უარყოფილია (ავთენტიკაცია უარყოფილია) | გადახდა უარყოფილია (ავთენტიკაცია უარყოფილია) | Mastercard სატესტო ბარათი წარმატებული გადახდისა და ბარათის შენახვისთვის, შემდგომ უარყოფილი ოპერაციებით | ### American Express (AMEX) ბარათები | ბარათის ნომერი | სტანდარტული შეკვეთა და გადახდა | დაბრუნება | პრეავტორიზაცია (დასრულება) | ავტომატური გადახდა (Subscription) | განმეორებადი გადახდა | აღწერა | |---|---|---|---|---|---|---| | | გადახდა წარმატებულია | დაბრუნება წარმატებულია | პრეავტორიზაცია დადასტურებულია | გადახდა წარმატებულია | გადახდა წარმატებულია | AMEX სატესტო ბარათი ყველა წარმატებული ოპერაციისთვის | | | გადახდა უარყოფილია (არასაკმარისი თანხა) | – | – | – | – | AMEX სატესტო ბარათი უარყოფილი გადახდის სიმულაციისთვის | | | გადახდა წარმატებულია | დაბრუნება უარყოფილია | პრეავტორიზაცია უარყოფილია | გადახდა უარყოფილია (ავთენტიკაცია უარყოფილია) | გადახდა უარყოფილია (ავთენტიკაცია უარყოფილია) | AMEX სატესტო ბარათი წარმატებული გადახდისა და ბარათის შენახვისთვის, შემდგომ უარყოფილი ოპერაციებით | --- # Response კოდები Source: https://api.bog.ge/docs/sandbox/payments/response-codes ## გადახდის Response კოდები | Code | აღწერა (EN) | აღწერა (GE) | |------|----------------------------------------------------------------------------------|----------------------------------------------------------------| | 100 | Successful payment | წარმატებული გადახდა | | 101 | Payment declined because card usage is limited. For detailed information, contact the card issuer bank | გადახდა უარყოფილია, რადგან ბარათის გამოყენება შეზღუდულია. დეტალური ინფორმაციისთვის დაუკავშირდით ბარათის მომსახურე ბანკს | | 102 | Saved card wasn't found | დამახსოვრებული ბარათი ვერ მოიძებნა | | 103 | Payment declined due to invalid card | გადახდა უარყოფილია, რადგან ბარათი არ არის ვალიდური | | 104 | Payment declined due to exceeding transaction limit | გადახდა უარყოფილია ტრანზაქციის რაოდენობის ლიმიტის გადაჭარბების გამო | | 105 | Payment declined because the card has expired | გადახდა უარყოფილია, რადგან ბარათი ვადაგასულია | | 106 | Payment declined due to exceeding the limit of the amount | გადახდა უარყოფილია თანხის ლიმიტის გადაჭარბების გამო | | 107 | Payment declined due to insufficient funds in the account | გადახდა უარყოფილია ანგარიშზე არასაკმარისი თანხის გამო | | 108 | Authentication Declined | გადახდის ავტორიზაციის უარყოფა | | 109 | Technical Issue | დაფიქსირდა ტექნიკური ხარვეზი | | 110 | Transaction Expired | ოპერაციის შესრულების დრო ამოიწურა | | 111 | Authentication timeout | გადახდის ავტორიზაციის დრო ამოიწურა | | 112 | General Error | საერთო შეცდომა | | 122 | Payment declined by the acquirer bank | გადახდა უარყოფილია მომსახურე ბანკის მიერ | | 199 | Unknown Response | უცნობი პასუხი | | 200 | Successful preauthorization | წარმატებული პრეავტორიზაცია | ## მოქმედების Response კოდები | Code | აღწერა (GE) | აღწერა (EN) | |------|----------------------------------------------------------------------------------|----------------------------------------------------------------| | 161 | თანხის დაბრუნება ვერ მოხერხდა. მეტი დეტალისთვის დაუკავშირდით ბარათის გამცემ ბანკს. | Refund could not be completed. Please contact the card issuing bank for more details. | | 162 | ბარათის გამცემი ბანკი უარყოფს თანხის დაბრუნებას. | The card issuing bank declined the refund. | | 163 | ანგარიშზე არ გაქვთ საკმარისი ნაშთი. | Not enough funds available in the account | | 164 | თანხის დაბრუნება ვერ მოხერხდა. მეტი დეტალისთვის დაუკავშირდით ბარათის გამცემ ბანკს. | Refund could not be completed. Please contact the card issuing bank for more details. | | 165 | თანხის დაბრუნება ვერ მოხერხდა. მეტი დეტალისთვის დაუკავშირდით ბარათის გამცემ ბანკს. | Refund could not be completed. Please contact the card issuing bank for more details. | | 166 | თანხის დაბრუნება ვერ მოხერხდა. მეტი დეტალისთვის დაუკავშირდით ბარათის გამცემ ბანკს. | Refund could not be completed. Please contact the card issuing bank for more details. | | 167 | ბარათი ვადაგასულია. დაუკავშირდით მომხმარებელს და დაუბრუნეთ თანხა აქტიურ ბარათზე. | Card expired. Contact the customer and refund the amount to an active card. | | 168 | თანხის დაბრუნება ვერ მოხერხდა. მეტი დეტალისთვის დაუკავშირდით ბარათის გამცემ ბანკს. | Refund could not be completed. Please contact the card issuing bank for more details. | | 169 | ბარათი ვადაგასულია ან მონაცემები არასწორია. გადაამოწმეთ ინფორმაცია მომხმარებელთან და თავიდან ცადეთ. | The card is expired or the details are incorrect. Please verify the information with the customer and try again. | | 179 | Unknown Response | Unknown Response | --- # გამოყენებული ტერმინები Source: https://api.bog.ge/docs/sandbox/payments/terms-used 1. ბიზნესი - საცალო ვაჭრობის ან მომსახურების კომპანია, რომელსაც გააჩნია ონლაინ/ელექტრონული სისტემა. 2. ონლაინ გადახდების გვერდი - ონლაინ გადახდების სისტემა, რომელიც საშუალებას გაძლევთ, მარტივად ჩააშენოთ გადახდების მოდული ნებისმიერი ტიპის ბიზნესში. 3. Callback - საბანკო სისტემიდან ბიზნესის მიერ გამოდგმული სერვისის გამოძახება, გადახდის შესახებ განახლებული ინფორმაციის მიწოდების მიზნით. 4. სისტემაში შესასვლელი რეკვიზიტები - ბანკის სისტემაში კლიენტის იდენტიფიკატორი (client_id) და საიდუმლო გასაღები (secret_key), რომელსაც ბანკი ანიჭებს კლიენტს, მისი ბიზნესად წარმატებით დარეგისტრირების შემდეგ. 5. ბარათის ნომერი (PAN) - პლასტიკური ბარათის წინა მხარეს გამოსახული 16 ციფრი. --- # შესავალი Source: https://api.bog.ge/docs/sandbox/paymentgateway/introduction :::caution NOTICE დოკუმენტი განკუთვნილია სერვის-პროვაიდერებისათვის. ::: ## რა არის Payment Gateway? Payment Gateway არის ონლაინ სერვისი, რომელიც საშუალებას აძლევს ბიზნესს და ინდივიდებს მიიღონ გადახდები მომხმარებლებისგან მათი ვებსაიტების ან მობილური აპლიკაციების საშუალებით. ## მიზანი დოკუმენტი შეიცავს ინფორმაციას კომუნიკაციის მეთოდების, ხელმისაწვდომი ოპერაციების, გაცვლის ფორმატების, ავთენტიფიკაციის, წინასწარ განსაზღვრულ პარამეტრებსა და სტატუსის კოდებზე და ა.შ.. ## პროტოკოლის აღწერა დოკუმენტი აღწერს სისტემას, რომელშიც მომხმარებელი ურთიერთქმედებს სერვის-პროვაიდერთან ინტერფეისის საშუალებით. უფრო კონკრეტულად, მომხმარებელს შეუძლია საქართველოს ბანკის სერვერის მეშვეობით გააგზავნოს ვებ-მოთხოვნა სერვის-პროვაიდერთან, რაზეც ამ უკანასკნელს პასუხის გაცემის ვალდებულება ეკისრება. ხოლო მიღებული პასუხი დამუშავდება BOG-ის მიერ და გამოჩნდება მომხმარებლისთვის შესაბამის ადგილას. მომხმარებელს შეუძლია განახორციელოს ოპერაციების თვითნებური რაოდენობა. გარდა ამისა, ზოგიერთი გადახდის არხი შეზღუდავს ამ რიცხვს ორი ოპერაციით (ინფორმაცია ვალისა და/ან გადახდის შესახებ), თუმცა ამის გვერდის ავლა შესაძლებელია სერვისის ინტეგრაციისთვის საჭირო დროის ხარჯზე. პროტოკოლი იმუშავებს ვებ-აპთან ერთად, რომელიც მისცემს სერვის-პროვაიდერებს შესაძლებლობას განსაზღვრონ მრავალი ოპერაცია ერთი გადახდის ნაკადზე ინტერფეისის საშუალებით. ყველა სერვის-პროვაიდერს ექნება შესაძლებლობა განაგოს ისევე როგორც ოპერაციების რაოდენობა, ასევე სერვისის შესაბამასისი მახასიათებლებიც კი. ## მოთხოვნები სერვის-პროვაიდერისადმი სერვისის პროვაიდერს მოეთხოვება შექმნას ვებ-სერვერი, რომელიც შეიძლება იყოს საჯაროდ ხელმისაწვდომი ან მხოლოდ VPN არხის საშუალებით. იმ შემთხვევაში, თუ ვებ სერვერი საჯაროდ ხელმისაწვდომია, საჭიროა, რომ მას ჰქონდეს HTTPS მხარდაჭერა. სერვისის პროვაიდერს უფლება აქვს გამოიყენოს სურვილამებრ შერჩეული ნებისმიერი API endpoint. Მაგალითად. http://serviceprovider:8088/api/mock შესაძლებელია შემდეგი HTTP მეთოდების განსაზღვრა სერვის-პროვაიდერის ოპერაციებზე: GET, POST, PUT, PATCH & DELETE; თუმცა BOG არ გამოიყენებს HTTP მოთხოვნის body-ის წინასწარ შერჩეული ოპერაციებისთვის რაიმე ინფორმაციის გადასაცემად, მიუხედავად სერვისის პროვაიდერის მიერ არჩეული HTTP მეთოდისა. --- # ავთენტიფიკაცია Source: https://api.bog.ge/docs/sandbox/paymentgateway/authentication ## რას გულისხმობს ავთენტიფიკაცია? სექცია განსაზღვრავს ავთენტიფიკაციის სხვადასხვა მეთოდებს, რომლებიც მხარდაჭერილია BOG პროტოკოლის მიერ. სავალდებულოა, რომ სერვისის პროვაიდერმა გამოიყენოს აქ ჩამოთვლილი ავთენტიფიკაციის ერთ-ერთი მეთოდი. უფრო მეტიც, უსაფრთხოების გაზრდის მიზნით რეკომენდირებულია ავთენტიფიკაციის რამდენიმე მეთოდის ერთდროულად გამოყენება. ## რისკები წინამდებარე დოკუმენტი არ ისახავს მიზნად გადახდის სისტემის მონაწილეებზე დაკისრებული რისკების შეფასებას ელექტრონულ გადახდებთან და შესაბამის პასუხისმგებლობებთან დაკავშირებით. დოკუმენტი აღწერს უსაფრთხოების რეჟიმებს, რომლებიც გამოიყენება გადახდის სისტემის დასაცავად. ## მხარდაჭერილი მეთოდები - [HTTP Basic](https://api.bog.ge/docs/paymentgateway/auth-methods/basic) - [OAuth 2.0 - Client Credentials](https://api.bog.ge/docs/paymentgateway/auth-methods/oauth2) - [API Key](https://api.bog.ge/docs/paymentgateway/auth-methods/apikey) - [HMAC-SHA256](https://api.bog.ge/docs/paymentgateway/auth-methods/hmac-sha256) --- # HTTP Basic Source: https://api.bog.ge/docs/sandbox/paymentgateway/auth-methods/basic თუ სერვისის პროვაიდერი გადაწყვეტს [HTTP Basic Auth](https://datatracker.ietf.org/doc/html/rfc7235)-ის ავთენტიფიკაციის მეთოდის გამოყენებას, მაშინ მან უნდა მიიღოს Authorization header-ი, რომლის მნიშვნელობაც იყენებს ძირითადი ავტორიზაციის ფორმატს. ### Header-ის პარამეტრები - `Authorization` — Basic , required გადაეცემა „Basic „ + „:“ მნიშვნელობა კოდირებული Base64 ფორმატში (მაგ: `Basic ODI4Mjo3Njk3MDY0OTlmMDcwOWUyMzQ4NDU4NjNmOThiMjMxNA==`), სადაც და არის სერვის-პროვაიდერის მიერ ბანკინსთვის გადაცემული, სისტემაში შესვლისთვის საჭირო, რეკვიზიტები. --- # OAuth 2.0 - Client Credentials Source: https://api.bog.ge/docs/sandbox/paymentgateway/auth-methods/oauth2 სერვისის პროვაიდერს შეუძლია შექმნას ავტორიზაციის ვებ-სერვისი, რომელიც მხარს უჭერს OAuth 2.0 ([D. Hardt, Ed., 2012](https://datatracker.ietf.org/doc/html/rfc6749)) Client Credentials-ის გრანტის ტიპს. ბანკი სერვის-პროვაიდერთან კომუნიკაციისთვის გამოიყენებს HTTP POST მეთოდს შემდეგი ფორმატით: ### Header-ის პარამეტრები - `Content-Type` — application/x-www-form-urlencoded, required ### Body-ს პარამეტრები - `grant_type` — client_credentials, required მნიშვნელობად გადაეცემა ფიქსირებული ტექსტი: `client_credentials` - `client_id` — <client_id>, required - `client_secret` — <client_secret>, required **CURL** ```bash curl --location --request POST 'http://localhost:8080/ess-api/authenticate' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'grant_type=client_credentials' \ --data-urlencode 'client_id=client_id' \ --data-urlencode 'client_secret=client_secret' ``` ### Response სერვის-პროვაიდერმა უნდა დააბრუნოს შემდეგი JSON პასუხი: - `access_token` — string ავტორიზაციის სერვერის მიერ დაბრუნებული Token-ის მნიშვნელობა - `created_at` — string UNIX დროის შტამპი – მილიწამების რაოდენობა, რაც გავიდა 1970 წლის 1 იანვრიდან დღემდე UTC-ის დროის სარტყელით. - `expires_in` — number აბრუნებს რიცხვით მნიშვნელობას, თუ რამდენი წამის განმავლობაში არის აქტიური Token. - `token_type` — number Token-ის ტიპი (ბრუნდება ტექსტური მნიშვნელობა - `Bearer`). **RESPONSE** ```json { "access_token": "xx82194x21412xxx219124x678x888x2xxx1900xx", "created_at": 1693236686855, "expires_in": 300, "token_type": "Bearer" } ``` ამ უკანასკნელი სერვერის არსებობის შემთხვევაში, საქართველოს ბანკი ყოველი ოპერაციის გამოძახების დროს სერვის-პროვაიდერს გადასცემს შემდეგ Header-ის მნიშვნელობას: - `Authorization` — Bearer , required გადაეცემა „Bearer „ + „<token>“ (მაგ: „Bearer xx82194x21412xxx219124x678x888x2xxx1900xx“), სადაც `token` არის სერვის-პროვიადერის ავტორიზაციის სერვერის მიერ დაბრუნებული პარამეტრი. --- # API Key Source: https://api.bog.ge/docs/sandbox/paymentgateway/auth-methods/apikey სერვის-პროვაიდერს შეუძლია ბანკს მიაწოდოს API გასაღები, რომელიც გამოყენებული იქნება თითოეული ოპერაციის ფარგლებში. თუ გასაღები მოცემულია, მაშინ BOG თითოეულ ოპერაციას გამოაყოლებს HTTP Header-ს: - `Auth-Key` — , required `API_KEY` არის სერვის-პროვაიდერის მიერ მოცემული გასაღები. --- # HMAC-SHA256 Source: https://api.bog.ge/docs/sandbox/paymentgateway/auth-methods/hmac-sha256 სერვისის პროვაიდერს შეუძლია დამატებით მიაწოდოს BOG-ს ჰეშინგის საიდუმლო გასაღები, რომელიც გამოყენებული იქნება HTTP Request Body-ის ჰეშირებისთვის HTTP POST & PATCH მეთოდებისთვის, ხოლო HTTP GET, PUT & DELETE მოთხოვნების შემთხვევაში – Query-ის ჰეშირებისთვის. თუ ზემოაღნიშნული პარამეტრი მოწოდებულია, სერვის-პროვაიდერმა უნდა მიიღოს HTTP header: `Hash` და გადაამოწმოს იგი. ჰეშირებისთვის გამოყენებული იქნება HMAC-SHA256 ალგორითმი, სადაც HMAC-SHA256 ეხება ჰეშზე დაფუძნებულ შეტყობინებების ავთენტიფიკაციის კოდს ([Krawczyk, Bellare, Canetti, 1997](https://www.ietf.org/rfc/rfc2104.txt)) დაშიფვრის მეთოდს საიდუმლო გასაღებთან და კრიპტოგრაფიულ ფუნქციასთან ერთად- SHA256 ([Eastlake, E. Huawei, Hansen, 2011](https://datatracker.ietf.org/doc/html/rfc6234)). გარდა ამისა, ჰეშის კოდი შეიცავს მხოლოდ დიდ ასოებს და ციფრებს, თექვსმეტობით ფორმატში. - `Hash` — , required `HASH` არის HTTP Request Body-ის ან Query-ის დაჰეშილი მნიშვნელობა. მაგალითად, თუ სერვის-პროვაიდერის მიერ მოწოდებული საიდუმლო გასაღებია: `8bbe50a7d61af79211148c09e40e1bffaefdf319dce665bc5a31b55ec28a508b` და თუ HTTP GET მოთხოვნა არის ფორმის: `http://serviceprovider:8088/api/mock/get-categories?personalNumber=01234567890&birthDate=11.01.2002` მაშინ მისი შესაბამისი კრიპტოგრაფიული მესიჯი იქნება მისი Query (რადგან GET მოთხოვნაა): `personalNumber=01234567890&birthDate=11.01.2002` რომელიც მოგვცემს შემდეგ `HASH`-ის მნიშვნელობას: `841A782048F51A798331E4A534A240911D541B869CB0E2CF1BB58F086873C079` --- # არჩევითი ოპერაციები Source: https://api.bog.ge/docs/sandbox/paymentgateway/operations :::caution NOTICE მორგებული ოპერაციები არჩევითია. ე.ი. სერვის-პროვაიდერმა შეიძლება საერთოდ არ განსაზღვროს რაიმე ოპერაცია. ::: ## ცვლადების სავალდებულო სტანდარტები კომპანიის მასშტაბით სტანდარტების შესანარჩუნებლად, BOG მოითხოვს, რომ სერვის-პროვაიდერებმა გამოიყენონ კონკრეტული ცვლადის სახელები, რომლებიც შეესაბამება მათ მნიშვნელობებს. Მაგალითად. თუ მომხმარებელი იყენებს თავის პირად ნომერს სერვის-პროვაიდერისგან გარკვეული ინფორმაციის მისაღებად (მაგ. დავალიანება), მაშინ ამ უკანასკნელმა უნდა გამოიყენოს personalNumber, როგორც API-ს მიერ მოთხოვნილი ცვლადის სახელი. იხილეთ სავალდებულო ცვლადების სტანდარტების სრული სია ქვემოთ: - **personalNumber** – გამოიყენება როგორც პირადი ნომრის იდენტიფიკატორი. - **customerId** – გამოიყენება როგორც მომხმარებლის იდენტიფიკატორი. - **debt** – მომხმარებელმა მომსახურების მიმწოდებლის მიმართ მცირე ერთეულებით დავალიანება. - **debtList** – მონაცემთა მოდელების სია, რომელიც შეიცავს კლიენტის მიერ მომსახურების მიმწოდებლისადმი კუთვნილ თანხებს (და შესაძლოა სხვა ველებს) მცირე ერთეულებში. - **amount** – თანხა, რომელიც მომხმარებელს სურს გადაიხადოს მცირე ერთეულებით. ## მონაცემთა გაცვლის ფორმატი ყველა მორგებული ოპერაცია, რომელიც დაუკავშირდება სერვის-პროვაიდერის API-ს, გაგზავნის ყველა მოთხოვნის პარამეტრს, როგორც HTTP Query პარამეტრებს, ასევე HTTP Header-ის მნიშვნელობებს, რომლებიც გამოიყენება ავტორიზაციისთვის. სერვის-პროვაიდერმა კი, თითოეულ ოპერაციას უნდა უპასუხოს წინასწარ განსაზღვრული ფორმატით: - `status.code` — number წინასწარ განსაზღვრული სტატუსის [კოდი](https://api.bog.ge/docs/paymentgateway/error-codes). - `status.value` — string სტატუსის მნიშვნელობა (სურვილისამებრ). - `timestamp` — number UNIX დროის შტამპი – მილიწამების რაოდენობა, რაც გავიდა 1970 წლის 1 იანვრიდან დღემდე UTC-ის დროის სარტყელით. - `receiptId` — string receiptId არის გადახდის უნიკალური იდენტიფიკატორი, რომელიც დაბრუნდა სერვის-პროვაიდერისგან წარმატებული გადახდის ოპერაციის შემდეგ. - `response` — object JSON მონაცემები - დაბრუნებული ნებისმიერი თვითნებური ოპერაციიდან. ველი სავალდებულოა ყოველი ოპერაციისთვის. **RESPONSE** ```json { "status":{ "code":0, "value":"OK" }, "timestamp":1693236686855, "receiptId":"", "response":{"wrapper":{"categoryCodes":["A1","B"]}} } ``` :::note სერვის-პროვაიდერის მიერ შექმნილ ოპერაციებთან ერთად, ასევე არსებობს BOG-ის მიერ წინასწარ განსაზღვრული ოპერაციები, რომელთაგან საჭიროა მხოლოდ [გადახდის](https://api.bog.ge/docs/paymentgateway/pre-defined-ops/payment) ოპერაცია, ყველა დანარჩენი არასავალდებულოა. ::: --- # გადახდა Source: https://api.bog.ge/docs/sandbox/paymentgateway/pre-defined-ops/payment ოპერაციების ნებისმიერი რაოდენობა შეიძლება განისაზღვროს სერვის-პროვაიდერის მიერ, თუმცა გადახდის ოპერაცია ყოველთვის შესრულდება საოპერაციო ჯაჭვის ბოლოს, თუ კი მომხმარებელი გადაწყვეტს გადახდას. შესაბამისად, სერვის-პროვაიდერი ვალდებულია უზრუნველყოს გადახდის ოპერაციის იმპლემენტაცია. ### Body-ს პარამეტრები - `transactionId` — string, required ბანკის მიერ შექმნილი ტრანზაქციის უნიკალური იდენტიფიკატორი. - `amount` — number, required თანხა მცირე ერთეულებში (თეთრი, ცენტი, და ა.შ.). - `currency` — string, required ვალუტა ([ISO 4217 currency code](https://www.iban.com/currency-codes)), მაგალითად `GEL`. - `parameters` — object, required პარამეტრების ობიექტი, რომლის თითოეული ელემენტი მოიცავს `key` & `value` წყვილს, სადაც `key` არის პარამეტრის დასახელება, ხოლო `value` - მნიშვნელობა. **REQUEST BODY** ```json { "transactionId": "00000000", "amount": 500000, "currency": "GEL", "parameters": { "personalNumber": "01234567890", "birthDate": "11.01.2002" } } ``` ### Response სერვის-პროვაიდერმა უნდა დააბრუნოს შემდეგი JSON პასუხი: - `status.code` — number წინასწარ განსაზღვრული სტატუსის [კოდი](https://api.bog.ge/docs/paymentgateway/error-codes). - `status.value` — string სტატუსის მნიშვნელობა (სურვილისამებრ). - `timestamp` — number UNIX დროის შტამპი – მილიწამების რაოდენობა, რაც გავიდა 1970 წლის 1 იანვრიდან დღემდე UTC-ის დროის სარტყელით. - `receiptId` — string receiptId არის გადახდის უნიკალური იდენტიფიკატორი, რომელიც დაბრუნდა სერვის-პროვაიდერისგან წარმატებული გადახდის ოპერაციის შემდეგ. **RESPONSE** ```json { "status":{ "code":0, "value":"OK" }, "timestamp":1693236686855, "receiptId":"1234" } ``` --- # ტრანზაქციის სტატუსი Source: https://api.bog.ge/docs/sandbox/paymentgateway/pre-defined-ops/payment-status როდესაც გადახდის სტატუსის ოპერაცია გამოძახებულია BOG-ის მიერ, მოსალოდნელია, რომ სერვის-პროვაიდერი უპასუხებს ჩამოთვლილთაგან ერთ-ერთი სტატუსის კოდით: [12, 13, 14](https://api.bog.ge/docs/paymentgateway/error-codes). ### Body-ს პარამეტრები - `transactionId` — string, required ბანკის მიერ შექმნილი ტრანზაქციის უნიკალური იდენტიფიკატორი. **CURL** ```bash curl --location --request GET 'http://serviceprovider:8088/api/mock/payment-status?transactionId=00000000' ``` ### Response სერვის-პროვაიდერმა უნდა დააბრუნოს შემდეგი JSON პასუხი: - `status.code` — number წინასწარ განსაზღვრული სტატუსის [კოდი](https://api.bog.ge/docs/paymentgateway/error-codes) ავტორიზაციის სერვერის მიერ დაბრუნებული Token-ის მნიშვნელობა - `status.value` — string სტატუსის მნიშვნელობა (სურვილისამებრ) - `timestamp` — number UNIX დროის შტამპი – მილიწამების რაოდენობა, რაც გავიდა 1970 წლის 1 იანვრიდან დღემდე UTC-ის დროის სარტყელით. **RESPONSE** ```json { "status":{ "code":12, "value":"Transaction was successful" }, "timestamp":1693236686855 } ``` --- # ტრანზაქციის გაუქმება Source: https://api.bog.ge/docs/sandbox/paymentgateway/pre-defined-ops/cancel-payment ტრანზაქციის გაუქმების ოპერაციის გამოძახებისას, სერვის-პროვაიდერი ვალდებულია გააუქმოს გადახდა BOG-დან მოცემული ტრანზაქციის იდენტიფიკატორით. ### Body-ს პარამეტრები - `transactionId` — string, required ბანკის მიერ შექმნილი ტრანზაქციის უნიკალური იდენტიფიკატორი. **CURL** ```bash curl --location --request GET 'http://serviceprovider:8088/api/mock/cancel-status?transactionId=00000000' ``` ### Response სერვის-პროვაიდერმა უნდა დააბრუნოს შემდეგი JSON პასუხი: - `status.code` — number წინასწარ განსაზღვრული სტატუსის [კოდი](https://api.bog.ge/docs/paymentgateway/error-codes) - `status.value` — string სტატუსის მნიშვნელობა (სურვილისამებრ) - `timestamp` — number UNIX დროის შტამპი – მილიწამების რაოდენობა, რაც გავიდა 1970 წლის 1 იანვრიდან დღემდე UTC-ის დროის სარტყელით. **RESPONSE** ```json { "status":{ "code":0, "value":"OK" }, "timestamp":1693236686855 } ``` --- # გადახდების შესახებ ინფორმაციის მიწოდება Source: https://api.bog.ge/docs/sandbox/paymentgateway/pre-defined-ops/send-payment-info გადახდების შესახებ ინფორმაციის მიწოდების ოპერაცია შესრულდება ერთხელ დღის ბოლოს, სადაც BOG გამოგიგზავნით ინფორმაციას წინა დღეს განხორციელებული წარმატებული გადახდების შესახებ (24 საათის განმავლობაში), UTC+4h (თბილისი) დროის ზონის მიხედვით. ვინაიდან Request Body შეიცავს როგორც შემაჯამებელ, ასევე ინდივიდუალურ ინფორმაციას გადახდების შესახებ, არსებობს რისკი იმისა, რომ Request Body გასცდეს ზომის ლიმიტს. ამის გამო, გაგზავნა-გადახდის-ინფორმაციის ოპერაცია შესრულდება სერიებად, სადაც n-ე პარტიის დროის ინტერვალი იწყება Tn-დან (ჩათვლით), ხოლო n-1 პარტიის დროის ინტერვალი მთავრდება Tn-ზე (ჩაუთვლელად), სადაც Tn-1 < Tn. ე.ი. პარტიები გაიგზავნება შემდგომში 24 საათიანი დროის ქვეჯგუფების საფუძველზე. უფრო მეტიც, მონაცემების თითო პარტიაში გაგზავნის შეუსრულებლობის შემთხვევაში, მხოლოდ ერთხელ მოხდება მოთხოვნის თავიდან მცდელობა. ### Body-ს პარამეტრები - `timezoneId` — string, required [დროის სარტყელის იდენტიფიკატორი.](https://docs.oracle.com/middleware/1221/wcs/tag-ref/MISC/TimeZones.html) - `timespan.from` — number, required (ჩათვლით) UNIX დროის შტამპი – მილიწამების რაოდენობა, რაც გავიდა 1970 წლის 1 იანვრიდან დღემდე UTC-ის დროის სარტყელით. - `timespan.to` — number, required (ჩაუთვლელად) UNIX დროის შტამპი – მილიწამების რაოდენობა, რაც გავიდა 1970 წლის 1 იანვრიდან დღემდე UTC-ის დროის სარტყელით. - `summary[?].totalAmount` — string, required ჯამური თანხა მცირე ერთეულებში (თეთრი, ცენტი, და ა.შ.). - `summary[?].currencyCode` — string, required [ვალუტა](https://www.iban.com/currency-codes) - `summary[?].count` — string, required ტრანზაქციების რაოდენობა. - `paymentList[?].transactionId` — string, required ბანკის მიერ შექმნილი ტრანზაქციის უნიკალური იდენტიფიკატორი. - `paymentList[?].currencyCode` — string, required [ვალუტა](https://www.iban.com/currency-codes) - `paymentList[?].amount` — string, required თანხა მცირე ერთეულებში (თეთრი, ცენტი, და ა.შ.). **REQUEST BODY** ```json { "timezoneId": "Asia/Tbilisi", "timespan": { "from": 1693598400000, "to": 1693684799000 }, "summary": [ { "totalAmount": 5000000, "currency": "GEL", "count": 2 }, { "totalAmount": 100000, "currency": "USD", "count": 1 } ], "paymentList":[ { "transactionId": "00000000", "currencyCode": "GEL", "amount": 2500000 }, { "transactionId": "00000001", "currencyCode": "GEL", "amount": 2500000 }, { "transactionId": "00000002", "currencyCode": "USD", "amount": 100000 } ] } ``` ### Response სერვის-პროვაიდერმა უნდა დააბრუნოს შემდეგი JSON პასუხი: - `status.code` — number წინასწარ განსაზღვრული სტატუსის [კოდი](https://api.bog.ge/docs/paymentgateway/error-codes). - `status.value` — string სტატუსის მნიშვნელობა (სურვილისამებრ). - `timestamp` — number UNIX დროის შტამპი – მილიწამების რაოდენობა, რაც გავიდა 1970 წლის 1 იანვრიდან დღემდე UTC-ის დროის სარტყელით. **RESPONSE** ```json { "status":{ "code":0, "value":"OK" }, "timestamp":1693236686855 } ``` --- # პასუხის მოსალოდნელი დრო Source: https://api.bog.ge/docs/sandbox/paymentgateway/expected-response-times პასუხის მოსალოდნელი დრო, ე.ი. თითოეული ოპერაციისთვის რეაგირების დროის ლიმიტები, მოცემულია ქვემოთ. - **OAuth Client Credentials** – 15 წამი. - **არჩევითი ოპერაციები** – 10 წამი. - **გადახდა** – 30 წამი. - **ტრანზაქციის სტატუსი** – 15 წამი. - **ტრანზაქციის გაუქმება** – 15 წამი. - **გადახდების შესახებ ინფორმაციის მიწოდება** – 60 წამი. თუ სერვის-პროვაიდერი არ დააბრუნებს პასუხს თითოეული ოპერაციისთვის მოცემულ ვადაში, ჩაითვლება, რომ მოთხოვნა წარუმატებელია. --- # გამოყენებული ტერმინები Source: https://api.bog.ge/docs/sandbox/paymentgateway/terms-used ## განმარტებები, აბრევიატურები და აკრონიმები - **BOG** - საქართველოს ბანკი - **სერვის-პროვაიდერი** - კომპანია, რომელიც უზრუნველყოფს მომსახურებას გარკვეული გადახდისთვის და სურს გადაიხადოს BOG გადახდის სისტემის მეშვეობით. - **მომხმარებელი** - პირი, რომელიც იყენებს BOG-ის მომხმარებლის ინტერფეისს სერვის-პროვაიდერთან დასაკავშირებლად, ვალების შესახებ ინფორმაციის მისაღებად, გადახდების განსახორციელებლად და ა.შ. --- # გამონაკლისი შემთხვევები Source: https://api.bog.ge/docs/sandbox/paymentgateway/error-flow შემდეგი მონაკვეთი შეიცავს ინფორმაციას სხვადასხვა მარშრუტებთან დაკავშირებით, რომელიც BOG-ის გადახდის სისტემას შეუძლია აიღოს გადახდის ოპერაციის ფარგლებში მოცემული გარემოებების მიხედვით. გაითვალისწინეთ, რომ BOG-ის მხრიდან სტატუსის „ტრანზაქცია მიმდინარეობს“ ([კოდი 14](https://api.bog.ge/docs/paymentgateway/error-codes)) დამუშავება, შეიძლება შეიცვალოს. ![განახლებული პროტოკოლის შეცდომის მარშრუტი](./media/protocol-error-flow.png) --- # შეცდომის კოდები Source: https://api.bog.ge/docs/sandbox/paymentgateway/error-codes |კოდი | აღწერა | |-----|--------------------------------| |0 |OK| |1 |Access Denied| |2 |Invalid username or password| |3 |Invalid hash code| |4 |Missing parameter| |5 |Invalid parameter| |6 |Customer does not exist| |7 |Invalid Amount| |8 |Payment id is not unique| |9 |Payment is not possible| |10 |Unknown service| |11 |Unknown operation type| |12 |Transaction was successful| |13 |Invalid transaction| |14 |Transaction in progress| |99 |General error| ამავე დროს, სერვის-პროვაიდერმა შეიძლება შემოიღოს შეცდომათა ისეთი კოდები, რომლებიც არ არიან ამ ცხრილში. კოდები არ უნდა შედიოდნენ 0-99 დიაპაზონში. უნდა აღინიშნოს ისიც რომ პროტოკოლი არ აძლევს გარანტიას სერვის-პროვაიდერს რომ მის მიერ გამოგზავნილი კოდის (გარდა ამ დოკუმენტით განსაზღვრული მნიშვნელობებისა) შესაბამის ტექსტს დაინახავს ყველა მომხმარებელი. ამიტომ საკუთარი კოდების დაბრუნება მხოლოდ განსაკუთრებულ შემთხვევებშია მიზანშეწონილი.