.. _forms_customization_reference: Forms Customization ###################################### .. toctree:: :maxdepth: 1 .. contents:: :local: .. role:: ex .. role:: code .. _payment_page_display_logic_reference: Payment Page Display Logic ==================================================== .. uml:: :align: center skinparam ConditionEndStyle hline : (1) Initiate transaction; if ((2) Additional Payer input required?) then (yes) : (3) return input form; : (4) submit form; else (no) endif if ((5) External form required?) then (yes) : (6) request external form from the payment provider; : (7) redirect to external form; : (8) submit form on payment provider side; else (no) endif : (9) show wait form; : (10) process transaction; : (11) show finish form or redirect \nto Connecting Party website; | (1) Transactions can be initiated with API requests, batch upload or via Virtual terminal on UI. Each payment method has its own payment page display logic. .. note:: Payment Cashier might have multiple transactions initiated within the same payment session, because it can have multiple payment methods available for the Payer. When Payer selects payment tab, respective auxiliary transaction is initiated. See :ref:`Payment Cashier Page Customization`. | (3) For credit card payment method form is displayed on Payment Gateway side and can be customized. See :ref:`Payment Page Customization`. Some other payment methods may have additional forms on Payment Gateway side. Contact Payneteasy support for details. | (7) Some payment methods require the Payer to be redirected to their own form. That form is not hosted by Payment Gateway and can`t be customized. | (9) Until transaction reaches final status, Payment Gateway displays :ref:`Wait Form` for the Payer. | (11) After the transaction reaches the final status, Payment Gateway displays :ref:`Finish Form` for the Payer or :ref:`Redirect` to Connecting Party website. .. _payment_page_customization_reference: Payment Page Customization ==================================================== Payment Page Example ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. code-block:: html

Order #$!MERCHANT_ORDER_ID - $!ORDERDESCRIPTION

Total amount: $!AMOUNT $!CURRENCY to $!MERCHANT

.. note:: The code described below allows to submit destination card data in :ref:`Transfer` type transactions: .. code-block:: html

Destination card number:

Payment Page Autofill ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ If Connecting Party wants to use autofill in payment form, certain element attributes :code:`` :code:`` :code:`` should be hardcoded in the following manner: .. code-block:: html Credit Card NumberThe 13-19 digits on the front of your card If autofill in the transfer form must be used, certain element attributes should be hardcoded in the following manner: .. code-block:: html #if ($INPUT_SOURCE_CARD_CARDHOLDER)

Card printed name:

#end #if ($INPUT_SOURCE_CARD_CVV2)

Card security code (CVV2/CVC2):

#end #end #if ($INPUT_DESTINATION_CARD) #if($!DESTINATIONCARDNO)

Destination card number:

