APW Wallet API

Partner API, version 1: registration, login, password reset, profile, limits and notifications, utility and other service payments, wallet-to-wallet transfers, currency exchange, ATM cash withdrawal, verification and operation history.

Overview

Base URL:

https://wallet.apw.ge/api/v1

Every request is a POST with a JSON body (Content-Type: application/json), including requests with an empty body.

Authentication happens at two levels:

1. Partner: your server signs every request with an HMAC signature. This is how we know the request comes from you.
2. Wallet customer: after login you send the received access_token in the Authorization: Bearer … header. This works exactly as in the APW Wallet app.

Partner authentication (HMAC)

You will receive two values from us: a Partner ID (e.g. pk_…) and a secret.

The secret is handed over only once. If it is lost or leaked, contact us and we will issue a new one. The old one stops working at the same moment.

Headers

String to sign

Six lines joined with \n (LF). No trailing newline is added at the end.

POST
/api/v1/auth/login-check
1761140000
3f1c9a0e-5b7d-4e2a-9c61-0d8e2b7f4a10
203.0.113.7
e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

1. The HTTP method in uppercase: POST.
2. The URL path, without the domain and query string. For example /api/v1/auth/login-check.
3. The value of X-Timestamp.
4. The value of X-Nonce.
5. The value of X-Client-Ip.
6. The SHA-256 hash of the request body, in lowercase hex. The body must be exactly the bytes you send. The hash of an empty body is e3b0c442…b855.

X-Signature = hex( HMAC-SHA256( key = secret, message = string to sign ) )

function apwRequest(string $path, array $data, string $clientIp, ?string $customerToken = null): array
{
    $partnerId = getenv('APW_PARTNER_ID');
    $secret    = getenv('APW_SECRET');

    $body      = json_encode($data ?: new stdClass(), JSON_UNESCAPED_UNICODE);
    $timestamp = (string) time();
    $nonce     = bin2hex(random_bytes(16));

    $stringToSign = implode("\n", [
        'POST', $path, $timestamp, $nonce, $clientIp, hash('sha256', $body),
    ]);

    $headers = [
        'Content-Type: application/json',
        'X-Partner-Id: ' . $partnerId,
        'X-Timestamp: ' . $timestamp,
        'X-Nonce: ' . $nonce,
        'X-Client-Ip: ' . $clientIp,
        'X-Signature: ' . hash_hmac('sha256', $stringToSign, $secret),
    ];
    if ($customerToken) {
        $headers[] = 'Authorization: Bearer ' . $customerToken;
    }

    $ch = curl_init('https://wallet.apw.ge' . $path);
    curl_setopt_array($ch, [
        CURLOPT_POST           => true,
        CURLOPT_POSTFIELDS     => $body,
        CURLOPT_HTTPHEADER     => $headers,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT        => 140,
    ]);
    $response = curl_exec($ch);
    $status   = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
    curl_close($ch);

    return ['status' => $status, 'body' => json_decode((string) $response, true)];
}

$result = apwRequest('/api/v1/auth/login-check', [
    'wallet_number' => '12345678901',
    'password'      => 'Secret123',
], $_SERVER['REMOTE_ADDR']);

const crypto = require('crypto');

async function apwRequest(path, data, clientIp, customerToken) {
  const body = JSON.stringify(data ?? {});
  const timestamp = Math.floor(Date.now() / 1000).toString();
  const nonce = crypto.randomUUID();
  const bodyHash = crypto.createHash('sha256').update(body, 'utf8').digest('hex');

  const stringToSign = ['POST', path, timestamp, nonce, clientIp, bodyHash].join('\n');
  const signature = crypto.createHmac('sha256', process.env.APW_SECRET)
    .update(stringToSign, 'utf8').digest('hex');

  const headers = {
    'Content-Type': 'application/json',
    'X-Partner-Id': process.env.APW_PARTNER_ID,
    'X-Timestamp': timestamp,
    'X-Nonce': nonce,
    'X-Client-Ip': clientIp,
    'X-Signature': signature,
  };
  if (customerToken) headers.Authorization = `Bearer ${customerToken}`;

  // body here is the same string that was signed
  const res = await fetch('https://wallet.apw.ge' + path, { method: 'POST', headers, body });
  return { status: res.status, body: await res.json() };
}

