Safe deal: accepting payments from customers — Payment acceptance via the YooMoney API

Accepting payments from customers

Safe deal provides access to all payment methods except for Faster Payments System (FPS), SberBank Business Online, "Credit purchases" by SberBank, and Electronic certificate.

You can use any integration scenario for accepting money from customers, including the YooMoney widget and mobile SDKs. You can make autopayments and accept payments in two stages. The only difference from the standard process is that information about the deal within which the transaction is processed must be specified in requests for creating and capturing payments.

Before processing a payment: get familiar with the payment process, select the integration scenario, and create a deal.

Interaction scenario

To accept a payment from a customer:

Send a request for creating a payment to YooMoney and specify the parameters required for the selected payment processing scenario and information about the deal in this request.
If necessary, implement the scenario of confirming the payment by the customer.
If you’re processing the payment in two stages, confirm that you’re ready to accept the payment and add money to deal’s balance.

After the payment is made successfully, YooMoney will add money to deal’s balance. The amount credited to deal’s balance by YooMoney depends on when you selected the remuneration to be paid to you (fee_moment in the deal).

Deal scenario	fee_moment	Amount on deal’s balance	Amount of seller’s remuneration
Remuneration after the successful payment	`payment_succeeded`	Amount of seller’s remuneration	Amount on deal’s balance
Remuneration after the deal is closed	`deal_closed`	Amount of seller’s remuneration and the amount of your remuneration with YooMoney’s commission deducted	Amount on deal’s balance with your remuneration amount deducted. Example: payment amount is 1,000 rubles, 800 rubles of which is seller’s remuneration and 200 rubles of which is marketplace’s remuneration. If YooMoney’s commission is 4.5% of the payment amount, there will be 800 + (200 - 1 000*0,045) = 955 rubles left on deal’s balance

Only one payment with the pending, waiting_for_capture, or succeeded status can be linked to a deal. If the payment switched to the canceled status for some reason (for example, if the customer couldn’t pay or if you canceled the payment in case it was supposed to be made in two stages), you can link one more payment to the deal.

Instructions for processing payments when using Safe deal are provided below:

creating a payment;
confirming and canceling a payment when it’s made in two stages.

You can find examples of payments processed in one and two stages at the end of the article.

Creating a payment

To accept a payment from a customer, send a request for creating a payment to YooMoney. This request must contain the information necessary for the payment depending on the selected integration scenario, the capture parameter in accordance with how you’d like to process the payment (in one or two stages), and the following information for processing the payment within the deal:

The amount object with the total payment amount of the deal (the amount of seller’s remuneration and your marketplace’s remuneration). YooMoney will debit this amount from the customer. YooMoney’s commission for processing the payment is calculated based on this amount and debited from your remuneration. The payment amount must stay within the limits on the minimum and maximum payment amount. Learn more about payment limits
The deal object with information about the deal: deal’s ID and the settlements array with information about the amount to be paid out to the seller. The difference between the payment amount and payout amount must be bigger than YooMoney’s acquiring commission. The payout amount must stay within the limits on the minimum and maximum payout amount. Learn more about payout limits

Example: seller’s product costs 800 rubles, and the fee for conducting the deal on your marketplace is 200 rubles. In total, the customer will pay 1,000 rubles. In this case, the value of amount must be 1,000 rubles, and the value of deal.settlements.amount must be 800 rubles. If YooMoney’s commission rate is 4.5%, YooMoney’s remuneration will amount to 45 rubles (1,000*0.045). YooMoney debits its commission from your remuneration, so the outcome will be 800 rubles for the seller, 45 rubles for YooMoney, and 155 rubles for you.

You can specify additional parameters except the receipt object in the request for creating a payment. If you use the YooMoney solution for 54-FZ, specify the information for creating the receipt in a separate request.

