Common methods

6.1 Authorize invoice (PIN)

Confirm the invoice with the PIN code from SMS. Used when no contract is involved and the invoice authorization.type = SMS_PIN.

JSON API v3

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

JSON API v3

Request body


{
  "client_ip": "10.20.30.40",
  "pin_code": "987656"
}

JSON API v3

Response — 200 OK


{
  "success": true,
  "data": {
    "invoice_id": "1624505c-0031-00cf-7d54-4cf1ce08cb30",
    "status": "Authorize"
  }
}

6.2 Cancel invoice

JSON API v3

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

JSON API v3

Request body


{
  "client_ip": "10.20.30.40"
}

JSON API v3

Response — 200 OK


{
  "success": true,
  "data": {
    "invoice_id": "1624505c-0031-00cf-7d54-4cf1ce08cb30",
    "status": "Cancelled"
  }
}

6.3 Get invoice

Get the status of a previously created invoice. Look up by invoice_id (in the path) or merchant_order_id (in the query).

JSON API v3

GET /api/v3/projects/{projectId}/invoices/{invoiceId}

GET /api/v3/projects/{projectId}/invoices?merchant_order_id=order_123

JSON API v3

Response — 200 OK


{
  "success": true,
  "data": {
    "invoice_id": "1624505c-0031-00cf-7d54-4cf1ce08cb30",
    "status": "Processed",
    "payment_status": "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" }
    },
    "transactions": [
      {
        "transaction_id": "B4DA05E2-1D77-40C9-85AC-0BB3835DE8B5",
        "part_number": 1,
        "sequence_number": 1,
        "status": "FAILED",
        "result_code": 210,
        "result_description": "PAYMENT_CHANNEL_NOT_ENOUGH_MONEY",
        "paid_at": "2025-03-29T20:00:10Z",
        "price":          { "amount": "25.00", "currency": "RUB", "vat_included": true },
        "partner_profit": { "amount": "0.00",  "currency": "RUB", "vat_included": true },
        "total_paid":     { "amount": "0.00",  "currency": "RUB", "vat_included": true },
        "total_remaining":{ "amount": "25.00", "currency": "RUB", "vat_included": true },
        "billing_channel": "CPA",
        "service_number": "1234"
      }
    ]
  }
}

XML API v2.9

Response example


<?xml version="1.0" encoding="utf-8"?>
<Response>
  <GetInvoiceResponse>
    <InvoiceInfo>
      <MerchantOrderID>order_123</MerchantOrderID>
      <CustomerPrice amount='25' currency='RUB' includingVAT='true' />
      <CreatedTimeUtc>2021-03-29T20:00:10</CreatedTimeUtc>
      <ExpirationTimeUtc>2021-03-29T22:00:10</ExpirationTimeUtc>
      <InvoiceStatus>Processed</InvoiceStatus>
      <PaymentStatus>PAID</PaymentStatus>
      <AuthorizationType>BY_CONTRACT</AuthorizationType>
      <IsAuthorized>true</IsAuthorized>
      <InvoiceID>1624505c-0031-00cf-7d54-4cf1ce08cb30</InvoiceID>
    </InvoiceInfo>
    <ProjectID>1234</ProjectID>
    <MobilePhoneCustomer>
      <MSISDN>79600000000</MSISDN>
      <Country>ru</Country>
      <NetworkID>3</NetworkID>
      <OperatorID>42</OperatorID>
    </MobilePhoneCustomer>
    <PaymentTransactionsInfo>
      <PaymentTransaction>
        <TransactionID>B4DA05E2-1D77-40C9-85AC-0BB3835DE8B5</TransactionID>
        <PaymentPartNumber>1</PaymentPartNumber>
        <PaymentSequenceNumber>1</PaymentSequenceNumber>
        <PaymentStatus>FAILED</PaymentStatus>
        <PaymentResultCode>210</PaymentResultCode>
        <PaymentResultDescription>PAYMENT_CHANNEL_NOT_ENOUGH_MONEY</PaymentResultDescription>
        <PaymentTimeUtc>2021-03-29T20:00:10</PaymentTimeUtc>
        <CustomerPrice amount='25' currency='RUB' includingVAT='true' />
        <PartnerProfit amount='0' currency='RUB' includingVAT='true' />
        <CustomerPriceTotalPaid amount='0' currency='RUB' includingVAT='true' />
        <CustomerPriceTotalToPay amount='25' currency='RUB' includingVAT='true' />
        <BillingInfo>
          <BillingChannel>CPA</BillingChannel>
          <BillingDetails d6p1:type="MobileBilling" xmlns:d6p1="http://www.w3.org/2001/XMLSchema-instance">
            <ServiceNumber>1234</ServiceNumber>
          </BillingDetails>
        </BillingInfo>
      </PaymentTransaction>
    </PaymentTransactionsInfo>
    <IsContentRequired>false</IsContentRequired>
  </GetInvoiceResponse>
  <ResultCode>0</ResultCode>
  <ResultDescription>OK</ResultDescription>
</Response>

GET /invoices/{invoiceId}

curl


INVOICE_ID=1624505c-0031-00cf-7d54-4cf1ce08cb30
 
curl -sS "$BASE/api/v3/projects/$PROJECT_ID/invoices/$INVOICE_ID" \
  -H "X-Login: $LOGIN" \
  -H "X-Timestamp: $TS" \
  -H "X-Signature-Version: 3" \
  -H "X-Signature: $SIG" | jq '.data.payment_status'

PHP


<?php
$invoiceId = '1624505c-0031-00cf-7d54-4cf1ce08cb30';
 
$ch = curl_init();
curl_setopt_array($ch, [
    CURLOPT_URL        => $base . '/api/v3/projects/' . $projectId . '/invoices/' . $invoiceId,
    CURLOPT_HTTPHEADER => [
        'X-Login: ' . $login,
        'X-Timestamp: ' . $ts,
        'X-Signature-Version: 3',
        'X-Signature: ' . $sig,
    ],
    CURLOPT_RETURNTRANSFER => true,
]);
$invoice = json_decode(curl_exec($ch), true)['data'];
curl_close($ch);
 
echo $invoice['payment_status'];

Python


invoice_id = "1624505c-0031-00cf-7d54-4cf1ce08cb30"
 
response = requests.get(
    f"{BASE}/api/v3/projects/{PROJECT_ID}/invoices/{invoice_id}",
    headers={
        "X-Login": LOGIN,
        "X-Timestamp": ts,
        "X-Signature-Version": "3",
        "X-Signature": sig,
    },
    timeout=30,
)
print(response.json()["data"]["payment_status"])

6.4 Refund

JSON API v3

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

JSON API v3

Request body


{
  "client_ip": "10.20.30.40"
}

JSON API v3

Response — 202 Accepted


{
  "success": true,
  "data": {
    "invoice_id": "1624505c-0031-00cf-7d54-4cf1ce08cb30",
    "refund_status": "processing"
  }
}

The refund result arrives asynchronously via the “Refund notification” webhook.