Документация API Zenpayments: примеры кода

Примеры решения разных конкретных задач при работе с заказами

Создание заказов

Во всех примерах вам нужно заменить TOKEN и REQUISITE_ID на собственные значения.

TOKEN нужно создать в разделе API токены личного кабинета.

REQUISITE_ID нужно узнать в разделе "Компании". Кликните на добавленную компанию и посмотрите подзаголовок "Информация для работы с API".

Заказ с оплатой картой и СБП

curl --request POST \
    "https://zenpayments.ru/api/v1/orders/store" \
    --header "Authorization: Bearer TOKEN" \
    --header "Content-Type: application/json" \
    --data "{
    \"customer_email\": \"alex@example.org\",
    \"is_subscription\": false,
    \"methods\": [
        {
            \"name\": \"Оплата картой и СБП\",
            \"method\": 1
        }
    ],
    \"positions\": [
        {
            \"content\": \"Оплата доступа к курсу\",
            \"price\": 1999.99,
            \"quantity\": 1,
            \"vat_code_id\": 1
        }
    ],
    \"team_requisite_id\": REQUISITE_ID
}"

Заказ с оплатой по подписке, списание раз в месяц

curl --request POST \
    "https://zenpayments.ru/api/v1/orders/store" \
    --header "Authorization: Bearer TOKEN" \
    --header "Content-Type: application/json" \
    --data "{
    \"customer_email\": \"alex@example.org\",
    \"is_subscription\": true,
    \"methods\": [
        {
            \"name\": \"Оплата картой и СБП\",
            \"method\": 1,
            \"interval\": 5,
            \"period\": 1,
            \"is_recurring\": true,
            \"is_subscription\": true
        }
    ],
    \"positions\": [
        {
            \"content\": \"Оплата доступа к клубу\",
            \"price\": 5000,
            \"quantity\": 1,
            \"vat_code_id\": 1
        }
    ],
    \"team_requisite_id\": REQUISITE_ID
}"

Заказ с оплатой по подписке, списание раз в месяц, первый платёж отличается

curl --request POST \
    "https://zenpayments.ru/api/v1/orders/store" \
    --header "Authorization: Bearer TOKEN" \
    --header "Content-Type: application/json" \
    --data "{
    \"customer_email\": \"alex@example.org\",
    \"is_subscription\": true,
    \"methods\": [
        {
            \"name\": \"Оплата картой и СБП\",
            \"method\": 1,
            \"interval\": 5,
            \"period\": 1,
            \"is_recurring\": true,
            \"is_subscription\": true,
            \"custom_first_payment_amount\": 2500
        }
    ],
    \"positions\": [
        {
            \"content\": \"Оплата доступа к клубу\",
            \"price\": 5000,
            \"quantity\": 1,
            \"vat_code_id\": 1
        }
    ],
    \"team_requisite_id\": REQUISITE_ID
}"

Заказ с оплатой по подписке, списание раз в две недели

curl --request POST \
    "https://zenpayments.ru/api/v1/orders/store" \
    --header "Authorization: Bearer TOKEN" \
    --header "Content-Type: application/json" \
    --data "{
    \"customer_email\": \"alex@example.org\",
    \"is_subscription\": true,
    \"methods\": [
        {
            \"name\": \"Оплата картой и СБП\",
            \"method\": 1,
            \"interval\": 4,
            \"period\": 2,
            \"is_recurring\": true,
            \"is_subscription\": true
        }
    ],
    \"positions\": [
        {
            \"content\": \"Оплата доступа к клубу\",
            \"price\": 5000,
            \"quantity\": 1,
            \"vat_code_id\": 1
        }
    ],
    \"team_requisite_id\": REQUISITE_ID
}"

Заказ с оплатой по подписке, списание раз в пять дней

