Оплатить на форме ePay (с 3-D Secure)
curl --request POST \
--url https://api.tungo.kz/v1/workspaces/{ws}/billing/payments/{id}/pay-form \
--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/payments/{id}/pay-form"
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/payments/{id}/pay-form', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"payment_id": "pay_01jz8x3m4n5p6q7r8s9t0v1w2x",
"amount_tiyn": 123,
"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"
}{
"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 (с 3-D Secure)
Только владелец или админ организации (остальным — 403). Не настроены ключи ePay на сервере — 500 api_error. Для платежа, который ждёт подтверждения (requires_action), не прошёл (failed) или отменён (cancelled): новый платёж на ту же сумму по тому же счёту; клиент подтверждает его на форме ePay (номер карты к нам не приходит). Подключить script_url и открыть форму с payment_object. Счёт уже оплачен или по нему уже идёт списание — 409. Счёт Lago оплачен вне Tungo (перевод) или аннулирован — тоже 409: оплачивать его не нужно. Пополнение баланса (доп. использование, платформа): после него уже прошло или идёт другое пополнение, а у автопополнения ещё и баланс уже не ниже порога — 409 (пополнить второй раз нельзя по старой форме; нужно — новое пополнение).
Только по сессии кабинета, не по ключу API.
POST
/
v1
/
workspaces
/
{ws}
/
billing
/
payments
/
{id}
/
pay-form
Оплатить на форме ePay (с 3-D Secure)
curl --request POST \
--url https://api.tungo.kz/v1/workspaces/{ws}/billing/payments/{id}/pay-form \
--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/payments/{id}/pay-form"
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/payments/{id}/pay-form', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"payment_id": "pay_01jz8x3m4n5p6q7r8s9t0v1w2x",
"amount_tiyn": 123,
"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"
}{
"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
id платежа, pay_…
Тело
application/json
Куда вернуть клиента после формы ePay (только адреса нашего фронтенда).
Страница кабинета, куда ePay вернёт клиента после успеха. Только адрес нашего фронтенда, иначе 400
Пример:
"https://app.example.kz/settings/billing?card=ok"
Страница кабинета, куда вернуть после отказа или отмены. Только адрес нашего фронтенда
Пример:
"https://app.example.kz/settings/billing?card=failed"
Ответ
Платёж для формы
Оплата счёта на форме ePay с подтверждением 3-D Secure.
Новый платёж на ту же сумму — его статус смотреть в списке платежей (pay_…)
Пример:
"pay_01jz8x3m4n5p6q7r8s9t0v1w2x"
Сумма к оплате на форме. Целое число тиынов: 1 ₸ = 100 тиын. Показывать как тиыны / 100 со знаком ₸ (520000 → «5 200 ₸»; дробь — только если не 0)
Адрес скрипта платёжной формы ePay: подключить его на странице (тег script) перед открытием формы
true — тестовый терминал ePay: настоящие деньги не списываются, платят тестовыми картами. Показать на форме пометку «тестовая оплата»
Готовый объект для формы ePay: передать без изменений в halyk.pay(payment_object). Поля — формата ePay (camelCase), содержимое не разбирать. Внутри — одноразовый токен только на этот заказ
Show child attributes
Show child attributes