import hashlib, hmac, json, os, time, uuid
import requests

def apw_request(path, data, client_ip, customer_token=None):
    body = json.dumps(data or {}, ensure_ascii=False).encode('utf-8')
    timestamp = str(int(time.time()))
    nonce = uuid.uuid4().hex

    string_to_sign = '\n'.join([
        'POST', path, timestamp, nonce, client_ip, hashlib.sha256(body).hexdigest(),
    ])
    signature = hmac.new(os.environ['APW_SECRET'].encode(), string_to_sign.encode(), hashlib.sha256).hexdigest()

    headers = {
        'Content-Type': 'application/json',
        'X-Partner-Id': os.environ['APW_PARTNER_ID'],
        'X-Timestamp': timestamp,
        'X-Nonce': nonce,
        'X-Client-Ip': client_ip,
        'X-Signature': signature,
    }
    if customer_token:
        headers['Authorization'] = 'Bearer ' + customer_token

    # data=body, not json=data, so that exactly the signed bytes are sent
    res = requests.post('https://wallet.apw.ge' + path, data=body, headers=headers, timeout=140)
    return res.status_code, res.json()

PATH_="/api/v1/register/params"
BODY='{}'
TS=$(date +%s)
NONCE=$(openssl rand -hex 16)
CLIENT_IP="203.0.113.7"
BODY_HASH=$(printf '%s' "$BODY" | openssl dgst -sha256 -hex | awk '{print $NF}')
SIG=$(printf 'POST\n%s\n%s\n%s\n%s\n%s' "$PATH_" "$TS" "$NONCE" "$CLIENT_IP" "$BODY_HASH" \
      | openssl dgst -sha256 -hmac "$APW_SECRET" -hex | awk '{print $NF}')

curl -sS "https://wallet.apw.ge$PATH_" \
  -H "Content-Type: application/json" \
  -H "X-Partner-Id: $APW_PARTNER_ID" \
  -H "X-Timestamp: $TS" \
  -H "X-Nonce: $NONCE" \
  -H "X-Client-Ip: $CLIENT_IP" \
  -H "X-Signature: $SIG" \
  --data-binary "$BODY"

Additional protection

• IP allowlist: give us the IP addresses of your server(s), and we will accept requests only from them.
• Nonce: the same X-Nonce is not accepted twice (error 905). This makes replaying an intercepted request impossible. When retrying, always use a new nonce and a new signature.
• Time: keep your server clock synchronized via NTP. With a difference of more than ±300 seconds you will get error 904.

Customer authentication

The access_token comes from three endpoints: auth/login, register/4 (completing registration) and password/reset/change. Send it in the Authorization: Bearer <token> header, together with the partner HMAC headers.

• It is valid for 1 hour. There is no refresh token. After it expires, the customer must log in again.
• An account has one active session. Logging in or resetting the password revokes previous tokens, including those in APW's own app. So a token can be revoked at any time, and you must handle 401 correctly.
• An invalid or expired token gets HTTP 401 with the body {"message":"Unauthenticated."}. Sometimes the body is {"errorCode":401,"errorMessage":"Token expired"}. In both cases, send the customer to the login screen.
• Exception: billing/pay, transfer/pay and exchange/convert return HTTP 401 with the text „ავტორიზაცია მუშავდება“ ("authorization is being processed") or „…ავტორიზაცია დაიბლოკა“ ("…authorization has been blocked"). This is not a token problem: the operation is undergoing an additional check. Show the text to the customer and try again later. A real token problem is always answered with "Unauthenticated." or "errorCode":401.

Responses and errors

Gateway errors (9xx)

The request did not reach the wallet. The format is {"errorCode": 9xx, "errorMessage": "..."}.

Wallet responses

After the signature check, the wallet response is returned unchanged: both the status and the body. The body comes in two formats:

