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 match account.

Raise a ValueError if the parameters are invalid, or raise an ObjectDoesNotExist exception if the customer specified via the id 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 a django.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 the pending_customer_info_update status, all such Transaction.status values should be updated to pending_receiver. Polaris will then call the execute_outgoing_transaction integration function for each updated transaction.

If the anchor requires verification of values passed in params, such as mobile_number or email_address, the anchor should initate the verification process in this function and ensure the next call to GET /customer contains the field requiring verification with a VERIFICATION_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 to PUT /customer/verification to return the verification codes sent as a result of the initial call to PUT /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 a ValueError.

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 the VERIFICATION_REQUIRED status if the anchor requires the user to verify a SEP-9 field value provided in a previous call to PUT /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 authenticated account does not match Stellar account associated with the ID, raise an ObjectDoesNotExist 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