/v1/subscriptions

Запрос на создание подписки.

Используется для создания подписки и получения ссылки для ее оформления.

Request

POST

https://pay.yandex.ru/api/merchant/v1/subscriptions

Production

POST

https://sandbox.pay.yandex.ru/api/merchant/v1/subscriptions

Sandbox

Body

application/json
{
    "cart": {
        "externalId": "string",
        "items": [
            {
                "description": "string",
                "discountedUnitPrice": "123.45",
                "features": {
                    "tariffModifier": "VERY_LOW"
                },
                "productId": "string",
                "quantity": {
                    "available": "123.45",
                    "count": "123.45"
                },
                "receipt": {
                    "agent": {
                        "agentType": 1,
                        "operation": "string",
                        "paymentsOperator": {
                            "phones": [
                                "string"
                            ]
                        },
                        "phones": [
                            "string"
                        ],
                        "transferOperator": {
                            "address": "string",
                            "inn": "string",
                            "name": "string",
                            "phones": [
                                "string"
                            ]
                        }
                    },
                    "excise": "123.45",
                    "markQuantity": {
                        "denominator": 0,
                        "numerator": 0
                    },
                    "measure": 0,
                    "paymentMethodType": 1,
                    "paymentSubjectType": 1,
                    "productCode": "string",
                    "supplier": {
                        "inn": "string",
                        "name": "string",
                        "phones": [
                            "string"
                        ]
                    },
                    "tax": 1,
                    "title": "string"
                },
                "skuId": "string",
                "subtotal": "123.45",
                "title": "string",
                "total": "123.45",
                "unitPrice": "123.45"
            }
        ],
        "total": {
            "amount": "123.45"
        }
    },
    "currencyCode": "RUB",
    "futureWriteOffAmount": "123.45",
    "intervalCount": "6",
    "intervalUnit": "SECOND",
    "isBinding": false,
    "metadata": "string",
    "orderId": "string",
    "orderSource": "WEBSITE",
    "purpose": "string",
    "redirectUrls": {
        "onAbort": "string",
        "onError": "string",
        "onSuccess": "string"
    },
    "title": "string",
    "trialCount": 0,
    "trialEndAt": "2022-12-29T18:02:01Z",
    "trialUnit": "SECOND",
    "ttl": 1800
}

Name

Description

currencyCode*

Type: string

Трехбуквенный код валюты заказа (ISO 4217)

Max length: 2048

Enum: RUB, UZS

orderId*

Type: string

Уникальный идентификатор заказа на стороне продавца.

Используется:

  • как ключ идемпотентности;
  • для дальнейшего взаимодействия по заказу и платежу;
  • в сверках.

Max length: 2048

cart

Type: RenderedCart1

Корзина

futureWriteOffAmount

Type: string<double>

Сумма, которую будет списана в будущем

Example: 123.45

intervalCount

Type: integer<int32>

Количество периодов подписки в единицах времени, указанных в intervalUnit.

Например, для подписки в 6 месяцев укажите: intervalUnit: 'MONTH', intervalCount: 6.

Обязательно, если не указан параметр isBinding=True.

Example: 6

intervalUnit

Type: string

Единица времени, в которой будет периодичность подписки.

Обязательно, если не указан параметр isBinding=True.

Enum: SECOND, DAY, WEEK, MONTH, YEAR, null

isBinding

Type: boolean

Позволяет привязать карту пользователя без сформированной корзины товаров

Если во время первого списания нужна только привязка карты, передайте в запросе параметр isBinding=true.

Корзину и периодичность подписки в данном сценарии передавать не нужно.

Default: false

metadata

Type: string

Произвольные данные по заказу для внутреннего использования

Max length: 2048

orderSource

Type: string

Поверхность на который инициализацировали создание заказа

Необходимо для последующей аналитики

WEBSITE: Кнопка размещена на сайте. Ссылка на оплату сформировалась после действий (нажатия кнопки) пользователя на сайте

APP: Кнопка размещена в мобильном приложении. Ссылка на оплату сформировалась после действий (нажатия кнопки) пользователя в приложении

