NAV Navbar

Quick start

Since you're here, we assume that you've already signed up with Yandex.Checkout, got access to Merchant Profile, generated and activated a secret key.

What's next:

  1. Create a payment and get the payment link
  2. Redirect user to the payment page
  3. Wait until the payment is processed

Step 1. Create a payment

Shop ID is shopId in the Merchant Profile.

You can issue a Secret key by following these instructions.

Use any value that is unique for this request as Idempotence key. We recommend v4 UUID.

curl https://payment.yandex.net/api/v3/payments \
  -X POST \
  -u <Shop ID>:<Secret Key> \
  -H 'Idempotence-Key: <Idempotence Key>' \
  -H 'Content-Type: application/json' \
  -d '{
        "amount": {
          "value": "2.00",
          "currency": "RUB"
        },
        "confirmation": {
          "type": "redirect",
          "return_url": "https://www.merchant-website.com/return_url"
        },
        "capture": true,
        "description": "Order No. 1"
      }'
<?php
    use YandexCheckout\Client;

    $client = new Client();
    $client->setAuth('<Shop ID>', '<Secret Key>');
    $payment = $client->createPayment(
        array(
            'amount' => array(
                'value' => 2.0,
                'currency' => 'RUB',
            ),
            'confirmation' => array(
                'type' => 'redirect',
                'return_url' => 'https://www.merchant-website.com/return_url',
            ),
            'capture' => true,
            'description' => 'Order No. 1',
        ),
        uniqid('', true)
    );
?>
from yandex_checkout import Configuration, Payment

Configuration.account_id = <Shop ID>
Configuration.secret_key = <Secret Key>

payment = Payment.create({
    "amount": {
        "value": "2.00",
        "currency": "RUB"
    },
    "confirmation": {
        "type": "redirect",
        "return_url": "https://www.merchant-website.com/return_url"
    },
    "capture": true,
    "description": "Order No. 1"
})

Create a payment with the payment method selection at Yandex.Checkout's side by sending the request for creating a payment to Yandex.Checkout:

Send a request with a unique Idempotence key.

Step 2. Display the payment page

Example of response body

{
  "id": "22d6d597-000f-5000-9000-145f6df21d6f",
  "status": "pending",
  "paid": false,
  "amount": {
    "value": "2.00",
    "currency": "RUB"
  },
  "confirmation": {
    "type": "redirect",
    "confirmation_url": "https://money.yandex.ru/api-pages/v2/payment-confirm/epl?orderId=22d6d597-000f-5000-9000-145f6df21d6f"
  },
  "created_at": "2018-07-10T14:25:27.535Z",
  "description": "Order No. 1",
  "metadata": {},
  "test": false
}

Redirect the user to confirmation_url that you've received in response body. This is the page on the Yandex.Checkout's side where the user can select a payment method and make the payment.

Step 3. Wait for the payment

A notification from Yandex.Checkout on the status change to succeeded

{
  "type": "notification",
  "event": "payment.succeeded",
  "object": {
    "id": "22d6d597-000f-5000-9000-145f6df21d6f",
    "status": "succeeded",
    "paid": true,
    "amount": {
      "value": "2.00",
      "currency": "RUB"
    },
    "authorization_details": {
      "rrn": "10000000000",
      "auth_code": "000000"
    },
    "captured_at": "2018-07-10T14:34:37.036Z",
    "created_at": "2018-07-10T14:27:54.691Z",
    "description": "Order No. 1",
    "metadata": {},
    "payment_method": {
      "type": "bank_card",
      "id": "22d6d597-000f-5000-9000-145f6df21d6f",
      "saved": false,
      "card": {
        "first6": "555555",
        "last4": "4444",
        "expiry_month": "07",
        "expiry_year": "2020",
        "card_type": "MasterCard"
      },
      "title": "Bank card *4444"
    },
    "refunded_amount": {
      "value": "0.00",
      "currency": "RUB"
    },
    "test": false
  }
}

Once the user selects the method and confirms the payment, the payment status will change to succeeded. This status indicates a successful payment. Now you can provide the customer with the product.

You can monitor the changes in payment status by:

Payments

Example of Payment object with the succeeded status

{
  "id": "22d6d597-000f-5000-9000-145f6df21d6f",
  "status": "succeeded",
  "paid": true,
  "amount": {
    "value": "2.00",
    "currency": "RUB"
  },
  "authorization_details": {
    "rrn": "10000000000",
    "auth_code": "000000"
  },
  "captured_at": "2018-07-10T14:38:32.295Z",
  "created_at": "2018-07-10T14:27:54.691Z",
  "description": "Order No. 72",
  "metadata": {},
  "payment_method": {
    "type": "bank_card",
    "id": "22d6d597-000f-5000-9000-145f6df21d6f",
    "saved": false,
    "card": {
      "first6": "555555",
      "last4": "4444",
      "expiry_month": "07",
      "expiry_year": "2021",
      "card_type": "MasterCard"
    },
    "title": "Bank card *4444"
  },
  "refunded_amount": {
    "value": "0.00",
    "currency": "RUB"
  },
  "test": false
}

Payment object is the primary entity used for payment acceptance. Payments have a linear life cycle, going from one status to the next sequentially.

Payment statuses

Depending on your store's settings, and the attributes set at payment creation, some statuses may be omitted — but their sequence is always unchangeable.

Create payment

To create a Payment object, you need to specify the payment amount, currency, and other additional information (depending on the payment scenario).

There are several payment scenarios:

User confirmation

Example of payment created with redirect confirmation scenario

curl https://payment.yandex.net/api/v3/payments \
  -X POST \
  -u <Shop ID>:<Secret Key> \
  -H 'Idempotence-Key: <Idempotence Key>' \
  -H 'Content-Type: application/json' \
  -d '{
        "amount": {
          "value": "2.00",
          "currency": "RUB"
        },
        "confirmation": {
          "type": "redirect",
          "return_url": "https://www.merchant-website.com/return_url"
        },
        "description": "Order No. 72"
      }'
<?php
    $payment = $client->createPayment(
        array(
            'amount' => array(
                'value' => 2.0,
                'currency' => 'RUB',
            ),
            'confirmation' => array(
                'type' => 'redirect',
                'return_url' => 'https://www.merchant-website.com/return_url',
            ),
            'description' => 'Order No. 72',
        ),
        uniqid('', true)
    );
?>
payment = Payment.create({
    "amount": {
        "value": "2.00",
        "currency": "RUB"
    },
    "confirmation": {
        "type": "redirect",
        "return_url": "https://www.merchant-website.com/return_url"
    },
    "description": "Order No. 72"
})

Example of payment waiting for confirmation under redirect scenario

{
  "id": "22d6d9be-000f-5000-9000-1427689709c4",
  "status": "pending",
  "paid": false,
  "amount": {
    "value": "2.00",
    "currency": "RUB"
  },
  "confirmation": {
    "type": "redirect",
    "confirmation_url": "https://money.yandex.ru/api-pages/v2/payment-confirm/epl?orderId=22d6d9be-000f-5000-9000-1427689709c4"
  },
  "created_at": "2018-07-10T14:43:10.782Z",
  "description": "Order No. 72",
  "metadata": {},
  "test": false
}

Sometimes, users need to perform certain actions to confirm the payment. For example, enter the 3-D Secure confirmation code when paying by bank card, or confirm the payment in our partner's payment service, or pay the invoice via online banking or text message.

One payment method might support several confirmation scenarios and ask for different input data for each specific scenario.

Capture and cancel

Example of request for a partial confirmation of a bank card payment

curl https://payment.yandex.net/api/v3/payments/{payment_id}/capture \
  -X POST \
  -u <Shop ID>:<Secret Key> \
  -H 'Idempotence-Key: <Idempotence Key>' \
  -H 'Content-Type: application/json' \
  -d '{
        "amount": {
          "value": "2.00",
          "currency": "RUB"
        }
      }'
<?php
    $client->capturePayment(
        array(
            'amount' => array(
                'value' => 2.0,
                'currency' => 'RUB',
            ),
        ),
        $paymentId,
        uniqid('', true)
    );
?>
payment = Payment.capture(payment_id, {
    {
        "amount": {
            "value": "2.00",
            "currency": "RUB"
        }
    }
})

Example of request for payment cancellation

curl https://payment.yandex.net/api/v3/payments/{payment_id}/cancel \
  -X POST \
  -u <Shop ID>:<Secret Key> \
  -H 'Idempotence-Key: <Idempotence Key>' \
  -H 'Content-Type: application/json'
<?php
    $client->cancelPayment(
        $paymentId,
        uniqid('', true)
    );
?>
payment = Payment.cancel(payment_id)

By default, all Yandex.Checkout API payments with the waiting_for_capture status require you to capture them. If you want the payment to be captured automatically, put true value in the capture parameter when you create it. Such payments will immediately change their status to succeeded once all the necessary actions with the pending status are performed.

Once the payment status changes to waiting_for_capture, you will have:

Time provided for payment capture is indicated in the expires_at field. If you don't capture the payment within that period, its status will automatically change to canceled, and the funds will be returned to user.

Once you're ready to provide the service or dispatch the goods, you must capture the payment using the capture method. If a payment is made via bank card or from a Yandex.Money wallet, you can capture a part of the payment amount by including the amount to be debited and the currency in the request body. In this case, the rest of the payment amount will be returned to the user's bank card. When other payment methods are used, you can only capture the whole amount.

On the day after the capture, the payment will be recorded in the register, and Yandex.Checkout will credit the funds to your settlement account.

If you're unable to provide the service or dispatch the goods, you will have to cancel the payment using the cancel method. In this case, the payment status will change to canceled, and the funds will be returned to the user. If a payment is canceled, Yandex.Checkout doesn't charge a fee for the transaction.

Canceled payments

Example of the Payment object with the canceled status

{
  "id": "22979b7b-000f-5000-9000-1a603a795739",
  "status": "canceled",
  "paid": false,
  "amount": {
    "value": "2.00",
    "currency": "RUB"
  },
  "created_at": "2018-05-23T15:24:43.812Z",
  "metadata": {},
  "payment_method": {
    "type": "bank_card",
    "id": "22979b7b-000f-5000-9000-1a603a795739",
    "saved": false
  },
  "recipient": {
    "account_id": "67192",
    "gateway_id": "352780"
  },
  "test": false,
  "cancellation_details": {
    "party": "payment_network",
    "reason": "payment_method_restricted"
  }
}

In course of a payment process, something might go wrong. For example, the buyer might not have enough money to make a payment, the card issuer might be unavailable, or Yandex.Checkout might suspect a fraud attempt. In this case, the payment will be canceled and the status will change to canceled.

The Payment object that you will receive from Yandex.Checkout will contain the details of the cancellation (cancellation_details) so you can better understand what happened and what you should do next. The information includes the initiator (cancellation_details.party) and the reason behind the cancellation (cancellation_details.reason). You can use this information to analyze and solve problems, display messages to the customer, and for any other purposes.

Possible initiators of the cancellation of a payment

Value Description
merchant Seller of goods and services (you)
yandex_checkout Yandex.Checkout
payment_network "External" participants of the payment process, i.e. all other participants of the payment process except for you and Yandex.Checkout (for example, the card issuer or the third-party payment service)

Possible reasons behind the cancellation of a payment

