taler-docs

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

post-registration.rst (4102B)

      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       // This is a signature over
     52       // a struct `TALER_PreparedTransferRegisterPS` with purpose
     53       // ``TALER_SIGNATURE_WALLET_PREPARED_TRANSFER_REGISTER``.
     54       authorization_sig: EddsaSignature;
     55     }
     56 
     57   **Response:**
     58 
     59   :http:statuscode:`200 Ok`:
     60     Response is a `RegistrationResponse`.
     61   :http:statuscode:`400 Bad request`:
     62     Input data was invalid.
     63   :http:statuscode:`403 Forbidden`:
     64     * ``TALER_EC_BANK_BAD_SIGNATURE``: signature is invalid.
     65   :http:statuscode:`409 Conflict`:
     66     * ``TALER_EC_BANK_UNKNOWN_CREDITOR``: credit_account is unknown or not supported.
     67     * ``TALER_EC_BANK_DUPLICATE_RESERVE_PUB_SUBJECT``: the same reserve public key is already registered, you should retry using another key.
     68     * ``TALER_EC_BANK_DERIVATION_REUSE``: derived subject is already used, you should retry using another key.
     69 
     70   **Details:**
     71 
     72   .. ts:def:: TransferSubject
     73 
     74     // Union discriminated by the "type" field.
     75     type TransferSubject =
     76     | SimpleSubject
     77     | UriSubject
     78     | SwissQrBillSubject;
     79 
     80   .. ts:def:: SimpleSubject
     81 
     82     interface SimpleSubject {
     83       // Subject for systems accepting large subjects
     84       type: "SIMPLE";
     85 
     86       // Amount to transfer
     87       credit_amount: Amount;
     88 
     89       // Encoded string containing either the full key and transfer type or a
     90       // derived short subject
     91       subject: string;
     92     }
     93 
     94   .. ts:def:: UriSubject
     95 
     96     interface UriSubject {
     97       // Subject for systems accepting prepared payments
     98       type: "URI";
     99 
    100       // Amount to transfer.
    101       // FIXME-#11537: C client does not support this field yet.
    102       // Is it required? Merchant backend also does not use
    103       // it and soly relies on the ``uri``.
    104       credit_amount: Amount;
    105 
    106       // Prepared payments confirmation URI.
    107       // All necessary information for the user to complete
    108       // the transfer is encoded inside the URI.
    109       // Clients should not try to decode the URI but should
    110       // let the system handle it.
    111       uri: string;
    112     }
    113 
    114   .. ts:def:: SwissQrBillSubject
    115 
    116     interface SwissQrBillSubject {
    117       // Subject for Swiss QR Bill
    118       type: "CH_QR_BILL";
    119 
    120       // Amount to transfer
    121       credit_amount: Amount;
    122 
    123       // 27-digit QR Reference number to encode inside a QR-bill
    124       qr_reference_number: string;
    125     }
    126 
    127   .. ts:def:: RegistrationResponse
    128 
    129     interface RegistrationResponse {
    130       // The transfer subject encoded in all supported formats
    131       subjects: TransferSubject[];
    132 
    133       // Expiration date after which this subject is expected to be reused
    134       expiration: Timestamp;
    135     }