.. _api_v2_add-document: /api/v2/documents/add-document ############################## .. toctree:: :maxdepth: 1 .. contents:: :local: .. role:: ex .. role:: code Introduction ------------ Add document is initiated through :code:`HTTPS POST` request by using :ref:`URL` and the :ref:`parameters` specified below. :ref:`OAuth HMAC-SHA1` is used for authentication (two-legged mode). .. _api_url_add-document: 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 Base URL - Production Base URL * - :ex:`https://sandbox.payneteasy.com/paynet/api/v2/documents/add-document/ENDPOINTID/ORDERID` - :ex:`https://gate.payneteasy.com/paynet/api/v2/documents/add-document/ENDPOINTID/ORDERID` Request Headers --------------- .. list-table:: :widths: 20 80 :header-rows: 0 :class: longtable * - Content-Type - The request must contain this header with the following value: :code:`binary/octet-stream`. * - Content-Length - This header specifies correct file size in bytes. * - Authorization - :ref:`OAuth HMAC-SHA1` is used for authentication (two-legged mode). .. _request_parameters_add_document: Request Parameters ------------------ .. list-table:: :widths: 25, 45, 25 :header-rows: 1 :class: longtable * - Request parameters - Description - Value * - :code:`endpoint id` - Endpoint of the order. This parameter is passed in request URL. - | ``Necessity``: Required | ``Type``: Numeric | ``Length``: 10 * - :code:`order id` - Transaction order identifier assigned by Payment Gateway. This parameter is passed in request URL. - | ``Necessity``: Required | ``Type``: String | ``Length``: 128 * - :code:`consumer key` - Connecting Party’s login name. This parameter is used to calculate signature and is passed in Authorization request header as :code:`oauth_consumer_key`. - | ``Necessity``: Required | ``Type``: String | ``Length``: 20 * - :code:`consumer secret` - Connecting Party’s control key. This parameter is used to calculate signature as a part of Encryption key for OAuth HMAC-SHA1. - | ``Necessity``: Required | ``Type``: String | ``Length``: 40 * - :code:`file name` - Name of the file to upload, e.g. :ex:`filename.txt`. This parameter is passed in the request body as file and in a query part of request URL as :code:`fileName`. - | ``Necessity``: Required | ``Type``: String | ``Length``: 255 * - :code:`comment`. - Adds a comment to attached file, accessible via pointing cursor on file in order details page. This parameter is passed in a query part of request URL. - | ``Necessity``: Optional | ``Type``: String | ``Length``: 255 * - :code:`file content` - Field for the contents of the file. Used to calculate only txt files via bytes per symbol. Use either :code:`file content` or a combination of :code:`file sha1` and :code:`file size`, not both. Mandatory, if :code:`file sha1` and :code:`file size` fields are empty. This parameter is passed in the request body as a string. - | ``Necessity``: Conditional | ``Type``: String | ``Length``: 255 * - :code:`file sha1` - Calculate sha1 of the file and insert here. Use either :code:`file content` or a combination of :code:`file sha1` and :code:`file size`, not both. Mandatory, if :code:`file content` field is empty. This parameter is passed in base part of request URL, after :code:`order id` parameter. - | ``Necessity``: Conditional | ``Type``: String | ``Length``: 255 * - :code:`file size` - Field for file size in bytes. Use either :code:`file content` or a combination of :code:`file sha1` and :code:`file size`, not both. Mandatory, if :code:`file content` field is empty. This parameter is passed in Content-Length request header. - | ``Necessity``: Conditional | ``Type``: String | ``Length``: 255 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:`status` - May have values such as: :ex:`success` or :ex:`error`. :ex:`Success` means that document attached to order successfully. :ex:`Error` provides error-message. * - :code:`error-message` - If status is :ex:`error` this parameter contains the reason for decline or error details. Request Example --------------- .. code-block:: guess POST /paynet/api/v2/documents/add-document/6655/1852755/561d839dde5ae8deeced73c14902e04dc746bfc2?fileName=test5.txt&comment=no%20comments HTTP/1.1 Host: sandbox.payneteasy.com User-Agent: curl/7.83.0 Accept: */* Content-Type: binary/octet-stream Content-Length: 7 Authorization: OAuth realm="",oauth_signature_method="HMAC-SHA1",oauth_signature="ItDxdBQtPRqLiKTAOdy%2BAtDB5cI%3D" Connection: close Success Response Example ------------------------ .. code-block:: guess HTTP/1.1 200 Server: server Date: Tue, 18 Jul 2023 06:10:27 GMT Content-Type: text/plain;charset=utf-8 Content-Length: 14 Connection: close X-XSS-Protection: 1 Strict-Transport-Security: max-age=31536000 Content-Language: en-US Strict-Transport-Security: max-age=31536000 status=success Fail Response Example --------------------- .. code-block:: guess HTTP/1.1 200 Server: server Date: Tue, 18 Jul 2023 07:37:34 GMT Content-Type: text/plain;charset=utf-8 Content-Length: 46 Connection: close X-XSS-Protection: 1 Strict-Transport-Security: max-age=31536000 Content-Language: en-US Strict-Transport-Security: max-age=31536000 status=error &error-message=File+hash+mismatch Request Builder --------------- | The file can be uploaded in 2 different ways: | | 1. :ex:`Upload file attached to request` - to perform this operation the curl request should be executed in the folder with the target file that must be attached. :code:`file sha1` and :code:`file size` parameters must be filled. | | 2. :ex:`Upload file with one-line content` - to perform this operation :code:`file content` parameter must be filled. | .. raw:: html :file: ../_static/examples/add_document_debug.html