GNU Taler

2FA is required for this operation. This returns the Challenge response.

Invalid or missing credentials.

TALER_EC_GENERIC_FORBIDDEN: missing rights.
TALER_EC_BANK_ACCOUNT_LOCKED: account is locked and cannot create new token using its password.

Details:

interface TokenSuccessResponse {
  // Expiration determined by the server.
  // Can be based on the token_duration
  // from the request, but ultimately the
  // server decides the expiration.
  expiration: Timestamp;

  // Opque access token.
  access_token: string;
}

DELETE /accounts/$USERNAME/token¶

Invalidate the access token that is being used to make the request.

Authentication: The client must authenticate with a valid access token.

Response:

204 No content:: The token have been deleted.
401 Unauthorized:: Invalid or missing credentials.
403 Forbidden:: Missing rights.

GET /accounts/$USERNAME/tokens¶

Retrieve a subset of tokens related to $USERNAME. @since v4

Request:

Query Parameters:

delta – Optional. Takes value of the form N (-N), so that at most N values strictly older (younger) than start are returned. Defaults to -20 to return the last 20 entries.
start – Optional. Row number threshold, see delta for its interpretation. Defaults to smallest or biggest row id possible according to delta sign.

Response:

200 OK:: Response is a TokenInfos.
204 No content:: No tokens.
401 Unauthorized:: Invalid or missing credentials.
403 Forbidden:: Mmissing rights.

Details:

interface TokenInfos {
  tokens: TokenInfo[];
}

interface TokenInfo {
  // Time when the token was created.
  creation_time: Timestamp;

  // Expiration determined by the server.
  // Can be based on the token_duration
  // from the request, but ultimately the
  // server decides the expiration.
  expiration: Timestamp;

  // Scope for the token.
  scope: "readonly" | "readwrite" | "revenue" | "wiregateway";

  // Is the token refreshable into a new token during its
  // validity?
  // Refreshable tokens effectively provide indefinite
  // access if they are refreshed in time.
  refreshable: boolean;

  // Optional token description
  description?: string;

  // Time when the token was last used.
  last_access: Timestamp;

  // Opaque unique ID used for pagination.
  row_id: Integer;
}

1.11.2.3. Bank Web UI ¶

The web UI for the bank is typically served under /.

1.11.2.4. Config ¶

GET /config¶

Return the protocol version and configuration information about the bank. This specification corresponds to current protocol being version v7.

Response:

200 OK:: Response is a Config.

Details:

interface Config {
  // Name of the API.
  name: "taler-corebank";

  // 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;

  // Bank display name to be used in user interfaces.
  // For consistency use "Taler Bank" if missing.
  // @since **v4**, will become mandatory in the next version.
  bank_name?: string;

  // Advertised base URL to use when you sharing an URL with another
  // program.
  // @since **v4**.
  base_url?: string;

  // If 'true' the server provides local currency conversion support
  // If 'false' some parts of the API are not supported and return 501
  allow_conversion: boolean;

  // If 'true' anyone can register
  // If 'false' only admin can
  allow_registrations: boolean;

  // If 'true' account can delete themselves
  // If 'false' only admin can delete accounts
  allow_deletions: boolean;

  // If 'true' anyone can edit their name
  // If 'false' only admin can
  allow_edit_name: boolean;

  // If 'true' anyone can edit their cashout account
  // If 'false' only admin can
  allow_edit_cashout_payto_uri: boolean;

  // Default debt limit for newly created accounts
  default_debit_threshold: Amount;

  // Currency used by this bank.
  currency: string;

  // How the bank SPA should render this currency.
  currency_specification: CurrencySpecification;

  // TAN channels supported by the server
  supported_tan_channels: TanChannel[];

  // Wire transfer type supported by the bank.
  // Defaults to 'iban' is missing
  // @since **v4**, will become mandatory in the next version.
  wire_type?: string;

  // Wire transfer execution fees. Only applies to bank transactions and withdrawals.
  // @since **v4**, will become mandatory in the next version.
  wire_transfer_fees?: Amount;