Example of a request for processing a payment in one stage

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": "Payment for order No. 37",
        "deal": {
          "id": "dl-285e5ee7-0022-5000-8000-01516a44b147",
          "settlements": [{
            "type": "payout",
            "amount": {
              "value": "800.00",
              "currency": "RUB"
            }
          }]
        },
        "metadata": {
          "order_id": "37"
        }
      }'

YooMoney will send you a payment object in its current status in response to the request.

Example of the response body

JSON
{
  "id": "2855940e-000f-5000-9000-1ef78d597562",
  "status": "pending",
  "paid": false,
  "amount": {
    "value": "1000.00",
    "currency": "RUB"
  },
  "confirmation": {
    "type": "redirect",
    "confirmation_url": "https://yoomoney.ru/checkout/payments/v2/contract?orderId=2855940e-000f-5000-9000-1ef78d597562"
  },
  "created_at": "2021-06-19T15:25:02.321Z",
  "deal": {
    "id": "dl-285e5ee7-0022-5000-8000-01516a44b147",
    "settlements": [{
      "type": "payout",
      "amount": {
        "value": "800.00",
        "currency": "RUB"
      }
    }]
  },
  "description": "Payment for order No. 37",
  "metadata": {
    "order_id": "37"
  },
  "recipient": {
    "account_id": "100500",
    "gateway_id": "100700"
  },
  "refundable": false,
  "test": false
}

If necessary, implement the payment confirmation scenario you need and initialize the YooMoney widget.

Wait until the customer confirms the payment and the payment status changes to succeeded if you’re accepting the payment in one stage (capture=true) or to waiting_for_capture if you’re accepting the payment in two stages (capture=false). To find out the payment status, send periodic requests for information about the payment or wait for a notification from YooMoney.

If you’re processing the payment in one stage, YooMoney will add money to deal’s balance after the payment is confirmed by the user. If you’re processing the payment in two stages, you need to additionally confirm adding money to the balance or cancel the payment.

Confirming and canceling a payment

This is only applicable to two-stage payments.

If you’re processing the payment in two stages, money is frozen (held) in customer’s means of payment after they confirm the payment. To transfer the payment amount to your deal’s balance, you need to debit or cancel the payment.

Debiting the payment

To debit the whole payment amount, send YooMoney a standard request for capturing the payment with an empty request body. To debit only a part of the payment amount, send YooMoney a request for capturing the payment with a new payment amount and corrected information about how money should be distributed.

After the payment is captured, your remuneration must be the same as in the request for creating the payment or lower.

Example of a request for debiting a part of the payment amount

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": "600.00",
          "currency": "RUB"
        },
        "deal": {
          "settlements": [
            {
              "type": "payout",
              "amount": {
                "value": "480.00",
                "currency": "RUB"
              }
            }
          ]
        }
      }'

You need to capture the payment and confirm the addition of money to deal’s balance before the moment specified in the expires_at parameter of the payment object. If you don’t do anything with the payment before that moment, YooMoney will cancel the payment and specify expired_on_capture as the reason. To add money to deal’s balance, create a new payment with the same deal ID.

Payment cancellation initiated by you

If you’re not ready to add money to the balance, send YooMoney a standard request for canceling the payment . After the payment is canceled, deal’s balance will remain at zero. To add money to deal’s balance, create a new payment with the same deal ID.

Examples of processed payments

Examples of processed payments with examples of deal objects are given below:

Example of a one-stage payment: if a payment is made in one stage, YooMoney credits the payment to deal’s balance right after the payment is successfully confirmed by the user.
Example of a two-stage payment: if a payment is made in two stages, after the user confirms the payment, you need to notify YooMoney that the amount can be credited to deal’s balance.

The Smart payment integration scenario is used in the examples. You can use any other scenario by adding deal’s ID and information on how money should be distributed to the request. Learn more about integration scenarios

Example of a one-stage payment

Step 1. Create a payment with the payment details, information about the linked deal, and the capture parameter with the true value.