Value Description
3d_secure_failed 3-D Secure authentication failed. The buyer should repeat the payment, contact their bank for details, or use another payment method
call_issuer Payment made with this payment method was declined for unknown reasons. The buyer should contact the organization that provides the payment method
card_expired The bank card has expired. The buyer should use a different payment method
country_forbidden Payments with a bank card issued in this country are not allowed. The buyer should use a different payment method.
You can set up the limits for payments made via bank card issued by foreign banks
fraud_suspected The payment was blocked due to suspected fraud. The buyer should use a different payment method
general_decline No detailed reason provided. The buyer should contact the initiator of the payment cancellation for more details
identification_required Exceeded payment limit on the Yandex.Money wallet. The buyer should complete the identification process or select another payment method
insufficient_funds Not enough money to make the payment. The buyer should add money to the account balance or select another payment method
invalid_card_number Invalid card number. The buyer should repeat the payment and enter the correct card details
invalid_csc The CVV2 code (CVC2, CID) was entered incorrectly. The buyer should repeat the payment and enter the correct card details
issuer_unavailable The organization that provides the payment method is not available. The buyer should repeat the payment later or select another payment method
payment_method_limit_exceeded You have reached the payment limit for this payment method or your store. The buyer should repeat the payment on the next day or select another payment method
payment_method_restricted Transactions made with this payment method are forbidden (for example, the card is blocked due to loss or the wallet is blocked due to hacking). The buyer should contact the organization that provides the payment method

Please note: the canceled status is final and unchangeable. To repeat a payment, you should create a new payment object with a new Idempotence key.

You can test payment cancellation with test bank cards.

Native payment forms

Native payment forms allow integrating the payment acceptance process directly to your website or mobile app, so the user won't have to visit the Yandex.Checkout website during the payment process.

To integrate native payment forms, you need to:

Payment confirmation by the user

Some payment methods require the implementation of a certain user confirmation scenario:

Processing payments from native payment forms

Example of payment creation with a payment token

curl https://payment.yandex.net/api/v3/payments \
  -X POST \
  -u <Shop ID>:<Secret Key> \
  -H 'Idempotence-Key: <Idempotence Key>' \
  -H 'Content-Type: application/json' \
  -d '{
        "payment_token": "eyJ0eXBlIjoiY2hlY2tvdXRfanNfYmFua19jYXJkIiwiZW5jcnlwdGVkIjoiMFk3Q3dVVXFVSUE0bXVUWW5EVXhBRG9PUFFCRHByQ3F6Y0cvcGw5SDFZV0xKejROaS9wVkZ0amhmT3N1b1NzVGp2cFJzYkRxSTdLWStYNjZjdW45STczTC8zQXFPOGVwV0dtSFEyV1pXR1lHM3pNdUxyNHp1WmJzMW85bDh5czdjT0ZuMEc5T3hma0kyNitQcXBuSGU3NGZwYzRXU1l2TUh4MFpyYVdRNW5UdFlDVWQyZz09IiwiaW5pdFZlY3RvciI6Ik50d0lpZVFFaG9Cb3FJRzFxT29yREE9PSIsImtleUlkIjoiT2pOQUJrL21Uam5kTGtWZlR1U1F0dz09In0=",
        "amount": {
          "value": "2.00",
          "currency": "RUB"
        },
        "confirmation": {
          "type": "redirect",
          "enforce": false,
          "return_url": "https://www.merchant-website.com/return_url"
        },
        "capture": false,
        "description": "Payment for order No. 12345"
      }'
<?php
    $client->createPayment(
        array(
            payment_token => eyJ0eXBlIjoiY2hlY2tvdXRfanNfYmFua19jYXJkIiwiZW5jcnlwdGVkIjoiMFk3Q3dVVXFVSUE0bXVUWW5EVXhBRG9PUFFCRHByQ3F6Y0cvcGw5SDFZV0xKejROaS9wVkZ0amhmT3N1b1NzVGp2cFJzYkRxSTdLWStYNjZjdW45STczTC8zQXFPOGVwV0dtSFEyV1pXR1lHM3pNdUxyNHp1WmJzMW85bDh5czdjT0ZuMEc5T3hma0kyNitQcXBuSGU3NGZwYzRXU1l2TUh4MFpyYVdRNW5UdFlDVWQyZz09IiwiaW5pdFZlY3RvciI6Ik50d0lpZVFFaG9Cb3FJRzFxT29yREE9PSIsImtleUlkIjoiT2pOQUJrL21Uam5kTGtWZlR1U1F0dz09In0=,
            'amount' => array(
                'value' => 2,
                'currency' => 'RUB',
            ),
            'confirmation' => array(
                'type' => 'redirect',
                'return_url' => 'https://www.merchant-website.com/return_url',
            ),
            'capture' => false,
            'description' => 'Payment for order No. 12345',
        ),
        uniqid('', true)
    );
?>
payment = Payment.create({
    "payment_token": "eyJ0eXBlIjoiY2hlY2tvdXRfanNfYmFua19jYXJkIiwiZW5jcnlwdGVkIjoiMFk3Q3dVVXFVSUE0bXVUWW5EVXhBRG9PUFFCRHByQ3F6Y0cvcGw5SDFZV0xKejROaS9wVkZ0amhmT3N1b1NzVGp2cFJzYkRxSTdLWStYNjZjdW45STczTC8zQXFPOGVwV0dtSFEyV1pXR1lHM3pNdUxyNHp1WmJzMW85bDh5czdjT0ZuMEc5T3hma0kyNitQcXBuSGU3NGZwYzRXU1l2TUh4MFpyYVdRNW5UdFlDVWQyZz09IiwiaW5pdFZlY3RvciI6Ik50d0lpZVFFaG9Cb3FJRzFxT29yREE9PSIsImtleUlkIjoiT2pOQUJrL21Uam5kTGtWZlR1U1F0dz09In0=",
    "amount": {
        "value": "2.00",
        "currency": "RUB"
    },
    "confirmation": {
        "type": "redirect",
        "return_url": "https://www.merchant-website.com/return_url"
    },
    "capture": false,
    "description": "Order No. 72"
})

Example of response body

{
  "id": "22cfeb68-000f-5000-9000-170954758639",
  "status": "waiting_for_capture",
  "paid": true,
  "amount": {
    "value": "2.00",
    "currency": "RUB"
  },
  "authorization_details": {
    "rrn": "10000000000",
    "auth_code": "000000"
  },
  "created_at": "2018-07-05T08:32:40.935Z",
  "expires_at": "2018-07-12T08:32:44.505Z",
  "description": "Payment for order No. 12345",
  "metadata": {},
  "payment_method": {
    "type": "bank_card",
    "id": "22cfeb68-000f-5000-9000-170954758639",
    "saved": false,
    "card": {
      "first6": "420000",
      "last4": "1111",
      "expiry_month": "01",
      "expiry_year": "2020",
      "card_type": "Visa"
    },
    "title": "Bank card *1111"
  },
  "test": false
}
  1. Obtain a payment token from a client library (YandexCheckout.js, YandexCheckout UI, mobile SDK).
  2. Send the generated payment token and the selected payment method to your server.
  3. Create a payment:
    • include the generated payment token as a value for the payment_token parameter;
    • depending on the selected payment method, specify the parameters for payment confirmation by the user in the confirmation object.
  4. If necessary, show any information required for the payment confirmation to the user.
  5. Wait for the payment process to complete: you will receive a notification from Yandex.Checkout. You can also send periodic requests to receive payment information.
  6. Capture the payment using the capture method.

Refunds

Example of request for a partial refund

curl https://payment.yandex.net/api/v3/refunds \
  -X POST \
  -u <Shop ID>:<Secret Key> \
  -H 'Idempotence-Key: <Idempotence Key>' \
  -H 'Content-Type: application/json' \
  -d '{
        "amount": {
          "value": "2.00",
          "currency": "RUB"
        },
        "payment_id": "21740069-000f-50be-b000-0486ffbf45b0"
      }'
<?php
    $client->createRefund(
        array(
            'amount' => array(
                'value' => 2.0,
                'currency' => 'RUB',
            ),
            'payment_id' => '21740069-000f-50be-b000-0486ffbf45b0',
        ),
        uniqid('', true)
    );
?>
refund = Refund.create({
    "amount": {
        "value": "2.00",
        "currency": "RUB"
    },
    "payment_id": "21740069-000f-50be-b000-0486ffbf45b0"
})

Example of a successfully conducted refund

  {
    "id": "216749f7-0016-50be-b000-078d43a63ae4",
    "status": "succeeded",
    "amount": {
      "value": "2.00",
      "currency": "RUB"
    },
    "created_at": "2017-10-04T19:27:51.407Z",
    "payment_id": "216749da-000f-50be-b000-096747fad91e"
  }

To refund a payment, you need to create the Refund object and specify the amount, the currency and the unique ID of the payment being refunded (payment_id).

You're allowed to make an infinite number of partial refunds, as long as:

Some payment options do not allow for refunds. Payment options that allow for refunds

Recurring payments

The Yandex.Checkout API allows saving the payment method (with all payment information) for payments made via Yandex.Money wallet or bank card, and using it for recurring payments.

Such payments do not require the confirmation from user.

Step 1. Saving the payment method

Example of a payment creation request with a payment method saved afterwards

curl https://payment.yandex.net/api/v3/payments \
  -X POST \
  -u <Shop ID>:<Secret Key> \
  -H 'Idempotence-Key: <Idempotence Key>' \
  -H 'Content-Type: application/json' \
  -d '{
        "amount": {
          "value": "2.00",
          "currency": "RUB"
        },
        "payment_method_data": {
          "type": "bank_card"
        },
        "confirmation": {
          "type": "redirect",
          "return_url": "https://www.merchant-website.com/return_url"
        },
        "description": "Order No. 72",
        "save_payment_method": "true"
      }'
<?php
    $payment = $client->createPayment(
        array(
            'amount' => array(
                'value' => 2.0,
                'currency' => 'RUB',
            ),
            'payment_method_data' => array(
                'type' => 'bank_card',
            ),
            'confirmation' => array(
                'type' => 'redirect',
                'return_url' => 'https://www.merchant-website.com/return_url',
            ),
            'description' => 'Order No. 72',
            'save_payment_method' => true,
        ),
        uniqid('', true)
    );
?>
payment = Payment.create({
    "amount": {
        "value": "2.00",
        "currency": "RUB"
    },
    "payment_method_data": {
        "type": "bank_card"
    },
    "confirmation": {
        "type": "redirect",
        "return_url": "https://www.merchant-website.com/return_url"
    },
    "description": "Order No. 72",
    "save_payment_method": "true"
})

Example of a successful payment with a saved payment method

{
  "id": "22e18a2f-000f-5000-a000-1db6312b7767",
  "status": "succeeded",
  "paid": true,
  "amount": {
    "value": "2.00",
    "currency": "RUB"
  },
  "authorization_details": {
    "rrn": "10000000000",
    "auth_code": "000000"
  },
  "captured_at": "2018-07-18T17:20:50.825Z",
  "created_at": "2018-07-18T17:18:39.345Z",
  "description": "Order No. 72",
  "metadata": {},
  "payment_method": {
    "type": "bank_card",
    "id": "22e18a2f-000f-5000-a000-1db6312b7767",
    "saved": true,
    "card": {
      "first6": "555555",
      "last4": "4444",
      "expiry_month": "07",
      "expiry_year": "2022",
      "card_type": "MasterCard"
    },
    "title": "Bank card *4444"
  },
  "refunded_amount": {
    "value": "0.00",
    "currency": "RUB"
  },
  "test": false
}

To save a payment method, you will need to complete a successful payment.

Create a payment request. The request should contain save_payment_method with the true value (meaning the payment method should be saved). The payment can be made by entering the bank card or wallet information at the Yandex.Checkout page, transferring card data, or using a payment token.

After the payment status changes to succeeded, the value of the payment_method.saved parameter will change to true, allowing you to use payment_method.id for further direct debit payments.

Step 2. Making a payment from the saved bank card

Example of a payment made with a saved payment method

