SEP-12 Explained: How KYC Works on Stellar Anchors

What SEP-12 is

SEP-12 (Stellar Ecosystem Proposal 12) defines HTTP endpoints for uploading, checking and deleting customer KYC information. It is used by the payment SEPs, SEP-6, SEP-24 and SEP-31, but can also run as a stand-alone service. The current version is 1.15.0 (stellar-protocol).

Anchors are the bridge between bank money and Stellar: they issue or redeem assets such as USDC or local-currency tokens and are licensed where they operate. Because they handle fiat, they must know their customers. SEP-12 lets every Stellar wallet speak to every anchor the same way, instead of each pair building a custom integration. Background: Stellar anchors explained.

The endpoints

Endpoint	What it does
GET /customer	Returns the customer's status and, if anything is missing, which fields are required
PUT /customer	Uploads or updates customer fields and files; safe to repeat
PUT /customer/callback	Registers a URL where the anchor pushes status changes
DELETE /customer/[account]	Deletes the customer's stored data

An anchor publishes the location of these endpoints as KYC_SERVER (or falls back to TRANSFER_SERVER) in its stellar.toml file. Every call is authenticated with a token from SEP-10, which proves control of a Stellar account, or SEP-45, its counterpart for contract accounts such as passkey smart wallets.

The flow, step by step

1. Discover. The wallet reads the anchor's stellar.toml to find its KYC and transfer servers.
2. Authenticate. The wallet signs a SEP-10 (or SEP-45) challenge and receives a JWT.
3. Ask what is needed. The payment SEP's /info endpoint lists customer types, for example a sender or receiver in SEP-31. GET /customer with that type returns the required fields.
4. Upload. PUT /customer sends names, addresses, dates of birth and ID images, using the standard field names defined in SEP-9.
5. Verify. The anchor's back end passes the data to its KYC vendor, which checks the document, the selfie and sanctions lists.
6. Wait for status. The customer moves through NEEDS_INFO, PROCESSING and then ACCEPTED or REJECTED. The wallet polls GET /customer or listens on its callback URL.
7. Transact. Once accepted, the deposit, withdrawal or payment goes ahead.

Customers can be identified by a plain account (G…), a muxed account (M…) or an account plus memo, which lets custodial wallets and exchanges register many users behind one Stellar address.

An example exchange

A wallet sending a cross-border payment asks the receiving anchor what it needs for a sender:

GET /customer?account=G...&type=sep31-sender
Authorization: Bearer <SEP-10 JWT>

The anchor answers with the customer's status and any missing fields:

{
  "status": "NEEDS_INFO",
  "fields": {
    "first_name": { "type": "string", "description": "First name" },
    "last_name":  { "type": "string", "description": "Last name" },
    "photo_id_front": { "type": "binary", "description": "Front of ID document" }
  }
}

The wallet then sends those fields with PUT /customer and receives an id for the customer, which it attaches to the payment. When the anchor's checks finish, GET /customer returns ACCEPTED and the payment can proceed. Field names come from SEP-9, so a wallet that has collected a user's details once can reuse them with any anchor that asks for the same fields, though each anchor still runs its own verification.

Where SEP-12 sits among the payment SEPs

• SEP-6 — programmatic deposits and withdrawals. KYC goes through SEP-12, so a wallet can build a native in-app flow.
• SEP-24 — interactive deposits and withdrawals. The anchor hosts a web page inside the wallet and usually collects KYC there itself, though SEP-12 can pre-fill it.
• SEP-31 — cross-border payments between two institutions. The sending institution uses SEP-12 to register the sender and the receiver with the receiving anchor before paying.

This is the plumbing behind cash ramps like MoneyGram on Stellar and much of the stablecoin cross-border payment activity on the network.

Where a KYC vendor plugs in

SEP-12 standardises the conversation between wallet and anchor, not the checks themselves. The anchor decides which verification vendor to use and connects it behind its endpoints.

In the SDF's open-source Anchor Platform, the platform serves the SEP-12 endpoints and forwards customer data to the anchor's own business server through a callback API (GET customer and its PUT counterpart). That business server is where the vendor integration lives. With a vendor such as iDenfy, a typical setup is:

1. The business server receives the SEP-12 fields and creates a verification session with the vendor.
2. For a SEP-24 or app flow, the user completes document capture, selfie and liveness in the vendor's interface; iDenfy can also require an NFC chip scan of the passport or ID card.
3. The vendor returns a decision by webhook, alongside AML and sanctions screening results.
4. The business server maps the decision to a SEP-12 status: approved to ACCEPTED, a missing document to NEEDS_INFO, a failure to REJECTED.

This is a generic pattern, not a description of a specific anchor's integration. iDenfy's per-approved-verification billing suits anchors because many ramp sign-ups never complete; see our KYC provider comparison for the alternatives.

Businesses and KYB

SEP-12's customer types are not limited to individuals. SEP-31 receivers and senders are often businesses, and SEP-9 includes organisation fields such as registered name, registration number and address. Verifying those, and the people who own and control the company, is KYB. An anchor that serves payment companies needs a vendor that handles both; iDenfy and several others do.

Privacy and data handling

• Off-chain only. SEP-12 runs over HTTPS. No personal data is written to the Stellar ledger.
• Deletion. DELETE /customer lets a customer's data be removed, subject to the anchor's legal retention duties.
• Re-use. Data uploaded to one anchor is not shared with another. Each anchor verifies separately, which is why EU digital identity wallets and reusable credentials are a topic for anchors from 2027; see RegTech trends in 2026.

Why it matters for DeFi on Stellar

Protocols like Blend, Aquarius or WhaleHub do not ask for identity: anyone with a wallet can use them. But almost every dollar in Stellar DeFi arrived through an anchor that ran KYC. SEP-12 is what makes those on-ramps interoperable across wallets, which is a large part of why stablecoins move so easily on Stellar. See stablecoins on Stellar and the best Stellar wallets.