Payments with YooMoney wallets

You can accept payments with YooMoney wallets, including:

Payments made with YooMoney wallets are refunded in a standard way.

info

Payments with YooMoney are made without the Bank 131 payment widget.

Step 1. Create a payment session

Send a (session/create) request. In response you will get the session identifier.

Alternatively, you can use the (session/init/payment method to create a session and a payment at the same time. In this case, specify all the payment parameters and skip the next step. This option is not recommended.

Step 2. Start the payment

Send a session/start/payment request with the session identifier and payment parameters. Optionally, you can pass a URL in payment_options.return_url to redirect the payer back after the payment is completed.

The payment amount limits depend on the YooMoney wallet level—the higher the level, the larger the amount that can be charged.

Request example

curl -X POST \
  https://demo.bank131.ru/api/v1/session/start/payment \
  -H 'Content-Type: application/json' \
  -H 'X-PARTNER-PROJECT: your_project_name' \
  -H 'X-PARTNER-SIGN: signature' \
  -d '{
    "payment_details": {
      "type": "wallet",
      "wallet": {
        "type": "yoomoney",
        "yoomoney": {}
      }
    },
    "amount_details": {
      "amount": 25420,
      "currency": "rub"
    },
    "metadata": {
      "key": "value"
    },
    "customer": {
      "reference": "lucky",
      "contacts": [{
        "email": "test@mail.net"
      }]
    },
    "payment_options": {
      "return_url": "https://www.131.ru",
      "description": "description"
    }
  }'

Step 3. Wait for a webhook confirming the payment is ready

Bank 131 will then send you a ready_to_confirm webhook to notify you that you should now confirm or cancel the payment.

Webhook example

curl -X POST \
  https://partner.ru \
  -H 'content-type: application/json' \
  -H 'X-PARTNER-SIGN: signature' \
  -d '{
    "type": "ready_to_confirm",
    "session": {
      "id": "ps_3821809",
      "status": "in_progress",
      "created_at": "2025-11-05T08:33:46.121130Z",
      "updated_at": "2025-11-05T08:33:46.290108Z",
      "acquiring_payments": [{
        "id": "pm_2775568",
        "status": "pending",
        "created_at": "2025-11-05T08:33:46.190121Z",
        "customer": {
          "reference": "lucky",
          "contacts": [{
            "email": "test@mail.net"
          }]
        },
        "payment_details": {
          "type": "wallet",
          "wallet": {
            "type": "yoomoney",
            "yoomoney": {}
          }
        },
        "amount_details": {
          "amount": 25420,
          "currency": "RUB"
        },
        "amounts": {},
        "metadata": {
          "key": "value"
        },
        "payment_options": {
          "return_url": "https://www.131.ru",
          "description": "description"
        }
      }],
      "next_action": "confirm"
    }
}'

Step 4. Confirm or cancel the payment

Check the data, then confirm (session/confirm) or cancel (session/cancel) the payment.

Step 5. Wait for a webhook on additional actions

An action_required webhook from Bank 131 arrives if the payer needs to confirm the charge in their YooMoney wallet.

Redirect the customer using the link from the customer_interaction.redirect.url parameter.

Wait for the payer to confirm the payment.

The payer has 20 minutes to confirm the payment after being redirected. If the timeout expires, the transaction will automatically complete with the cancelled status.

Webhook example

curl -X POST \
  https://partner.ru \
  -H 'content-type: application/json' \
  -H 'X-PARTNER-SIGN: signature' \
  -d '{
    "type": "action_required",
    "session": {
      "id": "ps_3821809",
      "status": "in_progress",
      "created_at": "2025-11-05T08:33:46.121130Z",
      "updated_at": "2025-11-05T08:34:31.887997Z",
      "acquiring_payments": [{
        "id": "pm_2775568",
        "status": "pending",
        "created_at": "2025-11-05T08:33:46.190121Z",
        "customer": {
          "reference": "lucky",
          "contacts": [{
            "email": "test@mail.net"
          }]
        },
        "payment_details": {
          "type": "wallet",
          "wallet": {
            "type": "yoomoney",
            "yoomoney": {}
          }
        },
        "amount_details": {
          "amount": 25420,
          "currency": "RUB"
        },
        "amounts": {},
        "customer_interaction": {
          "type": "redirect",
          "redirect": {
            "url": "https://yoomoney.ru/checkout/payments/v2/contract?orderId=309d1fd7-000f-5001-8000-1e9f64506f41",
            "base_url": "https://yoomoney.ru/checkout/payments/v2/contract",
            "method": "GET",
            "qs": {
              "orderId": "309d1fd7-000f-5001-8000-1e9f64506f41"
            },
            "params": {}
            }
        },
        "metadata": {
          "key": "value"
        },
        "payment_options": {
          "return_url": "https://www.131.ru",
          "description": "description"
        }
      }],
      "actions": {
        "confirm": "2025-11-05T08:34:31.626530Z"
      }
    }
  }'

