1.8. Taler Bank Access API

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”).

1.8.1. Accounts and Withdrawals

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.

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 exchange,
  // only non-null if selection_done is 'true'
  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.

Status Codes
  • 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

Status Codes
  • 200 OK – The withdrawal operation has been confirmed. The response is an empty JSON object.
  • 409 Conflict – The reserve operation has been aborted previously and can’t be confirmed.

1.8.2. Registration (Testing)

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

Status Codes
  • 200 OK – Registration was successful