taler-docs

Documentation for GNU Taler components, APIs and protocols
Log | Files | Refs | README | LICENSE

get-sessions-SESSION_ID.rst (2310B)

      1 .. http:get:: [/instances/$INSTANCE]/sessions/$SESSION_ID?fulfillment_url=$URL
      2 
      3   Query the payment status for a session and fulfillment URL.
      4   This endpoint is for Web shops,
      5   Paivana and other integrations (like JavaScript from inside the customer's
      6   browser) that need an unauthenticated way to query a payment status where
      7   they do not know the order ID because they *only* know the session ID they
      8   passed into the template mechanism.  Here, the "$SESSION_ID" is an arbitrary
      9   string, the semantics of which are left to the application. However, it must
     10   match the "$SESSION_ID" passed to the template mechanism.
     11 
     12   Since protocol **v25**.
     13 
     14   **Request:**
     15 
     16   :query fulfillment_url=URL: *Mandatory.* Specifies the fulfillment URL
     17     for which the order must be valid.
     18   :query timeout_ms=NUMBER: *Optional.*  If specified, the merchant backend will
     19     wait up to ``timeout_ms`` milliseconds for completion of the payment before
     20     sending the HTTP response.  A client must never rely on this behavior, as the
     21     merchant backend may return a response immediately.
     22 
     23   **Response:**
     24 
     25   :http:statuscode:`200 OK`:
     26     The response is a `GetSessionStatusPaidResponse`. Returned if an
     27     order that paid for the respective session exists and was paid.
     28   :http:statuscode:`400 Bad Request`:
     29     A required parameter is missing or malformed.
     30     Returned with ``TALER_EC_GENERIC_PARAMETER_MISSING`` or
     31     ``TALER_EC_GENERIC_PARAMETER_MALFORMED``.
     32   :http:statuscode:`202 Accepted`:
     33     The response is a `GetSessionStatusUnpaidResponse`.  Returned if an
     34     order that paid for the respective session exists,
     35     but not yet paid.
     36   :http:statuscode:`404 Not found`:
     37     The merchant backend is unaware of an order matching the given session.
     38     Returned with ``TALER_EC_MERCHANT_GENERIC_SESSION_UNKNOWN``.
     39   :http:statuscode:`500 Internal Server Error`:
     40     The server experienced an internal failure.
     41     Returned with ``TALER_EC_GENERIC_DB_FETCH_FAILED``.
     42 
     43   **Details:**
     44 
     45   .. ts:def:: GetSessionStatusPaidResponse
     46 
     47     interface GetSessionStatusPaidResponse {
     48 
     49       // Order ID of the paid order.
     50       order_id: string;
     51 
     52     }
     53 
     54   .. ts:def:: GetSessionStatusUnpaidResponse
     55 
     56     interface GetSessionStatusUnpaidResponse {
     57 
     58       // Order ID of the unpaid order.
     59       order_id: string;
     60 
     61     }