curl --request POST \
    "https://zenpayments.ru/api/v1/orders/store" \
    --header "Authorization: Bearer TOKEN" \
    --header "Content-Type: application/json" \
    --data "{
    \"customer_email\": \"alex@example.org\",
    \"is_subscription\": true,
    \"methods\": [
        {
            \"name\": \"Оплата картой и СБП\",
            \"method\": 1,
            \"interval\": 3,
            \"period\": 5,
            \"is_recurring\": true,
            \"is_subscription\": true
        }
    ],
    \"positions\": [
        {
            \"content\": \"Оплата доступа к клубу\",
            \"price\": 5000,
            \"quantity\": 1,
            \"vat_code_id\": 1
        }
    ],
    \"team_requisite_id\": REQUISITE_ID
}"

Заказ с оплатой в рассрочку, списание раз в месяц

curl --request POST \
    "https://zenpayments.ru/api/v1/orders/store" \
    --header "Authorization: Bearer TOKEN" \
    --header "Content-Type: application/json" \
    --data "{
    \"customer_email\": \"alex@example.org\",
    \"is_subscription\": false,
    \"methods\": [
        {
            \"name\": \"Оплата картой и СБП\",
            \"method\": 1,
            \"interval\": 5,
            \"period\": 1,
            \"is_recurring\": true,
            \"is_subscription\": false
        }
    ],
    \"positions\": [
        {
            \"content\": \"Оплата доступа в рассрочку\",
            \"price\": 5000,
            \"quantity\": 1,
            \"vat_code_id\": 1
        }
    ],
    \"team_requisite_id\": REQUISITE_ID
}"

Заказ с оплатой с помощью банковской рассрочки

Изменён параметр method. Добавлен параметр gateway. Возможные значения смотрите в основной документации.

curl --request POST \
    "https://zenpayments.ru/api/v1/orders/store" \
    --header "Authorization: Bearer TOKEN" \
    --header "Content-Type: application/json" \
    --data "{
    \"customer_email\": \"alex@example.org\",
    \"is_subscription\": false,
    \"methods\": [
        {
            \"name\": \"Рассрочка от банка\",
            \"method\": 2,
            \"gateway\": 4
        }
    ],
    \"positions\": [
        {
            \"content\": \"Оплата доступа к курсу\",
            \"price\": 1999.99,
            \"quantity\": 1,
            \"vat_code_id\": 1
        }
    ],
    \"team_requisite_id\": REQUISITE_ID
}"

Заказ с оплатой в кредит

Изменён параметр method. Добавлен параметр gateway. Возможные значения смотрите в основной документации.

curl --request POST \
    "https://zenpayments.ru/api/v1/orders/store" \
    --header "Authorization: Bearer TOKEN" \
    --header "Content-Type: application/json" \
    --data "{
    \"customer_email\": \"alex@example.org\",
    \"is_subscription\": false,
    \"methods\": [
        {
            \"name\": \"Кредит от банка\",
            \"method\": 3,
            \"gateway\": 4
        }
    ],
    \"positions\": [
        {
            \"content\": \"Оплата доступа к курсу\",
            \"price\": 1999.99,
            \"quantity\": 1,
            \"vat_code_id\": 1
        }
    ],
    \"team_requisite_id\": REQUISITE_ID
}"

Заказ с оплатой через BNPL-сервисы

Изменён параметр method. Добавлен параметр gateway. Возможные значения смотрите в основной документации.

curl --request POST \
    "https://zenpayments.ru/api/v1/orders/store" \
    --header "Authorization: Bearer TOKEN" \
    --header "Content-Type: application/json" \
    --data "{
    \"customer_email\": \"alex@example.org\",
    \"is_subscription\": false,
    \"methods\": [
        {
            \"name\": \"BNPL\",
            \"method\": 4,
            \"gateway\": 5
        }
    ],
    \"positions\": [
        {
            \"content\": \"Оплата доступа к курсу\",
            \"price\": 1999.99,
            \"quantity\": 1,
            \"vat_code_id\": 1
        }
    ],
    \"team_requisite_id\": REQUISITE_ID
}"

Заказ, на выбор два метода оплаты: картой или в кредит

Изменён параметр method. Добавлен параметр gateway. Возможные значения смотрите в основной документации.