CRM: Ссылка на оплату сформирована менеджером в CRM или другой админке

CASH_REGISTER: Ссылка на оплату сформирована для отображения на оффлайн-кассе

CMS_PLUGIN: Ссылка на оплату сформирована в плагине для CMS

TV: Ссылка на оплату сформирована для отображения на ТВ-платформе

Default: null

Enum: WEBSITE, APP, CRM, CASH_REGISTER, CMS_PLUGIN, TV

purpose

Type: string

Назначение платежа

Max length: 1000

redirectUrls

Type: MerchantRedirectUrls

Ссылки для переадресации пользователя с формы оплаты. Обязательно для онлайн-магазинов.

title

Type: string

Название подписки

Max length: 30

trialCount

Type: integer<int32>

Количество периодов триального периода, например "7 дней"

trialEndAt

Type: string<date-time>

Дата окончания пробного периода. Взаимоисключающее с полями trial_unit + trial_count

trialUnit

Type: string

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

Enum: SECOND, DAY, WEEK, MONTH, YEAR, null

ttl

Type: integer<int32>

Время жизни заказа (в секундах)

180 <= ttl <= 604800

Default: 1800

RenderedCart1

Примечание

Стоимость доставки передавайте в items как отдельный товар.

Name

Description

items*

Type: RenderedCartItem1[]

Корзина товаров, которую оплачивает покупатель.

total*

Type: CartTotal

Итоговая информация о стоимости заказа.

externalId

Type: string

Идентификатор корзины на стороне продавца.

Max length: 2048

MerchantRedirectUrls

Примечание

В мобильных интеграциях, использующих App Link и Universal Link, в поле redirectUrls можно указать базовый URL сайта.

Name

Description

onError*

Type: string

Обязательное поле только для онлайн-магазинов. Ссылка для переадресации пользователя в случае возникновения ошибки во время оплаты, или если срок ссылки на оплату истек.

Max length: 2048

onSuccess*

Type: string

Обязательное поле только для онлайн-магазинов. Ссылка для переадресации пользователя в случае успешной оплаты.

Max length: 2048

onAbort

Type: string

Ссылка для переадресации пользователя в случае отмены процесса оплаты. Отмену оплаты осуществляет пользователь на форме для оплаты.

Max length: 2048

RenderedCartItem1

Name

Description

productId*

Type: string

Id товара в системе продавца. В параметрах запроса каждый идентификатор товара productId должен быть уникальным

Max length: 2048

quantity*

Type: ItemQuantity

Количество товара в заказе

title*

Type: string

Наименование товара

Max length: 2048

total*

Type: string<double>

Итоговая цена позиции с учетом примененных скидок.

Важно

Убедитесь, что цена за единицу товара (total / quantity.count) имеет максимум 2 знака в дробной части. Иначе вернется ошибка ORDER_CART_DATA_ERROR.

Чтобы избежать ошибок, вынесите товары в отдельные позиции с разными productId.

Пример

Правильно:

{
  "productId": "xxx-123",
  "quantity": {
    "count": "2"
  },
  "title": "Мармелад",
  "total": "100.50"
}

Цена за единицу 100.50 / 2 = 50.25 c двумя знаками в дробной части.

Неправильно:

{
  "productId": "xxx-123",
  "quantity": {
    "count": "2"
  },
  "title": "Мармелад",
  "total": "100.25"
}

Цена за единицу 100.25 / 2 = 50.125 c тремя знаками в дробной части.

В таком случае разбейте на две позиции:

[
  {
    "productId": "xxx-123-1",
    "quantity": {
      "count": "1"
    },
    "title": "Мармелад",
    "total": "50.25"
  },
  {
    "productId": "xxx-123-2",
    "quantity": {
      "count": "1"
    },
    "title": "Мармелад со скидкой",
    "total": "50"
  }
]

Example: 123.45

description

Type: string

Описание товара

Max length: 2048

discountedUnitPrice

Type: string<double>

Цена за единицу товара с учётом скидок на позицию

Example: 123.45

features

Type: CartItemFeatures1

