Справочник API

Выставить счёт

Счёт на подписку (purpose: subscription и plan_id) или на доп. устройства (purpose: devices и devices). Клиента нет — заводится. Продление — тот же вызов на тот же client_id: срок прибавляется к текущему, ссылка подписки не меняется. Ссылку payment_url отдайте клиенту, результат оплаты — GET /payments/{payment_id}.

Заголовок Idempotency-Key обязателен — обычно номер заказа в вашей системе. 201 — счёт выставлен; 200 — повтор с тем же ключом и теми же полями, в ответе тот же счёт и replayed: true; 409 IDEMPOTENCY_KEY_REUSE — ключ уже занят счётом с другими полями; 409 OPERATION_IN_PROGRESS — счёт по этому ключу ещё выставляется, повторите тем же ключом через пару секунд; 503 PAYMENT_UNAVAILABLE — счёт не выставлен, повторите тем же ключом.

POST

api

partner

payments

Выставить счёт

curl --request POST \
  --url https://api.vargopartners.com/api/partner/v1/payments \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "client_id": "user-42",
  "method": "sbp",
  "plan_id": 3,
  "devices": 2,
  "return_url": "<string>"
}
'

import requests

url = "https://api.vargopartners.com/api/partner/v1/payments"

payload = {
    "client_id": "user-42",
    "method": "sbp",
    "plan_id": 3,
    "devices": 2,
    "return_url": "<string>"
}
headers = {
    "Idempotency-Key": "<idempotency-key>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    client_id: 'user-42',
    method: 'sbp',
    plan_id: 3,
    devices: 2,
    return_url: '<string>'
  })
};

fetch('https://api.vargopartners.com/api/partner/v1/payments', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "payment_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "status": "pending",
  "purpose": "subscription",
  "client_id": "user-42",
  "plan_id": 123,
  "devices": 123,
  "method": "sbp",
  "amount": "150.00",
  "platform_amount": "100.00",
  "partner_share": "50.00",
  "currency": "RUB",
  "payment_url": "<string>",
  "created_at": "2023-11-07T05:31:56Z",
  "expires_at": "2023-11-07T05:31:56Z",
  "paid_at": "2023-11-07T05:31:56Z",
  "client": {
    "client_id": "user-42",
    "created_at": "2023-11-07T05:31:56Z",
    "subscription": {
      "status": "active",
      "is_trial": true,
      "expires_at": "2023-11-07T05:31:56Z",
      "days_left": 30,
      "subscription_url": "<string>",
      "connect": [
        {
          "app_id": "happ",
          "app_name": "Happ",
          "connect_url": "<string>",
          "qr_payload": "<string>",
          "supports_manual_url": true
        }
      ],
      "devices_limit": 123
    },
    "trial_available": true
  },
  "replayed": true
}

{
  "payment_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "status": "pending",
  "purpose": "subscription",
  "client_id": "user-42",
  "plan_id": 123,
  "devices": 123,
  "method": "sbp",
  "amount": "150.00",
  "platform_amount": "100.00",
  "partner_share": "50.00",
  "currency": "RUB",
  "payment_url": "<string>",
  "created_at": "2023-11-07T05:31:56Z",
  "expires_at": "2023-11-07T05:31:56Z",
  "paid_at": "2023-11-07T05:31:56Z",
  "client": {
    "client_id": "user-42",
    "created_at": "2023-11-07T05:31:56Z",
    "subscription": {
      "status": "active",
      "is_trial": true,
      "expires_at": "2023-11-07T05:31:56Z",
      "days_left": 30,
      "subscription_url": "<string>",
      "connect": [
        {
          "app_id": "happ",
          "app_name": "Happ",
          "connect_url": "<string>",
          "qr_payload": "<string>",
          "supports_manual_url": true
        }
      ],
      "devices_limit": 123
    },
    "trial_available": true
  },
  "replayed": true
}

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "<string>",
    "fields": {}
  }
}

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "<string>",
    "fields": {}
  }
}

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "<string>",
    "fields": {}
  }
}

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "<string>",
    "fields": {}
  }
}

Authorizations

Authorization

string

header

required

Ключ партнёра vgo_live_…, его выдаёт платформа. Хранится только на сервере партнёра.

Headers

Idempotency-Key

string

required

Ключ повтора, обычно номер заказа в вашей системе, до 200 символов. Повтор с тем же ключом и теми же полями не выставит второй счёт. Нет ключа — 400 IDEMPOTENCY_KEY_REQUIRED, длиннее — 400 IDEMPOTENCY_KEY_TOO_LONG

Required string length: 1 - 200

Body

application/json

Тело POST /payments. Неизвестные поля отклоняются — 422 VALIDATION_ERROR.

client_id

string

required

Id клиента в вашей системе: 1–128 символов A–Z a–z 0–9 . _ : @ + -, не . и не .., регистр различается. Нового клиента счёт заводит сам

Required string length: 1 - 128

Pattern: ^[A-Za-z0-9._:@+-]*[A-Za-z0-9_:@+-][A-Za-z0-9._:@+-]*$

Example:

"user-42"

purpose

enum<string>

required

subscription — подписка или её продление, devices — доп. устройства

Available options:

subscription,

devices

method

string

required

Способ оплаты из GET /payment-methods

Required string length: 1 - 32

Example:

"sbp"

plan_id

