Skip to Content
Разовые платежиОплата с телефона (DCB)

Оплата с мобильного телефона (DCB)

Сценарий Direct Carrier Billing состоит из трёх шагов:

  1. Создание контракта (POST .../contracts) — привязка номера телефона.
  2. Авторизация контракта (POST .../contracts/{id}/authorize) — подтверждение PIN-кодом.
  3. Создание счёта (POST .../invoices) — списание средств в рамках активного контракта.

Контракт привязывает реквизиты, но не ведёт график списаний. Каждое списание инициирует мерчант отдельным CreateInvoice — тогда, когда нужно ему. Если график должна вести платформа, это другой продукт: Подписки.

Отсюда две границы контракта. Метода, возвращающего его статус, в протоколе нет — об истечении или закрытии партнёр узнаёт из уведомления contract.closed (Вебхуки), а закрыть контракт сам может отменой (§4.4). Возврат делается тоже не по контракту, а по конкретному счёту — Возврат средств.

4.1 Создание контракта

Инициирует привязку мобильного номера клиента для последующих платежей.

POST /api/v3/projects/{projectId}/contracts

Тело запроса
{
  "client_ip": "10.20.30.40",
  "customer": {
    "type": "mobile_phone",
    "msisdn": "79600000000"
  },
  "merchant_contract_id": "1234567890"
}
ПолеТипОбязательноеОписание
client_ipstring (ip)УсловноIP-адрес клиента. По умолчанию обязателен (настраивается в проекте)
customer.typestringДаТип клиента: "mobile_phone"
customer.msisdnstring (E.164)ДаНомер телефона клиента
merchant_contract_idstring (max 64)ДаID контракта в системе мерчанта. Контракт создаётся по ключу MSISDN + merchant_contract_id
Ответ — 201 Created
{
  "success": true,
  "data": {
    "contract_id": "16449203-0000-009b-a125-351b7bfbd207",
    "authorization_type": "SMS_PIN",
    "expires_at": "2025-03-29T20:00:08Z",
    "merchant_contract_id": "1234567890",
    "customer": {
      "type": "mobile_phone",
      "msisdn": "79600000000",
      "country": "RU",
      "network": { "id": 3, "name": "Beeline" },
      "operator": { "id": 42, "name": "Beeline" }
    }
  }
}
ПолеТипОписание
contract_iduuidУникальный ID контракта в системе платформы
authorization_typeenumТип авторизации: SMS_PIN, EXTERNAL, SKIP
expires_atdatetimeСрок действия контракта
customer.networkobjectСеть клиента (id, name)
customer.operatorobjectОператор клиента (id, name)

POST /contracts

curl -X POST "$BASE/api/v3/projects/$PROJECT_ID/contracts" \
  -H "Content-Type: application/json" \
  -H "X-Login: $LOGIN" \
  -H "X-Timestamp: $TS" \
  -H "X-Signature-Version: 3" \
  -H "X-Signature: $SIG" \
  -d '{
        "client_ip": "10.20.30.40",
        "customer": { "type": "mobile_phone", "msisdn": "79600000000" },
        "merchant_contract_id": "1234567890"
      }'

4.2 Авторизация контракта

Подтверждение контракта PIN-кодом, полученным клиентом по SMS.

POST /api/v3/projects/{projectId}/contracts/{contractId}/authorize

Тело запроса
{
  "client_ip": "10.20.30.40",
  "pin_code": "987656"
}
ПолеТипОбязательноеОписание
client_ipstringУсловноIP-адрес клиента
pin_codestring (max 16)ДаPIN-код из SMS
Ответ — 200 OK
{
  "success": true,
  "data": {
    "contract_id": "16449203-0000-009b-a125-351b7bfbd207",
    "status": "active"
  }
}

После успешной авторизации контракт становится активным. Все платежи в рамках срока действия контракта проходят без повторной авторизации.

4.3 Создание счёта (DCB)

Инициирует списание средств с мобильного счёта клиента.

POST /api/v3/projects/{projectId}/invoices

