Платежи

Объект платежа

Объект платежа (Payment) содержит всю информацию о платеже, актуальную на текущий момент времени. Он формируется при создании платежа и приходит в ответ на любой запрос, связанный с платежами.

Объект может содержать параметры и значения, не описанные в этом Справочнике API. Их следует игнорировать.

Параметр
Тип
Обязателен
Описание

uuid

string

Идентификатор платежа в Payvo

status

string

Статус платежа. Возможные значения: pending, succeeded и canceled.

is_test

boolean

Признак тестового платежа.

amount

number

Сумма платежа в копейках.

merchant_customer_id

string

Идентификатор покупателя в вашей системе, например электронная почта или номер телефона. Не более 200 символов.

description

string

Описание платежа (не более 128 символов), которое вы увидите в личном кабинете Payvo, а пользователь — при оплате.

metadata

object

Любые дополнительные данные, которые нужны вам для работы (например, ваш внутренний идентификатор заказа). Передаются в виде набора пар «ключ-значение» и возвращаются в ответе от Payvo. Ограничения: максимум 16 ключей, имя ключа не больше 32 символов, значение ключа не больше 512 символов, тип данных — строка в формате UTF-8.

refunded_amount

number

Сумма в копейках, которая вернулась пользователю. Присутствует, если у этого платежа есть успешные возвраты.

expires_at

string

Время, до которого пользователь может совершить оплату. В указанное время платеж в статусе pending будет автоматически отменен. Указывается по UTC и передается в формате ISO 8601. Пример: 2025-07-10T11:52:31.827Z

created_at

string

Время создания платежа. Указывается по UTC и передается в формате ISO 8601. Пример: 2025-07-10T11:52:31.827Z

income_amount

number

Сумма платежа в копейках, которую получит магазин, — значение amount за вычетом комиссии Payvo.

confirmation

object

Данные, необходимые для инициирования выбранного сценария для совершения оплаты заказа пользователем.

confirmation.type

string

Тип выбранного сценария: redirect или qr

confirmation.url

string

URL, на который нужно перенаправить пользователя для оплаты заказа. Обязателен при confirmation.type в значении redirect.

confirmation.return_url

string

URL, на который нужно перенаправить пользователя после оплаты заказа. Обязателен при confirmation.type в значении redirect.

confirmation.data

string

Данные для генерации QR-кода. Обязателен при confirmation.type в значении qr.

payment_method

object

Способ оплаты, который был использован для этого платежа.

payment_method.type

string

Код выбранного способа оплаты.

payment_method.id

string

Идентификатор способа оплаты. Отображается только в том случае, если вы сохраняете метод с помощью save_payment_method или уже используете сохранённый метод, указав payment_method_id.

payment_method.saved

string

С помощью сохраненного способа оплаты можно проводить безакцептные списания.

receipt

object

Данные о чеке платежа. Отображается только при использовании сервиса Payvo.Чеки и у платежей в статусе succeeded.

receipt.customer.email

string

Электронная почта пользователя для отправки чека.

receipt.items

array

Список товаров в заказе.

receipt.items[].description

string

Название товара (от 1 до 128 символов).

receipt.items[].amount

number

Цена товара в копейках.

receipt.items[].vat_code

number

Ставка НДС. Перечень возможных значений.

receipt.items[].quantity

number

Количество товара.

receipt.items[].payment_subject

string

Признак предмета расчета — это то, за что принимается оплата, например товар, услуга. Перечень возможных значений.

receipt.items[].measure

string

Мера количества предмета расчета — единица измерения товара, например штуки, граммы. Перечень возможных значений.

receipt.registration_status

string

Статус регистрации чека. Возможные значения:

  • pending — данные в обработке;

  • succeeded — чек успешно зарегистрирован;

  • canceled — чек зарегистрировать не удалось; обратитесь в техническую поддержку.

cancellation_details

object

Комментарий к статусу canceled: кто отменил платеж и по какой причине. Подробнее про неуспешные платежи.

cancellation_details.party

string

Участник процесса платежа, который принял решение об отмене транзакции.

Подробнее про инициаторов отмены платежа.

cancellation_details.reason

string

Причина отмены платежа.

Перечень и описание возможных значений.

Создание платежа

Чтобы принять оплату, необходимо создать объект платежа — Payment. Он содержит всю необходимую информацию для проведения оплаты (сумму, валюту и статус). У платежа линейный жизненный цикл, он последовательно переходит из статуса в статус.

POST https://api.payvo.ru/public/payments

Параметры запроса

Параметр
Тип
Обязателен
Описание

amount

number

Сумма платежа в копейках.

merchant_customer_id

string

Идентификатор покупателя в вашей системе, например электронная почта или номер телефона. Не более 200 символов.

