Привязать карту (форма 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",
"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",
"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",
"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",
"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",
"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",
"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
/
v1
/
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",
"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",
"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",
"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",
"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",
"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",
"allowed_methods": [
"email_otp"
],
"role": "<string>",
"permissions": [
"<string>"
],
"fields": [
{
"path": "bin",
"code": "invalid_format",
"message": "БИН/ИИН — 12 цифр"
}
]
},
"request_id": "req_4f9c2a7e1b3d4c5a8e6f7a9b0c1d2e3f"
}Авторизации
Сессия кабинета: cookie ставит вход через /v1/auth/* (Better Auth), браузер шлёт её сам — фронтенду кабинета ничего добавлять не нужно (fetch с credentials: 'include'). За HTTPS имя cookie — __Secure-tungo.session_token. Сессия кончилась — 401 authentication_error: отправить на вход.
Параметры пути
id организации (workspace), ws_… — из GET /v1/workspaces
Тело
application/json
Куда вернуть клиента после формы ePay (только адреса нашего фронтенда).
Страница кабинета, куда ePay вернёт клиента после успеха. Только адрес нашего фронтенда, иначе 400
Пример:
"https://app.example.kz/settings/billing?card=ok"
Страница кабинета, куда вернуть после отказа или отмены. Только адрес нашего фронтенда
Пример:
"https://app.example.kz/settings/billing?card=failed"
Ответ
Сессия проверки карты: подключить script_url и открыть форму с payment_object
Сессия привязки карты: открыть форму ePay; после неё клиент вернётся на back_link или failure_back_link, карта появится в списке.
Служебный платёж проверки карты на 0 USD (в список платежей не попадает) (pay_…)
Пример:
"pay_01jz8x3m4n5p6q7r8s9t0v1w2x"
Адрес скрипта платёжной формы ePay: подключить его на странице (тег script) перед открытием формы
true — тестовый терминал ePay: настоящие деньги не списываются, платят тестовыми картами. Показать на форме пометку «тестовая оплата»
Готовый объект для формы ePay: передать без изменений в halyk.pay(payment_object). Поля — формата ePay (camelCase), содержимое не разбирать. Внутри — одноразовый токен только на этот заказ
Show child attributes
Show child attributes