Safe deal: conducting deals — Payment acceptance via the YooMoney API

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
}