Documentation

sale.paysystem.handler.add

sale.paysystem.handler.add(
 fiedls
)

This method adds REST-handler.

Parameters

Parameter Description Available from version
fiedls Set of fields (array type array("field":"value"[, ...])), containing values, describing the handler. Available fields:
  • NAME - Name of handler
  • CODE - Unique handler code in the system.
  • SETTINGS - Handler settings
  • SORT - Sorting

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());
    }
);

Note: When passing both FIELDS and PARAMS uses only FIELDS.

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

{Possible values for PROVIDER_KEY
ORDER Parameters
PROPERTY Invoice properties
PAYMENT Payment
USER User
VALUE String type value
Y\N Checkbox
Possible values for PROVIDER_VALUE
ORDER ID: ID,
ACCOUNT_NUMBER: Order number,
ORDER_TOPIC: Topic,
DATE_INSERT: Date of order,
DATE_INSERT_DATE: Date of order (without time),
DATE_BILL: Data and time when issued,
DATE_BILL_DATE: Date when issued,
DATE_PAY_BEFORE: Due date,
SHOULD_PAY: Invoice amount,
CURRENCY: Currency,
PRICE: Order price,
PRICE_DELIVERY: Delivery price,
DISCOUNT_VALUE: Discount amount,
USER_ID: Buyer code,
PAY_SYSTEM_ID: Payment system code,
DELIVERY_ID: Delivery service code,
TAX_VALUE: Tax,
USER_DESCRIPTION: Comment
PAYMENT ID: ID
ACCOUNT_NUMBER: Payment number,
DATE_BILL: Data and time when issued,
DATE_BILL_DATE: Data when issued (without time),
SUM: Invoice amount,
CURRENCY: Currency,
USER ID: Buyer code,
LOGIN: Login,
NAME: Name,
SECOND_NAME: Middle 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: Telephone 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 website,
WORK_PHONE: Work telephone,
WORK_FAX: Work fax,
WORK_STREET: Company address,
WORK_MAILBOX: Work mailbox,
WORK_CITY: Company city,
WORK_STATE: Company state,
WORK_ZIP: Company index,
WORK_COUNTRY: Company country


© «Bitrix24», 2001-2022
Up