Example of a request for processing a payment in one stage

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": "Payment for order No. 37",
        "deal": {
          "id": "dl-285e5ee7-0022-5000-8000-01516a44b147",
          "settlements": [{
            "type": "payout",
            "amount": {
              "value": "800.00",
              "currency": "RUB"
            }
          }]
        },
        "metadata": {
          "order_id": "37"
        }
      }'

Example of the response body

JSON
{
  "id": "2855940e-000f-5000-9000-1ef78d597562",
  "status": "pending",
  "paid": false,
  "amount": {
    "value": "1000.00",
    "currency": "RUB"
  },
  "confirmation": {
    "type": "redirect",
    "confirmation_url": "https://yoomoney.ru/checkout/payments/v2/contract?orderId=2855940e-000f-5000-9000-1ef78d597562"
  },
  "created_at": "2021-06-19T15:25:02.321Z",
  "deal": {
    "id": "dl-285e5ee7-0022-5000-8000-01516a44b147",
    "settlements": [{
      "type": "payout",
      "amount": {
        "value": "800.00",
        "currency": "RUB"
      }
    }]
  },
  "description": "Payment for order No. 37",
  "metadata": {
    "order_id": "37"
  },
  "recipient": {
    "account_id": "100500",
    "gateway_id": "100700"
  },
  "refundable": false,
  "test": false
}

Step 2. If necessary, implement the required confirmation scenario or initialize the widget for payment acceptance.

Step 3. Wait until the user confirms the payment (payment status changes to succeeded). Send periodic requests for information about the payment or wait for a notification from YooMoney.

Example of a payment object in the succeeded status

JSON
{
  "id": "2855940e-000f-5000-9000-1ef78d597562",
  "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-19T15:26:17.540Z",
  "created_at": "2021-06-19T15:25:02.321Z",
  "deal": {
    "id": "dl-285e5ee7-0022-5000-8000-01516a44b147",
    "settlements": [{
      "type": "payout",
      "amount": {
        "value": "800.00",
        "currency": "RUB"
      }
    }]
  },
  "description": "Payment for order No. 37",
  "income_amount": {
    "value": "955",
    "currency": "RUB"
  },
  "metadata": {
    "order_id": "37"
  },
  "payment_method": {
    "type": "bank_card",
    "id": "2855940e-000f-5000-9000-1ef78d597562",
    "saved": false,
    "card": {
      "first6": "555555",
      "last4": "4477",
      "expiry_month": "01",
      "expiry_year": "2030",
      "card_type": "Mir",
      "card_product": {
        "code": "MCP",
        "name": "MIR Privilege"
      },
      "issuer_country": "RU"
    },
    "title": "Bank card *4477"
  },
  "recipient": {
    "account_id": "100500",
    "gateway_id": "100700"
  },
  "refundable": true,
  "refunded_amount": {
    "value": "0.00",
    "currency": "RUB"
  },
  "test": false
}

When payment status changes to succeeded, YooMoney will add money to deal’s balance. Now you can make a payout to the seller.

Deal’s balance after the payment

Deal scenario	Deal’s balance after the payment	Amount of seller’s remuneration
Remuneration after the successful payment `fee_moment=payment_succeeded`	Only the amount required for the payout to the seller will be on the balance. Example: if the payment amount is 1,000 rubles and the payout amount is 800 rubles, there will be 800 rubles on deal’s balance.	Amount on deal’s balance
Remuneration after the deal is closed `fee_moment=deal_closed`	The amount of the payout to the seller and the amount of your marketplace's remuneration excluding YooMoney's commission (the value of `income_amount` from the payment object) will be on deal’s balance. Example: if the payment amount is 1,000 rubles and the payout amount is 800 rubles, there will be 955 rubles on deal’s balance (`1,000*(1-0.045)`)	The amount on deal’s balance excluding your marketplace's remuneration

Example of a two-stage payment

Accept the payment, then debit or cancel it.