  // Minimum wire transfer amount allowed. Only applies to bank transactions and withdrawals.
  // @since **v4**, will become mandatory in the next version.
  min_wire_transfer_amount?: Amount;

  // Maximum wire transfer amount allowed. Only applies to bank transactions and withdrawals.
  // @since **v4**, will become mandatory in the next version.
  max_wire_transfer_amount?: Amount;
}

1.11.2.5. Account Management ¶

POST /accounts¶

Create a new bank account. Depending on the configuration, the account creation is self-serve, or only restricted to the administrators.

Request:

interface RegisterAccountRequest {
  // Username of the account
  username: string;

  // Password of the account used for authentication
  password: string;

  // Legal name of the account owner
  name: string;

  // Make this account visible to anyone?
  // Defaults to false.
  is_public?: boolean;

  // Make this account a taler exchange account?
  // If true:
  // - incoming transactions to the account that do not
  //   have a valid reserve public key are automatically
  // - the account provides the taler-wire-gateway-api endpoints
  // Defaults to false.
  is_taler_exchange?: boolean;

  // Addresses where to send the TAN for protected operations.
  contact_data?: ChallengeContactData;

  // Full 'payto' URI of a fiat bank account with a 'receiver-name' parameter.
  // If 'receiver-name' is missing, name will be used instead.
  // Payments will be sent to this bank account
  // when the user wants to convert the regional currency
  // back to fiat currency outside bank.
  cashout_payto_uri?: string;

  // Internal payto URI of this bank account.
  // Used mostly for testing, this field is ignored if the bank payment
  // method is not IBAN.
  payto_uri?: string;

  // If present, set the max debit allowed for this user
  // Only admin can set this property.
  debit_threshold?: Amount;

  // If present, set a custom minimum cashout amount for this account.
  // Only admin can set this property
  // @since **v4**
  min_cashout?: Amount;

  // If present, enables 2FA and set the TAN channel used for challenges
  // Only admin can set this property, other user can reconfig their account
  // after creation.
  tan_channel?: TanChannel;
}

interface ChallengeContactData {
  // E-Mail address
  email?: EmailAddress;

  // Phone number.
  phone?: PhoneNumber;
}

Response:

200 OK:

Response is a RegisterAccountResponse.

400 Bad request:

Input data was invalid. For example, the client specified a invalid phone number or e-mail address.

Invalid or missing credentials.

Missing rights.

TALER_EC_BANK_REGISTER_USERNAME_REUSE : username already used.
TALER_EC_BANK_REGISTER_PAYTO_URI_REUSE : payto URI already used.
TALER_EC_BANK_UNALLOWED_DEBIT : admin account does not have sufficient funds to grant bonus.
TALER_EC_BANK_RESERVED_USERNAME_CONFLICT : a reserved username was attempted, like admin or bank
TALER_EC_BANK_NON_ADMIN_PATCH_DEBT_LIMIT : a non-admin user has tried to create an account with a customer debt limit.
TALER_EC_BANK_NON_ADMIN_SET_MIN_CASHOUT : a non-admin user has tried to create an account with a custom min cashout amount.
TALER_EC_BANK_NON_ADMIN_SET_TAN_CHANNEL : a non-admin user has tried to create an account with 2fa.
TALER_EC_BANK_TAN_CHANNEL_NOT_SUPPORTED: tan_channel is not supported, check bank config to find supported ones.
TALER_EC_BANK_MISSING_TAN_INFO: the user did not share any contact data where to send the TAN via tan_channel.
TALER_EC_BANK_PASSWORD_TOO_SHORT: password is shorter than 8 characters.
TALER_EC_BANK_PASSWORD_TOO_LONG: password is longer than 64 characters.

Details:

interface RegisterAccountResponse {
  // Internal payto URI of this bank account.
  internal_payto_uri: string;
}

PATCH /accounts/$USERNAME¶

Allows reconfiguring the account data of $USERNAME.

Request:

interface AccountReconfiguration {
  // Addresses where to send the TAN for protected operations.
  contact_data?: ChallengeContactData;

  // Full 'payto' URI of a fiat bank account with a 'receiver-name' parameter.
  // If 'receiver-name' is missing, name will be used instead.
  // Payments will be sent to this bank account
  // when the user wants to convert the regional currency
  // back to fiat currency outside bank.
  // Only admin can change this property if not allowed in config
  cashout_payto_uri?: string;

  // If present, change the legal name associated with $username.
  // Only admin can change this property if not allowed in config
  name?: string;

  // Make this account visible to anyone?
  is_public?: boolean;

  // If present, change the max debit allowed for this user
  // Only admin can change this property.
  debit_threshold?: Amount;

  // If present, change the custom minimum cashout amount for this account.
  // Only admin can set this property
  // @since **v4**
  min_cashout?: Amount;

  // If present, enables 2FA and set the TAN channel used for challenges
  tan_channel?: TanChannel;
}

Response:

2FA is required for this operation. This returns the Challenge response.

Operation successful.

Invalid or missing credentials.

Missing rights.

The account pointed by $USERNAME was not found.

TALER_EC_BANK_NON_ADMIN_PATCH_LEGAL_NAME : a non-admin user has tried to change their legal name.
TALER_EC_BANK_NON_ADMIN_PATCH_CASHOUT : a non-admin user has tried to change their cashout account.
TALER_EC_BANK_NON_ADMIN_PATCH_DEBT_LIMIT : a non-admin user has tried to change their debt limit.
TALER_EC_BANK_NON_ADMIN_SET_MIN_CASHOUT : a non-admin user has tried to change their custom min cashout amount.
TALER_EC_BANK_TAN_CHANNEL_NOT_SUPPORTED : tan_channel is not supported, check bank config to find supported ones.
TALER_EC_BANK_MISSING_TAN_INFO : the user did not share any contact data where to send the TAN via tan_channel.

PATCH /accounts/$USERNAME/auth¶

Allows changing the account’s password.

Request:

interface AccountPasswordChange {
  // Old password. If present it need to match the current
  // password before updating.
  old_password?: string;
  // New password.
  new_password: string;
}

Response:

2FA is required for this operation. This returns the Challenge response.

Operation successful.

The account pointed by $USERNAME was not found.

Invalid or missing credentials.

Missing rights.

TALER_EC_BANK_NON_ADMIN_PATCH_MISSING_OLD_PASSWORD: a non-admin user has tried to change their password whihout providing the current one.
TALER_EC_BANK_PATCH_BAD_OLD_PASSWORD : provided old password does not match current password.
TALER_EC_BANK_PASSWORD_TOO_SHORT: new password is shorter than 8 characters.
TALER_EC_BANK_PASSWORD_TOO_LONG: new password is longer than 64 characters.

DELETE /accounts/$USERNAME¶

Delete the account whose username is $USERNAME. The deletion succeeds only if the balance is zero. Typically only available to the administrator, but can be configured to allow ordinary users too.

Response:

2FA is required for this operation. This returns the Challenge response.

The account was successfully deleted.

Invalid or missing credentials.

Missing rights.

The account pointed by $USERNAME was not found.

TALER_EC_BANK_RESERVED_USERNAME_CONFLICT : a reserved username was attempted, like admin or bank.
TALER_EC_BANK_ACCOUNT_BALANCE_NOT_ZERO: the account balance was not zero.

GET /public-accounts¶

Show those accounts whose histories are publicly visible. For example, accounts from donation receivers. As such, this request is unauthenticated.

Request:

Query Parameters:

limit – Optional. At most return the given number of results. Negative for descending by row_id, positive for ascending by row_id. Defaults to -20. Since protocol v5.
offset – Optional. Starting row_id for pagination. Since protocol v5.
filter_name – Optional. Pattern to filter on the account’s legal name. Given the filter ‘foo’, all the results will contain ‘foo’ in their legal name. Without this option, all the existing accounts are returned.
delta – Optional. Deprecated in protocol v5. Use limit instead.
start – Optional. Deprecated in protocol v5. Use offset instead.

