Bank card
Specifics
- Payment method type in the API:
bank_card - Confirmation scenario: Redirect
- Payment term: 1 hour
- Holding: 7 days, full and partial payment capture is available
- 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
Integration scenarios
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
Payment on YooMoney’s ready-made page
How it works
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.
The available payment methods:
- By default, only the form for entering the bank card details is displayed.
- For payments made via Android devices, the button for payment via Mir Pay is additionally displayed in the payment form.
- If payment via SberPay is available in your store, the button for payment via this method can be displayed in the payment form.
Contact your YooMoney manager to disable the option of displaying Mir Pay and SberPay.
Standard payment form
Payment form with Mir Pay (on Android)
Example of a payment form
In order to complete integration, add a button that will redirect users to payment to your website. When the user clicks the button, you will receive the link to the ready-made payment page from YooMoney: redirect the user to it. When the user returns back to your website, request payment results from YooMoney and display them.
Payment processing
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
PHP
Python
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
JSON
{ "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 .
If the user enters their bank card details, the
bank_card payment method code will be returned in the payment_method object.Example of a successful payment via bank card
JSON
{ "id": "22c5d173-000f-5000-9000-1bdf241d4651", "status": "succeeded", "paid": true, "amount": { "value": "2.00", "currency": "RUB" }, "description": "Order No. 72", "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": "Mir", "card_product": { "code": "MCP", "name": "MIR Privilege" }, "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 } }, "metadata": {} }
If the user made the payment via Mir Pay, the
bank_card value will be returned in the payment_method object and the mir_pay value is returned will be the card.source parameter.Example of a successful payment via Mir Pay
JSON
{ "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": "Mir", "card_product": { "code": "MCP", "name": "MIR Privilege" }, "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 } } }
If the customer selects SberPay during payment, the
sberbank payment method code will be returned in the payment_method object.Example of a successful payment via SberPay
JSON
{ "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":"sberbank", "id":"22e12f66-000f-5000-8000-18db351245c7", "saved":false, "card":{ "first6":"555555", "last4":"4444", "expiry_year":"2022", "expiry_month":"07", "card_type":"MasterCard" } }, "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 } } }
Done!
Payment with data entry on your side
To use this option, you’ll need to get a PCI DSS compliance certificate.
How it works
In this scenario, you implement the selection of payment method independently. You get the details of the user's bank card on your side. After that, create a payment in YooMoney and wait for the user to confirm the payment.
In order to complete integration, add the following items to your website: a button that redirects users to payment, and the payment form where users can enter their bank card details. After the user enters the details, get a link to the 3-D Secure authentication page from YooMoney and redirect the user to it. When the user returns to your website, request the payment results from YooMoney.
Payment processing
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
PHP
Python
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": "2030", "number": "5555555555554477" } }, "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
JSON
{ "id": "22c5d173-000f-5000-9000-1bdf241d4651", "status": "pending", "amount": { "value": "2.00", "currency": "RUB" }, "description": "Order No. 72", "payment_method": { "type": "bank_card", "id": "22c5d173-000f-5000-9000-1bdf241d4651", "saved": false, "title": "Bank card *4477", "card": { "first6": "555555", "last4": "4477", "expiry_month": "01", "expiry_year": "2030", "card_type": "Mir", "card_product": { "code": "MCP", "name": "MIR Privilege" }, "issuer_country": "RU", "issuer_name": "Sberbank" }, "created_at": "2021-04-12T13:49:33.026Z", "confirmation": { "type": "redirect", "confirmation_url": "<URL for authentication via 3-D Secure>" }, "test": true, "paid": false, "refundable": false, "metadata": {} }
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
JSON
{ "id": "22c5d173-000f-5000-9000-1bdf241d4651", "status": "succeeded", "paid": true, "amount": { "value": "2.00", "currency": "RUB" }, "description": "Order No. 72", "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": "Mir", "card_product": { "code": "MCP", "name": "MIR Privilege" }, "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 } }, "metadata": {} }
Done!
Managing 3-D Secure
First, arrange the conditions with the YooMoney manager.
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.Specific requirements
For some types of payments, you need to specify additional details:
- when you add money to e-wallets, bank accounts, and phone balance: payment receiver's details;
- when you sell airline tickets: information about tickets, flights, and passengers.
See also