Read the error text in this order: errorMessage, then message. The text (errorMessage / message) is intended to be shown to the customer. It is mostly in Georgian, some of it in English. Build your logic on errorCode and the HTTP status, not on the text.

Limits

• 600 requests per minute per partner (can be raised by agreement). When exceeded: 907 / HTTP 429.
• The wallet's own limits. When these are exceeded: HTTP 429 with the body {"message":"Too Many Attempts."} and a Retry-After header.
• An SMS code can be resent at most once per minute per account.
• verification-defect/2 sends an SMS on every call, so 5 calls per 10 minutes are allowed per customer. When exceeded: HTTP 429, {"message":"Too Many Attempts."}.
• After 10 wrong passwords within 15 minutes, logging in to the account is temporarily blocked.
• After 5 wrong codes for one token, the login process must be started over.
• Request timeout on your side: at least 140 seconds for regular endpoints, and at least 310 seconds for billing/pay, transfer/pay, exchange/convert, qr/verify and verification/2. Before a payment the system performs several external checks, and a connection closed early does not cancel the result.
• Payments (billing) are unavailable every day from 23:30 to 00:10 (Tbilisi time): errorCode 99.

Registration: flow

Registration consists of several steps. Each step uses the token from the previous one (a 64-character string; this is not the access_token).

Two steps take place on the customer's own device and do not go through the API:

• document scan and selfie (Identomat);
• signing the contract via a link received by SMS.

1. register/params: lists for the form (countries, employment, income…).
2. register/1: contact details, address, password, PEP status. Returns a token.
3. register/2: economic profile. Returns an iframe_url.
4. The customer opens the iframe_url on their device (a camera is required) and completes the document scan and selfie.
5. register/3: we check the document, and the customer receives two SMS messages: the contract link and a 6-digit code.
6. The customer signs the contract via the link. The link is valid for 10 minutes.
7. register/check: poll until status: 1 is returned. If the link has expired, use register/contract-sms.
8. register/4: registration is completed with the SMS code. Returns an access_token.

POST/api/v1/register/params

Allowed values for the form fields. The body is empty: {}.

{
  "message": "Success",
  "data": {
    "0": {
      "countrie": [{"ccode": "GE", "country": "Georgia", "code": "995", ...}],
      "sferos": [...],
      "userEmployeeStatus": [...],
      "userExpectedTurnover": [...],
      "userMonthlyIncome": [...],
      "userPurposeRelationship": [...],
      "userSourceOfIncome": [...],
      "currency_id": [{"id": 981, "name": "GEL"}, {"id": 978, "name": "EUR"}, {"id": 840, "name": "USD"}, {"id": 643, "name": "RUB"}]
    },
    "links": {"contract": "https://…pdf", "privacy_policy": "https://…pdf", "limits": "https://…pdf"},
    "pep_status": [...], "pep_family_status": [...],
    "pep_definition": "...", "pep_family_definition": "..."
  }
}

The lists are under data["0"] (the key is the string "0").

POST/api/v1/register/1

// 200
{"token": "Xr9…64 characters", "message": "Success"}
// 402
{"message": "ელ-ფოსტა უკვე გამოყენებულია"}

POST/api/v1/register/2

// 200
{"token": "…", "iframe_url": "https://widget.identomat.com/?session_token=…", "message": "Success"}

Open the iframe_url for the customer: in a WebView with camera permission, or in a browser. When the customer finishes the scan, call register/3.

POST/api/v1/register/3

Field: token.

We check the Identomat result, the validity of the document and the age. On success the customer receives two SMS messages: the contract link and a 6-digit code for register/4. This step takes a few seconds.

// 200
{"token": "…", "mobile": "995******123", "expire": 5, "message": "Success"}
// 402: examples
{"message": "user_checking"}                    // the document is being checked manually, try again later
{"message": "user must be 18 years or older!"}
{"message": "არარეზიდენტების რეგისტრაცია დროებით შეზღუდულია!"}

POST/api/v1/register/check

Field: token. Checks whether the customer has signed the contract. Poll once every few seconds.