curl --request POST \
    "https://zenpayments.ru/api/v1/orders/store" \
    --header "Authorization: Bearer TOKEN" \
    --header "Content-Type: application/json" \
    --data "{
    \"customer_email\": \"alex@example.org\",
    \"is_subscription\": false,
    \"methods\": [
        {
            \"name\": \"Картой и СБП\",
            \"method\": 1
        },
        {
            \"name\": \"В кредит\",
            \"method\": 3,
            \"gateway\": 4
        }
    ],
    \"positions\": [
        {
            \"content\": \"Оплата доступа к курсу\",
            \"price\": 1999.99,
            \"quantity\": 1,
            \"vat_code_id\": 1
        }
    ],
    \"team_requisite_id\": REQUISITE_ID
}"

Вебхуки

Этот раздел документации описывает вебхуки, которые Zenpayments может отправлять вам. Для того, чтобы задать адрес вебхуков, при создании заказа используйте поле callback_url.

Заказ создан

{
  "id": "bmaVNlXuvugWliPS67ON3CVHDs6WsEvr",
  "timestamp": "1758103375",
  "event": "order.created",
  "payload": {
    "created_at": 1758103375,
    "order_number": "ZP-1-60308116515848192",
    "order_id_client": null,
    "customer_last_name": "Пушкин",
    "customer_first_name": "Александр",
    "customer_middle_name": "Сергеевич",
    "customer_email": "alex@example.org",
    "customer_phone": null,
    "order_positions": [
      {
        "content": "Доступ к курсу",
        "price": 10000,
        "quantity": 1,
        "vat_code_id": 1
      }
    ],
    "is_subscription": false,
    "payment_methods": [
      {
        "id": 299,
        "is_recurring": false,
        "is_subscription": false,
        "name": "Эквайринг (оплата картой или СБП)",
        "method": 1,
        "gateway": null,
        "terms": null,
        "custom_first_payment_amount": null,
        "interval": null,
        "period": null,
        "max_payments": null
      }
    ],
    "return_url": null,
    "success_url": null,
    "fail_url": null,
    "callback_url": "https://your-server-example.org/webhook-endpoint",
    "team_requisite_id": 2
  }
}

Покупатель перешёл к оплате

{
  "id": "oRLbOn2GRyVOYbWwXGfweE9gAhYxFFvA",
  "timestamp": "1758103546",
  "event": "payment.proceeded_to_gateway",
  "payload": {
    "payment_number": "P-1-60308835805429760",
    "amount": 10000,
    "currency_code": "RUB",
    "payment_method": 1,
    "payment_gateway": null,
    "payment_terms": null,
    "order_number": "ZP-1-60308116515848192",
    "order_id_client": null,
    "invoice_number": "INV-1-60308835759292416",
    "customer_last_name": "Пушкин",
    "customer_first_name": "Александр",
    "customer_middle_name": "Сергеевич",
    "customer_email": "alex@example.org",
    "customer_phone": null,
    "order_positions": [
      {
        "content": "Доступ к курсу",
        "quantity": 1,
        "vat_code_id": 1,
        "price": 10000,
        "price_discounted": 10000
      }
    ]
  }
}

Покупатель успешно оплатил заказ

{
  "id": "aknTHNMGVa0ssKj1BBz9ZN05YibavObX",
  "timestamp": "1758103556",
  "event": "payment.accepted",
  "payload": {
    "paid_at": 1758103556,
    "payment_number": "P-1-60308835805429760",
    "amount_paid": 10000,
    "amount_commission": 599,
    "currency_code": "RUB",
    "payment_method": 1,
    "payment_gateway": null,
    "payment_terms": null,
    "order_number": "ZP-1-60308116515848192",
    "order_id_client": null,
    "invoice_number": "INV-1-60308835759292416",
    "next_payment_at": null,
    "customer_last_name": "Пушкин",
    "customer_first_name": "Александр",
    "customer_middle_name": "Сергеевич",
    "customer_email": "alex@example.org",
    "customer_phone": null,
    "order_positions": [
      {
        "content": "Доступ к курсу",
        "quantity": 1,
        "vat_code_id": 1,
        "price": 10000,
        "price_discounted": 10000
      }
    ],
    "pan4": "1111"
  }
}

Не удалось списать автоплатёж

