Bank card — Payment acceptance via the YooMoney API

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.

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-13T09:27:09.960Z",
   "created_at":"2021-04-13T09:25:13.087Z",
   "description":"Order No. 72",
   "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.