Customer

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" }
    }
  }
}

Documentation

Sessions

Customers

Payment Methods

Quotes

Transactions

Objects & Types

Properties

KYC

KYC status

Requirements

Challenge

Example

​Properties

​KYC

​KYC status

​Requirements

​Challenge

​Example

Properties

KYC

KYC status

Requirements

Challenge

Example