.. _api_v2_get-exchange:

/api/v2/get-exchange
##########################

.. contents::
  :local:

.. role:: ex

.. role:: code

Introduction
^^^^^^^^^^^^

Get exchange rate is initiated through :code:`HTTPS POST` request by using :ref:`URLs<api_v2_get-exchange_request_url>` and the :ref:`parameters<api_v2_get-exchange_parameters>` specified below. Use :ref:`OAuth HMAC-SHA1<HMAC-SHA1>` for authentication. See :ref:`statuses`.

.. _api_v2_get-exchange_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/get-exchange/ENDPOINTID`
     - :ex:`https://gate.payneteasy.com/paynet/api/v2/get-exchange/ENDPOINTID`

.. _api_v2_get-exchange_parameters:

Request Parameters
^^^^^^^^^^^^^^^^^^

.. note::
  | Request must have content-type=application/x-www-form-urlencoded and :ref:`Authorization headers<HMAC-SHA1>`.

.. list-table::
  :widths: 25, 45, 25
  :header-rows: 1
  :class: longtable

  * - Parameter Name
    - Description
    - Value
  * - :code:`exchange-provider`
    - Exchange provider.
    - | ``Necessity``: Required
      | ``Type``: String
      | ``Length``: 128
  * - :code:`exchange-currency-code-from`
    - Currency code that need to exchange (See::ref:`Currency codes<currency_codes>`).
    - | ``Necessity``: Required
      | ``Type``: String
      | ``Length``: 128
  * - :code:`exchange-currency-code-to`
    - Currency code that need to get (See::ref:`Currency codes<currency_codes>`).
    - | ``Necessity``: Required
      | ``Type``: String
      | ``Length``: 128

.. _api_v2_get-exchange_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

   * - Parameter Name
     - Description
   * - :code:`exchange-low-rate`
     - Provider’s buy rate.
   * - :code:`exchange-high-rate`
     - Provider’s sell rate.

Request Example
^^^^^^^^^^^^^^^

.. code-block:: guess

  POST /paynet/api/v2/get-exchange/39790 HTTP/1.1
  Host: sandbox.payneteasy.com
  User-Agent: curl/7.83.0
  Accept: */*
  Authorization: OAuth realm="",oauth_version="1.0",oauth_consumer_key="test_merch",oauth_timestamp="1684995901",oauth_nonce="1kKy3hMlAe1",oauth_signature_method="HMAC-SHA1",oauth_signature="jGUaNFqLvBO1gGgWag%2FSU3wMnUc%3D"
  Content-Length: 222
  Content-Type: application/x-www-form-urlencoded
  Connection: close

  exchange-currency-code-from=USD
  &exchange-currency-code-to=RUB
  &exchange-provider=test
  &oauth_consumer_key=test_merch
  &oauth_nonce=1kKy3hMlAe1
  &oauth_signature_method=HMAC-SHA1
  &oauth_timestamp=1684995901
  &oauth_version=1.0

Success Response Example
^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: javascript

  HTTP/1.1 200
  Server: server
  Date: Thu, 25 May 2023 06:27:46 GMT
  Content-Length: 48
  Connection: close
  X-XSS-Protection: 1
  X-Content-Type-Options: nosniff
  Strict-Transport-Security: max-age=31536000
  Strict-Transport-Security: max-age=31536000

  exchange-low-rate=10.00
  &exchange-high-rate=20.00

Fail Response Example
^^^^^^^^^^^^^^^^^^^^^

.. code-block:: javascript

  HTTP/1.1 403
  Server: server
  Date: Thu, 25 May 2023 07:02:59 GMT
  Content-Type: text/html
  Content-Length: 735
  Connection: close
  X-XSS-Protection: 1
  X-Content-Type-Options: nosniff
  Strict-Transport-Security: max-age=31536000

  error-message=Book TCurrencyBook was not found by code USB

Postman Collection
^^^^^^^^^^^^^^^^^^

.. raw:: html
    :file: ../_static/Postman/Postman_get_exchange_rate.html

Request Builder
^^^^^^^^^^^^^^^

.. raw:: html
      :file: ../_static/examples/get_exchange_rate_Debug.html