curl https://payment.yandex.net/api/v3/payments \
  -X POST \
  -u <Shop ID>:<Secret Key> \
  -H 'Idempotence-Key: <Idempotence Key>' \
  -H 'Content-Type: application/json' \
  -d '{
        "amount": {
          "value": "2.00",
          "currency": "RUB"
        },
        "payment_method_id": "<Saved payment method ID>",
        "description": "Order No. 105"
      }'
<?php
    $payment = $client->createPayment(
        array(
            'amount' => array(
                'value' => 2.0,
                'currency' => 'RUB',
            ),
            'payment_method_id' => '<Saved payment method ID>',
            'description' => 'Order No. 105',
        ),
        uniqid('', true)
    );
?>
payment = Payment.create({
    "amount": {
        "value": "2.00",
        "currency": "RUB"
    },
    "payment_method_id": "<Saved payment method ID>",
    "description": "Order No. 105"
})

Create a request for a payment from a bank card or a wallet. Specify the saved payment method ID (that you received in response to the successful request used for for saving bank card data) in the payment_method_id parameter. Such payment does not require additional confirmation from the user.

Airline tickets

When selling airline tickets, you can specify the information about tickets, flights, and passengers, also known as airline addendum data. The addendum data is used only for bank card payments to prevent possible fraudulent transactions.

Step 1. Creating a payment with addendum data

Example of request for a payment for flight tickets

curl https://payment.yandex.net/api/v3/payments \
  -X POST \
  -u <Shop ID>:<Secret Key> \
  -H 'Idempotence-Key: <Idempotence Key>' \
  -H 'Content-Type: application/json' \
  -d '{
        "amount": {
          "value": "10000.00",
          "currency": "RUB"
        },
        "payment_method_data": {
          "type": "bank_card"
        },
        "confirmation": {
          "type": "redirect",
          "return_url": "https://www.merchant-website.com/return_url"
        },
        "description": "Order No. 72",
        "airline": {
          "booking_reference": "IIIKRV",
          "passengers": [
            {
              "first_name": "SERGEI",
              "last_name": "IVANOV"
              }
            ],
          "legs": [
            {
              "departure_airport": "LED",
              "destination_airport": "AMS",
              "departure_date": "2018-06-20"
            }
          ]
        }
      }'
<?php
     $payment = $client->createPayment(
        array(
            "amount" =>  array(
              "value" => "10000.00",
              "currency" => "RUB"
            ),
            "payment_method_data" => array(
                "type" => "bank_card"
            ),
            "confirmation" => array(
                "type" => "redirect",
                "return_url" => "https://www.merchant-website.com/return_url"
            ),
            "description" => "Order No. 72",
            "airline" => array(
                "booking_reference" => "IIIKRV",
                "passengers" => array(
                    array(
                        "first_name" => "SERGEI",
                        "last_name" => "IVANOV"
                    )
                ),
                "legs" => array(
                    array(
                        "departure_airport" => "LED",
                        "destination_airport" => "AMS",
                        "departure_date" => "2018-06-20"
                    )
                )
            )
        ),
        uniqid('', true)
    );
?>
payment = Payment.create({
    "amount": {
        "value": "10000.00",
        "currency": "RUB"
    },
    "payment_method_data": {
        "type": "bank_card"
    },
    "confirmation": {
        "type": "redirect",
        "return_url": "https://www.merchant-website.com/return_url"
    },
    "description": "Order No. 72",
    "airline": {
        "booking_reference": "IIIKRV",
        "passengers": [
            {
                "first_name": "SERGEI",
                "last_name": "IVANOV"
            }
        ],
        "legs": [
            {
                "departure_airport": "LED",
                "destination_airport": "AMS",
                "departure_date": "2018-06-20"
            }
        ]
    }
})

The information about passengers and tickets is specified in airline object during the payment creation process. Since the ticket number is not yet available, you will need to specify the booking reference number (booking_reference).

The passenger information is specified in passengers object (no more than 4 passengers for one payment).

The flight information is specified in legs object (no more than 4 flight legs for any payment). A leg is a fragment of a flight, a trip of an aircraft from take-off to landing. If the passenger takes connecting flights, it is considered to be a multi-leg flight.

Step 2. Capturing the payment

Example of request for a confirmation of the payment for flight tickets

curl https://payment.yandex.net/api/v3/{payment_id}/capture \
  -X POST \
  -u <Shop ID>:<Secret Key> \
  -H 'Idempotence-Key: <Idempotence Key>' \
  -H 'Content-Type: application/json' \
  -d '{
        "amount": {
          "value": "10000.00",
          "currency": "RUB"
        },
        "airline": {
          "booking_reference": "IIIKRV",
          "ticket_number": "5554916004417",
          "passengers": [
            {
              "first_name": "SERGEI",
              "last_name": "IVANOV"
              }
            ],
          "legs": [
            {
              "departure_airport": "LED",
              "destination_airport": "AMS",
              "departure_date": "2018-06-20"
            }
          ]
        }
      }'
<?php
     $payment = $client->createPayment(
        array(
            "amount" =>  array(
              "value" => "10000.00",
              "currency" => "RUB"
            ),
            "payment_method_data" => array(
                "type" => "bank_card"
            ),
            "confirmation" => array(
                "type" => "redirect",
                "return_url" => "https://www.merchant-website.com/return_url"
            ),
            "airline" => array(
                "booking_reference" => "IIIKRV",
                "ticket_number" => "5554916004417",
                "passengers" => array(
                    array(
                        "first_name" => "SERGEI",
                        "last_name" => "IVANOV"
                    )
                ),
                "legs" => array(
                    array(
                        "departure_airport" => "LED",
                        "destination_airport" => "AMS",
                        "departure_date" => "2018-06-20"
                    )
                )
            )
        ),
        uniqid('', true)
    );
?>
payment = Payment.create({
    "amount": {
        "value": "10000.00",
        "currency": "RUB"
    },
    "airline": {
        "booking_reference": "IIIKRV",
        "ticket_number": "5554916004417",
        "passengers": [
            {
                "first_name": "SERGEI",
                "last_name": "IVANOV"
            }
        ],
        "legs": [
            {
                "departure_airport": "LED",
                "destination_airport": "AMS",
                "departure_date": "2018-06-20"
            }
        ]
    }
})

When the payment status changes to waiting_for_capture, you can capture it (provided everything is in order and you are ready to accept the payment). When capturing the payment, specify the ticket number (ticket_number) instead of the booking reference number.

Payment methods

The Yandex.Checkout API allows accepting payments from individuals as well as legal entities and entrepreneurs (B2B payments).

To use a certain payment method, you need to create a payment, and specify the payment amount, the currency, and the payment method (payment_method_data) with all the required parameters.

If you don't set the payment_method_data parameter in the request, the user will be able to select the payment method at the Yandex.Checkout's side.

Payments from individuals

Each payment method requires the implementation of a certain confirmation scenario:

No confirmation Redirect External
bank_card
apple_pay
google_pay
bank_card
yandex_money
sberbank
alfabank
b2b_sberbank
qiwi
webmoney
cash
installments
tinkoff_bank
mobile_balance
sberbank
alfabank

You will receive the information about these payments in the reports on payments from individuals.

You can refund payments made using certain payment methods.

Payments from legal entities and entrepreneurs

Right now, the Yandex.Checkout API supports one payment method: b2b_sberbank, Sberbank Business Online (Sberbank's online bank for legal entities and entrepreneurs). This payment method requires the implementation of the Redirect confirmation scenario.

You will receive the information about these payments in the reports on payments from legal entities and entrepreneurs.

You can't refund payments from legal entities and entrepreneurs.

Bank card

Example of request for a payment via bank card

curl https://payment.yandex.net/api/v3/payments \
  -X POST \
  -u <Shop ID>:<Secret Key> \
  -H 'Idempotence-Key: <Idempotence Key>' \
  -H 'Content-Type: application/json' \
  -d '{
        "amount": {
          "value": "2.00",
          "currency": "RUB"
        },
        "payment_method_data": {
          "type": "bank_card"
        },
        "confirmation": {
          "type": "redirect",
          "return_url": "https://www.merchant-website.com/return_url"
        },
        "description": "Order No. 72"
      }'
  <?php
    $client->createPayment(
        array(
            'amount' => array(
                'value' => 2,
                'currency' => 'RUB',
            ),
            'payment_method_data' => array(
                'type' => 'bank_card',
            ),
            'confirmation' => array(
                'type' => 'redirect',
                'return_url' => 'https://www.merchant-website.com/return_url',
            ),
            'description' => 'Order No. 72',
        ),
        uniqid('', true)
    );
  ?>
  payment = Payment.create({
    "amount": {
        "value": "2.00",
        "currency": "RUB"
    },
    "payment_method_data": {
        "type": "bank_card"
    },
    "confirmation": {
        "type": "redirect",
        "return_url": "https://www.merchant-website.com/return_url"
    },
    "description": "Order No. 72"
  })

Example of the created Payment object

{
  "id": "22c5d173-000f-5000-9000-1bdf241d4651",
  "status": "pending",
  "paid": false,
  "amount": {
    "value": "2.00",
    "currency": "RUB"
  },
  "confirmation": {
    "type": "redirect",
    "return_url": "https://www.merchant-website.com/return_url",
    "confirmation_url": "https://money.yandex.ru/payments/external/confirmation?orderId=22c5d173-000f-5000-9000-1bdf241d4651"
  },
  "created_at": "2018-06-27T16:39:15.865Z",
  "description": "Order No. 72",
  "metadata": {},
  "payment_method": {
    "type": "bank_card",
    "id": "22c5d173-000f-5000-9000-1bdf241d4651",
    "saved": false
  },
  "test": false
}

To accept a payment via bank card made on the Yandex.Checkout's webpage, you need to create a payment with the bank_card payment method and implement the Redirect confirmation scenario.

  1. Create a payment:
    • in the payment_method_data object, set the bank_card type;
    • in the confirmation object, set the redirect type and specify the URL of the page on your side that the user will be redirected to after completing the payment (in the return_url parameter).
  2. Redirect the user to the payment page (you will receive the URL in the confirmation_url parameter).
  3. Wait for the user to confirm the payment: you will receive a notification from Yandex.Checkout. You can also send periodic requests to receive payment information.
  4. Capture the payment using the capture method.

Yandex.Money

Example of request to create a payment to be made from a Yandex.Money wallet or a linked bank card

curl https://payment.yandex.net/api/v3/payments \
  -X POST \
  -u <Shop ID>:<Secret Key> \
  -H 'Idempotence-Key: <Idempotence Key>' \
  -H 'Content-Type: application/json' \
  -d '{
        "amount": {
          "value": "2.00",
          "currency": "RUB"
        },
        "payment_method_data": {
          "type": "yandex_money"
        },
        "confirmation": {
          "type": "redirect",
          "return_url": "https://www.merchant-website.com/return_url"
        },
        "description": "Order No. 72"
      }'
<?php
    $client->createPayment(
        array(
            'amount' => array(
                'value' => 2,
                'currency' => 'RUB',
            ),
            'payment_method_data' => array(
                'type' => 'yandex_money',
            ),
            'confirmation' => array(
                'type' => 'redirect',
                'return_url' => 'https://www.merchant-website.com/return_url',
            ),
            'description' => 'Order No. 72',
        ),
        uniqid('', true)
    );
?>
payment = Payment.create({
    "amount": {
        "value": "2.00",
        "currency": "RUB"
    },
    "payment_method_data": {
        "type": "yandex_money"
    },
    "confirmation": {
        "type": "redirect",
        "return_url": "https://www.merchant-website.com/return_url"
    },
    "description": "Order No. 72"
})

Example of the created Payment object

