sale.paysystem.handler.add

sale.paysystem.handler.add(
 fiedls
)

This method adds REST-handler.

Parameters

Example

BX24.callMethod(
	"sale.paysystem.handler.add",
	{
		'NAME' : 'REST handler', 							// Name of handler
		'SORT' : 100, 											// Sorting
		'CODE' : 'resthandlercode', 							// Unique code of handler in the system
		'SETTINGS' : { 											// Handler settings
			'CURRENCY' : {'RUB'}, 								// List of currencies, supported by the handler
			'FORM_DATA' : { 									// Form settings
				'ACTION_URI' : 'https://payment_service_url', 	// URL, where the form will be sent
				'METHOD' : 'POST', 								// Method for sending form
				'PARAMS' : { 									// Chart with links between form fields and handler parameters: array of "array" type (code_field => code_handler_parameter)
					'serviceid' : 'REST_SERVICE_ID',
					'invoiceNumber' : 'PAYMENT_ID',
					'Sum' : 'PAYMENT_SHOULD_PAY',
					'customer' : 'PAYMENT_BUYER_ID',
				}
			},
			'CODES' : {											// LIst of handler parameters
				"REST_SERVICE_ID" : {							// Parameter code
					"NAME" : 'Payment system number',					// Parameter name
					"DESCRIPTION" : 'Payment system number',			// Parameter description
					'SORT' : 100,								// Sortintg
				},
				"REST_SERVICE_KEY" : {
					"NAME" : 'Secret key',
					"DESCRIPTION" : 'Secret key',
					'SORT' : 300,
				},
				"PAYMENT_ID" : {
					"NAME" : 'Payment number',
					'SORT' : 400,
					'GROUP' : 'PAYMENT',
					'DEFAULT' : {
						'PROVIDER_KEY' : 'PAYMENT',
						'PROVIDER_VALUE' : 'ACCOUNT_NUMBER'
					}
				},
				"PAYMENT_SHOULD_PAY" : {
					"NAME" : 'Payment amount',
					'SORT' : 600,
					'GROUP' : 'PAYMENT',
					'DEFAULT' : {
						'PROVIDER_KEY' : 'PAYMENT',
						'PROVIDER_VALUE' : 'SUM'
					}
				},
				"PS_CHANGE_STATUS_PAY" : {
					"NAME" : 'Payment status automatic change',
					'SORT' : 700,
					"INPUT" : {
						'TYPE' : 'Y/N'
					},
				},
				"PAYMENT_BUYER_ID" : {
					"NAME" : 'Buyer code',
					'SORT' : 1000,
					'GROUP' : 'PAYMENT',						// type of string value, checkbox and etc.
					'DEFAULT' : {								// By default value
						'PROVIDER_KEY' : 'ORDER',				// Value type (see. available list below)
						'PROVIDER_VALUE' : 'USER_ID'			// Value (see. available list below)
					}
				}
			}
		}
	},
	function(result)
	{
		if(result.error())
			console.error(result.error());
		else
			console.info("Handler is added with ID" + result.data());
	}
);

Example 2

Starting from the sale module version 20.5.0, a new FIELDS value is added instead of the old PARAMS (now you can pass arbitrary fields for payment system REST handlers).

When the CODE key value is string, the value is used for searching a match between form fields and handler parameters: array array('CODE' => 'handler_parameter_code'). Name and value will be retrieved from the handler parameters ('CODES').

When the key CODE have the passed object, the payment form will add the specified type of field. The following ерзуы are supported:

• STRING (string)
• Y/N (checkbox)
• ENUM (list)

By default, form fields are hidden. To make the field invisible, pass the 'VISIBLE' : 'Y'.

