# Bank of Georgia developer documentation > Documentation for the public API services of Bank of Georgia: online payments, payment links, billing, online instalments, business internet banking and open banking. --- # Introduction Source: https://api.bog.ge/docs/en/payments/introduction ## Aggregator Integration Protocol for E-Commerce Services ## What is Online Payment API? The Online Payment API is a robust, developer-friendly solution designed to integrate a secure payment module into any electronic system quickly and effortlessly. It streamlines payment processing, allowing business to receive payments using various payment methods, including cards from Bank of Georgia and other commercial banks (VISA, MasterCard, American Express). ## Protocol and Technical Specifications - **API Architecture:** RESTful - **Communication Protocol:** HTTP/1.1 (All API calls must be made over HTTPS to ensure secure data transmission.) - **Data Format:** JSON is used for both request payloads and response bodies, facilitating easy integration. - **Authentication & Security:** OAuth 2.0 is used for authentication, while JSON Web Tokens (JWT) ensure secure data exchange. - **Synchronous API Calls:** Every API request is processed immediately, delivering a response that reflects the outcome of the API call. - **Asynchronous Webhook Notifications:** Although API calls are synchronous, key events, such as payment confirmations and updates, are managed asynchronously via Callbacks for reliable, real-time communication. - **Error Handling:** Standard HTTP status codes and descriptive error messages are used to indicate success or error states, helping developers quickly diagnose issues. ## Checkout Process Overview - **Customer Initiates Payment:** The customer selects the desired product or service (or a combination in a shopping cart) on the business's website and clicks the payment button. - **Business Sends an Order Request:** The business sends an [order request](https://api.bog.ge/docs/en/payments/standard-process/create-order) to the online payment API to initiate the operation, marking the beginning of the payment process. - **API Returns Order Request Details:** The payment gateway responds with the necessary parameters—such as an order request ID and a redirect URL—that enable the payment process to continue. - **Customer is Redirected to the Online Payment Page:** The business directs the customer to the online payment page. Here, the customer chooses the payment method, enters their card details or uses internet banking to authorize the payment. - **Payment Processing:** The online payment system validates payment details and securely processes the payment. - **Callback Notification Sent to Business:** Once the transaction is processed, the payment gateway sends a [Callback](https://api.bog.ge/docs/en/payments/standard-process/callback), to the business’s callback URL, provided in the order request. :::note Receiving the callback is a crucial step in the payment process. it confirms the payment status (successful or failed) and other essential details. Based on the information received in the callback, the business must ensure that its system is updated accordingly. ::: - **Operation Completion:** After receiving the callback, the business finalizes the process by confirming the order to the customer and completing any related fulfillment activities. :::note Before redirecting to the online payments page, the business can use the card-saving feature to carry out future transactions automatically or without entering card details. ::: --- # Authentication Method Source: https://api.bog.ge/docs/en/payments/authentication ## What do I need to use the payment API? To use the payment API, [HTTP Basic Auth](https://en.wikipedia.org/wiki/Basic_access_authentication) is required. You will need to know the unique credentials of your business to enter the system. These credentials consist of two parameters, `client_id`, and `client_secret`, used as the username and password for business authentication. ## How to obtain the credentials for entering the business system? Upon registering a company as a business in the banking system and providing all the necessary data, the system provides the credentials `client_id` and `client_secret` necessary to enter the system. These credentials are unique identifiers of the business. It is impermissible to disclose or transfer the `client_secret` parameter to another person. Doing so significantly increases the probability of a security breach. The business cannot change the `client_secret` parameter. ## Method description This method allows businesses to undergo the authentication process. Upon calling the API, the online payment server returns the `Bearer Token`, which is the necessary authentication parameter for calling all further methods. ### Header parameters - `Content-Type` — application/x-www-form-urlencoded, required - `Authorization` — Basic , required 'Basic ' + ':' encoded in the Base64 format is transmitted as a value (e.g., 'Basic ODI4Mjo3Njk3MDY0OTlmMDcwOWUyMzQ4NDU4NjNmOThiMjMxNA=='), where and are the credentials necessary to enter the system, transmitted by the bank to the business. ### Body parameters - `grant_type` — client_credentials, required The fixed text `client_credentials` is transmitted as the value. **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 The Token is returned by the authorization server. - `token_type` — string The type of Token (fixed value – `Bearer` – is returned). - `expires_in` — number The number of seconds while the Token is active. **RESPONSE** ```json { "access_token": "", "token_type": "Bearer", "expires_in": 1634719923245 } ``` --- # Order Request Source: https://api.bog.ge/docs/en/payments/standard-process/create-order To place an order request, businesses must send payment details, technical specifications, and the amount to be paid to the online payment server. If the process is successful, the customer should be redirected to the online payment page at the `redirect` address returned to the `_link` parameter to complete the payment. ### Header parameters - `Content-Type` — application/json, required - `Authorization` — Basic , required `Bearer `, where `jwt_token` is the token returned in the `access_token` parameter of the authentication method response. - `Idempotency-Key` — UUID v4 The Idempotency-Key parameter should be unique for each new API request. Subsequent requests to the same API endpoint with the same Idempotency-Key header will result in the server returning the same status code and response body as the initial request. This functionality is particularly useful to ensure consistent outcome in scenarios where network issues or retries may lead to duplicate requests. - `Accept-Language` — string The language of the interface that the customer will see when redirected to the online payment page. The possible values are: - `ka` - Georgian (default) - `en` - English. - `Theme` — string The theme of the interface that the customer will see when redirected to the online payment page. The possible values are: - `light` - Light (default) - `dark` - Dark. ### Body parameters - `application_type` — "web" | "mobile" Defines the type of application from which the order was created. This parameter is used specifically when an order is created using Apple Pay, directly from the merchant's webpage or mobile application. `application_type` has two values: - `web` - For orders created from a webpage. - `mobile` - For orders created from a mobile application. - `buyer` — object Information about the buyer. - `buyer.full_name` — string The buyer's name and surname. - `buyer.masked_email` — string The buyer's masked email address. - `buyer.masked_phone` — string The buyer's masked phone number. - `callback_url` — string, required The web address of the business (must be HTTPS), which will be automatically called by the bank upon completion of the payment to provide the business with the payment details (via Callback). - `external_order_id` — string The payment identifier from the business's system. The first 25 characters of the provided value will be reflected in the payment description, both on the payer's bank statement and in the description of the transaction when the funds are credited to the company's account. - `capture` — "automatic" | "manual" The transaction type takes two values: - `automatic` - creation of a standard order, payment will be made without pre-authorization, and the amount will be immediately withdrawn from the customer’s account. - `manual` - after payment, the amount on the customer’s account will be blocked and will not be available for the customer. To complete the payment, it is necessary to use the pre-authorization completing method and confirm/reject the transaction. If this operation is not performed within 30 days, the amount will be automatically unblocked and will be available again for the customer. This feature can only be used when paying through Apple Pay, Google Pay or by a card. - `purchase_units` — object, required The purchase information. - `purchase_units.basket` — array, required A basket of products or services purchased within a given payment in a business. - `purchase_units.basket[].product_id` — string, required The purchased product/service identifier in the business system. - `purchase_units.basket[].description` — string The name (description) of the purchased product/service. - `purchase_units.basket[].quantity` — number, required The quantity (volume) of each product/service. The minimum value is 1. - `purchase_units.basket[].unit_price` — number, required The purchased product/service unit price. - `purchase_units.basket[].unit_discount_price` — number The volume of the deducted amount on the product/service unit in case of discount payment. - `purchase_units.basket[].vat` — number The value added tax (VAT) of the purchased product/service. - `purchase_units.basket[].vat_percent` — number The percentage of value added tax (VAT) of the purchased product/service. - `purchase_units.basket[].total_price` — number The total price of the purchased product/service. - `purchase_units.basket[].image` — string The web address of the product/service image. - `purchase_units.basket[].package_code` — string The product code of the purchased product/service. - `purchase_units.basket[].tin` — string The taxpayer identification number (TIN). - `purchase_units.basket[].pinfl` — string The personal identification number of an individual (PINFL). - `purchase_units.basket[].product_discount_id` — string Product discount identifier. If a discount promotion is registered in the bank with the provided value, taking into account the terms of the discount, the corresponding promotion will be applied to the order. - `purchase_units.delivery` — object Information about the delivery service. - `purchase_units.delivery.amount` — number The delivery fee. - `purchase_units.total_amount` — number, required The full amount is to be paid. - `purchase_units.total_discount_amount` — number The reduced amount in case of payment with a discount. - `purchase_units.currency` — string The currency in which payment is made: - `GEL` - Georgian Lari (default) - `USD` - US dollar - `EUR` - Euro - `GBP` - British pound. - `redirect_urls` — object The business web addresses that customers can be redirected to from the online payment system upon completion of the payment. - `redirect_urls.success` — string The web address in the case of successful completion of the transaction. If it is empty, the customer will remain on the online payments page and a corresponding receipt will be shown. - `redirect_urls.fail` — string The web address in the case of unsuccessful completion of the transaction. If it is empty, the customer will remain on the online payments page and a corresponding receipt will be shown. - `ttl` — number Specifies the duration of the order lifespan in minutes (the number of minutes a customer will be able to pay). The logic of this parameter can vary depending on the business's industry. The minimum value is 2 minutes, and the maximum is 1440 minutes (24 hours). If this parameter is left empty, the system defaults to 15 minutes. - `payment_method` — array The payment methods that a customer can use to pay for the order. The business must have all the methods it provides here activated. If the parameter is left empty, upon redirecting a customer to the online payment page, they will be able to use all the payment methods available for the business. The possible values are: - `card` - payment by a bank card - `google_pay` - payment through Google Pay and by a bank card (in the case of providing this option, the customer will be able to pay both by Google Pay and a bank card. The Business must have both payment methods activated) - `apple_pay` - payment through Apple Pay and by a bank card (in the case of providing this option, the customer will be able to pay both by Apple Pay and a bank card. The Business must have both payment methods activated) - `bog_p2p` - transferring by the BoG, internet, or mobile bank user - `bog_loyalty` - payment by the BoG MR/Plus points - `bnpl` - payment with Buy Now Pay Later plan - `bog_loan` - standard bank installment plan - `gift_card` - payment with a gift card - `config` — object Configuration of a specific payment. - `config.loan` — object Payment configuration. Transmission of a parameter is necessary if you wish the payment to be made only by installment plan ("payment_method":["bog_loan"]) or only by bnpl ("payment_method":["bnpl"]). - `config.loan.type` — string Discount code of the installment/bnpl (the value of the discount_code parameter returned by the calculator). - `config.loan.month` — number Duration of the installment/bnpl in months (the value of the month parameter returned by the calculator). - `config.campaign` — object Duration of the installment/bnpl in months (the value of the month parameter returned by the calculator). - `config.campaign.card` — string A card type, to which the discount applies to: - `visa` - Visa - `mc` - MasterCard - `solo` - SOLO card - `config.campaign.type` — string Discount type: - `restrict` - card type restriction - `client_discount` - discount on a specific card type - `config.google_pay` — object Payment configuration. Transmission of a parameter is necessary if you wish to make Google Pay payment from your own webpage. - `config.google_pay.google_pay_token` — string Full string representing the encrypted Google Pay payment details. It must include all nested fields as received from the Google Pay SDK without modification or truncation. - `config.google_pay.external` — boolean - `true` - payment is initiated from the Google Pay button on business' webpage - `false` - Payment is initiated from the bank's webpage (default). - `config.apple_pay` — object Payment configuration. This parameter is necessary if you wish to enable Apple Pay payments from your own webpage. - `config.apple_pay.external` — boolean - `true` -Payment is initiated from the Apple Pay button on the business's webpage. - `false` - Payment is initiated from the bank's webpage (default). - `config.account` — object Payment configuration: This object is necessary if you have configured multiple e-commerce POS terminals in the same currency. It allows you to group payments based on business needs or settle payments on different business bank accounts. - `config.account.tag` — string E-commerce POS identifier. If provided tag does not match with POS configuration or tag was not provided, the operation will default to the default POS terminal and its corresponding payment account. Note: It is important to agree upon tag values when configuring additional ecommerce POS terminal. - `config.split` — object The configuration object for split payments. This parameter is required if you want the order amount to be automatically split into specified amounts or percentages and transferred to the corresponding IBAN accounts. For more details, see [Split Payment Details](../split-payment). - `config.split.split_payments` — array An array of split payment transactions. Each object contains the details for a single transfer. - `config.split.split_payments[].iban` — string, required The recipient's account number in IBAN format where the split amount should be transferred. - `config.split.split_payments[].amount` — number, required The specific amount to be transferred. The sum of all amounts must not exceed the total order amount. - `config.split.split_payments[].percent` — number, required The percentage of the total order amount to be transferred. The sum of all percentages must not exceed 100. Only positive numerical values from 1 to 100 are allowed. - `config.split.split_payments[].description` — string A description for the transfer. :::note Providing both `amount` and `percent` fields in the same object is not permitted. Each object in the `split_payments` array must contain the `iban` field and either the `amount` or `percent` field. ::: **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 Order identifier. - `_links` — object The web resource addresses are used in the further stages of the payment process. At the moment two resources are returned: - `_links.details.href` — string The address of the payment details can be used to obtain information on the online payment. - `_links.redirect.href` — string The web page address, which a customer shall be redirected to in order to enter a plastic card or online banking details and complete the process. **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}" } } } ``` --- # Payment Details Source: https://api.bog.ge/docs/en/payments/standard-process/get-payment-details This method allows businesses to receive detailed information about an online payment using its identifier. ### Header parameters - `Authorization` — Basic , required The meaning `Bearer ` is transmitted, where `jwt_token` is the meaning returned to the access_token parameter of the Response method. ### Path parameter - `order_id` — string, required The order identifier returned to the online shop in the response of the create order request. **CURL** ```bash curl -X GET 'https://api.bog.ge/payments/v1/receipt/:order_id' \ -H 'Authorization: Bearer ' ``` ## Response - `order_id` — string The online payment identifier. - `industry` — string The business industry, defined during its registration. - `capture` — string The authorization method, always - `automatic`. transaction type with two possible meanings: - `automatic` - a standard order - `manual` - a pre-authorization order - `external_order_id` — string The payment identifier from the business's system. The first 25 characters of the provided value will be reflected in the payment description, both on the payer's bank statement and in the description of the transaction when the funds are credited to the company's account. - `client` — object The business information. - `client.id` — string The business identifier in the bank system. - `client.brand_ka` — string The business Georgian name. - `client.brand_en` — string The business English name. - `client.url` — string The business web-site address. - `zoned_create_date` — string The order creation date in Coordinated Universal Time ( UTC). It follows the format "YYYY-MM-DDTHH:MM:SS.ssssssZ". - `zoned_expire_date` — string The order expiration date in Coordinated Universal Time (UTC). It follows the format "YYYY-MM-DDTHH:MM:SS.ssssssZ". - `order_status` — object Order status. - `order_status.key` — string The status gets the following meanings: - `created` - payment request is created - `processing` - payment is being processed - `completed` - payment process has been completed - `rejected` - payment process has been unsuccessfully completed - `refund_requested` - refund of the amount is requested - `refunded` - payment amount has been returned - `refunded_partially` - payment amount has been partially refunded - `auth_requested` - pre-authorize payment is requested - `blocked` - pre-authorize payment has been completed successfully, but payment amount is blocked and waiting for confirmation - `partial_completed` - pre-authorize payment partial amount has been confirmed successfully - `order_status.value` — string Description. - `buyer` — object The buyer information. - `buyer.full_name` — string The buyer's full name. - `buyer.email` — string The buyer's email. - `buyer.phone_number` — string The buyer's phone number. - `purchase_units` — object Information on the purchased products. - `purchase_units.request_amount` — string The requested amount of the order. - `purchase_units.transfer_amount` — string The processed amount of the order. - `purchase_units.refund_amount` — string The refunded amount. - `purchase_units.currency_code` — string Currency. - `purchase_units.items` — array The list of the purchased products/services. - `purchase_units.items[].external_item_id` — string The purchased product/service identifier in the business system. - `purchase_units.items[].description` — string The name (description) of the purchased product/service. - `purchase_units.items[].quantity` — string The quantity (volume) of each product/service. - `purchase_units.items[].unit_price` — string The purchased product/service unit price. - `purchase_units.items[].unit_discount_price` — string The volume of the deducted amount on the product/service unit in case of discount payment. - `purchase_units.items[].vat` — string The value added tax (VAT) of the purchased product/service. - `purchase_units.items[].vat_percent` — string The percentage of value added tax (VAT) of the purchased product/service. - `purchase_units.items[].total_price` — string The total price of the purchased product/service. - `purchase_units.items[].package_code` — string The product code of the purchased product/service. - `purchase_units.items[].tin` — string The taxpayer identification number (TIN). - `purchase_units.items[].pinfl` — string The personal identification number of an individual (PINFL). - `purchase_units.basket[].product_discount_id` — string Product discount identifier. If a discount promotion is registered in the bank with the provided value, taking into account the terms of the discount, the corresponding promotion will be applied to the order. - `redirect_links` — object The business web-pages, to which customers can be re-directed from the online payment system upon completion of the transaction. - `redirect_links.fail` — string The web-address in the case of transaction failure. - `redirect_links.success` — string The web-address in the case of transaction success. - `payment_detail` — object Payment details. - `payment_detail.transfer_method` — string Payment method. - `payment_detail.transfer_method.key` — string The payment method gets the following meanings: - `card` - payment by a bank card - `google_pay` - payment through Google Pay - `apple_pay` - payment through Apple Pay - `bog_p2p` - transferring by a customer of the Bank of Georgia, internet or mobile banking - `bog_loyalty` - payment by BoG MR/Plus points - `bnpl` - payment in installments - `bog_loan` - standard bank installment plan. - `payment_detail.transfer_method.value` — string Description. - `payment_detail.transaction_id` — string Transaction identifier. - `payment_detail.auth_code` — string Payment authorization identifier. The value will also be reflected in the settlement statement on the company's account. - `payment_detail.payer_identifier` — string A payer's identifier, according to the `transfer_method`, gets various meanings: - `card`/`google_pay` – the card’s encoded number is returned (PAN) - `apple_pay` – a device-specific number assigned to your card by Apple is returned - `bog_p2p`/`bog_loyalty` – the account name is returned - `bog_loan`/`bnpl` – the first letter of a customer name is returned. - `payment_detail.payment_option` — string Payment method. The following values can be returned: - `direct_debit` - card payment - `recurrent` - payment by the saved card - `subscription` - automatic payment by the saved card. - `payment_detail.card_type` — string The type of card used for payment. The parameter takes its value during the card payment: - `amex` - American Express - `mc` - Mastercard - `visa` - Visa. - `payment_detail.card_expiry_date` — string Expiration date (month/year) of the card with which the payment was made. The parameter takes value at the time of card payment. - `payment_detail.request_account_tag` — string E-commerce POS identifier requested in the order. - `payment_detail.transfer_account_tag` — string E-commerce POS identifier on which the payment was processed. - `payment_detail.saved_card_type` — string Saved card type. Possible values are listed below: - `recurrent` - Card saved for client initiated future payments. - `subscription` - Card saved for automatic, subscription payments with fixed amount and details. - `payment_detail.parent_order_id` — string If payment was initiated using saved card, saved card order Id is given. - `payment_detail.code` — string Payment Response Code. - `payment_detail.code_description` — string Payment Response Code Description. - `payment_detail.auth_code` — string Card, Google Pay or Apple Pay Payment Authorization Code. - `discount` — object Discount details, that was applied on the payment - `discount.bank_discount_amount` — string Bank Discount Amount - `discount.bank_discount_desc` — string Bank Discount Description - `discount.system_discount_amount` — string Card system discount amount - `discount.system_discount_desc` — string Card system discount description - `discount.discounted_amount` — string Amount after discount - `discount.original_order_amount` — string Original amount - `actions` — array The list of actions associated with an order. - `actions[].action_id` — string The action identifier. - `actions[].request_channel` — string The channel, from which the action was initiated: - `public_api` - online payments API - `business_manager` - business manager website - `support` - BOG inner system. - `actions[].action` — string The action type: - `authorize` - confirmation of pre-authorize payment - `partial_authorize` - confirmation of pre-authorize payment - `cancel_authorize` - rejection of pre-authorize payment - `refund` - refund - `partial_refund` - partially refund - `actions[].status` — string The action status: - `completed` - action has been completed successfully - `rejected` - has been completed unsuccessfully - `actions[].code` — string Action response code. See [here](../response-codes#action-response-codes) for the List of Action Response Codes. - `actions[].code_description` — string Action response code description. - `actions[].zoned_action_date` — string The date when the action was initiated in Coordinated Universal Time (UTC). It follows the format "YYYY-MM-DDTHH:MM:SS.ssssssZ". - `actions[].amount` — string The amount associated with the action. - `lang` — string The interface language found by a customer after re-directing to the online payment page. There are two meanings: - `ka` - Kartuli (Georgian) - `en` - English - `reject_reason` — string The reason for payment failure. The parameter takes value only if the order failed ("order_status": "rejected"). takes the following values: - `expiration` - the order has expired - `unknown` - an unidentified reason. - `Payment Response Code Description` - Payment rejection reason, initiated by card, Google Pay or Apple Pay. See full list of Response codes [here](https://api.bog.ge/docs/en/docs/en/payments/response-codes). - `split` — object An object for the status and details of the split payment. - `split.split_status` — string The status of the split payment request. Possible values are: - `created` - The request has been created - `processing` - The request is being processed - `canceled` - The request has been canceled - `completed` - The request was successfully completed - `rejected` - The request was rejected (failed to execute) - `split.currency` — string The currency of the split payment (e.g., GEL). - `split.request_channel` — string The channel from which the split payment was initiated. **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/en/payments/standard-process/callback A callback is an asynchronous, server-to-server notification sent from the online payment system to your designated callback URL. Its purpose is to reliably inform your system about the final status of a transaction. Unlike synchronous API calls where your application requests information and waits for an immediate response, the callback process works in the background. The payment system will automatically send a POST request to your callback URL once a transaction is complete, whether successful or unsuccessful, including the initial payment or related actions such as partial/full refunds, preauthorization approvals, and split payments. The logic for receiving and processing this callback must be implemented on the business side, including the validation for callback signature. Proper handling of the callback is a crucial step to confirm the payment status and securely update the order in your system. Payment details are sent to the callback URL, provided when the order was requested, using the POST method. To confirm successful receipt of the callback, the business should return HTTP CODE 200. If callback was not received successfully, business must use the [Get Payment Details](https://api.bog.ge/docs/en/payments/standard-process/get-payment-details) method to verify the payment status and correctly update the order status in its system. :::note **Callback and Redirect URL serve distinct purposes:** **Redirect URL** - Redirects the customer from the online payment page back to the business’s website after payment, enhancing the user experience. However, it does not guarantee the final payment status, as redirection may fail due to user actions or other circumstances, making it essential to verify payment completion through a server-to-server callback. **Callbacks** - Ensure payment status confirmation and the secure delivery of payment information from the online payment system’s server to the business’s server. Unlike Redirect URLs, callbacks are independent of user actions and serve as a reliable source for verifying payment status. ::: # Request ### Header Parameters - `Callback-Signature` — string Signature generated by encrypting callback's request body with a `private key` using `SHA256withRSA` algorithm. In order to ensure integrity of callback data, business should verify signature using request body and `public key`. It is essential to execute this verification before the deserialization of the request body, ensuring that the order of fields remains unchanged. **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 Parameters - `event` — string Callback type. The meaning is always `order_payment`. - `zoned_request_time` — string Date of sending a callback in Coordinated Universal Time (UTC). It follows the format "YYYY-MM-DDTHH:MM:SS.ssssssZ". - `body` — object Order data. Involves the [payment detail](https://api.bog.ge/docs/en/payments/standard-process/get-payment-details#response) containing fields. **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", ... } } ``` --- # Save Card for Recurring Payments Source: https://api.bog.ge/docs/en/payments/saved-card/recurrent The bank offers businesses the option to save a customer's card information, with the customer's consent, to enable future payments without having to enter card details again. To use this feature, the business should call the relevant method and provide the order identifier before redirecting the customer to the payment page upon order request. If the card payment is successful for the given order, the same identifier can be used for future orders. ### Header parameters - `Authorization` — Basic , required `Bearer `, where `jwt_token` is the token returned in the `access_token` parameter of the authentication method response. - `Idempotency-Key` — UUID v4 The Idempotency-Key parameter should be unique for each new API request. Subsequent requests to the same API endpoint with the same Idempotency-Key header will result in the server returning the same status code and response body as the initial request. This functionality is particularly useful to ensure consistent outcome in scenarios where network issues or retries may lead to duplicate requests. ### Path parameters - `order_id` — string, required The order identifier is returned in response to the order request. ### Response - `Http Status: ` — 202 ACCEPTED The request has been accepted. **CURL** ```bash curl -X PUT 'https://api.bog.ge/payments/v1/orders/:order_id/cards' \ -H 'Authorization: Bearer ' ``` --- # Save Card for Automatic Payments Source: https://api.bog.ge/docs/en/payments/saved-card/offline The bank offers businesses the option to save a customer's card information, with the customer's consent, so that it can withdraw the amount automatically, without the customer's participation in the future. To use this feature, the business should call the relevant method and provide the order identifier before redirecting the customer to the payment page upon order request. If the card payment is successful for the given order, the same identifier can be used for future orders. ### Header parameters - `Authorization` — Basic , required `Bearer `, where `jwt_token` is the token returned in the `access_token` parameter of the authentication method response. - `Idempotency-Key` — UUID v4 The Idempotency-Key parameter should be unique for each new API request. Subsequent requests to the same API endpoint with the same Idempotency-Key header will result in the server returning the same status code and response body as the initial request. This functionality is particularly useful to ensure consistent outcome in scenarios where network issues or retries may lead to duplicate requests. ### Path parameters - `order_id` — string, required The order identifier is returned in response to the order request. ### Response - `Http Status: ` — 202 ACCEPTED The request has been accepted. **CURL** ```bash curl -X PUT 'https://api.bog.ge/payments/v1/orders/:order_id/subscriptions' \ -H 'Authorization: Bearer ' ``` --- # Delete Saved Card Source: https://api.bog.ge/docs/en/payments/saved-card/delete This method allows businesses to delete previously saved card information from the system. ### Header parameters - `Authorization` — Basic , required `Bearer `, where `jwt_token` is the token returned in the `access_token` parameter of the authentication method response. - `Idempotency-Key` — UUID v4 The Idempotency-Key parameter should be unique for each new API request. Subsequent requests to the same API endpoint with the same Idempotency-Key header will result in the server returning the same status code and response body as the initial request. This functionality is particularly useful to ensure consistent outcome in scenarios where network issues or retries may lead to duplicate requests. ### Path parameters - `order_id` — string, required The order identifier is returned in response to the order request. ### Response - `Http Status: ` — 202 ACCEPTED The request has been accepted. **CURL** ```bash curl -X DELETE 'https://api.bog.ge/payments/v1/charges/card/:order_id' \ -H 'Authorization: Bearer ' ``` --- # Payment by the Saved Card Source: https://api.bog.ge/docs/en/payments/saved-card/recurrent-payment This method allows businesses to enable customers to make payments on the bank's webpage without entering their card details again. This feature is useful when a customer has previously saved their card information during a successful card payment transaction for future use. ### Path parameters - `parent_order_id` — string, required The order identifier is returned in response to the order request. :::note The `Header`, `Body` and `Response` parameters for this method are the same as those used for the [order request method.](https://api.bog.ge/docs/en/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" } ] } }' ``` --- # Automatic Payment by the Saved Card Source: https://api.bog.ge/docs/en/payments/saved-card/offline-payment This method enables businesses to automatically withdraw funds from a customer's saved card without their participation. This feature is useful when a customer has previously saved their card information for automatic withdrawals during a successful card payment transaction. ### Header parameters - `Content-Type` — application/json, required - `Authorization` — Basic , required `Bearer `, where `jwt_token` is the token returned in the `access_token` parameter of the authentication method response. - `Idempotency-Key` — UUID v4 The Idempotency-Key parameter should be unique for each new API request. Subsequent requests to the same API endpoint with the same Idempotency-Key header will result in the server returning the same status code and response body as the initial request. This functionality is particularly useful to ensure consistent outcome in scenarios where network issues or retries may lead to duplicate requests. ### Path parameters - `parent_order_id` — string, required The order identifier on which the card was initially saved for automatic amount withdrawals. ### Body parameters - `callback_url` — string The web address of the business will be automatically called by the bank after the transaction is completed to transmit payment data (via callback). If the parameter is empty, the system will use the value transmitted during the creation of the order corresponding to the `parent_order_id.` - `external_order_id` — string The payment identifier from the business system (e.g., the purchase basket identifier). If the parameter is empty, the system will use the value transmitted during the creation of the order corresponding to the `parent_order_id.` :::note For the remaining parameters (amount, currency, buyer information, etc.) required for the order request, the system will automatically use the values transmitted during the creation of the order corresponding to the `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 The order identifier. - `_links` — object The web resource addresses are used in the further stages of the payment process. - `_links.details.href` — string The address of the payment details can be used to obtain information on the online payment. **RESPONSE** ```json { "id": "{order_id}", "_links": { "details": { "href": "https://api.bog.ge/payments/v1/receipt/{order_id}" } } } ``` --- # Introduction Source: https://api.bog.ge/docs/en/payments/preauthorization/introduction These methods allow businesses to complete the withdrawal process for the amount that was previously blocked during the [order request](https://api.bog.ge/docs/en/payments/standard-process/create-order) These methods are useful if the value of the capture field was set to manual during the order request. There are three methods available for completing the payment: full confirmation of the amount, partial confirmation of the amount, and rejection of the pre-authorization. [Confirm Pre-Authorization](https://api.bog.ge/docs/en/payments/preauthorization/approve) [Reject Pre-Authorization](https://api.bog.ge/docs/en/payments/preauthorization/reject) --- # Confirm Pre-Authorization Source: https://api.bog.ge/docs/en/payments/preauthorization/approve This method allows businesses to confirm pre-authorized amounts, either in full or partially. ### Header parameters - `Content-Type` — application/json, required - `Authorization` — Basic , required `Bearer `, where `jwt_token` is the token returned in the `access_token` parameter of the authentication method response. - `Idempotency-Key` — UUID v4 The Idempotency-Key parameter should be unique for each new API request. Subsequent requests to the same API endpoint with the same Idempotency-Key header will result in the server returning the same status code and response body as the initial request. This functionality is particularly useful to ensure consistent outcome in scenarios where network issues or retries may lead to duplicate requests. ### Path parameters - `order_id` — string, required The order identifier is returned in response to the order request. ### Body parameters - `amount` — number The amount is to be confirmed. If an exact amount is specified, the confirmation will be considered full; otherwise, it will be considered partial. If no amount is specified, the entire pre-authorized `amount` will be confirmed. - `description` — string A reason for confirmation. **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 The key or identifier for the status of the API request. - `message` — string The human-readable message associated with the API request. - `action_id` — string The unique identifier for the action associated with the API request. **RESPONSE** ```json { "key": "request_received", "message": "Pre-authorization payment approval request received", "action_id": "e786283f-dc7f-48ba-bb75-12857f5a43ad" } ``` --- # Reject Pre-Authorization Source: https://api.bog.ge/docs/en/payments/preauthorization/reject This method allows businesses to reject pre-authorized amounts in full. ### Header parameters - `Content-Type` — application/json, required - `Authorization` — Basic , required `Bearer `, where `jwt_token` is the token returned in the `access_token` parameter of the authentication method response. - `Idempotency-Key` — UUID v4 The Idempotency-Key parameter should be unique for each new API request. Subsequent requests to the same API endpoint with the same Idempotency-Key header will result in the server returning the same status code and response body as the initial request. This functionality is particularly useful to ensure consistent outcome in scenarios where network issues or retries may lead to duplicate requests. ### Path parameters - `order_id` — string, required The order identifier is returned in response to the order request. ### Body parameters - `description` — string A reason for rejection. **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 The key or identifier for the status of the API request. - `message` — string The human-readable message associated with the API request. - `action_id` — string The unique identifier for the action associated with the API request. **RESPONSE** ```json { "key": "request_received", "message": "Pre-authorization payment cancellation request received", "action_id": "aa9478c7-f82f-45a9-8a30-e7b4275b1224" } ``` --- # Online Installment Plan Modal Source: https://api.bog.ge/docs/en/payments/external-orders/modal :::info Integration of the installment plan model is necessary only in the case, if you want a consumer to choose the installment plan conditions on your page. ::: ## Buy Now Pay Later Visual Guide If you would like to place a ‘Buy Now Pay Later’ button on your page, please use the BNPL visual guide. Click [ { e.preventDefault(); const link = document.createElement('a'); link.href = '/docs/en/bnpl-button-guideline.pdf'; link.download = 'bnpl-button-guideline.pdf'; document.body.appendChild(link); link.click(); document.body.removeChild(link); }}>here](https://api.bog.ge/docs/en/docs/en/bnpl-button-guideline.pdf) to download the guide. ## Online Installment Plan Modal To choose the online installment plan conditions, we have prepared a special modal. The modal is a kind of loan calculator, where a customer, resulting from the basket cost, can see an approximate monthly payment and annual interest rate. As the conditions are always individual and rely on the agreement concluded between the Bank of Georgia and Merchant (including a 0% installment plan condition), they differ from the standard conditions. Providing a borrower with this information is important. All the information is given in the modal, thus helping a customer in decision-making. Respectively, prior to activation of the installment plan, a kind of loan calculator is necessary, which is an independent microservice and [needs integration](https://api.bog.ge/docs/en/docs/en/payments/authentication) on the Merchant’s site. The Bank of Georgia is offering a ready-made SDK, compatible with all devices (Desktop, Mobile, Tablet) and needs addition of a ready code fragment on the site. ![Online Installment Modal](../../assets/installment-modal.png) ### Example: ### Integration To begin the installment plan modal SDK integration, copy the code in HTML page. Put our client_id instead of the {`client_id`}. ```html ``` --- ### Modal demonstration To show the installment plan modal use the `BOG.Calculator.open` method. #### Parameters - `amount` — number, required Installment plan amount - `bnpl` — boolean The parameter defines whether to show the `standard installment plan` or/and `payment in installments` to a customer. - `true` - only the payment in installments will be shown to a customer - `false` - only the standard installment plan will be shown to a customer - `undefined` | `null` - both methods will be shown to a customer. - `onClose` — function The method, called by the SDK, if a customer closes the modal. - `onRequest` — function The method, called by the SDK, upon selecting the conditions by a customer. At this time the installment plan order should be [requested](https://api.bog.ge/docs/en/docs/en/payments/standard-process/create-order). The `config.loan` parameter should be set. The following arguments will be transmitted to the method: - `selected` - the object, into which there will be transmitted the data selected by a customer. - `amount` - the amount to be paid on monthly basis - `month` - number of the loan months - `discount_code` - the discount code - `successCb` - the method to be called, if you wish the SDK to continue the installment plan process. - `closeCb` - the method to be called, if you wish to close the modal. - `onComplete` — function The method being called by the SDK upon completion of the online installment plan process. At this time a customer is automatically re-directed to the Merchant’s success link. If you do not want the re-direction, return the `false` meaning (`return false`:) in the method. The method will be given the object as an argument with the following parameters: - `redirectUrl` - the link, where a customer is to be redirected to. ### There are two methods of process continuation: 1. If you want the SDK to continue the online installment plan process, upon generation of orderId in the `onRequest` method, call `successCb` and transmit the [generated](https://api.bog.ge/docs/en/docs/en/payments/standard-process/create-order) `orderld` parameter to it. Upon completion of the process, the `onComplete` method will be called. 2. If the SDK is needed only for a calculator and want a customer to continue the process after selection of the desirable condition, return the `false` meaning (`return false:`) into the `onRequest` method and the SDK will not continue the process. At this time the modal remains open. If you wish to close the modal, use the `closeCb` or `Bog.Calculator.close()` method. ```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; } }) ``` --- The SDK also gives you the opportunity to add the BoG button to your site. Transmit the DOM element to the method, where you wish to insert the button. ```html
``` --- # Google Pay™ on Business' Webpage Source: https://api.bog.ge/docs/en/payments/external-orders/external-googlepay # Google Pay™ on Business' Webpage To add Google Pay™ button on your webpage, following steps are required. First your webpage should be compliant with Google's requirements. Since Google Pay button is added to your own webpage, instead of Bank of Georgia's, you need to configure the environment independently. For more information visit [Google's configuration page](https://support.google.com/pay/business/answer/7684271?hl=en). :::note During configuration, use the following parameters: ```json { "type": "PAYMENT_GATEWAY", "parameters": { "gateway": "georgiancard", "gatewayMerchantId": "BCR2DN4TXKPITITV", } } ``` ::: After these steps you can make Bank payments through Google Pay button on your page. For creating order see [Standard Process - Order Request](https://api.bog.ge/docs/en/payments/standard-process/create-order) Order Request [`Body`](https://api.bog.ge/docs/en/payments/standard-process/create-order#body-parameters) should contain following parameters: ```json "payment_method": ["google_pay"], "config": { "google_pay": { "external": true, "google_pay_token": "{token}" } } ``` - `config.google_pay.external` — boolean Pass the value true when initiating the operation using the Google Pay button on the Business Web Page. - `config.google_pay.token` — string Full string representing the encrypted Google Pay payment details. It must include all nested fields as received from the Google Pay SDK without modification or truncation. {{ "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 Order identifier. - `status` — string Order status. - `order_details` — object Order details. Contains same data as [payment details](https://api.bog.ge/docs/en/payments/standard-process/get-payment-details#response). The object is returned if payment process is completed without 3DS authentication. - `_links` — object The web resource addresses are used in the further stages of the payment process. At the moment following resources are returned: - `_links.details.href` — string The address of the payment details can be used to obtain information on the online payment. - `_links.redirect.href` — string The web page address to which a customer should be redirected for 3DS authentication. The parameter is returned if the client has 3DS authentication turned on. **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™ on Business' Webpage Source: https://api.bog.ge/docs/en/payments/external-orders/external-applepay # Apple Pay™ on Business' Webpage To add Apple Pay™ button on your webpage, following steps are required. First your webpage should be compliant with [Apple's requirements](https://developer.apple.com/apple-pay/acceptable-use-guidelines-for-websites/). Since Apple Pay button is added to your own webpage, instead of Bank of Georgia's, you need to configure the environment independently. For more information visit [Apple's configuration page](https://developer.apple.com/documentation/apple_pay_on_the_web/configuring_your_environment). Add the Apple Pay certificate on your website. Download certificate [here](https://webstatic.bog.ge/apple-developer-merchantid-domain-association). See the detailed instruction [here](https://developer.apple.com/documentation/applepaywebmerchantregistrationapi/preparing_merchant_domains_for_verification). After adding the certificate, please, write to this email address [ecommercemerchants@bog.ge](mailto:ecommercemerchants@bog.ge) and provide your domain and your API Public Key. After these steps you can make Bank payments through Apple Pay button on your page. For creating order see [Standard Process - Order Request](https://api.bog.ge/docs/en/payments/standard-process/create-order) :::note [`Body`](https://api.bog.ge/docs/en/payments/standard-process/create-order#body-parameters) should contain following parameters: ```json "payment_method": ["apple_pay"], "config": { "apple_pay": { "external": true } } ``` ::: ### Response - `id` — string Order identifier. - `result` — json The result returned by Apple when initiating payment. - `_links` — object The web resource addresses are used in the further stages of the payment process. At the moment following resource is returned: - `_links.accept.href` — string The address for accepting payment. It is necessary to call this service for completing Apple Pay payment. **RESPONSE** ```json { "id": "{order_id}", "result": {...}, "_links": { "accept": { "href": "https://api.bog.ge/payments/v1/ecommerce/orders/{order_id}/payment" } } } ``` --- # Apple Pay™ Accept Payment Source: https://api.bog.ge/docs/en/payments/external-orders/complete-external-applepay # Apple Pay™ Accept Payment Calling this service is required to complete Apple Pay™ payment initiated on business' webpage. ### Header parameters - `Content-Type` — application/json, required - `Authorization` — Basic , required `Bearer `, where `jwt_token` is the token returned in the `access_token` parameter of the authentication method response. - `Idempotency-Key` — UUID v4 The Idempotency-Key parameter should be unique for each new API request. Subsequent requests to the same API endpoint with the same Idempotency-Key header will result in the server returning the same status code and response body as the initial request. This functionality is particularly useful to ensure consistent outcome in scenarios where network issues or retries may lead to duplicate requests. ### Path parameters - `order_id` — string, required The order identifier returned in response to the order request. ### Body parameters - `apple_pay_token` — string, required Full string representing the encrypted Apple Pay payment details. It must include all nested fields as received from the Apple Pay SDK without modification or truncation. **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 Order identifier. - `status` — string Order status. - `order_details` — object Order details. Contains same data as [payment details](https://api.bog.ge/docs/en/payments/standard-process/get-payment-details#response). - `_links` — object The web resource addresses are used in the further stages of the payment process. At the moment following resources are returned: - `_links.details.href` — string The address of the payment details can be used to obtain information on the online payment. **RESPONSE** ```json { "id": "{order_id}", "status": "completed", "order_details": {...}, "_links": { "details": { "href": "https://api.bog.ge/payments/v1/receipt/{order_id}" } } } ``` --- # Refund Source: https://api.bog.ge/docs/en/payments/refund This method allows merchants to refund the order amount either fully or partially. Full and partial refunds are supported for payments made via card, Apple Pay, Google Pay, BOG authorization, and loyalty points. The partial refund method can be initiated repeatedly until the total paid amount is fully refunded. ### Header parameters - `Content-Type` — application/json, required - `Authorization` — Basic , required `Bearer `, where `jwt_token` is the token returned in the `access_token` parameter of the authentication method response. - `Idempotency-Key` — UUID v4 The Idempotency-Key parameter should be unique for each new API request. Subsequent requests to the same API endpoint with the same Idempotency-Key header will result in the server returning the same status code and response body as the initial request. This functionality is particularly useful to ensure consistent outcome in scenarios where network issues or retries may lead to duplicate requests. ### Path parameters - `order_id` — string, required The order identifier is returned in response to the order request. ### Body parameters - `amount` — number The amount to be refunded. This parameter is necessary if a partial refund is being made. If the parameter is not included, the entire amount will be refunded. The value of this parameter cannot exceed the processed amount (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 The key or identifier for the status of the API request. - `message` — string The human-readable message associated with the API request. - `action_id` — string The unique identifier for the action associated with the API request. **RESPONSE** ```json { "key": "request_received", "message": "Refund request received", "action_id": "5b666901-eb05-4f83-abeb-8311e175f337" } ``` --- # Response Codes Source: https://api.bog.ge/docs/en/payments/response-codes ## Payment Response Codes | Code | Description (EN) | Description (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 | წარმატებული პრეავტორიზაცია | ## Action Response Codes | Code | Description (EN) | Description (GE) | |------|----------------------------------------------------------------------------------|----------------------------------------------------------------| | 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 | --- # Split Payment Source: https://api.bog.ge/docs/en/payments/split-payment ## Split Payment Details The Split Payment functionality allows you to easily and automatically distribute the amount received from an order among your partners, service providers, or merchants. This feature is available only in GEL and for the following online payment methods: - `card` - `google_pay` - `apple_pay` - `bog_loyalty` - `bog_p2p` If a customer pays for the order using any other method, the full amount will be credited to the main settlement account, and the split will not be executed. A single order amount can be split into a maximum of 10 parts. ### Conditions for Successful Execution: - The Split Payment functionality must be activated for the shop. - The shop’s main settlement account must have a sufficient balance to cover all transfers and associated fees. - The IBAN accounts provided must be active, belong to a local bank, and be denominated in the national currency (GEL). - The order must be paid for using one of the supported payment methods listed above. If any of these conditions are not met, the entire split payment operation will fail, and no transfers will be executed. ## Pre-authorization Capture When capturing a pre-authorized payment, a `split` object can be included in the request to split the captured amount. **Important:** If a pre-authorization is only partially captured and the split is defined by fixed amounts (`amount`), the sum of the amounts specified in the `split_payments` objects must not exceed the capture amount. ## Pre-authorization Cancellation No additional actions are required when canceling (voiding) a pre-authorization. When the main transaction is canceled, the associated split payment request is also automatically canceled and its status will change to `canceled`. ## Payment Refund A full or partial refund of an order does not affect an already completed or in-progress split payment request. The split operation is not reversed, and the transferred funds are not returned. --- # Google Pay™ Source: https://api.bog.ge/docs/en/payments/googlepay # Google Pay ™ Google Pay™ is the fast, simple way that allows you to make card payments without entering card details for each payment. The card data is safely stored by Google. This payment method is available for all devices (mobile phones and computers), regardless of the operating system and web browser. To enable Google Pay™, simply go to the [Business Manager](https://businessmanager.bog.ge/en/) and walk through onboarding process. Note that when you use Google Pay™ you must adhere to Google's [Terms of Service](https://payments.developers.google.com/terms/sellertos). Once you have enabled it, we will automatically show the Google Pay™ button in your payment window for applicable payments. Bank of Georgia supports both "PAN only" and "Cryptogram 3DS" methods of authorization. If 3D-secure is needed for the transaction, Bank of Georgia will automatically take care of that. Since some 3D-secure authentications require the billing address of the customer, we recommend that you supply it to Bank of Georgia when you create the payment. Bank of Georgia supports VISA, MasterCard and American Express transactions from Google Pay™. Google Pay™ is free to use and we recommend enabling it to increase your conversion rate. --- # Terms Used Source: https://api.bog.ge/docs/en/payments/terms-used 1. Business - a retailer or service company, having an online/electronic system. 2. Online Payments Page - an online payments system, that allows you to easily build a payments' module into any type of business. 3. Callback - calling of the service chosen by the business from the banking system to provide updated information on the payment. 4. System Entering Credentials - a client’s identifier in the banking system (`client_id`) and a secret key (`secret_key`), given by the bank to the client upon its successful registration. 5. Card Number (PAN) - 16 digits given on the front side of the bank card. --- # Authentication Method Source: https://api.bog.ge/docs/en/payments-addons/authentication ## What do I need to use the payment API? To use the payment API, [HTTP Basic Auth](https://en.wikipedia.org/wiki/Basic_access_authentication) is required. You will need to know the unique credentials of your business to enter the system. These credentials consist of two parameters, `client_id`, and `client_secret`, used as the username and password for business authentication. ## How to obtain the credentials for entering the business system? Upon registering a company as a business in the banking system and providing all the necessary data, the system provides the credentials `client_id` and `client_secret` necessary to enter the system. These credentials are unique identifiers of the business. It is impermissible to disclose or transfer the `client_secret` parameter to another person. Doing so significantly increases the probability of a security breach. The business cannot change the `client_secret` parameter. ## Method description This method allows the business to undergo the authentication process. Upon calling the API, the online payment server returns the `Bearer Token`, which is the necessary authentication parameter for calling all further methods. ### Header parameters - `Content-Type` — application/x-www-form-urlencoded, required - `Authorization` — Basic , required 'Basic ' + ':' encoded in the Base64 format is transmitted as a value (e.g., 'Basic ODI4Mjo3Njk3MDY0OTlmMDcwOWUyMzQ4NDU4NjNmOThiMjMxNA=='), where and are the credentials necessary to enter the system, transmitted by the bank to the business. ### Body parameters - `grant_type` — client_credentials, required The fixed text `client_credentials` is transmitted as the value. **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 The Token is returned by the authorization server. - `token_type` — string The type of Token (fixed value – `Bearer` – is returned). - `expires_in` — number The number of seconds while the Token is active. **RESPONSE** ```json { "access_token": "", "token_type": "Bearer", "expires_in": 1634719923245 } ``` --- # Top-Up Source: https://api.bog.ge/docs/en/payments-addons/standard-process/create-top-up-order This method allows business to initiate the top-up operation by sending the technical specifications along with the amount to be paid. To complete the payment, the customer should be redirected to the online payment page at the redirect address returned in the `_link` parameter. ### Header parameters - `Content-Type` — application/json, required - `Authorization` — Basic , required `Bearer `, where `jwt_token` is the token returned in the `access_token` parameter of the authentication method response. - `Idempotency-Key` — UUID v4 The `Idempotency-Key` parameter should be unique for each new API request. Subsequent requests to the same API endpoint with the same `Idempotency-Key` header will result in the server returning the same status code and response body as the initial request. This functionality is particularly useful to ensure a consistent outcome in scenarios where network issues or retries may lead to duplicate requests. - `Accept-Language` — string The language of the interface that the customer will see when redirected to the online payment page. The possible values are: - `ka` - Georgian (default) - `en` - English. - `Theme` — string The theme of the interface that the customer will see when redirected to the online payment page. The possible values are: - `light` - Light (default) - `dark` - Dark. ### Body parameters - `application_type` — "web" | "mobile" Defines the type of application from which the order was created. This parameter is used specifically when an order is created using Apple Pay, directly from the merchant's webpage or mobile application. `application_type` has two values: - `web` - For orders created from a webpage. - `mobile` - For orders created from a mobile application. - `callback_url` — string, required The web address of the business (must be HTTPS), which will be automatically called by the bank upon completion of the payment to provide the business with the payment details via Callback. - `external_order_id` — string The payment identifier from the business's system. The first 25 characters of the provided value will be reflected in the payment description, both on the payer's bank statement and in the description of the transaction when the funds are credited to the company's account. - `money_units` — object, required Specifies the operation amount and currency. - `money_units.total_amount` — number, required The operation amount. - `money_units.currency` — string, required The operation currency. - `redirect_urls` — object The business web addresses to which customers can be redirected from the online payment system upon completion of the payment. - `redirect_urls.success` — string The URL to redirect to in the case of successful completion of the transaction. If left empty, the customer will remain on the online payments page, and a corresponding receipt will be shown. - `redirect_urls.fail` — string The URL to redirect to in the case of unsuccessful completion of the transaction. If left empty, the customer will remain on the online payments page, and a corresponding receipt will be shown. - `ttl` — number Specifies the duration of the order lifespan in minutes (the number of minutes a customer will be able to pay). The logic of this parameter can vary depending on the business's industry. The minimum value is 2 minutes, and the maximum is 1440 minutes (24 hours). If this parameter is left empty, the system defaults to 15 minutes. - `payment_method` — array The payment methods that a customer can use to pay for the order. The business must have all the methods it provides here activated. If the parameter is left empty, upon redirecting a customer to the online payment page, they will be able to use all the payment methods available for the business. The possible values are: - `card` - Payment by a bank card. - `apple_pay` - Payment through Apple Pay and by a bank card (in the case of providing this option, the customer will be able to pay both by Apple Pay and a bank card. The Business must have both payment methods activated) - `bog_p2p` - Transferring by the BoG, internet, or mobile bank user - `config` — object Configuration of a specific payment. - `config.apple_pay` — object Payment configuration. This parameter is necessary if you wish to enable Apple Pay payments from your own webpage. - `config.apple_pay.external` — boolean - `true` - Payment is initiated from the Apple Pay button on the business's webpage. - `false` - Payment is initiated from the bank's webpage (default). - `config.account` — object Payment configuration: This object is necessary if you have configured multiple e-commerce POS terminals in the same currency. It allows you to group payments based on business needs or settle payments on different business bank accounts. - `config.account.tag` — string E-commerce POS identifier. If provided tag does not match with POS configuration or tag was not provided, the operation will default to the default POS terminal and its corresponding payment account. Note: It is important to agree upon tag values when configuring additional ecommerce POS terminal. - `save_card` — string Request card save. Add this field only if you need to save card used during completing the payment. Allowed value: - `recurrent` - Saving card for recurring payments. Card will be stored only if payment was completed successfully using card method. - `transaction_type` — string Identifies operation type. The possible values are: - `purchase` - Standard card payment. - `aft` - Account Funding Transaction. **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 Order identifier. - `_links` — object The web resource addresses are used in the further stages of the payment process. At the moment two resources are returned: - `_links.details.href` — string The address of the payment details that can be used to obtain information on the payment. - `_links.redirect.href` — string The web page address, which a customer shall be redirected to in order to enter a plastic card or online banking details and complete the process. **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}" } } } ``` --- # Top-Up By Saved Card Source: https://api.bog.ge/docs/en/payments-addons/standard-process/create-top-up-order-with-saved-card This method allows business to initiate the top-up operation using customer's already saved card, by sending the technical specifications along with the amount to be paid. To complete the payment, the customer should be redirected to the online payment page at the redirect address returned in the `_link` parameter. ### Path parameters - `parent_order_id` — string, required The order identifier is returned in response to the order request. :::note The `Header`, `Body` and `Response` parameters for this method are the same as those used for the [order request method.](https://api.bog.ge/docs/en/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" } }' ``` --- # Delete Saved Card Source: https://api.bog.ge/docs/en/payments-addons/standard-process/delete This method allows the business to delete previously saved card information from the system. ### Header parameters - `Authorization` — Basic , required `Bearer `, where `jwt_token` is the token returned in the `access_token` parameter of the authentication method response. - `Idempotency-Key` — UUID v4 The `Idempotency-Key` parameter should be unique for each new API request. Subsequent requests to the same API endpoint with the same `Idempotency-Key` header will result in the server returning the same status code and response body as the initial request. This functionality is particularly useful to ensure consistent outcome in scenarios where network issues or retries may lead to duplicate requests. ### Path parameters - `order_id` — string, required Order identifier that is returned in the Top-Up response. ### Response - `Http Status: ` — 202 ACCEPTED The request has been accepted. **CURL** ```bash curl -X DELETE 'https://api.bog.ge/payments/v1/charges/card/:order_id' \ -H 'Authorization: Bearer ' ``` --- # Payout Source: https://api.bog.ge/docs/en/payments-addons/standard-process/original-credit-transaction This method allows the business to enable customers to make payout operations on previously saved cards. This feature is useful when a customer has previously saved their card information during a successful card payment transaction for future use ### Header parameters - `Content-Type` — application/json, required - `Authorization` — Basic , required `Bearer `, where `jwt_token` is the token returned in the `access_token` parameter of the authentication method response. - `Idempotency-Key` — UUID v4 The `Idempotency-Key` parameter should be unique for each new API request. Subsequent requests to the same API endpoint with the same `Idempotency-Key` header will result in the server returning the same status code and response body as the initial request. This functionality is particularly useful to ensure consistent outcome in scenarios where network issues or retries may lead to duplicate requests. - `Accept-Language` — string The language of the interface that the customer will see when redirected to the online payment page. The possible values are: - `ka` - Georgian (default) - `en` - English. - `Theme` — string The theme of the interface that the customer will see when redirected to the online payment page. The possible values are: - `light` - Light (default) - `dark` - Dark. ### Path parameters - `parent_order_id` — string, required The order identifier returned in response to the order request. ### Body parameters - `callback_url` — string, required The web address of the business (must be HTTPS), which will be automatically called by the bank upon completion of the payment to provide the business with the payment details via Callback. - `external_order_id` — string The payment identifier from the business system. - `money_units` — object, required Specifies the operation amount and currency. - `money_units.total_amount` — number, required The operation amount. - `money_units.currency` — string, required The operation currency. - `redirect_urls` — object The business web addresses to which customers can be redirected from the online payment system upon completion of the payment. - `redirect_urls.success` — string The URL to redirect to in the case of successful completion of the transaction. If left empty, the customer will remain on the online payments page, and a corresponding receipt will be shown. - `redirect_urls.fail` — string The URL to redirect to in the case of unsuccessful completion of the transaction. If left empty, the customer will remain on the online payments page, and a corresponding receipt will be shown. **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 Order identifier. - `_links` — object The web resource addresses used in further stages of the payment process. - `_links.details.href` — string The address of the payment details that can be used to obtain information on the payment. **RESPONSE** ```json { "id": "{order_id}", "_links": { "details": { "href": "https://api.bog.ge/payments/v1/receipt/{order_id}" } } } ``` --- # Refund Source: https://api.bog.ge/docs/en/payments-addons/standard-process/refund This method allows merchants to refund the order amount either fully or partially. Full and partial refunds are supported for payments made via card, Apple Pay and BOG authorization. ### Header parameters - `Content-Type` — application/json, required - `Authorization` — Basic , required `Bearer `, where `jwt_token` is the token returned in the `access_token` parameter of the authentication method response. - `Idempotency-Key` — UUID v4 The `Idempotency-Key` parameter should be unique for each new API request. Subsequent requests to the same API endpoint with the same `Idempotency-Key` header will result in the server returning the same status code and response body as the initial request. This functionality is particularly useful to ensure consistent outcome in scenarios where network issues or retries may lead to duplicate requests. ### Path parameters - `order_id` — string, required Order identifier that is returned in the Top-up response. ### Body parameters - `amount` — number The amount to be refunded. This parameter is necessary if a partial refund is being made. If the parameter is not included, the entire amount will be refunded. The value of this parameter cannot exceed the processed amount (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 The key or identifier for the status of the API request. - `message` — string The human-readable message associated with the API request. - `action_id` — string The unique identifier for the action associated with the API request. **RESPONSE** ```json { "key": "request_received", "message": "Refund request received", "action_id": "5b666901-eb05-4f83-abeb-8311e175f337" } ``` --- # Payment Details Source: https://api.bog.ge/docs/en/payments-addons/standard-process/get-payment-details This method allows businesses to receive detailed information about an online payment using its identifier. ### Header parameters - `Authorization` — Basic , required The meaning `Bearer ` is transmitted, where `jwt_token` is the meaning returned to the access_token parameter of the Response method. ### Path parameter - `order_id` — string, required Order identifier that is returned in the Top-up or Payout response. **CURL** ```bash curl -X GET 'https://api.bog.ge/payments/v1/receipt/:order_id' \ -H 'Authorization: Bearer ' ``` ## Response - `order_id` — string The online payment identifier. - `industry` — string The business industry, defined during its registration. - `external_order_id` — string The payment identifier from the business's system. The first 25 characters of the provided value will be reflected in the payment description, both on the payer's bank statement and in the description of the transaction when the funds are credited to the company's account. - `client` — object The business information. - `client.id` — string The business identifier in the bank system. - `client.brand_ka` — string The business name in Georgian. - `client.brand_en` — string The business name in English. - `client.url` — string The business website address. - `zoned_create_date` — string The order creation date in Coordinated Universal Time ( UTC). It follows the format "YYYY-MM-DDTHH:MM:SS.ssssssZ". - `zoned_expire_date` — string The order expiration date in Coordinated Universal Time (UTC). It follows the format "YYYY-MM-DDTHH:MM:SS.ssssssZ". - `order_status` — object The status of the order. - `order_status.key` — string The status can have the following values: - `created` - The payment request is created. - `processing` - The payment is being processed. - `completed` - The payment process has been completed. - `rejected` - The payment process was unsuccessful. - `refund_requested` - A refund of the amount has been requested. - `refunded` - The payment amount has been returned. - `refunded_partially` - The payment amount has been partially refunded. - `order_status.value` — string Description of the order status. - `redirect_links` — object The business web pages to which customers can be redirected from the online payment platform upon completion of the transaction. - `redirect_links.fail` — string The web-address in the case of transaction failure. - `redirect_links.success` — string The web-address in the case of transaction success. - `payment_detail` — object The details of the payment. - `payment_detail.transfer_method` — string The payment method. - `payment_detail.transfer_method.key` — string The payment method can have the following values: - `card` - payment by a bank card - `apple_pay` - payment through Apple Pay - `bog_p2p` - transfer by a Bank of Georgia customer via internet or mobile banking. - `payment_detail.transfer_method.value` — string Description of the payment method. - `payment_detail.transaction_id` — string The transaction identifier. - `payment_detail.auth_code` — string Payment authorization identifier. The value will also be reflected in the settlement statement on the company's account. - `payment_detail.payer_identifier` — string The payer's identifier, which varies depending on the „transfer_method„: - `card` – the card’s encoded number is returned (PAN) - `apple_pay` – a device-specific number assigned to your card by Apple is returned - `bog_p2p` – the account name is returned - `payment_detail.payment_option` — string The payment method. The following values can be returned: - `direct_debit` - Card payment. - `recurrent` - Payment by the saved card. - `payment_detail.card_type` — string The type of card used for payment. The parameter takes its value during the card payment: - `amex` - American Express - `mc` - Mastercard - `visa` - Visa. - `payment_detail.card_expiry_date` — string The expiration date (month/year) of the card used for payment. The parameter takes its value at the time of card payment. - `payment_detail.request_account_tag` — string E-commerce POS identifier requested in the order. - `payment_detail.transfer_account_tag` — string E-commerce POS identifier on which the payment was processed. - `payment_detail.saved_card_type` — string The type of saved card. Possible values is: - `recurrent` - Card saved for client-initiated future payments. - `payment_detail.parent_order_id` — string If the payment was initiated using a saved card, the saved card order ID is provided. - `payment_detail.code` — string Payment Response Code. - `payment_detail.code_description` — string Payment Response Code Description. - `actions` — array The list of actions associated with an order. - `actions[].action_id` — string The action identifier. - `actions[].request_channel` — string The channel, from which the action was initiated: - `public_api` - online payments API - `business_manager` - business manager website - `support` - BOG inner system. - `actions[].action` — string The action type: - `refund` - refund - `partial_refund` - partial refund - `actions[].status` — string The action status: - `completed` - The action was successfully completed. - `rejected` - The action was unsuccessfully completed. - `actions[].code` — string Action response code. See [here](../response-codes#action-response-codes) for the List of Action Response Codes. - `actions[].code_description` — string Action response code description. - `actions[].zoned_action_date` — string The date when the action was initiated in Coordinated Universal Time (UTC). It follows the format "YYYY-MM-DDTHH:MM:SS.ssssssZ". - `actions[].amount` — string The amount associated with the action. - `lang` — string The interface language selected by the customer after being redirected to the payment platform. The possible values are: - `ka` - Georgian. - `en` - English. - `reject_reason` — string The reason for payment failure. This parameter takes a value only if the order failed (`order_status`: `rejected`). The possible values are: - `expiration` - The order has expired. - `unknown` - An unidentified reason. - `Payment Response Code Description` - Payment rejection reason, initiated by card, Google Pay or Apple Pay. See full list of Response codes [here](https://api.bog.ge/docs/en/docs/en/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/en/payments-addons/standard-process/callback A callback is an asynchronous, server-to-server notification sent from the online payment system to your designated callback URL. Its purpose is to reliably inform your system about the final status of a transaction. Unlike synchronous API calls where your application requests information and waits for an immediate response, the callback process works in the background. The payment system will automatically send a POST request to your callback URL once a transaction is complete, whether successful or unsuccessful, including the initial payment or related actions such as partial/full refunds, preauthorization approvals, and split payments. The logic for receiving and processing this callback must be implemented on the business side, including the validation for callback signature. Proper handling of the callback is a crucial step to confirm the payment status and securely update the order in your system. Payment details are sent to the callback URL, provided when the order was requested, using the POST method. To confirm successful receipt of the callback, the business should return HTTP CODE 200. If the callback is not successfully received, [the payment details method](https://api.bog.ge/docs/en/payments-addons/standard-process/get-payment-details) allows the business to check the payment status. # Request ### Header Parameters - `Callback-Signature` — string Signature generated by encrypting callback's request body with a `private key` using `SHA256withRSA` algorithm. In order to ensure integrity of callback data, business should verify signature using request body and `public key`. It is essential to execute this verification before the deserialization of the request body, ensuring that the order of fields remains unchanged. **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 Parameters - `event` — string The callback type. The value is always `order_payment`. - `zoned_request_time` — string The date and time the callback was sent in Coordinated Universal Time (UTC). It follows the format "YYYY-MM-DDTHH:MM:SS.ssssssZ". - `body` — object Contains order data, which includes the same fields as [payment details](https://api.bog.ge/docs/en/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™ on Business' Webpage Source: https://api.bog.ge/docs/en/payments-addons/external-orders/external-applepay # Apple Pay™ on Business' Webpage To add Apple Pay™ button on your webpage, following steps are required. First your webpage should be compliant with [Apple's requirements](https://developer.apple.com/apple-pay/acceptable-use-guidelines-for-websites/). Since Apple Pay button is added to your own webpage, instead of Bank of Georgia's, you need to configure the environment independently. For more information visit [Apple's configuration page](https://developer.apple.com/documentation/apple_pay_on_the_web/configuring_your_environment). Add the Apple Pay certificate on your website. Download certificate [here](https://webstatic.bog.ge/apple-developer-merchantid-domain-association). See the detailed instruction [here](https://developer.apple.com/documentation/applepaywebmerchantregistrationapi/preparing_merchant_domains_for_verification). After adding the certificate, please, write to this email address [ecommercemerchants@bog.ge](mailto:ecommercemerchants@bog.ge) and provide your domain and your API Public Key. After these steps you can make Bank payments through Apple Pay button on your page. For creating order see [Standard Process - Order Request](https://api.bog.ge/docs/en/payments-addons/standard-process/create-top-up-order) :::note [`Body`](https://api.bog.ge/docs/en/payments-addons/standard-process/create-top-up-order#body-parameters) should contain following parameters: ```json "payment_method": ["apple_pay"], "config": { "apple_pay": { "external": true } } ``` ::: ### Response - `id` — string Order identifier. - `result` — json The result returned by Apple when initiating payment. - `_links` — object The web resource addresses are used in the further stages of the payment process. At the moment following resource is returned: - `_links.accept.href` — string The address for accepting payment. It is necessary to call this service for completing Apple Pay payment. **RESPONSE** ```json { "id": "{order_id}", "result": {...}, "_links": { "accept": { "href": "https://api.bog.ge/payments/v1/ecommerce/orders/{order_id}/payment" } } } ``` --- # Apple Pay™ Accept Payment Source: https://api.bog.ge/docs/en/payments-addons/external-orders/complete-external-applepay # Apple Pay™ Accept Payment Calling this service is required to complete Apple Pay™ payment initiated on business' webpage. ### Header parameters - `Content-Type` — application/json, required - `Authorization` — Basic , required `Bearer `, where `jwt_token` is the token returned in the `access_token` parameter of the authentication method response. - `Idempotency-Key` — UUID v4 The `Idempotency-Key` parameter should be unique for each new API request. Subsequent requests to the same API endpoint with the same `Idempotency-Key` header will result in the server returning the same status code and response body as the initial request. This functionality is particularly useful to ensure consistent outcome in scenarios where network issues or retries may lead to duplicate requests. ### Path parameters - `order_id` — string, required The order identifier returned in response to the order request. ### Body parameters - `apple_pay_token` — string, required Apple token. **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 Order identifier. - `status` — string Order status. - `order_details` — object Order details. Contains same data as [payment details](https://api.bog.ge/docs/en/payments-addons/standard-process/get-payment-details#response). - `_links` — object The web resource addresses are used in the further stages of the payment process. At the moment following resources are returned: - `_links.details.href` — string The address of the payment details can be used to obtain information on the online payment. **RESPONSE** ```json { "id": "{order_id}", "status": "completed", "order_details": {...}, "_links": { "details": { "href": "https://api.bog.ge/payments/v1/receipt/{order_id}" } } } ``` --- # Response Codes Source: https://api.bog.ge/docs/en/payments-addons/response-codes ## Payment Response Codes | Code | Description (EN) | Description (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 | წარმატებული პრეავტორიზაცია | ## Action Response Codes | Code | Description (EN) | Description (GE) | |------|----------------------------------------------------------------------------------|----------------------------------------------------------------| | 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 | --- # Terms Used Source: https://api.bog.ge/docs/en/payments-addons/terms-used 1. Business - a retailer or service company, having an online/electronic system. 2. Online Payments Page - an online payments system, that allows you to easily build a payments' module into any type of business. 3. Callback - calling of the service chosen by the business from the banking system to provide updated information on the payment. 4. System Entering Credentials - a client’s identifier in the banking system (`client_id`) and a secret key (`secret_key`), given by the bank to the client upon its successful registration. 5. Card Number (PAN) - 16 digits given on the front side of the bank card. --- # Introduction Source: https://api.bog.ge/docs/en/link-payment/introduction ## Introduction The Bank of Georgia's Online Payment API offers a simple and secure method to integrate payment processing into digital platforms. Link Payment API allows merchants to create unique payment links that redirect customers to a bank-hosted page, streamlining the collection of payments through email, SMS, or any other digital channel. This robust, developer-friendly solution allows businesses to accept payments via VISA, Mastercard, and American Express cards, Apple Pay, Google Pay, payments via BOG APP and BOG loyalty points (Plus, MR). - **What it does**: The API's core goal is to simplify online payment acceptance for merchants. It solves the complexity of payment processing and reduces PCI DSS compliance scope by outsourcing the handling of sensitive card data to the bank's secure infrastructure. This enables businesses to request and receive payments efficiently without needing a traditional e-commerce checkout system. - **Key Features**: The API supports the creation of pre-orders (payment links), secure redirection to a payment page, and processing payments using cards, wallets and other payment methods. - **Supported Resources**: The primary resource is the `pre-order`. The API ecosystem also includes resources for handling refunds, checking payment details, and deactivating payment links. - **Eventing**: The system uses asynchronous webhooks - server-to-server callbacks to a merchant-specified `callback_url` to provide notifications on final payment outcomes, such as successful or failed transactions, refunds, payment link expirations. --- # Authentication and Authorization Source: https://api.bog.ge/docs/en/link-payment/authentication ## Authentication and Authorization This method allows businesses to undergo the authentication process. Upon calling the API, the online payment server returns the `Bearer Token`, which is the necessary authentication parameter for calling all further methods. ### OAuth 2.0 Client Credentials - **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` (seconds) **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 } ``` --- # Conventions & Common Headers Source: https://api.bog.ge/docs/en/link-payment/conventions ## Conventions - **Content types**: `application/json`; character set UTF-8 - **Date/time**: ISO 8601 with timezone offset or Z (e.g., `2026-04-21T13:45:00Z`) - **Ids**: UUID v4 unless otherwise specified - **Idempotency**: `Idempotency-Key` header for POST/PUT with retry safety - **Localization**: `Accept-Language` header (`ka`, `en`) ## Common Headers - `Authorization: Bearer ` - `Content-Type: application/json` - `Accept: application/json` - `Idempotency-Key: ` (optional but recommended) - `Accept-Language: ka|en` (optional) --- # Create Pre-order Source: https://api.bog.ge/docs/en/link-payment/link-payment-api/create-pre-order The `create pre-order` endpoint generates a unique payment link based on the provided transaction details. This link redirects the customer to a secure, bank-hosted page where they can complete their payment using various methods. **Method:** `POST /v1/preorder` **Headers:** See [Common Headers](https://api.bog.ge/docs/en/link-payment/conventions#common-headers) #### Request Parameters - `callback_url` — string, required The HTTPS URL where the bank's server sends asynchronous callbacks with the final transaction status. - `description` — string, required A brief description of the order or service. - `external_order_id` — string A unique order identifier generated by the merchant's system. - `purchase_units` — object, required An object with payment amount and currency details. - `purchase_units.currency` — string, required The three-letter currency code (e.g., 'GEL'). - `purchase_units.total_amount` — number, required The total transaction amount. - `ttl` — integer Time to live in minutes for which the pre-order link remains valid. Minimum: 2 min. Maximum: 1440 min (24 hours). Default: 15 min. **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 Parameters - `id` — string A unique identifier for the pre-order generated by the bank's system. This ID can be used for future references, such as checking the payment status. - `_links` — object A container for hypermedia links related to the resource. - `_links.payment_link` — object An object containing the URL for the customer to complete the payment. - `_links.payment_link.href` — string The fully qualified URL redirects the customer to the secure, bank-hosted payment page. **RESPONSE** ```json { "id": "c0fb0f1d-7715-485a-b753-10cf148708e3", "_links": { "payment_link": { "href": "https://link.bog.ge/HnisFqRnzJz" } } } ``` --- # Get Pre-Order Detail Source: https://api.bog.ge/docs/en/link-payment/link-payment-api/get-pre-order-detail This endpoint retrieves the current status and detailed information for a specific pre-order that has already been created. By providing the unique pre_order_id, a merchant can check whether a payment link is still active, has been paid, or has expired, and view the associated transaction details. **Method:** `GET v1/pre-orders/{pre_order_id}/detail` #### Headers: See [Common Headers](https://api.bog.ge/docs/en/link-payment/conventions#common-headers) - `Authorization` — Bearer Token, required Required. The JWT access_token for authenticating the API call. #### Path Parameters - `pre_order_id` — string, required Required. The unique identifier of the pre-order, which was returned when the pre-order was created. #### Response Parameters - `pre_order_id` — string The unique identifier for the pre-order. - `zoned_create_date` — string The date and time when the pre-order was created, in UTC (ISO 8601 format). - `zoned_expire_date` — string The date and time when the pre-order is set to expire, in UTC (ISO 8601 format). - `pre_order_status` — object An object containing the current status of the payment link itself. - `pre_order_status.key` — string Preorder status key: `active`, `performed`, `deactivated`, `expired` - `pre_order_status.value` — string Preorder status description. - `transaction_status` — object / null The status of the associated payment transaction. This will be null if no payment attempt has been made. - `payment_detail` — object An object containing details about the payment method used. - `payment_detail.transfer_method` — object The method used for the transfer (e.g., card payment). - `payment_detail.transfer_method.key` — string Key for the payment method: `card`, `google_pay`, `apple_pay`, `bog_p2p`, `bog_loyalty` - `payment_detail.transfer_method.value` — string Payment method description - `payment_detail.transaction_id` — string / null RRN - The unique identifier for the payment transaction, if one has occurred. - `payment_detail.payer_identifier` — string / null An identifier for the payer, such as a masked card number. - `payment_detail.order_id` — string / null UUID - The unique identifier of the payment transaction, if one has occurred, generated by bank's system. - `purchase_units` — object An object containing the monetary amounts associated with the pre-order. - `purchase_units.request_amount` — string The original amount requested in the pre-order. - `purchase_units.transfer_amount` — string / null The amount that was successfully transferred. - `purchase_units.refund_amount` — string / null The amount that has been refunded, if any. - `purchase_units.currency_code` — string The three-letter currency code for the transaction (e.g., "GEL"). - `purchase_units.items` — array / null A list of items included in the purchase. null if not provided. - `lang` — string The language setting for the payment page (e.g., "ka" for Georgian). - `invoice_payment_url` — string The short URL for the payment page (payment link). - `description` — string The original description provided when the pre-order was created. - `external_order_id` — string The merchant-provided unique identifier for the order. **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/en/link-payment/link-payment-api/deactivate-pre-order # Deactivate Pre-Order This endpoint allows a merchant to deactivate an active payment link before its scheduled expiration time. Once deactivated, the link will no longer be valid, and the customer will not be able to access the payment page to complete the transaction. - `Method` — POST The HTTP method used for this endpoint. - `Endpoint URI` — string `/v1/pre-order/{pre_order_id}/deactivate` - `Description` — string Deactivate an active pre-order link, preventing any future payment attempts. #### Path Parameters - `pre_order_id` — string, required The unique identifier of the pre-order to be deactivated. #### Headers: See [Common Headers](../conventions#common-headers) - `Authorization` — Bearer Token, required The JWT `access_token` for authenticating the API call. #### Request Body The request for this endpoint does not require a body. #### Response (200 OK): A successful deactivation will return a confirmation message. - `result` — object An object containing the outcome of the deactivation request. - `result.key` — string Key indicating the result (e.g., "success"). - `result.message` — string Result description. ```json { "result": { "key": "success", "message": "Successful pre-order deactivation" } } ``` --- # refund-pre-order Source: https://api.bog.ge/docs/en/link-payment/link-payment-api/refund-pre-order # Refund Pre-Order This endpoint initiates a refund for a previously completed transaction associated with a specific pre-order. The process is asynchronous, meaning the API confirms receipt of the refund request, and the actual processing of the refund occurs in the background. - `Method` — POST The HTTP method used for this endpoint. - `Endpoint URI` — string `/pa-payment-services-public/v1/pre-order/refund/{pre_order_id}` - `Description` — string Submits a request to refund a specified amount for a successful payment. #### Path Parameters - `pre_order_id` — string, required The unique identifier of the pre-order for which the refund is being requested. #### Headers: See [Common Headers](https://api.bog.ge/docs/en/link-payment/conventions#common-headers) - `Authorization` — Bearer Token, required The JWT `access_token` for authenticating the API call. - `Content-Type` — string, required Must be set to `application/json`. #### Request Body - `amount` — number, required The specific amount to be refunded. This can be a partial or full amount of the original transaction. ```json { "amount": 50.00 } ``` #### Response (202 Accepted) A successful response indicates that the refund request has been accepted for processing. - `key` — string A key indicating the status of the request (e.g., "request_received"). - `message` — string A message confirming that the refund request has been received and is being processed. - `action_id` — string A unique identifier for the refund action. ```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/en/link-payment/callback ## Callback A callback is an asynchronous, server-to-server notification sent from the payment system to your designated `callback_url`. Its purpose is to reliably inform your system about the final status of a transaction (e.g., successful payment, refund). This process is crucial for securely confirming payment status and automating order updates, as it operates independently of any user action and guarantees data delivery. Upon receiving a callback, your system must validate the included signature to ensure data integrity and then respond with an HTTP `200 OK` status to acknowledge successful receipt. ### Request Description (Incoming Callback) The payment system will send an HTTP POST request to the callback_url you specified when creating the pre-order. This request contains the final status and details of the transaction. #### Header | Header | Type | Description | |--------|------|-------------| | Callback-Signature | String | **Optional but Recommended.** A Base64-encoded signature generated by encrypting the raw request body with the bank's private key using the SHA256withRSA algorithm. You must verify this signature with the provided public key to ensure the callback's authenticity and data integrity. | #### Request Body | Parameter | Type | Description | |-----------|------|-------------| | event | String | The type of notification. For payment status updates, the value is consistently `link_payment`. | | zoned_request_time | String | The timestamp indicating when the callback was sent, formatted in UTC (e.g., "YYYY-MM-DDTHH:MM:SS.ssssssZ"). | | body | Object | An object containing the full order and payment detail data, similar to the response from the "Get Pre-Order Detail" endpoint. | **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" } } ``` --- # Terms Used Source: https://api.bog.ge/docs/en/link-payment/glossary 1. **Client Credentials** — OAuth 2.0 flow where the client authenticates as itself 2. **Idempotency** — Safe retry mechanism that prevents duplicate side effects 3. **TTL** — Time to Live; message lifetime in channel --- # Introduction Source: https://api.bog.ge/docs/en/paymentgateway/introduction :::caution NOTICE The document is intended for service-providers. ::: ## What is Payment Gateway? Payment Gateway is an online service that allows businesses and individuals to accept payments from customers through their websites or mobile applications. ## Purpose The following document contains information about communication methods, available operations, exchange formats, authentication, pre-defined parameters & status codes, etc. ## Protocol Description The document describes a system, in which a user will interact with a service-provider via an interface. More specifically, the user may issue a web request to the service-provider through the BOG server, to which the service-provider will be obliged to respond. The received response will be processed by BOG and be displayed to the user. The user may execute an arbitrary amount of operations. Additionally, some payment channels will restrict this number to two operations (information about debt and/or payment), although this can be bypassed at the expense of the time it takes to integrate the service. The protocol will work in conjunction with a web-app, which will give service-providers the ability to define multiple operations per a single payment flow via an interface. All service providers will have the ability to customize both the number and the characteristics of each operation based on their service. ## Requirements for the Service-Provider The service-provider is required to set up a web-server, which can either be publicly accessible or only available through a VPN channel. In case the web-server is publicly accessible, it is required that it supports HTTPS. The service-provider is allowed to use any API endpoint of their choice. E.g. http://serviceprovider:8088/api/mock The following HTTP methods can be defined on custom operations: GET, POST, PUT, PATCH & DELETE; although BOG will not use the HTTP request body to transfer any information for custom operations, regardless of the HTTP method chosen by the service-provider. --- # Authentication Source: https://api.bog.ge/docs/en/paymentgateway/authentication ## About This section defines different types of authentication methods supported by the BOG protocol. It is mandatory that a service-provider uses one of the authentication methods listed here. Moreover, it is recommended to use multiple authentication methods at once to increase security. ## Risks This document does not aim at assessing risks imposed on the participants of the payment system in relation to electronic payments and respective responsibilities. The document describes the security regimes applicable to protect the payment system. ## Supported Methods - [HTTP Basic](https://api.bog.ge/docs/en/paymentgateway/auth-methods/basic) - [OAuth 2.0 - Client Credentials](https://api.bog.ge/docs/en/paymentgateway/auth-methods/oauth2) - [API Key](https://api.bog.ge/docs/en/paymentgateway/auth-methods/apikey) - [HMAC-SHA256](https://api.bog.ge/docs/en/paymentgateway/auth-methods/hmac-sha256) --- # HTTP Basic Source: https://api.bog.ge/docs/en/paymentgateway/auth-methods/basic If the service-provider chooses to use the [HTTP Basic Auth](https://datatracker.ietf.org/doc/html/rfc7235) authentication method, then the former must accept the Authorization header whose value follows the Basic authentication format. More specifically, the header value will be of the form: `Authorization: Basic ` where credentials is the Base64 encoding of username and password joined by a single colon “:” (e.g. user:pass). ### Header Parameters - `Authorization` — Basic , required Pass in „Basic „ + „:“ value encoded in Base64 format. (e.g.: `Basic ODI4Mjo3Njk3MDY0OTlmMDcwOWUyMzQ4NDU4NjNmOThiMjMxNA==`), where & are the credentials that the service-provider hands to BOG. --- # OAuth 2.0 - Client Credentials Source: https://api.bog.ge/docs/en/paymentgateway/auth-methods/oauth2 The service-provider may create an authorization web-service, which supports the OAuth 2.0 ([D. Hardt, Ed., 2012](https://datatracker.ietf.org/doc/html/rfc6749)) Client Credentials grant type. BOG will use an HTTP POST request method for communication with the authorization endpoint. ### Header Parameters - `Content-Type` — application/x-www-form-urlencoded, required ### Body Parameters - `grant_type` — client_credentials, required The value is a static text: `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 The service-provider must return the following JSON response: - `access_token` — string The Token received from the authorization server. - `created_at` — string UNIX timestamp – the amount of milliseconds that have passed since January 1st, 1970 at UTC . - `expires_in` — number The number of seconds while the token stays active. - `token_type` — number Token type (A static value - `Bearer`). **RESPONSE** ```json { "access_token": "xx82194x21412xxx219124x678x888x2xxx1900xx", "created_at": 1693236686855, "expires_in": 300, "token_type": "Bearer" } ``` For any subsequent calls to the API, when the token is valid, BOG will use the HTTP header of the form: - `Authorization` — Bearer , required „Bearer „ + „<token>“ (e.g.: „Bearer xx82194x21412xxx219124x678x888x2xxx1900xx“), where `token` is the value returned from the service-provider's authorization endpoint. --- # API Key Source: https://api.bog.ge/docs/en/paymentgateway/auth-methods/apikey The service-provider may provide BOG with an API Key that will be used within each operation. If the key is given, then each operation will contain a header with the format: - `Auth-Key` — , required `API_KEY` is the key given by the service-provider. --- # HMAC-SHA256 Source: https://api.bog.ge/docs/en/paymentgateway/auth-methods/hmac-sha256 The service-provider can additionally provide BOG with a secret key for hashing, which will be used for hashing the request body for HTTP POST & PATCH requests, or in the case of HTTP GET, PUT & DELETE requests – for hashing the query. If the aforementioned parameter is provided, the service provider must accept the Hash header and verify it. The HMAC-SHA256 algorithm will be used for hashing, where HMAC-SHA256 refers to the Hash-based Message Authentication Code ([Krawczyk, Bellare, Canetti, 1997](https://www.ietf.org/rfc/rfc2104.txt)) encryption method in conjunction with a secret key and a cryptographic function – SHA256 ([Eastlake, E. Huawei, Hansen, 2011](https://datatracker.ietf.org/doc/html/rfc6234)). Additionally, the hash code will only contain capital letters and digits, in hexadecimal format. - `Hash` — , required `HASH` is the HTTP Request Body or the Query passed through the hashing algorithm. E.g. if given the secret key: `8bbe50a7d61af79211148c09e40e1bffaefdf319dce665bc5a31b55ec28a508b` And if the HTTP GET request is of the form: `http://serviceprovider:8088/api/mock/get-categories?personalNumber=01234567890&birthDate=11.01.2002` Then the value to hash (i.e. the query, since it’s a GET request) will be: `personalNumber=01234567890&birthDate=11.01.2002` Which will result in the following hash code: `841A782048F51A798331E4A534A240911D541B869CB0E2CF1BB58F086873C079` --- # Custom Operations Source: https://api.bog.ge/docs/en/paymentgateway/operations :::caution NOTICE Custom operations are optional. I.e. the service-provider may not define any custom operations at all. ::: ## Mandatory Standards for Variables In order to maintain company-wide standards, BOG requires that service-providers use specific variable names that correspond with their respective meaning. E.g. if a customer uses their personal number to receive some information (e.g. debt) from the service-provider, then the latter must use personalNumber as the name of the variable required by the API. View the full list of mandatory variable standards below: - **personalNumber** – used as a personal number identifier. - **customerId** – used as a customer identifier. - **debt** – the amount owed by the customer to the service-provider in minor units. - **debtList** – A list of data models that contain the amounts (and possibly other fields) owed by the customer to the service-provider in minor units. - **amount** – the amount that the customer is willing to pay in minor units. ## Data Exchange Format All custom operations that communicate with the service provider’s API will send all request parameters as query parameters,along with the header values used for authentication. The service provider must respond with a pre-defined format for each operation: - `status.code` — number Refers to the pre-defined [status codes](https://api.bog.ge/docs/en/paymentgateway/error-codes). - `status.value` — string Status value (optional) - `timestamp` — number UNIX timestamp – the amount of milliseconds that have passed since January 1st, 1970 at UTC . - `receiptId` — string receiptId is a unique identifier of the payment, returned from the service-provider after a successful payment operation (optional). - `response` — object The JSON data returned from some arbitrary operation. It is required for every custom operation. **RESPONSE** ```json { "status":{ "code":0, "value":"OK" }, "timestamp":1693236686855, "receiptId":"", "response":{"wrapper":{"categoryCodes":["A1","B"]}} } ``` :::note Along with the custom operations created by the service-provider, there also exist pre-defined operations by BOG, from which only the [Payment](https://api.bog.ge/docs/en/paymentgateway/pre-defined-ops/payment) operation is required, all others are optional. ::: --- # Payment Source: https://api.bog.ge/docs/en/paymentgateway/pre-defined-ops/payment Any number of operations can be defined by the service provider, howbeit, the payment operation with the key payment will always be executed at the end of the operation chain if the user decides to go through with the payment. Therefore, the service provider is obliged to provide an implementation for the payment operation. Additionally, the Georgian Tetri is assumed to be the default currency. ### Body Parameters - `transactionId` — string, required An unique transaction identifier, created by BOG. - `amount` — number, required Amount in minor units (e.g. Georgian Tetri, American Cent, etc.). - `currency` — string, required Currency ([ISO 4217 currency code](https://www.iban.com/currency-codes)), E.g. `GEL`. - `parameters` — object, required An object, that contains `key` & `value` pairs, where `key` is the name of the parameter, and `value` - the value of the parameter. **REQUEST BODY** ```json { "transactionId": "00000000", "amount": 500000, "currency": "GEL", "parameters": { "personalNumber": "01234567890", "birthDate": "11.01.2002" } } ``` ### Response The service-provider must respond with the following JSON format: - `status.code` — number Refers to the pre-defined [status codes](https://api.bog.ge/docs/en/paymentgateway/error-codes). - `status.value` — string Status value (optional) - `timestamp` — number UNIX timestamp – the amount of milliseconds that have passed since January 1st, 1970 at UTC. - `receiptId` — string receiptId is a unique identifier of the payment, returned from the service-provider after a successful payment operation (optional). **RESPONSE** ```json { "status":{ "code":0, "value":"OK" }, "timestamp":1693236686855, "receiptId":"1234" } ``` --- # Payment Status Source: https://api.bog.ge/docs/en/paymentgateway/pre-defined-ops/payment-status When the payment-status operation is invoked by BOG, the service-provider is expected to respond with one of the following status codes: [12, 13, 14](https://api.bog.ge/docs/en/paymentgateway/error-codes). ### Body Parameters - `transactionId` — string, required An unique transaction identifier, created by BOG. **CURL** ```bash curl --location --request GET 'http://serviceprovider:8088/api/mock/payment-status?transactionId=00000000' ``` ### Response The service-provider must answer in the following JSON format: - `status.code` — number Refers to the pre-defined [status codes](https://api.bog.ge/docs/en/paymentgateway/error-codes). - `status.value` — string Status value (optional) - `timestamp` — number UNIX timestamp – the amount of milliseconds that have passed since January 1st, 1970 at UTC. **RESPONSE** ```json { "status":{ "code":12, "value":"Transaction was successful" }, "timestamp":1693236686855 } ``` --- # Cancel Payment Source: https://api.bog.ge/docs/en/paymentgateway/pre-defined-ops/cancel-payment When invoking the cancel-payment operation, the service-provider is expected to cancel the payment with the given transaction identifier from BOG. ### Body Parameters - `transactionId` — string, required An unique transaction identifier, created by BOG. **CURL** ```bash curl --location --request GET 'http://serviceprovider:8088/api/mock/cancel-status?transactionId=00000000' ``` ### Response The service-provider must answer in the following JSON format: - `status.code` — number Refers to the pre-defined [status codes](https://api.bog.ge/docs/en/paymentgateway/error-codes). - `status.value` — string Status value (optional) - `timestamp` — number UNIX timestamp – the amount of milliseconds that have passed since January 1st, 1970 at UTC. **RESPONSE** ```json { "status":{ "code":0, "value":"OK" }, "timestamp":1693236686855 } ``` --- # Send Payment Info Source: https://api.bog.ge/docs/en/paymentgateway/pre-defined-ops/send-payment-info The send-payment-info operation will be executed once at the end of the day and will send information about successful payments that took place the day before the request (span of 24 hours), according to the UTC+4h (Tbilisi) time zone. Since the request body contains both the summary & individual information about payments, there is a risk that the request body might reach a size limit. Because of this, the send-payment-info operation will be executed in batches, where the timespan of nth batch starts at Tn (inclusive), and the timespan of n-1th batch ends at Tn (inclusive), where Tn-1 < Tn. I.e. batches will be sent subsequently based on subsets of a 24 hour timespan. Moreover, in case of failure to send the data per batch, a retry will be attempted once. ### Body Parameters - `timezoneId` — string, required [Time Zone Identifier.](https://docs.oracle.com/middleware/1221/wcs/tag-ref/MISC/TimeZones.html) - `timespan.from` — number, required (Inclusive) UNIX timestamp – the amount of milliseconds that have passed since January 1st, 1970 at UTC. - `timespan.to` — number, required (Exclusive) UNIX timestamp – the amount of milliseconds that have passed since January 1st, 1970 at UTC. - `summary[?].totalAmount` — string, required Amount in minor units (e.g. Georgian Tetri, American Cent, etc.). - `summary[?].currencyCode` — string, required [Currency](https://www.iban.com/currency-codes) - `summary[?].count` — string, required ტრანზაქციების რაოდენობა. - `paymentList[?].transactionId` — string, required An unique transaction identifier, created by BOG. - `paymentList[?].currencyCode` — string, required [Currency](https://www.iban.com/currency-codes) - `paymentList[?].amount` — string, required Amount in minor units (e.g. Georgian Tetri, American Cent, etc.). **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 The service-provider must answer in the following JSON format: - `status.code` — number Refers to the pre-defined [status codes](https://api.bog.ge/docs/en/paymentgateway/error-codes). - `status.value` — string Status value (optional) - `timestamp` — number UNIX timestamp – the amount of milliseconds that have passed since January 1st, 1970 at UTC. **RESPONSE** ```json { "status":{ "code":0, "value":"OK" }, "timestamp":1693236686855 } ``` --- # Expected Response Times Source: https://api.bog.ge/docs/en/paymentgateway/expected-response-times The expected response times, or the response time limits for each operation, are defined below. - **OAuth Client Credentials** – 15 seconds. - **Custom Operations** – 10 seconds. - **Payment** – 30 seconds. - **Payment Status** – 15 seconds. - **Cancel Payment** – 15 seconds. - **Send Payment Info** – 60 seconds. If the service-provider does not return an answer within the given time frame per operation, it is assumed that the request has failed. --- # Definitions, Acronyms & Abbreviations Source: https://api.bog.ge/docs/en/paymentgateway/terms-used - **BOG** - Bank Of Georgia - **Service-Provider** - A company providing a service for certain payment and willing to be paid through the BOG payment system. - **Customer** - A person using the BOG user interface to connect to the service provider, receive information about debt, make payments, etc. --- # Exception Cases Source: https://api.bog.ge/docs/en/paymentgateway/error-flow This section contains information regarding the different routes the BOG payment system could take depending on the given circumstances within the payment operation. Keep in mind, how BOG handles the “TRANSACTION IN PROGRESS” status ([code 14](https://api.bog.ge/docs/en/paymentgateway/error-codes)) is subject to change. ![Exception Cases Routes](./media/protocol-error-flow.png) --- # Error Codes Source: https://api.bog.ge/docs/en/paymentgateway/error-codes |Code | Description | |-----|--------------------------------| |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| A Service-provider may also introduce other error codes not listed in this table. Such codes must not be within 0-99 range. It is noteworthy that the BOG payment system does not guarantee to a service-provider that the text relevant for the code sent by the latter (except for the values set forth by this document) shall be seen by all users. Therefore, returning service-provider-generated codes is only recommended in exceptional cases. --- # Authentication Source: https://api.bog.ge/docs/en/installment/authentication # Authentication ⚠️(Deprecated) ## What is needed to use the Installment Loan API An HTTP Basic Authentication is needed to use an Installment Loan API. To do so, you need to know the credentials for accessing the system which is unique for each Merchant. The credentials consist of two parameters: client_id and secret_key, which are used as a username and a password for the Merchant Authentication. The company receives those credentials once it has been registered in the Bank system as a Merchant and has filled in all necessary data. (see: [How to find out the Merchant’s system credentials](introduction#how-to-find-out-the-merchants-system-credentials)) Example: ```properties client_id: 1006 secret_key: 581ba5eeadd657c8ccddc74c839bd3ad Header: Authorization: Basic MTY2Njo1ODFiYTVlZWFkZDY1N2M4Y2NkZGM3NGM4MzliZDNhZA== ``` ### Method Description Via the given method a Merchant passes the authentication. On calling this method, the Online Installment Loan Server returns a ‘Bearer Token’ which is used as a mandatory parameter for the authentication when calling all further methods. ### Header - `Content-Type` — application/x-www-form-urlencoded, required - `Authorization` — Basic , required `Basic` + `:` coded in a Base64 format (i.e: „Basic ODI4Mjo3Njk3MDY0OTlmMDcwOWUyMzQ4NDU4NjNmOThiMjMxNA==“). where and are a Merchant’s system access credentials provided by the Bank ### Body - `grant_type` — client_credentials, required A `client_credentials` text should be always passed in this parameter **http** ```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 A token returned by the Authorization Server - `token_type` — string A token type (The text „bearer“ is always returned) - `app_id` — string not used - `expires_in` — number A number of seconds for which the Token is active **response** ```json { "access_token": "", "token_type": "Bearer", "app_id": "1A2019", "expires_in": 1634719923245 } ``` --- # Callback Source: https://api.bog.ge/docs/en/installment/callback # Callback ⚠️(Deprecated) Unlike the previous methods which are called by the Online Shop, `Callback` is called by an Online Installment loan System, while the information should be received and processed on an Online Shop side. This method gives a possibility to receive real-time information about the status change. Callback URLs are assigned to each Online Shop when the latter is registered as a Merchant in a Bank system. Two kinds of `Callback` URLs can be assigned in a Payment System to a Merchant: - [After the Installment Loan Status Change](#installment-loan-status-change-callback) - [After the Installment Loan Cancelation](#installment-loan-cancelation-callback) After that each time when the Payment Status is changed, the Payment Details are sent via POST method on a Callback URL. To confirm the successful receiving of a Callback method response, a Merchant should return an HTTP CODE 200. In case of the unsuccessful result of sending via POST method of the Callback, the method is called again with 15-second intervals until the number of attempts reaches 5 or Merchant returns an HTTP CODE 200 status. In case the Callback could not be successfully called (on a timeout or if Merchant responded with a code other than 200 HTTP code), a customer will be redirected to the reject_redirect_url and a callback is not sent anymore. In this case, the merchant should call an Installment Loan Details method to receive the status of the installment loan. :::note If you already use an [Online Payment](https://api.bog.ge/docs/en/docs/ipay/introduction), the URL of the Installment Loan Callback will be the same as in the case of Online Payment, however, the parameters will be different. ::: ### Body: - `status` — string An installment loan status. Can take the following values: - success – An installment loan process has been completed successfully. - error - An installment loan process has been completed un-successfully - `order_id` — string An order identifier that is returned to the Online Shop in the response of the Order request method. - `shop_order_id` — string A Merchant’s payment identifier. - `payment_method` — string A payment method. In the case of the installment loan, the `BOG_LOAN` value is always returned. **request** ```api POST / An URL assigned to an Online Shop when registered as a Merchant in a Bank system 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 A method call is considered successful when a 200 HTTP status is received from a Merchant’s server **response** ```json { "Http_Status":"200 OK" } ``` ### Installment Loan Status Change 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 ``` ### Installment Loan Cancelation 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 ``` --- # Order Request Source: https://api.bog.ge/docs/en/installment/create-order # Order Request ⚠️(Deprecated) By calling this method an Online Shop sends the payments details, technical parameters, and a payment amount to an Installment Loan Server. To proceed further in case of the successful operation, a customer should be redirected to an Online Payment Webpage as per a `REDIRECT` URL returned in a `links` parameter ### Header - `Content-Type` — application/json, required - `Authorization` — Bearer , required `Bearer `, where the jwt_token is a value returned in an access_token parameter from the Authentication Method Response ### Body - `intent` — string, required defines which payment method is used by the customer for payment. When using the Installment Loan Integration `LOAN` value should be always passed in this element - `installment_month` — string, required An installment loan duration in months selected by the customer. To receive the installment loan duration in months and type you should use a [loan calculator](get-discounts.md) service - `installment_type` — string, required An installment loan type selected by the customer - `shop_order_id` — string, required A Payment Identifier from an Online Shop system (i.e.: An ID of a shopping Basket). - `success_redirect_url` — string, required An address (URL) of a webpage of the Online Shop to which a customer will be redirected on the successful activation of the installment loan. After the activation of the installment loan, a callback is sent to a Merchant which should return a `200` HTTP code and upon receiving this code a customer will be redirected to the success_redirect_url. A customer will be redirected to the `reject_redirect_url` if the Merchant returns a code other than 200 HTTP as a response on a callback. In this case, the status will remain ‘success’ and Merchant should call an Installment [Loan Details](installment-details.md) Service to retrieve an updated status - `fail_redirect_url` — string, required An address (URL) of a webpage of the Online Shop to which a customer will be redirected if the activation of the installment loan fails - `reject_redirect_url` — string, required An address (URL) of a webpage of the Online Shop to which a customer will be redirected in case of a failure other than the activation of the installment loan or if Merchant returns a code other than 200 HTTP as a response on a callback, or if a callback has a timeout response - `validate_items` — boolean Based on this parameter a total amount of the products cost from the cart is compared to a total amount of an order. Value if omitted: `true` - `true` a total amount of the products cost from the cart will be compared to a total amount of an order and an error will occur in case of difference - `false` a total amount of the products cost from the cart will not be compared to a total amount of an order, but the cost of each product from the cart should be greater than 0 - `locale` — ka defines the language of the Online Installment Loan Webpage on which a customer will be redirected. At the moment it may have only a `ka` – Georgian value - `purchase_units` — array, required contains information about the Installment Loan Amount and currency - `amount` — object, required An Installment Loan Amount object - `currency_code` — string, required An Installment Loan currency - `value` — number, required An Installment Loan Amount value - `cart_items` — array, required A list of the products purchased in the Online Shop within the given payment which contain a following attributes - `total_item_amount` — string, required A total cost of products. E.x. if a product price is 50 GEL and a quantity is 2, then 100 should be passed in this parameter - `item_description` — string, required A name of the purchased product (description) - `total_item_qty` — number, required A quantity of the purchased products - `item_vendor_code` — string, required An ID of the purchased product in the Online Shop System - `product_image_url` — string A URL of the product image - `item_site_detail_url` — string A product page URL on the Online Shop webpage **request** ```api POST /v1/installment/checkout 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 A status of the online installment loan - `links` — array URLs that are used on the further steps of the installment loan process. Currently, the `links` parameter may return one of these two resources: - An installment loan details URL allows retrieving information regarding the installment loan (the ‘rel’ parameter of this resource has a value ‘self’) - A URL on which a customer should be redirected to enter the credentials of the online banking and finalize the installment loan process (the ‘rel’ parameter of this resource has a value ‘target’) - `href` — string A Web resource Address - `rel` — string A Web resource unique name - `method` — string An HTTP method that should be used to redirect on the web resource (GET, REDIRECT…) - `order_id` — string An unique identifier of the online installment loan order **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}" } ``` --- # Control Panel Source: https://api.bog.ge/docs/en/installment/dashboard # Control Panel ⚠️(Deprecated) We created a panel for controlling the `Bank of Georgia’s` online installment loan. This control panel is a web application in which User logs in with the internet banking credentials for their business entity. Using our control panel User may follow the `Bank of Georgia’s` online installment loan operations performed from their e-commerce platform. Control Panel gives easy access to information such as installment loan details, their unique identifiers, the total cost of the cart, or its content. You also may request the cancellation of the installment loan from the Control Panel, or approve the cancellation request incoming from a customer’s mobile banking. We also provide statistics where you may check the rate of approval, activation, and cancellation of the installment loans. You also may find installment loan statistics by status and date on the Control Panel. Please visit the [merchant.bog.ge](https://merchant.bog.ge) to see our Control Panel. You should use your credentials from [bonline.bog.ge](https://bonline.bog.ge) ![Online Installment Dashboard](../assets/installment-dashboard.png) --- # Installment Loan Calculator Source: https://api.bog.ge/docs/en/installment/get-discounts # Installment Loan Calculator ⚠️(Deprecated) Before [requesting an order](create-order.md), a customer must choose the installment loan duration and the discount method. Thus before calling the [Order Request](create-order.md) service, you should use a calculation method which based on the cost of the product will return a list containing the combination of all allowed loan duration (in months) with type and monthly payment amounts. You should pass the terms selected by a customer from the ones available in the returned list. You also may use our [JS SDK](modal.md) to retrieve this list. :::note Discount type and loan duration is assigned to each Merchant individually. Thus different Merchants might receive different values in the list. ::: ### Header - `Content-Type` — application/json, required - `Authorization` — Bearer , required `Bearer `, where the jwt_token is a value returned in an access_token parameter from the Authentication Method Response ### Body - `amount` — object, required A total amount of the installment loan - `client_id` — string, required A Merchant’s unique identifier is provided to a Company once it has been successfully registered **http** ```api GET /v1/services/installment/calculate HTTP/1.1 ``` ```properties amount=1000.00 client_id=1006 ``` ### Response - `discounts` — array A list of all allowed conditions within the given installment loan which contains the following attributes: - `month` — number An installment loan duration in months - `amount` — string An installment loan monthly payment amount - `discounts` — string An installment loan discount code **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" } ] ``` --- # Installment Loan Details Receiving Source: https://api.bog.ge/docs/en/installment/installment-details # Installment Loan Details Receiving ⚠️(Deprecated) By calling this method an Online Shop can receive detailed information regarding the status of an installment loan completed by a customer based on the payment identifier. ### Header - `Content-Type` — application/json, required - `Authorization` — Bearer , required `Bearer `, where the jwt_token is a value returned in an access_token parameter from the Authentication Method Response **request** ```api POST /v1/installment/checkout/ HTTP/1.1 Content-Type: application/x-www-form-urlencoded Authorization: Basic ``` ## Response - `order_id` — string, required An order identifier that is passed in the Request of the given method. - `status` — string, required An Order Status. Can take the following values: - `success` - An installment loan process has been completed successfully - `in_progress` - An installment loan is in progress and is not completed yet and if in 45 minutes from the order generation a customer has not completed an installment loan process, the status will change to an `error`. - `error` - An installment loan process is unsuccessful. - `installment_status` — string, required An installment loan Status. - `success` - An installment loan was successfully activated. In this case, order status is also `success` - `reject` - An installment loan was not approved. In this case, order status is also an `error` - `reverse_success` - An installment loan is canceled based on the customer’s request or the Merchant canceled the installment loan from a [dashboard of the control panel](https://merchant.bog.ge/) - `fail` - An installment loan was not activated. In this case, the order status will be `error` - `unknown` - An installment loan will have this status if the installment loan is not completed and the order status is `in_progress` - `ipay_payment_id` — string, required A payment ID in the `ipay` system which is shown on a payment receipt - `shop_order_id` — string, required A Merchant’s order identifier - `payment_method` — string, required A payment method. In the case of the installment loan, the `BOG_LOAN` value is always returned **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" } ``` --- # Introduction Source: https://api.bog.ge/docs/en/installment/introduction # Introduction ⚠️(Deprecated) Ipay integration is no longer available. To integrate Bank of Georgia payment methods, please use the [Payment Manager technical documentation.](https://api.bog.ge/docs/en/docs/en/payments/introduction) ### What is an online installment loan API An installment loan is one of the important products in the retail business and it became especially in high demand in the digital world lately. Bank of Georgia introduces you to a simple integration solution. An online installment loan API allows you to easily embed an installment module into any kind of Online Shop or a Digital Payment System. ### What is needed for the integration o establish the integration, an Online Shop owner organization should have an account on [bonline.bog.ge](https://bonline.bog.ge) and unique credentials for accessing the system. Having an account on the [bonline.bog.ge](https://bonline.bog.ge) means that an organization holds an active account in the Bank of Georgia along with access to internet banking as a legal entity. ### Protocol and Technical Specifications API architecture: Restful Online Payment Application protocol: HTTP/1.1. To enhance security, it is mandatory to call all API methods using HTTPS, which is an extension of the HTTP protocol. Service call type: Synchronous Security protocol: OAuth 2.0 Information exchange security standard: JSON Web Tokens (JWT). **base** ```url https://installment.bog.ge/v1/ ``` ### How to find out the Merchant’s system credentials The company receives the client_id and the secret_key once it has been registered in the Bank system as a Merchant and has filled in all necessary data. To be registered as a Merchant, a company’s representative should fill the respective registration form or contact a Bank of Georgia’s employee and provide all necessary data. Those credentials are the unique identifier for the Merchant. Along with that, a secret_key is used as a password. It is prohibited to make it public or disclose to a third party. Violation might increase the likelihood of danger for an Online Shop! Secret_key cannot be changed by the Merchant. **base** ```properties client_id = XXXX (unique identifier for the Merchant) secret_key = XXXXXXXXXXXXXXXXXXXXXXXXXXXX (Api password) ``` :::caution It is prohibited to make **secret_key** public or disclose to a third party. Violation might increase the likelihood of danger for an Online Shop! ::: ### Preparatory work Below we introduce the brief overview of the full cycle of the Online Installment Loan registration and preparatory work: - Merchant fills in an API registration form on [bonline.bog.ge](https://bonline.bog.ge) which returns a client_id and secret_key which means that starting an integration process becomes technically possible. - Merchant chooses from one of the available integration approaches (simple integration, SDK, API) - Once the integration is completed testing of the full process on the test environment provided by the Bank of Georgia and making a test transaction is necessary - Merchant reflects respective information on the website/stock side upon a successful test transaction - After the above steps, test information will be replaced by a real one and an installment loan is ready to be launched! ### Short Description of a Process Below we introduce the brief review of the full cycle of the Online Installment Loan: - Customer presses an ‘Installment Loan’ button on the Online Shop webpage and chooses a loan duration and type (standard, discount, and 0%) - Online Shop sends a request to the Bank Server (order creation) - Bank Server returns the parameters needed for the payment along with the installment loan website redirection link `(https://installment.bog.ge/?order_id=xxx....xxx&locale=ka)` - The customer is redirected to the installment loan website - On the installment loan website, the actions needed for the activation of an installment loan are performed - The bank server returns a response to the Online Shop (callback) - Online Shop check the status of the installment loan and returns the respective HTTP code - Bank Server redirects the customer to the Online Shop Webpage by the received status (success, error) :::note [See quick and simple integration methods without writing code](plugins) ::: --- # An Online Installment Loan Module Source: https://api.bog.ge/docs/en/installment/modal # An Online Installment Loan Module ⚠️(Deprecated) We created a dedicated module to support selecting the terms of the online installment loan. The module in essence is a loan calculator where a customer may check the approximate monthly payment and the annual interest rate based on the cost of the shopping cart. It is important to provide such information to a customer since the installment loan terms always vary and are based on on the agreement between the Bank of Georgia and Merchant and the terms depend on a campaign (including the 0% installment loan) and they differ from a standard installment loan terms. All this information can be found in the Online Installment Loan Module helping support a customer in decision making. Thus before activating the installment loan, the loan calculator is needed, which is an independent microservise and [requires integration](authentication) with a Merchant’s website. Bank of Georgia offers you a ready SDK for the loan calculator which is compatible with all devices (Desktop, Mobile, Tablet) and requires adding a ready code snipped on the website. ![Online Installment Modal](../assets/installment-modal.png) ### მაგალითი: ### Integration To start the integration of the installment module SDK you should copy the below code into the HTML page. You should replace `{client_id}` by your client_id. ```html ``` --- ### Displaying the Modal You should use `BOG.Calculator.open` method for displaying the Online Installment modal. #### Parameters - `amount` — number, required A total amount of the installment loan - `onClose` — function A method which is called by SDK when a customer closes the modal - `onRequest` — function A method which is called by SDK after a customer chooses the terms. In such case the following arguments should be passed to the [Order Request](create-order) method: - `selected` - An object in which the terms chosen by a customer are passed - `amount` - A monthly payment amount of the installment loan - `month` - An installment loan duration in months - `discount_code` - A discount code of the installment loan - `successCb` - A method that should be called if you wish SDK to continue an installment loan process - `closeCb` - A method that should be called if you wish to close the module - `onComplete` — function onComplete (optional; function) – A method which is called after SDK finishes the online installment loan process. In this case, a customer is being automatically redirected to the success page of a merchant. If you wish to not have the redirection, you should pass `false` in the `return` parameter. This method receives an object with a redirectUrl parameter. - `redirectUrl` - URL on which a customer should be redirected. ### There are two methods to continue the process. 1. If you wish SDK to continue the process, you should call `successCb` in the `onRequest` method [after generating](create-order) the orderId, by passing this generated `orderId` parameter. After finishing the process you should call the `onComplete` method. 2. If you need the SDK only for the calculations and you wish to continue the process yourself after a customer chooses the terms, then you should pass `false` in the `return` parameter of the `onRequest` method. In such a case SDK will not continue the process anymore. The modal remains open and you have to call the `closeCb` or the `Bog.Calculator.close()` method if you wish to close the module. ```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 also gives you the possibility to add a Bank of Georgia’s button on your website. You should ```html
``` --- # Plugins and Technical Support Source: https://api.bog.ge/docs/en/installment/plugins # Plugins and Technical Support ⚠️(Deprecated) You do not necessarily have to be an experienced developer to establish an installment loan integration. Bank of Georgia cooperates with partner organizations that offer a product that is ready for use and requires only installation. A mandatory condition is that your Online Shop satisfies its technical requirements and is developed using the respective technology. 1. WooCommerce Payment Gateway is a plugin, which is ready for installation. A merchant needs an API Key for activating the plugin. You should consult with the documentation on [plugandpay.ge](https://plugandpay.ge/product/woocommerce-bog-installments-payment-gateway/) for full details. 2. A plugin for an Online Shop developed on a CScart system. You should consult with the documentation on [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/) for full details. 3. b2c is a platform that will help you to build a completely online platform on which an online installment loan of Bank of Georgia will be automatically available. Please visit [b2c.ge](https://www.b2c.ge/) for more information. --- # Regulations and Limitations Source: https://api.bog.ge/docs/en/installment/regulation # Regulations and Limitations ⚠️(Deprecated) Before familiarization with the regulations and limitations, it is crucial to distinguish two important conditions which apply to the person who takes an installment loan in the process of the Bank of Georgia’s installment loan. 1. A customer may have a pre-approved limit (a so-called **limit**) 2. A customer may not have a pre-approved limit at all or have an insufficient pre-approved limit. In such a case a customer requests a new application, which means that a customer should agree to check their information in the Credit Bureau and the Revenue Service (a so-called **application**) The process for a successfully approved application is similar. E.x. if a customer has an approved 200 GEL limit which is not sufficient for purchasing the desired item and the customer creates an application for the amount of 1000 GEL which in case of approval will be sufficient for the purchase, then after approval the initial limit (200 GEL) becomes 1000 GEL, and the process will continue following the normal flow. According to the rules of the National Bank of Georgia, it is also important that when a customer requests an installment loan with a 3-months duration with a monthly payment that exceeds the customer’s income factor, the system should automatically re-calculate the best possible terms applicable to that customer- meaning the duration for the given installment loan should be offered as close as possible to the initially requested one. In case if after approving an application is not sufficient for purchasing the desired item with any possible duration, a system should offer to the customer a down payment considering an automatically calculated factor. ### Regulations Before establishing the online installment loan integration, several limitations from a Bank of Georgia should be considered which are following the regulations from the National Bank of Georgia 1. An applicant for the installment loan should be a citizen of Georgia 2. An applicant’s age should be above 18 3. In case of a customer’s data has not been checked in the “Credit Info”, it should be examined to check a customer’s credit history. Credit history is checked by the system, however, the customer should accept the respective statement. 4. In case if the customer does not have a pre-approved installment loan, their data will be checked in the Revenue Service upon application. Again, the checks are performed by the system, however, the customer should accept the respective statement. 5. The minimum and maximum limits of the installment loan are from 45 GEL to 15000 GEL. Those limits are controlled by the online installment loan platform and no additional intervention from a Merchant’s side is needed. 6. The minimum and maximum duration of the installment loan are from 3 months to 48 months. Those limits are controlled by the online installment loan platform and no additional intervention from a Merchant’s side is needed. [Additional regulation information](https://matsne.gov.ge/ka/document/view/4822603?publication=0) ### Limitations A limitations part contains a rule which is set by the Bank of Georgia, in particular: it is not possible to make use of the installment loan from midnight until 5:00 AM since during this time closure of the operational day is in progress. A customer may calculate their **limit** of requesting a new application or have approved a new application, however, the application would not be activated and it can be used in 5 hours. One customer can request an application only once every 24 hours. Activation of the **limit** is not limited. Cancellation of the installment loan is possible within 14 calendar days. --- # Glossary Source: https://api.bog.ge/docs/en/installment/terms-used # Glossary ⚠️(Deprecated) - An installment module- an online system that allows to easily embed functionality of installment loan in any kind of Online Shop. - Online Shop – A webpage or an application, which allows a customer to purchase an item or a service via the internet. - Merchant – A retail trade or service company that possesses an Online Shop. - Callback – A request performed by the Bank System to a service published by an Online Shop to provide updated information regarding the installment loan. - A System Credentials - A client_id and the secret_key provided to a Company once it has been successfully registered in the Bank system as a merchant and has filled in all necessary data. --- # Available Balance Source: https://api.bog.ge/docs/en/bonline/accounts # Available Balance This method allows retrieving a current and an available balance of a bank account. ## Query params - `accountNumber` — string, required An account number. - `currency` — string, required An account currency code in the ISO 4217 format (e.g.: USD, GEL) - `initStatementBalance` — boolean Optional. When `true`, the response additionally contains the `StatementBalance` field. **REQUEST** ```api GET api/accounts/{accountNumber}/{currency} ``` ## Response - `AvailableBalance` — decimal number An available balance on the account. - `CurrentBalance` — decimal number A current balance on the account. - `StatementBalance` — decimal number The previous statement balance. Returned only when the `initStatementBalance` query parameter is set to `true`. **JSON** ```json { "AvailableBalance": 1.0, "CurrentBalance": 2.0 } ``` **xml** ```xml 1 2 ``` --- # Authentication Source: https://api.bog.ge/docs/en/bonline/auth/auth-introduction There are three methods of authentication available: - [For a desktop application](desktop-authentication) - [For a web application](web-authentication) - [Using token](token-authentication) --- # For a desktop application Source: https://api.bog.ge/docs/en/bonline/auth/desktop-authentication ## For a desktop application Authentication for a desktop application is done as follows: 1. Redirect a customer to the https://account.bog.ge/auth/realms/bog/protocol/openid-connect/auth, with the following parameters in the query string: `client_id` - Your application `client_id` `response_type` - A text `token` should be always passed in this parameter `scope` - A text `corp` should be always passed in this parameter `redirect_uri` – A redirect Uri of your application `kc_locale` – An interface language. `ka` should be passed for the Georgian language. Without passing this parameter an English interface will appear. For example, if a client id of your application is `implicitclient` and a redirect Uri is https://example.com/callback, the address will have the following format (after URL encoding): 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. A customer will be redirected to the redirect_uri address, with the following parameters in the query string: - `access_token` - A temporary token - `expires_in` - An expiration time - `token_type` - A token type 3. Authenticate using HTTP Basic Auth. On requesting the service, a Bearer Token is returned, which is used as an authentication parameter for calling the following methods. ## Header - `Content-Type` — string, required `application/x-www-form-urlencoded.` - `Authorization ` — string, required authentication using the HTTP Basic Auth. Use your application `client_id` as a user and a `client_secret` of your application as a password. ## Body - `grant_type` — string, required A text `client_credentials` should be always passed in this parameter. - `code` — string, required A temporary code - `redirect_uri` — string, required Your application `redirect_uri` ## Response - `access_token` — string A token returned by the authorization server. - `token_type` — string A token type (A text value `bearer` being returned) - `app_id` — string Not used. - `expires_in` — string A number of seconds during which a token is active. - `refresh_expires_in` — string The maximum time before a refresh token is expired and invalidated. It allows for the specification of a shorter timeout of refresh token than the session timeout. - `not-before-policy` — string If an access token or refresh token is compromised, access the Admin Console and push a not-before revocation policy to all applications. Pushing a not-before policy ensures that any tokens issued before that time become invalid. - `scope` — string A standard OAuth 2.0 authorization mechanism. A context in which a Token is valid. --- # Authentification using token Source: https://api.bog.ge/docs/en/bonline/auth/token-authentication # Token authentication happens using the following scheme: Send POST request to the following address:`https://account.bog.ge/auth/realms/bog/protocol/openid-connect/token` with these parameters in request body and application/x-www-form-urlencoded Content-Type: - `grant_type` - "client_credentials" - `client_id` - your application client_id - `client_secret` - your application client_secret You must make the request with Basic `BasicAuthorizationHeader` Header and use your application client_id as a username and use your application client secret as a password. After this you will be able to call the api using the access_token you got. For this you will need to add `AuthorizationHeader` Header like this: `Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6ImEzck1VZ01Gdjl0UGNsTGE2eUYzekFrZnF1RSJ9.eyJpc..........` --- # Authentification for a web application Source: https://api.bog.ge/docs/en/bonline/auth/web-authentication # Authentification for a web application An authentification for a web application is done as follows: 1. Redirect a customer to the https://account.bog.ge/auth/realms/bog/protocol/openid-connect/auth, with the following parameters in the query string: - `client_id` - Your application `client_id` - `response_type` - A text `code` should be always passed in this parameter - `scope` - A text `code` should be always passed in this parameter - `redirect_uri` – A redirect Uri of your application - `kc_locale` – An interface language. `ka` should be passed for the Georgian language. Without passing this parameter an interface will appear in English. For example, if a client id of your application is `codeclient` and a redirect Uri is `https://example.com/callback`, the address will have the following format (after URL encoding): 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. A customer will approve an application request 3. A customer will be redirected to the redirect_uri address, with the following parameters in the query string: - `code` – A temporary code 4. Authenticate using HTTP Basic Auth. On requesting the service, a Bearer Token is returned, which is used as an authentication parameter for calling the following methods. ## Header - `Content-Type` — string, required `application/x-www-form-urlencoded` - `Authorization` — string, required authentification using the HTTP Basic Auth. Use your application `client_id` as a user and a `client_secret` of your application as a password. ## Body - `grant_type` — string, required A text `client_credentials` should be always passed in this parameter. - `code` — string, required A temporary code. - `redirect_uri` — string, required Your application `redirect_uri` ## Resposne - `access_token` — string A token returned by the authorization server. - `token_type` — string A token type (A text value `bearer` is being returned) - `app_id` — string Not used. - `expires_in` — string A number of seconds of a Token being active. - `refresh_expires_in` — string The maximum time before a refresh token is expired and invalidated. It allows for the specification of a shorter timeout of refresh token than the session timeout. - `not-before-policy` — string If an access token or refresh token is compromised, access the Admin Console and push a not-before revocation policy to all applications. Pushing a not-before policy ensures that any tokens issued before that time become invalid. - `scope` — string A standard OAuth 2.0 authorization mechanism. A context in which a Token is valid. --- # საბალანსო უწყისის ატვირთვის მეთოდი Source: https://api.bog.ge/docs/en/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 ``` ## დაბრუნებული პარამეტრები --- # Deposits list Source: https://api.bog.ge/docs/en/bonline/deposits/agreements # Deposits list This method allows retrieving the list of active deposits. No parameters are passed. ## Response - `name` — string A deposit name or, if no name is set, a deposit type. - `accountNo` — string A deposit account number. - `balance` — decimal number An amount on the deposit. - `rate` — decimal number An annual interest rate. - `agreeNo` — string An agreement number. - `maturityDate` — date A deposit maturity date. - `startDate` — date A deposit opening date. - `interestAccrued` — decimal number An accrued interest. - `ccy` — string A deposit currency. - `depositType` — string A deposit type. - `nextWithdrawalDate` — date A date of the next interest accrual. - `interestWithPeriodType` — string An interest accrual periodicity. - `accrualBalance` — decimal number A minimum amount on which the interest was accrued. - `agreements` — object Interest accrual ranges. - `irr` — decimal number An internal rate of return. - `rate` — decimal number An annual interest rate. - `balance` — string An amount range as text. **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" } ] } ] ``` --- # Deposit amounts by currency Source: https://api.bog.ge/docs/en/bonline/deposits/available-amount # Deposit amounts by currency This method allows retrieving the total amounts of deposits summed by currency. No parameters are passed. ## Response - `ccy` — string A currency. - `totalAvailableAmount` — decimal number A sum of all deposit amounts in the given currency. **JSON** ```api GET api/deposits/available-amount ``` ```json [ { "ccy": "sample string 1", "totalAvailableAmount": 1.0 } ] ``` --- # Cancellation of a Package Transfer Source: https://api.bog.ge/docs/en/bonline/documents/bulk-delete # Cancellation of a Package Transfer This method allows you to cancel a package. This means that all documents inside the package will be canceled. ## Query params - `key` — integer, required An unique ID of the document in the business online. ## Response - — Http Status 200 OK. A method call is considered successful if the server returns 200 HTTP status. **REQUEST** ```api DELETE api/documents/bulk/{key} ``` --- # Package transfer in the national currency Source: https://api.bog.ge/docs/en/bonline/documents/bulk-domestic # Package transfer in the national currency This method allows to create one or more package document in national currency. ## Params - `Nomination` — string, required A reason, purpose of the transfer / 250 symbols max. - `PayerInn` — string, max-length: 11 An Identification Number of a taxpayer individual, or an Identification Code of a legal entity. Should be filled only when a transaction is performed towards the budget on behalf of a third party (in this case an identification code of a said the third party should be filled). - `PayerName` — string A Payer's name. Should be filled only when a transaction is performed towards the budget on behalf of a third party (in this case a name of a said the third party should be filled) - `DispatchType` — string A transfer method. Is used for outbound transfers only and is a mandatory field. Can take the following values: - `BULK` - A standard transfer. Is allowed only for up to 10 000 GEL transactions. - `MT103` - In other cases. - `ValueDate` — date, required A date of document entry in the bank system. - `IsSalary` — boolean Nonmandatory field, preferred to be filled on salary transfers: - `TRUE` - In cases of a salary transfer. - `FALSE` - In other cases - `UniqueId` — globally unique identifier, required A unique ID of an external (caller) system (Guid). - `Amount` — decimal number, required A document amount. - `DocumentNo` — string, required A document number. - `SourceAccountNumber` — string, required An IBAN format of a sender’s account. - `BeneficiaryAccountNumber` — string, required A recipient’s account. Only IBAN format is allowed for transfers to the Bank of Georgia or other banks in the national currency. A treasury code for the transfers to the National Treasury. An account ID in an existing format for the transfers in the foreign currency. - `BeneficiaryBankCode` — string A recipient Bank’s RTGS code. - `BeneficiaryInn` — string, max-length: 11 A Personal Identification Number for individuals; an Identification Code for legal entities. - `CheckInn` — boolean Used to indicate whether the compatibility of a receiver’s account to the Identification Code should be checked when transferring to the Bank of Georgia. Can take one of the two values: - `TRUE` - An additional compatibility check of the account number by the identification code should take place. If the account number does not match the account numbers related to that identification code- an error will be returned. - `FALSE` - A transfer will be checked in a standard way. When transferring to another bank, this parameter should be always set to `False`. - `BeneficiaryName` — string A recipient’s name. - `AdditionalInformation` — string An additional info. Is not used for transfers in a national currency. - `CommissionAccountNumber` — string Commission account. IBAN format only, e.g.: GE11BG1111111111111111GEL. In case of an incorrectly specified account, the commission (if any) will be deducted from the account from which the transfer is being made. - `IsPayerResident` — boolean Is payer resident of Georgia, Resident True, non-resident False This field must be completed only for transfers to a State Treasury account made on behalf of a third person. Indicate whether that person is a resident of Georgia - `PayerTaxRegistrationCode` — string Registration code This field must be completed only for transfers to the State Treasury made by non-residents of Georgia - `PayerPenaltyNumber` — string Protocol number This field must be completed only for transfers to the State Treasury made by non-residents of Georgia - `AttachmentIds` — array of string A list of attachment hashes. Each hash (`externalFileHash`) is obtained from the [file upload](../files/upload.md) endpoint. Filled only when you want to attach files to the document. - `CheckUniqueId` — boolean When `true`, before the document is created it is checked whether a document with the same `UniqueId` has already been created within the last 7 days. If a duplicate is found, no new document is created and result code `702` is returned. **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 ``` ## Response - — integer A unique ID of a package on the business online. **JSON** ```json 1 ``` **xml** ```xml 1 ``` --- # Package transfer in the foreign currency Source: https://api.bog.ge/docs/en/bonline/documents/bulk-foreign # Package transfer in the foreign currency This method allows to create one or more package documents in the national currency. ## Query params - `fileName` — string, required Package name ## Params - `Charges` — string, required A transfer method. Can take one of the following values: - `SHA` - (SWIFT) The Payer (sender of the payment) will pay only fees charged by the sending bank. - `OUR` - (SWIFT) The Payer (sender of the payment) will pay all fees charged by the sending bank. - `BULK` - (RTGS) A standard transfer. Is allowed only for up to 10 000 USD/EUR transactions. - `MT103` - (RTGS) An individual transfer. RTGS transfers are available only to Georgian banks in USD or EUR. - `CommissionAccountNumber` — string A fees’ account number. - `BeneficiaryBankName` — string A receiver Bank name. For SWIFT transfers, it is mandatory to fill in either BeneficiaryBankCode or BeneficiaryBankName. Must be left empty for RTGS transfers. - `IntermediaryBankCode` — string A SWIFT code of an Intermediary Bank. Must be left empty for RTGS transfers. - `IntermediaryBankName` — string A name of an Intermediary Bank. Must be left empty for RTGS transfers. - `PaymentDetail` — string A reason, purpose of the transfer / 4x34 (136) symbols max. - `ValueDate` — date, required A date of document entry in the bank system. - `BeneficiaryRegistrationCountryCode` — string Recipient’s registration country. - `BeneficiaryActualCountryCode` — string Recipient’s actual country. - `RecipientAddress` — string Recipient’s address. Must be left empty for RTGS transfers. - `RecipientCity` — string Recipient’s city. Must be left empty for RTGS transfers. - `RegReportingValue` — string An additional field that is used when transferring to the UAE. - `UniqueId` — globally unique identifier, required An unique ID of a document in the external (caller) system (Guid). - `Amount` — decimal number, required A document’s amount. - `Currency` — string, required A document currency. - `DocumentNo` — string, required A document’s number. - `SourceAccountNumber` — string, required A sender’s account in IBAN format. - `BeneficiaryAccountNumber` — string, required A recipient’s account. Only IBAN format is allowed for transfers to the Bank of Georgia or other banks in the national currency. A treasury code for the transfers to the National Treasury. An account ID in an existing format for the transfers in the foreign currency. - `BeneficiaryBankCode` — string A BIC code of a recipient Bank. Must be left empty for RTGS transfers. - `BeneficiaryInn` — string, max-length: 11 An Identification Number for individuals; an Identification Code for legal entities. - `CheckInn` — boolean Used to indicate whether the compatibility of a receiver’s account to the Identification Code should be checked when transferring to the Bank of Georgia. Can take one of the two values: - `TRUE` - An additional compatibility check of the account number by the identification code should take place. If the account number does not match the account numbers related to that identification code- an error will be returned. - `FALSE` - A transfer will be checked in a standard way. When transferring to another bank, this parameter should be always set to `False`. - `BeneficiaryName` — string A recipient’s name. - `AdditionalInformation` — string An additional info. Is not used for transfers in a national currency. - `PurposeCode` — string A payment purpose code. Used for currency operation reporting. - `AttachmentIds` — array of string A list of attachment hashes. Each hash (`externalFileHash`) is obtained from the [file upload](../files/upload.md) endpoint. Filled only when you want to attach files to the document. - `CheckUniqueId` — boolean When `true`, before the document is created it is checked whether a document with the same `UniqueId` has already been created within the last 7 days. If a duplicate is found, no new document is created and result code `702` is returned. **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 A unique ID of a package on the business online. **JSON** ```json 1 ``` **xml** ```xml 1 ``` --- # Package transfer status Source: https://api.bog.ge/docs/en/bonline/documents/bulk-status # Package transfer status This method allows retrieving the status of a document package and all individual documents status by a package unique ID. ## Query params - `key` — integer, required An unique ID of the document in the business online.. **REQUEST** ```api GET api/documents/bulk/status/{key} ``` ## Response - `Status` — string A document status. - `DocumentStatuses` — string A document array from a package transfer with the following attributes: - `UniqueId ` — globally unique identifier An unique ID of the document in the external (caller) system (Guid). - `UniqueKey ` — integer An unique ID of the document in the business online. - `Status` — string A document status. - `BulkLineStatus` — string Is used in case of the package transfer. - `RejectCode` — string A rejection code. - `ResultCode` — integer A result code of an operation. (With a link to the ResultCode page). - `Match` — integer For the internal transfers a matched coefficient of provided recipient name. For legal entities a match of an owner of a provided IBAN to the entity name is being checked, while for the individuals - to the name and surname. A match coefficient in percent will be shown as a result of such a comparison. **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 ``` --- # Conversion Source: https://api.bog.ge/docs/en/bonline/documents/conversion # Conversion This method allows creating one or more documents of conversion between customers’ accounts. ## Params A document array with the following attributes: - `UniqueId` — globally unique identifier, required An unique ID of the document in the external (caller) system (Guid). - `DocumentNo` — string A document number. - `SourceAccountNumber` — string An account number of a currency to sell. - `SourceCurrency` — string A currency to sell. - `DestinationAccountNumber` — string An account number of a currency to buy. - `DestinationCurrency` — string A currency to buy. - `Amount` — decimal number An amount - `Rate` — decimal number An exchange rate. Should be filled in case of using a conversion rate individually agreed with a Bank. - `AdditionalInfo` — string An additional info. Is not used for transfers in a national currency - `CheckUniqueId` — boolean When `true`, before the document is created it is checked whether a document with the same `UniqueId` has already been created within the last 7 days. If a duplicate is found, no new document is created and result code `702` is returned. **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 ``` ## Response - `UniqueId` — globally unique identifier An unique ID in the external system (Guid). - `UniqueKey` — integer An unique ID of the document in the business online. - `ResultCode` — integer A result code of an operation. (With a link to the ResultCode page). [result code](../result/result-codes.md) - `Match` — decimal number For the internal transfers a matched coefficient of provided recipient name. For legal entities a match of an owner of a provided IBAN to the entity name is being checked, while for the individuals - to the name and surname. A match coefficient in percent will be shown as a result of such a comparison. **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 ``` --- # Document creation codes Source: https://api.bog.ge/docs/en/bonline/documents/document-codes # Document creation codes This method allows retrieving all the document creation codes with the description. ## Response - `DocumentTypeName` — string A document type. - `ResultType` — string A result type. - `ResultDescription` — string A result description. - `ResultCode` — integer A result code. **REQUEST** ```api GET api/documents/code ``` **JSON** ```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** ```xml sample string 1 4 sample string 3 sample string 2 sample string 1 4 sample string 3 sample string 2 ``` --- # Cancellation of an individual document Source: https://api.bog.ge/docs/en/bonline/documents/document-delete # Cancellation of an individual document This method allows canceling an individual document. ## Query params - `key` — integer, required An unique ID of the document in the business online (one or more). ## Response - — Http Status 200 OK. A method call is considered successful if the server returns 200 HTTP status. **REQUEST** ```api DELETE api/documents/{keys} ``` --- # Individual document in the national currency Source: https://api.bog.ge/docs/en/bonline/documents/domestic # Individual document in the national currency This method allows creating one or more individual documents in national currency. ## Params An array of documents with the following attributes: - `Nomination` — string, required A reason, purpose of the transfer / 250 symbols max. - `PayerInn` — string, max-length: 11, required An Identification Number of a taxpayer individual, or an Identification Code of a legal entity. Should be filled only when a transaction is performed towards the budget on behalf of a third party (in this case an identification code of a said the third party should be filled). - `PayerName` — string A Payer's name. Should be filled only when a transaction is performed towards the budget on behalf of a third party (in this case a name of a said the third party should be filled) - `DispatchType` — string A transfer method. Is used for outbound transfers only and is a mandatory field. Can take the following values: - BULK – A standard transfer. Is allowed only for up to 10 000 GEL transactions. - MT103 - An individual transfer. - `ValueDate` — date, required A date of document entry in the bank system. - `IsSalary` — boolean Nonmandatory field, preferred to be filled on salary transfers: - TRUE – In cases of a salary transfer. - FALSE – In other cases - `UniqueId` — globally unique identifier, required A unique ID of an external (caller) system (Guid). - `Amount` — decimal number, required A document amount. - `DocumentNo` — string, required A document number, max. length = 16. - `SourceAccountNumber` — string, required An IBAN format of a sender’s account. - `BeneficiaryAccountNumber` — string, required A recipient’s account. Only IBAN format is allowed for transfers to the Bank of Georgia or other banks in the national currency. A treasury code for the transfers to the National Treasury. An account ID in an existing format for the transfers in the foreign currency. - `BeneficiaryBankCode` — string, required A recipient Bank’s RTGS code. - `BeneficiaryInn` — string, required A Personal Identification Number for individuals; an Identification Code for legal entities. - `CheckInn` — boolean Used to indicate whether the compatibility of a receiver’s account to the Identification Code should be checked when transferring to the Bank of Georgia. Can take one of the two values: - `TRUE` – An additional compatibility check of the account number by the identification code should take place. If the account number does not match the account numbers related to that identification code- an error will be returned. - `FALSE` – A transfer will be checked in a standard way. When transferring to another bank, this parameter should be always set to `False`. - `BeneficiaryName` — string A recipient’s name. - `CommissionAccountNumber` — string Commission account, for individual transfers only. IBAN format only, e.g.: GE11BG1111111111111111GEL. In case of an incorrectly specified account, the commission (if any) will be deducted from the account from which the transfer is being made. - `IsPayerResident` — boolean Is payer resident of Georgia,  Resident True, non-resident False This field must be completed only for transfers to a State Treasury account made on behalf of a third person. Indicate whether that person is a resident of Georgia - `PayerTaxRegistrationCode` — string Registration code This field must be completed only for transfers to the State Treasury made by non-residents of Georgia - `PayerPenaltyNumber` — string Protocol number This field must be completed only for transfers to the State Treasury made by non-residents of Georgia - `AdditionalInformation` — string An additional info. Is not used for transfers in a national currency. - `AttachmentIds` — array of string A list of attachment hashes. Each hash (`externalFileHash`) is obtained from the [file upload](../files/upload.md) endpoint. Filled only when you want to attach files to the document. - `CheckUniqueId` — boolean When `true`, before the document is created it is checked whether a document with the same `UniqueId` has already been created within the last 7 days. If a duplicate is found, no new document is created and result code `702` is returned. **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" }, { "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" } ] ``` **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 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 ``` ## Response - `UniqueId` — globally unique identifier An unique ID in the external system (Guid). - `UniqueKey` — integer An unique ID of the document in the business online. - `ResultCode` — integer A result code of an operation. (With a link to the ResultCode page). [result code](../result/result-codes.md) - `Match` — decimal number For the internal transfers a matched coefficient of a provided recipient name. For legal entities a match of an owner of a provided IBAN to the entity name is being checked, while for the individuals - to the name and surname. A match coefficient in percent will be shown as a result of such a comparison. **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 ``` --- # Individual document in the foreign currency Source: https://api.bog.ge/docs/en/bonline/documents/foreign # Individual document in the foreign currency This method allows creating one or more individual documents in foreign currency. ## Params An array of documents with the following attributes: - `Charges` — string, required Charges (required; string) – A transfer method. Can take one of the following values: - `SHA` - (SWIFT) The Payer (sender of the payment) will pay only fees charged by the sending bank. - `OUR` - (SWIFT) The Payer (sender of the payment) will pay all fees charged by the sending bank. - `BULK` - (RTGS) A standard transfer. Is allowed only for up to 10 000 USD/EUR transactions. - `MT103` - (RTGS) An individual transfer. RTGS transfers are available only to Georgian banks in USD or EUR. - `BeneficiaryBankName` — string A receiver Bank name. For SWIFT transfers, it is mandatory to fill in either BeneficiaryBankCode or BeneficiaryBankName. Must be left empty for RTGS transfers. - `IntermediaryBankCode` — string A SWIFT code of an Intermediary Bank. Must be left empty for RTGS transfers. - `IntermediaryBankName` — string A name of an Intermediary Bank. Must be left empty for RTGS transfers. - `PaymentDetail` — string A reason, purpose of the transfer / 4x34 (136) symbols max. - `ValueDate` — date, required A date of document entry in the bank system. - `BeneficiaryRegistrationCountryCode` — string Recipient’s registration country. - `BeneficiaryActualCountryCode` — string Recipient’s actual country. - `RecipientAddress` — string Recipient’s address. Must be left empty for RTGS transfers. - `RecipientCity` — string Recipient’s city. Must be left empty for RTGS transfers. - `RegReportingValue` — string An additional field that is used when transferring to the UAE. - `UniqueId` — globally unique identifier, required An unique ID of a document in the external (caller) system (Guid). - `Amount` — decimal number, required A document’s amount. - `Currency` — string, required A document currency. - `DocumentNo` — string, required A document’s number - `SourceAccountNumber` — string, required A sender’s account in IBAN format. - `BeneficiaryAccountNumber` — string, required A recipient’s account. Only IBAN format is allowed for transfers to the Bank of Georgia or other banks in the national currency. A treasury code for the transfers to the National Treasury. An account ID in an existing format for the transfers in the foreign currency. - `BeneficiaryBankCode` — string A BIC code of a recipient Bank. Must be left empty for RTGS transfers. - `BeneficiaryInn` — string, max-length: 11 An Identification Number for individuals; an Identification Code for legal entities. - `CheckInn` — string Used to indicate whether the compatibility of a receiver’s account to the Identification Code should be checked when transferring to the Bank of Georgia. Can take one of the two values: - `TRUE` – An additional compatibility check of the account number by the identification code should take place. If the account number does not match the account numbers related to that identification code - an error will be returned. - `FALSE` – A transfer will be checked in a standard way. When transferring to another bank, this parameter should be always set to `False`. - `BeneficiaryName` — string A recipient’s name. - `CommissionAccountNumber` — string Commission account, for individual transfers only / IBAN format only, e.g.: GE11BG1111111111111111GEL. In case of an incorrectly specified account, the commission (if any) will be deducted from the account from which the transfer is being made. - `AdditionalInformation` — string An additional info. Is not used for transfers in a national currency. - `AttachmentIds` — array of string A list of attachment hashes. Each hash (`externalFileHash`) is obtained from the [file upload](../files/upload.md) endpoint. Filled only when you want to attach files to the document. - `PurposeCode` — string A payment purpose code. Used for currency operation reporting. - `CheckUniqueId` — boolean When `true`, before the document is created it is checked whether a document with the same `UniqueId` has already been created within the last 7 days. If a duplicate is found, no new document is created and result code `702` is returned. **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" }, { "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" } ] ``` **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 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 ``` ## Response - `UniqueId` — globally unique identifier An unique ID in the external system (Guid). - `UniqueKey` — integer An unique ID of the document in the business online. - `ResultCode` — integer A result code of an operation. (With a link to the ResultCode page). [result code](../result/result-codes.md) - `Match` — decimal number For the internal transfers a matched coefficient of provided recipient name. For legal entities a match of an owner of a provided IBAN to the entity name is being checked, while for the individuals - to the name and surname. A match coefficient in percent will be shown as a result of such a comparison. **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 ``` --- # Individual document status Source: https://api.bog.ge/docs/en/bonline/documents/status # Individual document status This method allows retrieving a document status by its unique ID. ## Query params - `key` — integer, required A document unique ID on the business online. **REQUEST** ```api GET api/documents/status/{key} ``` ## Response - `UniqueId` — globally unique identifier A unique ID of the document in the external (caller) system (Guid). - `UniqueKey` — integer A unique ID of the document in the business online. - `Status` — string A document status. - `BulkLineStatus` — string Is used during package transfers. - `RejectCode` — integer A rejection code. - `ResultCode` — integer A result code of an operation. [result code](../result/result-codes.md) - `Match` — decimal number For the internal transfers a matched coefficient of provided recipient name. For legal entities a match of an owner of a provided IBAN to the entity name is being checked, while for the individuals - to the name and surname. A match coefficient in percent will be shown as a result of such a comparison. **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 ``` --- # Individual document statuses Source: https://api.bog.ge/docs/en/bonline/documents/statuses # Individual document statuses This method allows retrieving documents’ statuses by their unique IDs. ## Query params - `key` — one or more integer, required A documents’ unique ID on the business online. **REQUEST** ```api GET api/documents/statuses/{keys} ``` ## Response - `UniqueId` — globally unique identifier An unique ID of the document in the external (caller) system (Guid). - `UniqueKey` — integer An unique ID of the document in the business online. - `Status` — string A document status. - `BulkLineStatus` — string Is used during package transfers. - `RejectCode` — integer A rejection code. - `ResultCode` — integer A result code of an operation. [ResultCode](../result/result-codes.md). - `Match` — decimal number For the internal transfers a matched coefficient of provided recipient name. For legal entities a match of an owner of a provided IBAN to the entity name is being checked, while for the individuals - to the name and surname. A match coefficient in percent will be shown as a result of such a comparison. **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 ``` --- # Current day activities Source: https://api.bog.ge/docs/en/bonline/documents/todayactivities # Current day activities This method allows us to retrieve all activities of the current day. :::note This method is rate limited — 800 requests per day are allowed (per account and currency). Exceeding the limit returns `429 Too Many Requests` with a `Retry-After` header (in seconds). ::: ## Query params - `accountNumber` — string, required An account number - `currency` — string, required A currency **REQUEST** ```api GET api/documents/todayactivities/{accountNumber}/{currency} ``` ## Response - `Id` — integer A unique identifier. - `DocKey` — integer A document unique ID on the business online. - `DocNo` — string A document number. - `PostDate` — date A document creation date. - `ValueDate` — date ვალუტირების თარიღი - `EntryType` — string An entry type. Can take the following values: - PMC - GEL Operation - PLC - Card Operation - CDS - Saving Operation - LND - Loan Operation - PBS - Paybox Operation - INC - Inkaso (Debts collection) - PMD - Transfer of a national currency - PMI - Transfer of a foreign currency - COM - Fee - `EntryComment` — string An entry comment, a content of the transaction. - `EntryCommentEn` — string An entry comment, a content of the transaction in English. - `Nomination` — string A document purpose. - `Credit` — decimal number A credit. - `Debit` — decimal number A debit. - `Amount` — decimal number An amount. - `AmountBase` — decimal number An amount equivalent in GEL. - `PayerName` — string A payer name. - `PayerInn` — string A payer identification code. - `Sender` — object A sender info. - `Name` — string A name. - `Inn` — string An identification number. - `AccountNumber` — string An account number. - `BankCode` — string A bank code. - `BankName` — string A bank name. - `Beneficiary` — object A recipient info. - `Inn` — string An identification number. - `AccountNumber` — string An account number. - `BankCode` — string A bank code. - `BankName` — string A bank name. **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 ``` --- # File upload Source: https://api.bog.ge/docs/en/bonline/files/upload # File upload This method allows uploading a file. The file is sent as `multipart/form-data`, using the `file` field. On success, the hash of the uploaded file (`externalFileHash`) is returned, which is later used to attach the file to transfer documents (the `AttachmentIds` field). Allowed extensions: `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`. For a disallowed extension or a missing file, the HTTP status code `400 Bad Request` is returned with the message `File extension is not allowed`. ## Parameters - `file` — file, required The file to upload. Sent via the `file` field of the `multipart/form-data` form. **FORM-DATA** ```api POST api/files/upload Content-Type: multipart/form-data ``` ``` file: (binary) ``` ## Returned parameters - `externalFileHash` — string A unique hash of the uploaded file. Used in the `AttachmentIds` field when creating a transfer document. **JSON** ```json "sample string 1" ``` --- # Postman Collections (NEW!) Source: https://api.bog.ge/docs/en/bonline/introduction-token ## Postman Collections (NEW!) To help you get started quickly and follow API best practices, we provide ready-to-use Postman collections covering all endpoints with full configuration. Collections are available in two languages: - 📦 [ { e.preventDefault(); const link = document.createElement('a'); link.href = '/docs/en/files/BOG_BusinessOnline_API_EN.postman_collection.json'; link.download = 'BOG_BusinessOnline_API_EN.postman_collection.json'; document.body.appendChild(link); link.click(); document.body.removeChild(link); }}>**BOG Business Online API [EN]**](https://api.bog.ge/docs/en/docs/en/files/BOG_BusinessOnline_API_EN.postman_collection.json) — English version — v1.0.5 **What's included:** - All three authentication methods — Client Credentials Flow, Implicit Flow, Authorization Code Flow (with Refresh Token support) - All document endpoints — domestic, foreign, conversion, bulk - Statement V1 and V2 (with pagination support) - Currency rates and account balance - Error scenarios (401, 404, 400) **Key features:** - `ACCESS_TOKEN` is automatically saved and applied to all requests - `x-correlationid` header is automatically logged to the Console - `TODAY_DATE`, `LAST_DOCUMENT_KEY`, `LAST_BULK_KEY` are auto-populated via Test Scripts **To get started**, fill in the following collection variables: | Variable | Description | |---|---| | `CLIENT_ID` | From [bonline.bog.ge/admin/api](https://bonline.bog.ge/admin/api/) | | `CLIENT_SECRET` | From [bonline.bog.ge/admin/api](https://bonline.bog.ge/admin/api/) | | `ACCOUNT_IBAN` | Your account IBAN | | `BENEFICIARY_IBAN` | Beneficiary IBAN | | `BENEFICIARY_BANK_CODE` | Beneficiary bank RTGS code (BOG: `BAGAGE22`) | Run **1.1.1 [CC] Get Access Token** first — all subsequent requests will be automatically authorized. --- # Introduction Source: https://api.bog.ge/docs/en/bonline/introduction ## What is Business Online API The API allows you to easily embed a functionality existing in the Bank of Georgia’s Internet Banking into your accounting or other business application. simplifying everyday operations for your users, who without leaving your application will have access to the Internet Banking functionality such as: - **Create Transfer Documents** –within your application a user will be able to create an individual or a package document for money transfer and conversion in national and foreign currency. - **Account Statement Management** – User will not need to upload an account statement anymore. General information regarding the first 1000 records will be available in your application. A user will be able to monitor a monthly or daily global account statement balance for the period of their choice. - **Account Balance Check** - A user will see the available and current balances on their accounts in the operational area. - **Currency Rate Control** – Information about a National Bank, historical, Bank’s commercial or currency cross rate will be integrated into your own application. ## What is needed for the integration To simplify the service integration, we prepared a test environment and comprehensive documentation which allows establishing the integration with the API having only basic programming knowledge. To establish the integration, a Company should have an account on [bonline.bog.ge](https://bonline.bog.ge) and unique credentials for accessing the system. To call the API you should register your application on the [bonline.bog.ge/admin/api](https://bonline.bog.ge/admin/api/) webpage. When registering you should enter the application name, application name in an international language, and the address of the logo of your choice (it is advised to use an https protocol and size no more than 400x800). In case you are registering a web client, you should also enter a web address for redirection on authentication. After registration, Application identifiers which you will have to use on the authentication request will appear on the application details page. - `client id` - `client secret ` - `redirect uri` (only in case of web clients) To gain access to the test environment, contact your business banking personal assistant or fill the application. ## Protocol and Technical Specifications AAPI architecture: `Restful` Business Online Application protocol: `HTTP/1.1`. To enhance security, it is mandatory to call all API methods using https, which is an extension of the HTTP protocol. Service call type: Synchronous Security protocol: `OAuth 2.0` Information exchange security standard: `JSON Web Tokens (JWT).` BASE URL: `https://api.businessonline.ge/api` On each request, an x-correlationid Header will be returned with a unique value which is an ID of this request. It is recommended to store this ID on your side since in case of a problem it will help to find your request. Please contact us at `customerservice@bog.ge` for any additional information. ## Rate Limit The API is protected by a rate limit. By default, every method is subject to a baseline limit of 5 requests per second per client; specific methods have additional, stricter limits (see the table). When the limit is exceeded, the request is rejected with a `429 Too Many Requests` status. In that case the response includes a `Retry-After` header, indicating in seconds when you may send the request again. | Method | Limit | | --- | --- | | All methods (default) | 5 requests per second (per client) | | Currency rates (`api/rates/*`, `api/v2/rates/{currency}`, `api/v2/crossrates/{sellCurrency}/{buyCurrency}`) | 60 requests per minute (per individual method) | | Current day activities (`api/v2/documents/todayactivities/...`) | 800 requests per day (per account and currency) | The limit is calculated per application (client) and per specific method, using a sliding window. --- # Money request creation Source: https://api.bog.ge/docs/en/bonline/money-request/create # Money request creation This method allows creating a money request. The request is sent to the recipient, who confirms the transfer. On success, the HTTP status code `201 Created` is returned with an empty response body. ## Parameters - `AccountNumber` — string, required Your account number in IBAN format, to which the requested amount will be deposited. E.g. GE11BG1111111111111111 - `Currency` — string, required A currency in ISO 4217 format (e.g. GEL, USD, EUR). - `Amount` — decimal number, required A requested amount. - `IsPhysical` — boolean, required A recipient type. Accepts two values: - `TRUE` - a physical person. - `FALSE` - a legal entity. - `PhoneNumber` — string A phone number of the recipient physical person. Filled only for a physical person (`IsPhysical=true`) — exactly one of `PhoneNumber` or `Pin` must be filled. - `Pin` — string A personal number of the recipient physical person. Filled only for a physical person (`IsPhysical=true`) — exactly one of `PhoneNumber` or `Pin` must be filled. - `RecipientIdentifier` — string An identification code of the recipient legal entity. Required for a legal entity (`IsPhysical=false`) — in this case `PhoneNumber` and `Pin` must be empty. - `Description` — string, required A purpose of the money request. **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" } ``` --- # OTP Request Source: https://api.bog.ge/docs/en/bonline/otp/request # OTP Request ## Parameters - `ObjectKey` — integer, required Object Identifier - `ObjectType` — object, required Object Type - `ObjectType.Payment` — integer, required Payment **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 ``` --- # Bank’s commercial currency exchange rate Source: https://api.bog.ge/docs/en/bonline/rates/commercial-currency # Bank’s commercial currency exchange rate This method allows retrieving a current commercial currency exchange rate by a Bank of Georgia for a given currency to a Georgian Lari and vice versa. :::note This method is rate limited — 60 requests per minute are allowed. Exceeding the limit returns `429 Too Many Requests` with a `Retry-After` header (in seconds). ::: ## Query params - `currency` — string, required A currency code in the ISO 4217 format (e.g.: USD, GEL). **REQUEST** ```api GET api/rates/commercial/{currency} ``` ## Response - `Sell` — decimal number A commercial currency exchange rate from a Georgian Lari to a given currency by the Bank of Georgia. - `Buy` — decimal number A commercial currency exchange rate from a given currency to a Georgian Lari by Bank of Georgia. **JSON** ```json { "Sell": 1.0, "Buy": 1.0 } ``` **xml** ```xml 1 1 ``` --- # Cross Rate Source: https://api.bog.ge/docs/en/bonline/rates/commercial-sellCurrency-buyCurrency # Cross Rate მეთოდის საშუალებით შესაძლებელია საქართველოს ბანკში გასაყიდი ვალუტის, საყიდელ ვალუტასთან მიმართებაში კომერციული კურსის გაგება. :::note This method is rate limited — 60 requests per minute are allowed. Exceeding the limit returns `429 Too Many Requests` with a `Retry-After` header (in seconds). ::: ## Query params - `sellCurrency` — string, required A ‘to’ currency code in the ISO 4217 format (e.g.: USD, GEL) - `buyCurrency` — string, required A ‘from’ currency code in the ISO 4217 format (e.g.: USD, GEL) **REQUEST** ```api GET api/rates/commercial/{sellCurrency}/{buyCurrency} ``` ## Response - — decimal number An exchange rate by a National Bank for a given currency. **JSON** ```json 1.0 ``` **xml** ```xml 1 ``` --- # Cross Rate Source: https://api.bog.ge/docs/en/bonline/rates/cross-rates # Cross Rate This method returns the Bank of Georgia digital-channel rate of the sell currency against the buy currency. The base currency is returned together with the rate. :::note This method requires authorization (Bearer token). It is also rate limited — 60 requests per minute are allowed. Exceeding the limit returns `429 Too Many Requests` with a `Retry-After` header (in seconds). ::: ## Query params - `sellCurrency` — string, required The currency to sell, in the ISO 4217 format (e.g.: USD, GEL) - `buyCurrency` — string, required The currency to buy, in the ISO 4217 format (e.g.: USD, GEL) **REQUEST** ```api GET api/v2/crossrates/{sellCurrency}/{buyCurrency} ``` ## Response - `rate` — decimal number The digital-channel rate of the sell currency against the buy currency. - `baseCcy` — string The base currency in the ISO 4217 format, against which the rate is expressed. **JSON** ```json { "rate": 0.9200, "baseCcy": "USD" } ``` --- # National Bank’s currency exchange rate history Source: https://api.bog.ge/docs/en/bonline/rates/nbg-hist # National Bank’s currency exchange rate history This method allows retrieving an exchange rate by National Bank for a requested currency to a Georgian Lari by a period. A method returns a currency exchange rate for each date within a requested period. :::note This method is rate limited — 60 requests per minute are allowed. Exceeding the limit returns `429 Too Many Requests` with a `Retry-After` header (in seconds). ::: ## Query params - `currency` — string, required A currency code in the ISO 4217 format (e.g.: USD, GEL). - `startDate` — date, required A start date for a period. - `endDate` — date, required An end date for a period. **REQUEST** ```api GET api/rates/nbg/{currency}/{startDate}/{endDate} ``` ## Response - `Date` — date A date. - `Rate` — decimal number An exchange rate by a National Bank for a given currency. - `Currency` — string A currency code in the ISO 4217 format (e.g: 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 ``` --- # A currency rate of the National Bank for a given currency Source: https://api.bog.ge/docs/en/bonline/rates/nbg # A currency rate of the National Bank for a given currency This method allows retrieving a current exchange rate by National Bank for a requested currency to a Georgian Lari. :::note This method is rate limited — 60 requests per minute are allowed. Exceeding the limit returns `429 Too Many Requests` with a `Retry-After` header (in seconds). ::: ## Query params - `currency` — string, required A currency code in the ISO 4217 format (e.g: USD, GEL) **REQUEST** ```api GET api/rates/nbg/{currency} ``` ## Response - — decimal number An exchange rate by a National Bank for a given currency. **JSON** ```json 1.0 ``` **xml** ```xml 1 ``` --- # Currency rate details Source: https://api.bog.ge/docs/en/bonline/rates/rate-details # Currency rate details This method returns, in a single request, the full set of rates for a requested currency against the Georgian Lari: the National Bank rate, the standard buy/sell rate and the digital-channel buy/sell rate. The digital rate is client-specific — if the authenticated client has an individual (special) rate, their special rate is returned; otherwise the regular digital-channel rate is returned. :::note This method requires authorization (Bearer token). Rates are calculated for the authenticated client. It is also rate limited — 60 requests per minute are allowed. Exceeding the limit returns `429 Too Many Requests` with a `Retry-After` header (in seconds). ::: ## Query params - `currency` — string, required A currency code in the ISO 4217 format (e.g: USD, EUR) **REQUEST** ```api GET api/v2/rates/{currency} ``` ## Response - `nbgRate` — decimal number The exchange rate set by the National Bank for the given currency. - `standardBuyRate` — decimal number The standard rate at which the bank buys the given currency. - `standardSellRate` — decimal number The standard rate at which the bank sells the given currency. - `digitalBuyRate` — decimal number The digital-channel rate at which the bank buys the given currency. If the client has a special rate, the special rate is returned. - `digitalSellRate` — decimal number The digital-channel rate at which the bank sells the given currency. If the client has a special rate, the special rate is returned. **JSON** ```json { "nbgRate": 2.7000, "standardBuyRate": 2.6500, "standardSellRate": 2.7500, "digitalBuyRate": 2.6600, "digitalSellRate": 2.7400 } ``` --- # Bulk Transfer Statuses Source: https://api.bog.ge/docs/en/bonline/result/bulk-transfer-statuses
Status Description
N Processing
S Signed
C Canceled by Response
P To be Signed
D File Duplicate
Z Sign in Progress
I Individual documents created
A The bulk transfer is in process of Signature
B Documents are being created
U Uploading file, checking
--- # Document Statuses Source: https://api.bog.ge/docs/en/bonline/result/document-statuses
Status Description
C Cancelled by Response
N Incomplete
D Cancelled by Bank
P Completed
A To be Signed
S Signed
T In Progress
R Rejected
Z Sign In Progress
--- # Error Codes Source: https://api.bog.ge/docs/en/bonline/result/reject-codes
Code Description
22 Canceled, please contact us for more information 2444444
21 The recipient account and Name Not Comparable
20 Card error
19 Expired card
18 Blocked Card
17 Insufficient funds
16 Fonts can not be read
15 Wrong destination
14 Beneficiary Account Is Incorrect
13 Not Set Treasury code
12 Wrong IBAN Format
--- # Result Codes Source: https://api.bog.ge/docs/en/bonline/result/result-codes
Code Document Type Description Result Type
-999 Foreign Error occured while executing operation Error
-999 Error occured while executing operation Error
-998 Rejected due to expiration Warn
-99 Utility Payments Payment failed, try again later Error
-82 Transfer to the entered account isn't possible. The account owner needs to update their personal information at the bank Error
-21 Foreign document.result.code.foreign.transfer.incorrect.amount Error
-21 document.result.code.foreign.transfer.incorrect.amount Error
-20 Foreign document.result.code.foreign.transfer.incorrect.receiver.country Error
-20 document.result.code.foreign.transfer.incorrect.receiver.country Error
-19 Foreign document.result.code.foreign.transfer.incorrect.receiver.status Error
-19 document.result.code.foreign.transfer.incorrect.receiver.status Error
-18 Foreign document.result.code.foreign.transfer.not.enough.balance.on.account Warn
-18 document.result.code.foreign.transfer.not.enough.balance.on.account Warn
-17 Foreign Benef Account Is Incorrect Error
-17 Benef Account Is Incorrect Error
-16 Foreign Incorrect Commision Account Error
-16 Incorrect Commision Account Error
-15 Foreign Incorrect Commision Parameters Error
-15 Incorrect Commision Parameters Error
-14 Utility Payments გამგზავნის ანგარიში არასწორია Error
-14 Foreign Incorrect System Phase Error
-14 Incorrect System Phase Error
-13 Foreign document.result.code.foreign.transfer.template.not.found Error
-13 document.result.code.foreign.transfer.template.not.found Error
-12 Foreign Incorrect Currency Error
-12 Incorrect Currency Error
-11 Foreign Incorrect Value Date Error
-11 Incorrect Value Date Error
-10 Foreign Additional Information format is invalid. Max number of symbols should be 210 Error
-10 Additional Information format is invalid. Max number of symbols should be 210 Error
-9 Foreign Transfer Description Format is Invalid. Valid Characters are a-z A-Z 0-9 /-?)., ' + : Error
-9 Transfer Description Format is Invalid. Valid Characters are a-z A-Z 0-9 /-?)., ' + : Error
-8 Utility Payments document.result.code.electronic.payment.https.error Warn
-8 Foreign Destination Account Is Incorrect Error
-8 Destination Account Is Incorrect Error
-7 Foreign The receiver bank data is incorrect, try again Error
-7 The receiver bank data is incorrect, try again Error
-6 Foreign Intermediar Info Is Empty Error
-6 Intermediar Info Is Empty Error
-5 Foreign Beneficiary Name Is not Valid Error
-5 Beneficiary Name Is not Valid Error
-4 Foreign Sender Name Is Empty Error
-4 Sender Name Is Empty Error
-3 Foreign Incorrect Sender Account Error
-3 Incorrect Sender Account Error
-2 Foreign Transfer to this beneficiary account with the submitted parameters is impossible Error
-2 Transfer to this beneficiary account with the submitted parameters is impossible Error
-1 Foreign Sender And Beneficiary Accounts Ccy Is Incorrect Error
-1 Sender And Beneficiary Accounts Ccy Is Incorrect Error
0 Document is Ready to Sign Success
1 Document Not Found Error
2 Doc Type Not Found Error
4 Conversion Incorrect Currency Rate For Specified Currencies Error
28 CheckInn is used while transferring outside Bank of Georgia. Tis parameter is used only while transferring within Bank of Georgia Error
29 Beneficiary account number and taxpayer number are incorrect Error
30 Recipient's account number and/or bank code are blank Error
31 Invalid sender or recipient Bank code Error
32 Transaction is not possible Error
33 Within Georgia Sender ID not found Error
33 Sender account is incorrect Error
34 Incorrect Sender Account Currency Error
35 Cannot perform transaction on the specified account Error
36 Sender Number Taxpayer is Not Correct Error
37 Beneficiary Account Is Empty Error
38 Beneficiary Account Is Too Long Error
39 Beneficiary Account Is Incorrect Error
40 The Treasury code is incorrect Error
41 Receiver tax id is not correct Error
42 Beneficiary Name Is not Valid Error
43 Recipient name should not exceed 160 symbols Error
44 Beneficiary Account Is Incorrect Error
45 Incorrect Beneficiary Account Currency Error
46 Cannot perform transaction between specified accounts Error
47 The document has expired Error
48 Incorrect Value Date Error
49 Incorrect Transfer Currency Error
50 Incorrect Amount Format Error
51 Incorrect Commis Amount Format Error
52 Incorrect taxpayer ID Error
53 Payer name must not exceed 160 symbols Error
54 Nomination Is Empty Error
55 Destination field should not exceed 250 symbols Error
56 Additional information field should not exceed 250 symbols Error
57 Validation General Exception Error
58 Fee account is incorrect Error
59 Payer name and payer INN are filled only when making a transfer to a State Treasury account on behalf of the third person Error
60 Beneficiary taxpayer number is empty Error
61 Within BoG The number of symbols in the identification code must not exceed 14 Error
61 Within Georgia The number of symbols in the identification code must not exceed 14 Error
71 Foreign Sender And Beneficiary Accounts Ccy Is Incorrect Error
72 Transfer to this beneficiary account with the submitted parameters is impossible Error
73 Foreign Incorrect Sender Account Error
74 Foreign Sender Name Is Empty Error
75 Foreign Beneficiary Name Is not Valid Error
76 Foreign Intermediar Info Is Empty Error
77 Foreign The receiver bank data is incorrect, try again Error
78 Foreign Destination Account Is Incorrect Error
79 Foreign Transfer Description Format is Invalid. Valid Characters are a-z A-Z 0-9 /-?)., ' + : Error
80 Foreign Additional Information format is invalid. Max number of symbols should be 210 Error
81 Foreign Incorrect Value Date Error
81 Within BoG Incorrect Value Date Error
82 Foreign Incorrect Currency Error
83 Foreign Insufficient funds Error
83 Between My Accounts Insufficient funds Error
84 Foreign Incorrect System Phase Error
85 Foreign Incorrect Commision Parameters Error
86 Foreign Incorrect Commision Account Error
87 Foreign Benef Account Is Incorrect Error
90 Recipient Name Long Error
91 Description Long Error
92 Foreign Recipient's Country code is not valid Error
96 Foreign Transaction Type Description is not valid, please indicate correct code Error
110 Conversion Incorrect Amount Format Error
111 Conversion Incorrect Transfer Currency Error
112 Conversion Incorrect Sender Account Error
113 Conversion Beneficiary Account Is Incorrect Error
114 Conversion Sender And Beneficiary Accounts Is Same Error
115 Conversion Sender And Beneficiary Accounts Ccy Is Same Error
116 Conversion Sender And Beneficiary Client Is Different Error
117 Conversion Sender and beneficiary branches are different. Choose different accounts or contact the Bank. Error
118 Conversion Incorrect Document Parameters Error
119 Conversion Incorrect Remark Length Error
120 Conversion Incorrect Document Currency Rate Error
121 Conversion Incorrect Document Currency Error
122 Conversion Error occured while executing operation Error
123 Conversion Error occured while executing operation Error
124 Sender account is invalid. Please correct and try again Error
147 Wrong IBAN Format Error
150 Required Field Error
151 Field Value Must Be Numeric Error
152 Field Format Does Not Match Error
153 ID length should not exceed 11 symbols Error
154 Field value not found Error
155 Salary transfer is made only to the individual Error
157 Foreign document.bulk.result.code.pmi.recip.name.length Error
158 Foreign document.bulk.result.code.pmi.regreporting.required.field Error
333 Not Enough Working Balance Warn
363 Document has Duplicate. Warn
444 Not Enough Funds Warn
500 Internal Error Error
666 error.message.documents.wrong.content.symbols Error
669 Please, Upload Invoice or Contract Error
670 Beneficiary Account Is Incorrect Error
671 Within Georgia Beneficiary Account Is Incorrect Error
671 Incorrect Account Number Error
673 Foreign document.bulk.result.code.pmi.recipient.required.fields Error
674 Foreign You are not allowed to transfer to this account Error
674 Within BoG You are not allowed to transfer to this account Error
674 Within Georgia You are not allowed to transfer to this account Error
674 You are not allowed to transfer to this account Error
675 document.result.code.source.account.invalid Error
676 document.result.code.has.not.access.to.source.account Error
677 Foreign document.result.code.nomination.is.mandatory Error
677 Within BoG document.result.code.nomination.is.mandatory Error
677 Within Georgia document.result.code.nomination.is.mandatory Error
678 Foreign document.result.code.dispatch.type.is.mandatory Error
678 Within Georgia document.result.code.dispatch.type.is.mandatory Error
679 document.result.code.wrong.comission.account Error
701 Document inputs didn't pass validations Warn
999 Error occured while executing operation Error
1001 You don't have right to transfer Error
1002 The receiver bank data is incorrect, try again Error
9999 document.result.code.unknown.error Error
--- # Document Sign Source: https://api.bog.ge/docs/en/bonline/sign/document # Document Sign ## Parameters - `Otp` — string, required OTP - `ObjectKey` — integer, required Object Identifier **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 ``` --- # Statement entries on the page Source: https://api.bog.ge/docs/en/bonline/statement/paging # Statement entries on the page This method allows retrieving 1000 entries for an already generated account statement. ## Query params - `accountNumber` — string, required An account number. - `currency` — string, required An account currency. - `id` — integer, required A unique ID of a statement. - `page` — integer, required A page number of an account statement. If the number of generated entries is more than 1000, the portion number of a 1000-record should be passed. **REQUEST** ```api GET api/statement/{accountNumber}/{currency}/{id}/{page} ``` ## Response - `EntryDate` — date An entry date. - `EntryDocumentNumber` — string An entry document number. - `EntryAccountNumber` — string An entry account number. - `EntryAmountDebit` — decimal number An entry amount (debit). - `EntryAmountDebitBase` — decimal number A debit equivalent in GEL. - `EntryAmountCredit` — decimal number An entry amount (credit). - `EntryAmountCreditBase` — decimal number A credit equivalent in GEL. - `EntryAmountBase` — decimal number An amount equivalent in GEL. - `EntryAmount` — decimal number An entry amount. - `EntryComment` — string An entry comment, a content of the transaction. - `EntryDepartment` — string - `EntryAccountPoint` — string - `DocumentProductGroup` — string A transaction type, document product group. - `DocumentValueDate` — date A date of document entry in the bank system. - `SenderDetails` — object A sender info. - `Name` — string A name. - `Inn` — string An identification number. - `AccountNumber` — string An account number. - `BankCode` — string A bank code. - `BankName` — string A bank name. - `BeneficiaryDetails` — object A recipient info. - `Name` — string A name. - `Inn` — string An identification number. - `AccountNumber` — string An account number. - `BankCode` — string A bank code. - `BankName` — string A bank name. - `DocumentTreasuryCode` — string A treasury code. - `DocumentNomination` — string A reason, purpose of the transaction / 250 symbols max. - `DocumentInformation` — string An additional info. - `DocumentSourceAmount` — decimal number A starting amount. - `DocumentSourceCurrency` — string A starting currency. - `DocumentDestinationAmount` — decimal number A document destination amount. - `DocumentDestinationCurrency` — string A document destination currency. - `DocumentReceiveDate` — date A document receival date. - `DocumentBranch` — string - `DocumentDepartment` — string - `DocumentActualDate` — date - `DocumentExpiryDate` — date - `DocumentRateLimit` — decimal number - `DocumentRate` — decimal number A conversion rate. - `DocumentRegistrationRate` — decimal number - `DocumentSenderInstitution` — string - `DocumentIntermediaryInstitution` — string - `DocumentBeneficiaryInstitution` — string - `DocumentPayee` — string A payee. - `DocumentCorrespondentAccountNumber` — string A document correspondent account. - `DocumentCorrespondentBankCode` — string A document correspondent bank code. - `DocumentCorrespondentBankName` — string A document correspondent bank name. - `DocumentKey` — decimal number A document unique number in a bank. - `EntryId` — decimal number An entry unique ID. - `DocumentPayerName` — string A document payee name. - `DocumentPayerInn` — string A Personal Identification Number of a taxpayer individual, or an Identification Code of a legal entity. Should be filled only when a transaction is performed towards the budget on behalf of a third party (in this case an identification code of a said the third party should be filled). - `DocComment` — string A document comment. **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 ``` --- # Statement entries on the page Source: https://api.bog.ge/docs/en/bonline/statement/pagingV2 # Statement entries on the page This method is used to retrieve bank statement records for a specified account in stages (pages). The service processes the request in real time and returns a detailed list of transactions based on the available bank data. A maximum of 1,000 records can be retrieved per request. Pages must be requested sequentially — for example, if page 3 has already been retrieved, the next request must be for page 4. Skipping pages (e.g., requesting page 6 after page 3) is not allowed. ## Query params - `accountNumber` — string, required An account number. - `currency` — string, required An account currency. - `id` — integer, required A unique ID of a statement. - `page` — integer, required A page number of an account statement. If the number of generated entries is more than 1000, the portion number of a 1000-record should be passed. **REQUEST** ```api GET api/v2/statement/{accountNumber}/{currency}/{id}/{page} ``` ## Response - `Id` — integer A unique ID. - `Count` — integer A number of records. - `TotalCount` — integer The total number of records in the requested period, regardless of paging. - `Records` — object Records, transaction details. - `EntryDate` — date An entry date. - `EntryDocumentNumber` — string An entry document number. - `EntryAccountNumber` — string An entry account number. - `EntryAmountDebit` — decimal number An entry amount (debit). - `EntryAmountDebitBase` — decimal number A debit equivalent in GEL. - `EntryAmountCredit` — decimal number An entry amount (credit). - `EntryAmountCreditBase` — decimal number A credit equivalent in GEL. - `EntryAmountBase` — decimal number An amount equivalent in GEL. - `EntryAmount` — decimal number An entry amount. - `EntryComment` — string An entry comment, a content of the transaction. - `DocumentProductGroup` — string A transaction type, document product group. - `DocumentValueDate` — date A date of document entry in the bank system. - `SenderDetails` — object A sender info. - `Name` — string A name. - `Inn` — string An identification number. - `AccountNumber` — string An account number. - `BankCode` — string A bank code. - `BankName` — string A bank name. - `BeneficiaryDetails` — object A recipient info. - `Name` — string A name. - `Inn` — string An identification number. - `AccountNumber` — string An account number. - `BankCode` — string A bank code. - `BankName` — string A bank name. - `DocumentTreasuryCode` — string A treasury code. - `DocumentNomination` — string A reason, purpose of the transaction / 250 symbols max. - `DocumentInformation` — string An additional info. - `DocumentSourceAmount` — decimal number A starting amount. - `DocumentSourceCurrency` — string A starting currency. - `DocumentDestinationAmount` — decimal number A document destination amount. - `DocumentDestinationCurrency` — string A document destination currency. - `DocumentReceiveDate` — date A document receival date. - `DocumentRate` — decimal number A conversion rate. - `DocumentKey` — decimal number A document unique number in a bank. - `EntryId` — decimal number An entry unique ID. - `DocumentPayerName` — string A document payee name. - `DocumentPayerInn` — string A Personal Identification Number of a taxpayer individual, or an Identification Code of a legal entity. Should be filled only when a transaction is performed towards the budget on behalf of a third party (in this case an identification code of a said the third party should be filled). - `DocComment` — string An entry comment, a content of the transaction. Is concatenated from several transactional attributes. (for example: "Automatic payment, 22/12/2021 , JSC ""Insurance Company"", : Name Surname GE75BG00000000000000000GEL JSC "Bank of Georgia" BAGAGE22") - `AuthDate` — date The authorisation date of the operation. **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, "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 ``` --- # Statement generation Source: https://api.bog.ge/docs/en/bonline/statement/statement # Statement generation This method allows to generate an account statement for a certain account, certain period and retrieves no more than 1000 records. ## Query params - `accountNumber` — string, required An account number. - `currency` — string, required An account currency. - `startDate` — date, required A start date. - `endDate` — date, required An end date. **REQUEST** ```api GET api/statement/{accountNumber}/{currency}/{startDate}/{endDate} ``` ## Response - `Id` — integer A unique ID. - `Count` — integer A number of records. - `Records` — object Records, transaction details. - `EntryDate` — date An entry date. - `EntryDocumentNumber` — string An entry document number. - `EntryAccountNumber` — string An entry account number. - `EntryAmountDebit` — decimal number An entry amount (debit). - `EntryAmountDebitBase` — decimal number A debit equivalent in GEL. - `EntryAmountCredit` — decimal number An entry amount (credit). - `EntryAmountCreditBase` — decimal number A credit equivalent in GEL. - `EntryAmountBase` — decimal number An amount equivalent in GEL. - `EntryAmount` — decimal number An entry amount. - `EntryComment` — string An entry comment, a content of the transaction. - `EntryDepartment` — string - `EntryAccountPoint` — string - `DocumentProductGroup` — string A transaction type, document product group. - `DocumentValueDate` — date A date of document entry in the bank system. - `SenderDetails` — object A sender info. - `Name` — string A name. - `Inn` — string An identification number. - `AccountNumber` — string An account number. - `BankCode` — string A bank code. - `BankName` — string A bank name. - `BeneficiaryDetails` — object A recipient info. - `Name` — string A name. - `Inn` — string An identification number. - `AccountNumber` — string An account number. - `BankCode` — string A bank code. - `BankName` — string A bank name. - `DocumentTreasuryCode` — string A treasury code. - `DocumentNomination` — string A reason, purpose of the transaction / 250 symbols max. - `DocumentInformation` — string An additional info. - `DocumentSourceAmount` — decimal number A starting amount. - `DocumentSourceCurrency` — string A starting currency. - `DocumentDestinationAmount` — decimal number A document destination amount. - `DocumentDestinationCurrency` — string A document destination currency. - `DocumentReceiveDate` — date A document receival date. - `DocumentBranch` — string - `DocumentDepartment` — string - `DocumentActualDate` — date - `DocumentExpiryDate` — date - `DocumentRateLimit` — decimal number - `DocumentRate` — decimal number A conversion rate. - `DocumentRegistrationRate` — decimal number The document registration rate. - `DocumentSenderInstitution` — string - `DocumentIntermediaryInstitution` — string - `DocumentBeneficiaryInstitution` — string - `DocumentPayee` — string A payee. - `DocumentCorrespondentAccountNumber` — string A document correspondent account. - `DocumentCorrespondentBankCode` — string A document correspondent bank code. - `DocumentCorrespondentBankName` — string A document correspondent bank name. - `DocumentKey` — decimal number A document unique number in a bank. - `EntryId` — decimal number An entry unique ID. - `DocumentPayerName` — string A document payee name. - `DocumentPayerInn` — string A Personal Identification Number of a taxpayer individual, or an Identification Code of a legal entity. Should be filled only when a transaction is performed towards the budget on behalf of a third party (in this case an identification code of a said the third party should be filled). - `DocComment` — string A document comment. **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 ``` --- # Statement generation Source: https://api.bog.ge/docs/en/bonline/statement/statementV2 # Statement generation The service provides bank statement for the specified account within the selected period. A maximum of 1,000 transactions can be retrieved per request. If the number of transactions in the selected period exceeds this limit, additional data can be obtained by sending subsequent requests with the appropriate page parameter (using pagination). ## Query params - `accountNumber` — string, required An account number. - `currency` — string, required An account currency. - `startDate` — date, required A start date. - `endDate` — date, required An end date. **REQUEST** ```api GET api/v2/statement/{accountNumber}/{currency}/{startDate}/{endDate} ``` ## Response - `Id` — integer A unique ID. - `Count` — integer A number of records. - `TotalCount` — integer The total number of records in the requested period, regardless of paging. - `Records` — object Records, transaction details. - `EntryDate` — date An entry date. - `EntryDocumentNumber` — string An entry document number. - `EntryAccountNumber` — string An entry account number. - `EntryAmountDebit` — decimal number An entry amount (debit). - `EntryAmountDebitBase` — decimal number A debit equivalent in GEL. - `EntryAmountCredit` — decimal number An entry amount (credit). - `EntryAmountCreditBase` — decimal number A credit equivalent in GEL. - `EntryAmountBase` — decimal number An amount equivalent in GEL. - `EntryAmount` — decimal number An entry amount. - `EntryComment` — string An entry comment, a content of the transaction. - `DocumentProductGroup` — string A transaction type, document product group. - `DocumentValueDate` — date A date of document entry in the bank system. - `SenderDetails` — object A sender info. - `Name` — string A name. - `Inn` — string An identification number. - `AccountNumber` — string An account number. - `BankCode` — string A bank code. - `BankName` — string A bank name. - `BeneficiaryDetails` — object A recipient info. - `Name` — string A name. - `Inn` — string An identification number. - `AccountNumber` — string An account number. - `BankCode` — string A bank code. - `BankName` — string A bank name. - `DocumentTreasuryCode` — string A treasury code. - `DocumentNomination` — string A reason, purpose of the transaction / 250 symbols max. - `DocumentInformation` — string An additional info. - `DocumentSourceAmount` — decimal number A starting amount. - `DocumentSourceCurrency` — string A starting currency. - `DocumentDestinationAmount` — decimal number A document destination amount. - `DocumentDestinationCurrency` — string A document destination currency. - `DocumentReceiveDate` — date A document receival date. - `DocumentRate` — decimal number A conversion rate. - `DocumentKey` — decimal number A document unique number in a bank. - `EntryId` — decimal number An entry unique ID. - `DocumentPayerName` — string A document payee name. - `DocumentPayerInn` — string A Personal Identification Number of a taxpayer individual, or an Identification Code of a legal entity. Should be filled only when a transaction is performed towards the budget on behalf of a third party (in this case an identification code of a said the third party should be filled). - `DocComment` — string An entry comment, a content of the transaction. Is concatenated from several transactional attributes. (for example: "Automatic payment, 22/12/2021 , JSC ""Insurance Company"", : Name Surname GE75BG00000000000000000GEL JSC "Bank of Georgia" BAGAGE22") - `AuthDate` — date The authorisation date of the operation. **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 ``` --- # Statement with revaluation Source: https://api.bog.ge/docs/en/bonline/statement/statementV2Revaluation # Statement with revaluation The service provides bank statement for the specified account within the selected period, including revaluation records. To retrieve revaluation records, set the `revaluation=true` parameter. A maximum of 1,000 transactions can be retrieved per request. If the number of transactions in the selected period exceeds this limit, additional data can be obtained by sending subsequent requests with the appropriate page parameter (using pagination). ## Query params - `accountNumber` — string, required An account number. - `currency` — string, required An account currency. - `startDate` — date, required A start date. - `endDate` — date, required An end date. - `includeToday` — boolean Include today's operations (path, optional). - `orderByDate` — boolean Order by date (path, optional). - `take` — integer A records limit (query, optional). - `revaluation` — boolean Show revaluation records (query, optional). **REQUEST** ```api GET api/v2/statement/{accountNumber}/{currency}/{startDate}/{endDate}/{includeToday}/{orderByDate}?take={take}&revaluation={revaluation} ``` ## Response - `Id` — integer A unique ID. - `Count` — integer A number of records. - `TotalCount` — integer The total number of records in the requested period, regardless of paging. - `Records` — object Records, transaction details. - `EntryDate` — date An entry date. - `EntryDocumentNumber` — string An entry document number. - `EntryAccountNumber` — string An entry account number. - `EntryAmountDebit` — decimal number An entry amount (debit). - `EntryAmountDebitBase` — decimal number A debit equivalent in GEL. - `EntryAmountCredit` — decimal number An entry amount (credit). - `EntryAmountCreditBase` — decimal number A credit equivalent in GEL. - `EntryAmountBase` — decimal number An amount equivalent in GEL. - `EntryAmount` — decimal number An entry amount. - `EntryComment` — string An entry comment, a content of the transaction. - `DocumentProductGroup` — string A transaction type, document product group. - `DocumentValueDate` — date A date of document entry in the bank system. - `SenderDetails` — object A sender info. - `Name` — string A name. - `Inn` — string An identification number. - `AccountNumber` — string An account number. - `BankCode` — string A bank code. - `BankName` — string A bank name. - `BeneficiaryDetails` — object A recipient info. - `Name` — string A name. - `Inn` — string An identification number. - `AccountNumber` — string An account number. - `BankCode` — string A bank code. - `BankName` — string A bank name. - `DocumentTreasuryCode` — string A treasury code. - `DocumentNomination` — string A reason, purpose of the transaction / 250 symbols max. - `DocumentInformation` — string An additional info. - `DocumentSourceAmount` — decimal number A starting amount. - `DocumentSourceCurrency` — string A starting currency. - `DocumentDestinationAmount` — decimal number A document destination amount. - `DocumentDestinationCurrency` — string A document destination currency. - `DocumentReceiveDate` — date A document receival date. - `DocumentRate` — decimal number A conversion rate (the rate set by the National Bank). - `DocumentKey` — decimal number A document unique number in a bank. - `EntryId` — decimal number An entry unique ID. - `DocumentPayerName` — string A document payee name. - `DocumentPayerInn` — string A Personal Identification Number of a taxpayer individual, or an Identification Code of a legal entity. Should be filled only when a transaction is performed towards the budget on behalf of a third party (in this case an identification code of a said the third party should be filled). - `DocComment` — string An entry comment, a content of the transaction. Is concatenated from several transactional attributes. (for example: "Automatic payment, 22/12/2021 , JSC ""Insurance Company"", : Name Surname GE75BG00000000000000000GEL JSC "Bank of Georgia" BAGAGE22") - `AuthDate` — date The authorisation date of the operation. **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 ``` --- # Statement global and daily balances Source: https://api.bog.ge/docs/en/bonline/statement/summary # Statement global and daily balances This method allows retrieving summary info for certain accounts by an ID returned during generation. The method retrieves summary info in total and by day. ## Query params - `accountNumber` — string, required An account number. - `currency` — string, required An account currency. - `id` — date, required A statement unique ID. **REQUEST** ```api GET api/statement/summary/{accountNumber}/{currency}/{id} ``` ## Response - `GlobalSummary` — object A statement period summary balance. - `AccountNumber` — string An account number. - `Currency` — string A currency. - `StartDate` — date A date of the first transaction. - `EndDate` — date A date of the last transaction. - `PeriodStartDate` — date A period start date. - `PeriodEndDate` — date A period end date. - `InAmount` — decimal number An income amount. - `InAmountBase` — decimal number An income amount in the national currency. - `InRate` — decimal number An income amount conversion rate. - `OutAmount` — decimal number An outcome amount. - `OutAmountBase` — decimal number An outcome amount in the national currency. - `OutRate` — decimal number An outcome amount conversion rate. - `CreditSum` — decimal number An entry summary amount (credit). - `DebitSum` — decimal number An entry summary amount (debit). - `DailySummaries` — object A statement of daily amounts (one or more). - `Balance` — decimal number A balance. - `BalanceBase` — decimal number A balance equivalent in the national currency. - `CreditSum` — decimal number An entry summary amount (credit). - `DebitSum` — decimal number An entry summary amount (debit). - `Rate` — decimal number A conversion rate. - `EntryCount` — integer An entry count for a given date. - `Date` — date An entry 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 ``` --- # Statement global and daily balances Source: https://api.bog.ge/docs/en/bonline/statement/summaryV2 # Statement global and daily balances This method allows to view the total summary information for a specific account's statement. The method returns the full summary information, as well as the information broken down by each day. ## Query params - `accountNumber` — string, required An account number. - `currency` — string, required An account currency. - `id` — date, required A statement unique ID. **REQUEST** ```api GET api/v2/statement/summary/{accountNumber}/{currency}/{startDate}/{endDate} ``` ## Response - `GlobalSummary` — object A statement period summary balance. - `AccountNumber` — string An account number. - `Currency` — string A currency. - `StartDate` — date A date of the first transaction. - `EndDate` — date A date of the last transaction. - `PeriodStartDate` — date A period start date. - `PeriodEndDate` — date A period end date. - `InAmount` — decimal number An income amount. - `InAmountBase` — decimal number An income amount in the national currency. - `InRate` — decimal number An income amount conversion rate. - `OutAmount` — decimal number An outcome amount. - `OutAmountBase` — decimal number An outcome amount in the national currency. - `OutRate` — decimal number An outcome amount conversion rate. - `CreditSum` — decimal number An entry summary amount (credit). - `DebitSum` — decimal number An entry summary amount (debit). - `DailySummaries` — object A statement of daily amounts (one or more). - `Balance` — decimal number A balance. - `BalanceBase` — decimal number A balance equivalent in the national currency. - `CreditSum` — decimal number An entry summary amount (credit). - `DebitSum` — decimal number An entry summary amount (debit). - `Rate` — decimal number A conversion rate. - `EntryCount` — integer An entry count for a given date. - `Date` — date An entry 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 ``` --- # Current day activities Source: https://api.bog.ge/docs/en/bonline/statement/todayactivities # Current day activities This method allows us to retrieve all activities of the current day. :::note This method is rate limited — 800 requests per day are allowed (per account and currency). Exceeding the limit returns `429 Too Many Requests` with a `Retry-After` header (in seconds). ::: ## Query params - `accountNumber` — string, required An account number - `currency` — string, required A currency **REQUEST** ```api GET api/v2/documents/todayactivities/{accountNumber}/{currency} ``` ## Response - `Id` — integer A unique identifier. - `DocKey` — integer A document unique ID on the business online. - `DocNo` — string A document number. - `PostDate` — date A document creation date. - `ValueDate` — date ვალუტირების თარიღი - `EntryType` — string An entry type. Can take the following values: - PMC - GEL Operation - PLC - Card Operation - CDS - Saving Operation - LND - Loan Operation - PBS - Paybox Operation - INC - Inkaso (Debts collection) - PMD - Transfer of a national currency - PMI - Transfer of a foreign currency - COM - Fee - `EntryComment` — string An entry comment, a content of the transaction. - `EntryCommentEn` — string An entry comment, a content of the transaction in English. - `Nomination` — string A document purpose. - `Credit` — decimal number A credit. - `Debit` — decimal number A debit. - `Amount` — decimal number An amount. - `AmountBase` — decimal number An amount equivalent in GEL. - `PayerName` — string A payer name. - `PayerInn` — string A payer identification code. - `Sender` — object A sender info. - `Name` — string A name. - `Inn` — string An identification number. - `AccountNumber` — string An account number. - `BankCode` — string A bank code. - `BankName` — string A bank name. - `Beneficiary` — object A recipient info. - `Inn` — string An identification number. - `AccountNumber` — string An account number. - `BankCode` — string A bank code. - `BankName` — string A bank name. **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/en/obidentity/process # Technical Documentation for Integration with Identity Assurance Service ## Introduction This documentation describes how to integrate your application with the Open Finance Identity Assurance service. The service enables one financial institution (hereinafter “Relying Party”) to receive verified identity information about a user from another financial institution (hereinafter “Identity Provider”). The process is based on the **OpenID Connect for Identity Assurance 1.0** standard and is fully compatible with the **Financial-grade API (FAPI)** security profile. --- ## Key Concepts **Relying Party:** Your application or service that wants to verify the identity of the user. **Identity Provider:** An organization (e.g., a bank) that verifies the user's identity and provides related information. **Verified Claims:** Information about the user (e.g., first name, last name, personal ID number, etc.) that has been verified by the Identity Provider. **Evidence:** Information about the document or method the Identity Provider used to verify the user’s identity (e.g., ID card, passport). **Trust Framework:** A set of rules under which the identity verification was performed. For Georgia, the use of the `ge_aml` framework is mandatory, which ensures compliance with anti-money laundering legislation. --- ## Integration Process The integration process follows the standard OpenID Connect (OIDC) flow, but includes specific parameters for requesting verified claims. ### Step 1: Prerequisites 1. **Legal Agreement:** The relying party must be a participant in the “data exchange agreement for user identification and verification through a third party/intermediary”. 2. **Client Registration:** The relying party must obtain a unique `client_id` and authentication credentials from the Identity Provider. 3. **Using Identity Assurance services:** the client (Relying Party) authentication is performed over a secure communication channel that requires the mutual presentation of X.509 certificates (mTLS), in accordance with the standards defined for Open Banking. ### Step 2: Constructing the Authentication Request The relying party must redirect the user to the Identity Provider’s `authorization_endpoint` with the following parameters: - `response_type=code` - `client_id` - `scope=openid` (and other required scopes, e.g., `https://openfinance.ge/ns/scope/kyc`) - `redirect_uri` - `state` - `code_challenge` (if using PKCE) - `code_challenge_method` (if using PKCE) - `nonce` - **`claims` (most important parameter):** A JSON object that specifies which verified information is being requested. The `claims` parameter must comply with the OpenID Connect for Identity Assurance 1.0 standard and the User Identification and Authentication Service Standard 0.3.RC3 developed by the Open Banking Association of Georgia: 1. https://openid.net/specs/openid-connect-4-identity-assurance-1_0.html 2. https://openfinance.ge/en/standards #### Example `claims` parameter: ```json { "userinfo": { "verified_claims": { "verification": { "trust_framework": { "value": "ge_aml", "essential": true } }, "claims": { "given_name": null, "family_name": null, "personal_number": null, "birthdate": null } } } } ``` ### Step 3: Requesting the Token After successful user authentication, the Identity Provider returns an `authorization_code`, which must be used at the `token_endpoint` to obtain a token. Follow the standard OIDC protocol for this request. Parameters required for the `token_endpoint` request: - `code` - `client_id` - `grant_type=authorization_code` - `redirect_uri` - `code_verifier` (if using PKCE) ### Step 4: Retrieving User Information To retrieve user information, use the `userinfo_endpoint`. The service will respond with the user's details as defined in the `claims` parameter, including any verified claims. To call the `userinfo` endpoint, you must provide the `Authorization` header with the `Bearer {access_token}` received from the `token_endpoint`. --- # technical-information Source: https://api.bog.ge/docs/en/obidentity/technical-information # Endpoints ### Test environment OpenID Provider's configuration: https://account-ob-test.bog.ge/auth/realms/bog-test/.well-known/ob-openid-configuration ### Production environment OpenID Provider's configuration: https://ob-identity.bog.ge/auth/realms/bog/.well-known/ob-openid-configuration --- # Introduction Source: https://api.bog.ge/docs/en/sandbox/payments/introduction ## Aggregator Integration Protocol for E-Commerce Services ## What is Sandbox Environment? The Sandbox environment is an isolated testing space that allows you to safely integrate and validate your ecommerce payment flows using the Online Payment API without processing real transactions or moving real funds. In Sandbox, you can simulate orders, payment authorizations, callbacks, and refunds using test credentials and test card values. Sandbox helps you verify integration scenarios, handle callback notifications correctly, and identify issues before going live. :::tip · Use Sandbox credentials only · Use test cards provided in this documentation · Test full payment flows: order creation, payment authorization, callbacks, refunds, save cards, complete preauthorization · Validate callback handling and idempotency logic ::: :::danger caution · Do not use real card data and live credentials · Do not rely on Sandbox data for accounting or reporting · Do not use Sandbox for stress or performance testing ::: The Sandbox environment is intended for functional and integration testing only. Sandbox data never appears in Live, and vice versa. Always verify that the correct credentials and endpoints are configured for each environment. ## What is Online Payment API? The Online Payment API is a robust, developer-friendly solution designed to integrate a secure payment module into any electronic system quickly and effortlessly. It streamlines payment processing, allowing business to receive payments using various payment methods, including cards from Bank of Georgia and other commercial banks (VISA, MasterCard, American Express). ## Protocol and Technical Specifications - **API Architecture:** RESTful - **Communication Protocol:** HTTP/1.1 (All API calls must be made over HTTPS to ensure secure data transmission.) - **Data Format:** JSON is used for both request payloads and response bodies, facilitating easy integration. - **Authentication & Security:** OAuth 2.0 is used for authentication, while JSON Web Tokens (JWT) ensure secure data exchange. - **Synchronous API Calls:** Every API request is processed immediately, delivering a response that reflects the outcome of the API call. - **Asynchronous Webhook Notifications:** Although API calls are synchronous, key events, such as payment confirmations and updates, are managed asynchronously via Callbacks for reliable, real-time communication. - **Error Handling:** Standard HTTP status codes and descriptive error messages are used to indicate success or error states, helping developers quickly diagnose issues. ## Checkout Process Overview - **Customer Initiates Payment:** The customer selects the desired product or service (or a combination in a shopping cart) on the business's website and clicks the payment button. - **Business Sends an Order Request:** The business sends an [order request](https://api.bog.ge/docs/en/payments/standard-process/create-order) to the online payment API to initiate the operation, marking the beginning of the payment process. - **API Returns Order Request Details:** The payment gateway responds with the necessary parameters—such as an order request ID and a redirect URL—that enable the payment process to continue. - **Customer is Redirected to the Online Payment Page:** The business directs the customer to the online payment page. Here, the customer chooses the payment method, enters their card details or uses internet banking to authorize the payment. - **Payment Processing:** The online payment system validates payment details and securely processes the payment. - **Callback Notification Sent to Business:** Once the transaction is processed, the payment gateway sends a [Callback](https://api.bog.ge/docs/en/payments/standard-process/callback), to the business’s callback URL, provided in the order request. :::note Receiving the callback is a crucial step in the payment process. it confirms the payment status (successful or failed) and other essential details. Based on the information received in the callback, the business must ensure that its system is updated accordingly. ::: - **Operation Completion:** After receiving the callback, the business finalizes the process by confirming the order to the customer and completing any related fulfillment activities. :::note Before redirecting to the online payments page, the business can use the card-saving feature to carry out future transactions automatically or without entering card details. ::: --- # Authentication Method Source: https://api.bog.ge/docs/en/sandbox/payments/authentication :::caution note In the Sandbox environment, you must authenticate using Sandbox API credentials only. Authentication tokens generated in Sandbox are valid only within this environment and must not be used in Production. Sandbox tokens simulate real authorization flows but do not provide access to live financial operations. ::: ## What do I need to use the payment API? To use the payment API, [HTTP Basic Auth](https://en.wikipedia.org/wiki/Basic_access_authentication) is required. You will need to know the unique credentials of your business to enter the system. These credentials consist of two parameters, `client_id`, and `client_secret`, used as the username and password for business authentication. ## How to obtain the credentials for entering the business system? Upon registering a company as a business in the banking system and providing all the necessary data, the system provides the credentials `client_id` and `client_secret` necessary to enter the system. These credentials are unique identifiers of the business. It is impermissible to disclose or transfer the `client_secret` parameter to another person. Doing so significantly increases the probability of a security breach. The business cannot change the `client_secret` parameter. ## Method description This method allows businesses to undergo the authentication process. Upon calling the API, the online payment server returns the `Bearer Token`, which is the necessary authentication parameter for calling all further methods. ### Header parameters - `Content-Type` — application/x-www-form-urlencoded, required - `Authorization` — Basic , required 'Basic ' + ':' encoded in the Base64 format is transmitted as a value (e.g., 'Basic ODI4Mjo3Njk3MDY0OTlmMDcwOWUyMzQ4NDU4NjNmOThiMjMxNA=='), where and are the credentials necessary to enter the system, transmitted by the bank to the business. ### Body parameters - `grant_type` — client_credentials, required The fixed text `client_credentials` is transmitted as the value. **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 The Token is returned by the authorization server. - `token_type` — string The type of Token (fixed value – `Bearer` – is returned). - `expires_in` — number The number of seconds while the Token is active. **RESPONSE** ```json { "access_token": "", "token_type": "Bearer", "expires_in": 1634719923245 } ``` --- # Order Request Source: https://api.bog.ge/docs/en/sandbox/payments/standard-process/create-order :::caution note All order requests in Sandbox generate simulated order IDs and redirect URLs. You can safely test the complete checkout flow, including redirect, card data entry, and callback handling, without processing real payments. Use the [Test Cards](../test-cards) page for supported test values. ::: To place an order request, businesses must send payment details, technical specifications, and the amount to be paid to the online payment server. If the process is successful, the customer should be redirected to the online payment page at the `redirect` address returned to the `_link` parameter to complete the payment. ### Header parameters - `Content-Type` — application/json, required - `Authorization` — Basic , required `Bearer `, where `jwt_token` is the token returned in the `access_token` parameter of the authentication method response. - `Idempotency-Key` — UUID v4 The Idempotency-Key parameter should be unique for each new API request. Subsequent requests to the same API endpoint with the same Idempotency-Key header will result in the server returning the same status code and response body as the initial request. This functionality is particularly useful to ensure consistent outcome in scenarios where network issues or retries may lead to duplicate requests. - `Accept-Language` — string The language of the interface that the customer will see when redirected to the online payment page. The possible values are: - `ka` - Georgian (default) - `en` - English. - `Theme` — string The theme of the interface that the customer will see when redirected to the online payment page. The possible values are: - `light` - Light (default) - `dark` - Dark. ### Body parameters - `application_type` — "web" | "mobile" Defines the type of application from which the order was created. This parameter is used specifically when an order is created using Apple Pay, directly from the merchant's webpage or mobile application. `application_type` has two values: - `web` - For orders created from a webpage. - `mobile` - For orders created from a mobile application. - `buyer` — object Information about the buyer. - `buyer.full_name` — string The buyer's name and surname. - `buyer.masked_email` — string The buyer's masked email address. - `buyer.masked_phone` — string The buyer's masked phone number. - `callback_url` — string, required The web address of the business (must be HTTPS), which will be automatically called by the bank upon completion of the payment to provide the business with the payment details (via Callback). - `external_order_id` — string The payment identifier from the business's system. The first 25 characters of the provided value will be reflected in the payment description, both on the payer's bank statement and in the description of the transaction when the funds are credited to the company's account. - `capture` — "automatic" | "manual" The transaction type takes two values: - `automatic` - creation of a standard order, payment will be made without pre-authorization, and the amount will be immediately withdrawn from the customer’s account. - `manual` - after payment, the amount on the customer’s account will be blocked and will not be available for the customer. To complete the payment, it is necessary to use the pre-authorization completing method and confirm/reject the transaction. If this operation is not performed within 30 days, the amount will be automatically unblocked and will be available again for the customer. This feature can only be used when paying through Apple Pay, Google Pay or by a card. - `purchase_units` — object, required The purchase information. - `purchase_units.basket` — array, required A basket of products or services purchased within a given payment in a business. - `purchase_units.basket[].product_id` — string, required The purchased product/service identifier in the business system. - `purchase_units.basket[].description` — string The name (description) of the purchased product/service. - `purchase_units.basket[].quantity` — number, required The quantity (volume) of each product/service. The minimum value is 1. - `purchase_units.basket[].unit_price` — number, required The purchased product/service unit price. - `purchase_units.basket[].unit_discount_price` — number The volume of the deducted amount on the product/service unit in case of discount payment. - `purchase_units.basket[].vat` — number The value added tax (VAT) of the purchased product/service. - `purchase_units.basket[].vat_percent` — number The percentage of value added tax (VAT) of the purchased product/service. - `purchase_units.basket[].total_price` — number The total price of the purchased product/service. - `purchase_units.basket[].image` — string The web address of the product/service image. - `purchase_units.basket[].package_code` — string The product code of the purchased product/service. - `purchase_units.basket[].tin` — string The taxpayer identification number (TIN). - `purchase_units.basket[].pinfl` — string The personal identification number of an individual (PINFL). - `purchase_units.basket[].product_discount_id` — string Product discount identifier. If a discount promotion is registered in the bank with the provided value, taking into account the terms of the discount, the corresponding promotion will be applied to the order. - `purchase_units.delivery` — object Information about the delivery service. - `purchase_units.delivery.amount` — number The delivery fee. - `purchase_units.total_amount` — number, required The full amount is to be paid. - `purchase_units.total_discount_amount` — number The reduced amount in case of payment with a discount. - `purchase_units.currency` — string The currency in which payment is made: - `GEL` - Georgian Lari (default) - `USD` - US dollar - `EUR` - Euro - `GBP` - British pound. - `redirect_urls` — object The business web addresses that customers can be redirected to from the online payment system upon completion of the payment. - `redirect_urls.success` — string The web address in the case of successful completion of the transaction. If it is empty, the customer will remain on the online payments page and a corresponding receipt will be shown. - `redirect_urls.fail` — string The web address in the case of unsuccessful completion of the transaction. If it is empty, the customer will remain on the online payments page and a corresponding receipt will be shown. - `ttl` — number Specifies the duration of the order lifespan in minutes (the number of minutes a customer will be able to pay). The logic of this parameter can vary depending on the business's industry. The minimum value is 2 minutes, and the maximum is 1440 minutes (24 hours). If this parameter is left empty, the system defaults to 15 minutes. - `payment_method` — array The payment methods that a customer can use to pay for the order. The business must have all the methods it provides here activated. If the parameter is left empty, upon redirecting a customer to the online payment page, they will be able to use all the payment methods available for the business. The possible values are: - `card` - payment by a bank card :::note **In the Sandbox environment, only card payments are currently available.**
Additional payment methods will be added soon. ::: - `google_pay` - payment through Google Pay and by a bank card (in the case of providing this option, the customer will be able to pay both by Google Pay and a bank card. The Business must have both payment methods activated) - `apple_pay` - payment through Apple Pay and by a bank card (in the case of providing this option, the customer will be able to pay both by Apple Pay and a bank card. The Business must have both payment methods activated) - `bog_p2p` - transferring by the BoG, internet, or mobile bank user - `bog_loyalty` - payment by the BoG MR/Plus points - `bnpl` - payment with Buy Now Pay Later plan - `bog_loan` - standard bank installment plan - `gift_card` - payment with a gift card - `config` — object Configuration of a specific payment. - `config.loan` — object Payment configuration. Transmission of a parameter is necessary if you wish the payment to be made only by installment plan ("payment_method":["bog_loan"]) or only by bnpl ("payment_method":["bnpl"]). - `config.loan.type` — string Discount code of the installment/bnpl (the value of the discount_code parameter returned by the calculator). - `config.loan.month` — number Duration of the installment/bnpl in months (the value of the month parameter returned by the calculator). - `config.campaign` — object Duration of the installment/bnpl in months (the value of the month parameter returned by the calculator). - `config.campaign.card` — string A card type, to which the discount applies to: - `visa` - Visa - `mc` - MasterCard - `solo` - SOLO card - `config.campaign.type` — string Discount type: - `restrict` - card type restriction - `client_discount` - discount on a specific card type - `config.google_pay` — object Payment configuration. Transmission of a parameter is necessary if you wish to make Google Pay payment from your own webpage. - `config.google_pay.google_pay_token` — string Full string representing the encrypted Google Pay payment details. It must include all nested fields as received from the Google Pay SDK without modification or truncation. - `config.google_pay.external` — boolean - `true` - payment is initiated from the Google Pay button on business' webpage - `false` - Payment is initiated from the bank's webpage (default). - `config.apple_pay` — object Payment configuration. This parameter is necessary if you wish to enable Apple Pay payments from your own webpage. - `config.apple_pay.external` — boolean - `true` -Payment is initiated from the Apple Pay button on the business's webpage. - `false` - Payment is initiated from the bank's webpage (default). - `config.account` — object Payment configuration: This object is necessary if you have configured multiple e-commerce POS terminals in the same currency. It allows you to group payments based on business needs or settle payments on different business bank accounts. - `config.account.tag` — string E-commerce POS identifier. If provided tag does not match with POS configuration or tag was not provided, the operation will default to the default POS terminal and its corresponding payment account. Note: It is important to agree upon tag values when configuring additional ecommerce POS terminal. **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 Order identifier. - `_links` — object The web resource addresses are used in the further stages of the payment process. At the moment two resources are returned: - `_links.details.href` — string The address of the payment details can be used to obtain information on the online payment. - `_links.redirect.href` — string The web page address, which a customer shall be redirected to in order to enter a plastic card or online banking details and complete the process. **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}" } } } ``` --- # Payment Details Source: https://api.bog.ge/docs/en/sandbox/payments/standard-process/get-payment-details This method allows businesses to receive detailed information about an online payment using its identifier. ### Header parameters - `Authorization` — Basic , required The meaning `Bearer ` is transmitted, where `jwt_token` is the meaning returned to the access_token parameter of the Response method. ### Path parameter - `order_id` — string, required The order identifier returned to the online shop in the response of the create order request. **CURL** ```bash curl -X GET 'https://api-sandbox.bog.ge/payments/v1/receipt/:order_id' \ -H 'Authorization: Bearer ' ``` ## Response - `order_id` — string The online payment identifier. - `industry` — string The business industry, defined during its registration. - `capture` — string The authorization method, always - `automatic`. transaction type with two possible meanings: - `automatic` - a standard order - `manual` - a pre-authorization order - `external_order_id` — string The payment identifier from the business's system. The first 25 characters of the provided value will be reflected in the payment description, both on the payer's bank statement and in the description of the transaction when the funds are credited to the company's account. - `client` — object The business information. - `client.id` — string The business identifier in the bank system. - `client.brand_ka` — string The business Georgian name. - `client.brand_en` — string The business English name. - `client.url` — string The business web-site address. - `zoned_create_date` — string The order creation date in Coordinated Universal Time ( UTC). It follows the format "YYYY-MM-DDTHH:MM:SS.ssssssZ". - `zoned_expire_date` — string The order expiration date in Coordinated Universal Time (UTC). It follows the format "YYYY-MM-DDTHH:MM:SS.ssssssZ". - `order_status` — object Order status. - `order_status.key` — string The status gets the following meanings: - `created` - payment request is created - `processing` - payment is being processed - `completed` - payment process has been completed - `rejected` - payment process has been unsuccessfully completed - `refund_requested` - refund of the amount is requested - `refunded` - payment amount has been returned - `refunded_partially` - payment amount has been partially refunded - `auth_requested` - pre-authorize payment is requested - `blocked` - pre-authorize payment has been completed successfully, but payment amount is blocked and waiting for confirmation - `partial_completed` - pre-authorize payment partial amount has been confirmed successfully - `order_status.value` — string Description. - `buyer` — object The buyer information. - `buyer.full_name` — string The buyer's full name. - `buyer.email` — string The buyer's email. - `buyer.phone_number` — string The buyer's phone number. - `purchase_units` — object Information on the purchased products. - `purchase_units.request_amount` — string The requested amount of the order. - `purchase_units.transfer_amount` — string The processed amount of the order. - `purchase_units.refund_amount` — string The refunded amount. - `purchase_units.currency_code` — string Currency. - `purchase_units.items` — array The list of the purchased products/services. - `purchase_units.items[].external_item_id` — string The purchased product/service identifier in the business system. - `purchase_units.items[].description` — string The name (description) of the purchased product/service. - `purchase_units.items[].quantity` — string The quantity (volume) of each product/service. - `purchase_units.items[].unit_price` — string The purchased product/service unit price. - `purchase_units.items[].unit_discount_price` — string The volume of the deducted amount on the product/service unit in case of discount payment. - `purchase_units.items[].vat` — string The value added tax (VAT) of the purchased product/service. - `purchase_units.items[].vat_percent` — string The percentage of value added tax (VAT) of the purchased product/service. - `purchase_units.items[].total_price` — string The total price of the purchased product/service. - `purchase_units.items[].package_code` — string The product code of the purchased product/service. - `purchase_units.items[].tin` — string The taxpayer identification number (TIN). - `purchase_units.items[].pinfl` — string The personal identification number of an individual (PINFL). - `purchase_units.basket[].product_discount_id` — string Product discount identifier. If a discount promotion is registered in the bank with the provided value, taking into account the terms of the discount, the corresponding promotion will be applied to the order. - `redirect_links` — object The business web-pages, to which customers can be re-directed from the online payment system upon completion of the transaction. - `redirect_links.fail` — string The web-address in the case of transaction failure. - `redirect_links.success` — string The web-address in the case of transaction success. - `payment_detail` — object Payment details. - `payment_detail.transfer_method` — string Payment method. - `payment_detail.transfer_method.key` — string The payment method gets the following meanings: - `card` - payment by a bank card :::note **In the Sandbox environment, only card payments are currently available.**
Additional payment methods will be added soon. ::: - `google_pay` - payment through Google Pay - `apple_pay` - payment through Apple Pay - `bog_p2p` - transferring by a customer of the Bank of Georgia, internet or mobile banking - `bog_loyalty` - payment by BoG MR/Plus points - `bnpl` - payment in installments - `bog_loan` - standard bank installment plan. - `payment_detail.transfer_method.value` — string Description. - `payment_detail.transaction_id` — string Transaction identifier. - `payment_detail.auth_code` — string Payment authorization identifier. The value will also be reflected in the settlement statement on the company's account. - `payment_detail.payer_identifier` — string A payer's identifier, according to the `transfer_method`, gets various meanings: - `card`/`google_pay` – the card’s encoded number is returned (PAN) - `apple_pay` – a device-specific number assigned to your card by Apple is returned - `bog_p2p`/`bog_loyalty` – the account name is returned - `bog_loan`/`bnpl` – the first letter of a customer name is returned. - `payment_detail.payment_option` — string Payment method. The following values can be returned: - `direct_debit` - card payment - `recurrent` - payment by the saved card - `subscription` - automatic payment by the saved card. - `payment_detail.card_type` — string The type of card used for payment. The parameter takes its value during the card payment: - `amex` - American Express - `mc` - Mastercard - `visa` - Visa. - `payment_detail.card_expiry_date` — string Expiration date (month/year) of the card with which the payment was made. The parameter takes value at the time of card payment. - `payment_detail.request_account_tag` — string E-commerce POS identifier requested in the order. - `payment_detail.transfer_account_tag` — string E-commerce POS identifier on which the payment was processed. - `payment_detail.saved_card_type` — string Saved card type. Possible values are listed below: - `recurrent` - Card saved for client initiated future payments. - `subscription` - Card saved for automatic, subscription payments with fixed amount and details. - `payment_detail.parent_order_id` — string If payment was initiated using saved card, saved card order Id is given. - `payment_detail.code` — string Payment Response Code. - `payment_detail.code_description` — string Payment Response Code Description. - `payment_detail.auth_code` — string Card, Google Pay or Apple Pay Payment Authorization Code. - `discount` — object Discount details, that was applied on the payment - `discount.bank_discount_amount` — string Bank Discount Amount - `discount.bank_discount_desc` — string Bank Discount Description - `discount.system_discount_amount` — string Card system discount amount - `discount.system_discount_desc` — string Card system discount description - `discount.discounted_amount` — string Amount after discount - `discount.original_order_amount` — string Original amount - `actions` — array The list of actions associated with an order. - `actions[].action_id` — string The action identifier. - `actions[].request_channel` — string The channel, from which the action was initiated: - `public_api` - online payments API - `business_manager` - business manager website - `support` - BOG inner system. - `actions[].action` — string The action type: - `authorize` - confirmation of pre-authorize payment - `partial_authorize` - confirmation of pre-authorize payment - `cancel_authorize` - rejection of pre-authorize payment - `refund` - refund - `partial_refund` - partially refund - `actions[].status` — string The action status: - `completed` - action has been completed successfully - `rejected` - has been completed unsuccessfully - `actions[].code` — string Action response code. See [here](../response-codes#action-response-codes) for the List of Action Response Codes. - `actions[].code_description` — string Action response code description. - `actions[].zoned_action_date` — string The date when the action was initiated in Coordinated Universal Time (UTC). It follows the format "YYYY-MM-DDTHH:MM:SS.ssssssZ". - `actions[].amount` — string The amount associated with the action. - `lang` — string The interface language found by a customer after re-directing to the online payment page. There are two meanings: - `ka` - Kartuli (Georgian) - `en` - English - `reject_reason` — string The reason for payment failure. The parameter takes value only if the order failed ("order_status": "rejected"). takes the following values: - `expiration` - the order has expired - `unknown` - an unidentified reason. - `Payment Response Code Description` - Payment rejection reason, initiated by card, Google Pay or Apple Pay. See full list of Response codes [here](https://api.bog.ge/docs/en/docs/en/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/en/sandbox/payments/standard-process/callback :::caution note Callback events in Sandbox are simulated. Always implement robust callback handling and verify signature validation logic, even when testing in Sandbox. ::: A callback is an asynchronous, server-to-server notification sent from the online payment system to your designated callback URL. Its purpose is to reliably inform your system about the final status of a transaction. Unlike synchronous API calls where your application requests information and waits for an immediate response, the callback process works in the background. The payment system will automatically send a POST request to your callback URL once a transaction is complete, whether successful or unsuccessful, including the initial payment or related actions such as partial/full refunds, preauthorization approvals, and split payments. The logic for receiving and processing this callback must be implemented on the business side, including the validation for callback signature. Proper handling of the callback is a crucial step to confirm the payment status and securely update the order in your system. Payment details are sent to the callback URL, provided when the order was requested, using the POST method. To confirm successful receipt of the callback, the business should return HTTP CODE 200. If callback was not received successfully, business must use the [Get Payment Details](https://api.bog.ge/docs/en/payments/standard-process/get-payment-details) method to verify the payment status and correctly update the order status in its system. :::note **Callback and Redirect URL serve distinct purposes:** **Redirect URL** - Redirects the customer from the online payment page back to the business’s website after payment, enhancing the user experience. However, it does not guarantee the final payment status, as redirection may fail due to user actions or other circumstances, making it essential to verify payment completion through a server-to-server callback. **Callbacks** - Ensure payment status confirmation and the secure delivery of payment information from the online payment system’s server to the business’s server. Unlike Redirect URLs, callbacks are independent of user actions and serve as a reliable source for verifying payment status. ::: # Request ### Header Parameters - `Callback-Signature` — string Signature generated by encrypting callback's request body with a `private key` using `SHA256withRSA` algorithm. In order to ensure integrity of callback data, business should verify signature using request body and `public key`. It is essential to execute this verification before the deserialization of the request body, ensuring that the order of fields remains unchanged. **PUBLIC KEY** ```bash -----BEGIN PUBLIC KEY----- MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAqczfAuhtxw2iF68kS0Hy bGSv0ZlDAjsXh6VC8avDl3Vxa9qCn6Pzl37Tl2Z21WodiISLeXdhCtOMTeLNUBeb CYD31y2/MwnhLYqlCk2bOh29fyPc1iT5Eu/k/1IaNRrK9/UVZaTkhOMeEm+aL4y8 5XsE4UjqftEmwrAdbO2G4cCpuoMC9ZXG9gAdr2BFN6i2Vt9eCen5Poj7E1ik7s8T GyzploVV0NflhwBGeWnvQANUQGr87gsP5k2JG1z5EwnMybJQ7i3XT726rJMaV6QW sY5hP72Mtv1I1zL2d9FXm9FWOzbpcXCyxuEBXvqqOHzogri8C7KRRYKyk97Ri7D6 8wIDAQAB -----END PUBLIC KEY----- ``` ### Body Parameters - `event` — string Callback type. The meaning is always `order_payment`. - `zoned_request_time` — string Date of sending a callback in Coordinated Universal Time (UTC). It follows the format "YYYY-MM-DDTHH:MM:SS.ssssssZ". - `body` — object Order data. Involves the [payment detail](https://api.bog.ge/docs/en/payments/standard-process/get-payment-details#response) containing fields. **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", ... } } ``` --- # Save Card for Recurring Payments Source: https://api.bog.ge/docs/en/sandbox/payments/saved-card/recurrent The bank offers businesses the option to save a customer's card information, with the customer's consent, to enable future payments without having to enter card details again. To use this feature, the business should call the relevant method and provide the order identifier before redirecting the customer to the payment page upon order request. If the card payment is successful for the given order, the same identifier can be used for future orders. ### Header parameters - `Authorization` — Basic , required `Bearer `, where `jwt_token` is the token returned in the `access_token` parameter of the authentication method response. - `Idempotency-Key` — UUID v4 The Idempotency-Key parameter should be unique for each new API request. Subsequent requests to the same API endpoint with the same Idempotency-Key header will result in the server returning the same status code and response body as the initial request. This functionality is particularly useful to ensure consistent outcome in scenarios where network issues or retries may lead to duplicate requests. ### Path parameters - `order_id` — string, required The order identifier is returned in response to the order request. ### Response - `Http Status: ` — 202 ACCEPTED The request has been accepted. **CURL** ```bash curl -X PUT 'https://api-sandbox.bog.ge/payments/v1/orders/:order_id/cards' \ -H 'Authorization: Bearer ' ``` --- # Save Card for Automatic Payments Source: https://api.bog.ge/docs/en/sandbox/payments/saved-card/offline The bank offers businesses the option to save a customer's card information, with the customer's consent, so that it can withdraw the amount automatically, without the customer's participation in the future. To use this feature, the business should call the relevant method and provide the order identifier before redirecting the customer to the payment page upon order request. If the card payment is successful for the given order, the same identifier can be used for future orders. ### Header parameters - `Authorization` — Basic , required `Bearer `, where `jwt_token` is the token returned in the `access_token` parameter of the authentication method response. - `Idempotency-Key` — UUID v4 The Idempotency-Key parameter should be unique for each new API request. Subsequent requests to the same API endpoint with the same Idempotency-Key header will result in the server returning the same status code and response body as the initial request. This functionality is particularly useful to ensure consistent outcome in scenarios where network issues or retries may lead to duplicate requests. ### Path parameters - `order_id` — string, required The order identifier is returned in response to the order request. ### Response - `Http Status: ` — 202 ACCEPTED The request has been accepted. **CURL** ```bash curl -X PUT 'https://api-sandbox.bog.ge/payments/v1/orders/:order_id/subscriptions' \ -H 'Authorization: Bearer ' ``` --- # Delete Saved Card Source: https://api.bog.ge/docs/en/sandbox/payments/saved-card/delete This method allows businesses to delete previously saved card information from the system. ### Header parameters - `Authorization` — Basic , required `Bearer `, where `jwt_token` is the token returned in the `access_token` parameter of the authentication method response. - `Idempotency-Key` — UUID v4 The Idempotency-Key parameter should be unique for each new API request. Subsequent requests to the same API endpoint with the same Idempotency-Key header will result in the server returning the same status code and response body as the initial request. This functionality is particularly useful to ensure consistent outcome in scenarios where network issues or retries may lead to duplicate requests. ### Path parameters - `order_id` — string, required The order identifier is returned in response to the order request. ### Response - `Http Status: ` — 202 ACCEPTED The request has been accepted. **CURL** ```bash curl -X DELETE 'https://api-sandbox.bog.ge/payments/v1/charges/card/:order_id' \ -H 'Authorization: Bearer ' ``` --- # Payment by the Saved Card Source: https://api.bog.ge/docs/en/sandbox/payments/saved-card/recurrent-payment This method allows businesses to enable customers to make payments on the bank's webpage without entering their card details again. This feature is useful when a customer has previously saved their card information during a successful card payment transaction for future use. ### Path parameters - `parent_order_id` — string, required The order identifier is returned in response to the order request. :::note The `Header`, `Body` and `Response` parameters for this method are the same as those used for the [order request method.](https://api.bog.ge/docs/en/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" } ] } }' ``` --- # Automatic Payment by the Saved Card Source: https://api.bog.ge/docs/en/sandbox/payments/saved-card/offline-payment This method enables businesses to automatically withdraw funds from a customer's saved card without their participation. This feature is useful when a customer has previously saved their card information for automatic withdrawals during a successful card payment transaction. ### Header parameters - `Content-Type` — application/json, required - `Authorization` — Basic , required `Bearer `, where `jwt_token` is the token returned in the `access_token` parameter of the authentication method response. - `Idempotency-Key` — UUID v4 The Idempotency-Key parameter should be unique for each new API request. Subsequent requests to the same API endpoint with the same Idempotency-Key header will result in the server returning the same status code and response body as the initial request. This functionality is particularly useful to ensure consistent outcome in scenarios where network issues or retries may lead to duplicate requests. ### Path parameters - `parent_order_id` — string, required The order identifier on which the card was initially saved for automatic amount withdrawals. ### Body parameters - `callback_url` — string The web address of the business will be automatically called by the bank after the transaction is completed to transmit payment data (via callback). If the parameter is empty, the system will use the value transmitted during the creation of the order corresponding to the `parent_order_id.` - `external_order_id` — string The payment identifier from the business system (e.g., the purchase basket identifier). If the parameter is empty, the system will use the value transmitted during the creation of the order corresponding to the `parent_order_id.` :::note For the remaining parameters (amount, currency, buyer information, etc.) required for the order request, the system will automatically use the values transmitted during the creation of the order corresponding to the `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 The order identifier. - `_links` — object The web resource addresses are used in the further stages of the payment process. - `_links.details.href` — string The address of the payment details can be used to obtain information on the online payment. **RESPONSE** ```json { "id": "{order_id}", "_links": { "details": { "href": "https://api-sandbox.bog.ge/payments/v1/receipt/{order_id}" } } } ``` --- # Introduction Source: https://api.bog.ge/docs/en/sandbox/payments/preauthorization/introduction These methods allow businesses to complete the withdrawal process for the amount that was previously blocked during the [order request](https://api.bog.ge/docs/en/payments/standard-process/create-order) These methods are useful if the value of the capture field was set to manual during the order request. There are three methods available for completing the payment: full confirmation of the amount, partial confirmation of the amount, and rejection of the pre-authorization. [Confirm Pre-Authorization](https://api.bog.ge/docs/en/payments/preauthorization/approve) [Reject Pre-Authorization](https://api.bog.ge/docs/en/payments/preauthorization/reject) --- # Confirm Pre-Authorization Source: https://api.bog.ge/docs/en/sandbox/payments/preauthorization/approve This method allows businesses to confirm pre-authorized amounts, either in full or partially. ### Header parameters - `Content-Type` — application/json, required - `Authorization` — Basic , required `Bearer `, where `jwt_token` is the token returned in the `access_token` parameter of the authentication method response. - `Idempotency-Key` — UUID v4 The Idempotency-Key parameter should be unique for each new API request. Subsequent requests to the same API endpoint with the same Idempotency-Key header will result in the server returning the same status code and response body as the initial request. This functionality is particularly useful to ensure consistent outcome in scenarios where network issues or retries may lead to duplicate requests. ### Path parameters - `order_id` — string, required The order identifier is returned in response to the order request. ### Body parameters - `amount` — number The amount is to be confirmed. If an exact amount is specified, the confirmation will be considered full; otherwise, it will be considered partial. If no amount is specified, the entire pre-authorized `amount` will be confirmed. - `description` — string A reason for confirmation. **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 The key or identifier for the status of the API request. - `message` — string The human-readable message associated with the API request. - `action_id` — string The unique identifier for the action associated with the API request. **RESPONSE** ```json { "key": "request_received", "message": "Pre-authorization payment approval request received", "action_id": "e786283f-dc7f-48ba-bb75-12857f5a43ad" } ``` --- # Reject Pre-Authorization Source: https://api.bog.ge/docs/en/sandbox/payments/preauthorization/reject This method allows businesses to reject pre-authorized amounts in full. ### Header parameters - `Content-Type` — application/json, required - `Authorization` — Basic , required `Bearer `, where `jwt_token` is the token returned in the `access_token` parameter of the authentication method response. - `Idempotency-Key` — UUID v4 The Idempotency-Key parameter should be unique for each new API request. Subsequent requests to the same API endpoint with the same Idempotency-Key header will result in the server returning the same status code and response body as the initial request. This functionality is particularly useful to ensure consistent outcome in scenarios where network issues or retries may lead to duplicate requests. ### Path parameters - `order_id` — string, required The order identifier is returned in response to the order request. ### Body parameters - `description` — string A reason for rejection. **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 The key or identifier for the status of the API request. - `message` — string The human-readable message associated with the API request. - `action_id` — string The unique identifier for the action associated with the API request. **RESPONSE** ```json { "key": "request_received", "message": "Pre-authorization payment cancellation request received", "action_id": "aa9478c7-f82f-45a9-8a30-e7b4275b1224" } ``` --- # Online Installment Plan Modal Source: https://api.bog.ge/docs/en/sandbox/payments/external-orders/modal :::info Integration of the installment plan model is necessary only in the case, if you want a consumer to choose the installment plan conditions on your page. ::: ## Buy Now Pay Later Visual Guide If you would like to place a ‘Buy Now Pay Later’ button on your page, please use the BNPL visual guide. Click [ { e.preventDefault(); const link = document.createElement('a'); link.href = '/docs/en/bnpl-button-guideline.pdf'; link.download = 'bnpl-button-guideline.pdf'; document.body.appendChild(link); link.click(); document.body.removeChild(link); }}>here](https://api.bog.ge/docs/en/docs/en/bnpl-button-guideline.pdf) to download the guide. ## Online Installment Plan Modal To choose the online installment plan conditions, we have prepared a special modal. The modal is a kind of loan calculator, where a customer, resulting from the basket cost, can see an approximate monthly payment and annual interest rate. As the conditions are always individual and rely on the agreement concluded between the Bank of Georgia and Merchant (including a 0% installment plan condition), they differ from the standard conditions. Providing a borrower with this information is important. All the information is given in the modal, thus helping a customer in decision-making. Respectively, prior to activation of the installment plan, a kind of loan calculator is necessary, which is an independent microservice and [needs integration](https://api.bog.ge/docs/en/docs/en/payments/authentication) on the Merchant’s site. The Bank of Georgia is offering a ready-made SDK, compatible with all devices (Desktop, Mobile, Tablet) and needs addition of a ready code fragment on the site. ![Online Installment Modal](../../assets/installment-modal.png) ### Example: ### Integration To begin the installment plan modal SDK integration, copy the code in HTML page. Put our client_id instead of the {`client_id`}. ```html ``` --- ### Modal demonstration To show the installment plan modal use the `BOG.Calculator.open` method. #### Parameters - `amount` — number, required Installment plan amount - `bnpl` — boolean The parameter defines whether to show the `standard installment plan` or/and `payment in installments` to a customer. - `true` - only the payment in installments will be shown to a customer - `false` - only the standard installment plan will be shown to a customer - `undefined` | `null` - both methods will be shown to a customer. - `onClose` — function The method, called by the SDK, if a customer closes the modal. - `onRequest` — function The method, called by the SDK, upon selecting the conditions by a customer. At this time the installment plan order should be [requested](https://api.bog.ge/docs/en/docs/en/payments/standard-process/create-order). The `config.loan` parameter should be set. The following arguments will be transmitted to the method: - `selected` - the object, into which there will be transmitted the data selected by a customer. - `amount` - the amount to be paid on monthly basis - `month` - number of the loan months - `discount_code` - the discount code - `successCb` - the method to be called, if you wish the SDK to continue the installment plan process. - `closeCb` - the method to be called, if you wish to close the modal. - `onComplete` — function The method being called by the SDK upon completion of the online installment plan process. At this time a customer is automatically re-directed to the Merchant’s success link. If you do not want the re-direction, return the `false` meaning (`return false`:) in the method. The method will be given the object as an argument with the following parameters: - `redirectUrl` - the link, where a customer is to be redirected to. ### There are two methods of process continuation: 1. If you want the SDK to continue the online installment plan process, upon generation of orderId in the `onRequest` method, call `successCb` and transmit the [generated](https://api.bog.ge/docs/en/docs/en/payments/standard-process/create-order) `orderld` parameter to it. Upon completion of the process, the `onComplete` method will be called. 2. If the SDK is needed only for a calculator and want a customer to continue the process after selection of the desirable condition, return the `false` meaning (`return false:`) into the `onRequest` method and the SDK will not continue the process. At this time the modal remains open. If you wish to close the modal, use the `closeCb` or `Bog.Calculator.close()` method. ```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; } }) ``` --- The SDK also gives you the opportunity to add the BoG button to your site. Transmit the DOM element to the method, where you wish to insert the button. ```html
``` --- # Google Pay™ on Business' Webpage Source: https://api.bog.ge/docs/en/sandbox/payments/external-orders/external-googlepay # Google Pay™ on Business' Webpage To add Google Pay™ button on your webpage, following steps are required. First your webpage should be compliant with Google's requirements. Since Google Pay button is added to your own webpage, instead of Bank of Georgia's, you need to configure the environment independently. For more information visit [Google's configuration page](https://support.google.com/pay/business/answer/7684271?hl=en). :::note During configuration, use the following parameters: ```json { "type": "PAYMENT_GATEWAY", "parameters": { "gateway": "georgiancard", "gatewayMerchantId": "BCR2DN4TXKPITITV", } } ``` ::: After these steps you can make Bank payments through Google Pay button on your page. For creating order see [Standard Process - Order Request](https://api.bog.ge/docs/en/payments/standard-process/create-order) Order Request [`Body`](https://api.bog.ge/docs/en/payments/standard-process/create-order#body-parameters) should contain following parameters: ```json "payment_method": ["google_pay"], "config": { "google_pay": { "external": true, "google_pay_token": "{token}" } } ``` - `config.google_pay.external` — boolean Pass the value true when initiating the operation using the Google Pay button on the Business Web Page. - `config.google_pay.token` — string Full string representing the encrypted Google Pay payment details. It must include all nested fields as received from the Google Pay SDK without modification or truncation. {{ "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 Order identifier. - `status` — string Order status. - `order_details` — object Order details. Contains same data as [payment details](https://api.bog.ge/docs/en/payments/standard-process/get-payment-details#response). The object is returned if payment process is completed without 3DS authentication. - `_links` — object The web resource addresses are used in the further stages of the payment process. At the moment following resources are returned: - `_links.details.href` — string The address of the payment details can be used to obtain information on the online payment. - `_links.redirect.href` — string The web page address to which a customer should be redirected for 3DS authentication. The parameter is returned if the client has 3DS authentication turned on. **RESPONSE** ```json { "id": "{order_id}", "status": "completed", "order_details": {...}, "_links": { "details": { "href": "https://api-sandbox.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™ on Business' Webpage Source: https://api.bog.ge/docs/en/sandbox/payments/external-orders/external-applepay # Apple Pay™ on Business' Webpage To add Apple Pay™ button on your webpage, following steps are required. First your webpage should be compliant with [Apple's requirements](https://developer.apple.com/apple-pay/acceptable-use-guidelines-for-websites/). Since Apple Pay button is added to your own webpage, instead of Bank of Georgia's, you need to configure the environment independently. For more information visit [Apple's configuration page](https://developer.apple.com/documentation/apple_pay_on_the_web/configuring_your_environment). Add the Apple Pay certificate on your website. Download certificate [here](https://webstatic.bog.ge/apple-developer-merchantid-domain-association). See the detailed instruction [here](https://developer.apple.com/documentation/applepaywebmerchantregistrationapi/preparing_merchant_domains_for_verification). After adding the certificate, please, write to this email address [ecommercemerchants@bog.ge](mailto:ecommercemerchants@bog.ge) and provide your domain and your API Public Key. After these steps you can make Bank payments through Apple Pay button on your page. For creating order see [Standard Process - Order Request](https://api.bog.ge/docs/en/payments/standard-process/create-order) :::note [`Body`](https://api.bog.ge/docs/en/payments/standard-process/create-order#body-parameters) should contain following parameters: ```json "payment_method": ["apple_pay"], "config": { "apple_pay": { "external": true } } ``` ::: ### Response - `id` — string Order identifier. - `result` — json The result returned by Apple when initiating payment. - `_links` — object The web resource addresses are used in the further stages of the payment process. At the moment following resource is returned: - `_links.accept.href` — string The address for accepting payment. It is necessary to call this service for completing Apple Pay payment. **RESPONSE** ```json { "id": "{order_id}", "result": {...}, "_links": { "accept": { "href": "https://api-sandbox.bog.ge/payments/v1/ecommerce/orders/{order_id}/payment" } } } ``` --- # Apple Pay™ Accept Payment Source: https://api.bog.ge/docs/en/sandbox/payments/external-orders/complete-external-applepay # Apple Pay™ Accept Payment Calling this service is required to complete Apple Pay™ payment initiated on business' webpage. ### Header parameters - `Content-Type` — application/json, required - `Authorization` — Basic , required `Bearer `, where `jwt_token` is the token returned in the `access_token` parameter of the authentication method response. - `Idempotency-Key` — UUID v4 The Idempotency-Key parameter should be unique for each new API request. Subsequent requests to the same API endpoint with the same Idempotency-Key header will result in the server returning the same status code and response body as the initial request. This functionality is particularly useful to ensure consistent outcome in scenarios where network issues or retries may lead to duplicate requests. ### Path parameters - `order_id` — string, required The order identifier returned in response to the order request. ### Body parameters - `apple_pay_token` — string, required Full string representing the encrypted Apple Pay payment details. It must include all nested fields as received from the Apple Pay SDK without modification or truncation. **CURL** ```bash curl -X POST 'https://api-sandbox.bog.ge/payments/v1/ecommerce/orders/{order_id}/payment' \ -H 'Authorization: Bearer ' \ -H 'Content-Type: application/json' \ --data-raw '{ "apple_pay_token": "{\"token\":{\"paymentData\":{\"data\":\"..."}" }' ``` ### Response - `id` — string Order identifier. - `status` — string Order status. - `order_details` — object Order details. Contains same data as [payment details](https://api.bog.ge/docs/en/payments/standard-process/get-payment-details#response). - `_links` — object The web resource addresses are used in the further stages of the payment process. At the moment following resources are returned: - `_links.details.href` — string The address of the payment details can be used to obtain information on the online payment. **RESPONSE** ```json { "id": "{order_id}", "status": "completed", "order_details": {...}, "_links": { "details": { "href": "https://api-sandbox.bog.ge/payments/v1/receipt/{order_id}" } } } ``` --- # Refund Source: https://api.bog.ge/docs/en/sandbox/payments/refund This method allows merchants to refund the order amount either fully or partially. Full and partial refunds are supported for payments made via card, Apple Pay, Google Pay, BOG authorization, and loyalty points. The partial refund method can be initiated repeatedly until the total paid amount is fully refunded. ### Header parameters - `Content-Type` — application/json, required - `Authorization` — Basic , required `Bearer `, where `jwt_token` is the token returned in the `access_token` parameter of the authentication method response. - `Idempotency-Key` — UUID v4 The Idempotency-Key parameter should be unique for each new API request. Subsequent requests to the same API endpoint with the same Idempotency-Key header will result in the server returning the same status code and response body as the initial request. This functionality is particularly useful to ensure consistent outcome in scenarios where network issues or retries may lead to duplicate requests. ### Path parameters - `order_id` — string, required The order identifier is returned in response to the order request. ### Body parameters - `amount` — number The amount to be refunded. This parameter is necessary if a partial refund is being made. If the parameter is not included, the entire amount will be refunded. The value of this parameter cannot exceed the processed amount (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 The key or identifier for the status of the API request. - `message` — string The human-readable message associated with the API request. - `action_id` — string The unique identifier for the action associated with the API request. **RESPONSE** ```json { "key": "request_received", "message": "Refund request received", "action_id": "5b666901-eb05-4f83-abeb-8311e175f337" } ``` --- # Response Codes Source: https://api.bog.ge/docs/en/sandbox/payments/response-codes ## Payment Response Codes | Code | Description (EN) | Description (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 | წარმატებული პრეავტორიზაცია | ## Action Response Codes | Code | Description (EN) | Description (GE) | |------|----------------------------------------------------------------------------------|----------------------------------------------------------------| | 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/en/sandbox/payments/googlepay # Google Pay ™ Google Pay™ is the fast, simple way that allows you to make card payments without entering card details for each payment. The card data is safely stored by Google. This payment method is available for all devices (mobile phones and computers), regardless of the operating system and web browser. To enable Google Pay™, simply go to the [Business Manager](https://businessmanager.bog.ge/en/) and walk through onboarding process. Note that when you use Google Pay™ you must adhere to Google's [Terms of Service](https://payments.developers.google.com/terms/sellertos). Once you have enabled it, we will automatically show the Google Pay™ button in your payment window for applicable payments. Bank of Georgia supports both "PAN only" and "Cryptogram 3DS" methods of authorization. If 3D-secure is needed for the transaction, Bank of Georgia will automatically take care of that. Since some 3D-secure authentications require the billing address of the customer, we recommend that you supply it to Bank of Georgia when you create the payment. Bank of Georgia supports VISA, MasterCard and American Express transactions from Google Pay™. Google Pay™ is free to use and we recommend enabling it to increase your conversion rate. --- # Test Cards Source: https://api.bog.ge/docs/en/sandbox/payments/test-cards :::caution note The test cards listed here are valid only in the Sandbox environment. They allow you to simulate successful and declined payment scenarios. These card values do not work in Live environment and represent simulated behavior only. ::: :::info Use any number for the card's expiration date and CVV code. ::: ### VISA Cards | Card Number | Standard Order & Payment | Refund | Preauthorization (Complete) | Automatic Payment (Subscription) | Recurring Payment | Description | |---|---|---|---|---|---|---| | | Successful payment | Successful refund | Preauthorization approved | Successful payment | Successful payment | VISA test card for fully successful operations | | | Payment declined (insufficient funds) | – | – | – | – | VISA test card for declined payments due to insufficient funds | | | Successful payment | Refund rejected | Preauthorization rejected | Payment rejected (authentication declined) | Payment rejected (authentication declined) | VISA test card for successful payment and card save, followed by rejected operations | ### Mastercard Cards | Card Number | Standard Order & Payment | Refund | Preauthorization (Complete) | Automatic Payment (Subscription) | Recurring Payment | Description | |---|---|---|---|---|---|---| | | Successful payment | Successful refund | Preauthorization approved | Successful payment | Successful payment | Mastercard test card for fully successful operations | | | Payment declined (insufficient funds) | – | – | – | – | Mastercard test card for declined payments due to insufficient funds | | | Successful payment | Refund rejected | Preauthorization rejected | Payment rejected (authentication declined) | Payment rejected (authentication declined) | Mastercard test card for successful payment and card save, followed by rejected operations | ### American Express (AMEX) Cards | Card Number | Standard Order & Payment | Refund | Preauthorization (Complete) | Automatic Payment (Subscription) | Recurring Payment | Description | |---|---|---|---|---|---|---| | | Successful payment | Successful refund | Preauthorization approved | Successful payment | Successful payment | AMEX test card for fully successful operations | | | Payment declined (insufficient funds) | – | – | – | – | AMEX test card for declined payments due to insufficient funds | | | Successful payment | Refund rejected | Preauthorization rejected | Payment rejected (authentication declined) | Payment rejected (authentication declined) | AMEX test card for successful payment and card save, followed by rejected operations | --- # Terms Used Source: https://api.bog.ge/docs/en/sandbox/payments/terms-used 1. Business - a retailer or service company, having an online/electronic system. 2. Online Payments Page - an online payments system, that allows you to easily build a payments' module into any type of business. 3. Callback - calling of the service chosen by the business from the banking system to provide updated information on the payment. 4. System Entering Credentials - a client’s identifier in the banking system (`client_id`) and a secret key (`secret_key`), given by the bank to the client upon its successful registration. 5. Card Number (PAN) - 16 digits given on the front side of the bank card. --- # HTTP Basic Source: https://api.bog.ge/docs/en/sandbox/paymentgateway/auth-methods/basic If the service-provider chooses to use the [HTTP Basic Auth](https://datatracker.ietf.org/doc/html/rfc7235) authentication method, then the former must accept the Authorization header whose value follows the Basic authentication format. More specifically, the header value will be of the form: `Authorization: Basic ` where credentials is the Base64 encoding of username and password joined by a single colon “:” (e.g. user:pass). ### Header Parameters - `Authorization` — Basic , required Pass in „Basic „ + „:“ value encoded in Base64 format. (e.g.: `Basic ODI4Mjo3Njk3MDY0OTlmMDcwOWUyMzQ4NDU4NjNmOThiMjMxNA==`), where & are the credentials that the service-provider hands to BOG. --- # OAuth 2.0 - Client Credentials Source: https://api.bog.ge/docs/en/sandbox/paymentgateway/auth-methods/oauth2 The service-provider may create an authorization web-service, which supports the OAuth 2.0 ([D. Hardt, Ed., 2012](https://datatracker.ietf.org/doc/html/rfc6749)) Client Credentials grant type. BOG will use an HTTP POST request method for communication with the authorization endpoint. ### Header Parameters - `Content-Type` — application/x-www-form-urlencoded, required ### Body Parameters - `grant_type` — client_credentials, required The value is a static text: `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 The service-provider must return the following JSON response: - `access_token` — string The Token received from the authorization server. - `created_at` — string UNIX timestamp – the amount of milliseconds that have passed since January 1st, 1970 at UTC . - `expires_in` — number The number of seconds while the token stays active. - `token_type` — number Token type (A static value - `Bearer`). **RESPONSE** ```json { "access_token": "xx82194x21412xxx219124x678x888x2xxx1900xx", "created_at": 1693236686855, "expires_in": 300, "token_type": "Bearer" } ``` For any subsequent calls to the API, when the token is valid, BOG will use the HTTP header of the form: - `Authorization` — Bearer , required „Bearer „ + „<token>“ (e.g.: „Bearer xx82194x21412xxx219124x678x888x2xxx1900xx“), where `token` is the value returned from the service-provider's authorization endpoint. --- # API Key Source: https://api.bog.ge/docs/en/sandbox/paymentgateway/auth-methods/apikey The service-provider may provide BOG with an API Key that will be used within each operation. If the key is given, then each operation will contain a header with the format: - `Auth-Key` — , required `API_KEY` is the key given by the service-provider. --- # HMAC-SHA256 Source: https://api.bog.ge/docs/en/sandbox/paymentgateway/auth-methods/hmac-sha256 The service-provider can additionally provide BOG with a secret key for hashing, which will be used for hashing the request body for HTTP POST & PATCH requests, or in the case of HTTP GET, PUT & DELETE requests – for hashing the query. If the aforementioned parameter is provided, the service provider must accept the Hash header and verify it. The HMAC-SHA256 algorithm will be used for hashing, where HMAC-SHA256 refers to the Hash-based Message Authentication Code ([Krawczyk, Bellare, Canetti, 1997](https://www.ietf.org/rfc/rfc2104.txt)) encryption method in conjunction with a secret key and a cryptographic function – SHA256 ([Eastlake, E. Huawei, Hansen, 2011](https://datatracker.ietf.org/doc/html/rfc6234)). Additionally, the hash code will only contain capital letters and digits, in hexadecimal format. - `Hash` — , required `HASH` is the HTTP Request Body or the Query passed through the hashing algorithm. E.g. if given the secret key: `8bbe50a7d61af79211148c09e40e1bffaefdf319dce665bc5a31b55ec28a508b` And if the HTTP GET request is of the form: `http://serviceprovider:8088/api/mock/get-categories?personalNumber=01234567890&birthDate=11.01.2002` Then the value to hash (i.e. the query, since it’s a GET request) will be: `personalNumber=01234567890&birthDate=11.01.2002` Which will result in the following hash code: `841A782048F51A798331E4A534A240911D541B869CB0E2CF1BB58F086873C079` --- # Introduction Source: https://api.bog.ge/docs/en/sandbox/paymentgateway/introduction :::caution NOTICE The document is intended for service-providers. ::: ## What is Payment Gateway? Payment Gateway is an online service that allows businesses and individuals to accept payments from customers through their websites or mobile applications. ## Purpose The following document contains information about communication methods, available operations, exchange formats, authentication, pre-defined parameters & status codes, etc. ## Protocol Description The document describes a system, in which a user will interact with a service-provider via an interface. More specifically, the user may issue a web request to the service-provider through the BOG server, to which the service-provider will be obliged to respond. The received response will be processed by BOG and be displayed to the user. The user may execute an arbitrary amount of operations. Additionally, some payment channels will restrict this number to two operations (information about debt and/or payment), although this can be bypassed at the expense of the time it takes to integrate the service. The protocol will work in conjunction with a web-app, which will give service-providers the ability to define multiple operations per a single payment flow via an interface. All service providers will have the ability to customize both the number and the characteristics of each operation based on their service. ## Requirements for the Service-Provider The service-provider is required to set up a web-server, which can either be publicly accessible or only available through a VPN channel. In case the web-server is publicly accessible, it is required that it supports HTTPS. The service-provider is allowed to use any API endpoint of their choice. E.g. http://serviceprovider:8088/api/mock The following HTTP methods can be defined on custom operations: GET, POST, PUT, PATCH & DELETE; although BOG will not use the HTTP request body to transfer any information for custom operations, regardless of the HTTP method chosen by the service-provider. --- # Authentication Source: https://api.bog.ge/docs/en/sandbox/paymentgateway/authentication ## About This section defines different types of authentication methods supported by the BOG protocol. It is mandatory that a service-provider uses one of the authentication methods listed here. Moreover, it is recommended to use multiple authentication methods at once to increase security. ## Risks This document does not aim at assessing risks imposed on the participants of the payment system in relation to electronic payments and respective responsibilities. The document describes the security regimes applicable to protect the payment system. ## Supported Methods - [HTTP Basic](https://api.bog.ge/docs/en/paymentgateway/auth-methods/basic) - [OAuth 2.0 - Client Credentials](https://api.bog.ge/docs/en/paymentgateway/auth-methods/oauth2) - [API Key](https://api.bog.ge/docs/en/paymentgateway/auth-methods/apikey) - [HMAC-SHA256](https://api.bog.ge/docs/en/paymentgateway/auth-methods/hmac-sha256) --- # Payment Source: https://api.bog.ge/docs/en/sandbox/paymentgateway/pre-defined-ops/payment Any number of operations can be defined by the service provider, howbeit, the payment operation with the key payment will always be executed at the end of the operation chain if the user decides to go through with the payment. Therefore, the service provider is obliged to provide an implementation for the payment operation. Additionally, the Georgian Tetri is assumed to be the default currency. ### Body Parameters - `transactionId` — string, required An unique transaction identifier, created by BOG. - `amount` — number, required Amount in minor units (e.g. Georgian Tetri, American Cent, etc.). - `currency` — string, required Currency ([ISO 4217 currency code](https://www.iban.com/currency-codes)), E.g. `GEL`. - `parameters` — object, required An object, that contains `key` & `value` pairs, where `key` is the name of the parameter, and `value` - the value of the parameter. **REQUEST BODY** ```json { "transactionId": "00000000", "amount": 500000, "currency": "GEL", "parameters": { "personalNumber": "01234567890", "birthDate": "11.01.2002" } } ``` ### Response The service-provider must respond with the following JSON format: - `status.code` — number Refers to the pre-defined [status codes](https://api.bog.ge/docs/en/paymentgateway/error-codes). - `status.value` — string Status value (optional) - `timestamp` — number UNIX timestamp – the amount of milliseconds that have passed since January 1st, 1970 at UTC. - `receiptId` — string receiptId is a unique identifier of the payment, returned from the service-provider after a successful payment operation (optional). **RESPONSE** ```json { "status":{ "code":0, "value":"OK" }, "timestamp":1693236686855, "receiptId":"1234" } ``` --- # Payment Status Source: https://api.bog.ge/docs/en/sandbox/paymentgateway/pre-defined-ops/payment-status When the payment-status operation is invoked by BOG, the service-provider is expected to respond with one of the following status codes: [12, 13, 14](https://api.bog.ge/docs/en/paymentgateway/error-codes). ### Body Parameters - `transactionId` — string, required An unique transaction identifier, created by BOG. **CURL** ```bash curl --location --request GET 'http://serviceprovider:8088/api/mock/payment-status?transactionId=00000000' ``` ### Response The service-provider must answer in the following JSON format: - `status.code` — number Refers to the pre-defined [status codes](https://api.bog.ge/docs/en/paymentgateway/error-codes). - `status.value` — string Status value (optional) - `timestamp` — number UNIX timestamp – the amount of milliseconds that have passed since January 1st, 1970 at UTC. **RESPONSE** ```json { "status":{ "code":12, "value":"Transaction was successful" }, "timestamp":1693236686855 } ``` --- # Cancel Payment Source: https://api.bog.ge/docs/en/sandbox/paymentgateway/pre-defined-ops/cancel-payment When invoking the cancel-payment operation, the service-provider is expected to cancel the payment with the given transaction identifier from BOG. ### Body Parameters - `transactionId` — string, required An unique transaction identifier, created by BOG. **CURL** ```bash curl --location --request GET 'http://serviceprovider:8088/api/mock/cancel-status?transactionId=00000000' ``` ### Response The service-provider must answer in the following JSON format: - `status.code` — number Refers to the pre-defined [status codes](https://api.bog.ge/docs/en/paymentgateway/error-codes). - `status.value` — string Status value (optional) - `timestamp` — number UNIX timestamp – the amount of milliseconds that have passed since January 1st, 1970 at UTC. **RESPONSE** ```json { "status":{ "code":0, "value":"OK" }, "timestamp":1693236686855 } ``` --- # Send Payment Info Source: https://api.bog.ge/docs/en/sandbox/paymentgateway/pre-defined-ops/send-payment-info The send-payment-info operation will be executed once at the end of the day and will send information about successful payments that took place the day before the request (span of 24 hours), according to the UTC+4h (Tbilisi) time zone. Since the request body contains both the summary & individual information about payments, there is a risk that the request body might reach a size limit. Because of this, the send-payment-info operation will be executed in batches, where the timespan of nth batch starts at Tn (inclusive), and the timespan of n-1th batch ends at Tn (inclusive), where Tn-1 < Tn. I.e. batches will be sent subsequently based on subsets of a 24 hour timespan. Moreover, in case of failure to send the data per batch, a retry will be attempted once. ### Body Parameters - `timezoneId` — string, required [Time Zone Identifier.](https://docs.oracle.com/middleware/1221/wcs/tag-ref/MISC/TimeZones.html) - `timespan.from` — number, required (Inclusive) UNIX timestamp – the amount of milliseconds that have passed since January 1st, 1970 at UTC. - `timespan.to` — number, required (Exclusive) UNIX timestamp – the amount of milliseconds that have passed since January 1st, 1970 at UTC. - `summary[?].totalAmount` — string, required Amount in minor units (e.g. Georgian Tetri, American Cent, etc.). - `summary[?].currencyCode` — string, required [Currency](https://www.iban.com/currency-codes) - `summary[?].count` — string, required ტრანზაქციების რაოდენობა. - `paymentList[?].transactionId` — string, required An unique transaction identifier, created by BOG. - `paymentList[?].currencyCode` — string, required [Currency](https://www.iban.com/currency-codes) - `paymentList[?].amount` — string, required Amount in minor units (e.g. Georgian Tetri, American Cent, etc.). **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 The service-provider must answer in the following JSON format: - `status.code` — number Refers to the pre-defined [status codes](https://api.bog.ge/docs/en/paymentgateway/error-codes). - `status.value` — string Status value (optional) - `timestamp` — number UNIX timestamp – the amount of milliseconds that have passed since January 1st, 1970 at UTC. **RESPONSE** ```json { "status":{ "code":0, "value":"OK" }, "timestamp":1693236686855 } ``` --- # Custom Operations Source: https://api.bog.ge/docs/en/sandbox/paymentgateway/operations :::caution NOTICE Custom operations are optional. I.e. the service-provider may not define any custom operations at all. ::: ## Mandatory Standards for Variables In order to maintain company-wide standards, BOG requires that service-providers use specific variable names that correspond with their respective meaning. E.g. if a customer uses their personal number to receive some information (e.g. debt) from the service-provider, then the latter must use personalNumber as the name of the variable required by the API. View the full list of mandatory variable standards below: - **personalNumber** – used as a personal number identifier. - **customerId** – used as a customer identifier. - **debt** – the amount owed by the customer to the service-provider in minor units. - **debtList** – A list of data models that contain the amounts (and possibly other fields) owed by the customer to the service-provider in minor units. - **amount** – the amount that the customer is willing to pay in minor units. ## Data Exchange Format All custom operations that communicate with the service provider’s API will send all request parameters as query parameters,along with the header values used for authentication. The service provider must respond with a pre-defined format for each operation: - `status.code` — number Refers to the pre-defined [status codes](https://api.bog.ge/docs/en/paymentgateway/error-codes). - `status.value` — string Status value (optional) - `timestamp` — number UNIX timestamp – the amount of milliseconds that have passed since January 1st, 1970 at UTC . - `receiptId` — string receiptId is a unique identifier of the payment, returned from the service-provider after a successful payment operation (optional). - `response` — object The JSON data returned from some arbitrary operation. It is required for every custom operation. **RESPONSE** ```json { "status":{ "code":0, "value":"OK" }, "timestamp":1693236686855, "receiptId":"", "response":{"wrapper":{"categoryCodes":["A1","B"]}} } ``` :::note Along with the custom operations created by the service-provider, there also exist pre-defined operations by BOG, from which only the [Payment](https://api.bog.ge/docs/en/paymentgateway/pre-defined-ops/payment) operation is required, all others are optional. ::: --- # Expected Response Times Source: https://api.bog.ge/docs/en/sandbox/paymentgateway/expected-response-times The expected response times, or the response time limits for each operation, are defined below. - **OAuth Client Credentials** – 15 seconds. - **Custom Operations** – 10 seconds. - **Payment** – 30 seconds. - **Payment Status** – 15 seconds. - **Cancel Payment** – 15 seconds. - **Send Payment Info** – 60 seconds. If the service-provider does not return an answer within the given time frame per operation, it is assumed that the request has failed. --- # Definitions, Acronyms & Abbreviations Source: https://api.bog.ge/docs/en/sandbox/paymentgateway/terms-used - **BOG** - Bank Of Georgia - **Service-Provider** - A company providing a service for certain payment and willing to be paid through the BOG payment system. - **Customer** - A person using the BOG user interface to connect to the service provider, receive information about debt, make payments, etc. --- # Exception Cases Source: https://api.bog.ge/docs/en/sandbox/paymentgateway/error-flow This section contains information regarding the different routes the BOG payment system could take depending on the given circumstances within the payment operation. Keep in mind, how BOG handles the “TRANSACTION IN PROGRESS” status ([code 14](https://api.bog.ge/docs/en/paymentgateway/error-codes)) is subject to change. ![Exception Cases Routes](./media/protocol-error-flow.png) --- # Error Codes Source: https://api.bog.ge/docs/en/sandbox/paymentgateway/error-codes |Code | Description | |-----|--------------------------------| |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| A Service-provider may also introduce other error codes not listed in this table. Such codes must not be within 0-99 range. It is noteworthy that the BOG payment system does not guarantee to a service-provider that the text relevant for the code sent by the latter (except for the values set forth by this document) shall be seen by all users. Therefore, returning service-provider-generated codes is only recommended in exceptional cases.