Skip to content

Widget setup

To make the PayCross payment widget appear to your customers on your website, follow the steps below:

  1. Install the widget script.

    To make the widget send requests, run the following script on your website:

    <script type="text/javascript" src="https://js.pay-cross.com/widget/be_gateway.js"></script>

  2. Create the payment widget.

    Register a function to generate the necessary parameters for the BeGateway constructor object, and to call out the createWidget method. The payment is considered as successfully completed only after you receive the automatic payment notification.

    <script type="text/javascript">
    this.payment = function() {
        var params ={
            checkout_url: "https://panel.pay-cross.com",
            fromWebview: true,
            checkout: {
                iframe: true,
                test: true,
                transaction_type: "payment",
                public_key: "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEArOlXKxA/dL7Qc4jn/qEeDm62Qhd876pQAmwfabC90e1K1tLRLSoDFa3cmPnwdod3M+s1zJ1Iqd0JAFijq5YVCNlBcD595pQjqCxSMdJndJHAcgxflvgGXsVhgY+Ckl/xDfzRhIvTzEtFIj7hrIeMWnwufHfWHoJ7XAhaZX/4uI7UvPTcyZwFNxmN8x7xxfJBhTdHvd2/wNa1P+lA9JQrPuofVf+e47ajH2MVda434gO51kFsgwrgWRIEPRR0asCBeB7h/YfRyUPZEoxnoULgXLA+GMxoT6saZzxD4uBhYO8ddD8EsNl1719Ik9zEZ86GgS/I65bCAuKMXc76IikmHQIDAQAB",
                order: {
                    amount: 100,
                    currency: "EUR",
                    description: "Payment description",
                    tracking_id: "my_transaction_id"
                },
            },
            closeWidget: function(status) {
              // possible values of status variable
              // successful - transaction is successful
              // failed - transaction is declined
              // pending - awaiting transaction confirmation
              // redirected - customer is redirected to external the payment method system
              // error - error in input paras/network error/etc
              // null - payment widget is closed
              console.debug('close widget callback')
            }
        };

        new BeGateway(params).createWidget();
    };
</script>

  3. Call the created function.

    Register the call of the above created function to some event, for example, to the “Pay” link click.

    <a onclick="payment()" href="#">Pay</a>

Widget parameters

Parameter Type Description
checkout_url * required
 string https://panel.pay-cross.com
token * conditionally required
 string Payment token.

Required if the parameter public_key is not sent. The widget can be launched using the payment token, which was previously received in request for a payment token. This way, the user can not make changes to the payment parameters.
fromWebview boolean Set this parameter to true if you want the payment widget to open on payment initialization in a WebView (for example, within a web application). If this parameter is not provided, or it is set to false, initializing the payment will open the payment page instead.
checkout object
transaction_type * required
 string A type of transaction or request that will be sent to gateway.

Possible values:
authorization;
payment;
tokenization;
charge (for the charge request).
attempts integer A number of payment attempts. The default is 1.
dynamic_billing_descriptor string Dynamic billing descriptor.
public_key * conditionally required
 string Shop public key.

Required if the token parameter is not sent. When using this method to launch the widget be sure to check the payment details in automatic notification and only then change the payment status to the received.
test boolean Set to true for a test transaction. Otherwise, false (default).
iframe boolean When the value is true, if possible, open transitions to external services inside the widget. By default, false.
order object
amount * required
 integer A payment amount in minimal currency units, for example $32.45 must be sent as 3245.
currency * required
 string A transaction currency in the ISO-4217 alpha-3 code format. For example, USD.
description * required
 string Order description.