// 200: signed
{"status": 1, "message": "ხელმოწერილი"}
// 402: not signed yet. This is a normal state, not an error.
{"status": 0, "message": "ხელმოუწერელი"}

POST/api/v1/register/contract-sms

Field: token. Resends the contract link. Call it only when the previous link has expired, i.e. 10 minutes after it was sent.

// 200
{"token": "…", "mobile": "99*****23", "expire": 5, "message": "Success"}

POST/api/v1/register/4

// 200
{
  "message": "რეგისტრაცია წარმატებით დასრულდა",
  "user": {"id": 1, "verify_id": 1, "iban": "GE…", "wallet_number": "12345678901",
           "first_name": "…", "last_name": "…", "birth_date": "1990-01-01",
           "balance": 0, "balance_usd": 0, "balance_eur": 0, "balance_rub": 0,
           "mobile": "995…", "email": "…"},
  "access_token": "eyJ0eXAiOiJKV1Qi…"
}
// 402
{"message": "ხელშეკრულებაზე დათანხმება აუცილებელია!"}

Login: flow

1. auth/login-check: wallet number and password. The two_factor field in the response tells you which code is required.
2. two_factor: "sms": the customer receives an SMS code. To resend it, use auth/login-sms.
   two_factor: "google": the code is in the customer's Authenticator app. No SMS is sent.
3. auth/login: token and code. Returns an access_token.

Legal entity (type = 2): one natural person can have several companies linked to them. auth/login-check returns a legal_entities list; if it contains more than one entry, you must pass legal_user_id to auth/login. With a single company nothing changes.

POST/api/v1/auth/login-check

// SMS
{"two_factor": "sms", "phone": "995******123", "token": "…", "date": "2026-10-22 12:00:00",
 "expire": 1, "errorCode": 0, "message": "Sms send success"}
// Authenticator
{"two_factor": "google", "token": "…", "date": "…", "expire": 5, "errorCode": 0,
 "message": "Authenticator code required"}

expire is the code's validity period in minutes.

For type = 2, the response additionally contains legal_entities — the list of companies this customer can log in as. This field is absent from the response for a natural-person login.

{"two_factor": "sms", "phone": "995******123", "token": "…", "expire": 1,
 "errorCode": 0, "message": "Sms send success",
 "legal_entities": [
   {"legal_user_id": 12, "wallet_number": "00000000123",
    "name": "შპს ალფა", "identification_number": "400147211"},
   {"legal_user_id": 19, "wallet_number": "00000000456",
    "name": "შპს ბეტა",  "identification_number": "405123456"}
 ]}

The list includes only the companies that can be logged in as at this moment — expired or suspended authority and blocked companies are excluded. name is the company name, identification_number is its identification code; both are meant to be shown to the customer, while legal_user_id is what you pass to auth/login.

POST/api/v1/auth/login-sms

Field: token (from login-check). Resends the SMS code, at most once per minute. The token does not change.

{"phone": "995******123", "token": "…", "date": "…", "expire": 1, "errorCode": 0, "errorMessage": "Sms send success"}

If errorCode: 6 is returned, the customer uses an Authenticator app and no SMS is sent.

POST/api/v1/auth/login

{
  "user": {"id": 1, "verify_id": 1, "iban": "GE…", "wallet_number": "12345678901",
           "first_name": "…", "last_name": "…", "birth_date": "…", "mobile": "…", "email": "…",
           "balance": 10.5, "balance_usd": 0, "balance_eur": 0, "balance_rub": 0,
           "frozen_balance": 0, "frozen_balance_usd": 0, "frozen_balance_eur": 0, "frozen_balance_rub": 0,
           "type": 1, "verification_defect": 0, "requested_document": 0, ...},
  "access_token": "eyJ0eXAiOiJKV1Qi…",
  "errorCode": 0,
  "errorMessage": "success"
}

On code 9 the token remains valid — show the choice and call again with the same token and code. The login does not start over.

// 200 — choose a company
{"errorCode": 9, "errorMessage": "აირჩიეთ იურიდიული პირი",
 "legal_entities": [
   {"legal_user_id": 12, "wallet_number": "00000000123",
    "name": "შპს ალფა", "identification_number": "400147211"},
   {"legal_user_id": 19, "wallet_number": "00000000456",
    "name": "შპს ბეტა",  "identification_number": "405123456"}
 ]}

