Checkout.js: using the library — Payment acceptance via the YooMoney API

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.

You can create payments using tokens after making a corresponding request to your YooMoney manager.

Configuration

You can show error messages to your users in Russian and English languages. The default language for error messages is Russian.

Parameter	Description	Type	Validation
language	Language for user error messages. Possible values: `en` and `ru`	string	2 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

Parameter	Description	Type	Validation
number	Bank card number	string	16 characters, digits only
cvc	CVC2 or CVV2 code, 3 or 4 characters, printed on the back of the card	string	3, 4 characters, digits only
month	Month of the card expiration date	string	2 characters, digits only
year	Year of the card expiration date	string	2 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 code	Value
400	Validation error
401	Authentication error
402	Failure to connect to the YooMoney API
404	Resource not found
500	Internal 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 type	Value
authentication_error	Authentication error
api_connection_error	Couldn’t connect to YooMoney
api_error	Error on YooMoney’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 code	Value
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
processing_error	Failure to process the card
missing	Internal server error