Step 8. Wait for a webhook on the payment results

Bank 131 will send you a payment_finished webhook. The payment status is in the acquiring_payments/payment_list array.

If the status is succeeded, the payment went through. If the status is failed, the payment was not processed due to an error.

Webhook example

curl -X POST \
  https://partner.ru \
  -H 'content-type: application/json' \
  -H 'X-PARTNER-SIGN: signature' \
  -d '{
    "type": "payment_finished",
    "session": {
      "id": "ps_3821809",
      "status": "accepted",
      "created_at": "2025-11-05T08:33:46.121130Z",
      "updated_at": "2025-11-05T08:45:19.857746Z",
      "acquiring_payments": [{
        "id": "pm_2775568",
        "status": "succeeded",
        "created_at": "2025-11-05T08:33:46.190121Z",
        "finished_at": "2025-11-05T08:45:19.781451Z",
        "customer": {
          "reference": "lucky",
          "contacts": [{
            "email": "test@mail.net"
          }]
        },
        "payment_details": {
          "type": "wallet",
          "wallet": {
            "type": "yoomoney",
            "yoomoney": {}
          }
        },
         "amount_details": {
           "amount": 25420,
           "currency": "RUB"
         },
         "amounts": {},
         "metadata": {
          "key": "value"
        },
        "payment_options": {
          "return_url": "https://www.131.ru",
          "description": "description"
        }
      }],
      "actions": {
        "confirm": "2025-11-05T08:34:31.626530Z",
        "capture": "2025-11-05T08:45:18.934056Z"
      }
    }
  }'

Sequence diagram

View the diagram

MIT recurring payments

info

CIT recurring payments with YooMoney wallets are not supported.

Make a one-time payment to get a recurring token. You can use this token to make subsequent payments.

Get a recurring token

When making a one-time payment, send recurrent=true in the payment_options object. If the payment is successful, you will get the token in the payment_finished webhook in the recurrent.token parameter.

Request example

curl -X POST \
  https://demo.bank131.ru/api/v1/session/init/payment \
  -H 'Content-Type: application/json' \
  -H 'X-PARTNER-PROJECT: your_project_name' \
  -H 'X-PARTNER-SIGN: signature' \
  -d '{
    "payment_details": {
      "type": "wallet",
      "wallet": {
        "type": "yoomoney",
        "yoomoney": {}
      }
    },
    "amount_details": {
      "amount": 25420,
      "currency": "rub"
    },
    "metadata": {
      "key": "value"
    },
    "customer": {
      "reference": "lucky",
      "contacts": [{
        "email": "test@mail.net"
      }]
    },
    "payment_options": {
      "return_url": "https://www.131.ru",
      "description": "description",
      "recurrent": true
    }
  }'

Make a payment by token

Use the token received earlier.

Request example

curl -X POST \
  https://proxy.bank131.ru/api/v1/session/init/payment \
  -H 'Content-Type: application/json' \
  -H 'X-PARTNER-PROJECT: your_project_name' \
  -H 'X-PARTNER-SIGN: signature' \
  -d '{
    "payment_details": {
      "type": "recurrent",
      "recurrent": {
        "token": "e9876f32bcd947f79c324cf2da5726304a894f6ae2037de7705fdb3e0a134d39"
      }
    },
    "amount_details": {
      "amount": 1000,
      "currency": "RUB"
    },
    "metadata": {
      "key": "value"
    },
    "customer": {
      "reference": "lucky",
      "contacts": [{
        "email": "test@mail.net"
      }]
    }
  }'

More about MIT recurring payments >

More about the payment statuses >

View error codes >

Step 1. Create a payment session​

Step 2. Start the payment​

Step 3. Wait for a webhook confirming the payment is ready​

Step 4. Confirm or cancel the payment​

Step 5. Wait for a webhook on additional actions​

Step 8. Wait for a webhook on the payment results​

Sequence diagram​

MIT recurring payments​

Get a recurring token​

Make a payment by token​

Step 1. Create a payment session

Step 2. Start the payment

Step 3. Wait for a webhook confirming the payment is ready

Step 4. Confirm or cancel the payment

Step 5. Wait for a webhook on additional actions

Step 8. Wait for a webhook on the payment results

Sequence diagram

MIT recurring payments

Get a recurring token

Make a payment by token