integer | null

Id тарифа из GET /plans — только при purpose: subscription

Required range: 1 <= x <= 2147483647

Example:

3

devices

integer | null

Сколько устройств добавить, от 1 — только при purpose: devices

Required range: x >= 1

return_url

string | null

Куда вернуть клиента после оплаты: только https, до 500 символов. Поддерживается не каждым способом оплаты

Maximum string length: 500

Response

Повтор по тому же Idempotency-Key: счёт первого запроса, replayed: true

payment_id

string<uuid>

required

Id счёта

status

enum<string>

required

pending — ждёт оплаты; succeeded — оплачен, доступ выдан; expired — срок оплаты вышел, но статус не окончательный: поздняя оплата переводит счёт в succeeded; failed — оплата не прошла, бывает и после succeeded, если банк отозвал платёж

Available options:

pending,

succeeded,

failed,

expired

purpose

enum<string>

required

Что оплачивается

Available options:

subscription,

devices

client_id

string

required

Id клиента в вашей системе

Example:

"user-42"

plan_id

integer | null

required

Тариф — у purpose: subscription

devices

integer | null

required

Сколько устройств — у purpose: devices

method

string

required

Способ оплаты

Example:

"sbp"

amount

string

required

Сумма к оплате клиентом

Example:

"150.00"

platform_amount

string

required

Часть платформы

Example:

"100.00"

Наценка партнёра: после оплаты ложится на его баланс

Example:

"50.00"

currency

string

required

Валюта

Example:

"RUB"

payment_url

string | null

required

Страница оплаты для клиента; есть только у pending

created_at

string<date-time>

required

Когда счёт выставлен, UTC

expires_at

string<date-time>

required

Ориентир срока оплаты, UTC: статус меняется с задержкой до часа, поздняя оплата проходит

paid_at

string<date-time> | null

required

Когда счёт оплачен, UTC

client

ApiClient · object | null

required

Клиент со ссылкой подписки; заполнен у succeeded

Show child attributes

replayed

boolean

required

true — повтор по тому же Idempotency-Key: в ответе счёт, выставленный первым запросом

Выставить счёт

curl --request POST \
  --url https://api.vargopartners.com/api/partner/v1/payments \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "client_id": "user-42",
  "method": "sbp",
  "plan_id": 3,
  "devices": 2,
  "return_url": "<string>"
}
'

import requests

url = "https://api.vargopartners.com/api/partner/v1/payments"

payload = {
    "client_id": "user-42",
    "method": "sbp",
    "plan_id": 3,
    "devices": 2,
    "return_url": "<string>"
}
headers = {
    "Idempotency-Key": "<idempotency-key>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    client_id: 'user-42',
    method: 'sbp',
    plan_id: 3,
    devices: 2,
    return_url: '<string>'
  })
};

fetch('https://api.vargopartners.com/api/partner/v1/payments', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "payment_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "status": "pending",
  "purpose": "subscription",
  "client_id": "user-42",
  "plan_id": 123,
  "devices": 123,
  "method": "sbp",
  "amount": "150.00",
  "platform_amount": "100.00",
  "partner_share": "50.00",
  "currency": "RUB",
  "payment_url": "<string>",
  "created_at": "2023-11-07T05:31:56Z",
  "expires_at": "2023-11-07T05:31:56Z",
  "paid_at": "2023-11-07T05:31:56Z",
  "client": {
    "client_id": "user-42",
    "created_at": "2023-11-07T05:31:56Z",
    "subscription": {
      "status": "active",
      "is_trial": true,
      "expires_at": "2023-11-07T05:31:56Z",
      "days_left": 30,
      "subscription_url": "<string>",
      "connect": [
        {
          "app_id": "happ",
          "app_name": "Happ",
          "connect_url": "<string>",
          "qr_payload": "<string>",
          "supports_manual_url": true
        }
      ],
      "devices_limit": 123
    },
    "trial_available": true
  },
  "replayed": true
}

{
  "payment_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "status": "pending",
  "purpose": "subscription",
  "client_id": "user-42",
  "plan_id": 123,
  "devices": 123,
  "method": "sbp",
  "amount": "150.00",
  "platform_amount": "100.00",
  "partner_share": "50.00",
  "currency": "RUB",
  "payment_url": "<string>",
  "created_at": "2023-11-07T05:31:56Z",
  "expires_at": "2023-11-07T05:31:56Z",
  "paid_at": "2023-11-07T05:31:56Z",
  "client": {
    "client_id": "user-42",
    "created_at": "2023-11-07T05:31:56Z",
    "subscription": {
      "status": "active",
      "is_trial": true,
      "expires_at": "2023-11-07T05:31:56Z",
      "days_left": 30,
      "subscription_url": "<string>",
      "connect": [
        {
          "app_id": "happ",
          "app_name": "Happ",
          "connect_url": "<string>",
          "qr_payload": "<string>",
          "supports_manual_url": true
        }
      ],
      "devices_limit": 123
    },
    "trial_available": true
  },
  "replayed": true
}

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "<string>",
    "fields": {}
  }
}

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "<string>",
    "fields": {}
  }
}

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "<string>",
    "fields": {}
  }
}

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "<string>",
    "fields": {}
  }
}

Начало

Справочник API

Как это работает

Подключение

Выставить счёт

Authorizations

Headers

Body

Response