Привязать карту (форма ePay)

curl --request POST \
  --url https://api.tungo.kz/v1/workspaces/{ws}/billing/card-sessions \
  --header 'Content-Type: application/json' \
  --cookie tungo.session_token= \
  --data '
{
  "back_link": "https://app.example.kz/settings/billing?card=ok",
  "failure_back_link": "https://app.example.kz/settings/billing?card=failed"
}
'

import requests

url = "https://api.tungo.kz/v1/workspaces/{ws}/billing/card-sessions"

payload = {
    "back_link": "https://app.example.kz/settings/billing?card=ok",
    "failure_back_link": "https://app.example.kz/settings/billing?card=failed"
}
headers = {
    "cookie": "tungo.session_token=",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {cookie: 'tungo.session_token=', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    back_link: 'https://app.example.kz/settings/billing?card=ok',
    failure_back_link: 'https://app.example.kz/settings/billing?card=failed'
  })
};

fetch('https://api.tungo.kz/v1/workspaces/{ws}/billing/card-sessions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "payment_id": "pay_01jz8x3m4n5p6q7r8s9t0v1w2x",
  "script_url": "<string>",
  "test_mode": true,
  "payment_object": {}
}

{
  "type": "error",
  "error": {
    "type": "payment_required_error",
    "message": "Баланс доп. использования закончился — пополнить его или включить автопополнение могут владелец и админ workspace.",
    "code": "balance_exhausted",
    "permission": "proposals.approve",
    "resets_at": "2026-11-01T19:00:00.000Z",
    "retry_after_seconds": 42,
    "next_request_at": "2026-11-12T09:30:42.000Z",
    "allowed_methods": [
      "email_otp"
    ],
    "role": "<string>",
    "permissions": [
      "<string>"
    ],
    "fields": [
      {
        "path": "bin",
        "code": "invalid_format",
        "message": "БИН/ИИН — 12 цифр"
      }
    ]
  },
  "request_id": "req_4f9c2a7e1b3d4c5a8e6f7a9b0c1d2e3f"
}

{
  "type": "error",
  "error": {
    "type": "payment_required_error",
    "message": "Баланс доп. использования закончился — пополнить его или включить автопополнение могут владелец и админ workspace.",
    "code": "balance_exhausted",
    "permission": "proposals.approve",
    "resets_at": "2026-11-01T19:00:00.000Z",
    "retry_after_seconds": 42,
    "next_request_at": "2026-11-12T09:30:42.000Z",
    "allowed_methods": [
      "email_otp"
    ],
    "role": "<string>",
    "permissions": [
      "<string>"
    ],
    "fields": [
      {
        "path": "bin",
        "code": "invalid_format",
        "message": "БИН/ИИН — 12 цифр"
      }
    ]
  },
  "request_id": "req_4f9c2a7e1b3d4c5a8e6f7a9b0c1d2e3f"
}

{
  "type": "error",
  "error": {
    "type": "payment_required_error",
    "message": "Баланс доп. использования закончился — пополнить его или включить автопополнение могут владелец и админ workspace.",
    "code": "balance_exhausted",
    "permission": "proposals.approve",
    "resets_at": "2026-11-01T19:00:00.000Z",
    "retry_after_seconds": 42,
    "next_request_at": "2026-11-12T09:30:42.000Z",
    "allowed_methods": [
      "email_otp"
    ],
    "role": "<string>",
    "permissions": [
      "<string>"
    ],
    "fields": [
      {
        "path": "bin",
        "code": "invalid_format",
        "message": "БИН/ИИН — 12 цифр"
      }
    ]
  },
  "request_id": "req_4f9c2a7e1b3d4c5a8e6f7a9b0c1d2e3f"
}

{
  "type": "error",
  "error": {
    "type": "payment_required_error",
    "message": "Баланс доп. использования закончился — пополнить его или включить автопополнение могут владелец и админ workspace.",
    "code": "balance_exhausted",
    "permission": "proposals.approve",
    "resets_at": "2026-11-01T19:00:00.000Z",
    "retry_after_seconds": 42,
    "next_request_at": "2026-11-12T09:30:42.000Z",
    "allowed_methods": [
      "email_otp"
    ],
    "role": "<string>",
    "permissions": [
      "<string>"
    ],
    "fields": [
      {
        "path": "bin",
        "code": "invalid_format",
        "message": "БИН/ИИН — 12 цифр"
      }
    ]
  },
  "request_id": "req_4f9c2a7e1b3d4c5a8e6f7a9b0c1d2e3f"
}

