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.| Parameter | Type | Mandatory | Description |
|---|---|---|---|
| confirmation_token | string | Required | YooMoney 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) => void | Required | Callback function that accepts the initialization error code |
| customization | object | Optional | Payment 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:
|
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.Configuration of display of payment methods. Possible values:
If you’d like to configure how payment methods are displayed, contact your YooMoney manager. |
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.
| Parameter | Type | Description | Default |
|---|---|---|---|
| control_primary | string | Background 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 (yellow) |
| control_primary_content | string | Color 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 (black) or #FFFFFF (white) — selected to contrast with control_primary |
| background | string | Payment 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 (white) |
| text | string | Color 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 |
| border | string | Color of borders and separators. If the parameter is not specified, the color is determined on the basis of background | Contrast to background |
| control_secondary | string | Color 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 code | Value |
|---|---|
| customization_of_payment_methods_not_allowed | This 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_error | Error during payment creation. Repeat widget initialization |
| invalid_combination_of_payment_methods | Invalid 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_methods | Incorrect 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_url | Invalid 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_token | Invalid 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_expired | Token has expired. Create a payment to obtain a new token |
| token_required | Token not sent. Send confirmation_token during widget initialization |
Description of widget’s methods
| Method | Type | Description |
|---|---|---|
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 | () => void | Deletion of an initialized widget. |
on | (event, callback) => void | Registering widget events and calling the callback function. |
Description of the widget events
The widget can notify about following events:
| Event | Description |
|---|---|
| success | User's payment was successful. Used together with fail |
| fail | User's payment was unsuccessful. Used together with success |
| complete | User finished the payment. This event occurs after a successful or unsuccessful payment. |
| modal_close | User closed the pop-up window with the payment form. For those who display the widget in a pop-up window. |
See also