Stellar PHP SDK API Documentation

KYCService
in package

Implements SEP-12 Customer Information and KYC API (v1.15.0)

This class provides methods for managing customer information and Know Your Customer (KYC) data through the SEP-12 protocol. It enables anchors to collect and verify customer information required for regulatory compliance, particularly for deposit, withdrawal, and cross-border payment operations.

The service supports operations to:

  • Retrieve required KYC fields for a customer
  • Submit customer information for verification
  • Check the status of customer verification
  • Upload supporting documents (ID scans, proof of address, etc.)
  • Update customer information
  • Register callback URLs for status notifications

Customer information can be linked to Stellar accounts, memo values (for shared accounts), or anchor-assigned customer IDs. The anchor validates submitted data and returns the verification status (accepted, pending, rejected, needs info).

SECURITY AND PRIVACY WARNINGS:

This service handles highly sensitive Personally Identifiable Information (PII) and KYC data. Implementers MUST ensure:

  • HTTPS ONLY: All communications with KYC endpoints MUST use HTTPS with valid TLS certificates. Never transmit KYC data over unencrypted HTTP connections.

  • DATA PROTECTION COMPLIANCE: Implementations must comply with applicable data protection regulations including GDPR (EU), CCPA (California), and other jurisdiction-specific laws. Ensure proper legal basis for data collection and processing.

  • SECURE STORAGE: Customer data must be stored securely with encryption at rest. Implement appropriate data retention policies and secure deletion procedures when data is no longer needed or upon customer request.

  • ACCESS CONTROLS: Implement strict role-based access controls. Limit access to KYC data to authorized personnel only. Maintain comprehensive audit logs of all data access.

  • CUSTOMER CONSENT: Obtain explicit customer consent before collecting, processing, or sharing KYC data. Provide clear privacy notices explaining data usage, retention, and customer rights (access, correction, deletion).

  • DATA MINIMIZATION: Only collect KYC data that is necessary for regulatory compliance and the specific use case. Avoid collecting excessive information.

Tags
see
https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0012.md

SEP-12 Specification v1.15.0

see
StellarToml

For discovering the KYC service endpoint

Table of Contents

Methods

__construct()  : mixed
deleteCustomer()  : ResponseInterface
Delete all personal information that the anchor has stored about a given customer.
fromDomain()  : KYCService
creates a KYCService by parsing server address from stellar.toml of given domain.
getCustomerFiles()  : GetCustomerFilesResponse
Requests info about the uploaded files via postCustomerFile See: https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0012.md#customer-file
getCustomerInfo()  : GetCustomerInfoResponse
Check the status of a customers info (customer GET) This endpoint allows clients to: 1. Fetch the fields the server requires in order to register a customer: If the server does not have a customer registered for the parameters sent in the request, it will return the fields required in the response. The same response will be returned when no parameters are sent.
postCustomerFile()  : CustomerFileResponse
Passing binary fields such as photo_id_front or organization.photo_proof_address in PUT /customer requests must be done using the multipart/form-data content type. This is acceptable in most cases, but multipart/form-data does not support nested data structures such as arrays or sub-objects.
putCustomerCallback()  : ResponseInterface
Allow the wallet to provide a callback URL to the anchor. The provided callback URL will replace (and supercede) any previously-set callback URL for this account.
putCustomerInfo()  : PutCustomerInfoResponse
Upload customer information to an anchor in an authenticated and idempotent fashion.
putCustomerVerification()  : GetCustomerInfoResponse
This endpoint allows servers to accept data values, usually confirmation codes, that verify a previously provided field via PUT /customer, such as mobile_number or email_address.
setMockHandlerStack()  : mixed

Methods

__construct()

public __construct(string $serviceAddress[, Client|null $httpClient = null ]) : mixed
Parameters
$serviceAddress : string

The base URL of the SEP-12 KYC service endpoint.

$httpClient : Client|null = null

Optional HTTP client to be used for requests. Provide a custom client when you need specific configurations such as custom timeouts, proxy settings, middleware, or mock handlers for testing.

deleteCustomer()

Delete all personal information that the anchor has stored about a given customer.

public deleteCustomer(string $account, string $jwt[, string|null $memo = null ][, string|null $memoType = null ]) : ResponseInterface

[account] is the Stellar account ID (G...) of the customer to delete. If account does not uniquely identify an individual customer (a shared account), the client should include the [memo] and [memoType] fields in the request. This request must be authenticated (via SEP-10) as coming from the owner of the account that will be deleted - [jwt].

Parameters
$account : string

is the Stellar account ID (G...) of the customer to delete.

$jwt : string

jwt token from authentication (SEP-10)

$memo : string|null = null