A successful login revokes all other sessions of this account. For a legal entity this also means that two authorized persons of the same company cannot be logged in at the same time — the second one's login logs out the first.

POST/api/v1/auth/logoutcustomer token

The body is empty. Revokes the customer's tokens.

{"errorCode": 0, "errorMessage": "success"}

Password reset: flow

1. password/reset/check: wallet number. The customer receives an SMS code.
2. password/reset/verify: the code. Returns a new token.
3. password/reset/change: the new password, with the new token, within 10 minutes. The customer is logged in directly.

password/reset/check returns success even for an unknown wallet number. This is intentional, so that the API cannot be used to find out whether a wallet exists. In that case the next step will return a “wrong code” error.

POST/api/v1/password/reset/check

Field: wallet_number (11 digits).

{"phone": "995******123", "token": "…", "date": "…", "expire": 1, "errorCode": 0,
 "errorMessage": "Password reset sms send success"}

Errors: 1 validation · 3 authorization is being checked or is blocked · 4 an SMS was sent just now.

POST/api/v1/password/reset/sms

Field: token. Resends the SMS, at most once per minute. The response format is the same as for reset/check.

POST/api/v1/password/reset/verify

{"token": "…new token…", "date": "…", "errorCode": 0, "errorMessage": "SMS check success"}

Errors: 1 validation · 2 the code is wrong or attempts are exhausted · 3 the code has expired.

POST/api/v1/password/reset/change

The success response is the same as for auth/login: user and access_token. Errors: 1 validation · 2 the token is wrong or already used · 3 the token has expired (10 minutes).

Payments: flow

Paying for services from the customer's wallet: mobile, utilities, internet, etc. The catalog is public (no customer token needed), while paying requires a token.

1. billing/categories → billing/category/{id} → billing/service/{id}: choosing a service. The service contains the field descriptions (params_info, params_pay), the amount limits and the commission.
2. billing/info: checking the subscriber (debt, name…). The sms field in the response tells you whether the payment needs an SMS code.
3. If sms = 1: billing/pay-sms. The code is valid for 2 minutes.
4. billing/pay: the payment. On success you receive an operationId.
5. billing/status/{operationId}: poll until the status becomes 3 (completed) or 4 (cancelled).

The currency is always the lari (GEL). An identical payment (same service, subscriber and amount) is not accepted a second time within 20 seconds.

Catalog

POST/api/v1/billing/categories: array of categories.

[{"id": 32, "image": "https://uploads.allpayway.ge/files/categories/….png", "count": 3,
  "lang": {"ka": "მობილური", "en": "Mobile", "ru": "Мобильная связь"}}, ...]

POST/api/v1/billing/category/{id}: the services of a category.

{"services": [{"id": 19, "name": "Magti", "lang": {...}, "image": "…", "min_amount": "1.00", "max_amount": "400.00", ...}],
 "category": {"lang": {"ka": "…", "en": "…", "ru": "…"}}}

POST/api/v1/billing/services: all services in a single array.

POST/api/v1/billing/service/{id}: full description of a single service.

{
  "errorCode": 1000,
  "service": {
    "id": 19, "name": "Magti", "lang": {"ka": "მაგთი", "en": "Magti", "ru": "Магти"},
    "currency_id": 981, "min_amount": "1.00", "max_amount": "400.00", "category_id": 32,
    "image": "https://uploads.allpayway.ge/files/services/….png",
    "params_info": [
      {"name": "phone_number", "regexp": "/^(\\d{9})$/i", "description": "ტელეფონის ნომერი", "example": "599470076"}
    ],
    "params_pay": [
      {"name": "phone_number", "regexp": "/^(\\d{9})$/i", "description": "ტელეფონის ნომერი", "example": "599470076"}
    ],
    "commission": {
      "client_commission_percent": "4.00", "client_commission_fixed": "0.00",
      "min_client_commission": "0.000000", "max_client_commission": "0.000000",
      "min_amount": "1.000000", "max_amount": "1000.000000", "rate": 1
    }
  }
}