{
  "id": "22c5d0f0-000f-5000-8000-13ece77bc6c1",
  "status": "pending",
  "paid": false,
  "amount": {
    "value": "2.00",
    "currency": "RUB"
  },
  "confirmation": {
    "type": "redirect",
    "confirmation_url": "https://money.yandex.ru/payments/internal/confirmation?orderId=22c5d0f0-000f-5000-8000-13ece77bc6c1"
  },
  "created_at": "2018-06-27T16:37:04.513Z",
  "description": "Order No. 72",
  "metadata": {},
  "payment_method": {
    "type": "yandex_money",
    "id": "22c5d0f0-000f-5000-8000-13ece77bc6c1",
    "saved": false
  },
  "test": false
}

To accept a payment made from a Yandex.Money wallet or a bank card linked to it, you need to create a payment with the yandex_money payment method and implement the Redirect confirmation scenario.

  1. Create a payment:
    • in the payment_method_data object, set the yandex_money type;
    • in the confirmation object, set the redirect type and specify the URL of the page on your side that the user will be redirected to after completing the payment (in the return_url parameter).
  2. Redirect the user to the payment page (you will receive the URL in the confirmation_url parameter).
  3. Wait for the user to confirm the payment: you will receive a notification from Yandex.Checkout. You can also send periodic requests to receive payment information.
  4. Capture the payment using the capture method.

Sberbank Online

There are two ways to accept payments via Sberbank Online:

Sberbank Online (confirmation at website)

Example of request for a payment via Sberbank Online with the confirmation at the website

curl https://payment.yandex.net/api/v3/payments \
  -X POST \
  -u <Shop ID>:<Secret Key> \
  -H 'Idempotence-Key: <Idempotence Key>' \
  -H 'Content-Type: application/json' \
  -d '{
        "amount": {
          "value": "2.00",
          "currency": "RUB"
        },
        "payment_method_data": {
          "type": "sberbank"
        },
        "confirmation": {
          "type": "redirect",
          "return_url": "https://www.merchant-website.com/return_url"
        },
        "description": "Order No. 72"
      }'
<?php
    $client->createPayment(
        array(
            'amount' => array(
                'value' => 2,
                'currency' => 'RUB',
            ),
            'payment_method_data' => array(
                'type' => 'sberbank',
            ),
            'confirmation' => array(
                'type' => 'redirect',
                'return_url' => 'https://www.merchant-website.com/return_url',
            ),
            'description' => 'Order No. 72',
        ),
        uniqid('', true)
    );
?>
payment = Payment.create({
    "amount": {
        "value": "2.00",
        "currency": "RUB"
    },
    "payment_method_data": {
        "type": "sberbank"
    },
    "confirmation": {
        "type": "redirect",
        "return_url": "https://www.merchant-website.com/return_url"
    },
    "description": "Order No. 72"
})

Example of the created Payment object

{
  "id": "22c5d21b-000f-5000-8000-1ff9ebc96611",
  "status": "pending",
  "paid": false,
  "amount": {
    "value": "2.00",
    "currency": "RUB"
  },
  "confirmation": {
    "type": "redirect",
    "confirmation_url": "https://online.sberbank.ru/CSAFront/payOrderPaymentLogin.do?ReqId=21990df19c919689374dd7387966def7"
  },
  "created_at": "2018-06-27T16:42:03.515Z",
  "description": "Order No. 72",
  "metadata": {},
  "payment_method": {
    "type": "sberbank",
    "id": "22c5d21b-000f-5000-8000-1ff9ebc96611",
    "saved": false
  },
  "test": false
}

To accept a Sberbank Online payment with confirmation at the website, you need to create a payment with the sberbank payment method and implement the Redirect confirmation scenario.

  1. Create a payment:
    • in the payment_method_data object, set the sberbank type;
    • in the confirmation object, set the redirect type and specify the URL of the page on your side that the user will be redirected to after completing the payment (in the return_url parameter).
  2. Redirect the user to the payment page (you will receive the URL in the confirmation_url parameter).
  3. Wait for the user to confirm the payment: you will receive a notification from Yandex.Checkout. You can also send periodic requests to receive payment information.
  4. Capture the payment using the capture method.

Sberbank Online (confirmation via text message)

Example of request for a payment via Sberbank Online with the confirmation via text message

curl https://payment.yandex.net/api/v3/payments \
  -X POST \
  -u <Shop ID>:<Secret Key> \
  -H 'Idempotence-Key: <Idempotence Key>' \
  -H 'Content-Type: application/json' \
  -d '{
        "amount": {
          "value": "2.00",
          "currency": "RUB"
        },
        "payment_method_data": {
          "type": "sberbank",
          "phone": "79000000000"
        },
        "confirmation": {
          "type": "external"
        },
        "description": "Order No. 72"
      }'
<?php
    $client->createPayment(
        array(
            'amount' => array(
                'value' => 2,
                'currency' => 'RUB',
            ),
            'payment_method_data' => array(
                'type' => 'sberbank',
                'phone' => '79000000000',
            ),
            'confirmation' => array(
                'type' => 'external',
            ),
            'description' => 'Order No. 72',
        ),
        uniqid('', true)
    );
?>
payment = Payment.create({
    "amount": {
        "value": "2.00",
        "currency": "RUB"
    },
    "payment_method_data": {
        "type": "sberbank",
        "phone": "79000000000"
    },
    "confirmation": {
        "type": "external"
    },
    "description": "Order No. 72"
})

Example of the created Payment object

{
  "id": "22e2724d-000f-5000-a000-1269c483ca3e",
  "status": "pending",
  "paid": false,
  "amount": {
    "value": "2.00",
    "currency": "RUB"
  },
  "confirmation": {
    "type": "external"
  },
  "created_at": "2018-07-19T09:49:01.683Z",
  "description": "Order No. 72",
  "metadata": {},
  "payment_method": {
    "type": "sberbank",
    "id": "22e2724d-000f-5000-a000-1269c483ca3e",
    "saved": false
  },
  "test": false
}

To accept a Sberbank Online payment with confirmation via a text message, you need to create a payment with the sberbank payment method and implement the External confirmation scenario.

  1. Create a payment:
    • in the payment_method_data object, set the sberbank type and specify the user's phone number linked to Sberbank Online;
    • in the confirmation object, set the external type.
  2. Inform the user that they need to confirm the payment.
  3. Wait for the user to confirm the payment: you will receive a notification from Yandex.Checkout. You can also send periodic requests to receive payment information.
  4. Capture the payment using the capture method.

Alfa-Click

To accept a payment via Alfa-Click, you can use one of the following scenarios:

Alfa-Click (redirect confirmation scenario)

Example of request for a payment made via Alfa-Click using the redirect scenario

curl https://payment.yandex.net/api/v3/payments \
  -X POST \
  -u <Идентификатор магазина>:<Секретный ключ> \
  -H 'Idempotence-Key: <Ключ идемпотентности>' \
  -H 'Content-Type: application/json' \
  -d '{
        "amount": {
          "value": "2.00",
          "currency": "RUB"
        },
        "payment_method_data": {
          "type": "alfabank",
          "login": "79990000000"
        },
        "confirmation": {
          "type": "redirect",
          "return_url": "https://www.merchant-website.com/return_url"
        },
        "description": "Order No. 72"
      }'
<?php
    $client->createPayment(
        array(
            'amount' => array(
                'value' => 2.00,
                'currency' => 'RUB',
            ),
            'payment_method_data' => array(
                'type' => 'alfabank',
                'login' => '79990000000',
            ),
            'confirmation' => array(
                'type' => "redirect",
                'return_url': "https://www.merchant-website.com/return_url",
            ),
            'description' => 'Order No. 72',
        ),
        uniqid('', true)
    );
?>
payment = Payment.create({
    "amount": {
        "value": "2.00",
        "currency": "RUB"
    },
    "payment_method_data": {
        "type": "alfabank",
        "login": "79990000000"
    },
    "confirmation": {
        "type": "redirect",
        "return_url": "https://www.merchant-website.com/return_url"
    },
    "description": "Заказ №72"
})

Example of the created Payment object

{
  "id": "22c80e01-000f-5000-a000-14ce15eb7b74",
  "status": "pending",
  "paid": false,
  "amount": {
    "value": "2.00",
    "currency": "RUB"
  },
  "confirmation": {
    "type": "redirect"
    "confirmation_url": "https://click.alfabank.ru/"
  },
  "created_at": "2019-03-20T09:22:09.367Z",
  "description": "Заказ №72",
  "metadata": {},
  "payment_method": {
    "type": "alfabank",
    "id": "22c80e01-000f-5000-a000-14ce15eb7b74",
    "saved": false,
    "login": "79990000000"
  },
  "recipient": {
    "account_id": "100001",
    "gateway_id": "1000001"
  },
  "test": false
}

To accept a payment made via Alfa-Bank by redirecting the user to Alfa-Click, you need to create a payment with the alfabank payment method and implement the redirect confirmation scenario.

  1. Create a payment:
    • in the payment_method_data object, set the alfabank type and the user’s login in Alfa-Click (if available);
    • in the confirmation object, set the redirect type and specify the URL of the page on your side that the user will be redirected to after completing the payment (in the return_url parameter).
  2. Redirect the user to the payment confirmation page (you will receive the URL in the confirmation_url parameter).
  3. Wait for the user to confirm the payment: you will receive a notification from Yandex.Checkout. You can also send periodic requests to receive payment information.
  4. Capture the payment using the capture method.

Alfa-Click (external confirmation scenario)

Example of request for a payment made via Alfa-Click using the external scenario

curl https://payment.yandex.net/api/v3/payments \
  -X POST \
  -u <Shop ID>:<Secret Key> \
  -H 'Idempotence-Key: <Idempotence Key>' \
  -H 'Content-Type: application/json' \
  -d '{
        "amount": {
          "value": "2.00",
          "currency": "RUB"
        },
        "payment_method_data": {
          "type": "alfabank",
          "login": "79990000000"
        },
        "confirmation": {
          "type": "external"
        },
        "description": "Order No. 72"
      }'
<?php
    $client->createPayment(
        array(
            'amount' => array(
                'value' => 2,
                'currency' => 'RUB',
            ),
            'payment_method_data' => array(
                'type' => 'alfabank',
                'login' => '79990000000',
            ),
            'confirmation' => array(
                'type' => 'external',
            ),
            'description' => 'Order No. 72',
        ),
        uniqid('', true)
    );
?>
payment = Payment.create({
    "amount": {
        "value": "2.00",
        "currency": "RUB"
    },
    "payment_method_data": {
        "type": "alfabank",
        "login": "79990000000"
    },
    "confirmation": {
        "type": "external"
    },
    "description": "Order No. 72"
})

Example of the created Payment object

{
  "id": "22c80e01-000f-5000-a000-14ce15eb7b74",
  "status": "pending",
  "paid": false,
  "amount": {
    "value": "2.00",
    "currency": "RUB"
  },
  "confirmation": {
    "type": "external"
  },
  "created_at": "2018-06-29T09:22:09.367Z",
  "description": "Order No. 72",
  "metadata": {},
  "payment_method": {
    "type": "alfabank",
    "id": "22c80e01-000f-5000-a000-14ce15eb7b74",
    "saved": false
  },
  "test": false
}

To accept a payment made via Alfa-Click, you need to create a payment with the alfabank payment method and implement the External confirmation scenario.

  1. Create a payment:
    • in the payment_method_data object, set the alfabank type and specify the user's login at Alfa-Click;
    • in the confirmation object, set the external type.
  2. Inform the user that they need to confirm the payment.
  3. Wait for the user to confirm the payment: you will receive a notification from Yandex.Checkout. You can also send periodic requests to receive payment information.
  4. Capture the payment using the capture method.

Tinkoff

Example of request for a payment via Tinkoff online banking

