.. meta::
   :description: /api/v4/tokenize/create-ephemeral-ticket Payneteasy API endpoint: issue a single-use ephemeralTicket that lets the Hosted Fields card fields tokenize one card on the Endpoint.

.. _/api/v4/tokenize/create-ephemeral-ticket/:

/api/v4/tokenize/create-ephemeral-ticket
########################################

.. role:: ex

.. role:: code

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

Ephemeral ticket creation is initiated through :code:`HTTPS POST` request by using :ref:`URLs<create-ephemeral-ticket_request_url>` and the :ref:`headers<create-ephemeral-ticket_request_headers>` specified below. The request is signed with OAuth 1.0a — for example :ref:`RSA-SHA256`, as in the examples on this page; other signature methods are supported as well, see :ref:`Request Authentication Methods<request_authentication_methods>`.

The ticket is used by the card fields of :ref:`Hosted Fields<hosted_payment_fields>`: the Connecting Party server requests it and embeds it into the payment page. Tokenization must be enabled on the Endpoint, and the Endpoint must belong to the login the request is signed with.

.. _create-ephemeral-ticket_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.eu/paynet/api/v4/tokenize/create-ephemeral-ticket/ENDPOINTID`
     - :ex:`https://gate.payneteasy.eu/paynet/api/v4/tokenize/create-ephemeral-ticket/ENDPOINTID`

.. _create-ephemeral-ticket_request_headers:

Request Headers
^^^^^^^^^^^^^^^

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

   * - Header
     - Description
   * - :code:`Authorization`
     - OAuth 1.0a signature of the request, see :ref:`Authorization headers<RSA-SHA256>`. :ex:`oauth_consumer_key` is the Connecting Party's login.
   * - :code:`Content-Length`
     - :ex:`0` — the request has no body.

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

| This type of request has no parameters: the Endpoint is taken from the URL, the Connecting Party from the :code:`Authorization` header.

.. _create-ephemeral-ticket_response_parameters:

Response Parameters
^^^^^^^^^^^^^^^^^^^

.. note::
  | A successful response has status :code:`200` and Content-Type: application/json. A rejected request is answered with status :code:`401` and an x-www-form-urlencoded body.

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

   * - Parameter name
     - Description
     - Format
   * - :code:`ephemeralTicket`
     - Single-use ticket passed to the Hosted Fields SDK on the payment page. Issued for the Endpoint from the URL, valid for 15 minutes and consumed by a single tokenization.
     - | ``Type``: String
   * - :code:`error-id`
     - Only in a :code:`401` response. Identifier of the error, to be quoted to support.
     - | ``Type``: String
   * - :code:`message`
     - Only in a :code:`401` response. The reason the request was rejected.
     - | ``Type``: String

A :code:`401` means the request failed the signature check or authentication. Most common: the server clock is outside the :ex:`oauth_timestamp` window (10 minutes by default), :ex:`oauth_nonce` is reused, the Endpoint does not belong to the login from :ex:`oauth_consumer_key`, or a wrong signing key is configured on the Endpoint.

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

.. code-block:: http

  POST /paynet/api/v4/tokenize/create-ephemeral-ticket/ENDPOINTID HTTP/1.1
  Host: sandbox.payneteasy.eu
  Authorization: OAuth oauth_consumer_key="MERCHANTLOGIN",
                       oauth_signature_method="RSA-SHA256",
                       oauth_timestamp="...", oauth_nonce="...", oauth_version="1.0",
                       oauth_signature="..."
  Content-Length: 0

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

.. code-block:: http

  HTTP/1.1 200 OK
  Content-Type: application/json

  {
    "ephemeralTicket": "eyJhbGciOi..."
  }

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

.. code-block:: http

  HTTP/1.1 401 Unauthorized

  error-id=6f1f0b0e-1c2a-4c1e-9a3e-2f7d5b8c9a10
  &message=Wrong+token