Adding money to phone balance

Only available to those who have MCC 4814 (telecommunication services).

If your system can be used for adding money to mobile phone or landline balance, the phone number where money is being added must also be specified when the payment is made in accordance with NSPK's requirements.

In this article, you can find out how to do it via the YooMoney API when processing regular payments and autopayments.

How it works

If you're adding money to mobile phone or landline balance, you need to specify the phone number where money should be added in your request for creating a payment. The number must be specified for each integration scenario.

You don't have to specify the phone number when confirming or canceling payments.

If you've enabled autopayments, you also need to specify the number when adding money to the balance. Learn more about processing autopayments when money is added to phone balance

Creating a payment

Create a payment : send YooMoney a request with information for authentication, the idempotency key, amount and currency of the payment as well as payment details for the selected method. In addition, specify the phone number where money should be added in the topped_up_phone parameter of the fraud_data object. Example: 79110000000

Example of a request for creating a payment in which the phone number where money should be added is specified (based on a payment via a bank card)

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": "100.00",
          "currency": "RUB"
        },
        "capture": true,
        "payment_method_data": {
          "type": "bank_card"
        },
        "confirmation": {
          "type": "redirect",
          "return_url": "https://www.example.com/return_url"
        },
        "description": "Adding money to mobile phone balance",
        "fraud_data": {
          "topped_up_phone": "79000000000"
        }
      }'

The fraud_data object in the payment object with the phone number is not returned.

Specifying the phone number for autopayments

If you've enabled autopayments, you can save the payment method and use it when adding money to phone balance.

There are two ways to save the payment method:

Only for adding money to phone balance: you can use the saved payment method for adding money to phone balance. The saved payment method can't be used for other transactions.
For other transactions: you can use the saved payment method for any transactions, including adding money to phone balance.

Adding money to phone balance

When creating a payment where the payment method is saved, specify the phone number where money should be added.

Example of a request for creating a payment where the payment method is saved for adding money to phone balance (based on a payment via a bank card)

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": "100.00",
          "currency": "RUB"
        },
        "capture": true,
        "payment_method_data": {
          "type": "bank_card"
        },
        "confirmation": {
          "type": "redirect",
          "return_url": "https://www.example.com/return_url"
        },
        "description": "Adding money to mobile phone balance",
        "save_payment_method": "true",
        "fraud_data": {
          "topped_up_phone": "79000000000"
        }
      }'

You don't have to specify the phone number for subsequent recurring payments. If you specify a different number when repeating the payment, YooMoney will send it to NSPK instead of the number you specified when saving the payment method.

Example of a request for creating a recurring payment via a saved payment method for adding money to phone balance

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": "100.00",
          "currency": "RUB"
        },
        "capture": true,
        "payment_method_id": "<Saved payment method’s ID>",
        "description": "Adding money to mobile phone balance",
        "fraud_data": {
          "topped_up_phone": "79111111111"
        }
      }'

Processing other transactions

When creating a payment where the payment method is saved, don't specify the phone number where money should be added.

Example of a request for creating a payment where the payment method is saved for processing other transaction (based on a payment via a bank card)

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": "100.00",
          "currency": "RUB"
        },
        "payment_method_data": {
          "type": "bank_card"
        },
        "confirmation": {
          "type": "redirect",
          "return_url": "https://www.example.com/return_url"
        },
        "save_payment_method": "true"
      }'

For subsequent recurring payments, only specify the phone number if you're processing a transaction where money is added to phone balance.

Example of a request for creating a recurring payment via a saved payment method for adding money to phone balance

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": "100.00",
          "currency": "RUB"
        },
        "capture": true,
        "payment_method_id": "<Saved payment method’s ID>",
        "description": "Adding money to mobile phone balance",
        "fraud_data": {
          "topped_up_phone": "79000000000"
        }
      }'