Skip to Content
One-time paymentsMobile payments (DCB)

Mobile phone payments (DCB)

The Direct Carrier Billing flow consists of three steps:

  1. Create a contract (POST .../contracts) — bind the phone number.
  2. Authorize the contract (POST .../contracts/{id}/authorize) — confirm with a PIN code.
  3. Create an invoice (POST .../invoices) — charge funds under the active contract.

A contract binds the payment details; it does not run a charging schedule. Every charge is initiated by the merchant with its own CreateInvoice, whenever the merchant needs it. If the schedule is to be run by the platform, that is a different product: Subscriptions.

Two boundaries follow from this. The protocol has no method that returns a contract’s status — expiry or closure reaches the partner through the contract.closed notification (Webhooks), and the partner can close a contract itself by cancelling it (§4.4). A refund is likewise made against a specific invoice, not against the contract — Refunds.

4.1 Create contract

Initiates binding of the client’s mobile number for subsequent payments.

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

Request body
{
  "client_ip": "10.20.30.40",
  "customer": {
    "type": "mobile_phone",
    "msisdn": "79600000000"
  },
  "merchant_contract_id": "1234567890"
}
FieldTypeRequiredDescription
client_ipstring (ip)ConditionalClient IP address. Required by default (configurable per project)
customer.typestringYesClient type: "mobile_phone"
customer.msisdnstring (E.164)YesClient phone number
merchant_contract_idstring (max 64)YesContract ID in the merchant system. The contract is keyed by MSISDN + merchant_contract_id
Response — 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" }
    }
  }
}
FieldTypeDescription
contract_iduuidUnique contract ID in the platform
authorization_typeenumAuthorization type: SMS_PIN, EXTERNAL, SKIP
expires_atdatetimeContract expiry
customer.networkobjectClient network (id, name)
customer.operatorobjectClient operator (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 Authorize contract

Confirm the contract with the PIN code the client received via SMS.

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

Request body
{
  "client_ip": "10.20.30.40",
  "pin_code": "987656"
}
FieldTypeRequiredDescription
client_ipstringConditionalClient IP address
pin_codestring (max 16)YesPIN code from SMS
Response — 200 OK
{
  "success": true,
  "data": {
    "contract_id": "16449203-0000-009b-a125-351b7bfbd207",
    "status": "active"
  }
}

After successful authorization the contract becomes active. All payments within the contract validity period proceed without repeated authorization.

4.3 Create invoice (DCB)

Initiates a charge to the client’s mobile account.

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

Request body
{
  "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" }
}
FieldTypeRequiredDescription
client_ipstringConditionalClient IP address
customer.typestringYes"mobile_phone"
customer.msisdnstringYesClient phone number
customer.emailstringNoClient email
order.merchant_order_idstring (max 38)YesOrder ID in the merchant system
order.pricemoneyNoPrice for the client. If omitted, taken from project settings
order.descriptionstringNoOrder description
contract.create_if_not_existsbooleanNoCreate the contract automatically if it does not exist (default false)
contract.merchant_contract_idstring (max 64)NoMerchant contract ID
application.namestring (max 256)NoApplication name
product.namestring (max 256)NoProduct / service name
Response — 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"
    }
  }
}

Only one active invoice per client is allowed within a project. An attempt to create a second invoice returns 409 Conflict with code INVOICE_ALREADY_EXISTS and the details.invoice_id of the existing invoice.

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 Cancel contract

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

Request body
{
  "client_ip": "10.20.30.40"
}
Response — 200 OK
{
  "success": true,
  "data": {
    "contract_id": "16449203-0000-009b-a125-351b7bfbd207",
    "status": "cancelled"
  }
}

4.5 Billing support check

Checks whether activation and billing are possible for a specific MSISDN.

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

Request body
{
  "msisdn": "79600000000"
}
Response — 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" }
    }
  }
}
ConventionsCards, SBP, SberPay