Safe deal: Quick start based on a freelancing marketplace — Payment acceptance via the YooMoney API

Quick start — Classified ads platform

In this article, you'll learn how to process your first Safe deal in YooMoney. In this scenario, the platform is going to receive the remuneration when the deal is closed.

This article describes the simplest integration scenario. You can find descriptions of all the features of YooMoney and full instructions regarding the integration in the integration section.

Description of the scenario

A classified ads platform is a website where some users can publish a post about products on sale and other users can respond to these posts. Users don't sell products all the time but only when they need to. The platform receives the remuneration only when the deal is successfully closed.

A customer is looking to buy a product for 800 rubles on the platform. If everything goes well, the platform is going to receive 200 rubles for processing the deal. The seller would like to receive the payout to their bank card.

To process a Safe deal:

Create a deal
Accept the payment from the customer
Obtain the banking details for the payout
Make the payout to the seller

Step 1. Create a deal

Create a deal, within which you're going to accept the payment from the customer and make the payout to the seller. To do it, send YooMoney a request with the data for authentication, idempotency key (any random value can be used) and deal type (safe_deal for Safe deal) and specify in the request that platform's remuneration should be credited when the deal is closed (fee_moment=deal_closed).

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": "deal_closed",
        "metadata": {
          "order_id": "37"
        },
        "description": "SAFE_DEAL 123554642-2432FF344R"
      }'

YooMoney will return a deal payout object in response to the request.

Example of a created deal object

JSON
{
  "type": "safe_deal",
  "fee_moment": "deal_closed",
  "id": "dl-28646d17-0022-5000-8000-01e154d1324b",
  "balance": {
    "value": "0.00",
    "currency": "RUB"
  },
  "payout_balance": {
    "value": "0.00",
    "currency": "RUB"
  },
  "status": "opened",
  "created_at": "2021-06-22T21:42:47.672298Z",
  "expires_at": "2021-06-24T21:42:47.672321Z",
  "metadata": {
    "order_id": "37"
  },
  "description": "SAFE_DEAL 123554642-2432FF344R",
  "test": true
}

Save the deal ID (value of the id parameter in the created object). You'll need it when processing transactions within the deal and receiving information about the deal.

Step 2. Receive the payment from the customer

Process one payment, within which the customer pays off all the expenses for processing the Safe deal at once.

Example: seller's product costs 800 rubles, and processing the deal on your platform costs 200 rubles. In total, the customer pays 1,000 rubles. YooMoney will use this amount to calculate its remuneration for processing the payment. For example, if the commission rate is 4.5%, YooMoney's remuneration is going to amount to 45 rubles. YooMoney deducts its commission from your remuneration, so ultimately the seller is going to receive 800 rubles, YooMoney is going to receive 45 rubles, and you're going to receive 155 rubles.

1. Create a payment

Send YooMoney a request with the data for authentication, idempotency key, and banking details for processing the payment within the deal:

In the amount object, specify the total payment amount to be debited from the customer by YooMoney (the amount of seller's remuneration and your platform's remuneration). YooMoney's commission for processing the payment is calculated based on this amount and deducted from your remuneration.
Specify the details of the deal in the deal object: deal ID and the settlements array with information about the amount to be paid out to the seller. The difference between the payment amount and the payout amount must be greater than YooMoney's acquiring commission.

Example of a request for creating a payment within a deal

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": "1000.00",
          "currency": "RUB"
        },
        "capture": true,
        "confirmation": {
          "type": "redirect",
          "return_url": "https://example.com/return_url"
        },
        "description": "Order No. 37",
        "deal": {
          "id": "dl-28646d17-0022-5000-8000-01e154d1324b",
          "settlements": [{
            "type": "payout",
            "amount": {
              "value": "800.00",
              "currency": "RUB"
            }
          }]
        },
        "metadata": {
          "order_id": "37"
        }
      }'

In response to the request, YooMoney is going to return the created payment object with the pending status. It means that the payment has been created, but the customer hasn't confirmed it yet.

Example of the response body

JSON
{
  "id": "28646d50-000f-5000-a000-1fe4f81e5e88",
  "status": "pending",
  "paid": false,
  "amount": {
    "value": "1000.00",
    "currency": "RUB"
  },
  "confirmation": {
    "type": "redirect",
    "confirmation_url": "https://yoomoney.ru/checkout/payments/v2/contract?orderId=28646d50-000f-5000-a000-1fe4f81e5e88"
  },
  "created_at": "2021-06-22T21:43:44.794Z",
  "deal": {
    "id": "dl-28646d17-0022-5000-8000-01e154d1324b",
    "settlements": [{
      "type": "payout",
      "amount": {
        "value": "800.00",
        "currency": "RUB"
      }
    }]
  },
  "description": "Order No. 37",
  "metadata": {
    "order_id": "37"
  },
  "recipient": {
    "account_id": "100500",
    "gateway_id": "100700"
  },
  "refundable": false,
  "test": true
}

