taler-docs

Documentation for GNU Taler components, APIs and protocols
Log | Files | Refs | README | LICENSE

post-registration.rst (3984B)

      1 
      2 .. http:post:: /registration
      3 
      4   Registers a public key for wire transfer use.
      5 
      6   This endpoint generates the appropriate subjects to link a wire transfer
      7   to a registered public key.
      8 
      9   Two public keys must be provided:
     10   * ``account_pub``: forwarded to the exchange.
     11   * ``authorization_pub``: encoded inside the transfer subject.
     12 
     13   For non-recurrent transfers, you should use the same key for both ``account_pub``
     14   and ``authorization_pub``. For recurrent transfers, use a single
     15   ``authorization_pub`` across transfers, but a different ``account_pub`` for each.
     16 
     17   If registered as ``recurrent``, wire adapters will accept incoming transfers
     18   that reuse the same subject. If not marked as recurrent, transfers reusing
     19   a subject will bounce.
     20 
     21   Registering with an existing ``authorization_pub`` will replace the previously
     22   registered information for that key.
     23 
     24   **Request:**
     25 
     26   .. ts:def:: RegistrationRequest
     27 
     28     interface RegistrationRequest {
     29       // Payto URI of the credit account
     30       credit_account: Amount;
     31 
     32       // Transfer types
     33       type: "reserve" | "kyc";
     34 
     35       // Whether the authorization_pub will be reused for recurrent transfers
     36       // Disable bounces in case of authorization_pub reuse
     37       recurrent: boolean;
     38 
     39       // Amount to transfer
     40       credit_amount: Amount;
     41 
     42       // Public key algorithm
     43       alg: "EdDSA";
     44 
     45       // Account public key for the exchange
     46       account_pub: EddsaPublicKey;
     47 
     48       // Public key encoded inside the subject
     49       authorization_pub: EddsaPublicKey;
     50 
     51       // Signature of the account_pub key using the authorization_pub private key
     52       authorization_sig: EddsaSignature;
     53     }
     54 
     55   **Response:**
     56 
     57   :http:statuscode:`200 Ok`:
     58     Response is a `RegistrationResponse`.
     59   :http:statuscode:`400 Bad request`:
     60     Input data was invalid.
     61   :http:statuscode:`409 Conflict`:
     62     * ``TALER_EC_BANK_UNKNOWN_CREDITOR``: credit_account is unknown or not supported.
     63     * ``TALER_EC_BANK_DUPLICATE_RESERVE_PUB_SUBJECT``: the same reserve public key is already registered, you should retry using another key.
     64     * ``TALER_EC_BANK_DERIVATION_REUSE``: derived subject is already used, you should retry using another key.
     65     * ``TALER_EC_BANK_BAD_SIGNATURE``: signature is invalid.
     66 
     67   **Details:**
     68 
     69   .. ts:def:: TransferSubject
     70 
     71     // Union discriminated by the "type" field.
     72     type TransferSubject =
     73     | SimpleSubject
     74     | UriSubject
     75     | SwissQrBillSubject;
     76 
     77   .. ts:def:: SimpleSubject
     78 
     79     interface SimpleSubject {
     80       // Subject for systems accepting large subjects
     81       type: "SIMPLE";
     82 
     83       // Amount to transfer
     84       credit_amount: Amount;
     85 
     86       // Encoded string containing either the full key and transfer type or a
     87       // derived short subject
     88       subject: string;
     89     }
     90 
     91   .. ts:def:: UriSubject
     92 
     93     interface UriSubject {
     94       // Subject for systems accepting prepared payments
     95       type: "URI";
     96 
     97       // Amount to transfer.
     98       // FIXME-#11537: C client does not support this field yet.
     99       // Is it required? Merchant backend also does not use
    100       // it and soly relies on the ``uri``.
    101       credit_amount: Amount;
    102 
    103       // Prepared payments confirmation URI.
    104       // All necessary information for the user to complete
    105       // the transfer is encoded inside the URI.
    106       // Clients should not try to decode the URI but should
    107       // let the system handle it.
    108       uri: string;
    109     }
    110 
    111   .. ts:def:: SwissQrBillSubject
    112 
    113     interface SwissQrBillSubject {
    114       // Subject for Swiss QR Bill
    115       type: "CH_QR_BILL";
    116 
    117       // Amount to transfer
    118       credit_amount: Amount;
    119 
    120       // 27-digit QR Reference number to encode inside a QR-bill
    121       qr_reference_number: string;
    122     }
    123 
    124   .. ts:def:: RegistrationResponse
    125 
    126     interface RegistrationResponse {
    127       // The transfer subject encoded in all supported formats
    128       subjects: TransferSubject[];
    129 
    130       // Expiration date after which this subject is expected to be reused
    131       expiration: Timestamp;
    132     }