{
  "type": "error",
  "error": {
    "type": "payment_required_error",
    "message": "Баланс доп. использования закончился — пополнить его или включить автопополнение могут владелец и админ workspace.",
    "code": "balance_exhausted",
    "permission": "proposals.approve",
    "resets_at": "2026-11-01T19:00:00.000Z",
    "retry_after_seconds": 42,
    "next_request_at": "2026-11-12T09:30:42.000Z",
    "allowed_methods": [
      "email_otp"
    ],
    "role": "<string>",
    "permissions": [
      "<string>"
    ],
    "fields": [
      {
        "path": "bin",
        "code": "invalid_format",
        "message": "БИН/ИИН — 12 цифр"
      }
    ]
  },
  "request_id": "req_4f9c2a7e1b3d4c5a8e6f7a9b0c1d2e3f"
}

{
  "type": "error",
  "error": {
    "type": "payment_required_error",
    "message": "Баланс доп. использования закончился — пополнить его или включить автопополнение могут владелец и админ workspace.",
    "code": "balance_exhausted",
    "permission": "proposals.approve",
    "resets_at": "2026-11-01T19:00:00.000Z",
    "retry_after_seconds": 42,
    "next_request_at": "2026-11-12T09:30:42.000Z",
    "allowed_methods": [
      "email_otp"
    ],
    "role": "<string>",
    "permissions": [
      "<string>"
    ],
    "fields": [
      {
        "path": "bin",
        "code": "invalid_format",
        "message": "БИН/ИИН — 12 цифр"
      }
    ]
  },
  "request_id": "req_4f9c2a7e1b3d4c5a8e6f7a9b0c1d2e3f"
}

Биллинг

Привязать карту (форма ePay)

Только владелец или админ организации (остальным — 403). Не настроены ключи ePay на сервере — 500 api_error. Номер карты к нам не приходит: клиент вводит его на форме ePay (проверка на 0 USD). Ссылки возврата — только на адреса фронтенда.

Только по сессии кабинета, не по ключу API.

POST

workspaces

{ws}

billing

card-sessions

Привязать карту (форма ePay)

curl --request POST \
  --url https://api.tungo.kz/v1/workspaces/{ws}/billing/card-sessions \
  --header 'Content-Type: application/json' \
  --cookie tungo.session_token= \
  --data '
{
  "back_link": "https://app.example.kz/settings/billing?card=ok",
  "failure_back_link": "https://app.example.kz/settings/billing?card=failed"
}
'

import requests

url = "https://api.tungo.kz/v1/workspaces/{ws}/billing/card-sessions"

payload = {
    "back_link": "https://app.example.kz/settings/billing?card=ok",
    "failure_back_link": "https://app.example.kz/settings/billing?card=failed"
}
headers = {
    "cookie": "tungo.session_token=",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {cookie: 'tungo.session_token=', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    back_link: 'https://app.example.kz/settings/billing?card=ok',
    failure_back_link: 'https://app.example.kz/settings/billing?card=failed'
  })
};

fetch('https://api.tungo.kz/v1/workspaces/{ws}/billing/card-sessions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "payment_id": "pay_01jz8x3m4n5p6q7r8s9t0v1w2x",
  "script_url": "<string>",
  "test_mode": true,
  "payment_object": {}
}

{
  "type": "error",
  "error": {
    "type": "payment_required_error",
    "message": "Баланс доп. использования закончился — пополнить его или включить автопополнение могут владелец и админ workspace.",
    "code": "balance_exhausted",
    "permission": "proposals.approve",
    "resets_at": "2026-11-01T19:00:00.000Z",
    "retry_after_seconds": 42,
    "next_request_at": "2026-11-12T09:30:42.000Z",
    "allowed_methods": [
      "email_otp"
    ],
    "role": "<string>",
    "permissions": [
      "<string>"
    ],
    "fields": [
      {
        "path": "bin",
        "code": "invalid_format",
        "message": "БИН/ИИН — 12 цифр"
      }
    ]
  },
  "request_id": "req_4f9c2a7e1b3d4c5a8e6f7a9b0c1d2e3f"
}

{
  "type": "error",
  "error": {
    "type": "payment_required_error",
    "message": "Баланс доп. использования закончился — пополнить его или включить автопополнение могут владелец и админ workspace.",
    "code": "balance_exhausted",
    "permission": "proposals.approve",
    "resets_at": "2026-11-01T19:00:00.000Z",
    "retry_after_seconds": 42,
    "next_request_at": "2026-11-12T09:30:42.000Z",
    "allowed_methods": [
      "email_otp"
    ],
    "role": "<string>",
    "permissions": [
      "<string>"
    ],
    "fields": [
      {
        "path": "bin",
        "code": "invalid_format",
        "message": "БИН/ИИН — 12 цифр"
      }
    ]
  },
  "request_id": "req_4f9c2a7e1b3d4c5a8e6f7a9b0c1d2e3f"
}

