16.11.4. Taler Wire Transfer Gateway HTTP API

This section describes the API offered by Taler wire adapters. The API is used by clients such as wallets to prepare wire transfers. This allows the use of wire-specific subject format or optimized alternating wire transfer flows, and enables the use of recurring wire transfers.

GET /config

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

Response:

200 OK:

The adapter responds with a WireTransferConfig object. This request should virtually always be successful.

Details:

type SubjectFormat =
  | "SIMPLE"
  | "URI"
  | "CH_QR_BILL";

interface WireTransferConfig {
  // Name of the API.
  name: "taler-wire-transfer-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;

  // Supported formats for registration, there must at least one.
  supported_formats: SubjectFormat[];
}

16.11.4.1. Prepared wire transfers

POST /registration

Register a public key for wire transfer use.

This endpoint generate appropriate subjects to link a transfer to the registered public key.

Two public keys must be provided, the account_pub key is the key that will forwarded to the exchange and the authorization_pub key will be encoded inside the subject.

For simple one time wire transfers, use the same key for both account_pub and authorization_pub. For recurrent transfers, use a single authorization_pub for different account_pub.

If registered as recurrent the wire adapters will keep incoming transfers reusing the same subject until a registration is performed, else it will bounce.

Registration with the same authorization_pu will replace the existing information registered for the key.

Request:

interface RegistrationRequest {
  // Amount to transfer
  credit_amount: Amount;

  // Transfer types
  type: "reserve" | "kyc";

  // Public key algorithm
  alg: "EdDSA";

  // Account public key for the exchange
  account_pub: EddsaPublicKey;

  // Public key encoded inside the subject
  authorization_pub: EddsaPublicKey;

  // Signature of the account_pub key using the authorization_pub private key
  authorization_sig: EddsaSignature;

  // Whether the authorization_pub will be reused for recurrent transfers
  // Disable bounces in case of authorization_pub reuse
  recurrent: boolean;
}

Response:

200 Ok:

Response is a RegistrationResponse.

400 Bad request:

Input data was invalid.

409 Conflict:

• TALER_EC_BANK_DUPLICATE_RESERVE_PUB_SUBJECT: the same reserve public key is already registered, you should retry using another key.

• TALER_EC_BANK_DERIVATION_REUSE: derived subject is already used, you should retry using another key.

• TALER_EC_BANK_BAD_SIGNATURE: signature is invalid.

Details:

// Union discriminated by the "type" field.
type TransferSubject =
| SimpleSubject
| UriSubject
| SwissQrBillSubject;

interface SimpleSubject {
  // Subject for system accepting large subjects
  type: "SIMPLE";

  // Amount to transfer
  credit_amount: Amount;

  // Encoded string containing either the full key and transfer type or a
  // derived short subject
  subject: string;
}

interface UriSubject {
  // Subject for system accepting prepared payments
  type: "URI";

  // Amount to transfer
  credit_amount: Amount;

  // Prepared payments confirmation URI
  uri: string;
}

interface SwissQrBillSubject {
  // Subject for Swiss QR Bill
  type: "CH_QR_BILL";

  // Amount to transfer
  credit_amount: Amount;

  // 27-digit QR Reference number
  qr_reference_number: string;
}

interface RegistrationResponse {
  // The transfer subject encoded in all supported formats
  subjects: TransferSubject[];

  // Expiration date after which this subject is expected to be reused
  expiration: Timestamp;
}

DELETE /registration

Remove an existing registered public key for wire transfer use.

Use this endpoint to free a derived subject or cancel a recurrent paiment.

Request:

interface Unregistration {
  // Current timestamp in the ISO 8601
  timestamp: string;

  // Public key used for registration
  authorization_pub: EddsaPublicKey;

  // Signature of the timestamp using the authorization_pub private key
  // Prevent replay attack
  authorization_sig: EddsaSignature;
}

Response:

204 No content:

The registration have been deleted.

400 Bad request:

Input data was invalid.

404 Not found:

Unknown registration.

409 Conflict:

• TALER_EC_BANK_OLD_TIMESTAMP: the timestamp is too old.

• TALER_EC_BANK_BAD_SIGNATURE: signature is invalid.