---
updatedAt: 2026-03-25T11:16:42.000Z
---

# /Create E-Commerce payment

# /Create E-Commerce payment

***

***

[block:html]
{
  "html": "<html>\n  <head>\n  </head>\n  <body>\n    <!-- Adding link to the button on the onclick event -->\n    <button class=\"Button_ref\" onclick=\"window.location.href = 'https://developers.tbcbank.ge/reference/checkout-create-web-payment-api';\">\n      <> Check API Reference here\n    </button>\n  </body>\n</html>"
}
[/block]

# Request Endpoint

```http production endpoint
https://api.tbcbank.ge/v1/tpay/payments
```

# Authorization

| Authorization Type | Description                                          |
| :----------------- | :--------------------------------------------------- |
| Bearer Token       | access-token should be added to Authorization header |

# Request Parameters

### Header

| Parameter | Type   | Description           |
| :-------- | :----- | :-------------------- |
| apikey    | string | developer app API key |

### Body Parameters

[block:parameters]
{
  "data": {
    "h-0": "Parameter",
    "h-1": "Type",
    "h-2": "Description",
    "0-0": "[amount { } (required)](https://developers.tbcbank.ge/docs/checkout-create-checkout-payment#amount)",
    "0-1": "object",
    "0-2": "Transaction amount",
    "1-0": "returnurl (required)",
    "1-1": "string",
    "1-2": "Url to redirect user after finishing payment",
    "2-0": "extra",
    "2-1": "string",
    "2-2": "Additional parameter for merchant specific info (optional). only non-unicode (ANSI) symbols allowed. max length 25. This parameter will appear in the account statement",
    "3-0": "extra2",
    "3-1": "string",
    "3-2": "Additional parameter for merchant specific info (optional). only non-unicode (ANSI) symbols allowed. max length 52.",
    "4-0": "userIpAddress",
    "4-1": "string",
    "4-2": "User IP address",
    "5-0": "expirationMinutes",
    "5-1": "number",
    "5-2": "Payment initiation expiration time in minutes. **Recommended value is max 12 minutes.**  \n  \nIf the value is not specified in the request, 12 minutes will be assigned by default.",
    "6-0": "methods",
    "6-1": "array",
    "6-2": "There are several payment methods available to be passed when initiating TBC E-Commerce payment.  \nDetailed list and description of available methods is described in the <a href=\"/docs/payment-methods\" target=\"_blank\">Classifications chapter/ Payment Methods</a>  \n  \n_If no method is passed, all methods available for a given merchant will be displayed by default_",
    "7-0": "[installmentProducts \\[ \\]](https://developers.tbcbank.ge/docs/checkout-create-checkout-payment#installmentproducts)",
    "7-1": "array",
    "7-2": "list of installment products. mandatory if installment is selected as payment method. Please note, sum of prices of installment products should be same as total amount.",
    "8-0": "callbackUrl",
    "8-1": "string",
    "8-2": "When the payment status changes to final status, POST request containing PaymentId in the body will be sent to given URL. Request body example {\"PaymentId\":\"6azzo13uw5u2116332\"}  \n  \nIn case of successful receipt of the request, the merchant must return the status code 200 and check the payment status through [Get Payment](/docs/checkout-get-checkout-payment-details)  endpoint.  \n  \nCallbackUrl must be added on the merchant dashboard at [ecom.tbcpayments.ge.](https://ecom.tbcpayments.ge/)  \nIf callbackUrl parameter is not provided, system automatically takes the basic callbackUrl value from the merchant dashboard.  \n  \nPlease, verify that POST request is allowed at your callbackUrl from the following IP addresses:  \n193.104.20.44  \n193.104.20.45  \n185.52.80.44  \n185.52.80.45  \n  \nSee [how to add callback url on the merchant datshboard](/docs/checkout-callback-url)",
    "9-0": "preAuth",
    "9-1": "boolean",
    "9-2": "Specify if preauthorization is needed for the transaction. if \"true\" is passed, amount will be blocked on the card and additional request should be executed by merchant to complete payment. To finalize authorization process, /v1/tpay/payments/:paymentId/completion endpoint should be used. Note, that Completion request can be initiated not later than 30 days from Preauthorization date. By default block is saved for 30 days, although some banks may have a different setting, so this setting depends on the card issuing bank (Isuer Bank).  \n  \nThe following values are allowed:  \ntrue, false",
    "10-0": "language",
    "10-1": "string",
    "10-2": "Language for payment page.  \n  \nThe following values are allowed: **KA, EN**  \n  \nIf the language value is not specified in the request, Georgian page will be loaded by default.",
    "11-0": " merchantPaymentId",
    "11-1": "string",
    "11-2": "Merchant-side payment identifier",
    "12-0": "skipInfoMessage",
    "12-1": "boolean",
    "12-2": "If true is passed, TBC E-Commerce info message will be skipped and customer will be redirected to merchant. If false is passed or this parameter isn’t passed at all,  TBC E-Commerce info message will be shown and customer will be redirected to merchant.",
    "13-0": "saveCard",
    "13-1": "boolean",
    "13-2": "Specify if saving card funcion is needed. This function should be enabled for the merchant by bank. If true is passed, recId parameter should be returned in response, through this parameter merchant can execute payment by saved card - POST /payments/execution. Zero amount is allowed for this function. If card saving funtion is requested with preauthorization parameter=true, saved card execution method will be activated after preauthorization completion. WebQR, ApplePay and installments pay methods are not allowed for saving card request",
    "14-0": "saveCardToDate",
    "14-1": "string",
    "14-2": "The date until the card will be saved can be passed in following format \"MMYY\". If the saveCardToDate is not provided or data provided by the merchant exceeds card expiry , the system will automatically assign the SaveCardToDate value that will be equal to card expiry. The actual card save date must be verified by getting payment status after transaction completed with GET /payments/{payment-id}",
    "15-0": "description",
    "15-1": "string",
    "15-2": "Payment short description for clients, max length 30. This parameter will appear on the checkout page."
  },
  "cols": 3,
  "rows": 16,
  "align": [
    "left",
    "left",
    "left"
  ]
}
[/block]

