Для приема оплаты от покупателя вы можете использовать любой способ оплаты и любой сценарий интеграции, включая виджет ЮKassa и мобильные SDK. Вы можете делать автоплатежи и принимать оплату в две стадии. Единственное отличие от стандартного процесса — в запросах на создание и подтверждение платежа нужно передавать данные о сделке, в составе которой проходит операция.
До проведения платежа: ознакомьтесь с общим процессом оплаты, выберите нужный вам сценарий интеграции и создайте сделку.
Чтобы принять оплату от покупателя:
- Отправьте ЮKassa запрос на создание платежа, передайте в нём параметры, необходимые для выбранного сценария проведения платежа, и данные о сделке.
- При необходимости реализуйте сценарий подтверждения платежа покупателем.
- Если вы проводите платеж в две стадии, подтвердите, что вы готовы принять платеж и пополнить баланс сделки.
После успешного завершения оплаты ЮKassa пополнит баланс сделки. Сумма, которую ЮKassa перечисляет на баланс сделки, зависит от момента выплаты вам вознаграждения (
fee_moment
в сделке).Сценарий сделки | fee_moment | Сумма на балансе сделки | Сумма выплаты продавцу |
---|---|---|---|
Вознаграждение после успешного платежа | payment_succeeded | Сумма выплаты продавцу | Сумма на балансе сделки |
Вознаграждение при закрытии сделки | deal_closed | Сумма выплаты продавцу и сумма вашего вознаграждения за вычетом комиссии ЮKassa. | Сумма на балансе сделки за вычетом вашего вознаграждения Пример: сумма платежа — 1 000 рублей, из них вознаграждение продавца — 800 рублей, вознаграждение платформы — 200 рублей. Если комиссия ЮKassa — 4,5% от суммы платежа, то на балансе сделки останется: 800 + (200 — 1 000*0,045) = 955 рублей |
К сделке может быть привязан только один платеж в статусе
pending
, waiting_for_capture
или succeeded
. Если платеж по каким-то причинам перешел в статус canceled
, например покупателю не удалось оплатить или вы сами отменили платеж при оплате в две стадии, то вы можете привязать к сделке еще один платеж.Далее описаны особенности работы с платежами при использовании Безопасной сделки:
- особенности создания платежа;
- особенности подтверждения и отмены платежа при оплате в две стадии.
В конце статьи приведены примеры проведения платежей в одну и две стадии.
Чтобы принять оплату от покупателя, отправьте ЮKassa запрос на создание платежа , передайте в нём данные, которые нужны для оплаты в зависимости от выбранного сценария интеграции, параметр
capture
в соответствии с тем, как вы хотите проводить платеж — в одну или в две стадии, и следующие данные для проведения платежа в рамках сделки:- Объект
amount
с общей суммой платежа за сделку (сумма вознаграждения продавца и вознаграждения вашей платформы). Эту сумму ЮKassa спишет с покупателя. Комиссия ЮKassa за проведение платежа рассчитывается из этой суммы, а взимается из вашего вознаграждения. Сумма платежа должна соответствовать ограничениям на минимальный и максимальный размер платежа. Подробнее о лимитах платежей - Объект
deal
с данными о сделке: идентификатор сделки и массивsettlements
с данными о том, какую сумму нужно выплатить продавцу. Разница между суммой платежа и суммой выплаты должна быть больше эквайринговой комиссии ЮKassa. Сумма выплаты должна соответствовать ограничениям на минимальный и максимальный размер выплаты. Подробнее о лимитах выплат
Пример: товар продавца стоит 800 рублей, проведение сделки на вашей платформе — 200 рублей. Всего покупатель заплатит 1 000 рублей. В этом случае в
amount
нужно передать 1 000 рублей, в deal.settlements.amount
— 800 рублей. Если комиссия ЮKassa 4,5%, вознаграждение ЮKassa составит 45 рублей (1 000*0,045). Свою комиссию ЮKassa взимает из вашего вознаграждения, поэтому в итоге продавец получит 800 рублей, ЮKassa — 45 рублей, а вы — 155 рублей.Пример запроса на проведение платежа в одну стадию
curl https://api.yookassa.ru/v3/payments \ -X POST \ -u <Идентификатор магазина>:<Секретный ключ> \ -H 'Idempotence-Key: <Ключ идемпотентности>' \ -H 'Content-Type: application/json' \ -d '{ "amount": { "value": "1000.00", "currency": "RUB" }, "capture": true, "confirmation": { "type": "redirect", "return_url": "https://example.com/return_url" }, "description": "Оплата заказа №37", "deal": { "id": "dl-285e5ee7-0022-5000-8000-01516a44b147", "settlements": [{ "type": "payout", "amount": { "value": "800.00", "currency": "RUB" } }] }, "metadata": { "order_id": "37" } }'
В ответ ЮKassa отправит вам объект платежа в актуальном статусе.
Пример тела ответа
{ "id": "2855940e-000f-5000-9000-1ef78d597562", "status": "pending", "paid": false, "amount": { "value": "1000.00", "currency": "RUB" }, "confirmation": { "type": "redirect", "confirmation_url": "https://yoomoney.ru/checkout/payments/v2/contract?orderId=2855940e-000f-5000-9000-1ef78d597562" }, "created_at": "2021-06-19T15:25:02.321Z", "deal": { "id": "dl-285e5ee7-0022-5000-8000-01516a44b147", "settlements": [{ "type": "payout", "amount": { "value": "800.00", "currency": "RUB" } }] }, "description": "Оплата заказа №37", "metadata": { "order_id": "37" }, "recipient": { "account_id": "100500", "gateway_id": "100700" }, "refundable": false, "test": false }
При необходимости реализуйте нужный сценарий подтверждения платежа или инициализируйте виджет ЮKassa.
Дождитесь, когда пользователь подтвердит оплату — статус платежа изменится: если принимаете оплату в одну стадию (
capture=true
), платеж перейдет в статус succeeded
, если в две стадии (capture=false
), то в статус waiting_for_capture
. Чтобы узнать статус платежа, периодически запрашивайте информацию о платеже или дождитесь уведомления от ЮKassa.Если вы проводите платеж в одну стадию, ЮKassa пополнит баланс сделки после подтверждения платежа пользователем. Если вы проводите платеж в две стадии, вам нужно дополнительно подтвердить пополнение баланса или отменить платеж.
Если вы проводите платеж в две стадии, то после подтверждения платежа пользователем деньги замораживаются (холдируются) на платежном средстве покупателя. Чтобы перечислить оплату на баланс вашей сделки, вам необходимо списать или отменить платеж.
Чтобы списать всю сумму платежа, отправьте ЮKassa стандартный запрос на подтверждение платежа с пустым телом запроса. Чтобы списать только часть суммы платежа, отправьте ЮKassa запрос на подтверждение платежа с новой суммой платежа и со скорректированной информацией о распределении денег.
Пример запроса на частичное списание суммы платежа
curl https://api.yookassa.ru/v3/payments/{payment_id}/capture \ -X POST \ -u <Идентификатор магазина>:<Секретный ключ> \ -H 'Idempotence-Key: <Ключ идемпотентности>' \ -H 'Content-Type: application/json' \ -d '{ "amount": { "value": "600.00", "currency": "RUB" }, "deal": { "settlements": [ { "type": "payout", "amount": { "value": "480.00", "currency": "RUB" } } ] } }'
Вам нужно подтвердить платеж и пополнение баланса сделки до момента, указанного в параметре
expires_at
объекта платежа. Если вы ничего не сделаете с платежом за этот срок, ЮKassa отменит его, указав причину expired_on_capture
. Чтобы пополнить баланс сделки, создайте новый платеж с тем же идентификатором сделки.Если вы не готовы пополнить баланс, отправьте ЮKassa стандартный запрос на отмену платежа . После отмены платежа баланс сделки останется нулевым. Чтобы пополнить баланс сделки, создайте новый платеж с тем же идентификатором сделки.
Ниже приведены примеры проведения платежа с примерами объекта сделки:
- Пример платежа в одну стадию: если платеж проходит в одну стадию, ЮKassa перечисляет оплату на баланс сделки сразу после успешного подтверждения платежа пользователем.
- Пример платежа в две стадии: если платеж проходит в две стадии, после подтверждения платежа пользователем вам нужно сообщить ЮKassa, что можно перечислить оплату на баланс сделки.
Шаг 1. Создайте платеж с данными для оплаты, с информацией о связанной сделке и с параметром
capture
со значением true
.Пример запроса на создание одностадийного платежа в составе сделки
curl https://api.yookassa.ru/v3/payments \ -X POST \ -u <Идентификатор магазина>:<Секретный ключ> \ -H 'Idempotence-Key: <Ключ идемпотентности>' \ -H 'Content-Type: application/json' \ -d '{ "amount": { "value": "1000.00", "currency": "RUB" }, "capture": true, "confirmation": { "type": "redirect", "return_url": "https://example.com/return_url" }, "description": "Оплата заказа №37", "deal": { "id": "dl-285e5ee7-0022-5000-8000-01516a44b147", "settlements": [{ "type": "payout", "amount": { "value": "800.00", "currency": "RUB" } }] }, "metadata": { "order_id": "37" } }'
Пример тела ответа
{ "id": "2855940e-000f-5000-9000-1ef78d597562", "status": "pending", "paid": false, "amount": { "value": "1000.00", "currency": "RUB" }, "confirmation": { "type": "redirect", "confirmation_url": "https://yoomoney.ru/checkout/payments/v2/contract?orderId=2855940e-000f-5000-9000-1ef78d597562" }, "created_at": "2021-06-19T15:25:02.321Z", "deal": { "id": "dl-285e5ee7-0022-5000-8000-01516a44b147", "settlements": [{ "type": "payout", "amount": { "value": "800.00", "currency": "RUB" } }] }, "description": "Оплата заказа №37", "metadata": { "order_id": "37" }, "recipient": { "account_id": "100500", "gateway_id": "100700" }, "refundable": false, "test": false }
Шаг 2. При необходимости реализуйте нужный сценарий подтверждения или инициализируйте виджет для приема платежей.
Шаг 3. Дождитесь, когда пользователь подтвердит платеж (платеж перейдет в статус
succeeded
). Для этого периодически запрашивайте информацию о платеже или дождитесь уведомления от ЮKassa.Пример объекта платежа в статусе succeeded
{ "id": "2855940e-000f-5000-9000-1ef78d597562", "status": "succeeded", "paid": true, "amount": { "value": "1000.00", "currency": "RUB" }, "authorization_details": { "rrn": "10000000000", "auth_code": "000000", "three_d_secure": { "applied": true } }, "captured_at": "2021-06-19T15:26:17.540Z", "created_at": "2021-06-19T15:25:02.321Z", "deal": { "id": "dl-285e5ee7-0022-5000-8000-01516a44b147", "settlements": [{ "type": "payout", "amount": { "value": "800.00", "currency": "RUB" } }] }, "description": "Оплата заказа №37", "income_amount": { "value": "955", "currency": "RUB" }, "metadata": { "order_id": "37" }, "payment_method": { "type": "bank_card", "id": "2855940e-000f-5000-9000-1ef78d597562", "saved": false, "card": { "first6": "555555", "last4": "4477", "expiry_month": "01", "expiry_year": "2030", "card_type": "MasterCard", "issuer_country": "US" }, "title": "Bank card *4477" }, "recipient": { "account_id": "100500", "gateway_id": "100700" }, "refundable": true, "refunded_amount": { "value": "0.00", "currency": "RUB" }, "test": false }
Когда платеж перейдет в статус
succeeded
, ЮKassa пополнит баланс сделки. Теперь вы можете делать выплату продавцу.Сценарий проведения сделки | Баланс сделки после оплаты | Сумма выплаты продавцу |
---|---|---|
Вознаграждение после успешного платежа
fee_moment=payment_succeeded | На балансе окажется только та сумма, которая нужна для выплаты продавцу. Пример: если сумма платежа 1 000 рублей, сумма выплаты 800 рублей, то на балансе сделки будет 800 рублей. | Сумма на балансе сделки |
Вознаграждение после закрытия сделки
fee_moment=deal_closed | На балансе окажется сумма выплаты продавцу и сумма вашего вознаграждения за вычетом комиссии ЮKassa (значение income_amount из объекта платежа).Пример: если сумма платежа 1 000 рублей, сумма выплаты 800 рублей, то на балансе сделки будет 955 рублей ( 1 000*(1-0,045) ) | Сумма на балансе сделки за вычетом вашего вознаграждения |
Примите оплату, затем спишите ее или отмените платеж.
Шаг 1. Создайте платеж с данными для оплаты, с информацией о связанной сделке и с параметром
capture
со значением false
.Пример запроса на создание двухстадийного платежа в составе сделки
curl https://api.yookassa.ru/v3/payments \ -X POST \ -u <Идентификатор магазина>:<Секретный ключ> \ -H 'Idempotence-Key: <Ключ идемпотентности>' \ -H 'Content-Type: application/json' \ -d '{ "amount": { "value": "1000.00", "currency": "RUB" }, "capture": false, "confirmation": { "type": "redirect", "return_url": "https://example.com/return_url" }, "description": "Оплата заказа №37", "deal": { "id": "dl-285e5ee7-0022-5000-8000-01516a44b147", "settlements": [{ "type": "payout", "amount": { "value": "800.00", "currency": "RUB" } }] }, "metadata": { "order_id": "37" } }'
Пример тела ответа
{ "id": "2855940e-000f-5000-9000-1ef78d597562", "status": "pending", "paid": false, "amount": { "value": "1000.00", "currency": "RUB" }, "confirmation": { "type": "redirect", "confirmation_url": "https://yoomoney.ru/checkout/payments/v2/contract?orderId=2855940e-000f-5000-9000-1ef78d597562" }, "created_at": "2021-06-19T15:25:02.321Z", "deal": { "id": "dl-285e5ee7-0022-5000-8000-01516a44b147", "settlements": [{ "type": "payout", "amount": { "value": "800.00", "currency": "RUB" } }] }, "description": "Оплата заказа №37", "metadata": { "order_id": "37" }, "recipient": { "account_id": "100500", "gateway_id": "100700" }, "refundable": false, "test": false }
Шаг 2. При необходимости реализуйте нужный сценарий подтверждения или инициализируйте виджет для приема платежей.
Шаг 3. Дождитесь, когда пользователь подтвердит платеж (платеж перейдет в статус
waiting_for_capture
). Для этого периодически запрашивайте информацию о платеже или дождитесь уведомления от ЮKassa.Пример объекта платежа в статусе waiting_for_capture
{ "id": "2855940e-000f-5000-9000-1ef78d597562", "status": "waiting_for_capture", "paid": true, "amount": { "value": "1000.00", "currency": "RUB" }, "authorization_details": { "rrn": "10000000000", "auth_code": "000000", "three_d_secure": { "applied": true } }, "created_at": "2021-06-19T15:25:02.321Z", "deal": { "id": "dl-285e5ee7-0022-5000-8000-01516a44b147", "settlements": [{ "type": "payout", "amount": { "value": "800.00", "currency": "RUB" } }] }, "description": "Заказ №37", "expires_at": "2021-06-26T16:12:01.722Z", "metadata": { "order_id": "37" }, "payment_method": { "type": "bank_card", "id": "28559ec4-000f-5000-a000-1e57592b65df", "saved": false, "card": { "first6": "555555", "last4": "4477", "expiry_month": "01", "expiry_year": "2030", "card_type": "MasterCard", "issuer_country": "US" }, "title": "Bank card *4477" }, "recipient": { "account_id": "100500", "gateway_id": "100700" }, "refundable": false, "test": false }
После подтверждения платежа покупателем баланс сделки останется нулевым.
Если вы готовы списать оплату с покупателя и пополнить баланс сделки, отправьте запрос на подтверждение платежа. Если нужно подтвердить часть платежа, добавьте в тело запроса обновленные данные о платеже и распределении денег.
Пример запроса на частичное списание суммы платежа
curl https://api.yookassa.ru/v3/payments/{payment_id}/capture \ -X POST \ -u <Идентификатор магазина>:<Секретный ключ> \ -H 'Idempotence-Key: <Ключ идемпотентности>' \ -H 'Content-Type: application/json' \ -d '{ "amount": { "value": "600.00", "currency": "RUB" }, "deal": { "settlements": [ { "type": "payout", "amount": { "value": "480.00", "currency": "RUB" } } ] } }'
В ответ ЮKassa вернет объект платежа в статусе
succeeded
.Пример объекта платежа в статусе succeeded
{ "id": "2855940e-000f-5000-9000-1ef78d597562", "status": "succeeded", "paid": true, "amount": { "value": "600.00", "currency": "RUB" }, "authorization_details": { "rrn": "10000000000", "auth_code": "000000", "three_d_secure": { "applied": true } }, "captured_at": "2021-06-20T15:26:17.540Z", "created_at": "2021-06-19T15:25:02.321Z", "deal": { "id": "dl-285e5ee7-0022-5000-8000-01516a44b147", "settlements": [{ "type": "payout", "amount": { "value": "480.00", "currency": "RUB" } }] }, "description": "Оплата заказа №37", "income_amount": { "value": "573", "currency": "RUB" }, "metadata": { "order_id": "37" }, "payment_method": { "type": "bank_card", "id": "2855940e-000f-5000-9000-1ef78d597562", "saved": false, "card": { "first6": "555555", "last4": "4477", "expiry_month": "01", "expiry_year": "2030", "card_type": "MasterCard", "issuer_country": "US" }, "title": "Bank card *4477" }, "recipient": { "account_id": "100500", "gateway_id": "100700" }, "refundable": true, "refunded_amount": { "value": "0.00", "currency": "RUB" }, "test": false }
После этого ЮKassa пополнит баланс сделки. Теперь вы можете делать выплату продавцу.
Сценарий проведения сделки | Баланс сделки после оплаты | Сумма выплаты продавцу |
---|---|---|
Вознаграждение после успешного платежа
fee_moment=payment_succeeded | На балансе окажется только та сумма, которая нужна для выплаты продавцу. Пример: если после подтверждения сумма платежа 600 рублей, сумма выплаты 480 рублей, то на балансе сделки будет 480 рублей. | Сумма на балансе сделки |
Вознаграждение после закрытия сделки
fee_moment=deal_closed | На балансе окажется сумма выплаты продавцу и сумма вашего вознаграждения за вычетом комиссии ЮKassa (значение income_amount из объекта платежа).Пример: если после подтверждения сумма платежа 600 рублей, сумма выплаты 480 рублей, то на балансе сделки будет 573 рубля ( 600*(1-0,045) ) | Сумма на балансе сделки за вычетом вашего вознаграждения |
Если вы не готовы списать оплату и пополнить баланс, отправьте ЮKassa запрос на отмену платежа.
Пример запроса на отмену платежа
curl https://api.yookassa.ru/v3/payments/{payment_id}/cancel \ -X POST \ -u <Идентификатор магазина>:<Секретный ключ> \ -H 'Idempotence-Key: <Ключ идемпотентности>' \ -H 'Content-Type: application/json' \ -d '{ }'
В ответ на запрос ЮKassa вернет вам объект платежа в статусе
canceled
.Пример объекта платежа в статусе canceled
{ "id": "2855940e-000f-5000-9000-1ef78d597562", "status": "canceled", "paid": false, "amount": { "value": "1000.00", "currency": "RUB" }, "authorization_details": { "rrn": "10000000000", "auth_code": "000000", "three_d_secure": { "applied": true } }, "created_at": "2021-06-19T15:25:02.321Z", "deal": { "id": "dl-285e5ee7-0022-5000-8000-01516a44b147", "settlements": [{ "type": "payout", "amount": { "value": "800.00", "currency": "RUB" } }] }, "description": "Оплата заказа №37", "metadata": { "order_id": "37" }, "payment_method": { "type": "bank_card", "id": "2855940e-000f-5000-9000-1ef78d597562", "saved": false, "card": { "first6": "555555", "last4": "4477", "expiry_month": "01", "expiry_year": "2030", "card_type": "MasterCard", "issuer_country": "US" }, "title": "Bank card *4477" }, "recipient": { "account_id": "100500", "gateway_id": "100700" }, "refundable": false, "test": false, "cancellation_details": { "party": "merchant", "reason": "canceled_by_merchant" } }
ЮKassa вернет всю оплату покупателю.
После отмены платежа баланс сделки останется нулевым. Чтобы пополнить баланс, создайте новый платеж и подтвердите его.
Основы работы с APIНеуспешные платежиОтправка чеков в Безопасной сделкеВозврат платежа в Безопасной сделкеРеестры платежей и вознаграждений