Response:

200 OK:: Response is a PublicAccountsResponse.
204 No content:: No public account.

Details:

interface PublicAccountsResponse {
  public_accounts: PublicAccount[];
}

interface PublicAccount {
  // Username of the account
  username: string;

  // Internal payto URI of this bank account.
  payto_uri: string;

  // Current balance of the account
  balance: Balance;

  // Is this a taler exchange account?
  is_taler_exchange: boolean;

  // Opaque unique ID used for pagination.
  // @since **v4**, will become mandatory in the next version.
  row_id?: Integer;
}

GET /accounts¶

Obtains a list of the accounts registered at the bank. It returns only the information that this API handles, without any balance or transactions list. This request is only available to the administrator.

Request:

Query Parameters:

limit – Optional. At most return the given number of results. Negative for descending by row_id, positive for ascending by row_id. Defaults to -20. Since protocol v5.
offset – Optional. Starting row_id for pagination. Since protocol v5.
filter_name – Optional. Pattern to filter on the account’s legal name. Given the filter ‘foo’, all the results will contain ‘foo’ in their legal name. Without this option, all the existing accounts are returned.
delta – Optional. Deprecated in protocol v5. Use limit instead.
start – Optional. Deprecated in protocol v5. Use offset instead.

Response:

200 OK:: At least one account was found. The server responds with a ListBankAccountsResponse object.
204 No Content:: No accounts were found for the given request.
401 Unauthorized:: Invalid or missing credentials.
403 Forbidden:: Missing rights.

Details:

interface ListBankAccountsResponse {
  accounts: AccountMinimalData[];
}

interface Balance {
  amount: Amount;
  credit_debit_indicator: "credit" | "debit";
}

interface AccountMinimalData {
  // Username of the account
  username: string;

  // Legal name of the account owner.
  name: string;

  // Internal payto URI of this bank account.
  payto_uri: string;

  // Current balance of the account
  balance: Balance;

  // Number indicating the max debit allowed for the requesting user.
  debit_threshold: Amount;

  // Custom minimum cashout amount for this account.
  // If null or absent, the global conversion fee is used.
  // @since **v6**
  min_cashout?: Amount;

  // Is this account visible to anyone?
  is_public: boolean;

  // Is this a taler exchange account?
  is_taler_exchange: boolean;

  // Is the account locked.
  // Defaults to false.
  // @since **v7**
  is_locked?: boolean;

  // Opaque unique ID used for pagination.
  // @since **v4**, will become mandatory in the next version.
  row_id?: Integer;

  // Current status of the account
  // active: the account can be used
  // deleted: the account has been deleted but is retained for compliance
  // reasons, only the administrator can access it
  // Defaults to 'active' is missing
  // @since **v4**, will become mandatory in the next version.
  status?: "active" | "deleted";
}

GET /accounts/$USERNAME¶

Obtains information relative to the account owned by $USERNAME. The request is available to the administrator and $USERNAME itself.

Response:

200 OK:: The bank responds with an AccountData object.
401 Unauthorized:: Invalid or missing credentials.
403 Forbidden:: Missing rights.
404 Not found:: The account pointed by $USERNAME was not found.

Details:

interface AccountData {
  // Legal name of the account owner.
  name: string;

  // Available balance on the account.
  balance: Balance;

  // payto://-URI of the account.
  payto_uri: string;

  // Number indicating the max debit allowed for the requesting user.
  debit_threshold: Amount;

  // Custom minimum cashout amount for this account.
  // If null or absent, the global conversion fee is used.
  // @since **v6**
  min_cashout?: Amount;

  // Addresses where to send the TAN for transactions.
  // Currently only used for cashouts.
  // If missing, cashouts will fail.
  // In the future, might be used for other transactions
  // as well.
  contact_data?: ChallengeContactData;