### Complex Types Description

#### amount

[block:parameters]
{
  "data": {
    "h-0": "Parameter",
    "h-1": "Type",
    "h-2": "Description",
    "0-0": "currency (required)",
    "0-1": "string",
    "0-2": "transaction currency (3 digit ISO code).  \nThe following values are allowed:  \nGEL, USD, EUR  \n  \n**Note**  \n● payments in given currency should be enabled for the merchant by bank.  \n● only \"GEL\" is available for payment methods:  \n▹ 8 - Installment",
    "1-0": "total",
    "1-1": "number",
    "1-2": "total amount of payment  \nformat: 0.00",
    "2-0": "subtotal",
    "2-1": "number",
    "2-2": "amount of purchase  \nformat: 0.00",
    "3-0": "tax",
    "3-1": "number",
    "3-2": "amount of tax  \nformat: 0.00",
    "4-0": "shipping",
    "4-1": "number",
    "4-2": "amount of shipping price  \nformat: 0.00"
  },
  "cols": 3,
  "rows": 5,
  "align": [
    "left",
    "left",
    "left"
  ]
}
[/block]

#### installmentProducts

| Parameter           | Type             | Description                |
| :------------------ | :--------------- | :------------------------- |
| name                | string           | Product description        |
| price (required)    | number (decimal) | Product price in Lari 0.00 |
| quantity (required) | integer (int32)  | Number of purchased units. |

# Request Sample

