diff options
Diffstat (limited to 'core/api-bank-wire.rst')
| -rw-r--r-- | core/api-bank-wire.rst | 134 |
1 files changed, 83 insertions, 51 deletions
diff --git a/core/api-bank-wire.rst b/core/api-bank-wire.rst index 441537ca..a76f5195 100644 --- a/core/api-bank-wire.rst +++ b/core/api-bank-wire.rst @@ -13,6 +13,8 @@ You should have received a copy of the GNU Affero General Public License along with TALER; see the file COPYING. If not, see <http://www.gnu.org/licenses/> +.. _taler-wire-gateway-http-api: + =========================== Taler Wire Gateway HTTP API =========================== @@ -24,6 +26,37 @@ well as by the auditor to query incoming and outgoing transactions. This API is currently implemented by the Taler Demo Bank, as well as by LibEuFin (work in progress). +.. http:get:: /config + + Return the protocol version and configuration information about the bank. + This specification corresponds to ``current`` protocol being version **0**. + + **Response:** + + :http:statuscode:`200 OK`: + The exchange responds with a `WireConfig` object. This request should + virtually always be successful. + + **Details:** + + .. ts:def:: WireConfig + + interface WireConfig { + // Name of the API. + name: "taler-wire-gateway"; + + // libtool-style representation of the Bank protocol version, see + // https://www.gnu.org/software/libtool/manual/html_node/Versioning.html#Versioning + // The format is "current:revision:age". + version: string; + + // Currency used by this gateway. + currency: string; + + // URN of the implementation (needed to interpret 'revision' in version). + // @since v0, may become mandatory in the future. + implementation?: string; + } -------------- Authentication @@ -36,7 +69,7 @@ The bank library authenticates requests to the wire gateway via Making Transactions ------------------- -.. http:post:: ${BASE_URL}/transfer +.. http:post:: /transfer This API allows the exchange to make a transaction, typically to a merchant. The bank account of the exchange is not included in the request, but instead derived from the user name in the @@ -45,7 +78,31 @@ Making Transactions To make the API idempotent, the client must include a nonce. Requests with the same nonce are rejected unless the request is the same. - **Request:** The body of this request must have the format of a `TransferRequest`. + **Request:** + + .. ts:def:: TransferRequest + + interface TransferRequest { + // Nonce to make the request idempotent. Requests with the same + // ``request_uid`` that differ in any of the other fields + // are rejected. + request_uid: HashCode; + + // Amount to transfer. + amount: Amount; + + // Base URL of the exchange. Shall be included by the bank gateway + // in the appropriate section of the wire transfer details. + exchange_base_url: string; + + // Wire transfer identifier chosen by the exchange, + // used by the merchant to identify the Taler order(s) + // associated with this wire transfer. + wtid: ShortHashCode; + + // The recipient's account identifier as a payto URI. + credit_account: string; + } **Response:** @@ -59,7 +116,7 @@ Making Transactions :http:statuscode:`404 Not found`: The endpoint is wrong or the user name is unknown. The bank replies with an `ErrorDetail` object. :http:statuscode:`409 Conflict`: - A transaction with the same ``transaction_uid`` but different transaction details + A transaction with the same ``request_uid`` but different transaction details has been submitted before. **Details:** @@ -67,7 +124,6 @@ Making Transactions .. ts:def:: TransferResponse interface TransferResponse { - // Timestamp that indicates when the wire transfer will be executed. // In cases where the wire transfer gateway is unable to know when // the wire transfer will be executed, the time at which the request @@ -82,37 +138,12 @@ Making Transactions } - .. ts:def:: TransferRequest - - interface TransferRequest { - // Nonce to make the request idempotent. Requests with the same - // ``transaction_uid`` that differ in any of the other fields - // are rejected. - request_uid: HashCode; - - // Amount to transfer. - amount: Amount; - - // Base URL of the exchange. Shall be included by the bank gateway - // in the appropriate section of the wire transfer details. - exchange_base_url: string; - - // Wire transfer identifier chosen by the exchange, - // used by the merchant to identify the Taler order(s) - // associated with this wire transfer. - wtid: ShortHashCode; - - // The recipient's account identifier as a payto URI. - credit_account: string; - } - - -------------------------------- Querying the transaction history -------------------------------- -.. http:get:: ${BASE_URL}/history/incoming +.. http:get:: /history/incoming Return a list of transactions made from or to the exchange. @@ -170,10 +201,11 @@ Querying the transaction history :http:statuscode:`404 Not found`: The endpoint is wrong or the user name is unknown. The bank replies with an `ErrorDetail` object. + **Details:** + .. ts:def:: IncomingHistory interface IncomingHistory { - // Array of incoming transactions. incoming_transactions : IncomingBankTransaction[]; @@ -243,7 +275,7 @@ Querying the transaction history } -.. http:get:: ${BASE_URL}/history/outgoing +.. http:get:: /history/outgoing Return a list of transactions made by the exchange, typically to a merchant. @@ -297,10 +329,11 @@ Querying the transaction history :http:statuscode:`404 Not found`: The endpoint is wrong or the user name is unknown. The bank replies with an `ErrorDetail` object. + **Details:** + .. ts:def:: OutgoingHistory interface OutgoingHistory { - // Array of outgoing transactions. outgoing_transactions : OutgoingBankTransaction[]; @@ -315,7 +348,6 @@ Querying the transaction history .. ts:def:: OutgoingBankTransaction interface OutgoingBankTransaction { - // Opaque identifier of the returned record. row_id: SafeUint64; @@ -345,26 +377,12 @@ exposed by bank gateways in production. .. _twg-admin-add-incoming: -.. http:post:: ${BASE_URL}/admin/add-incoming +.. http:post:: /admin/add-incoming Simulate a transfer from a customer to the exchange. This API is *not* idempotent since it's only used in testing. - **Request:** The body of this request must have the format of a `AddIncomingRequest`. - - **Response:** - - :http:statuscode:`200 OK`: - The request has been correctly handled, so the funds have been transferred to - the recipient's account. The body is a `AddIncomingResponse`. - :http:statuscode:`400 Bad request`: - The request is malformed. The bank replies with an `ErrorDetail` object. - :http:statuscode:`401 Unauthorized`: - Authentication failed, likely the credentials are wrong. - :http:statuscode:`404 Not found`: - The endpoint is wrong or the user name is unknown. The bank replies with an `ErrorDetail` object. - :http:statuscode:`409 Conflict`: - The 'reserve_pub' argument was used previously in another transfer, and the specification mandates that reserve public keys must not be reused. + **Request:** .. ts:def:: AddIncomingRequest @@ -383,11 +401,25 @@ exposed by bank gateways in production. debit_account: string; } + **Response:** + + :http:statuscode:`200 OK`: + The request has been correctly handled, so the funds have been transferred to + the recipient's account. The body is a `AddIncomingResponse`. + :http:statuscode:`400 Bad request`: + The request is malformed. The bank replies with an `ErrorDetail` object. + :http:statuscode:`401 Unauthorized`: + Authentication failed, likely the credentials are wrong. + :http:statuscode:`404 Not found`: + The endpoint is wrong or the user name is unknown. The bank replies with an `ErrorDetail` object. + :http:statuscode:`409 Conflict`: + The 'reserve_pub' argument was used previously in another transfer, and the specification mandates that reserve public keys must not be reused. + + **Details:** .. ts:def:: AddIncomingResponse interface AddIncomingResponse { - // Timestamp that indicates when the wire transfer will be executed. // In cases where the wire transfer gateway is unable to know when // the wire transfer will be executed, the time at which the request |