Before you start

Before you proceed with getting a list of supported banks, make sure that you have completed the following steps:

• Creating a Service account
• Issuing a JWT token
• Managing JWT tokens

Payment process

Our service provides the ability to integrate payment by QR codes in various countries. This can be useful for expanding customer service and generating revenue through additional services.

This payment method is only possible using the h2h scheme, where all interaction with the customer takes place on the merchant's side.

To ensure the most transparent user experience, qr code working flow consists of two stages:

Stage one: QR code recognition and calculation of the final cost for the customer in their local currency.

Stage two: Payment finalization.

The full payment flow is shown in the diagram below:

Basic example

Stage one: API reference /FX/TLV

Example request:

curl --request POST \
  --url 'https://{base_url}/fx/tlv' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --data '{
    "data": "60110820GGLU955BDESTOPFHH8P70910TVMU000…"
  }'

Example repsonse:

{
 "id": "68fd5cb1-a99b-49c0-813f-5b5df0c7e32b",
 "currencyCode": "TRY",
 "amount": 839,
 "amountCrypto": 24.242185,
 "feeInCrypto": 2.203835,
 "feePercent": 10,
 "qrVersion": 3,
 "transactionCreatedAt": "2025-05-13T18:57:27.489Z",
 "transactionExpiredAt": "2025-05-08T18:08:27.000Z",
 "rate": 34.6091,
 "tlv": {
     "merchant": "BEYAZIT HALK ECZANESİ",
     "logo": "https://dkto9gpxgolik.cloudfront.net/icons/poscategory/eczane.png",
     "city": "İSTANBUL",
     "merchantId": "23151238",
     "zip": "34130",
     "qrRefId": "0010",
     "invoiceId": "T4LLDPYUE0BVHML9O8J6"
 }
}

Stage two: API reference DEALS/TLV

Example request:

curl --request POST \
  --url 'https://{base_url}/deals/tlv' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --data '{
    "quoteId": "68fd5cb1-a99b-49c0-813f-5b5df0c7e32b",
    "invoiceId": "000000232323",
    "clientId": "1103000330303012"
  }'

Example repsonse:

{
 "id": "00fd5cb1-a99b-49c0-813f-5b5df0c7e32b",
 "status": "paid",
}

❗️

Important

The request is synchronous. You will receive the payment status immediately in response.
You can receive only two statuses in response:

paid: means that the terminal has accepted the payment and the funds can be deducted from the customer.

canceled: means that the payment has not been processed

SDK Example:

import os
import sys
import uuid
from paymentsgate.types import (TokenResponse)
from paymentsgate.models import (Credentials)
from paymentsgate.client import ApiClient

config = Credentials(
  account_id = "ab586003-1ee5-4630-b2e1-3e6db7f05ea5",
  private_key = "xV0VGazV5VVh0QzZKTjg5TEJoRXFKCkhNNmZY",
  public_key = "0rZ245bElSczVieHZSem82ZndUWmp1RHE3",
)

cli = ApiClient(config, baseUrl='https://BASE_URL');

# step 1
res = cli.QuoteQr(
  {
    "data": '990067510620329982DAEAF541A08D1AEFD59CB0AB32313D602CF5', #success
  }
)

# ......
# show offer to client
# ......

#step 2

deal = cli.PayOutTlv({
  "quoteId": res.id,
  "invoiceId": str(uuid.uuid4()),
  "clientId": str(uuid.uuid4())
});

Static QR codes for test: