YooMoney API
Guides
Old versions of the API
Help
Sign up for YooMoney
Payment acceptance
If you use Split payments, you can accept payments for products from various stores in one transaction. You can also charge stores a commission for sold goods and services: send one general request for creating a payment to YooMoney with additional information detailing the distribution of funds between stores and the amount of commission to be charged from each of them.
All payment methods are available except for Faster Payments System (FPS), SberBank Business Online, “Credit purchases” by SberBank, Installments.
 
Interaction scenario
  1. Send a payment creation request to YooMoney and include all parameters required for the distribution of funds between stores and the amount of commission to be charged.
  2. If necessary, initiate the user payment confirmation scenario.
  3. If you process payments in two stages, confirm you’re ready to accept the payment. On this stage, you can still change the commission amount or cancel it altogether.
After the successful payment, YooMoney will make the settlements with the stores where the products were bought.
Payment creation
To accept a user payment, send a payment creation  request to YooMoney. In the request, specify the payment amount in the amount parameter, data for payment via the selected method, as well as the data for payment distribution between stores in two formats:
  • for settlements with sellers: transfers array with information about the YooMoney stores between which you're distributing the payments, the amount of your commission (if necessary), and additional information, which the seller will see in the YooMoney Merchant Profile;
  • for displaying to users during the payment process: description parameter with the information about sellers that YooMoney will make the settlements with. For each seller, specify their legal name and the amount of the settlement, for example: "Company 1” LLC 900 rub. Additionally, you can include any other information to be displayed to the user during payment in this parameter, for example the order number.
If necessary, you can send additional information for each store, for example, order number or the list of products. YooMoney will return them without changes. The information must be sent in the metadata object of the transfers array as a “key-value” pair.
Example of request for payment creation
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": "17000.00",
          "currency": "RUB"
        },
        "capture": false,
        "confirmation": {
          "type": "redirect",
          "return_url": "https://www.example.com/return_url"
        },
        "description": "Order No. 1: "Company 1" LLC 5000 rub., "Company 2" LLC 12000 rub.",
        "transfers": [
        {
          "account_id": "123",
          "amount": {
            "value": "5000.00",
            "currency": "RUB"
          },
          "platform_fee_amount": {
            "value": "50.00",
            "currency": "RUB"
          },
          "description": "Marketplace order No. 1",
          "metadata": {
            "order_id": "1"
          }
        },
        {
          "account_id": "456",
          "amount": {
            "value": "12000.00",
            "currency": "RUB"
          },
          "platform_fee_amount": {
             "value": "120.00",
             "currency": "RUB"
          },
          "description": "Marketplace order No. 1",
          "metadata": {
            "order_id": "1"
          }
        }
       ]
      }'
In response, YooMoney will send you the payment object  in its current status.
Example of payment object
JSON
{
  "id": "24e89cb0-000f-5000-9000-1de77fa0d6df",
  "status": "waiting_for_capture",
  "paid": true,
  "amount": {
    "value": "17000.00",
    "currency": "RUB"
  },
  "authorization_details": {
    "rrn": "10000000000",
    "auth_code": "000000",
    "three_d_secure": {
      "applied": true
    }
  },
  "created_at": "2019-08-16T10:44:12.717Z",
  "description": "Order No. 1: "Company 1" LLC 5000 rub., "Company 2" LLC 12000 rub.",
  "expires_at": "2019-08-23T10:44:14.664Z",
  "metadata": {
  },
  "payment_method": {
    "type": "bank_card",
    "id": "24e89cb0-000f-5000-9000-1de77fa0d6df",
    "saved": false,
    "card": {
      "first6": "666666",
      "last4": "4444",
      "expiry_month": "06",
      "expiry_year": "2022",
      "card_type": "MasterCard",
      "issuer_country": "RU",
      "issuer_name": "Tinkoff Bank"
    },
    "title": "Bank card *4444"
   },
  "recipient": {
    "account_id": "100500",
    "gateway_id": "10001"
  },
  "transfers": [
   {
     "account_id": "123",
     "amount": {
        "value": "5000.00",
        "currency": "RUB"
     },
     "platform_fee_amount": {
        "value": "50.00",
        "currency": "RUB"
     },
     "description": "Marketplace order No. 1",
     "metadata": {
       "order_id": "1"
     },
     "status": "waiting_for_capture"
   },
   {
     "account_id": "456",
     "amount": {
       "value": "12000.00",
       "currency": "RUB"
     },
     "platform_fee_amount": {
        "value": "120.00",
        "currency": "RUB"
     },
     "description": "Marketplace order No. 1",
     "metadata": {
       "order_id": "1"
     },
     "status": "waiting_for_capture"
    }
   ],
  "refundable": false,
  "test": false
 }