Accepting the payment

Step 1. Create a payment with the payment details, information about the linked deal, and the capture parameter with the false value.

Example of a request for processing a payment in two stages

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": false,
        "confirmation": {
          "type": "redirect",
          "return_url": "https://example.com/return_url"
        },
        "description": "Payment for order No. 37",
        "deal": {
          "id": "dl-285e5ee7-0022-5000-8000-01516a44b147",
          "settlements": [{
            "type": "payout",
            "amount": {
              "value": "800.00",
              "currency": "RUB"
            }
          }]
        },
        "metadata": {
          "order_id": "37"
        }
      }'

Example of the response body

JSON
{
  "id": "2855940e-000f-5000-9000-1ef78d597562",
  "status": "pending",
  "paid": false,
  "amount": {
    "value": "1000.00",
    "currency": "RUB"
  },
  "confirmation": {
    "type": "redirect",
    "confirmation_url": "https://yoomoney.ru/checkout/payments/v2/contract?orderId=2855940e-000f-5000-9000-1ef78d597562"
  },
  "created_at": "2021-06-19T15:25:02.321Z",
  "deal": {
    "id": "dl-285e5ee7-0022-5000-8000-01516a44b147",
    "settlements": [{
      "type": "payout",
      "amount": {
        "value": "800.00",
        "currency": "RUB"
      }
    }]
  },
  "description": "Payment for order No. 37",
  "metadata": {
    "order_id": "37"
  },
  "recipient": {
    "account_id": "100500",
    "gateway_id": "100700"
  },
  "refundable": false,
  "test": false
}

Step 2. If necessary, implement the required confirmation scenario or initialize the widget for payment acceptance.

Step 3. Wait until the user confirms the payment (payment status changes to waiting_for_capture). Send periodic requests for information about the payment or wait for a notification from YooMoney.

Example of a payment object in the waiting_for_capture status

JSON
{
  "id": "2855940e-000f-5000-9000-1ef78d597562",
  "status": "waiting_for_capture",
  "paid": true,
  "amount": {
    "value": "1000.00",
    "currency": "RUB"
  },
  "authorization_details": {
    "rrn": "10000000000",
    "auth_code": "000000",
    "three_d_secure": {
      "applied": true
    }
  },
  "created_at": "2021-06-19T15:25:02.321Z",
  "deal": {
    "id": "dl-285e5ee7-0022-5000-8000-01516a44b147",
    "settlements": [{
      "type": "payout",
      "amount": {
        "value": "800.00",
        "currency": "RUB"
      }
    }]
  },
  "description": "Order No. 37",
  "expires_at": "2021-06-26T16:12:01.722Z",
  "metadata": {
    "order_id": "37"
  },
  "payment_method": {
    "type": "bank_card",
    "id": "28559ec4-000f-5000-a000-1e57592b65df",
    "saved": false,
    "card": {
      "first6": "555555",
      "last4": "4477",
      "expiry_month": "01",
      "expiry_year": "2030",
      "card_type": "Mir",
      "card_product": {
        "code": "MCP",
        "name": "MIR Privilege"
      },
      "issuer_country": "RU"
    },
    "title": "Bank card *4477"
  },
  "recipient": {
    "account_id": "100500",
    "gateway_id": "100700"
  },
  "refundable": false,
  "test": false
}

Deal’s balance after the payment is confirmed by the user

After the payment is confirmed by the user, deal’s balance will remain at zero.

Debiting the payment

If you're ready to debit the payment from the customer and add the amount to deal’s balance, send a request for capturing the payment.с If only a part of the payment needs to be captured, add updated information about the payment and how it should be distributed to the body of the request.

Example of a request for debiting a part of the payment amount

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": "600.00",
          "currency": "RUB"
        },
        "deal": {
          "settlements": [
            {
              "type": "payout",
              "amount": {
                "value": "480.00",
                "currency": "RUB"
              }
            }
          ]
        }
      }'