#end #end Payneteasy has default payment form template which supports autocomplete. In case if Connecting Party wants to add additional fields for autocomplete, this `specification `_ should be used for naming references. Payment Page Template Macros ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. list-table:: :widths: 30, 10, 30 :header-rows: 1 :class: longtable * - Field Name Macro - Field Value Macro - Description * - :code:`${APPLE_PAY}` - n/a - Apple Pay buy button will be available if this macros is used. Not available for Transfer transactions. * - :code:`${GOOGLE_PAY}` - n/a - Google Pay buy button will be available if this macros is used. Not available for Transfer transactions. * - :code:`${CARDNO}` - :code:`${CARDNOVALUE}` - Payer’s credit card number. * - :code:`${EXPMONTH}` - n/a - Credit card expiration month. * - :code:`${EXPYEAR}` - n/a - Credit card expiration year. * - :code:`${CVV2}` - :code:`${CVV2VALUE}` - Card security code. Example: :ex:`432` * - :code:`${CARDHOLDER}` - :code:`${CARDHOLDER_VALUE}` - Card printed name. * - :code:`${MERCHANT}` - n/a - End point display name. * - :code:`${SKIN_VERSION}` - n/a - CSS skin version. * - :code:`${ORDERDESCRIPTION}` - n/a - Order description. * - :code:`${CUSTOMER_FIRST_NAME}` - n/a - Payer first name sent by Connecting Party via input parameters. * - :code:`${CUSTOMER_LAST_NAME}` - n/a - Payer last name sent by Connecting Party via input parameters. * - :code:`${CUSTOMER_EMAIL}` - n/a - Payer E-mail address sent by Connecting Party via input parameters. * - :code:`${DESTINATIONCARDNO}` - n/a - Destination credit card number. Available for Transfer transactions. * - :code:`${DESTINATION_CARD_TYPE}` - n/a - Destination card type. Available for Transfer transactions. * - :code:`${DESTINATION_LAST_FOUR_DIGITS}` - n/a - Destination card last four digits. Available for Transfer transactions. * - :code:`${AMOUNT}` - n/a - Amount. * - :code:`${CURRENCY}` - n/a - Currency. * - :code:`${DESTINATION_PURPOSE}` - n/a - Purpose sent by Connecting Party via input parameters. * - :code:`${PAYNET_ORDER_ID}` - n/a - Payneteasy order id. * - :code:`${MERCHANT_ORDER_ID}` - n/a - Connecting Party order id. * - :code:`${refresh_interval}` - n/a - Refresh interval recommended by system. * - :code:`${uuid}` - n/a - Internal. * - :code:`${INTERNAL_SECTION}` - n/a - Internal for iFrame integration. * - :code:`${CUSTOMER_IP_COUNTRY_ISO_CODE}` - n/a - Payer country defined by IP Address. * - :code:`${PREFERRED_LANGUAGE}` - n/a - Payer language sent by Connecting Party via input parameters. Not available for Account Verification. * - :code:`${BROWSER_LANGUAGE}` - n/a - Payer language defined by browser settings. * - :code:`${CUSTOMER_LANGUAGE}` - n/a - Payer language send by Connecting Party via input parameters or defined by browser settings if first is not set. * - :code:`${MERCHANT_FORM_DATA}` - n/a - Parameters sent in :ex:`MERCHANT_FORM_DATA` API parameter are parsed into macros with the same name, the parameter is url-encoded, example: :ex:`testparam%3Dtest1%26mynewparam%3Dtest2` and is parsed into :ex:`$MFD_testparam = test1` and :ex:`$MFD_mynewparam = test2` macros in the form. Parameter name characters[a-zA-Z0-9], parameter value characters[a-zA-Z0-9], control characters [=&], 2MB max size. Not available for Account Verification. For example, this parameter can be used to display payment form in light/dark mode depending on the value passed by Connecting Party (e.g. pass :code:`merchant_form_data=theme%3Ddark` in request and :ex:`$MFD_theme` macro placeholder on payment form will be changed to :ex:`dark`. * - :code:`${MIN_AMOUNT}` - n/a - This macro has the value provided in :code:`minimum-transaction-amount` parameter in initial request. It can be used to validate the transaction amount before payment form is submitted. Contact support manager to enable this feature. * - :code:`${MAX_AMOUNT}` - n/a - This macro has the value provided in :code:`maximum-transaction-amount` parameter in initial request. It can be used to validate the transaction amount before payment form is submitted. Contact support manager to enable this feature. * - :code:`${CUSTOMER_ZIP_CODE}` - n/a - Generates a ZIP code if it was not received from the Payer. Not available for Account Verification. .. _prefilled_cardholder_data_in_payment_page: Prefilled Cardholder Data in Payment Page ================================================================================== Payer's cardholder data, used for processing of a previous transaction, can be tokenized for future use with request to :ref:`/api/v2/create-card-ref/`. The obtained token :code:`cardrefid` then can be passed in the next requests to relevant API. If this parameter is sent, all cardholder data input will be immutable and prefilled on the payment page. CVV is not tokenized and must be provided by Payer on this payment page. Below is the example of form customization to work with prefilled cardholder data in payment page. .. note:: This feature is available only for :ref:`Sale` and :ref:`Preauth` transaction types and cannot be used in :ref:`Payment Cashier`. Prefilled Cardholder Data Payment Page Example ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. code-block:: html

Order #$!MERCHANT_ORDER_ID - $!ORDERDESCRIPTION

Total amount: $!AMOUNT $!CURRENCY to $!MERCHANT

Card Holder: ${CARDHOLDER}

Card Number: $!CARD_BIN ...... $!CARD_LAST4DIGITS

Exp year: $!EXPYEAR_VALUE

Exp month: $!EXPMONTH_VALUE