Save the payment ID (value of the id parameter in the created object). You'll need it to receive information about the payment, process refunds, and submitting data for receipts (if necessary).

Save confirmation_url: you'll need it for the payment.

2. Implement the confirmation scenario you need

Redirect the customer to confirmation_url, so they could confirm the payment.

At this point, if you're processing a test deal, follow the link from confirmation_url, enter the banking details for the payment, and confirm the payment. If you're processing a payment for the demo online platform, use the following card details for the payment:

card number — 5555555555554477
expiration date — 01/30 (or any other date greater than the current one)
CVC — 123 (or any other three digits)
code for 3-D Secure authentication — 123 (or any other three digits)

3. Wait until the customer confirms the payment

A payment can be considered to be successful once its status changes to succeeded. If the customer changes their mind or if something goes wrong, payment's status will change to canceled.

To find out the status of the payment, subscribe to notifications from YooMoney. You can also track the status by sending requests for information about the payment as often as you want (for example, after the user came back to return_url). To do it, you need the payment ID.

Example of a payment with the succeeded status

JSON
{
  "id": "28646d50-000f-5000-a000-1fe4f81e5e88",
  "status": "succeeded",
  "paid": true,
  "amount": {
    "value": "1000.00",
    "currency": "RUB"
  },
  "authorization_details": {
    "rrn": "10000000000",
    "auth_code": "000000",
    "three_d_secure": {
      "applied": true
    }
  },
  "captured_at": "2021-06-22T21:44:55.506Z",
  "created_at": "2021-06-22T21:43:44.794Z",
  "deal": {
    "id": "dl-28646d17-0022-5000-8000-01e154d1324b",
    "settlements": [{
      "type": "payout",
      "amount": {
        "value": "800.00",
        "currency": "RUB"
      }
    }]
  },
  "description": "Order No. 37",
  "income_amount": {
    "value": "955.00",
    "currency": "RUB"
  },
  "metadata": {
    "order_id": "37"
  },
  "payment_method": {
    "type": "bank_card",
    "id": "28646d50-000f-5000-a000-1fe4f81e5e88",
    "saved": false,
    "card": {
      "first6": "555555",
      "last4": "4477",
      "expiry_month": "01",
      "expiry_year": "2030",
      "card_type": "MasterCard",
      "issuer_country": "US"
    },
    "title": "Bank card *4477"
  },
  "recipient": {
    "account_id": "100500",
    "gateway_id": "100700"
  },
  "refundable": true,
  "refunded_amount": {
    "value": "0.00",
    "currency": "RUB"
  },
  "test": true
}

Once the payment status changes to succeeded, YooMoney is going to add money to the deal balance. The total payment amount with YooMoney's acquiring commission deducted will be added to the deal balance, and amount of seller's remuneration will be specified in the payout_balance parameter. At this point, you can make the payout to the seller.!

Example of a deal after money is added to its balance

JSON
{
  "type": "safe_deal",
  "fee_moment": "deal_closed",
  "id": "dl-28646d17-0022-5000-8000-01e154d1324b",
  "balance": {
    "value": "955.00",
    "currency": "RUB"
  },
  "payout_balance": {
    "value": "800.00",
    "currency": "RUB"
  },
  "status": "opened",
  "created_at": "2021-06-22T21:42:47.672298Z",
  "expires_at": "2021-06-24T21:42:47.672321Z",
  "metadata": {
    "order_id": "37"
  },
  "description": "SAFE_DEAL 123554642-2432FF344R",
  "test": true
}

Step 3. Obtain the banking details for the payout

To process the payout, you need to get seller's bank card details. Obtaining and storing the card number is regulated by the PCI DSS standard, therefore YooMoney stores this data on its end.

To obtain the banking details for the payout, place the widget for that on your website and display the form for entering the banking details to the seller. When the seller enters their bank card details, the widget will return you the synonym of the bank card: card's ID in YooMoney's system, which must be used for processing payouts, as well as data for displaying the card in the interface.

At this point, if you're processing a test deal, copy the code below and save it to an HTML file. Open this page in a browser, enter the bank card details for the payout, then open the console and save the synonym you received for processing the payout. The same bank card synonym can be used multiple times and for multiple different payouts.

Example of a code

HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html>
 <head>
  <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
  <title>Obtaining bank card details using the YooMoney Checkout Widget</title>

  <!--Library implementation-->
  <script src="https://static.yoomoney.ru/payouts-data-widget-front/widget.js"></script>
 </head>
 <body>
  The payment form for bank card details will be displayed below.

  <!--Container in which the payment form will be displayed-->
  <div id="payout-form"></div>

  <script>
  //Widget initialization. All parameters are required.
  const payoutsData = new window.PayoutsData({
    successCallback(data) {
      //Processing the response with card’s token
      console.log(data)
    },
    errorCallback(error) {
      //Processing of initialization errors
      console.log(error)
    }
  });

  //Display of payment form in the container
  payoutsData.render('payout-form')
    //After the payment form is displayed, the render method returns Promise (optional).
    .then(() => {
      //Code that must be executed after the payment form is displayed.
  });
  </script>
 </body>