curl https://payment.yandex.net/api/v3/payments \
  -X POST \
  -u <Shop ID>:<Secret Key> \
  -H 'Idempotence-Key: <Idempotence Key>' \
  -H 'Content-Type: application/json' \
  -d '{
        "amount": {
          "value": "2.00",
          "currency": "RUB"
        },
        "payment_method_data": {
          "type": "tinkoff_bank"
        },
        "confirmation": {
          "type": "redirect",
          "return_url": "https://www.merchant-website.com/return_url"
        },
        "description": "Order No. 72"
      }'
<?php
    $client->createPayment(
        array(
            'amount' => array(
                'value' => 2,
                'currency' => 'RUB',
            ),
            'payment_method_data' => array(
                'type' => 'tinkoff_bank',
            ),
            'confirmation' => array(
                'type' => 'redirect',
                'return_url' => 'https://www.merchant-website.com/return_url',
            ),
            'description' => 'Order No. 72',
        ),
        uniqid('', true)
    );
?>
payment = Payment.create({
    "amount": {
        "value": "2.00",
        "currency": "RUB"
    },
    "payment_method_data": {
        "type": "tinkoff_bank"
    },
    "confirmation": {
        "type": "redirect",
        "return_url": "https://www.merchant-website.com/return_url"
    },
    "description": "Order No. 72"
})

Example of the created Payment object

{
  "id": "23ce833e-000f-5000-8000-172b6722debf",
  "status": "pending",
  "paid": false,
  "amount": {
    "value": "2.00",
    "currency": "RUB"
  },
  "confirmation": {
    "type": "redirect",
    "confirmation_url": "https://www.tinkoff.ru/payments/invoice/merch/?invoiceGuId=6347da6e-bed7-442b-b4a6-cfc73188469b"
  },
  "created_at": "2019-01-14T11:16:14.441Z",
  "description": "Order No. 72",
  "metadata": {},
  "payment_method": {
    "type": "tinkoff_bank",
    "id": "23ce833e-000f-5000-8000-172b6722debf",
    "saved": false
  },
  "test": false
}

To accept a payment made via Tinkoff online banking, you need to create a payment with the tinkoff_bank payment method and implement the Redirect confirmation scenario.

  1. Create a payment:
    • in the payment_method_data object, set the tinkoff_bank type;
    • in the confirmation object, set the redirect type and specify the URL of the page on your side that the user will be redirected to after completing the payment (in the return_url parameter).
  2. Redirect the user to the payment page (you will receive the URL in the confirmation_url parameter).
  3. Wait for the user to confirm the payment: you will receive a notification from Yandex.Checkout. You can also send periodic requests to receive payment information.
  4. Capture the payment using the capture method.

Apple Pay

To activate this payment method, send the certificate that will be used by Apple to encode the bank card data to Yandex.Checkout. To get this certificate, you need to:

  1. Contact the manager and ask them to create a Certificate Signing Request (CSR) for you.
  2. Load the CSR in Apple Developer account.
  3. Download the generated certificate and send it to the manager.

Detailed instructions (see Step 2 "Exchange certificates with Apple")

To accept a payment made using the Apple Pay cryptogram, you need to:

  1. Create a cryptogram.
  2. Create a payment.
  3. Capture the payment.

Step 1. Create a cryptogram

Generate an Apple Pay cryptogram on the user's device and get the contents of the PKPaymentToken object.

More about generating cryptograms:

Step 2. Create a payment

Example of request for a creating payment with the Apple Pay cryptogram

curl https://payment.yandex.net/api/v3/payments \
  -X POST \
  -u <Shop ID>:<Secret Key> \
  -H 'Idempotence-Key: <Idempotence Key>' \
  -H 'Content-Type: application/json' \
  -d ' {
        "amount": {
          "value": "2.00",
          "currency": "RUB"
        },
        "payment_method_data": {
          "type": "apple_pay",
          "payment_data": "<paymentData>"
        },
        "description": "Order No. 72"
      }'
<?php
    $client->createPayment(
        array(
            'amount' => array(
                'value' => 2,
                'currency' => 'RUB',
            ),
            'payment_method_data' => array(
                'type' => 'apple_pay',
                'payment_data' => '<paymentData>',
            ),
            'description' => 'Order No. 72',
        ),
        uniqid('', true)
    );
?>
payment = Payment.create({
    "amount": {
        "value": "2.00",
        "currency": "RUB"
    },
    "payment_method_data": {
        "type": "apple_pay",
        "payment_data": "<paymentData>"
    },
    "description": "Order No. 72"
})

Example of the created Payment object

{
  "id": "22e290a5-000f-5000-9000-13324c06cacb",
  "status": "waiting_for_capture",
  "paid": true,
  "amount": {
    "value": "2.00",
    "currency": "RUB"
  },
  "created_at": "2018-07-19T11:58:29.196Z",
  "description": "Order No. 72",
  "expires_at": "2018-07-26T11:58:32.019Z",
  "metadata": {},
  "payment_method": {
    "type": "apple_pay",
    "id": "22e290a5-000f-5000-9000-13324c06cacb",
    "saved": false
  },
  "test": false
}

Send the request for creating a payment to Yandex.Checkout, set the apple_pay type and the Apple Pay cryptogram (paymentData) in the payment_method_data object.

Step 3. Capture the payment

Capture the payment using the capture method. After that, the payment status will change to succeeded.

Google Pay

To accept a payment made using the Google Pay cryptogram, you need to:

  1. Obtain payment data.
  2. Create a payment.
  3. Capture the payment.

Step 1. Obtain payment data

Generate an Google Pay cryptogram (paymentMethodToken) on the user's device and obtain the Google Transaction ID (googleTransactionId) by following the instructions on using Google Pay for Android.

Set the following tokenization parameters when creating the PaymentDataRequest object:

Tokenization parameter Value
type PAYMENT_METHOD_TOKENIZATION_TYPE_PAYMENT_GATEWAY
gateway yandexcheckout
gatewayMerchantId Shop ID (shopId in the Merchant Profile)

Step 2. Create a payment

Example of request for a creating payment with the Google Pay cryptogram

curl https://payment.yandex.net/api/v3/payments \
  -X POST \
  -u <Shop ID>:<Secret Key> \
  -H 'Idempotence-Key: <Idempotence Key>' \
  -H 'Content-Type: application/json' \
  -d ' {
        "amount": {
          "value": "2.00",
          "currency": "RUB"
        },
        "payment_method_data":{
          "type": "google_pay",
          "google_transaction_id": "<googleTransactionId>",
          "payment_method_token": "<paymentMethodToken>"
        },
        "description": "Order No. 72"
      }'
<?php
    $client->createPayment(
        array(
            'amount' => array(
                'value' => 2,
                'currency' => 'RUB',
            ),
            'payment_method_data' => array(
                'type' => 'google_pay',
                'google_transaction_id' => '<googleTransactionId>',
                'payment_method_token' => '<paymentMethodToken>',
            ),
            'description' => 'Order No. 72',
        ),
        uniqid('', true)
    );
?>
payment = Payment.create({
    "amount": {
        "value": "2.00",
        "currency": "RUB"
    },
    "payment_method_data": {
        "type": "google_pay",
        "google_transaction_id": "<googleTransactionId>",
        "payment_method_token": "<paymentMethodToken>"
    },
    "description": "Order No. 72"
})

Example of the created Payment object

{
  "id": "22f504f4-000f-5000-8000-10d80496bbca",
  "status": "waiting_for_capture",
  "paid": true,
  "amount": {
    "value": "2.00",
    "currency": "RUB"
  },
  "created_at": "2018-08-02T11:55:33.562Z",
  "description": "Order No. 72",
  "expires_at": "2018-08-09T11:55:36.108Z",
  "metadata": {},
  "payment_method": {
    "type": "google_pay",
    "id": "22f504f4-000f-5000-8000-10d80496bbca",
    "saved": false
  },
  "test": false
}

Send the request for creating a payment to Yandex.Checkout, set the google_pay type, the Google Pay cryptogram (payment_method_token), and the Google Transaction ID (google_transaction_id) in the payment_method_data object.

Step 3. Capture the payment

Capture the payment using the capture method. After that, the payment status will change to succeeded.

QIWI Wallet

Example of request to create a payment to be made from a QIWI wallet

curl https://payment.yandex.net/api/v3/payments \
  -X POST \
  -u <Shop ID>:<Secret Key> \
  -H 'Idempotence-Key: <Idempotence Key>' \
  -H 'Content-Type: application/json' \
  -d '{
        "amount": {
          "value": "2.00",
          "currency": "RUB"
        },
        "payment_method_data": {
          "type": "qiwi",
          "phone": "79000000000"
        },
        "confirmation": {
          "type": "redirect",
          "return_url": "https://www.merchant-website.com/return_url"
        },
        "description": "Order No. 72"
      }'
<?php
    $client->createPayment(
        array(
            'amount' => array(
                'value' => 2,
                'currency' => 'RUB',
            ),
            'payment_method_data' => array(
                'type' => 'qiwi',
                'phone' => '79000000000',
            ),
            'confirmation' => array(
                'type' => 'redirect',
                'return_url' => 'https://www.merchant-website.com/return_url',
            ),
            'description' => 'Order No. 72',
        ),
        uniqid('', true)
    );
?>
payment = Payment.create({
    "amount": {
        "value": "2.00",
        "currency": "RUB"
    },
    "payment_method_data": {
        "type": "qiwi",
        "phone": "79000000000"
    },
    "confirmation": {
        "type": "redirect",
        "return_url": "https://www.merchant-website.com/return_url"
    },
    "description": "Order No. 72"
})

Example of the created Payment object

{
  "id": "22c5d258-000f-5000-a000-1c541a0670fc",
  "status": "pending",
  "paid": false,
  "amount": {
    "value": "2.00",
    "currency": "RUB"
  },
  "confirmation": {
    "type": "redirect",
    "confirmation_url": "https://w.qiwi.com/order/external/main.action?successUrl=https%3A%2F%2Fwww.merchant-website.com%2Freturn_url&failUrl=https%3A%2F%2Fwww.merchant-website.com%2Freturn_url&shop=474093&transaction=62059088b185a4408118654c31894e8bQW"
  },
  "created_at": "2018-06-27T16:43:04.184Z",
  "description": "Order No. 72",
  "metadata": {},
  "payment_method": {
    "type": "qiwi",
    "id": "22c5d258-000f-5000-a000-1c541a0670fc",
    "saved": false
  },
  "test": false
}

To accept a payment made from a QIWI wallet, you need to create a payment with the qiwi payment method and implement the Redirect confirmation scenario.

  1. Create a payment:
    • in the payment_method_data object, set the qiwi type and specify the phone number used for registering the QIWI wallet (if available);
    • in the confirmation object, set the redirect type and specify the URL of the page on your side that the user will be redirected to after completing the payment (in the return_url parameter).
  2. Redirect the user to the payment page (you will receive the URL in the confirmation_url parameter).
  3. Wait for the user to confirm the payment: you will receive a notification from Yandex.Checkout. You can also send periodic requests to receive payment information.
  4. Capture the payment using the capture method.

Webmoney

Example of request to create a payment to be made via Webmoney

curl https://payment.yandex.net/api/v3/payments \
  -X POST \
  -u <Shop ID>:<Secret Key> \
  -H 'Idempotence-Key: <Idempotence Key>' \
  -H 'Content-Type: application/json' \
  -d '{
        "amount": {
          "value": "2.00",
          "currency": "RUB"
        },
        "payment_method_data": {
          "type": "webmoney"
        },
        "confirmation": {
          "type": "redirect",
          "return_url": "https://www.merchant-website.com/return_url"
        },
        "description": "Order No. 72"
      }'