Промо параметры товара

receipt

⦸

Type: ItemReceipt

Данные для формирования чека.

Deprecated

В актуальных интеграциях передавать данные для чека не требуется. Чек формируется на вашей стороне. Подробнее см. в разделе Фискализация.

skuId

Type: string

Уникальный id, который описывает единицу ассортимента. Необходим для применения индивидуального тарифа.

Max length: 2048

subtotal

Type: string<double>

Суммарная цена за позицию без учета скидок

Example: 123.45

unitPrice

Type: string<double>

Полная цена за единицу товара без учетка скидки

Example: 123.45

CartTotal

Name

Description

amount*

Type: string<double>

Стоимость корзины с учетом всех скидок.

Example: 123.45

ItemQuantity

Name

Description

count*

Type: string<double>

Количество товара в заказе

Example: 123.45

available

Type: string<double>

Максимально доступное количество товара

Example: 123.45

CartItemFeatures1

Name

Description

tariffModifier

Type: string

Модификатор тарифа для расчета комиссии. Определяет, какой тариф будет применяться при расчете комиссии за обработку позиции в корзине.

Enum: VERY_LOW, LOW, MEDIUM, HIGH, VERY_HIGH, null

ItemReceipt

Deprecated

В актуальных интеграциях передавать данные для чека не требуется. Чек формируется на вашей стороне. Подробнее см. в разделе Фискализация.

Name

Description

tax*

Type: integer

Описание значений: Ссылка

Enum: 1, 2, 3, 4, 5, 6, 7, 8, 9, 10

agent

⦸

Type: Agent

excise

Type: string<double>

Не должно содержать больше двух знаков после запятой. Например: 1.12, 5.1, 10, 11.00 .

Example: 123.45

markQuantity

⦸

Type: MarkQuantity

measure

Type: integer

Описание значений: Ссылка

Enum: 0, 10, 11, 12, 20, 21, 22, 30, 31, 32, 40, 41, 42, 50, 51, 70, 71, 72, 73, 80, 81, 82, 83, 255, null

paymentMethodType

Type: integer

Описание значений: Ссылка

Enum: 1, 2, 3, 4, 5, 6, 7, null

paymentSubjectType

Type: integer

Описание значений: Ссылка

Enum: 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, null

productCode

Type: string<base64>

Код товара (base64 кодированный массив от 1 до 32 байт)

supplier

⦸

Type: Supplier

title

Type: string

Max length: 2048

Agent

Name

Description

agentType*

Type: integer

Признак агента по предмету расчёта. См. значения

Enum: 1, 2, 3, 4, 5, 6, 7

operation

Type: string

Max length: 2048

paymentsOperator

⦸

Type: PaymentsOperator

phones

Type: string[]

Max length: 2048

transferOperator

⦸

Type: TransferOperator

MarkQuantity

Name

Description

denominator*

Type: integer<int32>

numerator*

Type: integer<int32>

Supplier

Name

Description

inn

Type: string

Max length: 2048

name

Type: string

Max length: 2048

phones

Type: string[]

Max length: 2048

PaymentsOperator

Name

Description

phones

Type: string[]

Max length: 2048

TransferOperator

Name

Description

address

Type: string

Max length: 2048

inn

Type: string

Max length: 2048

name

Type: string

Max length: 2048

phones

Type: string[]

Max length: 2048

Responses

200 OK

Body

application/json
{
    "code": 200,
    "data": {
        "paymentUrl": "string",
        "subscriptionId": "c3073b9d-edd0-49f2-a28d-b7ded8ff9a8b"
    },
    "status": "success"
}

Name

Description

data*

Type: CreateSubscriptionResponseData

code

Type: number

Default: 200

status

Type: string

Default: success

Enum: success

CreateSubscriptionResponseData

Name

Description

paymentUrl*

Type: string

Ссылка на оплату заказа

Max length: 2048

subscriptionId*

Type: string<uuid>

Идентификатор подписки

Max length: 2048

No longer supported, please use an alternative and newer version.

Предыдущая
Overview
Следующая
/v1/subscriptions/recur