Payment acceptance
If you use the YooMoney solution for marketplaces, 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.
 
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 the data about YooMoney stores between which you’re distributing the payments and the amount of your commission (if necessary);
  • 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.
The request can include additional parameters , except for the 
receipt
object. If you use the YooMoney solution for 54-FZ, send the data for generating the receipt in a separate request.
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.merchant-website.com/return_url"
        },
        "description": "Order No. 1: "Company 1" LLC 900 rub., "Company 2" LLC 900 rub.",
        "transfers": [
        {
          "account_id": "123",
          "amount": {
            "value": "5000.00",
            "currency": "RUB"
          },
          "platform_fee_amount": {
            "value": "50.00",
            "currency": "RUB"
          },
          "metadata": {
            "order_id": "a12345"
          }
        },
        {
          "account_id": "456",
          "amount": {
            "value": "12000.00",
            "currency": "RUB"
          },
          "platform_fee_amount": {
             "value": "120.00",
             "currency": "RUB"
          }
        }
       ]
      }'
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 900 rub., "Company 2" LLC 900 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": "100001",
    "gateway_id": "10001"
  },
  "transfers": [
   {
     "account_id": "123",
     "amount": {
        "value": "5000.00",
        "currency": "RUB"
     },
     "platform_fee_amount": {
        "value": "50.00",
        "currency": "RUB"
     },
     "metadata": {
       "order_id": "a12345"
     },
     "status": "waiting_for_capture"
   },
   {
     "account_id": "456",
     "amount": {
       "value": "12000.00",
       "currency": "RUB"
     },
     "platform_fee_amount": {
        "value": "120.00",
        "currency": "RUB"
     },
     "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.
Request for payment capture  must be sent without the 
receipt
object. After the partial capture, you need to create two new receipts: refund receipt of the initial payment (for the full amount) and the payment receipt with the updated information.
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>:<Sekret 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 900 rub., "Company 2" LLC 900 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": "100001",
    "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"
       },
       "metadata": {
         "order_id": "a12345"
       },
       "status": "succeeded"
     },
     {
       "account_id": "456",
       "amount": {
         "value": "9000.00",
         "currency": "RUB"
       },
       "platform_fee_amount": {
         "value": "90.00",
         "currency": "RUB"
       },
       "status": "succeeded"
     }
 ],
 "test": false
}

Do you have any questions or comments regarding the documentation?

We can set up a call and discuss them: we'll help you solve the problem and you'll help us understand what we need to improve. To do that, share your contact information and select the time.
Yes, I'd like to set up a meeting
 
See also
Getting information about seller’s store via APIPayment refunds for marketplacesSending receipts for marketplacesPayments by 54-FZ