.. _/api/v2/sale-echeck/: /api/v2/sale-echeck #################### .. contents:: :local: .. role:: ex .. role:: code Introduction ^^^^^^^^^^^^ Sale-eCheck 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_echeck_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/sale-echeck/ENDPOINTID` - :ex:`https://gate.payneteasy.com/paynet/api/v2/sale-echeck/ENDPOINTID` .. _api_v2_echeck_request_parameters: Request Parameters ^^^^^^^^^^^^^^^^^^ .. note:: | Request must have content-type=application/x-www-form-urlencoded. | 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:`first_name` - Payer's first name. Parameter necessity depends on the Acquiring channel and necessity of it must be clarified with Tech Support. - | ``Necessity``: Required | ``Type``: String | ``Length``: 50 * - :code:`last_name` - Payer’s last name. Parameter necessity depends on the Acquiring channel and necessity of it must be clarified with Tech Support. - | ``Necessity``: Required | ``Type``: String | ``Length``: 50 * - :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:`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:`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:`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:`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:`routing_number` - This element should contain the Payer’s 9 digit bank routing number. - | ``Necessity``: Required | ``Type``: String | ``Length``: 9 * - :code:`account_number` - This element should contain the Payer’s bank account number. - | ``Necessity``: Required | ``Type``: String | ``Length``: 20 * - :code:`check_number` - This element should contain the Payer’s check number. - | ``Necessity``: Optional | ``Type``: String | ``Length``: 22 * - :code:`check_date` - This element should contain the Payer’s check date. Format is :ex:`MM/DD/YYYY`. - | ``Necessity``: Optional | ``Type``: String | ``Length``: 12 * - :code:`bank_name` - This element should contain the Payer’s bank name. - | ``Necessity``: Optional | ``Type``: String | ``Length``: 12 * - :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) | 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:`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 .. _api_v2_echeck_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:`status` - See :ref:`Status List` for 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. Request Example ^^^^^^^^^^^^^^^ .. code-block:: guess POST /paynet/api/v2/sale-echeck/39790 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 &amount=10.55 &email=john.smith@gmail.com ¤cy=USD &ipaddress=65.153.12.232 &routing_number=113024588 &account_number=1234567890 &check_number=77778888 &check_date=02/22/2025 &bank_name=testbank &server_callback_url=https%3A%2F%2Fhttpstat.us%2F200 &control=5ce2641b344bf35930ba9536055d24f038a1065b Success Response Example ^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: javascript HTTP/1.1 200 Server: server Date: Wed, 26 Apr 2023 13:51:16 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-000002e3450d &merchant-order-id=902B4FF5 &paynet-order-id=6994012 &end-point-id=39790 Fail Response Example ^^^^^^^^^^^^^^^^^^^^^ .. code-block:: javascript HTTP/1.1 200 Server: server Date: Wed, 26 Apr 2023 13:51:16 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=validation-error &serial-number=00000000-0000-0000-0000-000002b36f64 &merchant-order-id=inv4097763 &error-message=End+point+with+id+39790+not+found &error-code=3 Postman Collection ^^^^^^^^^^^^^^^^^^ .. raw:: html :file: ../_static/Postman/Postman_sale-echeck.html Request Builder ^^^^^^^^^^^^^^^ .. raw:: html :file: ../_static/examples/sale_echeck_integration_Request_Debug.html