YooMoney API
Guides
Old versions of the API
Help
Sign up for YooMoney
Using Checkout.js
 
Initialization
You can only connect to Checkout.js from the https://static.yoomoney.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.yoomoney.ru/checkout-js/v1/checkout.js"></script>
Authentication
Create a unit of YooMoneyCheckout object.
Use the YooMoneyCheckout (<Shop ID>) structure.
<Shop ID> is the shopId of your store in YooMoney (issued upon onboarding and can be found in your YooMoney Merchant Profile).
JavaScript
const checkout = YooMoneyCheckout(<Shop ID>);
After that you can create a YooMoneyCheckout instance and use it to generate a token containing the bank card information.
Configuration
You can show error messages to your users in Russian and English languages. The default language for error messages is Russian.
ParameterDescriptionTypeValidation
languageLanguage for user error messages. Possible values: en and rustring2 characters
JavaScript
const checkout = YooMoneyCheckout(<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 YooMoney 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
numberBank card numberstring16 characters, digits only
cvcCVC2 or CVV2 code, 3 or 4 characters, printed on the back of the cardstring3, 4 characters, digits only
monthMonth of the card expiration datestring2 characters, digits only
yearYear 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 Checkout.js performance.
JavaScript
try {
    const checkout = YooMoneyCheckout(); // 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 YooMoney 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 YooMoney API
404Resource not found
500Internal server error
Checkout.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 YooMoney’s side.
Error types
Error typeValue
authentication_errorAuthentication error
api_connection_errorCouldn’t connect to YooMoney
api_errorError on YooMoney’s side
card_errorSomething is wrong with the bank card
invalid_request_errorInvalid request data
validation_errorValidation error: invalid value in one of the data input fields
Error codes
Error codeValue
invalid_numberInvalid card number
invalid_expiry_monthInvalid month of the card expiration date
invalid_expiry_yearInvalid year of the card expiration date
invalid_cvcInvalid CVC code
processing_errorFailure to process the card
missingInternal server error
See also