This chapter describes the API that the GNU Taler demonstrator bank offers to access accounts.
This API differs from the “Bank Integration API” in that it provides advanced API access to accounts, as opposed to enabling wallets to withdraw with a better user experience (“tight integration”).
The following endpoints require HTTP “Basic” authentication with the account name and account password, at least in the GNU Taler demo bank implementation.
GET ${BANK_API_BASE_URL}/accounts/${account_name}¶Request the current balance of an account. (New: ) In case of a public bank account, no authentication is required.
Response
Details
interface BankAccountBalanceResponse {
// Available balance on the account.
balance: {
amount: Amount;
credit_debit_indicator: "credit" | "debit";
};
}
POST ${BANK_API_BASE_URL}/accounts/${account_name}/withdrawals¶Create a withdrawal operation, resulting in a taler://withdraw URI.
Request
interface BankAccountCreateWithdrawalRequest {
// Amount to withdraw.
amount: Amount;
}
Response
interface BankAccountCreateWithdrawalResponse {
// ID of the withdrawal, can be used to view/modify the withdrawal operation.
withdrawal_id: string;
// URI that can be passed to the wallet to initiate the withdrawal.
taler_withdraw_uri: string;
}
GET ${BANK_API_BASE_URL}/accounts/${account_name}/withdrawals/${withdrawal_id}¶Query the status of a withdrawal operation.
Response
Details
interface BankAccountGetWithdrawalResponse {
// Amount that will be withdrawn with this withdrawal operation.
amount: Amount;
// Was the withdrawal aborted?
aborted: boolean;
// Has the withdrawal been confirmed by the bank?
// The wire transfer for a withdrawal is only executed once
// both confirmation_done is true and selection_done is true.
confirmation_done: boolean;
// Did the wallet select reserve details?
selection_done: boolean;
// Reserve public key selected by the exchange,
// only non-null if selection_done is true.
selected_reserve_pub: string | null;
// Exchange account selected by the wallet, or by the bank
// (with the default exchange) in case the wallet did not provide one
// through the Integration API.
selected_exchange_account: string | null;
}
POST ${BANK_API_BASE_URL}/accounts/${account_name}/withdrawals/${withdrawal_id}/abort¶Abort a withdrawal operation. Has no effect on an already aborted withdrawal operation.
200 OK: The withdrawal operation has been aborted. The response is an empty JSON object. 409 Conflict: The reserve operation has been confirmed previously and can’t be aborted.
POST ${BANK_API_BASE_URL}/accounts/${account_name}/withdrawals/${withdrawal_id}/confirm¶Confirm a withdrawal operation. Has no effect on an already confirmed withdrawal operation.
Response
GET ${BANK_API_BASE_URL}/accounts/${account_name}/transactions¶Retrieve all the transactions where the bank account with the label account_name
was debited or credited.
Request
FIXME: this needs query parameters to filter the results.
Response
- interface BankAccountTransactionsResponse {
- transactions: BankAccountTransactionInfo[];
}
GET ${BANK_API_BASE_URL}/accounts/${account_name}/transactions/${transaction_id}¶Response
Retrieve the transaction whose identifier is transaction_id,
in the following format:
interface BankAccountTransactionInfo {
creditorIban: string;
creditorBic: string;
creditorName: string;
debtorIban: string;
debtorBic: string;
debtorName: string;
amount: number;
currency: string;
subject: string;
date: string; // YYYY-MM-DD
uid: string; // transaction (unique) ID
direction: "DBIT" | "CRDT";
}
POST ${BANK_API_BASE_URL}/accounts/${account_name}/transactions¶Create a new transaction where the bank account with the label account_name is debited.
Request
interface CreateBankAccountTransactionCreate {
// All the details corresponding to the wire transfer
// to initiate, in the 'payto' format (RFC 8905).
// Only: 'iban' authority and 'receiver-name', 'amount',
// and 'message' query parameters are accepted.
// The following example is accepted:
//
// payto://iban/AB0123456789?receiver-name=Jane%20Doe&message=donation&amount=EUR:1
paytoUri: string;
}
Response
POST ${BANK_API_BASE_URL}/testing/register¶Create a new bank account. This endpoint should be disabled for most deployments, but is useful for automated testing / integration tests.
Request
interface BankRegistrationRequest {
username: string;
password: string;
}
Response
200 OK: Registration was successful.