Prefilled Cardholder Data Payment Page Macros ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. list-table:: :widths: 30, 10, 30 :header-rows: 1 :class: longtable * - Field Name Macro - Field Value Macro - Description * - :code:`${CARDHOLDER}` - n/a - Cardholder name. * - :code:`${CARD_BIN}` - n/a - Full card number. * - :code:`${CARD_LAST4DIGITS}` - n/a - Last 4 digits of the card. * - :code:`${EXPMONTH_VALUE}` - n/a - Card expiry month value. * - :code:`${EXPYEAR_VALUE}` - n/a - Card expiry year value. * - :code:`${CVV2}` - n/a - CVV2 card value. .. _wait_page_customization_reference: Wait Page Customization ===================================================================== Wait Page Template ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Wait Page is the form where the Payer's stays on until transaction reaches it's final status. .. highlight:: html ::

Order #$!MERCHANT_ORDER_ID - $!ORDERDESCRIPTION

Total amount: $!AMOUNT $!CURRENCY to $!MERCHANT

Please wait, your payment is being processed, remaining seconds. .. note:: The code described below do not regard to the :ref:`Account Verification`: .. highlight:: html ::

Total amount: $!AMOUNT $!CURRENCY to $!MERCHANT

Wait Page Template Macros ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. list-table:: :widths: 30, 10, 30 :header-rows: 1 :class: longtable * - Field Name Macro - Field Value Macro - Description * - :code:`$!refresh_interval` - n/a - Refresh interval recommended by system. * - :code:`$!MERCHANT_ORDER_ID` - n/a - Connecting Party order id. * - :code:`$!ORDERDESCRIPTION` - n/a - Order description. * - :code:`$!AMOUNT` - n/a - Amount. Not available for Account verification. * - :code:`$!CURRENCY` - n/a - Currency. Not available for Account verification. * - :code:`$!MERCHANT` - n/a - End point display name. * - :code:`$!uuid` - n/a - Internal. * - :code:`$!{INTERNAL_SECTION}` - n/a - Internal for iFrame integration. * - :code:`${SKIN_VERSION}` - n/a - CSS skin version. * - :code:`${PAYNET_ORDER_ID}` - n/a - Payneteasy order id. * - :code:`${CUSTOMER_IP_COUNTRY_ISO_CODE}` - n/a - Payer country defined by IP Address. * - :code:`${PREFERRED_LANGUAGE}` - n/a - Payer language send by Connecting Party via input parameters. * - :code:`${BROWSER_LANGUAGE}` - n/a - Payer language defined by browser settings. * - :code:`${CUSTOMER_LANGUAGE}` - n/a - Payer language send by Connecting Party via input parameters or defined by browser settings if first is not set. .. _finish_page_customization_reference: Finish Page Customization =========================================================================== Finish Page Template ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ A form on which the Payer is shown the :ref:`final status` of his request. .. highlight:: html ::

Processing of the payment has finished

Order Invoice: $!{MERCHANT_ORDER_ID}

Order ID: $!{PAYNET_ORDER_ID}

Status: $!{STATUS}

#if($ERROR_MESSAGE)

Error: $!{ERROR_MESSAGE}

#end Finish Page Macros ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. list-table:: :widths: 30, 10, 30 :header-rows: 1 :class: longtable * - Field Name Macro - Field Value Macro - Description * - :code:`${STATUS}` - n/a - Order status. * - :code:`${PAYNET_ORDER_ID}` - n/a - System order id. * - :code:`${MERCHANT_ORDER_ID}` - n/a - Connecting Party order id. * - :code:`${ERROR_MESSAGE}` - n/a - Contains the reason for decline or error details. * - :code:`${SKIN_VERSION}` - n/a - CSS skin version. * - :code:`${CUSTOMER_IP_COUNTRY_ISO_CODE}` - n/a - Payer country defined by IP Address. * - :code:`${PREFERRED_LANGUAGE}` - n/a - Payer language send by Connecting Party via input parameters. * - :code:`${BROWSER_LANGUAGE}` - n/a - Payer language defined by browser settings. * - :code:`${CUSTOMER_LANGUAGE}` - n/a - Payer language send by Connecting Party via input parameters or defined by browser settings if first is not set. * - :code:`${AMOUNT}` - n/a - Amount. Not available for Account verification. * - :code:`${CURRENCY}` - n/a - Currency. Not available for Account verification. * - :code:`${DESCRIPTION}` - n/a - Transaction description. Not available for Account verification. * - :code:`${DATE}` - n/a - Transaction date. Not available for Account verification. * - :code:`${PAYNET_PROCESSING_DATE}` - n/a - Payneteasy processing date. Not available for Account verification. * - :code:`${RRN}` - n/a - Retrieval Reference Number. Not available for Account verification. * - :code:`${AUTH_CODE}` - n/a - Authorization Code. Not available for Account verification. * - :code:`${CARD_TYPE}` - n/a - Card type. Not available for Account verification. * - :code:`${LAST_FOUR_DIGITS}` - n/a - Last four digits of a card. Not available for Account verification. * - :code:`${CUSTOMER_REDIRECT_URL}` - n/a - URL the cardholder will be redirected to upon completion of the transaction. .. _payment_cashier_page_customization_reference: Payment Cashier Page Customization ==================================================================== .. note:: This page is relevant only for :ref:`Payment Cashier` integration. Parallel Form Template Sample ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Parallel Form is a form for the Payer to select one of the available payment methods to perform a transaction. .. code-block:: guess

