18.11.5. Taler Prepared Transfer 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 adapter. This specification corresponds to current protocol being version 1.

Response:

200 OK:

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

Details:

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

interface PreparedTransferConfig {
  // Name of the API.
  name: "taler-prepared-transfer";

  // libtool-style representation of the 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 API.
  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[];
}

18.11.5.1. Prepared wire transfers

POST /registration

Registers a public key for wire transfer use.

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

Two public keys must be provided: * account_pub: forwarded to the exchange. * authorization_pub: encoded inside the transfer subject.

For non-recurrent transfers, you should use the same key for both account_pub and authorization_pub. For recurrent transfers, use a single authorization_pub across transfers, but a different account_pub for each.

If registered as recurrent, wire adapters will accept incoming transfers that reuse the same subject. If not marked as recurrent, transfers reusing a subject will bounce.

Registering with an existing authorization_pub will replace the previously registered information for that key.

Request:

interface RegistrationRequest {
  // Payto URI of the credit account
  credit_account: Amount;

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

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

  // Amount to transfer
  credit_amount: Amount;

  // Public key algorithm
  alg: "EdDSA";

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

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

  // This is a signature over
  // a struct TALER_PreparedTransferRegisterPS with purpose
  // TALER_SIGNATURE_WALLET_PREPARED_TRANSFER_REGISTER.
  authorization_sig: EddsaSignature;
}

Response:

200 Ok:

Response is a RegistrationResponse.

400 Bad request:

Input data was invalid.

403 Forbidden:

• TALER_EC_BANK_BAD_SIGNATURE: signature is invalid.

409 Conflict:

• TALER_EC_BANK_UNKNOWN_CREDITOR: credit_account is unknown or not supported.

• 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.

Details:

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

interface SimpleSubject {
  // Subject for systems 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 systems accepting prepared payments
  type: "URI";

  // Amount to transfer.
  // FIXME-#11537: C client does not support this field yet.
  // Is it required? Merchant backend also does not use
  // it and soly relies on the uri.
  credit_amount: Amount;

  // Prepared payments confirmation URI.
  // All necessary information for the user to complete
  // the transfer is encoded inside the URI.
  // Clients should not try to decode the URI but should
  // let the system handle it.
  uri: string;
}

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

  // Amount to transfer
  credit_amount: Amount;

  // 27-digit QR Reference number to encode inside a QR-bill
  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;
}

POST /unregistration

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 {
  timestamp: Timestamp;

  // Public key used for registration
  authorization_pub: EddsaPublicKey;

  // This is a signature over
  // a struct TALER_PreparedTransferUnregisterPS with purpose
  // TALER_SIGNATURE_WALLET_PREPARED_TRANSFER_UNREGISTER.
  authorization_sig: EddsaSignature;
}

Response:

204 No content:

The registration have been deleted.

400 Bad request:

Input data was invalid.

403 Forbidden:

• TALER_EC_BANK_BAD_SIGNATURE: signature is invalid.

404 Not found:

Unknown registration.

409 Conflict:

• TALER_EC_BANK_OLD_TIMESTAMP: the timestamp is too old.