  // Full 'payto' URI (with a 'receiver-name' parameter) of a fiat bank
  // account where to send cashouts. This field is optional
  // because not all the accounts are required to participate
  // in the merchants' circuit.  One example is the exchange:
  // that never cashouts.  Registering these accounts can
  // be done via the access API.
  cashout_payto_uri?: string;

  // Is this account visible to anyone?
  is_public: boolean;

  // Is this a taler exchange account?
  is_taler_exchange: boolean;

  // Is the account locked.
  // Defaults to false.
  // @since **v7**
  is_locked?: boolean;

  // Is 2FA enabled and what channel is used for challenges?
  tan_channel?: TanChannel;

  // Current status of the account
  // active: the account can be used
  // deleted: the account has been deleted but is retained for compliance
  // reasons, only the administrator can access it
  // Defaults to 'active' is missing
  // @since **v4**, will become mandatory in the next version.
  status?: "active" | "deleted";
}

1.11.2.6. Transactions ¶

GET /accounts/$USERNAME/transactions¶

Retrieve a subset of transactions related to $USERNAME.

Request:

Query Parameters:

limit – Optional. At most return the given number of results. Negative for descending by row_id, positive for ascending by row_id. Defaults to -20. Since protocol v5.
offset – Optional. Starting row_id for pagination. Since protocol v5.
timeout_ms – Optional. Timeout in milliseconds, for long-polling, to wait for at least one element to be shown. Only useful if limit is positive. Since protocol v5.
delta – Optional. Deprecated in protocol v5. Use limit instead.
start – Optional. Deprecated in protocol v5. Use offset instead.
long_poll_ms – Optional. Deprecated in protocol v5. Use timeout_ms instead.

Response:

200 OK:: The bank responds with an BankAccountTransactionsResponse object.
204 No content:: No transaction found.
401 Unauthorized:: Invalid or missing credentials.
403 Forbidden:: Missing rights.
404 Not found:: The account pointed by $USERNAME was not found.

Details:

interface BankAccountTransactionsResponse {
  transactions: BankAccountTransactionInfo[];
}

GET /accounts/$USERNAME/transactions/$TRANSACTION_ID¶

Retrieve the transaction whose identifier is TRANSACTION_ID.

Response:

200 OK:: The bank responds with an BankAccountTransactionInfo object.
401 Unauthorized:: Invalid or missing credentials.
403 Forbidden:: Missing rights.
404 Not found:: The account pointed by $USERNAME was not found.

Details:

interface BankAccountTransactionInfo {
  // ???
  creditor_payto_uri: string;
  // ???
  debtor_payto_uri: string;

  // ???
  amount: Amount;

  // ???
  direction: "debit" | "credit";

  // ???
  subject: string;

  // Transaction unique ID.  Matches
  // $TRANSACTION_ID from the URI.
  row_id: Integer;

  // ???
  date: Timestamp;
}

POST /accounts/$USERNAME/transactions¶

Create a new transaction where the bank account with the label USERNAME is debited.

Request:

interface CreateTransactionRequest {
  // Address in the payto format of the wire transfer receiver.
  // It needs at least the 'message' query string parameter.
  payto_uri: string;

  // Transaction amount (in the $currency:x.y format), optional.
  // However, when not given, its value must occupy the 'amount'
  // query string parameter of the 'payto' field.  In case it
  // is given in both places, the payto_uri's takes the precedence.
  amount: string;

  // Nonce to make the request idempotent.  Requests with the same
  // request_uid that differ in any of the other fields
  // are rejected.
  // @since **v4**, will become mandatory in the next version.
  request_uid?: ShortHashCode;
}

Response:

200 Ok:

The bank responds with an CreateTransactionResponse object.

2FA is required for this operation. This returns the Challenge response.

400 Bad Request:

The request was invalid or the payto://-URI used unacceptable features.

Invalid or missing credentials.

Missing rights.

The account pointed by $USERNAME was not found.

