stellar-sdk/com.soneso.stellar.sdk.sep.sep12/KYCService

KYCService

class KYCService(serviceAddress: String, httpClient: HttpClient? = null, httpRequestHeaders: Map<String, String>? = null)

SEP-12 KYC (Know Your Customer) API client.

Implements the client side of SEP-12 for collecting customer information for regulatory compliance. This service allows wallets and applications to:

Register customers with required KYC information
Check KYC status and requirements
Upload verification documents
Update customer information
Verify customer data (phone, email, etc.)
Manage customer callbacks for status updates
Delete customer data (GDPR compliance)

The KYC process typically follows this workflow:

Client authenticates with SEP-10 WebAuth to get a JWT token
Client calls GET /customer to check what information is required
Server responds with required fields based on customer status
Client submits information via PUT /customer
Client may need to verify fields (email, phone) via verification codes
Process repeats until status is ACCEPTED or REJECTED

Customer statuses:

ACCEPTED: Customer has been approved
PROCESSING: Customer information is being reviewed
NEEDS_INFO: More information is required
REJECTED: Customer was rejected

Example - Complete KYC flow:

// 1. Initialize KYC service from domain
val kycService = KYCService.fromDomain("testanchor.stellar.org")

// 2. Get JWT token via WebAuth (SEP-10)
val webAuth = WebAuth.fromDomain("testanchor.stellar.org", Network.TESTNET)
val userKeyPair = KeyPair.fromSecretSeed("S...")
val authToken = webAuth.jwtToken(
    clientAccountId = userKeyPair.getAccountId(),
    signers = listOf(userKeyPair)
)

// 3. Check what information is required
val infoRequest = GetCustomerInfoRequest(jwt = authToken.token)
val infoResponse = kycService.getCustomerInfo(infoRequest)

when (infoResponse.status) {
    CustomerStatus.NEEDS_INFO -> {
        println("Required fields: ${infoResponse.fields?.keys}")

        // 4. Submit customer information
        val putRequest = PutCustomerInfoRequest(
            jwt = authToken.token,
            kycFields = StandardKYCFields(
                naturalPersonKYCFields = NaturalPersonKYCFields(
                    firstName = "John",
                    lastName = "Doe",
                    emailAddress = "john@example.com",
                    birthDate = LocalDate(1990, 1, 15)
                )
            )
        )
        val putResponse = kycService.putCustomerInfo(putRequest)
        println("Customer ID: ${putResponse.id}")
    }
    CustomerStatus.ACCEPTED -> println("Customer already verified")
    CustomerStatus.PROCESSING -> println("Verification in progress")
    CustomerStatus.REJECTED -> println("Customer rejected: ${infoResponse.message}")
}

Example - With document upload:

val putRequest = PutCustomerInfoRequest(
    jwt = authToken.token,
    kycFields = StandardKYCFields(
        naturalPersonKYCFields = NaturalPersonKYCFields(
            firstName = "John",
            lastName = "Doe",
            photoIdFront = loadImageBytes("passport_front.jpg"),
            photoIdBack = loadImageBytes("passport_back.jpg")
        )
    )
)
val response = kycService.putCustomerInfo(putRequest)

Example - Email verification:

// After submitting email, verify with code sent by anchor
val verifyRequest = PutCustomerInfoRequest(
    jwt = authToken.token,
    id = customerId,
    verificationFields = mapOf(
        "email_address_verification" to "123456",
        "mobile_number_verification" to "654321"
    )
)
val response = kycService.putCustomerInfo(verifyRequest)

Example - Set up status callbacks:

val callbackRequest = PutCustomerCallbackRequest(
    jwt = authToken.token,
    url = "https://myapp.com/kyc-webhook",
    account = userKeyPair.getAccountId()
)
kycService.putCustomerCallback(callbackRequest)