tracking_id string The ID of transaction or order in your system. It is recommended to use unique value for each transaction
expired_at string Date and time till which a payment can be done. By default a payment must be done within 24 hours upon a payment token creation. Format (ISO 8601): YYYY-MM-DDThh:mm:ssTZD, where YYYY – year (for example 2019), MM – month (for example 02), DD – day (for example 09), hh – hours (for example 18), mm – minutes (for example 20), ss – seconds (for example 45), TZD – time zone (+hh:mm или –hh:mm).
additional_data object A section contains a detailed information about the payment
receipt_text array Text, that will be added to client's mail and will be showed on success result page. Submit it as an array of strings, for example ["First line", "Second line"]
contract array An array, consisting of elements:

recurring - PayCross returns a card token to use it in subsequent charges without to enter a card data again. Customer agrees to be charged regularly, but initially the customer must make a payment with full card data including CVC/CVV code and pass 3-D Secure verification;

oneclick - PayCross returns a card token to use it in the one-click payment scheme. It means PayCross will open a payment widget with pre-filled card data and customer will be forced to enter CVC/CVV code and pass 3-D Secure verification to complete payment;

credit - PayCross returns a card token to use it for a payout;

save_card - returns an information, that the customer has turned save card toggle to the active state. Used in addition to recurring, oneclick and credit parameters. Conditions of usage:
1. Parameter save_card_toggle.customer_contract is true
2. Customer has turned save card toggle to the active state.
avs_cvc_verification object AVS/CVC verification
card_on_file object It sets flags submitted to a payment network why and what you charged a previously saved card for. If the parameter is not submitted, default values of initiator and type are in use.
initiator string merchant - (default) merchant initiated a card charge (for instance, for a car ride service)

customer - customer initiated a card charge (for instance, customer confirmed and order and wanted to pay by a saved card)
type string Used only in case additional_data.card_on_file.initiator is merchant.

delayed_charge - (default) delayed charge posted to a card

increment - merchant wants to charge additional amount above initially paid order (for instance, in case of upsale)

resubmission - merchant wants to resubmit a transaction due to fail with a previous charge (for instance, no money on a card)

reauthorization - merchant wants to refresh previously authorized amount (for instance, to continue to hold a money reserve on a card for future charges)

no_show - merchant wants to charge a card when customer didn't come (for instance, no visit to a hotel)
settings object
save_card_toggle object A section for configuring the save card toggle.
display boolean If the parameter is true, the save card toggle will be displayed on the widget.

This parameter has greater priority, than Display save card toggle on payment page parameter in a shop settings in the Merchant back office.

By default set to true
customer_contract boolean true - when the customer has turned save card toggle to the active state, he gives a legal agreement for storage card datа by Merchant and use this agreement in the additional_data.contract.
false - when the customer has turned save card toggle in the active state, he gives a legal agreement to store card only for selecting on the payment widget.

By default set to false
text string The parameter replaces the standard toggle name Save card to any Merchant text
hint string hint text, described why the save card option is needed.
another_card_toggle object A section for configuring the another card toggle.
display boolean If the parameter is true, the toggle Рay with another card will be displayed on the widget.

This parameter has greater priority, than Hide another card toggle on payment page parameter in a shop settings in the Merchant back office.