#if (!$HAS_PARALLEL_FORM_PAYMENT_METHODS) #end #if ($HAS_PARALLEL_FORM_PAYMENT_METHODS)

$!{paymentMethod.name}

#foreach ($paymentMethod in $PARALLEL_FORM_PAYMENT_METHODS)

1) style="display: none;"#end> ${MERCHANT}

#end #end #if ($HAS_PARALLEL_FORM_PAYMENT_METHODS) #foreach ($paymentMethod in $PARALLEL_FORM_PAYMENT_METHODS) #if ($paymentMethod.iframe)

1) style="display: none;"#end>

#end #end #end

For more information see :ref:`Country Codes` and :ref:`Language Codes`. Parallel Form Macros ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. list-table:: :widths: 30, 10, 30 :header-rows: 1 :class: longtable * - Field Name Macro - Field Value Macro - Description * - :code:`$!CUSTOMER_IP_COUNTRY_ISO_CODE` - n/a - Payer`s country defined by IP Address. * - :code:`$!CUSTOMER_COUNTRY_CODE` - n/a - Billing country of customer sent in incoming API request. * - :code:`$CUSTOMER_LANGUAGE` - n/a - Payer language sent by Connecting Party via input parameters or defined by browser settings if first is not set. * - :code:`$HAS_PARALLEL_FORM_PAYMENT_METHODS` - n/a - Determines the availability of parallel form payment methods. * - :code:`$paymentMethod` - n/a - Payment method object. * - :code:`$PARALLEL_FORM_PAYMENT_METHODS` - n/a - Array with available parallel form payment methods. * - :code:`$!{paymentMethod.identifier}` - n/a - Payment method identifier. * - :code:`$velocityCount` - n/a - Sequence number of the payment method. * - :code:`$paymentMethod.iframe` - n/a - Iframe of payment method. * - :code:`$!{paymentMethod.name}` - n/a - Payment method name. * - :code:`${MERCHANT}` - n/a - End point display name. * - :code:`$!{paymentMethod.countries}` - n/a - Countries which are set for this payment method. * - :code:`$$!paymentMethod.initSessionUrl` - n/a - URL for payment method session initialization. * - :code:`$!WAIT_FORM_URL` - n/a - Waiting form URL. * - :code:`$p` - n/a - Waiting form parameter. * - :code:`$WAIT_FORM_PARAMETERS` - n/a - Waiting form parameters array. * - :code:`$p.key` - n/a - Waiting form parameter key. * - :code:`$!p.value` - n/a - Waiting form parameter value. * - :code:`$!{INTERNAL_SECTION}` - n/a - Internal for iFrame integration. Parallel Form Scripts ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The following Parallel Form scripts are required for it`s operating. The first script should be added into :code:`` tag of html document: .. highlight:: html :: Second script should be added to html code before the :code:`` close tag. .. highlight:: html :: If needed to determine the Payer billing country on the data sent via the API, :code:`$!CUSTOMER_COUNTRY_CODE` is used. If needed to determine the Payer billing country on the IP address from the Payer browser, use :code:`$!CUSTOMER_IP_COUNTRY_ISO_CODE`, billing country will also change according to IP. The master set up by Billing country: .. highlight:: html ::