Conducting deals
To conduct a Safe deal, you need to create a deal, within which all the transactions will be processed, in YooMoney.
Specifics
There are two scenarios of conducting deals in YooMoney depending on when your marketplace's remuneration is credited to you:
  • Remuneration after the successful payment: you receive your marketplace's remuneration right after the successful payment. If you need to return the payment, you can only refund the customer with the amount intended for the seller.
  • Remuneration after the deal is closed: you receive your marketplace's remuneration after the payout is successfully made when the deal is closed. If you need to return the payment, you can refund the customer with the full payment amount including your marketplace's remuneration.
Every deal expires after a certain period. It's the time period (for example, 90 days) within which you need to accept the payment from the customer and make a payout to the seller. If you do not make a payout or a refund before the deal expires, it will be automatically closed by YooMoney and the payment will be refunded to the customer. The minimum timeframe for a deal is 1 day, and the maximum is 180 days. The validity period of a deal is set when Safe deal is implemented. It's applied to all the deals of your online marketplace in YooMoney.
A deal is closed automatically if certain conditions are fulfilled.
Making a deal
Step 1. Create a deal: send YooMoney a request containing data for authentication, idempotency key (any random value can be used), deal type (
safe_deal
for Safe deal), and information on when YooMoney should credit the remuneration to your marketplace: after the successful payment (
payment_succeeded
) or after the deal is closed (
deal_closed
).
You can specify unique information about the deal in the 
description
parameter. For example, deal’s ID on your marketplace’s side, customer’s or seller’s ID. You can use this parameter to filter required deals in a request for a list of deals.
You can also enter additional information, for example, order’s ID in your system. YooMoney will return it unchanged. This information must be specified in the 
metadata
object as a set of "key-value" pairs (strings in the UTF-8 format).
Example of a request for creating a deal
cURL
PHP
Python
curl https://api.yookassa.ru/v3/deals \
  -X POST \
  -u <Shop ID>:<Secret Key> \
  -H 'Idempotence-Key: <Idempotence Key>' \
  -H 'Content-Type: application/json' \
  -d '{
        "type": "safe_deal",
        "fee_moment": "payment_succeeded",
        "metadata": {
          "order_id": "37"
        },
        "description":"SAFE_DEAL 123554642-2432FF344R"
      }'
YooMoney will return a created deal object  in response to the request.
Example of a created deal object
JSON
{
   "type": "safe_deal",
   "fee_moment": "payment_succeeded",
   "id": "dl-285e5ee7-0022-5000-8000-01516a44b147",
   "balance": {
      "value": "0.00",
      "currency": "RUB"
   },
   "payout_balance": {
      "value": "0.00",
      "currency": "RUB"
   },
   "status": "opened",
   "created_at": "2021-06-18T07:28:39.390497Z",
   "expires_at": "2021-09-16T07:28:39.390513Z",
   "metadata": {
      "order_id": "37"
   },
   "description":"SAFE_DEAL 123554642-2432FF344R",
   "test": false
}
Step 2. Save the deal ID (the
id
parameter value in the created object). You’ll need it for processing transactions within the deal and obtaining deal’s status.
Obtaining information about deals
If you'd like to find out the balance, status, validity period of a deal, or other information about it, send YooMoney a request for information about a deal  and specify the ID of the deal in it.
Example of a request for information about a deal
cURL
PHP
Python
curl https://api.yookassa.ru/v3/deals/dl-285e5ee7-0022-5000-8000-01516a44b147 \
  -X GET \
  -u <Shop ID>:<Secret Key>
YooMoney will send you a deal object  with its current status in response to the request.
Example of a deal object where money has been added to the balance
JSON
{
   "type": "safe_deal",
   "fee_moment": "payment_succeeded",
   "id": "dl-285e5ee7-0022-5000-8000-01516a44b147",
   "balance": {
      "value": "800.00",
      "currency": "RUB"
   },
   "payout_balance": {
      "value": "800.00",
      "currency": "RUB"
   },
   "status": "opened",
   "created_at": "2021-06-18T07:28:39.390497Z",
   "expires_at": "2021-09-16T07:28:39.390513Z",
   "metadata": {
      "order_id": "37"
   },
   "description":"SAFE_DEAL 123554642-2432FF344R",
   "test": false
}
Obtaining a list of deals
If you'd like to get a list of all created deals, send YooMoney a request for a list of deals .
You can add filters regarding the time when the deal was created, date when the deal should be automatically closed, status, and text in deal’s description (the
description
parameter of the deal object ).
You can also add parameters for configuring how results are displayed to the request.
Example of a request for a list of deals
cURL
PHP
Python
curl https://api.yookassa.ru/v3/deals?limit=10&status=opened&full_text_search=123554642 \
  -X GET
  -u <Shop ID>:<Secret Key>
A list of deals  will be returned in response to the request. The list will contain information about deals created over the past 3 years. The list will be sorted by the time when deals were created in descending order.
Example of a list of deals
JSON
{
   "type":"list",
   "items":[
      {
         "type":"safe_deal",
         "fee_moment":"deal_closed",
         "id":"dl-285e5ee7-0022-5000-8000-01536a44b147",
         "balance":{
            "value":"-45.00",
            "currency":"RUB"
         },
         "payout_balance":{
            "value":"0.00",
            "currency":"RUB"
         },
         "status":"closed",
         "created_at":"2021-06-18T07:28:39.390497Z",
         "expires_at":"2021-09-16T07:28:39.390513Z",
         "metadata":{
            "order_id":"37"
         },
         "description":"SAFE_DEAL 123554642-2432FF344R",
         "test":false
      },
      {
         "type":"safe_deal",
         "fee_moment":"payment_succeeded",
         "id":"dl-d68d2fe4-2abb-47e5-8112-32e27f87fb52",
         "balance":{
            "value":"0.00",
            "currency":"RUB"
         },
         "payout_balance":{
            "value":"0.00",
            "currency":"RUB"
         },
         "status":"opened",
         "created_at":"2021-07-29T07:28:39.390497Z",
         "expires_at":"2021-10-29T07:28:39.390513Z",
         "metadata":{
            "order_id":"37"
         },
         "description":"SAFE_DEAL 123554642-6722FF343W",
         "test":false
      }
   ],
   "next_cursor":"dl-28559370-0022-5000-8000-0b65d8e0e06d"
}
Closing a deal
Deals are closed by YooMoney. Reasons for closing a deal:
  • you’ve received the payment from the customer and successfully paid it out to the seller (there’s no money left on deal’s balance);
  • you received the payment from the customer but then returned it (there’s no money left on deal’s balance);
  • deal’s expiration date specified in the 
    expires_at
    parameter has already passed (if there’s money left on deal’s balance, YooMoney will return it to the customer).
Example of a closed deal
JSON
{
   "type": "safe_deal",
   "fee_moment": "payment_succeeded",
   "id": "dl-285e5ee7-0022-5000-8000-01516a44b147",
   "balance": {
      "value": "0.00",
      "currency": "RUB"
   },
   "payout_balance": {
      "value": "0.00",
      "currency": "RUB"
   },
   "status": "closed",
   "created_at": "2021-06-18T07:28:39.390497Z",
   "expires_at": "2021-09-16T07:28:39.390513Z",
   "metadata": {
      "order_id": "37"
   },
   "description":"SAFE_DEAL 123554642-2432FF344R",
   "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
NotificationsBasics of using the APIAccepting payments from customersPayouts to sellersTesting Safe deal