Skip to main content
MoonPay Enterprise checks the format of every tax identification number (TIN) you submit for an individual customer. The format depends on tax_residence_country, not on the customer’s address or nationality. Match the format below and the TIN passes on the first attempt. The check runs on two endpoints:
Beneficiary TINs on a Business submission aren’t checked against this table.
On a Person submission whose tax residence is a jurisdiction that doesn’t issue tax IDs, the TIN isn’t checked. Any value you send is ignored and identity.identity_number is used instead. Tax residence is tax_residence_country. If you send neither a TIN nor tax_residence_country, address.country is used. A TIN without tax_residence_country still needs it, as described below. US persons (US address, US nationality, or a US-issued identity document) are never covered by this.

Tax residence country

Send tax_residence_country as an ISO 3166-1 alpha-2 code (DE, US) whenever you send tax_identification_number.
  • On a Person submission with API version 2026-10-15 or later, it’s always required, with or without a TIN. A missing one returns tin_required.
  • On a Person submission with an earlier version, you can omit it only when identity.identity_country_code is US. The TIN is then checked against the US format.
  • On PATCH /api/customers/{id}/identification-data, it’s always required with a TIN.

Formatting rules

  • Whitespace is ignored. Spaces anywhere in the value, including between groups of digits, are removed before the check.
  • Separators are accepted. Dashes (-), periods (.), and slashes (/) used between groups pass, so a US SSN like 123-45-6789 is accepted the same as 123456789.
  • Finland is the exception. The century marker is part of the format, so 010101-123A passes and 0101011234 fails. See the table below.
  • Letters are case-insensitive. Wherever a format allows a letter, upper and lower case both pass.

Country formats

Other countries

For a tax_residence_country not in the table, the TIN must:
  • Contain only letters, digits, +, and - (plus the whitespace and separators from Formatting rules)
  • Include 4-20 digits. Letters and punctuation don’t count toward that total.

Errors

A TIN that doesn’t match the format returns 400. The message names the country and an example of the expected format. On a Person submission under X-API-Version: 2026-08-01 or later, the error code is invalid_request:
Earlier API versions, and PATCH /api/customers/{id}/identification-data, return the same message as a plain string:
A TIN without tax_residence_country returns tin_required on a Person submission, and this plain string on PATCH /api/customers/{id}/identification-data:
Run the same format check in your own UI before you submit. Your customer fixes a typo on the spot instead of your integration handling a 400.
If a TIN is rejected and you believe it matches the format for its country, contact support with the customer ID and the country. Don’t send the full TIN.