Accepting payments from customers
You can use any payment method and integration scenario, including the YooMoney widget and mobile SDKs, for accepting money from customers. 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:
  1. 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.
  2. If necessary, implement the scenario of confirming the payment by the customer.
  3. 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 scenariofee_momentAmount on deal’s balanceAmount of seller’s remuneration
Remuneration after the successful payment
payment_succeeded
Amount of seller’s remunerationAmount 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:
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": "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
}
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 scenarioDeal’s balance after the paymentAmount 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 <Идентификатор магазина>:<Секретный ключ> \
  -H '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": "Payment for 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": "MasterCard",
            "issuer_country": "US"
        },
        "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 scenarioDeal’s balance after the paymentAmount 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.
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.

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
Basics of using the APIDeclined paymentsSubmitting receipts with Safe dealRefunding payments with Safe dealPayment and remuneration reports