taler-docs

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

post-transfer.rst (2989B)

      1 .. http:post:: /transfer
      2 
      3   Initiate a new wire transfer from the exchange's bank account, typically to a
      4   merchant.
      5 
      6   The exchange's bank account is not included in the request, but instead
      7   derived from the username in the ``Authorization`` header and/or the request
      8   base URL.
      9 
     10   To make the API idempotent, the client must include a nonce. Requests with
     11   the same nonce are rejected unless the request is the same.
     12 
     13   **Request:**
     14 
     15   .. ts:def:: TransferRequest
     16 
     17     interface TransferRequest {
     18       // Nonce to make the request idempotent.  Requests with the same
     19       // ``request_uid`` that differs in any of the other fields
     20       // are rejected.
     21       request_uid: HashCode;
     22 
     23       // Amount to transfer.
     24       amount: Amount;
     25 
     26       // Base URL of the exchange.  Shall be included by the bank gateway
     27       // in the appropriate section of the wire transfer details.
     28       exchange_base_url: string;
     29       
     30       // Optional additional metadata to be stored in the transaction.
     31       // Must match [a-zA-Z0-9-.:]{1, 40}
     32       // @since **v5**
     33       metadata?: string;
     34 
     35       // Wire transfer identifier chosen by the exchange,
     36       // used by the merchant to identify the Taler order(s)
     37       // associated with this wire transfer.
     38       wtid: ShortHashCode;
     39 
     40       // The recipient's account identifier as a full payto URI.
     41       credit_account: string;
     42     }
     43 
     44   **Response:**
     45 
     46   :http:statuscode:`200 OK`:
     47     The request has been correctly handled, so the funds have been transferred to
     48     the recipient's account.  The body is a `TransferResponse`.
     49   :http:statuscode:`400 Bad request`:
     50     Request malformed. The bank replies with an `ErrorDetail` object.
     51   :http:statuscode:`401 Unauthorized`:
     52     Authentication failed, likely the credentials are wrong.
     53   :http:statuscode:`404 Not found`:
     54     The endpoint is wrong or the user name is unknown. The bank replies with an `ErrorDetail` object.
     55   :http:statuscode:`409 Conflict`:
     56     * ``TALER_EC_BANK_TRANSFER_REQUEST_UID_REUSED``: an operation with the same ``request_uid`` but different details has been submitted before.
     57     * ``TALER_EC_BANK_TRANSFER_WTID_REUSED``: an operation with the same ``wtid`` but a different ``request_uid`` has been submitted before.
     58 
     59   **Details:**
     60 
     61   .. ts:def:: TransferResponse
     62 
     63     interface TransferResponse {
     64       // Timestamp that indicates when the wire transfer will be executed.
     65       // In cases where the wire transfer gateway is unable to know when
     66       // the wire transfer will be executed, the time at which the request
     67       // has been received and stored will be returned.
     68       // The purpose of this field is for debugging (humans trying to find
     69       // the transaction) as well as for taxation (determining which
     70       // time period a transaction belongs to).
     71       timestamp: Timestamp;
     72 
     73       // Opaque ID of the wire transfer initiation performed by the bank.
     74       // It is different from the /history endpoints row_id.
     75       row_id: SafeUint64;
     76     }