TALER_EC_BANK_SAME_ACCOUNT : creditor account is the same than USERNAME.
TALER_EC_BANK_UNKNOWN_CREDITOR : creditor account was not found.
TALER_EC_BANK_UNALLOWED_DEBIT : the account does not have sufficient funds or the amount is too low or too high.
TALER_EC_BANK_TRANSFER_REQUEST_UID_REUSED: an operation with the same request_uid but different details has been submitted before.

Details:

interface CreateTransactionResponse {
  // ID identifying the transaction being created
  row_id: Integer;
}

1.11.2.7. Account withdrawals ¶

POST /accounts/$USERNAME/withdrawals¶

Create a withdrawal operation, resulting in a taler://withdraw URI.

Request:

The request must be a BankAccountCreateWithdrawalRequest.

Response:

200 Ok:: The bank responds with an BankAccountCreateWithdrawalResponse object.
401 Unauthorized:: Invalid or missing credentials.
403 Forbidden:: Missing rights.
404 Not found:: The account pointed by $USERNAME was not found.
409 Conflict:: The account does not have sufficient funds.

Details:

interface BankAccountCreateWithdrawalRequest {
  // Amount to withdraw.  If given, the wallet
  // cannot change the amount.
  // Optional since **v6**.
  amount?: Amount;

  // Suggested amount to withdraw. The wallet can
  // still change the suggestion.
  // @since **v6**
  suggested_amount?: Amount;
}

interface BankAccountCreateWithdrawalResponse {
  // ID identifying the operation being created
  withdrawal_id: string;

  // URI that can be passed to the wallet to initiate the withdrawal
  taler_withdraw_uri: string;
}

POST /accounts/$USERNAME/withdrawals/$WITHDRAWAL_ID/confirm¶

Confirms WITHDRAWAL_ID operation. Has no effect on an already confirmed withdrawal operation. This call is responsible for wiring the funds to the exchange.

Request:

interface BankAccountConfirmWithdrawalRequest {

  // Selected amount to be transferred. Optional if the
  // backend already knows the amount.
  // @since **v6**
  amount?: Amount;
}

Response:

2FA is required for this operation. This returns the Challenge response.

The withdrawal operation has been confirmed.

Invalid or missing credentials.

Missing rights.

The operation was not found.

TALER_EC_BANK_CONFIRM_ABORT_CONFLICT : the withdrawal has been aborted previously and can’t be confirmed.
TALER_EC_BANK_CONFIRM_INCOMPLETE : the withdraw operation cannot be confirmed because no exchange and reserve public key selection happened before.
TALER_EC_BANK_UNALLOWED_DEBIT : the account does not have sufficient funds or the amount is too low or too high.
TALER_EC_BANK_AMOUNT_DIFFERS : the specified amount will not work for this withdrawal (since v6).
TALER_EC_BANK_AMOUNT_REQUIRED : the backend requires an amount to be specified (since v6).

POST /accounts/$USERNAME/withdrawals/$WITHDRAWAL_ID/abort¶

Aborts WITHDRAWAL_ID operation. Has no effect on an already aborted operation.

Response:

204 No content:: The withdrawal operation has been aborted.
401 Unauthorized:: Invalid or missing credentials.
403 Forbidden:: Missing rights.
404 Not found:: The withdrawal operation was not found.
409 Conflict:: The withdrawal operation has been confirmed previously and can’t be aborted.

GET /withdrawals/$WITHDRAWAL_ID¶

Retrieve public information about WITHDRAWAL_ID withdrawal operation. Does not require further authentication as knowledge of WITHDRAWAL_ID serves as an authenticator.

Request:

Query Parameters:

old_state – Optional. Defaults to “pending”.
timeout_ms – Optional. Timeout in milliseconds, for long-polling, to wait for the operation state to be different from old_state. Since protocol v5.
long_poll_ms – Optional. Deprecated in protocol v5. Use timeout_ms instead.

Response:

200 Ok:: The bank responds with an WithdrawalPublicInfo object.
404 Not found:: The operation was not found.