• params_info: the fields for billing/info. params_pay: the fields for billing/pay. Each field's name (name) is the request field name. The value must match regexp. Use description and example in your form.
• commission: the customer commission (percentage, fixed, minimum and maximum). The final commission is returned in the payment response and in the status.

POST/api/v1/billing/param: description of a single field. Body: {"param": "phone_number"}.

POST/api/v1/billing/info

Checking the subscriber. Fields: service_id and every params_info field of the service.

// request
{"service_id": 19, "phone_number": "599470076"}
// 200: the fields depend on the service. "sms" is always present.
{"errorCode": 1000, "errorMessage": "წარმატებული", ..., "sms": 1}
// 402
{"message": "The phone number field is required."}
{"errorCode": 99, "errorMessage": "00:10 საათამდე გადახდას ვერ შეძლებთ"}

POST/api/v1/billing/pay-smscustomer token

The customer receives a 6-digit code to confirm the payment. The code is valid for 2 minutes. The body is empty.

{"message": "Success"}

POST/api/v1/billing/paycustomer token

// request
{"service_id": 19, "phone_number": "599470076", "amount": "10.00", "sms": "123456"}
// 200: payment accepted
{"errorCode": 1000, "errorMessage": "წარმატებული", "operationId": 987654,
 "accoutant": {"genAmount": 10.4, "clientCommission": 0.4}, ...}

Errors (HTTP 402):

POST/api/v1/billing/status/{operationId}customer token

operationId from the billing/pay response. The body is empty. The response is always HTTP 200.

{"errorCode": 0, "errorMessage": "success", "data": {
  "service": {"image": "…", "lang": {"ka": "მაგთი", "en": "Magti", "ru": "Магти"},
              "abonent": "599470076", "amount": "10.00", "gen_amount": "10.40", "client_comision": "0.40"},
  "status": {"status_id": 3, "description": "შესრულებული"}}}

If the payment is not found, service and status are empty arrays ([]).

Poll once every 5–10 seconds.

Transfers: flow

From an APW wallet to an APW wallet, instantly. All endpoints require a customer token.

1. transfer/info: checking the recipient (by wallet number or IBAN) and the commission. Optional.
2. transfer/pay-sms: confirmation code via SMS. Valid for 2 minutes.
3. transfer/pay: the transfer.

POST/api/v1/transfer/infocustomer token

// 200
{"errorCode": 0, "errorMessage": "Success",
 "data": {"reciver": "გ. ბ.", "iban": "GE00DL0000000000000000", "percents": ...}}

reciver: the recipient's initials, so the customer can double-check. percents: the transfer commission.

Errors (402): 1 validation · 2 service restricted · 3 recipient not found · 4 transfer to own wallet · 22 temporary technical issue.

POST/api/v1/transfer/pay-smscustomer token

Same as billing/pay-sms: a 6-digit code valid for 2 minutes, and it is the same shared code (see note). Response: {"message": "Success"}.

POST/api/v1/transfer/paycustomer token

// request
{"type": 1, "wallet_number": "12345678901", "amount": "25.50", "currency_id": 981,
 "destination": "ვალის დაბრუნება", "sms": "123456"}
// 200: transfer completed
{"errorCode": 0, "errorMessage": "Success", "data": {...}}

Errors (HTTP 402, errorCode):

Customer

POST/api/v1/usercustomer token

The customer's current data and balances. The body is empty. The response is an object without a wrapper:

{"id": 1, "iban": "GE…", "wallet_number": "12345678901", "first_name": "…", "last_name": "…",
 "birth_date": "…", "mobile": "…", "email": "…",
 "balance": 10.5, "balance_usd": 0, "balance_eur": 0, "balance_rub": 0,
 "frozen_balance": 0, "frozen_balance_usd": 0, "frozen_balance_eur": 0, "frozen_balance_rub": 0,
 "avatar": null, "verify_id": 1, "type": 1,
 "verification_defect": 0, "requested_document": 0}

