---
metadata:
  - name: generator
    content: Diplodoc Platform v5.52.0
alternate:
  - https://pay.yandex.ru/docs/en/custom/index.md
  - https://pay.yandex.ru/docs/ru/custom/index.md
  - href: en/custom/index.md
    type: text/markdown
    title: Markdown version
  - href: ../llms.txt
    type: text/markdown
    title: llms.txt
---
> **Documentation Index:** Fetch the complete configuration index at https://pay.yandex.ru/docs/en/llms.txt

# Integration with Yandex Pay over API

You can use two methods to integrate with Yandex Pay:

- Adding a Yandex Pay [button](#sequence) and widget to the merchant's frontend.
- [Generating a payment link](#sequence-link) and redirecting the user to the Yandex Pay payment form.

## Integrating by adding a button {#sequence}

In this integration, to install a Yandex Pay button and widget, you need to implement the [Merchant API](./backend/merchant-api)'s `/order/render` and `/order/create` methods on the backend, and integrate them into the merchant's frontend. It also enables you to extend your integration to support Yandex Pay Checkout. To implement this integration, follow the [instructions for adding a Yandex Pay button](https://pay.yandex.ru/docs/en/custom/integration-guide.md).

Demo:

<!-- source: en/custom/web-sdk/_snippets/base-buttons-and-widgets.mdx -->
<!-- markdownlint-disable -->

<div class="ypd-preview">
    <a href="https://yastatic.net/s3/pay-static/docs/v41.0.0/custom/base-buttons-and-widgets/index.html" target="_blank">
        <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 24 24"><path fill="currentColor" d="M18 19H6c-.55 0-1-.45-1-1V6c0-.55.45-1 1-1h5c.55 0 1-.45 1-1s-.45-1-1-1H5c-1.11 0-2 .9-2 2v14c0 1.1.9 2 2 2h14c1.1 0 2-.9 2-2v-6c0-.55-.45-1-1-1s-1 .45-1 1v5c0 .55-.45 1-1 1zM14 4c0 .55.45 1 1 1h2.59l-9.13 9.13c-.39.39-.39 1.02 0 1.41.39.39 1.02.39 1.41 0L19 6.41V9c0 .55.45 1 1 1s1-.45 1-1V3h-6c-.55 0-1 .45-1 1z"></path></svg>
    </a>
    <iframe src="https://yastatic.net/s3/pay-static/docs/v41.0.0/custom/base-buttons-and-widgets/index.html" style="height: 450px"></iframe>
</div>
<!-- endsource: en/custom/web-sdk/_snippets/base-buttons-and-widgets.mdx -->

For more examples with the [button](./web-sdk/#payment-data) or [widget](./web-sdk/widgets#example), see the Web SDK documentation.

The following sequence of steps is provided for paying (and also creating a new order for Yandex Pay Checkout):

1. The buyer clicks the Yandex Pay button. The merchant uses the SDK on the frontend to specify the order ID or items in the cart in case of Yandex Pay Checkout.
1. Based on the order ID or items in the cart, Yandex Pay gets the information about the order and products using [order/render](https://pay.yandex.ru/docs/en/custom/backend/merchant-api/archive/order-render.md).
1. Based on the merchant's data and the user's personal data, Yandex Pay shows the payment form or checkout form.
1. The buyer selects the payment method and delivery option (if needed) and initiates payment.
1. Yandex Pay requests the permission to pay for the order by calling [/order/create](https://pay.yandex.ru/docs/en/custom/backend/merchant-api/archive/order-create.md).
1. The merchant checks the order details, reserves the items, and authorizes the payment.
1. Yandex Pay sends the payment through the merchant's payment gateway or Split.
1. Yandex Pay notifies the merchant about the payment status using the [/webhook](https://pay.yandex.ru/docs/en/custom/backend/merchant-api/webhook.md) call, if the [Callback URL](https://pay.yandex.ru/docs/en/console/index.md#setup-callback-url) has been set up.

Before paying, the buyer can update the form: change the delivery address, or apply a discount coupon. After each change, the Yandex Pay backend will repeat the steps 2-3.

![Integrating by ](_assets/scheme.svg "creating an order using the Yandex Pay element")

## Integrating with link generation {#sequence-link}

This integration model is simple, but it can only be used to paying for orders. Use it when you want to quickly add a payment method to your site. For this kind of integration, follow the [instructions with link generation](https://pay.yandex.ru/docs/en/custom/integration-guide-link.md).

Demo:

<!-- source: en/custom/web-sdk/_snippets/psp-like.mdx -->
<!-- markdownlint-disable -->

<div class="ypd-preview">
    <a href="https://yastatic.net/s3/pay-static/docs/v16.0.0/custom/psp-like/index.html" target="_blank">
        <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 24 24"><path fill="currentColor" d="M18 19H6c-.55 0-1-.45-1-1V6c0-.55.45-1 1-1h5c.55 0 1-.45 1-1s-.45-1-1-1H5c-1.11 0-2 .9-2 2v14c0 1.1.9 2 2 2h14c1.1 0 2-.9 2-2v-6c0-.55-.45-1-1-1s-1 .45-1 1v5c0 .55-.45 1-1 1zM14 4c0 .55.45 1 1 1h2.59l-9.13 9.13c-.39.39-.39 1.02 0 1.41.39.39 1.02.39 1.41 0L19 6.41V9c0 .55.45 1 1 1s1-.45 1-1V3h-6c-.55 0-1 .45-1 1z"></path></svg>
    </a>
    <iframe src="https://yastatic.net/s3/pay-static/docs/v16.0.0/custom/psp-like/index.html" style="height: 185px"></iframe>
</div>
<!-- endsource: en/custom/web-sdk/_snippets/psp-like.mdx -->

The order is paid in the following sequence:

1. The user selects a Yandex Pay payment method and proceeds to the payment page. The interface for selecting a payment method is implemented by the Merchant according to the [branding rules](https://pay.yandex.ru/docs/en/branding.md#link).
1. The merchant's backend receives a link to the payment form using the [/orders](https://pay.yandex.ru/docs/en/custom/backend/yandex-pay-api/order/merchant_v1_orders-post.md) request sent to the [Yandex Pay API](https://pay.yandex.ru/docs/en/custom/backend/yandex-pay-api/index.md).
1. The merchant's frontend redirects the user to the Yandex Pay payment form.
1. The user proceeds to the Yandex Pay payment form that renders the cart and payment amount.
1. The user clicks **Buy**.
1. Yandex Pay sends the payment through the merchant's payment gateway or Split.
1. Yandex Pay notifies the merchant about the payment status using the [/webhook](https://pay.yandex.ru/docs/en/custom/backend/merchant-api/webhook.md) call, if the [Callback URL](https://pay.yandex.ru/docs/en/console/index.md#setup-callback-url) has been set up.

![Integrating with ](_assets/scheme-link.svg "creating an order via a link")

## Managing orders {#back-office}

The merchant can manage the order using the [Yandex Pay API](https://pay.yandex.ru/docs/en/custom/backend/yandex-pay-api/index.md) and  [console](https://console.pay.yandex.ru/): confirm and cancel payments, make a refund, etc.

## What's next {#next-step}

To set up two-step payments, read the [instructions](https://pay.yandex.ru/docs/en/custom/payment-stages.md). To generate receipts for the Federal Taxation Service in Yandex Pay, you need to transmit the [receipt data](https://pay.yandex.ru/docs/en/custom/fns.md) along with the cart.