BX.rest.callMethod(
    "sale.paysystem.handler.add",
    {
        'NAME' : 'Handler.Rest',
        'SORT' : 100,
        'CODE' : 'resthandlercodedoc',
        'SETTINGS' : {
            'CURRENCY' : ['USD'],
            'FORM_DATA' : {
                'ACTION_URI' : 'https://payment_service_url',
                'METHOD' : 'POST',
                'FIELDS' : { 
                    'phone' : {
                        'CODE': {
                            'NAME' : 'Phone number',
                            'TYPE' : 'STRING',
                        }
                        'VISIBLE' : 'Y',
                    },
                    'paymentId' : {
                        'CODE' : 'PAYMENT_ID',
                        'VISIBLE' : 'Y'
                    },
                    'serviceid' : {
                        'CODE' : 'REST_SERVICE_ID'  
                    }
                }
            },
            'CODES' : {
                "REST_SERVICE_ID" : {
                    "NAME" : 'Store number',
                    "DESCRIPTION" : 'Store number',
                    'SORT' : 100,
                },
                "REST_SERVICE_KEY" : {
                    "NAME" : 'Secret key',
                    "DESCRIPTION" : 'Secret key',
                    'SORT' : 300,
                },
                "PAYMENT_ID" : {
                    "NAME" : 'Payment No.',
                    'SORT' : 400,
                    'GROUP' : 'PAYMENT',
                    'DEFAULT' : {
                        'PROVIDER_KEY' : 'PAYMENT',
                        'PROVIDER_VALUE' : 'ACCOUNT_NUMBER'
                    }
                },
                "PAYMENT_SHOULD_PAY" : {
                    "NAME" : 'Payment amout',
                    'SORT' : 600,
                    'GROUP' : 'PAYMENT',
                    'DEFAULT' : {
                        'PROVIDER_KEY' : 'PAYMENT',
                        'PROVIDER_VALUE' : 'SUM'
                    }
                },
                "PS_CHANGE_STATUS_PAY" : {
                    "NAME" : 'Payment status automatic update',
                    'SORT' : 700,
                    "INPUT" : {
                        'TYPE' : 'Y/N'
                    },
                },
                "PAYMENT_BUYER_ID" : {
                    "NAME" : 'Buyer code',
                    'SORT' : 1000,
                    'GROUP' : 'PAYMENT',
                    'DEFAULT' : {
                        'PROVIDER_KEY' : 'ORDER',
                        'PROVIDER_VALUE' : 'USER_ID'
                    }
                }
            }
        }
    },
    function(result)
    {
        if(result.error())
            console.error(result.error());
        else
            console.info("Handler is added with ID " + result.data());
    }
);

Example 3

Starting from the sale module version 21.700.0 has new payment scenarios:

• Form
• iFrame
• Checkout

Form

Pass FORM_DATA when adding the handler in SETTINGS (as shown in examples above). This method is suitable when no data is requested from buyer or a small-scale set of data is requested.

Form fields are automatically displayed according to the payment page design.

Form data (values FIELDS from FORM_DATA) will be sent to ACTION_URI.

iFrame

When adding the handler in SETTINGS, pass IFRAME_DATA (instead of FORM_DATA). The ACTION_URI must contain the page uploaded in iframe to the seller site.

When uploading iframe via the method Window.postMessage() the following data will be passed to ACTION_URI:

• BX_SYSTEM_PARAMS:
  • RETURN_URL- current page;
  • PAYSYSTEM_ID - payment system ID;
  • PAYMENT_ID - payment ID;
  • SUM - payment amount;
  • CURRENCY - currency.
• BX_COMPUTED_STYLE (iframe parent element styles, retrieved by the method window.getComputedStyle()
• FIELDS values from IFRAME_DATA

You can get values in the iframe using the event handler message, for example:

//js
document.addEventListener("DOMContentLoaded", function() {
    window.addEventListener("message", function (event) {
        // getting data from site (from payment system)
        var paymentData = event.data;

		// handling the BX_SYSTEM_PARAMS
        if (paymentData.BX_SYSTEM_PARAMS)
        {
            // ...
        }

        // use site styles
        if (paymentData.BX_COMPUTED_STYLE)
        {
            document.body.style.background = paymentData.BX_COMPUTED_STYLE.background;
            document.body.style.color = paymentData.BX_COMPUTED_STYLE.color;
        }
    }, false);
});

By default the iframe width - 100% of parent element, and height - 350px.

iframe sizes can be updated. You need to pass the height and/or width from iframe to seller's site. For example:

//js
document.addEventListener("DOMContentLoaded", function() {
	var size = {
		width: document.body.scrollWidth,
		height: document.body.scrollHeight
	};

	// sending data to seller site
	parent.postMessage(size, "*");
});

width and height are reserved variable names and only they are processed at the seller's site.

Checkout

When adding the handler to SETTINGS, pass CHECKOUT_DATA (instead of FORM_DATA).

Script that processes the received data is located at ACTION_URI. It creates the payment and returns created payment ID and payment page URL.

The following data for payment is passed to ACTION_URI:

• BX_SYSTEM_PARAMS:
  • RETURN_URL - current page;
  • PAYSYSTEM_ID - payment system ID;
  • PAYMENT_ID - payment ID;
  • SUM - payment amount;
  • CURRENCY - currency.
• FIELDS values from CHECKOUT_DATA

As the response to ACTION_URI, script must return created payment ID and payment page URL.

For example:

//php
// ... processing code for received data and created payment

$result = [
    'PAYMENT_URL' => '', // payment page URL
    'PAYMENT_ID' => '', // payment identifier
];

header('Content-Type:application/json; charset=UTF-8');
echo json_encode($result);

Buyer is forwarded via the link from PAYMENT_URL automatically or via the click at the "Buy" button.

Possible values