Тело запроса
{
  "client_ip": "10.20.30.40",
  "customer": {
    "type": "mobile_phone",
    "msisdn": "79600000000",
    "email": "test@test.com"
  },
  "order": {
    "merchant_order_id": "order_123",
    "price": {
      "amount": "25.00",
      "currency": "RUB",
      "vat_included": true
    },
    "description": "Premium subscription"
  },
  "contract": {
    "create_if_not_exists": false,
    "merchant_contract_id": "1234567890"
  },
  "application": { "name": "Game of Sultans" },
  "product":     { "name": "New Pack_1" }
}
ПолеТипОбязательноеОписание
client_ipstringУсловноIP-адрес клиента
customer.typestringДа"mobile_phone"
customer.msisdnstringДаНомер телефона клиента
customer.emailstringНетEmail клиента
order.merchant_order_idstring (max 38)ДаID заказа в системе мерчанта
order.pricemoneyНетЦена для клиента. Если не указана — берётся из настроек проекта
order.descriptionstringНетОписание заказа
contract.create_if_not_existsbooleanНетСоздать контракт автоматически, если его нет (по умолчанию false)
contract.merchant_contract_idstring (max 64)НетID контракта мерчанта
application.namestring (max 256)НетНазвание приложения
product.namestring (max 256)НетНазвание товара / услуги
Ответ — 201 Created
{
  "success": true,
  "data": {
    "invoice_id": "1624505c-0031-00cf-7d54-4cf1ce08cb30",
    "status": "Created",
    "payment_status": "NOT_PAID",
    "authorization": {
      "type": "BY_CONTRACT",
      "is_authorized": true
    },
    "price": {
      "amount": "25.00",
      "currency": "RUB",
      "vat_included": true
    },
    "merchant_order_id": "order_123",
    "created_at": "2025-03-29T20:00:10Z",
    "expires_at": "2025-03-29T22:00:10Z",
    "billing_channel": "CPA",
    "customer": {
      "type": "mobile_phone",
      "msisdn": "79600000000",
      "country": "RU",
      "network":  { "id": 3,  "name": "Beeline" },
      "operator": { "id": 42, "name": "Beeline" }
    },
    "contract": {
      "contract_id": "16449203-0000-009b-a125-351b7bfbd207",
      "authorization_type": "SMS_PIN",
      "expires_at": "2025-03-29T20:00:08Z",
      "merchant_contract_id": "1234567890"
    }
  }
}

Допускается только один активный счёт на одного клиента в рамках проекта. При попытке создать второй счёт API вернёт 409 Conflict с кодом INVOICE_ALREADY_EXISTS и details.invoice_id существующего счёта.

POST /invoices — DCB

curl -X POST "$BASE/api/v3/projects/$PROJECT_ID/invoices" \
  -H "Content-Type: application/json" \
  -H "X-Login: $LOGIN" \
  -H "X-Timestamp: $TS" \
  -H "X-Signature-Version: 3" \
  -H "X-Signature: $SIG" \
  -d '{
        "client_ip": "10.20.30.40",
        "customer": { "type": "mobile_phone", "msisdn": "79600000000" },
        "order": {
          "merchant_order_id": "order_123",
          "price": { "amount": "25.00", "currency": "RUB", "vat_included": true },
          "description": "Premium subscription"
        },
        "contract": { "merchant_contract_id": "1234567890" }
      }'

4.4 Отмена контракта

POST /api/v3/projects/{projectId}/contracts/{contractId}/cancel

Тело запроса
{
  "client_ip": "10.20.30.40"
}
Ответ — 200 OK
{
  "success": true,
  "data": {
    "contract_id": "16449203-0000-009b-a125-351b7bfbd207",
    "status": "cancelled"
  }
}

4.5 Проверка поддержки биллинга

Проверяет возможность активации и тарификации для конкретного MSISDN.

POST /api/v3/projects/{projectId}/billing/check

Тело запроса
{
  "msisdn": "79600000000"
}
Ответ — 200 OK
{
  "success": true,
  "data": {
    "supported": true,
    "customer": {
      "type": "mobile_phone",
      "msisdn": "79600000000",
      "country": "RU",
      "network":  { "id": 3,  "name": "Beeline" },
      "operator": { "id": 42, "name": "Beeline" }
    }
  }
}
Общие соглашенияКарты, СБП, SberPay