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

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

Response:

200 Ok:

Response is a RegistrationResponse.

400 Bad request:

Input data was 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.

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