Details:

interface WithdrawalPublicInfo {
  // Current status of the operation
  // pending: the operation is pending parameters selection (exchange and reserve public key)
  // selected: the operations has been selected and is pending confirmation
  // aborted: the operation has been aborted
  // confirmed: the transfer has been confirmed and registered by the bank
  status: "pending" | "selected" | "aborted" | "confirmed";

  // Amount that will be withdrawn with this operation
  // (raw amount without fee considerations).  Only
  // given once the amount is fixed and cannot be changed.
  // Optional since **v6**.
  amount?: Amount;

  // Suggestion for the amount to be withdrawn with this
  // operation.  Given if a suggestion was made but the
  // user may still change the amount.
  // Optional since **v6**.
  suggested_amount?: Amount;

  // Account username
  username: string;

  // Reserve public key selected by the exchange,
  // only non-null if status is selected or confirmed.
  selected_reserve_pub?: string;

  // Exchange account selected by the wallet
  // only non-null if status is selected or confirmed.
  selected_exchange_account?: string;
}

1.11.2.8. Cashouts ¶

POST /accounts/$USERNAME/cashouts¶

Initiates a conversion to fiat currency. The fiat bank account to be credited is the one specified at registration time via the cashout_payto_uri parameter. The regional bank account is specified via $USERNAME.

Note

Consult the cashout rates call to learn about any applicable fee or exchange rate.

Request:

interface CashoutRequest {
  // Nonce to make the request idempotent.  Requests with the same
  // request_uid that differ in any of the other fields
  // are rejected.
  request_uid: ShortHashCode;

  // Optional subject to associate to the
  // cashout operation.  This data will appear
  // as the incoming wire transfer subject in
  // the user's fiat bank account.
  subject?: string;

  // That is the plain amount that the user specified
  // to cashout.  Its $currency is the (regional) currency of the
  // bank instance.
  amount_debit: Amount;

  // That is the amount that will effectively be
  // transferred by the bank to the user's fiat bank
  // account.
  // It is expressed in the fiat currency and
  // is calculated after the cashout fee and the
  // exchange rate.  See the /cashout-rate call.
  // The client needs to calculate this amount
  // correctly based on the amount_debit and the cashout rate,
  // otherwise the request will fail.
  amount_credit: Amount;
}

Response:

200 OK:

The cashout request was correctly created. This returns the CashoutResponse response.

2FA is required for this operation. This returns the Challenge response.

Invalid or missing credentials.

Missing rights.

The account pointed by $USERNAME was not found.

TALER_EC_BANK_TRANSFER_REQUEST_UID_REUSED: an operation with the same request_uid but different details has been submitted before.
TALER_EC_BANK_BAD_CONVERSION: exchange rate was calculated incorrectly by the client.
TALER_EC_BANK_BANK_CONVERSION_AMOUNT_TO_SMALL: the amount of the cashout is too small.
TALER_EC_BANK_UNALLOWED_DEBIT: the account does not have sufficient funds or the amount is too low or too high.
TALER_EC_BANK_CONFIRM_INCOMPLETE: the user did not share any cashout payto to uri where to wire funds.

501 Not Implemented:

TALER_EC_BANK_TAN_CHANNEL_NOT_SUPPORTED: the chosen tan_channel is not currently supported.
This server does not support conversion, client should check config response.

Details:

interface CashoutResponse {
  // ID identifying the operation being created
  cashout_id: Integer;
}

GET /accounts/$USERNAME/cashouts/$CASHOUT_ID¶

Returns information about the status of the $CASHOUT_ID operation. The request is available to the administrator and the account owner.

Response:

200 OK:: Response is a CashoutStatusResponse.
401 Unauthorized:: Invalid or missing credentials.
403 Forbidden:: Missing rights.
404 Not found:: The cashout operation was not found.
501 Not implemented:: This server does not support conversion, client should check config response.

Details:

interface CashoutStatusResponse {
  // Amount debited to the regional bank account.
  amount_debit: Amount;

