.. _/api/v2/make-rebill-preauth/: /api/v2/make-rebill-preauth ######################################################## .. contents:: :local: .. role:: ex .. role:: code Introduction ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Preauth recurring transactions are initiated through :code:`HTTPS POST` request to the :ref:`URLs` and the :ref:`parameters` specified below. Use :ref:`SHA-1` for authentication. See :ref:`statuses`. .. _make-rebill_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/make-rebill-preauth/ENDPOINTID` - :ex:`https://gate.payneteasy.com/paynet/api/v2/make-rebill-preauth/ENDPOINTID` * - :ex:`https://sandbox.payneteasy.com/paynet/api/v2/make-rebill-preauth/group/ENDPOINTGROUPID` - :ex:`https://gate.payneteasy.com/paynet/api/v2/make-rebill-preauth/group/ENDPOINTGROUPID` .. _make-rebill_request_parameters: Request Parameters ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. note:: | Request must have content-type=application/x-www-form-urlencoded. .. list-table:: :widths: 30, 45, 25 :header-rows: 1 :class: longtable * - Parameter Name - Description - Value * - :code:`login` - Connecting Party's login name. - | ``Necessity``: Required | ``Type``: String | ``Length``: 20 * - :code:`client_orderid` - Connecting Party’s order identifier of the transaction. - | ``Necessity``: Required | ``Type``: String | ``Length``: 128 * - :code:`cardrefid` - Card reference ID obtained at Card Registration Stage :ref:`/api/v2/create-card-ref/`. - | ``Necessity``: Required | ``Type``: String | ``Length``: 20 * - :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 (three-letter currency code). Example of valid parameter values are: :ex:`USD` for US Dollar :ex:`EUR` for European Euro. - | ``Necessity``: Required | ``Type``: String | ``Length``: 3 * - :code:`enumerate_amounts` - This parameter may comprise multiple amounts, separated with :ex:`,`. Payneteasy will cycle through the amounts of the list, try to make a payment on that amount, until there are no more amounts from the list, or not get approved. - | ``Necessity``: Optional | ``Type``: String | ``Length``: 128 * - :code:`recurrent_scenario` - Type of the rebill transaction. Possible values: :ex:`REGULAR` or :ex:`IRREGULAR`. If this parameter is sent in the request, it will have priority over the same parameter specified on gate level. Only used for specific acquirers. - | ``Necessity``: Optional | ``Type``: String | ``Length``: 50 * - :code:`recurrent_initiator` - Initiator of the rebill transaction. Possible values: :ex:`CARDHOLDER` or :ex:`MERCHANT`. If this parameter is sent in the request, it will have priority over the same parameter specified on gate level. Only used for specific acquirers. - | ``Necessity``: Optional | ``Type``: String | ``Length``: 50 * - :code:`cvv2` - Customer's CVV2 code. CVV2 (Card Verification Value) is a three- or four-digit number AFTER the credit card number in the signature area of the card. May be empty or absent if bank gateway supports processing without CVV2. - | ``Necessity``: Optional | ``Type``: Numeric | ``Length``: 3-4 * - :code:`ipaddress` - Customer's IP address, included for fraud screening purposes. - | ``Necessity``: Required | ``Type``: String | ``Length``: 45 * - :code:`comment` - A short comment. - | ``Necessity``: Optional | ``Type``: String | ``Length``: 50 * - :code:`order_desc` - Order description. - | ``Necessity``: Required | ``Type``: String | ``Length``: 64k * - :code:`control` - | Checksum generated by :ref:`SHA-1`. Control string is represented as concatenation of the following parameters: | 1. Request parameter: :ex:`login` | 2. Request parameter: :ex:`client_orderid` | 3. Request parameter: :ex:`cardrefid` | 4. Request parameter: :ex:`amount` in minor units (if sent). | 5. request parameter: :ex:`currency` | 6. :ex:`merchant_control` (Control key assigned to Connecting Party account in the Payneteasy gateway system). - | ``Necessity``: Required | ``Type``: String | ``Length``: 40 * - :code:`purpose` - Destination to where the payment goes. It is useful for the Connecting Party who let their clients to transfer money from a credit card to some type of client’s account, e.g. game or mobile phone account. Sample values are: :ex:`+9999999999`; :ex:`mail@example.com` etc. This value will be used by fraud monitoring system. - | ``Necessity``: Optional | ``Type``: String | ``Length``: 128 * - :code:`redirect_url` - URL the cardholder will be redirected to upon completion of the transaction. Please note that the cardholder will be redirected in any case, no matter whether the transaction is :ex:`approved` or :ex:`declined`. This parameter should not be used to retrieve results from Payneteasy gateway, because all parameters go through client's browser and can be lost during transmission. To deliver the correct payment result to the backend :ex:`server_callback_url` must be used instead. Parameter is required for 3DS flow and optional for non-3DS. :ex:`https://doc.payneteasy.com` can be used for testing purposes if it's unknown whether 3DS is used or not. - | ``Necessity``: Optional | ``Type``: String | ``Length``: 1024 * - :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` - Any additional information for this transaction which may be useful in Connecting Party's external systems, e.g. :ex:`VIP customer`, :ex:`TV promo campaign lead`. Will be returned in Status response and Connecting Party Callback. - | ``Necessity``: Optional | ``Type``: String | ``Length``: 64 .. include:: empty.txt .. _make-rebill_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 * - Sale 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:`serial-number` - Unique number assigned by Payneteasy server to particular request from the Connecting Party. * - :code:`merchant-order-id` - Connecting Party's order id. * - :code:`paynet-order-id` - Order id assigned to the order by Payneteasy. * - :code:`end-point-id` - ID of the used End Point. * - :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. Request Example ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: text POST /paynet/api/v2/make-rebill-preauth/46750 HTTP/1.1 Host: https://sandbox.payneteasy.com User-Agent: curl/7.85.0 Accept: */ Content-Length: 229 Content-Type: application/x-www-form-urlencoded Connection: close &login=login &client_orderid=902B4FF5 &cardrefid=1461665 &amount=5.00 ¤cy=USD &cvv2=321 &ipaddress=34.129.65.12 &comment=Information abount Rebill &order_desc=Rebill order description &control=a37f4972233b4a5dbfb4dcaae149ce7feed01ef9 Success Response Example ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: javascript HTTP/1.1 200 Server: server Date: Thu, 02 Feb 2023 13:10:44 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: 144 &type=async-response &serial-number=00000000-0000-0000-0000-000002e0d498 &merchant-order-id=902B4FF5 &paynet-order-id=6937030 &end-point-id=46750 Fail Response Example ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: javascript HTTP/1.1 200 Server: server Date: Thu, 02 Feb 2023 13:18:50 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: 164 type=validation-error &serial-number=00000000-0000-0000-0000-000002e0d614 &merchant-order-id=902B4FF5 &error-message=End+point+with+id+99999+not+found &error-code=3 Postman Collection ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. raw:: html :file: ../_static/Postman/Postman_recurrent.html Request Builder ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. only:: insurance_enabled .. raw:: html :file: ../_static/examples/d2_insurance_Request_Debug_recurrent_preauth.html .. only:: insurance_disabled .. raw:: html :file: ../_static/examples/recurrent_transaction_Response_Debug_Preauth.html