taler-docs

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

post-registration.rst (3562B)

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