.. _/api/v2/preauth/: /api/v2/preauth ################################ .. contents:: :local: .. role:: ex .. role:: code Introduction ^^^^^^^^^^^^^^^^^^^^^^^^ Preauth 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-request-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/ENDPOINTID` - :ex:`https://gate.payneteasy.com/paynet/api/v2/preauth/ENDPOINTID` * - :ex:`https://sandbox.payneteasy.com/paynet/api/v2/preauth/group/ENDPOINTGROUPID` - :ex:`https://gate.payneteasy.com/paynet/api/v2/preauth/group/ENDPOINTGROUPID` .. _api_v2_preauth_request_parameters_url: Request Parameters ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. note:: | Request must have content-type=application/x-www-form-urlencoded. .. 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``: 125 * - :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`. | 3. 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:`cvv2` - Payer’s CVV2 code. CVV2 (Card Verification Value) is a three- or four-digit number printed on the back of the card in the signature area. - | ``Necessity``: Required | ``Type``: Numeric | ``Length``: 3-4 * - :code:`credit_card_number` - Payer’s bank card number (also known as PAN - Primary Account Number). - | ``Necessity``: Required | ``Type``: Numeric | ``Length``: 20 * - :code:`card_recurring_payment_id` - Payer’s tokenized cardholder's data ID. Send either :code:`card_recurring_payment_id` or combination of :code:`credit_card_number`, :code:`card_printed_name`, :code:`expire_month` and :code:`expire_year`, not all. To create :code:`card_recurring_payment_id` see :ref:`api-v2-card-ref-id`. - | ``Necessity``: Required | ``Type``: Long | ``Length``: 20 * - :code:`card_printed_name` - Cardholder name, printed on the bank card. - | ``Necessity``: Required | ``Type``: String | ``Length``: 64k * - :code:`expire_month` - Bank card expiration month. - | ``Necessity``: Required | ``Type``: Numeric | ``Length``: 2 * - :code:`expire_year` - Bank card expiration year. - | ``Necessity``: Required | ``Type``: Numeric | ``Length``: 4 * - :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:`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:`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:`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:`purpose` - Destination to where the payment goes. It is useful for the Connecting Partys who let their payers to top up their accounts with bank card (Mobile phone accounts, game accounts etc.). Sample values are: :ex:`+9999999999`; :ex:`mail@example.com` etc. This value can be used by the fraud monitoring system. - | ``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:`merchant_data` - | Custom Connecting Party details, which can be attached to the transaction and passed back in the :ref:`status response`, :ref:`Connecting Party callback parameters` or :ex:`server_callback_url`. Additional information of transaction which may be useful in Connecting Party's external system, e.g. :ex:`VIP customer`, :ex:`TV promo campaign lead`. | Information returns in Status response and Connecting Party Callback. - | ``Necessity``: Optional | ``Type``: String | ``Length``: 64k * - :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:`recurring-payment-id` - Recurring Payment ID can be sent instead of cardholder data. CVV for native is not needed. Customer Data can be updated via :ref:`/api/v4/update-recurring-payment/`. Recurring Payment ID creation is initiated through :code:`HTTPS POST` request by using :ref:`URLs` and the :ref:`parameters` specified below. Use :ref:`RSA-SHA256` for authentication. - | ``Necessity``: Conditional | ``Type``: Long .. _api_v2_preauth_additional_form: Additional Fields for Preauth Transactions ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ For Connecting Party """""""""""""""""""""""""""""""""""""""" .. note:: | Browser data for 3DS 2.X is gathered by Payneteasy system on 3DS authentication stage. For some processing channels, however, the browser data and/or Connecting Party URL for 3DS challenge results must be provided in initial transaction request. Please contact Support manager to clarify if these parameters should be included in request parameters. The Connecting Party’s site needs to accurately populate the browser information for each transaction. This data can be obtained by Connecting Party’s servers. Ensure that the data is not altered or hard-coded, and that it is unique to each transaction. .. list-table:: :widths: 30, 40, 20 :header-rows: 1 :class: longtable * - Parameter Name - Description - Value * - :code:`ipaddress` - IP address of the browser as returned by the HTTP headers to the 3DS Requestor. - | ``Necessity``: Required | ``Type``: String | ``Length``: 45 * - :code:`customer_browser_accept_header` - Exact content of the HTTP accept headers as sent to the 3DS Requestor from the Cardholder’s browser. - | ``Necessity``: Required | ``Type``: String | ``Length``: 2048 * - :code:`customer_browser_javascript_enabled` - Boolean that represents the ability of the cardholder browser to execute JavaScript. - | ``Necessity``: Required | ``Type``: Boolean | ``Length``: - * - :code:`customer_browser_accept_language` - Value representing the browser language as defined in IETF BCP47. - | ``Necessity``: Required | ``Type``: String | ``Length``: 8 * - :code:`customer_browser_user_agent` - Exact content of the HTTP user-agent header. - | ``Necessity``: Required | ``Type``: String | ``Length``: 2048 * - :code:`tds_areq_notification_url`, alias :code:`tds_cres_notification_url` - Fully qualified URL of Connecting Party system that will receive the CRes message or Error Message. This CRes message must be sent to Payneteasy. See details here :ref:`Upload CRes Result`. - | ``Necessity``: Optional | ``Type``: String | ``Length``: 256 * - :code:`customer_browser_info` - If true, then the fields below must be present. - | ``Necessity``: Optional | ``Type``: Boolean | ``Length``: - * - :code:`customer_browser_color_depth` - Value representing the bit depth of the colour palette for displaying images, in bits per pixel. Becomes required when :code:`browser_javaScript_enabled` = true. - | ``Necessity``: Optional | ``Type``: String | ``Length``: 2 * - :code:`customer_browser_java_enabled` - Boolean that represents the ability of the cardholder browser to execute Java. Becomes required when :code:`browser_javaScript_enabled` = true. - | ``Necessity``: Optional | ``Type``: Boolean | ``Length``: - * - :code:`customer_browser_screen_height` - Total height of the Cardholder’s screen in pixels. Becomes required when :code:`browser_javaScript_enabled` = true. - | ``Necessity``: Optional | ``Type``: Numeric | ``Length``: 6 * - :code:`customer_browser_screen_width` - Total width of the cardholder’s screen in pixels. Becomes required when :code:`browser_javaScript_enabled` = true. - | ``Necessity``: Optional | ``Type``: Numeric | ``Length``: 6 * - :code:`customer_browser_time_zone` - Time-zone offset in minutes between UTC and the Cardholder browser local time. Note that the offset is positive if the local time zone is behind UTC and negative if it is ahead. Becomes required when :code:`browser_javaScript_enabled` = true. - | ``Necessity``: Optional | ``Type``: String | ``Length``: 5 For Payment Institutions """""""""""""""""""""""""""""""""""""""""""" The PSP or Acquirer can fill the 3DS results for each transaction, if 3DS authentication is performed on their side. .. include:: ../rst_include/additional_fields_for_psp.txt .. _api_v2_preauth_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` etc. | 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:`end-point-id` - Endpoint id used for the transaction. Request with Cardholder Data Example ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: guess POST /paynet/api/v2/preauth/39549 HTTP/1.1 User-Agent: curl/7.83.0 Accept: */* Content-Length: 314 Content-Type: application/x-www-form-urlencoded Connection: close credit_card_number=4538977399606732 &card_printed_name=CARD HOLDER &expire_month=12 &expire_year=2099 &cvv2=123 &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=%2B12063582043 &cell_phone=%2B19023384543 &email=john.smith@gmail.com ¤cy=USD &amount=10.42 &ipaddress=65.153.12.232 &site_url=https://doc.payneteasy.com &purpose=user_account1 &redirect_url=https://doc.payneteasy.com/doc/dummy.htm &server_callback_url=https://httpstat.us/200 &merchant_data=VIP customer &control=768eb8162fc361a3e14150ec46e9a6dd8fbfa483 Request with Card Recurring Payment ID Example ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: none POST /paynet/api/v2/preauth/39549 HTTP/1.1 User-Agent: curl/7.83.0 Accept: */* Content-Length: 314 Content-Type: application/x-www-form-urlencoded Connection: close card_recurring_payment_id=1491927 &cvv2=123 &client_orderid=34T43R77N &order_desc=Test Order Description &amount=777 ¤cy=USD &ipaddress=65.153.12.232 &redirect_url=https://doc.payneteasy.com/doc/dummy.htm &server_callback_url=https://httpstat.us/200 &control=218d377897ce25c2ac69d99de42bc6902eb5bcd8 Success Response Example ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: javascript HTTP/1.1 200 OK Server: server Date: Mon, 05 Sep 2022 10:43:57 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: 139 type=async-response &serial-number=00000000-0000-0000-0000-000002ddb018 &merchant-order-id=123 &paynet-order-id=6863073 &end-point-id=39914 Fail Response Example ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: javascript HTTP/1.1 200 OK Server: server Date: Mon, 05 Sep 2022 10:51:14 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: 208 type=validation-error &serial-number=00000000-0000-0000-0000-000002ddb019 &merchant-order-id=123 &error-message=Validate+card+number+failed.+Card+Number+length+must+be+between+16+and+19+digits.. &error-code=8 Postman Collection ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. raw:: html :file: ../_static/Postman/Postman_preauth.html Request Builder ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. raw:: html :file: ../_static/examples/preauth_transaction_Request_Debug.html