<?php
    $client->createPayment(
        array(
            'amount' => array(
                'value' => 2,
                'currency' => 'RUB',
            ),
            'payment_method_data' => array(
                'type' => 'webmoney',
            ),
            'confirmation' => array(
                'type' => 'redirect',
                'return_url' => 'https://www.merchant-website.com/return_url',
            ),
            'description' => 'Order No. 72',
        ),
        uniqid('', true)
    );
?>
payment = Payment.create({
    "amount": {
        "value": "2.00",
        "currency": "RUB"
    },
    "payment_method_data": {
        "type": "webmoney"
    },
    "confirmation": {
        "type": "redirect",
        "return_url": "https://www.merchant-website.com/return_url"
    },
    "description": "Order No. 72"
})

Example of the created Payment object

{
  "id": "22c5d32a-000f-5000-a000-176b8fb6c8a9",
  "status": "pending",
  "paid": false,
  "amount": {
    "value": "2.00",
    "currency": "RUB"
  },
  "confirmation": {
    "type": "redirect",
    "confirmation_url": "https://merchant.webmoney.ru/lmi/payment.asp?gid=007A174F-3EE6-48B6-80D9-4E2406780E23"
  },
  "created_at": "2018-06-27T16:46:34.782Z",
  "description": "Order No. 72",
  "metadata": {},
  "payment_method": {
    "type": "webmoney",
    "id": "22c5d32a-000f-5000-a000-176b8fb6c8a9",
    "saved": false
  },
  "test": false
}

To accept a payment made via Webmoney, you need to create a payment with the webmoney payment method and implement the Redirect confirmation scenario.

  1. Create a payment:
    • in the payment_method_data object, set the webmoney type;
    • in the confirmation object, set the redirect type and specify the URL of the page on your side that the user will be redirected to after completing the payment (in the return_url parameter).
  2. Redirect the user to the payment page (you will receive the URL in the confirmation_url parameter).
  3. Wait for the user to confirm the payment: you will receive a notification from Yandex.Checkout. You can also send periodic requests to receive payment information.
  4. Capture the payment using the capture method.

Direct carrier billing

Example of request to create a payment to be made via direct carrier billing

curl https://payment.yandex.net/api/v3/payments \
  -X POST \
  -u <Shop ID>:<Secret Key> \
  -H 'Idempotence-Key: <Idempotence Key>' \
  -H 'Content-Type: application/json' \
  -d '{
        "amount": {
          "value": "2.00",
          "currency": "RUB"
        },
        "payment_method_data": {
          "type": "mobile_balance",
          "phone": "79000000000"
        },
        "confirmation": {
          "type": "external"
        },
        "description": "Order No. 72"
      }'
<?php
    $client->createPayment(
        array(
            'amount' => array(
                'value' => 2,
                'currency' => 'RUB',
            ),
            'payment_method_data' => array(
                'type' => 'mobile_balance',
                'phone' => '79000000000',
            ),
            'confirmation' => array(
                'type' => 'external',
            ),
            'description' => 'Order No. 72',
        ),
        uniqid('', true)
    );
?>
payment = Payment.create({
    "amount": {
        "value": "2.00",
        "currency": "RUB"
    },
    "payment_method_data": {
        "type": "mobile_balance",
        "phone": "79000000000"
    },
    "confirmation": {
        "type": "external"
    },
    "description": "Order No. 72"
})

Example of the created Payment object

{
  "id": "22c80e01-000f-5000-a000-14ce15eb7b74",
  "status": "pending",
  "paid": false,
  "amount": {
    "value": "2.00",
    "currency": "RUB"
  },
  "confirmation": {
    "type": "external"
  },
  "created_at": "2018-06-29T09:22:09.367Z",
  "description": "Order No. 72",
  "metadata": {},
  "payment_method": {
    "type": "mobile_balance",
    "id": "22c80e01-000f-5000-a000-14ce15eb7b74",
    "saved": false
  },
  "test": false
}

To accept a payment made via direct carrier billing, you need to create a payment with the mobile_balance payment method and implement the External confirmation scenario.

  1. Create a payment:
    • in the payment_method_data object, set the mobile_balance type and specify the phone number that will be used for making the payment;
    • in the confirmation object, set the external type.
  2. Inform the user that they need to confirm the payment.
  3. Wait for the user to confirm the payment: you will receive a notification from Yandex.Checkout. You can also send periodic requests to receive payment information.
  4. Capture the payment using the capture method.

Cash

Example of request for a cash payment

curl https://payment.yandex.net/api/v3/payments \
  -X POST \
  -u <Shop ID>:<Secret Key> \
  -H 'Idempotence-Key: <Idempotence Key>' \
  -H 'Content-Type: application/json' \
  -d '{
        "amount": {
          "value": "2.00",
          "currency": "RUB"
        },
        "payment_method_data": {
          "type": "cash",
          "phone": "79000000000"
        },
        "confirmation": {
          "type": "redirect",
          "return_url": "https://www.merchant-website.com/return_url"
        },
        "description": "Order No. 72"
      }'
<?php
    $client->createPayment(
        array(
            'amount' => array(
                'value' => 2,
                'currency' => 'RUB',
            ),
            'payment_method_data' => array(
                'type' => 'cash',
                'phone' => '79000000000',
            ),
            'confirmation' => array(
                'type' => 'redirect',
                'return_url' => 'https://www.merchant-website.com/return_url',
            ),
            'description' => 'Order No. 72',
        ),
        uniqid('', true)
    );
?>
payment = Payment.create({
    "amount": {
        "value": "2.00",
        "currency": "RUB"
    },
    "payment_method_data": {
        "type": "cash",
        "phone": "79000000000"
    },
    "confirmation": {
        "type": "redirect",
        "return_url": "https://www.merchant-website.com/return_url"
    },
    "description": "Order No. 72"
})

Example of the created Payment object

{
  "id": "22c5d3e2-000f-5000-8000-10a783a9392b",
  "status": "pending",
  "paid": false,
  "amount": {
    "value": "2.00",
    "currency": "RUB"
  },
  "confirmation": {
    "type": "redirect",
    "confirmation_url": "https://money.yandex.ru/api-pages/v2/payment-confirm/cash?orderId=22c5d3e2-000f-5000-8000-10a783a9392b"
  },
  "created_at": "2018-06-27T16:49:38.669Z",
  "description": "Order No. 72",
  "metadata": {},
  "payment_method": {
    "type": "cash",
    "id": "22c5d3e2-000f-5000-8000-10a783a9392b",
    "saved": false
  },
  "test": false
}

To accept a cash payment made via a payment kiosk or at a partner's office, you need to create a payment with the cash payment method and implement the Redirect confirmation scenario.

  1. Create a payment:
    • in the payment_method_data object, set the cash type and specify the user's phone number (if available) to send the payment confirmation code to;
    • in the confirmation object, set the redirect type and specify the URL of the page on your side that the user will be redirected to after completing the payment (in the return_url parameter).
  2. Redirect the user to the payment page (you will receive the URL in the confirmation_url parameter).
  3. Wait for the user to confirm the payment: you will receive a notification from Yandex.Checkout. You can also send periodic requests to receive payment information.
  4. Capture the payment using the capture method.

Installments

Example of request to create a payment to be made in parts (on an installment plan)

curl https://payment.yandex.net/api/v3/payments \
  -X POST \
  -u <Shop ID>:<Secret Key> \
  -H 'Idempotence-Key: <Idempotence Key>' \
  -H 'Content-Type: application/json' \
  -d '{
        "amount": {
          "value": "2.00",
          "currency": "RUB"
        },
        "payment_method_data": {
          "type": "installments"
        },
        "confirmation": {
          "type": "redirect",
          "return_url": "https://www.merchant-website.com/return_url"
        },
        "description": "Order No. 72"
      }'
<?php
    $client->createPayment(
        array(
            'amount' => array(
                'value' => 2,
                'currency' => 'RUB',
            ),
            'payment_method_data' => array(
                'type' => 'installments',
            ),
            'confirmation' => array(
                'type' => 'redirect',
                'return_url' => 'https://www.merchant-website.com/return_url',
            ),
            'description' => 'Order No. 72',
        ),
        uniqid('', true)
    );
?>
payment = Payment.create({
    "amount": {
        "value": "2.00",
        "currency": "RUB"
    },
    "payment_method_data": {
        "type": "installments"
    },
    "confirmation": {
        "type": "redirect",
        "return_url": "https://www.merchant-website.com/return_url"
    },
    "description": "Order No. 72"
})

Example of the created Payment object

{
  "id": "22c5d4d1-000f-5000-a000-1060585f5f12",
  "status": "pending",
  "paid": false,
  "amount": {
    "value": "2.00",
    "currency": "RUB"
  },
  "confirmation": {
    "type": "redirect",
    "confirmation_url": "https://money.yandex.ru/credit/order/step/options?orderId=22c5d4d1-000f-5000-a000-1060585f5f12"
  },
  "created_at": "2018-06-27T16:53:37.322Z",
  "description": "Order No. 72",
  "metadata": {},
  "payment_method": {
    "type": "installments",
    "id": "22c5d4d1-000f-5000-a000-1060585f5f12",
    "saved": false
  },
  "test": false
}

To accept partial payments (made on an installment plan), you need to create a payment with the installments payment type and implement the Redirect confirmation scenario.

  1. Create a payment:
    • in the payment_method_data object, set the installments type;
    • in the confirmation object, set the redirect type and specify the URL of the page on your side that the user will be redirected to after completing the payment (in the return_url parameter).
  2. Redirect the user to the payment page (you will receive the URL in the confirmation_url parameter).
  3. Wait for the user to confirm the payment: you will receive a notification from Yandex.Checkout. You can also send periodic requests to receive payment information.
  4. Capture the payment using the capture method.

Sberbank Business Online

Example of request for a payment via Sberbank Business Online

curl https://payment.yandex.net/api/v3/payments \
  -X POST \
  -u <Shop ID>:<Secret Key> \
  -H 'Idempotence-Key: <Idempotence Key>' \
  -H 'Content-Type: application/json' \
  -d '{
        "amount": {
          "value": "50.00",
          "currency": "RUB"
        },
        "payment_method_data": {
          "type": "b2b_sberbank",
          "payment_purpose": "Payment for order No. 2134",
          "vat_data": {
            "type": "calculated",
            "rate": 18,
            "amount": {
              "value": 9.00,
              "currency": "RUB"
            }
          }
        },
        "confirmation": {
          "type": "redirect"
        },
        "capture": true,
        "description": "Payment for order No. 2134"
      }'
<?php
    $client->createPayment(
        array(
            'amount' => array(
                'value' => 50,
                'currency' => 'RUB',
            ),
            'payment_method_data' => array(
                'type' => 'b2b_sberbank',
                'payment_purpose' => 'Payment for order No. 2134',
                'vat_data' => array(
                    'type' => 'calculated',
                    'rate' => 18,
                    'amount' => array(
                        'value' => 9,
                        'currency' => 'RUB',
                    ),
                ),
            ),
            'confirmation' => array(
                'type' => 'redirect',
            ),
            'capture' => true,
            'description' => 'Payment for order No. 2134',
        ),
        uniqid('', true)
    );
?>
payment = Payment.create({
    "amount": {
        "value": "50.00",
        "currency": "RUB"
    },
    "payment_method_data": {
      "type": "b2b_sberbank",
      "payment_purpose": "Payment for order No. 2134",
      "vat_data": {
        "type": "calculated",
        "rate": 18,
        "amount": {
          "value": 9.00,
          "currency": "RUB"
        }
      }
    },
    "confirmation": {
        "type": "redirect"
    },
    "capture": true,
    "description": "Payment for order No. 2134"
})

Example of the created Payment object