```json JSON - Minimal Request Sample
{
    "amount": {
        "currency":"GEL",
        "total": 1
    },
    "returnurl":"https://test.ge/ReturnURL",
    "callbackUrl":"https://test.ge/CallbackURL", 
    "preAuth":false,
    "language":"EN",
    "merchantPaymentId": "P123123",
    "description": "free text, which will be visible on payment page"
}
```
```json JSON - Extended Request Sample
{
    "amount": {
        "currency":"GEL",
        "total": 1,
        "subTotal": 0,
        "tax": 0,
        "shipping": 0
    },
    "returnurl":"https://test.ge/ReturnURL",
    "extra":"GE60TB4572261006330008",
    "userIpAddress" : "127.0.0.1",
    "expirationMinutes" : 12,
    "methods" : [5, 7, 8],
    "installmentProducts":
    [
       {"Name":"t1","Price":100,"Quantity":1},
       {"Name":"t1","Price":50,"Quantity":1},
       {"Name":"t1","Price":50,"Quantity":1}
    ],
    "callbackUrl":"https://test.ge/CallbackURL", 
    "preAuth":false,
    "language":"EN",
    "merchantPaymentId": "P123123",
    "saveCard": true,
    "saveCardToDate": "1030",
    "description": "free text, which will be visible on payment page"
}
```

# Response Parameters

[block:parameters]
{
  "data": {
    "h-0": "Parameter",
    "h-1": "Type",
    "h-2": "Description",
    "0-0": "payId",
    "0-1": "string",
    "0-2": "Payment id",
    "1-0": "status",
    "1-1": "string",
    "1-2": "Payment status  \n  \nThe following values are allowed:  \nCreated",
    "2-0": "currency",
    "2-1": "string",
    "2-2": "Transaction currency (3 digit ISO code)",
    "3-0": "amount",
    "3-1": "number",
    "3-2": "Transaction amount  \nFormat: 0.00",
    "4-0": "links",
    "4-1": "object",
    "4-2": "Links",
    "5-0": "\\- uri",
    "5-1": "string",
    "5-2": "Url",
    "6-0": "\\- method",
    "6-1": "string",
    "6-2": "Method to use on URL",
    "7-0": "\\- rel",
    "7-1": "string",
    "7-2": "Action to use on URL",
    "8-0": "transactionId",
    "8-1": "string",
    "8-2": "Transaction_id from UFC",
    "9-0": "recId",
    "9-1": "string",
    "9-2": "In case of recurring payment registration, recId of saved card. recId should be used for executing recurring payment.",
    "10-0": "preAuth",
    "10-1": "string",
    "10-2": "Preauthorization status for given payment (true, false)",
    "11-0": "httpStatusCode",
    "11-1": "number",
    "11-2": "HTTP status code",
    "12-0": "developerMessage",
    "12-1": "string",
    "12-2": "Developer message for logging in local system",
    "13-0": "userMessage",
    "13-1": "string",
    "13-2": "Error message for user",
    "14-0": "expirationMinutes",
    "14-1": "number",
    "14-2": "Payment initiation expiration time in minutes."
  },
  "cols": 3,
  "rows": 15,
  "align": [
    "left",
    "left",
    "left"
  ]
}
[/block]

# Response Sample

```json 200 OK
"payId": "tpay-tbvqma2372015",
  "status": "Created",
  "currency": "GEL",
  "amount": 200,
  "links": [
    {
      "uri": "https://api.tbcbank.ge/v1/tpay/payments/tpay-tbvqma2372015",
      "method": "GET",
      "rel": "self"
    },
    {
      "uri": "https://tpay.tbcbank.ge/checkout/choose-payment-method/tpay-tbvqma2372015",
      "method": "REDIRECT",
      "rel": "approval_url"
    }
  ],
  "transactionId": null,
  "preAuth": false,
  "recId": "8715aBbB4314e7dC4f91482283988365a3c30822",
  "httpStatusCode": 200,
  "developerMessage": null,
  "userMessage": null
}
```

# Error Response

In case of error, standard response in problem json will be returned.

> Details can be found at <a href="/docs/error-code-description" target="_blank">Error Code Description</a>.

# Recipe

[block:tutorial-tile]
{
  "backgroundColor": "#018FF4",
  "emoji": "👉",
  "id": "61bc87a6fb508001a286027f",
  "link": "https://developers.tbcbank.ge/v1.0/recipes/tbc-e-commerce-create-web-payment",
  "slug": "tbc-e-commerce-create-web-payment",
  "title": "TBC E-Commerce Create web payment"
}
[/block]