(optional) the client-generated memo that uniquely identifies the customer. If a memo is present in the decoded SEP-10 JWT's sub value, it must match this parameter value. If a muxed account is used as the JWT's sub value, memos sent in requests must match the 64-bit integer subaccount ID of the muxed account.

$memoType : string|null = null

(deprecated, optional) type of memo. One of text, id or hash. Deprecated because memos should always be of type id, although anchors should continue to support this parameter for outdated clients. If hash, memo should be base64-encoded. If a memo is present in the decoded SEP-10 JWT's sub value, this parameter can be ignored.

Tags
throws
GuzzleException

if a request error occurs

Return values
ResponseInterface —

response

fromDomain()

creates a KYCService by parsing server address from stellar.toml of given domain.

public static fromDomain(string $domain[, Client|null $httpClient = null ]) : KYCService
Parameters
$domain : string

to parse the toml data from.

$httpClient : Client|null = null

Optional http client to be used for requests.

Tags
throws
Exception

if no KYC service endpoint is found in the stellar.toml file

Return values
KYCService

getCustomerFiles()

Requests info about the uploaded files via postCustomerFile See: https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0012.md#customer-file

public getCustomerFiles(string $jwt[, string|null $fileId = null ][, string|null $customerId = null ]) : GetCustomerFilesResponse
Parameters
$jwt : string

jwt token obtained by sep-10

$fileId : string|null = null

(optional) The fileId returned from a previous postCustomerFile request. The response's files list will contain a single object if this parameter is used.

$customerId : string|null = null

(optional) The id returned from a previous putCustomerInfo request. The response should include all files uploaded for the specified customer.

Tags
throws
GuzzleException

in case of error.

Return values
GetCustomerFilesResponse —

response containing the file objects if any.

getCustomerInfo()

Check the status of a customers info (customer GET) This endpoint allows clients to: 1. Fetch the fields the server requires in order to register a customer: If the server does not have a customer registered for the parameters sent in the request, it will return the fields required in the response. The same response will be returned when no parameters are sent.

public getCustomerInfo(GetCustomerInfoRequest $request) : GetCustomerInfoResponse
  1. Check the status of a customer that may already be registered This allows clients to check whether the customers information was accepted, rejected, or still needs more info. If the server still needs more info, or the server needs updated information, it will return the fields required.
Parameters
$request : GetCustomerInfoRequest
Tags
throws
GuzzleException

if the HTTP request fails or the server returns an error

Return values
GetCustomerInfoResponse

postCustomerFile()

Passing binary fields such as photo_id_front or organization.photo_proof_address in PUT /customer requests must be done using the multipart/form-data content type. This is acceptable in most cases, but multipart/form-data does not support nested data structures such as arrays or sub-objects.

public postCustomerFile(string $fileBytes, string $jwt) : CustomerFileResponse

This endpoint is intended to decouple requests containing binary fields from requests containing nested data structures, supported by content types such as application/json. This endpoint is optional and only needs to be supported if the use case requires accepting nested data structures in PUT /customer requests. Once a file has been uploaded using this endpoint, it's file_id can be used in subsequent PUT /customer requests. The field name for the file_id should be the appropriate SEP-9 field followed by _file_id. For example, if file_abc is returned as a file_id from POST /customer/files, it can be used in a PUT /customer See: https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0012.md#customer-files

Parameters
$fileBytes : string

bytes of the file to be posted

$jwt : string

jwt token obtained by sep-10

Tags
throws
GuzzleException

in case of error.

Return values
CustomerFileResponse —

response

putCustomerCallback()

Allow the wallet to provide a callback URL to the anchor. The provided callback URL will replace (and supercede) any previously-set callback URL for this account.

public putCustomerCallback(PutCustomerCallbackRequest $request) : ResponseInterface

See: https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0012.md#customer-callback-put

Parameters
$request : PutCustomerCallbackRequest

request fields

Tags
throws
GuzzleException

if a request error occurs

Return values
ResponseInterface —

response

putCustomerVerification()

This endpoint allows servers to accept data values, usually confirmation codes, that verify a previously provided field via PUT /customer, such as mobile_number or email_address.

public putCustomerVerification(PutCustomerVerificationRequest $request) : GetCustomerInfoResponse

See: https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0012.md#customer-put-verification

Parameters
$request : PutCustomerVerificationRequest
Tags
throws
GuzzleException

if the HTTP request fails or the server returns an error

Return values
GetCustomerInfoResponse

setMockHandlerStack()

public setMockHandlerStack(HandlerStack $handlerStack) : mixed
Parameters
$handlerStack : HandlerStack 

        

        
    




    

    

                                

                

                                
    

        On this page

        
    


                

                            

            

    

        

            
Search results