.. _/api/v2/preauth-form/: /api/v2/preauth-form ########################################## .. contents:: :local: .. role:: ex .. role:: code Introduction ^^^^^^^^^^^^^^^^^^^^^^^^ Preauth-form is initiated through :code:`HTTPS POST` request by using :ref:`URLs` and the :ref:`parameters` specified below. Use :ref:`SHA-1` for authentication. See :ref:`statuses`. .. _api_v2_preauth-form_url: API URLs ^^^^^^^^^^^^^^^^^^^^ .. note:: | The path in API URL should not be hardcoded, as it may be changed in future. .. list-table:: :widths: 50, 50 :header-rows: 1 :class: longtable * - Integration - Production * - :ex:`https://sandbox.payneteasy.com/paynet/api/v2/preauth-form/ENDPOINTID` - :ex:`https://gate.payneteasy.com/paynet/api/v2/preauth-form/ENDPOINTID` * - :ex:`https://sandbox.payneteasy.com/paynet/api/v2/preauth-form/group/ENDPOINTGROUPID` - :ex:`https://gate.payneteasy.com/paynet/api/v2/preauth-form/group/ENDPOINTGROUPID` .. _api_v2_preauth-form_request_parameters: Request Parameters ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. note:: | Request must have content-type=application/x-www-form-urlencoded. | Acquirer can redefine the necessity of some fields so they become required instead of optional. | Leading and trailing whitespace in input parameters will be omitted. .. list-table:: :widths: 25, 45, 25 :header-rows: 1 :class: longtable * - Parameter Name - Description - Value * - :code:`client_orderid` - Unique order identifier assigned by Connecting Party. - | ``Necessity``: Required | ``Type``: String | ``Length``: 128 * - :code:`order_desc` - Brief order description. - | ``Necessity``: Required | ``Type``: String | ``Length``: 64k * - :code:`amount` - Amount to be charged. The amount has to be specified in the highest units with :ex:`.` delimiter. For instance, :ex:`10.5` for USD means 10 US Dollars and 50 Cents. - | ``Necessity``: Required | ``Type``: Numeric | ``Length``: 10 * - :code:`currency` - Currency the transaction is charged in (See: :ref:`Currency codes`). Sample values are: :ex:`USD` for US Dollar :ex:`EUR` for European Euro. - | ``Necessity``: Required | ``Type``: String | ``Length``: 3 * - :code:`address1` - Payer’s address line 1. (Please note that in some cases it is not possible to send address length more than 50 characters. Please contact your manager for more details.) - | ``Necessity``: Required | ``Type``: String | ``Length``: 256 * - :code:`city` - Payer’s city. - | ``Necessity``: Required | ``Type``: String | ``Length``: 50 * - :code:`zip_code` - Payer’s ZIP code. - | ``Necessity``: Required | ``Type``: String | ``Length``: 10 * - :code:`country` - Payer’s country. Please see :ref:`Country codes` for a list of valid country codes. - | ``Necessity``: Required | ``Type``: String | ``Length``: 2 * - :code:`phone` - Payer’s full international phone number, including country code. - | ``Necessity``: Required | ``Type``: String | ``Length``: 15 * - :code:`email` - Payer’s e-mail address. - | ``Necessity``: Required | ``Type``: String | ``Length``: 50 * - :code:`ipaddress` - Payer’s IP address, included for fraud screening purposes. - | ``Necessity``: Required | ``Type``: String | ``Length``: 45 * - :code:`control` - | Checksum generated by :ref:`SHA-1`. Control string is represented as concatenation of the following parameters: | 1. :ex:`` (See: :ref:`Request URL`). | 2. Request parameter: :ex:`client_orderid`. | 4. Request parameter: :ex:`amount` in minor units (if sent). | 4. Request parameter: :ex:`email`. | 5. :ex:`merchant_control` (Control key assigned to Connecting Party account in the Payneteasy gateway system). - | ``Necessity``: Required | ``Type``: String | ``Length``: 40 * - :code:`first_name` - Payer's first name. - | ``Necessity``: Required | ``Type``: String | ``Length``: 50 * - :code:`last_name` - Payer’s last name. - | ``Necessity``: Required | ``Type``: String | ``Length``: 50 * - :code:`state` - Payer’s state. Please see :ref:`Mandatory State codes` for a list of valid state codes. Required for USA, Canada and Australia. - | ``Necessity``: Conditional | ``Type``: String | ``Length``: 2-3 * - :code:`redirect_url` - | URL, where the Payer is redirected to upon completion of the transaction. Please note that redirection is performed in any case, no matter whether transaction is :ex:`approved`, :ex:`declined` in any other final :ref:`status`. | Connecting Party must not use the parameters come along with the redirect HTTP Request to treat the status of the transaction. Instead Connecting Party can utilize :ex:`server_callback_url` or :ref:`status API command`. Pass :ex:`http://https://doc.payneteasy.com` if you have no need to return payer anywhere. Use either :ex:`redirect_url` or combination of :ex:`redirect_success_url` and :ex:`redirect_fail_url`, not both. - | ``Necessity``: Optional | ``Type``: String | ``Length``: 1024 * - :code:`redirect_success_url` - | URL, where the Payer is redirected to when transaction status is :ex:`approved` (See :ref:`status list`). | Connecting Party must not use the parameters come along with the redirect HTTP Request to treat the status of the transaction. Instead Connecting Party can utilize :ex:`server_callback_url` or :ref:`status API command`. Otherwise put :ex:`http://https://doc.payneteasy.com` if there is no need to redirect Payer anywhere. Use either combination of :ex:`redirect_success_url` and :ex:`redirect_fail_url` or :ex:`redirect_url`, not both. - | ``Necessity``: Optional | ``Type``: String | ``Length``: 1024 * - :code:`redirect_fail_url` - | URL, where the Payer is redirected to when transaction status is not :ex:`approved` (See :ref:`status list`). | Connecting Party must not use the parameters come along with the redirect HTTP Request to treat the status of the transaction. Instead Connecting Party can utilize :ex:`server_callback_url` or :ref:`status API command`. Pass :ex:`http://https://doc.payneteasy.com` if there is no need to redirect Payer anywhere. Use either combination of :ex:`redirect_fail_url` and :ex:`redirect_success_url` or :ex:`redirect_url`, not both. - | ``Necessity``: Optional | ``Type``: String | ``Length``: 1024 * - :code:`ssn` - Last four digits of the Payer’s social security number. - | ``Necessity``: Optional | ``Type``: Numeric | ``Length``: 32 * - :code:`birthday` - Payer’s date of birth, in the format :ex:`YYYYMMDD`. - | ``Necessity``: Optional | ``Type``: Numeric | ``Length``: 8 * - :code:`cell_phone` - Payer’s full international cell phone number, including country code. - | ``Necessity``: Optional | ``Type``: String | ``Length``: 15 * - :code:`site_url` - The URL of the E-commerce entity, where the payment is originated from. - | ``Necessity``: Optional | ``Type``: String | ``Length``: 128 * - :code:`server_callback_url` - | URL, where the transaction status is sent to. | Connecting Party may use server callback URL for custom processing of the transaction completion, e.g. to collect payment data in the Connecting Party’s information system. For the list of parameters which come along with server callback to :ex:`server_callback_url` refer to :ref:`Connecting Party callback parameters`. This parameter can be sent instead of :ex:`notify_url`. If :ex:`server_callback_url` is sent, Payment Gateway sends callback notification only when original transaction receives final status. If :ex:`notify_url` is sent, Payment Gateway sends callback notification once the original transaction receives final status, and about every future update for this original transaction (reversal, chargeback, etc). - | ``Necessity``: Optional | ``Type``: String | ``Length``: 1024 * - :code:`notify_url` - | URL, where the transaction status is sent to. | Connecting Party may use notify URL for custom processing of the transaction completion, e.g. to collect payment data in the Connecting Party’s information system. For the list of parameters which come along with server callback to :ex:`notify_url` refer to :ref:`Connecting Party callback parameters`. This parameter can be sent instead of :ex:`server_callback_url`. If :ex:`notify_url` is sent, Payment Gateway sends callback notification once the original transaction receives final status, and about every future update for this original transaction (reversal, chargeback, etc). If :ex:`server_callback_url` is sent, Payment Gateway sends callback notification only when original transaction receives final status. - | ``Necessity``: Optional | ``Type``: String | ``Length``: 1024 * - :code:`preferred_language` - Payer’s two-letter language code for multi-language payment-forms. - | ``Necessity``: Optional | ``Type``: String | ``Length``: 2 * - :code:`merchant_form_data` - 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. 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`. - | ``Necessity``: Optional | ``Type``: String | ``Length``: 128 * - :code:`minimum_transaction_amount` - This parameter can be used to limit the minimum transaction amount, if transaction amount is submitted by Payer on the form. Contact support manager to enable this feature. Value format is the same as in the :ex:`amount` parameter. - | ``Necessity``: Optional | ``Type``: Numeric | ``Length``: 10 * - :code:`maximum_transaction_amount` - This parameter can be used to limit the maximum transaction amount, if transaction amount is submitted by Payer on the form. Contact support manager to enable this feature. Value format is the same as in the :ex:`amount` parameter. - | ``Necessity``: Optional | ``Type``: Numeric | ``Length``: 10 * - :code:`customer_level` - Customer level in CMS system - | ``Necessity``: Optional | ``Type``: Varchar | ``Length``: 32 * - :code:`customer_id` - Customer ID in CMS system. Required if transaction goes via CMS (Payment Gateway mode) - | ``Necessity``: Optional | ``Type``: Int | ``Length``: 10 * - :code:`merchant_customer_identifier` - Merchant Customer ID in CMS system. Required if transaction goes via CMS (CRM mode) - | ``Necessity``: Optional | ``Type``: Varchar | ``Length``: 64 * - :code:`preferred_language` - Payer’s two-letter language code for multi-language payment forms. - | ``Necessity``: Optional | ``Type``: String | ``Length``: 2 * - :code:`card_recurring_payment_id` - Payer’s tokenized cardholder’s data ID, referred as Recurring Payment ID (RPI). Recurring Payment ID can be created with :ref:`v4 tokenization request`. - | ``Necessity``: Conditional | ``Type``: Long * - :code:`cardrefid` - Card reference ID used in subsequent recurring payments. Card reference ID can be created with :ref:`v4 tokenization request` or :ref:`v2 tokenization request`. - | ``Necessity``: Conditional | ``Type``: Long .. include:: empty.txt .. _api_v2_preauth-form_response_parameters: Response Parameters ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. note:: | Response has Content-Type: text/html;charset=utf-8 header. All fields are x-www-form-urlencoded, with (0xA) character at the end of each parameter’s value. .. list-table:: :widths: 25, 75 :header-rows: 1 :class: longtable * - Response Parameters - Description * - :code:`type` - The type of response. May be :ex:`async-response`, :ex:`validation-error`, :ex:`error`. If type equals :ex:`validation-error` or :ex:`error`, :ex:`error-message` and :ex:`error-code` parameters contain error details. * - :code:`paynet-order-id` - Order id assigned to the order by Payneteasy. * - :code:`merchant-order-id` - Connecting Party order id. * - :code:`serial-number` - Unique number assigned by Payneteasy server to particular request from the Connecting Party. * - :code:`error-message` - If status is :ex:`error` this parameter contains the reason for decline or error details. * - :code:`error-code` - The error code is case of :ex:`error` status. * - :code:`redirect-url` - The URL to the page where the Connecting Party should redirect the client's browser. Connecting Party should send :ex:`HTTP 302` redirect, see :ref:`General Payment-form Process Flow`. Request Example ^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: guess POST /paynet/api/v2/preauth-form/39539 HTTP/1.1 User-Agent: curl/7.83.0 Accept: */* Content-Length: 314 Content-Type: application/x-www-form-urlencoded Connection: close client_orderid=902B4FF5 &order_desc=Test Order Description &first_name=John &last_name=Smith &ssn=1267&birthday=19820115 &address1=100 Main st &city=Seattle &state=WA &zip_code=98102 &country=US &phone=+12063582043 &cell_phone=+19023384543 &amount=69 &email=john.smith@gmail.com ¤cy=USD &ipaddress=65.153.12.232 &site_url=https://doc.payneteasy.com &credit_card_number=4538977399606732 &card_printed_name=CARD HOLDER &expire_month=12 &expire_year=2099 &cvv2=123 &purpose=user_account1 &redirect_url=http://sandbox.payneteasy.com/doc/dummy.htm &server_callback_url=https://httpstat.us/200 &merchant_data=VIP customer &merchant_form_data=testparam%3Dtest1%26mynewparam%3Dtest2 &control=b7ba0b0ce36fda192c3772e045520c7a9cb5e442 &preferred_language=en .. include:: empty.txt Success Response Example ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: none HTTP/1.1 200 OK Server: server Date: Thu, 13 Oct 2022 09:54:53 GMT Content-Type: text/html;charset=utf-8 Connection: close Vary: Accept-Encoding X-XSS-Protection: 1 X-Content-Type-Options: nosniff Strict-Transport-Security: max-age=31536000 Content-Language: en-US Strict-Transport-Security: max-age=31536000 Content-Length: 280 type=async-form-response &serial-number=00000000-0000-0000-0000-000002ddb0d3 &merchant-order-id=Test &paynet-order-id=6863103 &redirect-url=https%3A%2F%2Fsandbox.payneteasy.com%2Fpaynet%2Fform%2Finit%2FBB587546567A31587163597A68633370432F78675258396E6F78367975715973596936522B594B4F646168553D Fail Response Example ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: none HTTP/1.1 200 OK Server: server Date: Thu, 13 Oct 2022 09:58:28 GMT Content-Type: text/html;charset=utf-8 Connection: close Vary: Accept-Encoding X-XSS-Protection: 1 X-Content-Type-Options: nosniff Strict-Transport-Security: max-age=31536000 Content-Language: en-US Strict-Transport-Security: max-age=31536000 Content-Length: 170 type=validation-error &serial-number=00000000-0000-0000-0000-000002ddb0d4 &error-message=Project+with+currency+RUB+does+not+apply+request+with+currency+USD &error-code=16 Postman Collection ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. raw:: html :file: ../_static/Postman/Postman_preauth_form.html Request Builder ^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. only:: insurance_enabled .. raw:: html :file: ../_static/examples/d2_insurance_Request_Debug_preauth.html .. only:: insurance_disabled .. raw:: html :file: ../_static/examples/payment_form_integrations_Request_Debug_preauth.html