Skip to content

Latest commit

 

History

History
107 lines (74 loc) · 4.46 KB

sep-0012.md

File metadata and controls

107 lines (74 loc) · 4.46 KB
Raw

Preamble

SEP: 0012
Title: Anchor/Client customer info transfer
Author: Interstellar
Status: Active
Created: 2018-09-11
Updated: 2018-09-11
Version 1.1.0

Deprecation warning

We're currently recommending that anchors and wallets use the SEP-6 interactive flow for transmitting KYC information, rather than SEP-12. Therefore, SEP-12 is deprecated for anyone using it as part of a SEP-6 implementation.

Abstract

This SEP defines a standard way for stellar wallets to upload KYC (or other) information to anchors who need it.

This SEP was made with these goals in mind:

  • interoperability
  • Allow a user to enter their KYC information once and use it across many anchors without re-entering information manually
  • handle the most common 80% of use cases
  • handle image and binary data
  • support the set of fields defined in SEP-9
  • support authentication via SEP-10
  • give users control over their data by supporting complete data erasure

To support this protocol an anchor acts as a server and implements the specified REST API endpoints, while a wallet implements a client that consumes the API. The goal is interoperability, so a wallet implements a single client according to the protocol, and will be able to interact with any compliant anchor. Similarly, an anchor that implements the API endpoints according to the protocol will work with any compliant wallet.

Prerequisites

  • An anchor must define the location of their KYC_SERVER or TRANSFER_SERVER in their stellar.toml. This is how a client app knows where to find the anchor's server. A client app will send KYC requests to the KYC_SERVER if it is specified, otherwise to the TRANSFER_SERVER.
  • Anchors and clients must support SEP-10 web authentication and use it for all SEP-12 endpoints.

API Endpoints

Authentication

Clients should submit the JWT previously obtained from the anchor via the SEP-10 authentication flow. The JWT should be included in all requests as request header:

Authorization: Bearer <JWT>

Alternatively, if the client cannot add the authorization header. The JWT should be passed as a jwt query parameter:

?jwt=<token>

Customer PUT

Upload customer information to an anchor in an authenticated and idempotent fashion.

PUT [KYC_SERVER || TRANSFER_SERVER]/customer
Content-Type: multipart/form-data

Request

The fields below should be placed in the request body using the multipart/form-data encoding.

Name Type Description
account G... string The Stellar account ID to upload KYC data for
memo string (optional) Uniquely identifies individual customer in schemes where multiple wallet users share one Stellar address. If included, the KYC data will only apply to deposit/withdraw requests that include this memo.
memo_type string (optional) type of memo. One of text, id or hash

The wallet should also transmit one or more of the fields listed in SEP-9, depending on what the anchor has indicated it needs.

When uploading data for fields specificed in SEP-9, binary type fields (typically files) should be submitted after all other fields. The reason for this is that some web servers require binary fields at the end so that they know when they can begin processing the request as a stream.

Response

If the anchor received and stored the data successfully, it should respond with a 202 Accepted HTTP status code and an empty body.

Every other HTTP status code will be considered an error. The body should contain error details. For example:

{
   "error": "'photo_id_front' cannot be decoded. Must be jpg or png."
}

Customer DELETE

Delete all personal information that the anchor has stored about a given customer. [account] is the Stellar account ID (G...) of the customer to delete. This request must be authenticated (via SEP-10) as coming from the owner of the account that will be deleted.

Request

DELETE [KYC_SERVER || TRANSFER_SERVER]/customer/[account]

DELETE Responses

Situation Response
Success 200 OK
User not authenticated properly 401 Unauthorized
Anchor has no information on the customer 404 Not Found