{
  "id": "1da5c87d-0984-50e8-a7f3-8de646dd9ec9",
  "status": "pending",
  "paid": false,
  "amount": {
    "value": "50.00",
    "currency": "RUB"
  },
  "confirmation": {
    "type": "redirect",
    "confirmation_url": "http://b2bsberbank.confirmation.url?orderId=1da5c87d-0984-50e8-a7f3-8de646dd9ec9"
  },
  "created_at": "2017-06-29T22:20:00.000Z",
  "description": "Payment for order No. 2134",
  "metadata": {},
  "payment_method": {
    "id": "1da5c87d-0984-50e8-a7f3-8de646dd9ec9",
    "type": "b2b_sberbank",
    "saved": false,
    "payment_purpose": "Payment for order No. 2134",
    "vat_data": {
      "type": "calculated",
      "amount": {
        "value": "9.00",
        "currency": "RUB"
      },
      "rate": "18"
    }
  },
  "test": false,
}

Example of the created Payment object with the succeeded status

{
  "id": "1da5c87d-0984-50e8-a7f3-8de646dd9ec9",
  "status": "succeeded",
  "paid": true,
  "amount": {
    "value": "50.00",
    "currency": "RUB"
  },
  "captured_at": "2017-06-29T22:30:00.000Z",
  "created_at": "2017-06-29T22:20:00.000Z",
  "description": "Payment for order No. 2134",
  "metadata": {},
  "payment_method": {
    "id": "1da5c87d-0984-50e8-a7f3-8de646dd9ec9",
    "type": "b2b_sberbank",
    "saved": false,
    "payer_bank_details": {
      "account": "40702810355002135468",
      "address": "17 Severovokzalny ul., bld. 2, apt. 16, Saint Petersburg 197111, Russian Federation",
      "bank_bik": "044030653",
      "bank_branch": "SEVERO-ZAPADNY BANK OF SBERBANK OF RF",
      "bank_name": "SEVERO-ZAPADNY BANK PAO SBERBANK",
      "full_name": "Limited liability company 'Organization'",
      "inn": "7728662610",
      "kpp": "783501610",
      "short_name": "'Organization' LLC"
    },
    "payment_purpose": "Payment for order No. 2134",
    "vat_data": {
      "type": "calculated",
      "amount": {
        "value": "9.00",
        "currency": "RUB"
      },
      "rate": "18"
    }
  },
  "refunded_amount": {
    "value": "0.00",
    "currency": "RUB"
  },
  "test": false
}

This payment method allows you to accept payments from legal entities and entrepreneurs that use the Sberbank Business Online service.

To activate this payment method, you need to:

To accept payments via Sberbank Business Online, you will need to create a payment with the b2b_sberbank payment type and implement the Redirect confirmation scenario.

  1. Create a payment:
    • in the payment_method_data object, set the b2b_sberbank, specify the payment purpose, and provide the information about VAT;
    • in the confirmation object, set the redirect type and specify the URL of the page on your side that the user will be redirected to after completing the payment (in the return_url parameter).
    • in the capture parameter, set true value so the payment status will automatically change to succeeded after the payment.
  2. Redirect the user to the payment page (you will receive the URL in the confirmation_url parameter).
  3. Wait for the user to confirm the payment: you will receive a notification from Yandex.Checkout. You can also send periodic requests to receive payment information.
  4. Capture the payment using the capture method.

Payments made under 54-FZ

The Yandex.Checkout solution for carrying out transactions under Federal Law No. 54-FZ helps set up the interaction with your online sales register, i.e. the process of sending a request to form a receipt (with FFD 1.05 support) to the online sales register and receiving the result.

Onboarding

  1. Buy or rent an online sales register from one of our partners.
  2. Enter into an agreement with the fiscal data operator (OFD).
  3. Get your qualified electronic signature (KEP).
  4. Register your online sales register with the tax office (in Personal Office for Legal Entities).
  5. Fill in the settings for carrying out transactions under Federal Law No. 54-FZ in your Yandex.Checkout Merchant Profile.
  6. Send the data for receipt formation in the payment requests to Yandex.Checkout.

Transition to FFD 1.05

On 1 January 2019, a new fiscal data format (FFD 1.05) will be adopted requiring the inclusion of additional parameters for every product in a receipt:

If you already use the Yandex.Checkout solution, you will need to transition to the new format. The transition procedure depends on your online sales register.

ATOL Online

  1. First, complete the implementation process by the Yandex.Checkout API and start sending new parameters (payment_subject and payment_mode).
  2. Once you finish the configuration, switch to FFD 1.05 from your ATOL personal dashboard.

Orange Data, ModulKassa and Business.ru Online Receipts

You can start sending the new data. If you won't send them, your online sales register will add default values on its side.

Processing payments

Selecting the method of sending the receipt to the online sales register

Before you start carrying out transactions, you should visit the settings section of your Yandex.Checkout Merchant Profile and select the method of sending the receipt to the online sales register:

Processing payments in accordance with 54-FZ

Example of payment request with receipt parameters

<?php
    $client->createPayment(
        array(
            "amount" => array(
                "value" => "600.00",
                "currency" => "RUB"
            ),
            "confirmation" => array(
                "type" => "redirect",
                "return_url" => "https://www.merchant-website.com/return_url"
            ),
            "receipt" => array(
                "phone" => "79000000000",
                "items" => array(
                    array(
                        "description" => "Product name 1",
                        "quantity" => "2.00",
                        "amount" => array(
                            "value" => "250.00",
                            "currency" => "RUB"
                        ),
                        "vat_code" => "2",
                        "payment_mode" => "full_prepayment",
                        "payment_subject" => "commodity"
                    ),
                    array(
                        "description" => "Product name 2",
                        "quantity" => "1.00",
                        "amount" => array(
                            "value" => "100.00",
                            "currency" => "RUB"
                        ),
                        "vat_code" => "2",
                        "payment_mode" => "full_prepayment",
                        "payment_subject" => "commodity"
                    )
                )
            )
        ),
        uniqid('', true)
    );
?>
curl https://payment.yandex.net/api/v3/payments \
  -X POST \
  -u <Shop ID>:<Secret Key> \
  -H 'Idempotence-Key: <Idempotence Key>' \
  -H 'Content-Type: application/json' \
  -d '{
        "amount": {
          "value": "600.00",
          "currency": "RUB"
        },
        "confirmation": {
          "type": "redirect",
          "return_url": "https://www.merchant-website.com/return_url"
        },
        "receipt": {
          "phone": "79000000000",
          "items": [
            {
              "description": "Product name 1",
              "quantity": "2.00",
              "amount": {
                "value": "250.00",
                "currency": "RUB"
              },
              "vat_code": "2",
              "payment_mode": "full_prepayment",
              "payment_subject": "commodity"
            },
            {
              "description": "Product name 2",
              "quantity": "1.00",
              "amount": {
                "value": "100.00",
                "currency": "RUB"
              },
              "vat_code": "2",
              "payment_mode": "full_prepayment",
              "payment_subject": "commodity"
            }
          ]
        }
      }'
payment = Payment.create({
    "amount": {
        "value": "600.00",
        "currency": "RUB"
    },
    "confirmation": {
        "type": "redirect",
        "return_url": "https://www.merchant-website.com/return_url"
    },
    "receipt": {
        "phone": "79000000000",
        "items": [
            {
                "description": "Product name 1",
                "quantity": "2.00",
                "amount": {
                    "value": "250.00",
                    "currency": "RUB"
                },
                "vat_code": "2",
                "payment_mode": "full_prepayment",
                "payment_subject": "commodity"
            },
            {
                "description": "Product name 2",
                "quantity": "1.00",
                "amount": {
                    "value": "100.00",
                    "currency": "RUB"
                },
                "vat_code": "2",
                "payment_mode": "full_prepayment",
                "payment_subject": "commodity"
            }
        ]
    },
})

Example of the response

{
  "id": "227cf565-000f-5000-8000-1c9d1c6000fb",
  "status": "succeeded",
  "paid": true,
  "amount": {
    "value": "600.00",
    "currency": "RUB"
  },
  "authorization_details": {
    "rrn": "10000000000",
    "auth_code": "000000"
  },
  "captured_at": "2018-05-03T10:17:31.487Z",
  "created_at": "2018-05-03T10:17:09.337Z",
  "metadata": {},
  "payment_method": {
    "type": "bank_card",
    "id": "227cf565-000f-5000-8000-1c9d1c6000fb",
    "saved": false,
    "card": {
      "first6": "411111",
      "last4": "1111",
      "expiry_month": "01",
      "expiry_year": "2020",
      "card_type": "Visa"
    },
    "title": "Bank card *1111"
  },
  "receipt_registration": "pending",
  "recipient": {
    "account_id": "67192",
    "gateway_id": "352780"
  },
  "refunded_amount": {
    "value": "600.00",
    "currency": "RUB"
  }
}
  1. Create a payment and specify the parameters required for receipt formation in the receipt object. Yandex.Checkout will send these parameters to your online sales register.

  2. If necessary, wait until the payment status changes to waiting_for_capture, then capture the payment.

Please note: You can find out if the receipt is formed by the receipt_registration parameter value. If necessary, you can generate a receipt manually.

If the payment status changes to canceled (for example, if you don't capture it within the alloted time), Yandex.Checkout will generate a refund receipt and send it to the user.

Partial capture

Example of request with a partial capture and a new receipt

<?php
    $client->capturePayment(
        array(
            "amount" => array(
                "value" => "500.00",
                "currency" => "RUB"
            ),
            "receipt" => array(
                "phone" => "79000000000",
                "items" => array(
                    array(
                        "description" => "Product name",
                        "quantity" => "2.00",
                        "amount" => array(
                            "value" => "250.00",
                            "currency" => "RUB"
                        ),
                        "vat_code" => "2"
                    )
                )
            )
        ),
        uniqid('', true)
    );
?>
curl https://payment.yandex.net/api/v3/payments/<payment-id>/capture \
  -X POST \
  -u <Shop ID>:<Secret Key> \
  -H 'Idempotence-Key: <Idempotence Key>' \
  -H 'Content-Type: application/json' \
  -d '{
        "amount": {
          "value": "500.00",
          "currency": "RUB"
        },
        "receipt": {
          "phone": "79000000000",
          "items": [
            {
              "description": "Product name",
              "quantity": "2.00",
              "amount": {
                "value": "250.00",
                "currency": "RUB"
              },
              "vat_code": "2"
            }
          ]
        }
      }'
payment = Payment.capture({
    "amount": {
        "value": "500.00",
        "currency": "RUB"
    },
    "receipt": {
        "phone": "79000000000",
        "items": [
            {
                "description": "Product name",
                "quantity": "2.00",
                "amount": {
                    "value": "250.00",
                    "currency": "RUB"
                },
                "vat_code": "2"
            }
        ]
    },
})

Specify the following in the request in case you want to the change the payment amount during capture:

Refund

Example of refund request with the receipt data

<?php
    $client->createRefund(
        array(
            "payment_id" => "<Refunded payment ID>",
            "amount" => array(
                "value" => "600.00",
                "currency" => "RUB"
            ),
            "receipt" => array(
                "phone" => "79000000000",
                "items" => array(
                    array(
                        "description" => "Product name 1",
                        "quantity" => "2.00",
                        "amount" => array(
                            "value" => "250.00",
                            "currency" => "RUB"
                        ),
                        "vat_code" => "2"
                    ),
                     array(
                        "description" => "Product name 2",
                        "quantity" => "1.00",
                        "amount" => array(
                            "value" => "100.00",
                            "currency" => "RUB"
                        ),
                        "vat_code" => "2"
                    )
                )
            ),

        ),
        uniqid('', true)
    );