POST/api/v1/user/transactionscustomer token

Operation history, newest first. All filters are optional. Do not send a field you are not using at all (an empty string causes a validation error).

[{"id": 1201, "date": "2026-10-22 12:00:05", "description": "Magti: 599470076",
  "amount": 10.4, "type": 0, "balance": 89.6, "currency_id": 981, "currency": "GEL",
  "service_id": 19, "abonent": "599470076", "gen_amount": "10.40", "client_comision": "0.40", "status_id": 3}, ...]

• type: 1 incoming, 0 outgoing.
• Unfinished payments start with „მიმდინარე: …“ ("in progress: …"), cancelled ones with „გაუქმებული ოპერაცია: …“ ("cancelled operation: …"). Their balance is null.
• id comes from different tables and is not unique within the history. Do not use it as an entry key.

POST/api/v1/user/passwordcustomer token

// 200
{"message": "პაროლი წარმატებით შეიცვალა"}
// 402
{"message": "ძველი პაროლი არასწორია!"}

POST/api/v1/user/language/{locale}customer token

locale: ge, en or ru. Stores the customer's preferred language (used on payment pages). The body is empty.

{"message": "success"}

POST/api/v1/user/limitscustomer token

The customer's spending limits in GEL: monthly and daily. The body is empty. The response has no wrapper.

// natural person
{"month": "5000.00", "day": "1500.00"}
// legal entity
{"month": "unlimited", "day": "unlimited"}

Read both fields as strings: they can be a number or "unlimited".

POST/api/v1/user/servicescustomer token

Services payable with the wallet, grouped by category, with amount limits and the customer commission. The body is empty. For a full service description (fields, logo, names in each language) use billing/service/{id}.

{"errorCode": 0, "errorMessage": "success", "data": [
  {"category_id": 32, "services": [
    {"service_id": 19, "name": "Magti", "min_amount": 1.0, "max_amount": 400.0,
     "client_commission_percent": 4.0, "client_commission_fixed": 0.0,
     "min_client_commission": 0.0, "max_client_commission": 0.0}, ...]}, ...]}

If there are no entries: HTTP 402, {"errorCode": 1, "errorMessage": "ჩანაწერები ვერ მოიძებნა"}.

POST/api/v1/user/kyccustomer token

The customer's KYC documents (the questionnaire and its confirmation). The body is empty.

{"errorCode": 0, "errorMessage": "success", "data": [
  {"id": 123, "file": "https://…/files/kyc/…?expires=…&sig=…", "date": "2026-10-22T10:00:00.000000Z"}, ...]}

file is a signed link, valid for 1 hour. Do not store it: call the endpoint again when you need it. These are personal documents; show them to no one but the customer. If there are no documents, data is an empty array.

Notificationscustomer token

APW notifications for the customer. The body is empty for all endpoints. Notification format:

{"id": 5, "user_id": 42, "type_id": 1, "seen": 0, "seen_at": null,
 "title": "…", "text": "…", "created_at": "…", "updated_at": "…"}

{"errorCode": 0, "errorMessage": "success", "data": [ … ]}

