API ЮKassa
Инструкции
Старые версии API
Помощь
Подключить ЮKassa
Справочник
API ЮKassa: Инструкции
API ЮKassa: Справочник
Старые версии API
Помощь

|

Подключить ЮKassa
English
Прием оплаты от покупателя
Для приема оплаты от покупателя вы можете использовать любой способ оплаты и любой сценарий интеграции, включая виджет ЮKassa и мобильные SDK. Вы можете делать автоплатежи и принимать оплату в две стадии. Единственное отличие от стандартного процесса — в запросах на создание и подтверждение платежа нужно передавать данные о сделке, в составе которой проходит операция.
До проведения платежа: ознакомьтесь с общим процессом оплаты, выберите нужный вам сценарий интеграции и создайте сделку.
Сценарий взаимодействия
Чтобы принять оплату от покупателя:
  1. Отправьте ЮKassa запрос на создание платежа, передайте в нём параметры, необходимые для выбранного сценария проведения платежа, и данные о сделке.
  2. При необходимости реализуйте сценарий подтверждения платежа покупателем.
  3. Если вы проводите платеж в две стадии, подтвердите, что вы готовы принять платеж и пополнить баланс сделки.
После успешного завершения оплаты ЮKassa пополнит баланс сделки. Сумма, которую ЮKassa перечисляет на баланс сделки, зависит от момента выплаты вам вознаграждения (fee_moment в сделке).
Сценарий сделкиfee_momentСумма на балансе сделкиСумма выплаты продавцу
Вознаграждение после успешного платежаpayment_succeededСумма выплаты продавцуСумма на балансе сделки
Вознаграждение при закрытии сделкиdeal_closedСумма выплаты продавцу и сумма вашего вознаграждения за вычетом комиссии ЮKassa.
Сумма на балансе сделки за вычетом вашего вознаграждения
Пример: сумма платежа — 1 000 рублей, из них вознаграждение продавца — 800 рублей, вознаграждение платформы — 200 рублей. Если комиссия ЮKassa — 4,5% от суммы платежа, то на балансе сделки останется: 800 + (200 — 1 000*0,045) = 955 рублей
К сделке может быть привязан только один платеж в статусе pending, waiting_for_capture или succeeded. Если платеж по каким-то причинам перешел в статус canceled, например покупателю не удалось оплатить или вы сами отменили платеж при оплате в две стадии, то вы можете привязать к сделке еще один платеж.
Далее описаны особенности работы с платежами при использовании Безопасной сделки:
В конце статьи приведены примеры проведения платежей в одну и две стадии.
Создание платежа
Чтобы принять оплату от покупателя, отправьте ЮKassa запрос на создание платежа , передайте в нём данные, которые нужны для оплаты в зависимости от выбранного сценария интеграции, параметр capture в соответствии с тем, как вы хотите проводить платеж — в одну или в две стадии, и следующие данные для проведения платежа в рамках сделки:
  • Объект amount с общей суммой платежа за сделку (сумма вознаграждения продавца и вознаграждения вашей платформы). Эту сумму ЮKassa спишет с покупателя. Комиссия ЮKassa за проведение платежа рассчитывается из этой суммы, а взимается из вашего вознаграждения. Сумма платежа должна соответствовать ограничениям на минимальный и максимальный размер платежа. Подробнее о лимитах платежей
  • Объект deal с данными о сделке: идентификатор сделки и массив settlements с данными о том, какую сумму нужно выплатить продавцу. Разница между суммой платежа и суммой выплаты должна быть больше эквайринговой комиссии ЮKassa. Сумма выплаты должна соответствовать ограничениям на минимальный и максимальный размер выплаты. Подробнее о лимитах выплат
Пример: товар продавца стоит 800 рублей, проведение сделки на вашей платформе — 200 рублей. Всего покупатель заплатит 1 000 рублей. В этом случае в amount нужно передать 1 000 рублей, в deal.settlements.amount — 800 рублей. Если комиссия ЮKassa 4,5%, вознаграждение ЮKassa составит 45 рублей (1 000*0,045). Свою комиссию ЮKassa взимает из вашего вознаграждения, поэтому в итоге продавец получит 800 рублей, ЮKassa — 45 рублей, а вы — 155 рублей.
Пример запроса на проведение платежа в одну стадию
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": true,
        "confirmation": {
          "type": "redirect",
          "return_url": "https://example.com/return_url"
        },
        "description": "Оплата заказа №37",
        "deal": {
          "id": "dl-285e5ee7-0022-5000-8000-01516a44b147",
          "settlements": [{
            "type": "payout",
            "amount": {
              "value": "800.00",
              "currency": "RUB"
            }
          }]
        },
        "metadata": {
          "order_id": "37"
        }
      }'
