Customer

A customer and their KYC standing

Returned by the Customer API endpoints. The kyc object tells you whether the customer can transact, what’s outstanding, and how to submit it.

Properties

Property	Type	Required	Description
id	string (uuid)	Yes	The customer’s unique MoonPay identifier
externalCustomerId	string	Yes	Your identifier for this customer, if one was supplied. null when the customer connected without an external identifier
kyc	object	Yes	KYC details for the customer

KYC

Property	Type	Required	Description
status	string	Yes	The customer’s KYC standing with you. See KYC status
requirements	object	Yes	Outstanding and completed KYC requirements, keyed by category. See Requirements
challenge	object	No	Hosted challenge you must surface to the customer to complete verification. See Challenge

KYC status

Value	Description
not_created	No KYC session exists yet for this customer with your account.
collecting	The customer has outstanding requirements to submit.
verifying	MoonPay is processing the submitted data. No action is needed from you or the customer.
active	KYC is complete. The customer is in good standing.
unavailable	KYC cannot proceed for this customer (for example, an unsupported region, or a closed account).

Requirements

Each key is a requirement category. Only categories that apply to the customer are present. Each entry has the same shape:

Property	Type	Required	Description
status	string	Yes	incomplete or complete
requiredFields	array	No	When status is incomplete, the outstanding fields the customer must provide. Omitted when the category does not surface field-level detail

Category	Description
basicDetails	The customer’s basic personal details (first name, last name, date of birth, nationality)
residentialAddress	The customer’s residential address
identityDocuments	Identity document submission (passport, driver’s license, residence permit)
selfie	Selfie photo submission
taxIdentifiers	Tax identifier submission (SSN, CPF, TIN)
proofOfAddress	Proof-of-address document submission
phoneNumber	The customer’s phone number in E.164 format
questionnaires	Due-diligence questionnaires the customer must complete

For the fields and documents each country requires, see KYC data requirements.

Challenge

Property	Type	Required	Description
url	string	Yes	Fully-formed challenge URL. Render it directly; the URL embeds the challenge token
expiresAt	string (date-time)	Yes	When the challenge URL expires. Surface the challenge to the customer before this time

Example

{
  "id": "c1a2b3c4-0000-4000-8000-000000000000",
  "externalCustomerId": "your_user_id",
  "kyc": {
    "status": "collecting",
    "requirements": {
      "basicDetails": { "status": "complete" },
      "residentialAddress": {
        "status": "incomplete",
        "requiredFields": ["street", "locality", "postalCode"]
      },
      "identityDocuments": { "status": "incomplete" }
    }
  }
}