  // Amount credited to the fiat bank account.
  amount_credit: Amount;

  // Transaction subject.
  subject: string;

  // Time when the cashout was created.
  creation_time: Timestamp;
}

GET /accounts/$USERNAME/cashouts¶

Returns the list of all cash-out operations for an account.

Request:

Query Parameters:

limit – Optional. At most return the given number of results. Negative for descending by cashout_id, positive for ascending by cashout_id. Defaults to -20. Since protocol v5.
offset – Optional. Starting cashout_id for pagination. Since protocol v5.
delta – Optional. Deprecated in protocol v5. Use limit instead.
start – Optional. Deprecated in protocol v5. Use offset instead.

Response:

200 OK:: Response is a Cashouts.
204 No Content:: No cash-out operations were found.
401 Unauthorized:: Invalid or missing credentials.
403 Forbidden:: Missing rights.
501 Not implemented:: This server does not support conversion, client should check config response.

Details:

interface Cashouts {
  // Every string represents a cash-out operation ID.
  cashouts: CashoutInfo[];
}

interface CashoutInfo {
  cashout_id: Integer;
}

GET /cashouts¶

Returns the list of all cash-out operations for all accounts.

Can only be used by the administrators.

Request:

Query Parameters:

limit – Optional. At most return the given number of results. Negative for descending by cashout_id, positive for ascending by cashout_id. Defaults to -20. Since protocol v5.
offset – Optional. Starting cashout_id for pagination. Since protocol v5.
delta – Optional. Deprecated in protocol v5. Use limit instead.
start – Optional. Deprecated in protocol v5. Use offset instead.

Note

We might want to add a filter in the future to only query pending cashout operations.

Response:

200 OK:: Response is a GlobalCashouts.
204 No Content:: No cash-out operations were found.
401 Unauthorized:: Invalid or missing credentials.
403 Forbidden:: Missing rights.
501 Not implemented:: This server does not support conversion, client should check config response.

Details:

interface GlobalCashouts {
  cashouts: GlobalCashoutInfo[];
}

interface GlobalCashoutInfo {
  cashout_id: Integer;
  username: string;
}

1.11.2.9. 2FA ¶

POST /accounts/$USERNAME/challenge/$CHALLENGE_ID¶

Send TAN code for the CHALLENGE_ID challenge.

This request can be posted several times to trigger TAN retransmission when the current code has expired or too many confirmation attempts have been made.

This endpoints is not authenticated for token creation challenges.

Response:

200 OK:

The TAN code have been sent. This returns TanTransmission response.

Invalid or missing credentials.

429 Too many requests:

Missing rights.

404 Not Found:

The challenge was not found.

Too many challenges are active right now, you must wait or confirm current challenges.

502 Bad Gateway:

TALER_EC_BANK_TAN_CHANNEL_SCRIPT_FAILED: TAN transmition via tan_channel failed.

Details:

interface TanTransmission {
  // Channel of the last successful transmission of the TAN challenge.
  tan_channel: TanChannel;

  // Info of the last successful transmission of the TAN challenge.
  tan_info: string;
}

interface Challenge {
  // Unique identifier of the challenge to solve to run this protected
  // operation.
  challenge_id: string;
}

enum TanChannel {
  SMS = "sms",
  EMAIL = "email"
}

POST /accounts/$USERNAME/challenge/$CHALLENGE_ID/confirm¶

Solves the CHALLENGE_ID challenge and allows performing the protected operation.

When the challenge is confirmed, you can call the protected endpoint again with CHALLENGE_ID in the X-Challenge-Id HTTP header and an empty request body.

This endpoints is not authenticated for token creation challenges. Too many unsuccessful attempts to confirm token creation challenges block the account.

Request:

interface ChallengeSolve {
  // The TAN code that solves $CHALLENGE_ID
  tan: string;
}

Response:

204 No Content:

The challenge is confirmed.

Invalid or missing credentials.

Missing rights.

404 Not Found:

The challenge was not found.