seen/{id} always returns {"errorCode": 0, "errorMessage": "success"}, even when the notification does not exist or belongs to another customer (someone else's notification is not changed). next does not mark the notification as read.

Two-factor authentication (Authenticator)customer token

By default the login code is sent via SMS. The customer can link Google Authenticator or another TOTP app.

All endpoints return HTTP 200. On success: {"errorCode": 0, "errorMessage": "success", "data": {...}}.

Current state (data):

{"method": "sms" | "google", "method_id": 1 | 2, "google_enrolled": true,
 "google_confirmed_at": "2026-10-22 12:00:00" | null, "google_setup_pending": false}

Errors: 1 validation · 2 the code is wrong or expired · 3 the app is not linked.

Currency

Exchange rates and currency exchange between wallet balances. All endpoints require a customer token.

POST/api/v1/exchange/currenciescustomer token

The body is empty.

{"errorCode": 0, "errorMessage": "Success", "data": [
  {"id": 981, "title": "GEL"}, {"id": 840, "title": "USD"},
  {"id": 978, "title": "EUR"}, {"id": 643, "title": "RUB"}]}

RUB (643) is in the list, but a rate cannot be obtained for it (errorCode 2).

POST/api/v1/exchange/ratecustomer token

How much the customer would receive when exchanging amount. No money is moved.

// request
{"from": 981, "to": 840, "amount": 100}
// 200
{"errorCode": 0, "errorMessage": "Success",
 "data": {"from": "GEL", "to": "USD", "amount": 100, "rate": 36.42}}

data.rate is the amount to be received in the to currency, not the unit rate.

POST/api/v1/exchange/convertcustomer token

Performs the exchange: the amount is debited from the from balance and credited to the to balance. Fields and the success response are the same as for exchange/rate. data.rate is the amount credited.

// request
{"from": 981, "to": 840, "amount": 100}
// 200: exchange completed
{"errorCode": 0, "errorMessage": "Success",
 "data": {"from": "GEL", "to": "USD", "amount": 100, "rate": 36.42}}

Verification: what to use when

The user response contains three fields that tell you what the customer needs to do:

POST/api/v1/verification/{step}customer token

step: 1 or 2. The process resembles the document step of registration (register/2–3).

1. verification/1: the body is empty. Returns a token and an iframe_url.

   {"token": "…64 characters", "iframe_url": "https://widget.identomat.com/?session_token=…", "message": "Success"}

2. Open the iframe_url for the customer (a camera is required). The widget language is Georgian. If session_token in the URL is empty, the service is temporarily unavailable: try again later.
3. verification/2: field token. Checks the document and saves it. This may take several minutes: set a timeout of at least 310 seconds.

   // 200
   {"message": "Verification completed Success"}
   // 402: examples
   {"message": "user_checking"}            // the document is being checked manually, try again later
   {"message": "არასწორი დოკუმენტი!"}      // the document belongs to another person
   {"message": "SESSION_NOT_FOUND"}        // the token is wrong or the scan was not completed

The personal number on the document must match the customer's personal number.

POST/api/v1/verification-defect/{step}customer token

step: 1, 2 or 3. Use it when user has verification_defect: 1: data is missing from the customer's profile form.

verification-defect/1: the body is empty. Returns which fields need to be filled in.

// needs filling in
{"errorCode": 1, "errorMessage": "შესავსებია გამოტოვებული ველები",
 "data": {"employee_status": …, "real_address": …}}
// nothing is missing
{"errorCode": 0, "errorMessage": "ვერიფიცირებული"}

The keys of data come from this list: employee_status, monthly_income, expected_turnover, address_same, job_title, occupied_position, source_of_income_id, company_name, company_country, real_address, legal_address. Both responses are HTTP 200.

verification-defect/2: send only the fields returned by step 1. The value lists are in register/params.

address_same: 1 if the actual address matches the legal address; 0 if it does not, in which case real_address is required.

// 200: the customer receives an SMS with the profile form link and a 6-digit code
{"token": "…64 characters", "message": "Success"}
// 402
{"message": "…validation text…"}
{"message": "ატვირთული დოკუმენტი არავალიდურია!"}   // complete verification/1–2 first

Every call sends a new SMS and revokes the previous code (see the note on the shared code). Limit: 5 calls per 10 minutes per customer.

verification-defect/3: confirms the filled-in data.

// 200
{"message": "Success"}
// 402
{"message": "sms-ით მიღებული კოდი არასწორია"}

After success, verification_defect in user becomes 0.

POST/api/v1/requested-documentcustomer token

Use it when user has requested_document: 1. APW has requested an image from the customer: which image is written in requested_document_comment.

This is a regular JSON request, not multipart. The signing rule is the same.

{"file": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQ…"}

The response is always HTTP 200. Determine the result from errorCode:

ATM cash withdrawal (QR)

POST/api/v1/qr/verifycustomer token

The customer scans the QR code on the ATM screen and takes cash from the wallet. This endpoint binds the ATM session to the customer's wallet.

// 200
{"errorCode": 0, "errorMessage": "Success"}