YooMoney will return a payment object with the succeeded status in response to the request.

Example of a payment object in the succeeded status

JSON
{
  "id": "2855940e-000f-5000-9000-1ef78d597562",
  "status": "succeeded",
  "paid": true,
  "amount": {
    "value": "600.00",
    "currency": "RUB"
  },
  "authorization_details": {
    "rrn": "10000000000",
    "auth_code": "000000",
    "three_d_secure": {
      "applied": true
    }
  },
  "captured_at": "2021-06-20T15:26:17.540Z",
  "created_at": "2021-06-19T15:25:02.321Z",
  "deal": {
    "id": "dl-285e5ee7-0022-5000-8000-01516a44b147",
    "settlements": [{
      "type": "payout",
      "amount": {
        "value": "480.00",
        "currency": "RUB"
      }
    }]
  },
  "description": "Payment for order No. 37",
  "income_amount": {
    "value": "573",
    "currency": "RUB"
  },
  "metadata": {
    "order_id": "37"
  },
  "payment_method": {
    "type": "bank_card",
    "id": "2855940e-000f-5000-9000-1ef78d597562",
    "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": false
}

After that, YooMoney will add money to deal’s balance. Now you can make the payout to the seller.

Deal’s balance after the payment is captured

Deal scenario	Deal’s balance after the payment	Amount of seller’s remuneration
Remuneration after the successful payment `fee_moment=payment_succeeded`	Only the amount required for the payout to the seller will be on the balance. Example: if the payment amount after the payment is captured is 600 rubles and the payout amount is 480 rubles, there will be 480 rubles on deal’s balance.	Amount on deal’s balance
Remuneration after the deal is closed `fee_moment=deal_closed`	The amount of the payout to the seller and the amount of your marketplace's remuneration excluding YooMoney's commission (the value of `income_amount` from the payment object) will be on deal’s balance. Example: if the payment amount after the payment is captured is 600 rubles and the payout amount is 480 rubles, there will be 573 rubles on deal’s balance (`600*(1-0,045)`)	The amount on deal’s balance excluding your marketplace's remuneration

Canceling payments

If you're not ready to debit the payment and add money to the balance, send YooMoney a request for canceling the payment.

Example of a request for canceling a payment

cURL
PHP
Python
curl https://api.yookassa.ru/v3/payments/{payment_id}/cancel \
  -X POST \
  -u <Shop ID>:<Secret Key> \
  -H 'Idempotence-Key: <Idempotence Key>' \
  -H 'Content-Type: application/json' \
  -d '{
      }'

YooMoney will return a payment object with the canceled status in response to the request.

Example of a payment object with the canceled status

JSON
{
  "id": "2855940e-000f-5000-9000-1ef78d597562",
  "status": "canceled",
  "paid": false,
  "amount": {
    "value": "1000.00",
    "currency": "RUB"
  },
  "authorization_details": {
    "rrn": "10000000000",
    "auth_code": "000000",
    "three_d_secure": {
      "applied": true
    }
  },
  "created_at": "2021-06-19T15:25:02.321Z",
  "deal": {
    "id": "dl-285e5ee7-0022-5000-8000-01516a44b147",
    "settlements": [{
      "type": "payout",
      "amount": {
        "value": "800.00",
        "currency": "RUB"
      }
    }]
  },
  "description": "Payment for order No. 37",
  "metadata": {
    "order_id": "37"
  },
  "payment_method": {
    "type": "bank_card",
    "id": "2855940e-000f-5000-9000-1ef78d597562",
    "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": false,
  "test": false,
  "cancellation_details": {
    "party": "merchant",
    "reason": "canceled_by_merchant"
  }
}

YooMoney will return the full payment amount to the customer.

Deal’s balance after the payment is canceled

After the payment is canceled, deal’s balance will remain at zero. To add money to the balance, create a new payment and capture it.