description

string

Описание платежа (не более 128 символов), которое вы увидите в личном кабинете Payvo, а пользователь — при оплате.

metadata

object

Любые дополнительные данные, которые нужны вам для работы (например, ваш внутренний идентификатор заказа). Передаются в виде набора пар «ключ-значение» и возвращаются в ответе от Payvo. Ограничения: максимум 16 ключей, имя ключа не больше 32 символов, значение ключа не больше 512 символов, тип данных — строка в формате UTF-8.

confirmation

object

Данные, необходимые для инициирования выбранного сценария для совершения оплаты заказа пользователем.

confirmation.type

string

Тип выбранного сценария: redirect или qr Подробнее о сценариях подтверждения

confirmation.return_url

string

URL, на который нужно перенаправить пользователя после оплаты заказа. Обязателен при confirmation.type в значении redirect.

payment_method_type

string

Код для оплаты конкретным способом. Вы можете не передавать этот объект в запросе. В этом случае пользователь будет выбирать способ оплаты на стороне Payvo.

payment_method_id

string

Идентификатор сохраненного способа оплаты.

save_payment_method

boolean

Сохранение платежных данных для проведения автоплатежей. Возможные значения:

  • true — сохранить способ оплаты (сохранить платежные данные);

  • false — провести платеж без сохранения способа оплаты.

Доступно только после согласования с менеджером Payo.

receipt

object

Данные о чеке платежа. Обязательно при использовании сервиса Payvo.Чеки.

receipt.customer.email

string

Электронная почта пользователя для отправки чека.

receipt.items

array

Список товаров в заказе.

receipt.items[].description

string

Название товара (от 1 до 128 символов).

receipt.items[].amount

number

Цена товара в копейках.

receipt.items[].vat_code

number

Ставка НДС. Перечень возможных значений.

receipt.items[].quantity

number

Количество товара.

receipt.items[].payment_subject

string

Признак предмета расчета — это то, за что принимается оплата, например товар, услуга. Перечень возможных значений.

receipt.items[].measure

string

Мера количества предмета расчета — единица измерения товара, например штуки, граммы. Перечень возможных значений.

Пример запроса

curl https://api.payvo.ru/public/payments \
  -X POST \
  -H "merchant-id: <ID магазина>" \
  -H "merchant-secret-key: <Секретный ключ>" \
  -H 'Content-Type: application/json' \
  -d '{
        "amount": 1000,
        "payment_method_type": "card",
        "confirmation": {
          "type": "redirect",
          "return_url": "https://www.example.com/return_url"
        },
        "description": "Заказ №1"
      }'

Ответ

В ответ на запрос придет объект платежа в актуальном статусе.

Пример тела ответа

{
  "errors": null,
  "payment": {
    "uuid": "95ce46ab-0f52-42e5-a13b-d05b2dee9562",
    "status": "pending",
    "is_test": 0,
    "amount": 1000,
    "merchant_customer_id": null,
    "description": "Заказ №1",
    "refunded_amount": null,
    "expires_at": "2025-07-12T03:49:39.828+03:00",
    "created_at": "2025-07-12T03:39:37.000+03:00",
    "income_amount": null,
    "confirmation": {
      "type": "redirect",
      "url": "https://my.payvo.ru/payment/95ce46ab-0f52-42e5-a13b-d05b2dee9562",
      "return_url": "https://www.example.com/return_url"
    }
  }
}

Получение информации о платеже

Запрос позволяет получить информацию о текущем состоянии платежа по его уникальному идентификатору.

GET https://api.payvo.ru/public/payments/{payment_uuid}

Параметры запроса

Без параметров.

Пример запроса

curl https://api.payvo.ru/public/payments/{payment_uuid} \
  -H "merchant-id: <ID магазина>" \
  -H "merchant-secret-key: <Секретный ключ>"

Ответ

В ответ на запрос придет объект платежа в актуальном статусе.

Пример ответа

{
  "errors": null,
  "payment": {
    "uuid": "95ce46ab-0f52-42e5-a13b-d05b2dee9562",
    "status": "pending",
    "is_test": 0,
    "amount": 1000,
    "merchant_customer_id": null,
    "description": "Заказ №1",
    "refunded_amount": null,
    "expires_at": "2025-07-12T03:49:39.828+03:00",
    "created_at": "2025-07-12T03:39:37.000+03:00",
    "income_amount": null,
    "confirmation": {
      "type": "redirect",
      "url": "https://my.payvo.ru/payment/95ce46ab-0f52-42e5-a13b-d05b2dee9562",
      "return_url": "https://www.example.com/return_url"
    }
  }
}
PreviousВходящие уведомленияNextВозвраты

Last updated

Was this helpful?