Skip to main content

Payments with YooMoney wallets

You can accept payments with YooMoney wallets, including:

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

How to make a payment​

All parameters are passed in plain text. Do not use our widgets.

  1. Send a /session/init/payment request. Optionally, you can pass a URL in payment_options.return_url for redirecting the payer back after the payment.

    The payment amount limits depend on the YooMoney wallet level.

    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"
        }
      }'

  2. Wait for a ready_to_confirm webhook from Bank 131 when Bank 131 is ready to process the payment and is waiting for your confirmation.

    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": {
              "recurrent": false,
              "description": "description"
            }
          }],
          "next_action": "confirm"
        }
     }'

  3. Confirm (session/confirm) or cancel (session/cancel) the payment.

  4. Wait for an action_required webhook from Bank 131 and redirect the payer using the link from customer_interaction.redirect.url.

    info

    After the action_required webhook arrives, the payer has 20 minutes to confirm the payment.

    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": {
              "recurrent": false,
              "description": "description"
            }
          }],
          "actions": {
            "confirm": "2025-11-05T08:34:31.626530Z"
          }
        }
      }'

  5. If you make delayed capture payments, wait for a ready_to_capture webhook and then either confirm (session/capture) or cancel (session/cancel) the capture.

    Webhook example 
    curl -X POST \
      https://partner.ru \
      -H 'content-type: application/json' \
      -H 'X-PARTNER-SIGN: signature' \
      -d '{
        "type": "ready_to_capture",
        "session": {
          "id": "ps_3821809",
          "status": "in_progress",
          "created_at": "2025-11-05T08:33:46.121130Z",
          "updated_at": "2025-11-05T08:44:33.115425Z",
          "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": {
              "recurrent": false,
              "description": "description"
            }
          }],
          "next_action": "capture",
          "actions": {
            "confirm": "2025-11-05T08:34:31.626530Z"
          }
        }
      }'

  6. Wait for a payment_finished webhook. See the payment results in the status parameter of the acquiring_payments/payment_list array.

    If the status is succeeded, the payment was successful. If the status is failed, an error occurred during the payment.

    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": 5000,
              "currency": "RUB"
            },
            "amounts": {},
            "metadata": {
              "key": "value"
            },
            "payment_options": {
              "recurrent": false,
              "description": "description"
            }
          }],
          "actions": {
            "confirm": "2025-11-05T08:34:31.626530Z",
            "capture": "2025-11-05T08:45:18.934056Z"
          }
        }
      }'

Recurring payments​

CIT recurring payments with YooMoney wallets are not supported.

To make MIT recurring payments with YooMoney wallets:

  1. Get a token by sending 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"
        }
      }'

  2. Use the token to make recurring payments.

    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"
          }]
        }
      }'

Payment diagram​