taler-docs

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

post-registration.rst (3398B)

      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       // Amount to transfer
     28       credit_amount: Amount;
     29 
     30       // Transfer types
     31       type: "reserve" | "kyc";
     32 
     33       // Public key algorithm
     34       alg: "EdDSA";
     35 
     36       // Account public key for the exchange
     37       account_pub: EddsaPublicKey;
     38 
     39       // Public key encoded inside the subject
     40       authorization_pub: EddsaPublicKey;
     41 
     42       // Signature of the account_pub key using the authorization_pub private key
     43       authorization_sig: EddsaSignature;
     44 
     45       // Whether the authorization_pub will be reused for recurrent transfers
     46       // Disable bounces in case of authorization_pub reuse
     47       recurrent: boolean;
     48     }
     49 
     50   **Response:**
     51 
     52   :http:statuscode:`200 Ok`:
     53     Response is a `RegistrationResponse`.
     54   :http:statuscode:`400 Bad request`:
     55     Input data was invalid.
     56   :http:statuscode:`409 Conflict`:
     57     * ``TALER_EC_BANK_DUPLICATE_RESERVE_PUB_SUBJECT``: the same reserve public key is already registered, you should retry using another key.
     58     * ``TALER_EC_BANK_DERIVATION_REUSE``: derived subject is already used, you should retry using another key.
     59     * ``TALER_EC_BANK_BAD_SIGNATURE``: signature is invalid.
     60 
     61   **Details:**
     62 
     63   .. ts:def:: TransferSubject
     64 
     65     // Union discriminated by the "type" field.
     66     type TransferSubject =
     67     | SimpleSubject
     68     | UriSubject
     69     | SwissQrBillSubject;
     70 
     71   .. ts:def:: SimpleSubject
     72 
     73     interface SimpleSubject {
     74       // Subject for system accepting large subjects
     75       type: "SIMPLE";
     76 
     77       // Amount to transfer
     78       credit_amount: Amount;
     79 
     80       // Encoded string containing either the full key and transfer type or a 
     81       // derived short subject
     82       subject: string;
     83     }
     84 
     85   .. ts:def:: UriSubject
     86 
     87     interface UriSubject {
     88       // Subject for system accepting prepared payments 
     89       type: "URI";
     90 
     91       // Amount to transfer
     92       credit_amount: Amount;
     93 
     94       // Prepared payments confirmation URI
     95       uri: string;
     96     }
     97 
     98   .. ts:def:: SwissQrBillSubject
     99 
    100     interface SwissQrBillSubject {
    101       // Subject for Swiss QR Bill
    102       type: "CH_QR_BILL";
    103 
    104       // Amount to transfer
    105       credit_amount: Amount;
    106 
    107       // 27-digit QR Reference number
    108       qr_reference_number: string;
    109     }
    110 
    111   .. ts:def:: RegistrationResponse
    112 
    113     interface RegistrationResponse {
    114       // The transfer subject encoded in all supported formats
    115       subjects: TransferSubject[];
    116 
    117       // Expiration date after which this subject is expected to be reused
    118       expiration: Timestamp;
    119     }