Payment capture
If you process payments in two stages, you will need to capture it by sending a request for capturing  to YooMoney.
If you’re capturing the entire payment, send a request without parameters as YooMoney already has the data for the distribution of funds between stores and the commission amount. If you want to capture the entire payment but change the commission amount, send a request for partial capture with the new commission amount.
Example of request for a full capture
cURL
PHP
Python
curl https://api.yookassa.ru/v3/payments/{payment_id}/capture \
  -X POST \
  -u <Shop ID>:<Secret Key> \
  -H 'Idempotence-Key: <Idempotence Key>' \
  -H 'Content-Type: application/json'
If you’re capturing a part of the payment (for example, if the store ran out of one or several products) or changing the commission amount, send the transfers object with the updated information for distribution of funds in the request to YooMoney: the stores to send money to, the amounts to be sent, and the commission amounts to be charged. You don’t need to send the metadata object: it can’t be changed during payment capture.
If, for some reason, you decide not to charge the commission at the capture stage, send the platform_fee_amount.value parameter with the 0 value in the request.
Example of request for partial payment capture
cURL
PHP
Python
curl https://api.yookassa.ru/v3/payments/{payment_id}/capture \
  -X POST \
  -u <Shop ID>:<Secret Key> \
  -H 'Idempotence-Key: <Idempotence Key>' \
  -H 'Content-Type: application/json' \
  -d '{
         "amount": {
           "value": "11000.00",
           "currency": "RUB"
         },
         "transfers": [
         {
           "account_id": "123",
           "amount": {
             "value": "2000.00",
             "currency": "RUB"
           },
           "platform_fee_amount": {
              "value": "20.00",
              "currency": "RUB"
          }
         },
         {
           "account_id": "456",
           "amount": {
             "value": "9000.00",
             "currency": "RUB"
           },
           "platform_fee_amount": {
              "value": "90.00",
              "currency": "RUB"
           }
         }
        ]
      }'
After successful capture, the payment status will change to succeeded. To learn the current status of the payment, you can request payment information  or configure notifications from YooMoney.
Example of payment object
JSON
{
  "id": "24e89cb0-000f-5000-9000-1de77fa0d6df",
  "status": "succeeded",
  "paid": true,
  "amount": {
    "value": "11000.00",
    "currency": "RUB"
  },
  "authorization_details": {
    "rrn": "10000000000",
    "auth_code": "000000",
    "three_d_secure": {
      "applied": true
    }
  },
  "captured_at": "2019-08-16T12:23:12.849Z",
  "created_at": "2019-08-16T10:44:12.717Z",
  "description": "Order No. 1: "Company 1" LLC 5000 rub., "Company 2" LLC 12000 rub.",
  "metadata": {
  },
  "payment_method": {
    "type": "bank_card",
    "id": "24e89cb0-000f-5000-9000-1de77fa0d6df",
    "saved": false,
    "card": {
      "first6": "555555",
      "last4": "4444",
      "expiry_month": "06",
      "expiry_year": "2022",
      "card_type": "MasterCard",
      "issuer_country": "RU",
      "issuer_name": "Tinkoff Bank"
    },
    "title": "Bank card *4444"
  },
  "recipient": {
    "account_id": "100500",
    "gateway_id": "10001"
  },
  "refundable": true,
  "refunded_amount": {
    "value": "0.00",
    "currency": "RUB"
  },
  "transfers": [
    {
       "account_id": "123",
       "amount": {
         "value": "2000.00",
         "currency": "RUB"
       },
       "platform_fee_amount": {
         "value": "20.00",
         "currency": "RUB"
       },
       "description": "Marketplace order No. 1",
       "metadata": {
         "order_id": "1"
       },
       "status": "succeeded"
     },
     {
       "account_id": "456",
       "amount": {
         "value": "9000.00",
         "currency": "RUB"
       },
       "platform_fee_amount": {
         "value": "90.00",
         "currency": "RUB"
       },
       "description": "Marketplace order No. 1",
       "metadata": {
         "order_id": "1"
       },
       "status": "succeeded"
     }
 ],
 "test": false
}
See also