Quick start for partners — Payment acceptance via the YooMoney API

Quick start

The partnership program allows you interact with the YooMoney API on behalf of a YooMoney user.

This article will help you accept the first payment in favor of another person in three steps:

Register your app in YooMoney's OAuth server.
Get a payment processing permission from the store.
Make a payment via the YooMoney API.

Step 1. Register the app in YooMoney's OAuth server

To interact with YooMoney API, register your app in the YooMoney's OAuth server.

During the registration process:

Specify the app’s name, short description which the user will see, and the link to the app's website.
Select Send in Callback URL to get the confirmation code in Callback URL and specify the URL where the user will be redirected to after the permission is issued.
In the YooMoney API block of the Access rights section, select the rights to create and view payments.

On the following page, you will see your app’s properties. Save the app’s ID (Client ID), and password (Client Secret).

Properties of the created app

Step 2. Get a payment processing permission

You will make payments to the YooMoney’s demo store, which requires an OAuth token, the permission for carrying out transactions. The process of OAuth authorization in YooMoney is based on the OAuth 2.0 open protocol.

1. Access the demo store

Create a demo store for which you're going to get an OAuth token.

Sign up for YooMoney using this link.
In the process, you'll see two options: continue sign-up or proceed to testing payments. Select testing payments.

Done! You'll see the created demo store.

Create the URL for redirection

The user will be able to grant the rights to a store after you redirect them to the OAuth server: https://yookassa.ru/oauth/v2/authorize

Example of URL for redirecting the user

https://yookassa.ru/oauth/v2/authorize?response_type=code&client_id=<App ID>&state=test-user

In the redirection URL, specify that you are requesting authorization code (the response_type parameter with the code) value, specify the ID of your app (client_id) and, if necessary, ID of the user or session in which the rights are being granted (state). YooMoney's OAuth server will return the state parameter in the response.

3. Provide the app with the access to demo store

Allow the app to create payments for the demo store and view them:

Sign in to your YooMoney account linked to the YooMoney demo store.
Follow the link you generated on the previous step.
Allow the app to create payments and view them.
Access request
Select the demo store that you allow performing payment actions and grant access to it.
Selecting the store

Afterwards, the OAuth server will redirect you to Callback URL that you specified during the app registration. The link will include the authorization code and the ID of the user that granted you the rights (state value that you specified in the request).

Example of the URL you will be redirected to in case of success

http://www.example.com/app?code=rvunUlge6gUMx6TT0UT6ys4y398qqG73KQb1PjXETuX6eiQYJXXi-IrNHe49a9mt&state=test-user

4. Obtain an OAuth token

To exchange the authorization code to an OAuth token, send a POST request to the OAuth server and specify the authorization code (code parameter), your ID, and the password that your received after the registration in YooMoney's OAuth server.

URL for sending the request: https://yookassa.ru/oauth/v2/token

The code is valid for 5 minutes. You must exchange it to an OAuth token within this period, otherwise you will have to request it again.

Example of request

cURL
curl https://yookassa.ru/oauth/v2/token \
  -u <App ID>:<App password> \
  -d grant_type=authorization_code \
  -d code=<Authorization code>

In response, the YooMoney’s OAuth server will return the OAuth token in the access_token field. Save it for further interaction with the YooMoney API.

Example of response body with the OAuth token

JSON
{
  "access_token": "AAEAAAAA8cSwPQAAAXUcZAXZ9hmYP3bKvY2r3ALwPYRYhrnOiKDEou9aLKiLYArHj2Tke-syRshb-1TQ1Ns_nQbc",   
  "expires_in": 94607999
}

Step 3. Make a payment

1. Check the store’s settings

Before using the YooMoney API, you must check the settings of the store you obtained the OAuth token for. The settings define which features of YooMoney are available to you. For example, if it's a demo store, you can only process test payments and only two payment methods will be available: bank card and YooMoney.

To check the settings, send the request for obtaining the store information with the OAuth token.

Example of request

cURL
PHP
Python
curl https://api.yookassa.ru/v3/me \
  -H 'Authorization: Bearer <oauth_token>'

Store settings will be returned in response.

Example of the response body

JSON
{
  "account_id": "123",
  "test": true,
  "fiscalization_enabled": false,
  "payment_methods": [
    "bank_card",
    "yoo_money"
  ],
  "status": "enabled"
}

2. Make a test payment

Process your first payment to the demo store using Quick start for creating payments. Specify the OAuth token instead of store's ID and secret key.

Example of request for payment creation

cURL
PHP
Python
curl https://api.yookassa.ru/v3/payments \
  -X POST \
  -H 'Authorization: Bearer <oauth_token>' \
  -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"
      }'

Wait until the payment is completed successfully: send periodic requests for payment information to find out if the payment status has changed to succeeded.

Done! You've processed your first payment via YooMoney on behalf of a store.

Further steps

Set up the interaction with the API in the most convenient way for you:

select a set of rights required for your app to fully operate;
select how you'd like to receive the verification code;
set up notifications from YooMoney;
select the features of the YooMoney API that your users will need, for example, two-stage payments or sending of receipts to the Tax Service.