Quick start
The YooMoney API allows accepting online payments in the web and mobile apps. This article will help you accept your first payment, and your customers will be able to access all of the payment methods you’ve implemented.
Preparation
To start working with YooMoney, you need to sign up and get access to the Merchant Profile. You need the secret key and store ID from your Merchant Profile for authenticating requests. Learn more about the basics of interacting with the YooMoney API
You can process this payment in the demo store. The payment process in the demo store is identical to the actual payment process, except real money is not transferred anywhere. You can only test two payment methods: bank cards and YooMoney wallets. Learn more about test mode
If you'd like to try out the features of the API but you don't have a YooMoney Merchant Profile, sign up using this link. It's the simplest way to get a demo store. You don't need to enter the information about your company or enter into a contract.
Step 1. Create a payment
Payment is the main entity of the YooMoney API. To create a payment, you will need the payment amount and the URL for redirecting the user after they complete the payment. Also include the
capture parameter with the true value. This means you will receive the money immediately after the payment (if the value is false, the required amount will be held on the user’s account, and you’ll be able to capture it whenever convenient for you).If you want to add a payment description that’ll be displayed in the Merchant Profile to you, and during the payment to the user, include it in the
description parameter. The description must not exceed 128 characters.Send a request to YooMoney and include data for creating a payment, data for authentication (Shop ID and secret key) and the idempotence key (any random value).
All requests to the YooMoney API must be sent from your server. You can use ready-made server SDKs to interact with YooMoney.
Example of request for payment creation
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": "100.00", "currency": "RUB" }, "capture": true, "confirmation": { "type": "redirect", "return_url": "https://www.example.com/return_url" }, "description": "Order No. 1" }'
Step 2. Redirect the user to the payment page
In the body of the response from YooMoney, you will receive a created payment object with the
pending status. Redirect the user to the confirmation_url so they could make a payment.Redirect is the main confirmation scenario for user payments. In some cases, user confirmation is not required or is processed by another scenario.
Example of a created payment object
JSON
{ "id": "23d93cac-000f-5000-8000-126628f15141", "status": "pending", "paid": false, "amount": { "value": "100.00", "currency": "RUB" }, "confirmation": { "type": "redirect", "confirmation_url": "https://yoomoney.ru/api-pages/v2/payment-confirm/epl?orderId=23d93cac-000f-5000-8000-126628f15141" }, "created_at": "2019-01-22T14:30:45.129Z", "description": "Order No. 1", "metadata": {}, "recipient": { "account_id": "100500", "gateway_id": "100700" }, "refundable": false, "test": false }
If you’re creating a payment for the demo store, use one of the test cards for the payment, for example,
5555555555554444 (use any CVC and future date).After a successful payment (or if something goes wrong), YooMoney will return the user to
return_url that you specified during payment creation.Step 3. Wait for the successful payment completion
Payment can be considered completed once its status changes to
succeeded. If the user decides not to proceed with the payment or if something goes wrong, the payment status will change to canceled.You can check the payment status by subscribing to the notifications from YooMoney.
You can also track status changes by requesting payment information with a convenient frequency (for example, after the user returns to
return_url). For that, you will need the payment ID (value of the id parameter in the created payment object).Great, you have accepted your first payment!
In this example, the user selected the payment method and entered the payment details on the YooMoney’s side. This scenario is called Smart payment. If it doesn’t suit your mode of operation, you can use another integration scenario.
Remember: to accept real payments, you will need to use the ID and secret key of your real store.
See also