POST /kyc-import/$EXTERN_PUB

The /kyc-import/$EXTERN_PUB POST endpoint allows third parties to upload KYC/KYB data. The $EXTERN_PUB is the public EdDSA key identifying the 3rd party encoded using Crockford base32 encoding.

Clients should repeat this request (with some backoff) until it succeeds. The request is idempotent, so repeating it is always safe. The request may also be performed repeatedly for the same customer data (payto:// and/or account public key) with the same or different attributes, for example to provide additional attributes or to associate another account key pair with the same payto:// address. The primary identify for any customer is always the payto:// address.

Note

The exchange operator may internally notice that multiple payto:// addresses actually refer to the same entity, but that is of no concern for clients of this endpoint.

Provided attributes may include data of type FileUpload. In those cases, the data may either be provided inline, or reference a previous bulk import (by hash) performed via a POST to /kyc-bulk/. Bulk imports MUST always be performed before the import of attribute data referencing the bulk data.

This endpoint was introduced in protocol vIMPORT.

Request:

The request body must be a KycDataImportRequest object.

Response:

204 No Content:

The information was successfully uploaded.

400 Bad Request:

The request body is malformed or a parameter is invalid. This response comes with a standard ErrorDetail response with a code of TALER_EC_GENERIC_PARAMETER_MALFORMED. The client should not repeat the request until its has been restarted (presumably with a fixed implementation).

403 Forbidden:

The provided signature is invalid for the request. This response comes with a standard ErrorDetail response with a code of TALER_EC_KYC_IMPORT_SIGNATURE_INVALID. The client should not repeat the request until its has been restarted (presumably with a fixed implementation).

404 Not Found:

The $EXTERN_PUB is unknown to the exchange. This response comes with a standard ErrorDetail response. Possible error codes include TALER_EC_EXCHANGE_KYC_IMPORT_3RD_PARTY_UNKNOWN or TALER_EC_GENERIC_ENDPOINT_UNKNOWN. The client should not repeat the request until its has been restarted (presumably with a new configuration).

413 Request Entity Too Large:

The body is too large. This failure should be logged on both ends. The request should not be repeated.

500 Internal Server Error:

The server experienced an internal error. This response comes with a standard ErrorDetail response. Possible error codes include TALER_EC_GENERIC_DB_STORE_FAILED, TALER_EC_GENERIC_DB_INVARIANT_FAILURE, TALER_EC_GENERIC_DB_SETUP_FAILED, or TALER_EC_EXCHANGE_KYC_GENERIC_AML_LOGIC_BUG. The request should be repeated with some exponential back-off, giving the server operator to address its internal issues.

Details:

 interface KycDataImportRequest {

  // KYC attribute data. The fields present
  // will depend on the 3rd party and the entity the data is about.
  // Details will thus completely depend on the business context.
  // However, it MUST include a form ID.
  // Furthermore, the exchange may impose specific
  // restrictions on importing KYC data based on the 3rd party
  // and the respective business agreement.
  attributes: CustomerKycAttributes;

  // Time when the attributes were obtained by the 3rd party.
  import_date: Timestamp;

  // payto-URI of the bank account (or theoretically wallet)
  // for which the KYC/KYB data was obtained.
  customer_payto: string;

  // Public key of the merchant backend instance (or wallet)
  // that should be associated with the KYC/KYB data.
  account_pub: EddsaPublicKey;

  // EdDSA signature of the 3rd party. Must be of
  // purpose TALER_SIGNATURE_EXTERN_KYC_IMPORT_BINDING
  // and be made over the purpose header and the
  // SHA512 hash over the (normalized) JSON of attributes
  // as well as the timestamp, SHA512 hash of the payto URI
  // and the merchant public key.
  // See ExternKycDataImportBindingPS
  // for details.
  extern_sig: EddsaSignature;

}