{
  "id": "6eU4SAbMGYCig6TkKJasGf49xaR0fSAr",
  "timestamp": "1758103779",
  "event": "invoice.autopayment_failed",
  "payload": {
    "order_number": "ZP-1-60308116515848192",
    "order_id_client": null,
    "invoice_number": "INV-1-60308835759292416",
    "customer_last_name": "Пушкин",
    "customer_first_name": "Александр",
    "customer_middle_name": "Сергеевич",
    "customer_email": "alex@example.org",
    "customer_phone": null
  }
}

Изменился статус по заявке на кредит/рассрочку

Возможные значения event_code:

  • 0: заявка создана
  • 1: заявка одобрена хотя бы одним банком
  • 2: пришёл отказ по одному из банков
  • 3: договор подписан

Обратите внимание, что в случае подписания договора, следует также смотреть на поле has_finished_cooldown. Это поле отображает период охлаждения. Значение false означает, что период охлаждения ещё не завершён. А значение true означает, что деньги выданы.

Дату окончания периода охлаждения можно увидеть в поле cooldown_ends_at.

{
  "id": "Uftmc6f3fMaBk02e64ziPiNaSOrFSpJl",
  "timestamp": "1758103953",
  "event": "bank_credit.status_changed",
  "payload": {
    "changed_at": 1758103953,
    "event_code": 3,
    "has_finished_cooldown": true,
    "cooldown_ends_at": 1758103953, // может быть null
    "payment_number": "P-1-60308835805429760",
    "currency_code": "RUB",
    "payment_method": 1,
    "payment_gateway": null,
    "payment_terms": null,
    "order_number": "ZP-1-60308116515848192",
    "order_id_client": null,
    "invoice_number": "INV-1-60308835759292416",
    "customer_last_name": "Пушкин",
    "customer_first_name": "Александр",
    "customer_middle_name": "Сергеевич",
    "customer_email": "alex@example.org",
    "customer_phone": null,
    "order_positions": [
      {
        "content": "Доступ к курсу",
        "quantity": 1,
        "vat_code_id": 1,
        "price": 10000,
        "price_discounted": 10000
      }
    ]
  }
}

Возврат проведён

{
  "id": "DhBbR8z8ciCeWp1X0uuTqWArdFUSKZcR",
  "timestamp": "1768362416",
  "event": "refund.created",
  "payload": {
    "amount_refunded": 500,
    "refund_number": "RF-1-103337652605943808",
    "payment_number": "P-1-103334561722662912",
    "currency_code": "RUB",
    "order_number": "ZP-1-103334526800887808",
    "order_id_client": null,
    "invoice_number": "INV-1-103334561336786944",
    "customer_last_name": "Пушкин",
    "customer_first_name": "Александр",
    "customer_middle_name": "Сергеевич",
    "customer_email": "alex@example.org",
    "customer_phone": null
  }
}

Справка: payment_terms

Параметр payment_terms передаётся в некоторых вебхуках. Значение параметра является целым числом. Ниже справочная таблица значений:

Значение Описание
0 Кредит
1 Рассрочка на 3 месяца
2 Рассрочка на 6 месяцев
3 Рассрочка на 10 месяцев
4 Рассрочка на 12 месяцев
5 Рассрочка на 18 месяцев
6 Рассрочка на 24 месяца
7 Рассрочка на 36 месяцев
8 Рассрочка с переплатой на покупателе на 3 месяца
9 Рассрочка с переплатой на покупателе на 6 месяцев
10 Рассрочка с переплатой на покупателе на 10 месяцев
11 Рассрочка с переплатой на покупателе на 12 месяцев
12 Рассрочка с переплатой на покупателе на 18 месяцев
13 Рассрочка с переплатой на покупателе на 24 месяца
14 Рассрочка с переплатой на покупателе на 36 месяцев
15 Рассрочка с переплатой на покупателе на 9 месяцев
16 Рассрочка с переплатой на покупателе на 15 месяцев
17 Рассрочка с переплатой на покупателе на 28 месяцев
18 Рассрочка с переплатой на покупателе на 30 месяцев
19 Рассрочка с переплатой на покупателе на 8 месяцев
20 Рассрочка с переплатой на покупателе на 30 месяцев

Авторизация запросов

This API is not authenticated.