?>
curl https://payment.yandex.net/api/v3/refunds \
  -X POST \
  -u <Shop ID>:<Secret Key> \
  -H 'Idempotence-Key: <Idempotence Key>' \
  -H 'Content-Type: application/json' \
  -d '{
        "payment_id": "<Refunded payment ID>",
        "amount": {
          "value": "600.00",
          "currency": "RUB"
        },
        "receipt": {
          "phone": "79000000000",
          "items": [
            {
              "description": "Product name 1",
              "quantity": "2.00",
              "amount": {
                "value": "250.00",
                "currency": "RUB"
              },
              "vat_code": "2"
            },
            {
              "description": "Product name 2",
              "quantity": "1.00",
              "amount": {
                "value": "100.00",
                "currency": "RUB"
              },
              "vat_code": "2"
            }
          ]
        }
      }'
refund = Refund.create({
    "payment_id": "<Refunded payment ID>",
    "amount": {
        "value": "600.00",
        "currency": "RUB"
    },
    "receipt": {
        "phone": "79000000000",
        "items": [
            {
                "description": "Product name 1",
                "quantity": "2.00",
                "amount": {
                    "value": "250.00",
                    "currency": "RUB"
                },
                "vat_code": "2"
            },
            {
                "description": "Product name 2",
                "quantity": "1.00",
                "amount": {
                    "value": "100.00",
                    "currency": "RUB"
                },
                "vat_code": "2"
            }
        ]
    },
})
  1. Create a new refund and specify the parameters required for refund receipt formation in the receipt object. In case of a full refund, they will be identical to the initial payment's parameters. In case of a partial refund, you need to specify only the products that will be returned.

  2. As soon as the refund is formed, we will send the receipt formation data to the online sales register.

Possible parameter values

Below are the lists of possible value for the following parameters of the receipt object:

Tax systems codes

Tax system code is set in the tax_system_code parameter in the receipt object. Possible value is a number from 1 to 6.

Code Tax system
1 General tax system
2 Simplified (STS, income)
3 Simplified (STS, income with costs deducted)
4 Unified tax on imputed income (ENVD)
5 Unified agricultural tax (ESN)
6 Patent Based Tax System

VAT rates codes

VAT rate code is set in the vat_code parameter in the receipt object. Possible value is a number from 1 to 6.

Code VAT rate
1 VAT not included
2 0% VAT rate
3 10% VAT rate
4 20% receipt's VAT rate
5 10/110 receipt's estimate VAT rate
6 20/120 receipt's estimate VAT rate

Payment subject attributes

The payment subject attribute is set in the payment_subject parameter of the receipt object. Possible values:

Value Description
commodity Product
excise Excisable goods
job Job
service Service
gambling_bet Gambling bet
gambling_prize Gambling winnings
lottery Lottery ticket
lottery_prize Lottery winnings
intellectual_activity Intellectual property
payment Payment
agent_commission Agent's commission
composite Several subjects
another Other

Payment method attributes

The payment method attribute is set in the payment_mode parameter of the receipt object. Possible values:

Value Description
full_prepayment Full prepayment
partial_prepayment Partial prepayment
advance Advance payment
full_payment Full payment
partial_payment Partial payment and loan
credit Loan
credit_payment Loan repayment

Notifications

Notifications help you to stay informed on everything that is going on with your transactions.

How to set up

If you want to receive notifications, you need to subscribe to them in your Merchant Profile. Visit the HTTP notifications section in the store settings and specify the URL for notifications and the events that you want to track.

Events

Example of the payment.waiting_for_capture notification body

{
  "type": "notification",
  "event": "payment.waiting_for_capture",
  "object": {
    "id": "22d6d597-000f-5000-9000-145f6df21d6f",
    "status": "waiting_for_capture",
    "paid": true,
    "amount": {
      "value": "2.00",
      "currency": "RUB"
    },
    "authorization_details": {
      "rrn": "10000000000",
      "auth_code": "000000"
    },
    "created_at": "2018-07-10T14:27:54.691Z",
    "description": "Order No. 72",
    "expires_at": "2018-07-17T14:28:32.484Z",
    "metadata": {},
    "payment_method": {
      "type": "bank_card",
      "id": "22d6d597-000f-5000-9000-145f6df21d6f",
      "saved": false,
      "card": {
        "first6": "555555",
        "last4": "4444",
        "expiry_month": "07",
        "expiry_year": "2021",
        "card_type": "MasterCard"
      },
      "title": "Bank card *4444"
    },
    "test": false
  }
}

Right now Yandex.Checkout can send out the notifications on the following events:

As soon as the payment or refund changes the status, you will receive the notification to the URL specified during the set up. It will contain all the information on the object available at the moment of the event.

When to use

Notifications should be used for asynchronous payment processes, for example, when the user confirms the payment with the online bank or deposits cash via payment kiosk. The duration of the payment process in these scenarios ranges from a couple of minutes to a few hours.

In such scenario, you can:

How to respond

Respond with 200 HTTP code to confirm you've received the notification. We'll ignore everything contained in the header and body of the response. Replies with any other HTTP codes are considered invalid, so we'll continue to send notifications for 24 hours since the initial one.

Check the status of the object before responding to the notification: request the information using GET method. This will help avoiding the situations where somebody sends you a false notification of the successful payment.

How to process using the SDK

How to get data from a POST request

<?php
  $source = file_get_contents('php://input');
  $json = json_decode($source, true);
?>
How to create a notification class object
NotificationSucceeded или NotificationWaitingForCapture

<?php
try {
  $notification = ($json['event'] === YandexCheckout\Model\NotificationEventType::PAYMENT_SUCCEEDED)
    ? new NotificationSucceeded($json)
    : new NotificationWaitingForCapture($json);
} catch (Exception $e) {
  // Processing errors from incorrect data
}
?>
How to obtain Payment object

<?php
  $payment = $notification->getObject();
?>
# How to get data from a POST request

import json
from django.http import HttpResponse

def my_webhook_handler(request):
    event_json = json.loads(request.body)
    return HttpResponse(status=200)
# How to create a notification class object
# NotificationSucceeded или NotificationWaitingForCapture

try:
    notification_object = WebhookNotification(event_json)
except Exception:
    # processing errors

# How to obtain Payment object
   payment = notification_object.object
# example of notification processing

import json
from django.http import HttpResponse
from yandex_checkout import WebhookNotification


def my_webhook_view(request):
    event_json = json.loads(request.body)
    try:
        notification_object = WebhookNotification(event_json)
    except Exception:

    return HttpResponse(status=200)

You can use our libraries to process notifications:

  1. Obtain data from a POST request made by Yandex.Checkout.

  2. Create a notification class object depending on the event.

  3. Obtain the Payment object.

Testing

Demo store

You can check the integration in the demo store before accepting proper payments. The payment process in the demo store is identical to the actual payment process, except the money is not transferred anywhere.

The demo store appears in the Yandex.Checkout Merchant Profile after you fill out the partner questionnaire (and the manager verifies it) and send your technical settings.

The demo store has its own ID and secret key with a test_ prefix — you can issue and view both of them in your Yandex.Checkout Merchant Profile.

More about the demo store

Testing options

You can test the API functionality for the following payment methods:

Payment via a bank card

Payments in the demo store should only be made with test bank cards:

Testing successful scenarios

You can test payments with different types of bank cards:

Number Card type
5555555555554477 MasterCard (with 3-D Secure)
5555555555554444 MasterCard
6759649826438453 Maestro
4111111111111111 Visa
4175001000000017 Visa Electron
370000000000002 American Express
3528000700000000 JCB
36700102000000 Diners Club

Testing unsuccessful scenarios

If you want to test self-initiated payment cancellation, use the cancel method.

If you want to test the cancellation_details parameter for payment cancellation initiated by "external" participants of the payment process or Yandex.Checkout, use test bank cards:

Transaction cancelled by "external" participants of the payment process (payment_network)

Card number Reason behind the payment cancelation
5555555555554592 3d_secure_failed
5555555555554535 call_issuer
5555555555554543 card_expired
5555555555554568 fraud_suspected
5555555555554527 general_decline
5555555555554600 insufficient_funds
5555555555554618 invalid_card_number
5555555555554626 invalid_csc
5555555555554501 issuer_unavailable
5555555555554576 payment_method_limit_exceeded
5555555555554550 payment_method_restricted

Transaction cancelled by Yandex.Checkout (yandex_checkout)

Card number Reason behind the payment cancelation
5555555555554584 country_forbidden
5555555555554634 fraud_suspected

Payment from the Yandex.Money wallet

You don't need a test wallet to test payments via Yandex.Money: transactions in the demo store are carried out without an actual wallet.

Please note: you need to log out of your Yandex.Money account before making a test payment from wallet.

Reports

Yandex.Checkout generates daily reports on successful payments. They are sent to the email address that you specified in the store's settings section of your Yandex.Checkout Merchant Profile (the Address for reports field). A report contains all transactions carried out during a specific date.

There are two ways to receive reports:

Reports on payments from individuals

Fields in the report

Field name Description
Payment ID The unique identifier of a payment in Yandex.Checkout set in the id field at payment creation
Payment amount Amount of the transaction. The decimals are separated by the dot, and there is always two digits after the decimal point. There is no thousands separator
Payment currency The three-letter currency code (RUB is the Russian ruble)
Amount with a deduction of the fee The amount credited to your current account. The decimals are separated by the dot, and there is always two digits after the decimal point. There is no thousands separator
Time of payment The time at which the payment was created in Yandex.Checkout, based on UTC and shown in ISO 8601 format. Example: 2017-11-03T11:52:31.827Z
Payment method ID The number of the Yandex.Money wallet that the payment was made from. Other payment methods are specified by the external account number on Yandex.Checkout's side
Description The value set in the description field at payment creation
Payment type Code of the payment method on Yandex.Checkout's side (not used in requests)

Examples of reports

Fields in the report

Field in the report Description
Payment ID The unique identifier of a payment in Yandex.Checkout set in the id field at payment creation
Payment amount Amount of the transaction. The decimals are separated by the dot, and there is always two digits after the decimal point. There is no thousands separator
Payment currency The three-letter currency code (RUB is the Russian ruble)
Commission amount Amount of the fee charged for payment processing. The decimals are separated by the dot, and there is always two digits after the decimal point. There is no thousands separator
Time of payment The time at which the payment was created in Yandex.Checkout, based on UTC and shown in ISO 8601 format. Example: 2017-11-03T11:52:31.827Z
Payment type Code of the payment method on Yandex.Checkout's side (not used in requests)
Purpose of payment
Full name of the organization
Abbreviated name of the organization
Address of the organization
Taxpayer Identification Number (INN) of the organization
Tax Registration Reason Code (KPP) of the organization
Name of the organization's bank
Branch of the organization's bank
Bank Identification Code (BIC) of the organization's bank
Account number of the organization
Client ID Field for Yandex.Checkout's use

Refund reports

Fields in the report

Field name Description
Refund ID The unique identifier of a refund in Yandex.Checkout set in the id field at refund creation
Payment ID The unique identifier of the initial payment in Yandex.Checkout
Refund amount Amount of the transaction. The decimals are separated by the dot, and there is always two digits after the decimal point. There is no thousands separator
Refund currency The three-letter currency code (RUB is the Russian ruble).
The time at which the refund was credited to the payer's account The time at which the payment was created in Yandex.Checkout, based on UTC and shown in ISO 8601 format. Example: 2017-11-03T11:52:31.827Z
Payment method ID The number of the Yandex.Money wallet that the payment was made from. Other payment methods are set by the external account number on Yandex.Checkout's side
Refund amount in the currency of the product
Payment currency The three-letter currency code (RUB is the Russian ruble)
Payment type Code of the payment method on Yandex.Checkout's side (not used in requests)
Description The value set in the description field at refund creation

Examples of reports