sale.paysystem.handler.add

Scope: pay_system Permissions to execute: for all

Description

sale.paysystem.handler.add(
 fiedls
)

The method adds REST handler.

Parameters

Parameter	Description	Available from version
fiedls	Set of fields(array type `array("field":"value"[, ...]))`, containing value that describe the handler. Available fields: NAME - Handler name CODE - unique handler code in the system SETTINGS - handler settings SORT - sorting

Example

BX24.callMethod(
	"sale.paysystem.handler.add",
	{
		'NAME' : 'REST handler', 							// Handler name
		'SORT' : 100, 										// Sorting
		'CODE' : 'resthandlercode', 							// Unique handler code 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 to send the form  
				'METHOD' : 'POST', 						// Method to send the form
				'PARAMS' : { 								// Map of corresponding form fields and handler parameters: array type (field_code => handler_parameter_code)
					'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" : 'Store number',					// Parameter name
					"DESCRIPTION" : 'Store number',			        // Parameter description
					'SORT' : 100,								// Sorting
				},
				"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 sum',
					'SORT' : 600,
					'GROUP' : 'PAYMENT',
					'DEFAULT' : {
						'PROVIDER_KEY' : 'PAYMENT',
						'PROVIDER_VALUE' : 'SUM'
					}
				},
				"PS_CHANGE_STATUS_PAY" : {
					"NAME" : 'Automatic payment status change',
					'SORT' : 700,
					"INPUT" : {
						'TYPE' : 'Y/N'
					},
				},
				"PAYMENT_BUYER_ID" : {
					"NAME" : 'Buyer ID code',
					'SORT' : 1000,
					'GROUP' : 'PAYMENT',						// String value type, checkbox and etc.
					'DEFAULT' : {								// 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 added with ID " + result.data());
	}
);

Example No. 2

Starting from the Sale module version 20.5.0, a new value FIELDS is added instead of the legacy PARAMS (now arbitrary fields can be passed for payment system's REST handlers).

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

If the CODE key passes an object, the fields of specified type will be added in the payment's form. The following types are supported:

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

Form fields are hidden by default. To male them visible, pass 'VISIBLE' : 'Y'.

BX.rest.callMethod(
    "sale.paysystem.handler.add",
    {
        'NAME' : 'Rest.Handler',
        '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's number',
                    "DESCRIPTION" : 'Store's number',
                    'SORT' : 100,
                },
                "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 update',
                    'SORT' : 700,
                    "INPUT" : {
                        'TYPE' : 'Y/N'
                    },
                },
                "PAYMENT_BUYER_ID" : {
                    "NAME" : 'Buyer ID 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 added with ID " + result.data());
    }
);

Note: If passing both FIELDS and PARAMS, only FIELDS is used.

Example 3

Starting from the sale module version 21.700.0, there are new payment scenarios using the following:

Form
iFrame
Checkout

Form

When adding a handler to SETTINGS you need to pass FORM_DATA (as shown in examples above). This method is suitable when no extra data is requested from a buyer, or when requesting a small set of data from a buyer.

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

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

iFrame

When adding a handler to SETTINGS, you need to pass IFRAME_DATA (instead of FORM_DATA). The URL from ACTION_URI must располагаться страница, которая будет загружена в iframe на сайт продавца.

Uploading iframe via the method Window.postMessage() passes the following data to ACTION_URI:

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

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

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

		// работа с BX_SYSTEM_PARAMS
        if (paymentData.BX_SYSTEM_PARAMS)
        {
            // ...
        }

        // using 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);
});

Default iframe width - 100% of parent element, and height - 350px.

Iframe dimensions can be modified. For this, pass the height and/or width from iframe to a seller's site. For example:

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

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

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

Checkout

You need to pass CHECKOUT_DATA (instead of FORM_DATA) when adding a handler to SETTINGS.

Address at ACTION_URI must contain the script that processes retrieved data, creates a payment and returns an ID for created payment and payment page URL.

The following data for payment will be passed to ACTION_URI:

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

As the response to requested ACTION_URI, script returns an ID for created payment and payment page URL.

For example:

//php
// ... code for processing retrieved data and payment creating 

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

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

Buyer proceeds to the link from PAYMENT_URL automatically or by after clicking on the "Buy" button.

Starting from sale 22.200.0 you can return array with errors in the key PAYMENT_ERRORS. Manager will see the errors in the timeline and may may view them at the payment page (depends on the used template).

Example:

//php
// ... code for processing retrieved data and creating a payment

$result = [
    'PAYMENT_ERRORS' => [
       'Some user custom error',
       'Some error more',
    ]
];

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

If returning nothing, uses a default error: Error registering order in payment system

Possible values

PROVIDER_KEY possible values
ORDER	Parameters
PROPERTY	Invoice properties
PAYMENT	Payment
USER	User
VALUE	String type value
Y\N	Checkbox

PROVIDER_KEY possible values
ORDER	ID: ID (for invoices corresponds to invoice ID), ACCOUNT_NUMBER: Order number (for invoices corresponds to invoice number), ORDER_TOPIC: Topic, DATE_INSERT: Order date (for invoices corresponds to invoice date), DATE_INSERT_DATE: Order date (without time) (for invoices corresponds to invoice date (without time)), DATE_BILL: Data and time of issue, DATE_BILL_DATE: Date of issue, DATE_PAY_BEFORE: Payment date, SHOULD_PAY: Invoice sum (for invoices corresponds to invoice sum), CURRENCY: Currency, PRICE: Order price (for invoices corresponds to invoice price), PRICE_DELIVERY: Delivery price, DISCOUNT_VALUE: Discount value, USER_ID: Buyer code, PAY_SYSTEM_ID: Payment system code, DELIVERY_ID: Delivery service code, TAX_VALUE: Tax, USER_DESCRIPTION: Commentary
PAYMENT	ID: ID ACCOUNT_NUMBER: Payment number, DATE_BILL: ДатаDate and time of issue, DATE_BILL_DATE: Date of issue (without time), SUM: Payment sum, CURRENCY: Currency
USER	ID: Buyer code, LOGIN: Login, NAME: Name, SECOND_NAME: Second name, LAST_NAME: Last name, EMAIL: EMail, PERSONAL_PROFESSION: Professional occupation, PERSONAL_WWW: Personal website, PERSONAL_ICQ: ICQ number, PERSONAL_GENDER: Gender , PERSONAL_FAX: Fax number, PERSONAL_MOBILE: Phone number, PERSONAL_STREET: Address, PERSONAL_MAILBOX: Mailbox, PERSONAL_CITY: City, PERSONAL_STATE: State, PERSONAL_ZIP: Zip code, PERSONAL_COUNTRY: Country, WORK_COMPANY: Company, WORK_DEPARTMENT: Department, WORK_POSITION: Position, WORK_WWW: Company site, WORK_PHONE: Work phone, WORK_FAX: Work fax, WORK_STREET: Company address, WORK_MAILBOX: Work mailbox, WORK_CITY: Company city, WORK_STATE: Company state, WORK_ZIP: Company zip code, WORK_COUNTRY: Company country