В ответ ЮKassa отправит вам объект платежа  в актуальном статусе.
Пример тела ответа
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": "Оплата заказа №37",
    "metadata": {
        "order_id": "37"
    },
    "recipient": {
        "account_id": "100500",
        "gateway_id": "100700"
    },
    "refundable": false,
    "test": false
}
При необходимости реализуйте нужный сценарий подтверждения платежа или инициализируйте виджет ЮKassa.
Дождитесь, когда пользователь подтвердит оплату — статус платежа изменится: если принимаете оплату в одну стадию (capture=true), платеж перейдет в статус succeeded, если в две стадии (capture=false), то в статус waiting_for_capture. Чтобы узнать статус платежа, периодически запрашивайте информацию о платеже  или дождитесь уведомления от ЮKassa.
Если вы проводите платеж в одну стадию, ЮKassa пополнит баланс сделки после подтверждения платежа пользователем. Если вы проводите платеж в две стадии, вам нужно дополнительно подтвердить пополнение баланса или отменить платеж.
Подтверждение и отмена платежа
Если вы проводите платеж в две стадии, то после подтверждения платежа пользователем деньги замораживаются (холдируются) на платежном средстве покупателя. Чтобы перечислить оплату на баланс вашей сделки, вам необходимо списать или отменить платеж.
Списание оплаты
Чтобы списать всю сумму платежа, отправьте ЮKassa стандартный запрос на подтверждение платежа  с пустым телом запроса. Чтобы списать только часть суммы платежа, отправьте ЮKassa запрос на подтверждение платежа с новой суммой платежа и со скорректированной информацией о распределении денег.
Пример запроса на частичное списание суммы платежа
cURL
PHP
Python
curl https://api.yookassa.ru/v3/payments/{payment_id}/capture \
  -X POST \
  -u <Идентификатор магазина>:<Секретный ключ> \
  -H 'Idempotence-Key: <Ключ идемпотентности>' \
  -H 'Content-Type: application/json' \
  -d '{
        "amount": {
          "value": "600.00",
          "currency": "RUB"
        },
        "deal": {
          "settlements": [
            {
              "type": "payout",
              "amount": {
                "value": "480.00",
                "currency": "RUB"
              }
            }
          ]
        }
      }'
Вам нужно подтвердить платеж и пополнение баланса сделки до момента, указанного в параметре expires_at объекта платежа. Если вы ничего не сделаете с платежом за этот срок, ЮKassa отменит его, указав причину expired_on_capture. Чтобы пополнить баланс сделки, создайте новый платеж с тем же идентификатором сделки.
Отмена платежа по вашей инициативе
Если вы не готовы пополнить баланс, отправьте ЮKassa стандартный запрос на отмену платежа . После отмены платежа баланс сделки останется нулевым. Чтобы пополнить баланс сделки, создайте новый платеж с тем же идентификатором сделки.
Примеры проведения платежа
Ниже приведены примеры проведения платежа с примерами объекта сделки:
  • Пример платежа в одну стадию: если платеж проходит в одну стадию, ЮKassa перечисляет оплату на баланс сделки сразу после успешного подтверждения платежа пользователем.
  • Пример платежа в две стадии: если платеж проходит в две стадии, после подтверждения платежа пользователем вам нужно сообщить ЮKassa, что можно перечислить оплату на баланс сделки.
Пример платежа в одну стадию
Шаг 1. Создайте платеж с данными для оплаты, с информацией о связанной сделке и с параметром capture со значением true.
Пример запроса на создание одностадийного платежа в составе сделки
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": true,
        "confirmation": {
          "type": "redirect",
          "return_url": "https://example.com/return_url"
        },
        "description": "Оплата заказа №37",
        "deal": {
          "id": "dl-285e5ee7-0022-5000-8000-01516a44b147",
          "settlements": [{
            "type": "payout",
            "amount": {
              "value": "800.00",
              "currency": "RUB"
            }
          }]
        },
        "metadata": {
          "order_id": "37"
        }
      }'
Пример тела ответа
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": "Оплата заказа №37",
    "metadata": {
        "order_id": "37"
    },
    "recipient": {
        "account_id": "100500",
        "gateway_id": "100700"
    },
    "refundable": false,
    "test": false
}
Шаг 2. При необходимости реализуйте нужный сценарий подтверждения или инициализируйте виджет для приема платежей.
Шаг 3. Дождитесь, когда пользователь подтвердит платеж (платеж перейдет в статус succeeded). Для этого периодически запрашивайте информацию о платеже или дождитесь уведомления от ЮKassa.
Пример объекта платежа в статусе succeeded
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": "Оплата заказа №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
}
Когда платеж перейдет в статус succeeded, ЮKassa пополнит баланс сделки. Теперь вы можете делать выплату продавцу.
Баланс сделки после платежа
Сценарий проведения сделкиБаланс сделки после оплатыСумма выплаты продавцу
Вознаграждение после успешного платежа fee_moment=payment_succeeded
На балансе окажется только та сумма, которая нужна для выплаты продавцу.
Пример: если сумма платежа 1 000 рублей, сумма выплаты 800 рублей, то на балансе сделки будет 800 рублей.
Сумма на балансе сделки
Вознаграждение после закрытия сделки fee_moment=deal_closed
На балансе окажется сумма выплаты продавцу и сумма вашего вознаграждения за вычетом комиссии ЮKassa (значение income_amount из объекта платежа).
Пример: если сумма платежа 1 000 рублей, сумма выплаты 800 рублей, то на балансе сделки будет 955 рублей (1 000*(1-0,045))
Сумма на балансе сделки за вычетом вашего вознаграждения
Пример платежа в две стадии
Примите оплату, затем спишите ее или отмените платеж.
Прием оплаты
Шаг 1. Создайте платеж с данными для оплаты, с информацией о связанной сделке и с параметром capture со значением false.
Пример запроса на создание двухстадийного платежа в составе сделки
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": "Оплата заказа №37",
        "deal": {
          "id": "dl-285e5ee7-0022-5000-8000-01516a44b147",
          "settlements": [{
            "type": "payout",
            "amount": {
              "value": "800.00",
              "currency": "RUB"
            }
          }]
        },
        "metadata": {
          "order_id": "37"
        }
      }'
