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
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

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.

Two methods are displayed in the payment form on mobile devices on Android: bank card and Mir Pay. If you don't want to the Mir Pay method to be displayed, contact your YooMoney manager.

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
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 .

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"
  },
  "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
    }
  }
}

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

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
    }
  }
}

Payment with data entry on your side

To use this option, you’ll need to get a PCI DSS compliance certificate.

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": "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

JSON
{
  "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": "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
    }
  }
}

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 .

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.

Особые требования

Для некоторых типов платежей нужно передавать дополнительные данные:

при пополнении баланса телефона через вашу систему — номер пополняемого телефона;
при пополнении банковского счета, открытого в вашей системе, — номер пополняемого счета и БИК банка;
при продаже авиабилетов — информацию о билетах, перелетах и пассажирах.