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, and Electronic certificate.
Interaction scenario
- 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.
- If necessary, initiate the user payment confirmation scenario.
- 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:
transfersarray 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:
descriptionparameter 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.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": "Mir", "card_product": { "code": "MCP", "name": "MIR Privilege" }, "issuer_country": "RU", "issuer_name": "T-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.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>:<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": "Mir", "card_product": { "code": "MCP", "name": "MIR Privilege" }, "issuer_country": "RU", "issuer_name": "T-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