/Create E-Commerce payment

/Create E-Commerce payment



Request Endpoint

https://api.tbcbank.ge/v1/tpay/payments

Authorization

Authorization TypeDescription
Bearer Tokenaccess-token should be added to Authorization header

Request Parameters

Header

ParameterTypeDescription
apikeystringdeveloper app API key

Body Parameters

ParameterTypeDescription
amount { } (required)objectTransaction amount
returnurl (required)stringUrl to redirect user after finishing payment
extrastringAdditional parameter for merchant specific info (optional). only non-unicode (ANSI) symbols allowed. max length 25. This parameter will appear in the account statement
extra2stringAdditional parameter for merchant specific info (optional). only non-unicode (ANSI) symbols allowed. max length 52.
userIpAddressstringUser IP address
expirationMinutesnumberPayment initiation expiration time in minutes. Recommended value is max 12 minutes.

If the value is not specified in the request, 12 minutes will be assigned by default.
methodsarrayThere are several payment methods available to be passed when initiating TBC E-Commerce payment.
Detailed list and description of available methods is described in the Classifications chapter/ Payment Methods

If no method is passed, all methods available for a given merchant will be displayed by default
installmentProducts [ ]arraylist 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.
callbackUrlstringWhen 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"}

In case of successful receipt of the request, the merchant must return the status code 200 and check the payment status through Get Payment endpoint.

CallbackUrl must be added on the merchant dashboard at ecom.tbcpayments.ge.
If callbackUrl parameter is not provided, system automatically takes the basic callbackUrl value from the merchant dashboard.

Please, verify that POST request is allowed at your callbackUrl from the following IP addresses:
193.104.20.44
193.104.20.45
185.52.80.44
185.52.80.45

See how to add callback url on the merchant datshboard
preAuthbooleanSpecify 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).

The following values are allowed:
true, false
languagestringLanguage for payment page.

The following values are allowed: KA, EN

If the language value is not specified in the request, Georgian page will be loaded by default.
merchantPaymentIdstringMerchant-side payment identifier
skipInfoMessagebooleanIf 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.
saveCardbooleanSpecify 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
saveCardToDatestringThe 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}
descriptionstringPayment short description for clients, max length 30. This parameter will appear on the checkout page.

Complex Types Description

amount

ParameterTypeDescription
currency (required)stringtransaction currency (3 digit ISO code).
The following values are allowed:
GEL, USD, EUR

Note
● payments in given currency should be enabled for the merchant by bank.
● only "GEL" is available for payment methods:
▹ 8 - Installment
totalnumbertotal amount of payment
format: 0.00
subtotalnumberamount of purchase
format: 0.00
taxnumberamount of tax
format: 0.00
shippingnumberamount of shipping price
format: 0.00

installmentProducts

ParameterTypeDescription
namestringProduct description
price (required)number (decimal)Product price in Lari 0.00
quantity (required)integer (int32)Number of purchased units.

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"
}
{
    "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

ParameterTypeDescription
payIdstringPayment id
statusstringPayment status

The following values are allowed:
Created
currencystringTransaction currency (3 digit ISO code)
amountnumberTransaction amount
Format: 0.00
linksobjectLinks
- uristringUrl
- methodstringMethod to use on URL
- relstringAction to use on URL
transactionIdstringTransaction_id from UFC
recIdstringIn case of recurring payment registration, recId of saved card. recId should be used for executing recurring payment.
preAuthstringPreauthorization status for given payment (true, false)
httpStatusCodenumberHTTP status code
developerMessagestringDeveloper message for logging in local system
userMessagestringError message for user
expirationMinutesnumberPayment initiation expiration time in minutes.

Response Sample

"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 Error Code Description.

Recipe