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