Bank card
- Payment method type in the API:
bank_card
- Confirmation scenario: Redirect
- Payment term: 1 hour
- Holding: 7 days
- Code in reports: AC
- Refund: yes, full and partial
- Refund processing time: 0 to 3 days (depends on the issuer)
- Recurring payments: yes
- Limits: the minimum payment amount is 1 ruble, and the maximum amount is 350,000 rubles, there are additional restrictions
Ready-made solutions:
- Smart payment
- YooMoney Checkout Widget
- Mobile SDKs for iOS and Android
- Payment form for web with your design — Checkout.js
Manual integration:
- Payment on YooMoney’s ready-made page
- Payment with data input on your side (PCI-DSS)
- 3-D Secure management
In this scenario, after creating a payment, you redirect the user to the YooMoney page where they select the payment method and confirm the payment.
Standard payment form
Payment form with Mir Pay (on Android)
Example of a payment form
Step 1. Create a payment with the
bank_card
type in the payment_method_data
object, and the redirect
type as well as the URL of a page on your side for redirecting the user (in the return_url
parameter) in the confirmation
object.Example of request
curl https://api.yookassa.ru/v3/payments \ -X POST \ -u <Shop ID>:<Secret Key> \ -H 'Idempotence-Key: <Idempotence Key>' \ -H 'Content-Type: application/json' \ -d '{ "amount": { "value": "2.00", "currency": "RUB" }, "payment_method_data": { "type": "bank_card" }, "confirmation": { "type": "redirect", "return_url": "https://www.example.com/return_url" }, "description": "Order No. 72" }'
Step 2. Redirect the user to the YooMoney’s page (you will receive the URL in the
confirmation_url
parameter). On this page, the user will enter the bank card details and confirm the payment.Example of a created payment object
{ "id": "22c5d173-000f-5000-9000-1bdf241d4651", "status": "pending", "paid": false, "amount": { "value": "2.00", "currency": "RUB" }, "confirmation": { "type": "redirect", "return_url": "https://www.example.com/return_url", "confirmation_url": "https://yoomoney.ru/payments/external/confirmation?orderId=22c5d173-000f-5000-9000-1bdf241d4651" }, "created_at": "2021-04-12T13:59:33.681Z", "description": "Order No. 72", "metadata": {}, "payment_method": { "type": "bank_card", "id": "22c5d173-000f-5000-9000-1bdf241d4651", "saved": false }, "recipient": { "account_id": "100500", "gateway_id": "100700" }, "refundable": false, "test": false }
If a payment doesn't go through (for example, if there wasn't enough money), YooMoney will display an error message to the user and prompt them to try again.
Step 3. Wait for the payment to be successfully completed: you will receive a notification from YooMoney, or you can send periodic requests for payment information .
Example of a successful payment via bank card
{ "id": "22c5d173-000f-5000-9000-1bdf241d4651", "status": "succeeded", "paid": true, "amount": { "value": "2.00", "currency": "RUB" }, "captured_at": "2021-04-12T13:59:33.681Z", "created_at": "2021-04-12T13:49:33.026Z", "income_amount": { "value": "2.00", "currency": "RUB" }, "payment_method": { "type": "bank_card", "id": "22e12f66-000f-5000-8000-18db351245c7", "saved": false, "card": { "first6": "555555", "last4": "4444", "expiry_month": "01", "expiry_year": "2030", "card_type": "MasterCard", "issuer_country": "RU", "issuer_name": "Sberbank" } }, "recipient": { "account_id": "100500", "gateway_id": "100700" }, "refundable": true, "refunded_amount": { "value": "0.00", "currency": "RUB" }, "test": false, "authorization_details": { "rrn": "10000000000", "auth_code": "000000", "three_d_secure": { "applied": false } } }
If the user processed the payment via Mir Pay, the
mir_pay
value is returned in the source
parameter of the payment_method.card
object.Example of a successful payment via Mir Pay
{ "id": "22e12f66-000f-5000-8000-18db351245c7", "status": "succeeded", "paid": true, "amount": { "value": "2.00", "currency": "RUB" }, "captured_at": "2021-04-12T13:59:33.681Z", "created_at": "2021-04-12T13:49:33.026Z", "income_amount": { "value": "2.00", "currency": "RUB" }, "payment_method": { "type": "bank_card", "id": "22e12f66-000f-5000-8000-18db351245c7", "saved": false, "card": { "first6": "555555", "last4": "4444", "expiry_month": "01", "expiry_year": "2030", "card_type": "MasterCard", "issuer_country": "RU", "issuer_name": "Sberbank", "source": "mir_pay" } }, "recipient": { "account_id": "100500", "gateway_id": "100700" }, "refundable": true, "refunded_amount": { "value": "0.00", "currency": "RUB" }, "test": false, "authorization_details": { "rrn": "10000000000", "auth_code": "000000", "three_d_secure": { "applied": false } } }
Step 1. Create a payment with the
bank_card
type and the card
object (with the bank card details) in the payment_method_data
object, and the redirect
type as well as the URL of a page on your side for redirecting the user (in the return_url
parameter) in the confirmation
object.Example of request
curl https://api.yookassa.ru/v3/payments \ -X POST \ -u <Shop ID>:<Secret Key> \ -H 'Idempotence-Key: <Idempotence Key>' \ -H 'Content-Type: application/json' \ -d '{ "amount": { "value": "2.00", "currency": "RUB" }, "payment_method_data": { "type": "bank_card", "card": { "cardholder": "MR CARDHOLDER", "csc": "213", "expiry_month": "01", "expiry_year": "2020", "number": "5469550010800081" } }, "confirmation": { "type": "redirect", "return_url": "https://www.example.com/return_url" }, "description": "Order No. 72" }'
Step 2. Redirect the user to the 3-D Secure authentication page (you will receive the URL in the
confirmation_url
parameter).Example of a created payment object
{ "id": "22c5d173-000f-5000-9000-1bdf241d4651", "status": "succeeded", "paid": true, "amount": { "value": "2.00", "currency": "RUB" }, "captured_at": "2021-04-12T13:59:33.681Z", "created_at": "2021-04-12T13:49:33.026Z", "income_amount": { "value": "2.00", "currency": "RUB" }, "payment_method": { "type": "bank_card", "id": "22e12f66-000f-5000-8000-18db351245c7", "saved": false, "card": { "first6": "555555", "last4": "4444", "expiry_month": "01", "expiry_year": "2030", "card_type": "MasterCard", "issuer_country": "RU", "issuer_name": "Sberbank" } }, "recipient": { "account_id": "100500", "gateway_id": "100700" }, "refundable": true, "refunded_amount": { "value": "0.00", "currency": "RUB" }, "test": false, "authorization_details": { "rrn": "10000000000", "auth_code": "000000", "three_d_secure": { "applied": false } } }
Step 3. Wait for the payment to be successfully completed: you will receive a notification from YooMoney, or you can send periodic requests for payment information .
You can disable 3-D Secure, so you won’t need to send the
confirmation
object. If you want to request the user to be authenticated via 3-D Secure, set the redirect
type in the confirmation
object, specify the URL of the page on your side the user will be redirected to after completing the payment (in the return_url
parameter), and send the enforce
parameter with the true
value.Для некоторых типов платежей нужно передавать дополнительные данные:
- при пополнении баланса телефона через вашу систему — номер пополняемого телефона;
- при пополнении банковского счета, открытого в вашей системе, — номер пополняемого счета и БИК банка;
- при продаже авиабилетов — информацию о билетах, перелетах и пассажирах.
See also