</html>

Step 4. Make the payout to the seller

Process the payout using the bank card synonym you received.

1. Create a payout

Send YooMoney a request with the data for authentication, idempotency key, and banking details for the payout to the bank card:

specify the amount to be paid out to the seller in the amount object;
specify the synonym of seller's bank card in the payout_token parameter;
specify the deal ID in the deal object.

Example of a request for creating a deal

cURL
PHP
Python
curl https://api.yookassa.ru/v3/payouts \
  -X POST \
  -u <Shop ID>:<Secret Key> \
  -H 'Idempotence-Key: <Idempotence Key>' \
  -H 'Content-Type: application/json' \
  -d '{
        "amount": {
          "value": "800.00",
          "currency": "RUB"
        },
        "payout_token": "<Bank card synonym>",
        "description": "Payout for order No. 37",
        "metadata": {
          "order_id": "37"
        },
        "deal": {
          "id": "dl-28646d17-0022-5000-8000-01e154d1324b"
        }
      }'

YooMoney will return a created payout object in response to the request.

Example of a created payout object

JSON
{
  "id": "po-28646e56-0003-5000-a000-07be7831c61d",
  "amount": {
    "value": "800.00",
    "currency": "RUB"
  },
  "status": "pending",
  "payout_destination": {
    "type": "bank_card",
    "card": {
      "first6": "510621",
      "last4": "1882",
      "card_type": "MasterCard",
      "issuer_country": "RU",
      "issuer_name": "YOOMONEY NBCO LLC"
    }
  },
  "description": "Payout for order No. 37",
  "created_at": "2021-06-22T21:48:06.819Z",
  "deal": {
    "id": "dl-28646d17-0022-5000-8000-01e154d1324b"
  },
  "metadata": {
    "order_id": "37"
  },
  "test": true
}

2. Wait until the confirmation that the payout has been made successfully

Wait until the payout is approved by recipient's bank and YooMoney changes payout's status to succeeded. If necessary, send YooMoney periodic requests for information about the payout.

Example of a successfully performed payout

JSON
{
  "id": "po-28646e56-0003-5000-a000-07be7831c61d",
  "amount": {
    "value": "800.00",
    "currency": "RUB"
  },
  "status": "succeeded",
  "payout_destination": {
    "type": "bank_card",
    "card": {
      "first6": "510621",
      "last4": "1882",
      "card_type": "MasterCard",
      "issuer_country": "RU",
      "issuer_name": "YOOMONEY NBCO LLC"
    }
  },
  "description": "Payout for order No. 37",
  "created_at": "2021-06-22T21:48:06.819Z",
  "deal": {
    "id": "dl-28646d17-0022-5000-8000-01e154d1324b"
  },
  "metadata": {
    "order_id": "37"
  },
  "test": true
}

After the payout is processed successfully, YooMoney will automatically pay out platform's remuneration and close the deal.

Example of a closed deal

JSON
{
  "type": "safe_deal",
  "fee_moment": "deal_closed",
  "id": "dl-28646d17-0022-5000-8000-01e154d1324b",
  "balance": {
    "value": "0.00",
    "currency": "RUB"
  },
  "payout_balance": {
    "value": "0.00",
    "currency": "RUB"
  },
  "status": "closed",
  "created_at": "2021-06-22T21:42:47.672298Z",
  "expires_at": "2021-06-24T21:42:47.672321Z",
  "metadata": {
    "order_id": "37"
  },
  "description": "SAFE_DEAL 123554642-2432FF344R",
  "test": true
}

That's it! You've processed your first Safe deal in YooMoney.

Further steps

Learn more about the basics of the API. If you processed the deal for the demo online platform, get an ID and secret key for the real online platform.

Learn more about the details of implementing Safe deal:

General integration scenario: what other steps can there be besides the ones described in this article, which of the steps must be performed strictly in order and which don't have to be.
Deal conditions: additional parameters which can be specified in the request, conditions of closing the deal.
Accepting the payment from the customer: available features and options, differences from the standard payment process, examples of payments processed within deals.
Refunds to customers: differences between different scenarios of processing deals, things to consider when making a refund.
Submitting data for receipts (if you use YooMoney's solution for 54-FZ): when to generate receipts, what information is required and how to submit it.
Payouts to sellers: features, options, and restrictions, how to process a payout, possible reason for canceling a payout.

Select the features of YooMoney that you need and follow the instructions to complete the integration.