Пример тела ответа
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": "Оплата заказа №37",
    "metadata": {
        "order_id": "37"
    },
    "recipient": {
        "account_id": "100500",
        "gateway_id": "100700"
    },
    "refundable": false,
    "test": false
}
Шаг 2. При необходимости реализуйте нужный сценарий подтверждения или инициализируйте виджет для приема платежей.
Шаг 3. Дождитесь, когда пользователь подтвердит платеж (платеж перейдет в статус waiting_for_capture). Для этого периодически запрашивайте информацию о платеже или дождитесь уведомления от ЮKassa.
Пример объекта платежа в статусе waiting_for_capture
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": "Заказ №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
}
Баланс сделки после подтверждения платежа покупателем
После подтверждения платежа покупателем баланс сделки останется нулевым.
Списание оплаты
Если вы готовы списать оплату с покупателя и пополнить баланс сделки, отправьте запрос на подтверждение платежа. Если нужно подтвердить часть платежа, добавьте в тело запроса обновленные данные о платеже и распределении денег.
Пример запроса на частичное списание суммы платежа
cURL
PHP
Python
curl https://api.yookassa.ru/v3/payments/{payment_id}/capture \
  -X POST \
  -u <Идентификатор магазина>:<Секретный ключ> \
  -H 'Idempotence-Key: <Ключ идемпотентности>' \
  -H 'Content-Type: application/json' \
  -d '{
        "amount": {
          "value": "600.00",
          "currency": "RUB"
        },
        "deal": {
          "settlements": [
            {
              "type": "payout",
              "amount": {
                "value": "480.00",
                "currency": "RUB"
              }
            }
          ]
        }
      }'
В ответ ЮKassa вернет объект платежа в статусе succeeded.
Пример объекта платежа в статусе succeeded
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": "Оплата заказа №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
}
После этого ЮKassa пополнит баланс сделки. Теперь вы можете делать выплату продавцу.
Баланс сделки после подтверждения платежа
Сценарий проведения сделкиБаланс сделки после оплатыСумма выплаты продавцу
Вознаграждение после успешного платежа fee_moment=payment_succeeded
На балансе окажется только та сумма, которая нужна для выплаты продавцу.
Пример: если после подтверждения сумма платежа 600 рублей, сумма выплаты 480 рублей, то на балансе сделки будет 480 рублей.
Сумма на балансе сделки
Вознаграждение после закрытия сделки fee_moment=deal_closed
На балансе окажется сумма выплаты продавцу и сумма вашего вознаграждения за вычетом комиссии ЮKassa (значение income_amount из объекта платежа).
Пример: если после подтверждения сумма платежа 600 рублей, сумма выплаты 480 рублей, то на балансе сделки будет 573 рубля (600*(1-0,045))
Сумма на балансе сделки за вычетом вашего вознаграждения
Отмена платежа
Если вы не готовы списать оплату и пополнить баланс, отправьте ЮKassa запрос на отмену платежа.
Пример запроса на отмену платежа
cURL
PHP
Python
curl https://api.yookassa.ru/v3/payments/{payment_id}/cancel \
  -X POST \
  -u <Идентификатор магазина>:<Секретный ключ> \
  -H 'Idempotence-Key: <Ключ идемпотентности>' \
  -H 'Content-Type: application/json' \
  -d '{
      }'
В ответ на запрос ЮKassa вернет вам объект платежа в статусе canceled.
Пример объекта платежа в статусе canceled
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": "Оплата заказа №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"
    }
}
ЮKassa вернет всю оплату покупателю.
Баланс сделки после отмены платежа
После отмены платежа баланс сделки останется нулевым. Чтобы пополнить баланс, создайте новый платеж и подтвердите его.
Что почитать еще
Основы работы с APIНеуспешные платежиОтправка чеков в Безопасной сделкеВозврат платежа в Безопасной сделкеРеестры платежей и вознаграждений
Юридические документы
Правила работы сервиса ЮKassaСоглашение об ЭДО
Вы не разработчик?
Модули для CMSВыставление счетовПлатежи для лендингов
8 800 250-66-99
Задать вопросПомощь
© 2023, ООО НКО «ЮМани»