YooMoney API
Guides
Old versions of the API
Help
Sign up for YooMoney
Reference for parameters, methods, and error codes
This reference describes:
  • Parameters specified during widget initialization;
  • Errors related to widget initialization;
  • Widget’s methods;
  • Widget events.
 
Reference of parameters for widget initialization
Description of parameters that must be sent to the instance of the YooMoneyCheckoutWidget class on the payment page for widget initialization.
ParameterTypeMandatoryDescription
confirmation_tokenstringRequiredYooMoney token for initializing the widget. To issue a token, create a payment
return_url
string
Optional
Address of the page for redirecting the user after the payment is completed. The address must be absolute (with the protocol and website domain specified). Example: https://example.com/return_url.
If the URL isn't specified, you need to handle the payment process events
error_callback(error) => voidRequiredCallback function that accepts the initialization error code
customizationobjectOptionalPayment form customization. Right now, you can customize the color scheme, set up the way, how the widget is displayed and the display of payment methods.
modal
boolean
Optional
Sent in customization.
Configuring how the widget is displayed. Possible values:
  • true — the payment form is displayed in a pop-up window;
  • false — the payment form should be posted on the payment page.
colors
object
Optional
Sent in customization.
Color scheme customization. Colors that must be changed in the payment form’s interface are sent in the object.
payment_methods
array
Optional
Sent in customization.
  • bank_card — bank card;
  • yoo_money — YooMoney (wallet, linked cards, and bonus points);
  • mir_pay — Mir Pay;
  • sberbank — SberPay;
  • sbp — FPS (Faster Payments System).
  • tinkoff_bank — Tinkoff Pay.
Reference for color scheme configuration parameters
Description of all parameters in the colors object that can be used for configuring the color scheme.
For those who configure how payment methods are displayed: if you only display Mir Pay or a bank card with Mir Pay in the payment form of the YooMoney widget, a button will be displayed instead of the Mir Pay payment method block. The color scheme of this button can't be changed: its background can only be white.
ParameterTypeDescriptionDefault
control_primarystringBackground color for accent elements: the Pay button, selected radio buttons, checkboxes, border of the selected text field. We recommend using a bright color to draw attention#FFCC00 (желтый)
control_primary_contentstringColor of the text in the Pay button and the contents of accent radio buttons and checkboxes (for example, a ticked checkbox). We recommend using a color that will contrast with control_primary.
If the parameter is not specified, the color will be determined on the basis of control_primary
#000000 (черный) или #FFFFFF (белый) — выбирается контрастный к control_primary
backgroundstringPayment form background color, color of error messages and tips. We recommend using a color close to the background color of the container where the widget is placed#FFFFFF (белый)
textstringColor of all texts on the payment form except for the text in the Pay button and tooltips.
If the parameter is not specified, the color is determined on the basis of background
Contrast to background
borderstringColor of borders and separators.
If the parameter is not specified, the color is determined on the basis of background
Contrast to background
control_secondarystringColor of non-accent interface elements.
If the parameter is not specified, the color is determined on the basis of background
Contrast to background
Widget initialization errors
If the widget initialization failed, YooMoney will send an error code to the callback function.
Error codeValue
customization_of_payment_methods_not_allowedThis store can’t use the payment_methods parameter. If you’d like to configure how payment methods are displayed, contact your YooMoney manager.
internal_service_errorError during payment creation. Repeat widget initialization
invalid_combination_of_payment_methodsInvalid combination of payment methods in payment_methods of the customization object. You can only specify bank_card and mir_pay at the same time if you're allowed to configure how payment methods are displayed.
invalid_payment_methodsIncorrect payment_methods value of the customization object. The array can only contain the codes of the payment methods supported by the widget. If you display several methods, their codes must be presented as a list separated by commas.
invalid_return_urlInvalid return URL. During widget initialization, specify the absolute URL of the payment completion page in return_url with the protocol and domain of your website
invalid_tokenInvalid token. Create a payment to obtain a token
no_payment_methods_to_display
No payment methods to display: for example, you can’t accept payments via the selected method or the payment method doesn't support the payment processing features you selected (two-stage payment or autopayments).
Send another payment method in payment_methods during widget initialization.
token_expiredToken has expired. Create a payment to obtain a new token
token_requiredToken not sent. Send confirmation_token during widget initialization
Description of widget’s methods
MethodTypeDescription
render
(id?: string) => Promise<undefined>
Payment form display. Execution of Promise means the payment form is fully loaded. Promise можно не использовать.
If you place the widget on the payment page, specify the value of the id attribute of the container, in which you need to place the payment form, in method’s parameters. If you’d like to display the widget in a pop-up window, you don’t need to specify anything in method’s parameters.
destroy() => voidDeletion of an initialized widget.
on(event, callback) => voidRegistering widget events and calling the callback function.
Description of the widget events
The widget can notify about following events:
EventDescription
successUser's payment was successful. Used together with fail
failUser's payment was unsuccessful. Used together with success
completeUser finished the payment. This event occurs after a successful or unsuccessful payment.
modal_closeUser closed the pop-up window with the payment form. For those who display the widget in a pop-up window.
See also