1.11.6. Taler Conversion Info API

This chapter describes the conversion info API. The conversion info API is used by wallets for withdrawals that involve a currency conversion.

GET /config

Get configuration information about the bank.

Response:

200 OK:

Response is a ConversionConfig.

501 Not implemented:

This server does not support conversion, client should check config response.

Details:

interface ConversionConfig {
  // 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;

  // Name of the API.
  name: "taler-conversion-info";

  // URN of the implementation (needed to interpret 'revision' in version).
  // @since v4, may become mandatory in the future.
  implementation?: string;

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

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

  // External currency used during conversion.
  fiat_currency: string;

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

  // Additional information on conversion rates.
  // Those informations should never be used to perform conversions,
  // use /cashin-rate or /cashout-rate instead.
  // Conversion rates can change at any time. Clients must deal with
  // any resulting errors and call /cashin-rate or /cashout-rate again
  // to use the new rates.
  conversion_rate: ConversionRate;
}
GET /cashin-rate

This public endpoint allows clients to calculate the exchange rate between the regional currency and the fiat currency of the banking system.

This endpoint shows how the bank would apply the cash-in ratio and fee to one input amount. Typically, wallets would request this endpoint before creating withdrawals that involve a currency conversion.

Request:

Query Parameters:

  • amount_debit – this is the amount that the user will get deducted from their fiat bank account.

or

Query Parameters:

  • amount_credit – this is the amount that the user will receive in their regional bank account.

Response:

200 OK:

Response is a CashinConversionResponse.

400 Bad request:

  • TALER_EC_GENERIC_PARAMETER_MISSING : none of the parameters have been provided.

  • TALER_EC_GENERIC_PARAMETER_MALFORMED : both of the parameters have been provided or one of them is not a valid Taler amount.

  • TALER_EC_GENERIC_CURRENCY_MISMATCH : the parameter is in the wrong currency.

409 Conflict:

The amount is too small to be converted because it produces an amount less than zero.

501 Not implemented:

This server does not support conversion, client should check config response.

Details:

interface CashinConversionResponse {
  // Amount that the user will get deducted from their fiat
  // bank account, according to the 'amount_credit' value.
  amount_debit: Amount;
  // Amount that the user will receive in their regional
  // bank account, according to 'amount_debit'.
  amount_credit: Amount;
}
GET /cashout-rate

This public endpoint allows clients to calculate the exchange rate between the regional currency and the fiat currency of the banking system.

This endpoint shows how the bank would apply the cash-out ratio and fee to one input amount. Typically, frontends ask this endpoint before creating cash-in operations.

Request:

Query Parameters:

  • amount_debit – this is the amount that the user will get deducted from their regional bank account.

or

Query Parameters:

  • amount_credit – this is the amount that the user will receive in their fiat bank account.

Response:

200 OK:

Response is a CashoutConversionResponse.

400 Bad request:

  • TALER_EC_GENERIC_PARAMETER_MISSING : none of the parameters have been provided.

  • TALER_EC_GENERIC_PARAMETER_MALFORMED : both of the parameters have been provided or one of them is not a valid Taler amount.

  • TALER_EC_GENERIC_CURRENCY_MISMATCH : the parameter is in the wrong currency.

409 Conflict:

The amount is too small to be converted because it produces an amount less than zero.

501 Not implemented:

This server does not support conversion, client should check config response.

Details:

interface CashoutConversionResponse {
  // Amount that the user will get deducted from their regional
  // bank account, according to the 'amount_credit' value.
  amount_debit: Amount;
  // Amount that the user will receive in their fiat
  // bank account, according to 'amount_debit'.
  amount_credit: Amount;
}
POST /conversion-rate

This endpoint allows the administrator to update the exchange rate between the regional currency and the fiat currency of the banking system.

The conversion is calculated as follows: (amount * ratio - fee) / tiny_amount

Request:

interface ConversionRate {
  // Minimum fiat amount authorised for cashin before conversion
  cashin_min_amount: Amount;

  // Exchange rate to buy regional currency from fiat
  cashin_ratio: DecimalNumber;

  // Regional amount fee to subtract after applying the cashin ratio.
  cashin_fee: Amount;

  // Smallest possible regional amount, converted amount is rounded to this amount
  cashin_tiny_amount: Amount;

  // Rounding mode used during cashin conversion
  cashin_rounding_mode: "zero" | "up" | "nearest";

  // Minimum regional amount authorised for cashout before conversion
  cashout_min_amount: Amount;

  // Exchange rate to sell regional currency for fiat
  cashout_ratio: DecimalNumber;

  // Fiat amount fee to subtract after applying the cashout ratio.
  cashout_fee: Amount;

  // Smallest possible fiat amount, converted amount is rounded to this amount
  cashout_tiny_amount: Amount;

  // Rounding mode used during cashout conversion
  cashout_rounding_mode: "zero" | "up" | "nearest";
}

Response:

204 No content:

Operation successful.

401 Unauthorized:

Invalid credentials or missing rights.

501 Not implemented:

This server does not support conversion, client should check config response.

previous

1.11.5. Taler Bank Integration API

next

1.11.7. Terminal API