SEP-12¶
SEP-12 defines a standard for uploading KYC information to anchors servers.
Configuration¶
Simply add the SEP to your POLARIS_ACTIVE_SEPS
list in settings.py:
POLARIS_ACTIVE_SEPS = ["sep-1", "sep-12", ...]
Storing User Data¶
Polaris does not provide data models for storing user KYC data, and instead expects the anchor to manage this data independently.
That being said, its important to understand how users are identified and what information is necessary to keep in order to offer a functional SEP-12 implementation. Below is an example of how user (customer) data could be stored:
from django.db import models
from model_utils import Choices
class Customer(models.Model):
id = models.AutoField(primary_key=True)
email = models.TextField()
phone = models.Textfield()
# ... other SEP-9 fields ...
class CustomerStellarAccount(models.Model):
customer = models.ForeignKey(Customer, on_delete=models.CASCADE)
account = models.CharField(max_length=56)
memo = models.TextField(null=True, blank=True)
memo_type = models.CharField(choices=Choices("text", "id", "hash"), max_length=4, null=True, blank=True)
models.UniqueConstraint(fields=["account", "memo", "memo_type"], name="account_memo_constraint")
SEP-12 uses an id
attribute to uniquely identify users once clients register them using the account
and optional memo
and memo_type
parameters. memo
and memo_type
parameters are used when the customer being registered does not have sole ownership of account
, and is instead one of many users associated with account
.
Integrations¶
-
polaris.integrations.CustomerIntegration.
get
(self, params: Dict[KT, VT]) → Dict[KT, VT]¶ Return a dictionary matching the response schema outlined in SEP-12 GET /customer based on the params passed. The key-value pairs in params match the arguments sent in the request with the exception of
sep10_client_account
. This parameter was added in preparation for a future change. For now,sep10_client_account
will always matchaccount
.Raise a
ValueError
if the parameters are invalid, or raise an ObjectDoesNotExist exception if the customer specified via theid
parameter does not exist. An error response with the appropriate status will be sent using the message passed to the exception.Parameters: params – request parameters as described in SEP-12
-
polaris.integrations.CustomerIntegration.
put
(self, params: Dict[KT, VT]) → str¶ Update or create a record of the customer information passed. This information can then later be queried for when a client requests a deposit or withdraw on behalf of the customer.
If the information passed in params is invalid in some way, raise a
ValueError
for Polaris to return a 400 Bad Request response to the client. The message contained in the exception will be passed as the error message in the response. If the request specified a customer id in the request body but a record with that ID doesn’t exist, raise adjango.exceptions.ObjectDoesNotExist
exception. Polaris will return a 404 response.Return a customer ID that clients can use in future requests, such as a GET /customer request or a SEP-31 POST /transactions request. If the request included an id parameter, make sure the same id is returned.
If the required information is provided and the customer has
Transaction
objects in thepending_customer_info_update
status, all suchTransaction.status
values should be updated topending_receiver
. Polaris will then call theexecute_outgoing_transaction
integration function for each updated transaction.If the anchor requires verification of values passed in params, such as
mobile_number
oremail_address
, the anchor should initate the verification process in this function and ensure the next call toGET /customer
contains the field requiring verification with aVERIFICATION_REQUIRED
status. Unless the anchor expects users to verify the field value in some other manner, such as opening a confirmation link sent via email, client applications will eventually make a call toPUT /customer/verification
to return the verification codes sent as a result of the initial call toPUT /customer
.Parameters: params – request parameters as described in SEP-12 Raises: ValueError or ObjectDoesNotExist
-
polaris.integrations.CustomerIntegration.
delete
(self, account: str, memo: Optional[str], memo_type: Optional[str])¶ Delete the record of the customer specified by account, memo, and memo_type. If such a record does not exist, raise a
ObjectDoesNotExist
exception for Polaris to return a 404 Not Found response.Parameters: - account – the stellar account associated with the customer
- memo – the optional memo used to create the customer
- memo_type – the optional type of the memo used to create to the customer
-
polaris.integrations.CustomerIntegration.
callback
(self, params: Dict[KT, VT])¶ Save the URL provided in association with the user identified by the parameters sent in the request. The anchor is responsible for making POST requests containing the response body of a GET request to the saved URL whenever the SEP-12 status of the customer changes. Polaris does not manage an anchor’s customer data and therefore cannot make these requests.
Client applications may register callback URLs if the application does not have the ability to poll the
GET /customer
endopoint at any time, which requires SEP-10 authentication (and consequently the relevant account’s signature).If the customer specified does not exist, raise an
ObjectDoesNotExist
. If the URL is provided is invalid in some way, raise aValueError
.If this function is not implemented, Polaris will respond with a 501 Not Implemented.
Parameters: params – request parameters as described in SEP-12 Raises: ValueError or django.core.exceptions.ObjectDoesNotExist
-
polaris.integrations.CustomerIntegration.
more_info_url
(self, account: str) → str¶ Return a URL the client can open in a browser to view the status of their account with the anchor. This URL will be returned in a SEP-6 Customer Information Status response. This is optional.
Parameters: account – the stellar account for the url to be returned
-
polaris.integrations.CustomerIntegration.
put_verification
(self, account: str, params: Dict[KT, VT]) → Dict[KT, VT]¶ Validate the values, typically verification codes, passed in params for the customer identified by
params["id"]
. See the endpoint specification for more information on the request format.Anchors may return fields from
GET /customer
requests with theVERIFICATION_REQUIRED
status if the anchor requires the user to verify a SEP-9 field value provided in a previous call toPUT /customer
. The most common field needing verification is mobile_number. This function will be called when the client passes the verification value back to the anchor.If the validation values are correct, return a dictionary that is identical to what would be returned for a call to
GET /customer
.If any of the validation values are incorrect, raise a
ValueError
and Polaris will raise a 400 Bad Request.If the customer specified by
params["id"]
does not exist, or the authenticatedaccount
does not match Stellar account associated with the ID, raise anObjectDoesNotExist
exception. Polaris will return a 404 Not Found response.If this function is not implemented, Polaris will respond with a 501 Not Implemented.
Parameters: - account – the Stellar account authenticated via SEP-10
- params – the request body of the
PUT /customer/verification
call
Raises: ValueError, ObjectDoesNotExist, NotImplementedError