{
  "type": "error",
  "error": {
    "type": "payment_required_error",
    "message": "Баланс доп. использования закончился — пополнить его или включить автопополнение могут владелец и админ workspace.",
    "code": "balance_exhausted",
    "permission": "proposals.approve",
    "resets_at": "2026-11-01T19:00:00.000Z",
    "retry_after_seconds": 42,
    "next_request_at": "2026-11-12T09:30:42.000Z",
    "allowed_methods": [
      "email_otp"
    ],
    "role": "<string>",
    "permissions": [
      "<string>"
    ],
    "fields": [
      {
        "path": "bin",
        "code": "invalid_format",
        "message": "БИН/ИИН — 12 цифр"
      }
    ]
  },
  "request_id": "req_4f9c2a7e1b3d4c5a8e6f7a9b0c1d2e3f"
}

{
  "type": "error",
  "error": {
    "type": "payment_required_error",
    "message": "Баланс доп. использования закончился — пополнить его или включить автопополнение могут владелец и админ workspace.",
    "code": "balance_exhausted",
    "permission": "proposals.approve",
    "resets_at": "2026-11-01T19:00:00.000Z",
    "retry_after_seconds": 42,
    "next_request_at": "2026-11-12T09:30:42.000Z",
    "allowed_methods": [
      "email_otp"
    ],
    "role": "<string>",
    "permissions": [
      "<string>"
    ],
    "fields": [
      {
        "path": "bin",
        "code": "invalid_format",
        "message": "БИН/ИИН — 12 цифр"
      }
    ]
  },
  "request_id": "req_4f9c2a7e1b3d4c5a8e6f7a9b0c1d2e3f"
}

{
  "type": "error",
  "error": {
    "type": "payment_required_error",
    "message": "Баланс доп. использования закончился — пополнить его или включить автопополнение могут владелец и админ workspace.",
    "code": "balance_exhausted",
    "permission": "proposals.approve",
    "resets_at": "2026-11-01T19:00:00.000Z",
    "retry_after_seconds": 42,
    "next_request_at": "2026-11-12T09:30:42.000Z",
    "allowed_methods": [
      "email_otp"
    ],
    "role": "<string>",
    "permissions": [
      "<string>"
    ],
    "fields": [
      {
        "path": "bin",
        "code": "invalid_format",
        "message": "БИН/ИИН — 12 цифр"
      }
    ]
  },
  "request_id": "req_4f9c2a7e1b3d4c5a8e6f7a9b0c1d2e3f"
}

{
  "type": "error",
  "error": {
    "type": "payment_required_error",
    "message": "Баланс доп. использования закончился — пополнить его или включить автопополнение могут владелец и админ workspace.",
    "code": "balance_exhausted",
    "permission": "proposals.approve",
    "resets_at": "2026-11-01T19:00:00.000Z",
    "retry_after_seconds": 42,
    "next_request_at": "2026-11-12T09:30:42.000Z",
    "allowed_methods": [
      "email_otp"
    ],
    "role": "<string>",
    "permissions": [
      "<string>"
    ],
    "fields": [
      {
        "path": "bin",
        "code": "invalid_format",
        "message": "БИН/ИИН — 12 цифр"
      }
    ]
  },
  "request_id": "req_4f9c2a7e1b3d4c5a8e6f7a9b0c1d2e3f"
}

Авторизации

tungo.session_token

string

обязательно

Сессия кабинета: cookie ставит вход через /v1/auth/* (Better Auth), браузер шлёт её сам — фронтенду кабинета ничего добавлять не нужно (fetch с credentials: 'include'). За HTTPS имя cookie — __Secure-tungo.session_token. Сессия кончилась — 401 authentication_error: отправить на вход.

Параметры пути

string

обязательно

id организации (workspace), ws_… — из GET /v1/workspaces

Тело

application/json

Куда вернуть клиента после формы ePay (только адреса нашего фронтенда).

back_link

string<uri>

обязательно

Страница кабинета, куда ePay вернёт клиента после успеха. Только адрес нашего фронтенда, иначе 400

Пример:

"https://app.example.kz/settings/billing?card=ok"

failure_back_link

string<uri>

обязательно

Страница кабинета, куда вернуть после отказа или отмены. Только адрес нашего фронтенда

Пример:

"https://app.example.kz/settings/billing?card=failed"

Ответ

Сессия проверки карты: подключить script_url и открыть форму с payment_object

Сессия привязки карты: открыть форму ePay; после неё клиент вернётся на back_link или failure_back_link, карта появится в списке.

payment_id

string

обязательно

Служебный платёж проверки карты на 0 USD (в список платежей не попадает) (pay_…)

Пример:

"pay_01jz8x3m4n5p6q7r8s9t0v1w2x"

script_url

string

обязательно

Адрес скрипта платёжной формы ePay: подключить его на странице (тег script) перед открытием формы

test_mode

boolean

обязательно

true — тестовый терминал ePay: настоящие деньги не списываются, платят тестовыми картами. Показать на форме пометку «тестовая оплата»

payment_object

object

обязательно

Готовый объект для формы ePay: передать без изменений в halyk.pay(payment_object). Поля — формата ePay (camelCase), содержимое не разбирать. Внутри — одноразовый токен только на этот заказ

Show child attributes