Yandex Paybox payments via API

Payment service AntiDDOS Router enables Yandex Paybox payments via API. With the Yandex Paybox payment way, an order can be paid with Yandex Pay or Yandex Split. Payment is made on the Yandex payment page; the URL of that page is provided by the Yandex Paybox service.

Payment via Yandex Paybox is always made to Yandex Bank. The bank must be specified in the partner settings in the Payment service. To find out the current settings, use the /settings/getRouterParams.do request.

The partner have to receive Yandex Paybox API key(s) from Yandex Bank and provide those keys to the Payment service support team.

Integration flow

Register an order

1. The Client initiates the purchase of a product or service on the Partner's website.

2. The Partner sends one of the following order registration requests to the Payment Service AntiDDOS Router:

register.do for a one-phase payment, or
registerPreAuth.do for a two-phase payment.

For more details on these types of payments, see the section Two-phase payments.

On the Yandex Bank side, one API key allows you to use either one-phase or two-phase payments. However, the Partner can use both types of payment in the AntiDDOS Router Payment service. To do this, the Partner should obtain two API keys from Yandex Bank, one for each payment type, and provide them to the Payment Service support team.

Order registration features:

When registering an order, the Partner can specify which Yandex Paybox payment methods shall be available to the Client: only card, only Split, or both of them. For this, an additional parameter yandex_paymentWay is passed. By default, if the parameter is not passed, only payment by card (CARD) is available. The use of certain Yandex Paybox payment methods must be agreed upon between the Partner and Yandex Bank.
Make sure to pass cart items in the orderBundle parameter when registering an order for payment. If the cart is not passed, but clientId is, the request may be processed as creation of a stored credential, see Creating Yandex Paybox stored credentials.

Request example:

curl -X POST 'https://api.uat.all2pay.net/v1/register.do' -H 'Content-Type: application/json' \
--data-raw '{
    "orderNumber": "order_123508",
    "jsonParams": {
        "yandex_paymentWay": "CARD, SPLIT"
    },
    "amount": 10000,
    "currency": "643",
    "language": "en",
    "returnUrl": "https://mybestmerchantreturnurl.com/success",
    "failUrl": "https://mybestmerchantreturnurl.com/fail",
    "userName": "test_user",
    "password": "test_user_password",
    "orderBundle": {
        "cartItems": {
        "items": [
            {
                "itemAmount": 10000,
                "itemCode": "123code",
                "itemCurrency": "643",
                "itemPrice": 10000,
                "name": "item 1",
                "positionId": "1",
                "quantity": {
                    "measure": "pcs",
                    "value": "1"
                }
            }
        ]
        }
    }
}'

3. Payment Service AntiDDOS Router validates the input data and registers the order.

Request for payment via Yandex Paybox

4. Payment Service AntiDDOS Router returns the registered order ID orderId to the Partner.

Response example:

{
    "errorCode": "0",
    "formUrl": "https://router.rbsuat.com/wl/payment.html?mdOrder=f9584546-2613-4a0d-896f-0194d243865f&language=ru",
    "orderId": "f9584546-2613-4a0d-896f-0194d243865f",
    "orderNumber": "order_123508"
}

5. Partner requests the Payment service AntiDDOS Router to pay the order via Yandex Paybox /yandex-box/paymentOrder.do.

Request example:

curl -X POST 'https://api.uat.all2pay.net/v1/yandex-box/paymentOrder.do' \
-H 'Content-Type: application/json' \
--data-raw '{
    "orderId": "1f3224c9-cc80-4c2a-8ef7-ca4d198f6a2e",
    "password": "test_user_password",
    "userName": "test_user" 
}'

6. Payment service AntiDDOS Router requests the URL of the payment page from Yandex Bank.

7. The Yandex Bank communicates the URL of the payment page to the Payment service.

Redirect to the Yandex page for payment

8. The Payment service communicates the URL of the payment page to the Partner.

Response example:

{
    "data": {
        "gwId": "YANDEX",
        "gwOrderId": "ffc65a85-1af5-7a4d-ab65-a29206c90f80",
        "orderId": "14f8b21d-46ab-11f0-8452-696e1279ae2c",
        "redirect": "https://sandbox.pay.ya.ru/l/k774SQ"
    },
    "success": true
}

