YandexCheckout.js
YandexCheckout.js is a JavaScript library, an extension of the Yandex.Checkout API.
The library allows collecting the users' bank card details on your side without processing it on your servers, meaning the customers will be able to enter their bank card information directly in your system.
Using this library, you can:
  • create forms with custom designs (for example, in your own style and with your own logo);
  • embed them into your system as conveniently as possible;
  • conduct tests on your side and optimize the payment process.
YandexCheckout.js exchanges the data entered by the user for a one-time payment token so that you won’t have to process payment data in your system. You need to include this token to Yandex.Checkout in a request for creating a payment.
 
Initialization
You can only connect to YandexCheckout.js from the 
https://static.yamoney.ru
servers, so that your clients' sensitive data is always safe.
Load the main library to start working with the API.
HTML
<script src="https://static.yamoney.ru/checkout-js/v1/checkout.js"></script>
 
Authentication
Create a unit of YandexCheckout object.
Use the 
YandexCheckout (< Shop ID >)
structure.
< Shop ID >
is the shopId of your store in Yandex.Checkout (issued upon onboarding and can be found in your Yandex.Checkout Merchant Profile).
JavaScript
const checkout = YandexCheckout(<Shop ID>);
After that you can create a YandexCheckout instance and use it to generate a token containing the bank card information.
You can create payments using tokens after making a corresponding request to your Yandex.Checkout manager.
 
Configuration
You can show error messages to your users in Russian and English languages. The default language for error messages is Russian.
ParameterDescriptionTypeValidation
language
Language for user error messages. Possible values:
en
and
ru
string2 characters
JavaScript
const checkout = YandexCheckout(<Shop ID>, {
    language: 'en'
});
 
Tokenization
Generate a payment token containing the bank card data. The token can be used for carrying out transactions using the Yandex.Checkout API.
JavaScript
checkout.tokenize({
    number: document.querySelector('.number').value,
    cvc: document.querySelector('.cvc').value,
    month: document.querySelector('.expiry_month').value,
    year: document.querySelector('.expiry_year').value
}).then(res => {
    if (res.status === 'success') {
        const { paymentToken } = res.data.response;

        return paymentToken;
    }
});
 
Method parameters
ParameterDescriptionTypeValidation
number
Bank card numberstring16 characters, digits only
cvc
CVC2 or CVV2 code, 3 or 4 characters, printed on the back of the cardstring3, 4 characters, digits only
month
Month of the card expiration datestring2 characters, digits only
year
Year of the card expiration datestring2 characters, digits only
Example of valid data
JavaScript
checkout.tokenize({
    number: document.querySelector('.number').value,
    cvc: document.querySelector('.cvc').value,
    month: document.querySelector('.expiry_month').value,
    year: document.querySelector('.expiry_year').value
}).then(response => {
    if (response.status === 'success') {
        const { paymentToken } = response.data.response;

        // eyJlbmNyeXB0ZWRNZXNzYWdlIjoiWlc...
        return paymentToken;
    }
});
Example of invalid data
JavaScript
checkout.tokenize({
    number: document.querySelector('.number').value,
    cvc: document.querySelector('.cvc').value,
    month: document.querySelector('.expiry_month').value,
    year: document.querySelector('.expiry_year').value
}).then(response => {
    if (response.status === 'error') {
        // validation_error
        const { type } = response.error;

        /*
            [
                {
                    code: 'invalid_expiry_month',
                    message: 'Invalid month value'
                },
                {
                    code: 'invalid_cvc',
                    message: 'Invalid CVC value'
                }
            ]
        */
        const { params } = response.error;

        return response;
    }
});
 
Errors
The library returns two types of errors: those related to data validation in the form and those related to YandexCheckout.js performance.
JavaScript
try {
    const checkout = YandexCheckout(); // Missing shopId
} catch(error) {
    // See response format in the Errors section
}
Error notification format
JavaScript
{
    status: 'error',
    error: {
        type: string,
        message: ?string,
        status_code: number,
        code: ?string,
        params: Array<{
            code: string,
            message: string
        }>
    }
}
Validation errors occur when the user enters invalid bank card data: they must be shown to the user.
JavaScript
{
    status: 'error',
    error: {
        type: 'validation_error',
        message: undefined,
        status_code: 400,
        code: undefined,
        params: [
            {
                code: 'invalid_number',
                message: 'Invalid card number'
            },
            {
                code: 'invalid_expiry_month',
                message: 'Invalid month value'
            }
        ]
    }
}
Other errors occur as a result of the problems with the library initialization or the interaction between the library and the Yandex.Checkout server. You don’t have to show these error messages to the user.
JavaScript
{
    status: 'error',
    error: {
        type: 'api_connection_error',
        message: 'Failure to connect to the server',
        status_code: 402,
        code: 'processing_error',
        params: []
    }
}
 
Response codes
Response codeValue
400Validation error
401Authentication error
402Failure to connect to the Yandex.Checkout API
404Resource not found
500Internal server error
YandexCheckout.js supports standard response codes:
  • all codes that start with
    20*
    indicate success;
  • all codes that start with
    40*
    indicate that something went wrong;
  • all codes that start with
    50*
    indicate an unexpected error on Yandex.Checkout’s side.
 
Error types
Error typeValue
authentication_error
Authentication error
api_connection_error
Couldn’t connect to Yandex.Checkout
api_error
Error on Yandex.Checkout’s side
card_error
Something is wrong with the bank card
invalid_request_error
Invalid request data
validation_error
Validation error: invalid value in one of the data input fields
 
Error codes
Error codeValue
invalid_number
Invalid card number
invalid_expiry_month
Invalid month of the card expiration date
invalid_expiry_year
Invalid year of the card expiration date
invalid_cvc
Invalid CVC code
expired_card
The card has expired
card_declined
The card is declined
processing_error
Failure to process the card
missing
Internal server error
 
See also
YandexCheckout UIPayment tokenPayment processNotifications