By default set to true
return_url string URL to return Customer to after transaction was complete. If not set, then only closeWidget function is called. If set, then both success_url and decline_url are ignored.
success_url string URL to return Customer to if a transaction was successful.
decline_url string URL to return Customer to if a transaction was declined by bank.
fail_url string URL to return Customer to if a transaction failed (due to an error, exception and etc.). To check the status and a failure reason, send a status query request with the payment token.
cancel_url string URL to return Customer to if Customer cancels a transaction.
verification_url string URL where transaction verification request will be posted to. The verification request format equals to a transaction response format.
notification_url string URL where notifications about the transaction will be posted to
auto_return string After a transaction completes, PayCross shows a transaction result page for specified number of seconds and then automatically returns Customer to one of your return URLs. If the parameter value is 0, then Customer will be automatically redirected without showing PayCross transaction result page.
button_text string Customize the payment button text. Note: {amount} can be used as a placeholder to show transaction amount within the customized text
button_next_text string Customize the payment result page button text
language string Checkout page locale. English (en) is set by default. Possible values of language parameter.
customer_fields object It controls the input fields for customer details shown at the payment widget.
read_only array It is an array which may consist of the values email, first_name, last_name, address, city, state, zip, phone, country, birth_date, taxpayer_id.
Fields for customer's data indicated in the array will be disabled at the payment widget.
If email exists in the array then it must present in the customer section below and it can't be empty.
visible array It is an array which may consist of the values email, first_name, last_name, address, city, state, zip, phone, country and birth_date, taxpayer_id. Fields for customer's data indicated in the array will be displayed at the payment widget.
credit_card_fields object It controls the automatic filling of the cardholder name on the payment widget.
holder string Cardholder name for automatic filling on the payment widget.
read_only array It is an array which may consist only holder value. Blocks editing of the selected field.
customer * conditionally required
 object A section of the customer information.
Contact Tech Support Team to check what section parameters are required.
email string Customer email
first_name string The customer's first name.
last_name string The customer's last name.
address string The customer's billing address.
city string The customer's billing city.
state string The customer's two-letter billing state only if the billing address country is US or CA.
zip string The customer's billing ZIP or postal code.
country string The customer's billing country in ISO 3166-1 alpha-2 format.
phone string The customer's phone number.
birth_date string The customer's birth date in ISO 8601 YYYY-MM-DD format.
taxpayer_id string The customer's taxpayer ID.
payment_method object A section contains information about which payment methods are available to the customer in order to make a payment, as well as the parameters necessary to initialize each payment method. If not submitted, all active payment methods are available by default.
types array An array of available payment methods to enable on the payment widget. Possible values:

credit_card - bank card payment

for the remaining values of the array, see the section alternative payment methods for the value of the parameter type.

If the listed payment methods require additional parameters, then create objects with the name from type and internal parameters from the alternative payment methods section.

For example, for a payment method type apm with the parameter channel, send such an object:
apm : { channel: "ONLINE" }

Note! Apple Pay, Google Pay and Samsung Pay are displayed on the widget depending on the client's device and browser types. See more here.
excluded_types array An array of the payment types that will be excluded from the available payment methods on the payment page. If both payment_method.types and payment_method.excluded_types are sent in the request, the information from payment_method.types will be applied and payment_method.excluded_types will be ignored.
credit_card object
token string Card token. The tokenized data will be displayed on the payment widget.
travel object Travel related data.
airline object The section contains airline ticket addendum data.
agency_code string IATA agency code, for example 03.
agency_name string Agency name who sold the ticket, for example Corel travel.
ticket_number string 14-digit ticket number. Should contain 3-digit ticketing code, 4-digit form number, 6-digit serial number, and check digit, for example 390 5241 025377 1.
booking_number string For example, DKZVUA.
restricted_ticked_indicator string If the ticket can be returned, the field value is 0, otherwise it is 1.
legs array An optional array of travel legs. Every legs consists of:
airline_code string 2-letter IATA code, for example B2.
stop_over_code string IATA stopover code. If a traveler stays in the originating city more than 24h, then set the field value to O or left it empty. If the originating airport is transit airport, then set the field value to X.
flight_number string For example, A3 971.
departure_date_time string For example, 2014-05-26T05:15:00.
arrival_date_time string For example, 2014-05-26T07:30:00.
originating_country string For example, RU.
originating_city string For example, Moscow.
originating_airport_code string 3-letter IATA code, for example DME.
destination_country string For example, Greece.
destination_city string For example, Athens.
destination_airport_code string 3-letter IATA code, for example ATH.
coupon string Coupon number if it was applied.
class string Class flight, 1-letter IATA code. Example, C.
passengers array List of passengers where every list item consists of
first_name string First name of passenger, for example KONSTANTIN.
last_name string Last name of passenger, for example IVANOV.