Skip to main content
The Customer API puts KYC data capture in your hands. You are responsible for capturing the required customer data and submitting it through the API, whether you build the capture flow yourself or delegate it to a KYC provider. Use this page as your pre-integration reference. For when each requirement category becomes required in a customer’s journey, see Verification tiers. Each section covers one of the requirement categories that appear in kyc.requirements on GET /platform/v1/customers/{id}: basicDetails, residentialAddress, and phoneNumber (the profile fields), plus taxIdentifiers, questionnaires, identityDocuments, selfie, proofOfAddress, and proofOfIncome. You fulfill field-based categories with PATCH /platform/v1/customers/{id}/kyc and document-based categories with the file-upload endpoints. Country is the key driver: once you submit residentialAddress.country, the API returns the full requirement set for that jurisdiction.
The fields and documents MoonPay requires depend on the customer's country of residence, and the set evolves as compliance decisions change. The live response is definitive: kyc.requirements on the customer object lists exactly what is outstanding for a given customer. This page helps you plan the integration; it is not a contract. Build capture screens that render whatever the API returns instead of hardcoding fields per country.

​
Profile fields

Every customer requires the following profile fields, submitted with PATCH /platform/v1/customers/{id}/kyc. The API path is the field’s location in the PATCH body. Date of birth must be in YYYY-MM-DD format. The customer must be 18 or older. Country codes must be ISO 3166-1 alpha-3 (e.g. USA, GBR, DEU).
Phone number must be in E.164 format (e.g. +12025550143). Verify the customer’s phone number via OTP before submitting it. Re-verify at least once every 30 days. Submitting the number is your attestation that this verification occurred — see Terms acceptance.

​
Tax identifiers

Tax identifier requirements depend on the customer’s country of residence. Submit tax identifiers as taxIdentifiers[] on PATCH /platform/v1/customers/{id}/kyc, each with a type, value, and (for tin) a country field.
Submit ssn values as nine digits with no hyphens or spaces. Any other length, or a value containing -, fails with a 400 and an invalid_request error on taxIdentifiers.value. In test mode, any 9-digit value works — see Test data.

​
EEA and UK

​
Rest of world

​
Due diligence questionnaires

When questionnaires is incomplete in kyc.requirements, the customer must complete one or both due-diligence questionnaires. The entry’s requiredFields names which ones: customerDueDiligence, enhancedDueDiligence, or both. Submit answers as questionnaires[] on PATCH /platform/v1/customers/{id}/kyc, one entry per required questionnaire. Each entry carries a type identifying the questionnaire and an answers object; each questionnaire type may appear at most once per request.

​
Customer Due Diligence

Answers for the customerDueDiligence questionnaire.

​
Enhanced Due Diligence

Answers for the enhancedDueDiligence questionnaire. profession accepts: agriculture, artsAndEntertainment, businessOwner, education, financialServices, healthcare, industrialTradesAndTransport, informationAndTechnology, legalAndProfessionalServices, publicSector, realEstate, retail, and seniorManagement.

​
Monetary amounts

grossAnnualIncome, expectedTransactionAmountPerMonth, and netWorth share one shape: an object with a currency code and an amount. The reporting currency is fixed by the customer’s residentialAddress.country: The expected value is fixed by the residential address country, but currency is still required: it acts as an explicit confirmation so amounts are never silently misinterpreted. The API rejects any other currency with a 400 validation error that identifies the expected currency, for example Expected currency EUR for residentialAddress.country CZE, got PLN. If the customer’s local currency differs from the reporting currency, for example CZK or PLN in an EEA country, convert the amount to the reporting currency before submitting, using a current exchange rate.

​
Identity documents

When identityDocuments is incomplete in kyc.requirements, the customer must provide one of the document types listed below. Submit documents through the presigned upload flow, not inline in the PATCH body. Before you submit selfie or identity-document images, display the required biometric consent disclosure to the customer — see Biometric consent for selfie and document images.
Accepted document types vary by country.
The fields and documents MoonPay requires depend on the customer's country of residence, and the set evolves as compliance decisions change. The live response is definitive: kyc.requirements on the customer object lists exactly what is outstanding for a given customer. This page helps you plan the integration; it is not a contract. Build capture screens that render whatever the API returns instead of hardcoding fields per country.

​
Acceptance by country

The table below shows which documents MoonPay accepts per country.

​
Proof of address

When proofOfAddress is incomplete in kyc.requirements, the customer must submit a document confirming their residential address. Submit it through the presigned upload flow. Accepted documents
  • Utility bills (electricity, gas, internet, landline, or water)
  • Bank or credit card statements
  • Mortgage statement
  • Certificate of voter registration
  • Government correspondence (for example, from a tax authority or licensing body)
  • Lease agreements or rent receipts
  • Insurance documents
  • Tax documents
  • Official letters from schools, employers, or government agencies
  • Employer’s certificate (payslips are not accepted)
  • Certificate of vehicle registration
Recency Documents must be dated within the last 90 days. Documents outside this window are rejected. Country coverage The accepted document list applies globally with no country-specific restrictions.

​
Proof of income

When proofOfIncome is incomplete in kyc.requirements, the customer must submit a document that supports the source of wealth they declare. This is its own requirement, separate from the Enhanced Due Diligence questionnaire. Submit it through the presigned upload flow with fileType set to proofOfIncome. The document is single-sided, so omit side. Proof-of-income uploads take two extra fields, on both the upload URL request (POST /platform/v1/customers/{id}/files/upload-url) and the confirm request (POST /platform/v1/customers/{id}/files). The values you confirm must match the ones you declared when you requested the upload URL, and the subtype must be permitted for the sourceOfWealth. Otherwise the API returns INVALID_REQUEST. The API also rejects both fields for every other file type. Customers with rejected files get 409 Conflict. See Upload a file. The sourceOfWealth here describes the document. Its values aren’t limited to the sourceOfWealth you submit in the Customer Due Diligence questionnaire. The permitted subtype values for each sourceOfWealth: The upload runs in three steps. Request the upload URL, PUT the file to the URL in the response, then confirm with the uploadId from that same response.
Upload URL request
Confirm request

​
Selfie and liveness check

Details on selfie and liveness check requirements are being finalized. Contact your MoonPay account team if you need this information sooner.