9. The Partner redirects the Client to the Yandex Paybox payment page (via URL from the redirect parameter).

10. The Client pays for the order on the Yandex Paybox page using any of the available methods (card or Split).

11. The Yandex Bank service redirects the Client to the return URL.

Final status of the order

12. (Option) If the Partner has callbacks configured, the Yandex Bank sends the payment result callback to the Partner.

13. (Option) If the callback is not configured, the Partner periodically requests the Payment service AntiDDOS Router to get the final order status via getOrderStatusExtended.do with orderId query parameter. The order status will be PENDING until the payment result is known.

14-17. Payment AntiDDOS Router requests the order status in Yandex Bank and returns to the Partner. When the status changes, the Partner displays it on the final page.

Stored credentials with Yandex Paybox

Payment service AntiDDOS Router supports stored credentials with Yandex Paybox. Payments made using Yandex Paybox stored credentials are always directed to the Yandex Bank.

The use of stored credentials with Yandex Paybox is possible if the partner has corresponding permission in the Yandex Bank. Please contact the Payment service support team to check or change such permissions and settings.

Creating Yandex Paybox stored credentials

Creating a common eCom stored credential

To create a eCom stored credential, follow the above described process with some difference:

add the clientId parameter in the order registration request at step 2.
Do not pass cart items in the orderBundle parameter.

The amount value is ignored, no funds will be retrieved from the Client's account.

Request example:

curl -X POST 'https://api.uat.all2pay.net/v1/register.do' -H 'Content-Type: application/json' \
--data-raw '{
    "clientId": "12555",
    "orderNumber": "order_123508",
    "jsonParams": {
        "yandex_paymentWay": "CARD, SPLIT"
    },
    "amount": 10000,
    "currency": "643",
    "language": "ru",
    "returnUrl": "https://mybestmerchantreturnurl.com/success",
    "failUrl": "https://mybestmerchantreturnurl.com/fail",
    "userName": "test_user",
    "password": "test_user_password"
}'

The partner must have permission for the use of stored credentials and corresponding settings in Yandex Bank.

Then, on step 12, the Client will confirm or decline the credentials saving (card binding).

To find out the bindingId identifier of the stored credential created after the payment is completed, the partner can configure callback or send getOrderStatusExtended.do request (steps 15-16).

Creating a recurring stored credential

To create a recurring stored credential, in the above described process, add the following parameters in the order registration request at step 2:

clientId
recurringFrequency
recurringExpiry

Request example:

curl -X POST 'https://api.uat.all2pay.net/v1/register.do' -H 'Content-Type: application/json' \
--data-raw '{
    "clientId": "12555",
    "jsonParams": {
        "yandex_paymentWay": "CARD, SPLIT",
        "recurringFrequency":12,
        "recurringExpiry":"20251225"
    },
    "orderNumber": "order_123508",
    "amount": 10000,
    "currency": "643",
    "language": "ru",
    "returnUrl": "https://mybestmerchantreturnurl.com/success",
    "failUrl": "https://mybestmerchantreturnurl.com/fail",
    "userName": "test_user",
    "password": "test_user_password",
    "orderBundle": {
        "cartItems": {
        "items": [
            {
                "itemAmount": 10000,
                "itemCode": "123code",
                "itemCurrency": "643",
                "itemPrice": 10000,
                "name": "item 1",
                "positionId": "1",
                "quantity": {
                    "measure": "pcs",
                    "value": "1"
                }
            }
        ]
        }
    }
}'

The partner must have permission for the use of recurring stored credentials and corresponding settings in Yandex Bank.

Then, on step 12, the Client will have to confirm the credentials saving (subscription).

To find out the bindingId identifier of the stored credential created after the payment is completed, the partner can configure callback or send getOrderStatusExtended.do request (steps 15-16).

Paying with Yandex Paybox Stored Credential

For payment with a stored credential, the following methods are used:

paymentOrderBinding.do or instantPayment.do for payment with a regular eCom stored credential. See example request: Payment with eCom Stored Credentials via API.
recurrentPayment.do for payment with a recurring stored credential. See example request: Payment with Recurring Stored Credential.