Onboarding models
Manteca supports two operational models that define how end-users are onboarded and identified in every operation. The model determines the shape of each request payload, where compliance data is stored, and how reconciliation is consolidated. Pick a model before integrating.
Models at a glance
| Topic | End-user model | Principal Accounts model |
|---|---|---|
| Who onboards end-users | Manteca (via this section) | Your platform, audited by Manteca compliance |
| Identifier sent per operation | userAnyId of the end-user | userAnyId of the principal account + sender with end-user data |
| Compliance data carrier | Tied to the onboarded user record | Sent inline in sender (and recipient when applicable) per request |
| Reconciliation | Distributed across end-users | Consolidated at the principal account level |
| Audit requirement | No partner-side KYC audit — Manteca runs KYC on end-users | Compliance homologation of the partner's own onboarding process |
| Typical user | Direct B2C platforms, non-custodial wallets, brokers | Regulated fintechs and exchanges with mature local KYC pipelines |
End-user model (default)
Every end-user completes their own onboarding inside Manteca: personal data, document upload, KYC checks, PEP/FEP declarations, and limit assignment. Each end-user has a unique userAnyId (with id, numberId, and externalId variants — see AnyId convention).
Operations are identified by sending the end-user's userAnyId in the request body. Compliance state (limits, blocks, PEP flags) is enforced against that user record.
Start with Create user to onboard your first end-user, and review Country requirements for the payload expected in each jurisdiction.
Principal Accounts model
End-users are not onboarded in Manteca. Your platform owns the onboarding flow and the KYC pipeline. Manteca holds a single principal account for your company; operations execute under that account with end-user identity declared inline in each request.
When it applies
Principal Accounts is reserved for partners with regulated, mature KYC pipelines under formal local jurisdiction — licensed exchanges, regulated fintechs, and similar entities. The partner remains the compliance owner for the end-user; this regulatory pattern is commonly referred to as KYC reliance (Manteca relies on the partner's KYC for end-user identity verification).
The model does not apply to platforms without their own onboarding process — for example, self-custodial or decentralized wallets without identity verification. Those integrations must use the End-user model.
Audit requirement
Before Principal Accounts is enabled, Manteca's compliance team audits your in-house onboarding process: KYC procedure, document retention, sanction screening, and ongoing monitoring. Contact your account manager to start the homologation process.
How operations are identified
-
userAnyIdidentifies your principal account in Manteca — not the end-user. It is required on Ramps endpoints (POST /v2/withdrawsand ramp-on/ramp-off synthetics) and optional on QR Payments and Bill Payments endpoints. -
The end-user identity travels in the
senderobject on each compliance-sensitive request.sendercarries the real payer's country, legal ID, and name:{ "sender": { "legalIdNationality": "ARGENTINA", "legalId": "20406620000", "name": "JANE", "surname": "DOE" } }The payer's country travels in
legalIdNationality, consistent with the limits query below. The same field is used on therecipientobject. -
When the destination belongs to a different person from
sender, also includerecipientwith the beneficiary's identity. This applies toPOST /v2/withdrawsand to synthetic endpoints with an outbound leg (POST /v2/synthetics/ramp-off,POST /v2/synthetics/qr-payment,POST /v2/synthetics/bill-payment). Whenrecipientis present and differs fromsender, the operation is treated as a third-party transfer and is subject to the Outbound limit. See Third-party transfers for full shape and limit details.
The OpenAPI specification does not currently expose
senderorrecipientfor synthetic endpoints (POST /v2/synthetics/ramp-on,POST /v2/synthetics/ramp-off,POST /v2/synthetics/qr-payment,POST /v2/synthetics/bill-payment). The runtime accepts both fields on these endpoints for the Principal Accounts model. A specification update is tracked separately — until it ships, refer to this page for the supported request shape.
Looking up limits and per-entity data
Endpoints that look up per-entity data (e.g., GET /v2/limits/:numberId) accept the end-user's Manteca numberId as the path parameter. Under Principal Accounts, partners typically do not hold a Manteca numberId for each end-user — only the legal identity declared in sender.
For these cases, query the same data using legalIdNationality + legalId as query parameters:
GET /v2/limits?legalIdNationality=ARG&legalId=20406620000
The response shape is identical to the path-parameter variant. See Operational Limits for the full request and response details.
Legal ID nationality — accepted values
legalIdNationality declares the country of the legal identity carried in sender (and, when present, recipient). The same field is accepted as a query parameter when looking up limits by legal identity.
The field accepts three interchangeable formats for the same country — send whichever you already have. Manteca normalizes all of them to the canonical full name internally:
| Format | What it is | Example (Argentina) |
|---|---|---|
| Full name | The country name in UPPER_SNAKE_CASE — uppercase, spaces replaced by underscores, no accents. Case-sensitive. | ARGENTINA |
| ISO alpha-2 | The 2-letter ISO 3166-1 alpha-2 country code. Case-insensitive. | AR |
| ISO alpha-3 | The 3-letter ISO 3166-1 alpha-3 country code. Case-insensitive. | ARG |
All three forms in the row below resolve to the same country, so these payloads are equivalent:
{ "sender": { "legalIdNationality": "ARGENTINA", "legalId": "20406620000", "name": "JANE", "surname": "DOE" } }
{ "sender": { "legalIdNationality": "AR", "legalId": "20406620000", "name": "JANE", "surname": "DOE" } }
{ "sender": { "legalIdNationality": "ARG", "legalId": "20406620000", "name": "JANE", "surname": "DOE" } }Sending a value that is not in the table below — an unlisted country, a misspelled name, or an invalid ISO code — rejects the request. The full name must be exact
UPPER_SNAKE_CASE; ISO codes may be sent in any case.
Supported countries
Any of the three columns can be sent as legalIdNationality. Note that being listed here does not guarantee Manteca operates in that country — supported operations per jurisdiction are covered in Country requirements. Users whose legalIdNationality is one of the restricted countries cannot be onboarded.
| Country | Full name (legalIdNationality) | ISO alpha-2 | ISO alpha-3 |
|---|---|---|---|
| Afghanistan | AFGHANISTAN | AF | AFG |
| Aland Islands | ALAND_ISLANDS | AX | ALA |
| Albania | ALBANIA | AL | ALB |
| Algeria | ALGERIA | DZ | DZA |
| American Samoa | AMERICAN_SAMOA | AS | ASM |
| Andorra | ANDORRA | AD | AND |
| Angola | ANGOLA | AO | AGO |
| Anguilla | ANGUILLA | AI | AIA |
| Antarctica | ANTARCTICA | AQ | ATA |
| Antigua And Barbuda | ANTIGUA_AND_BARBUDA | AG | ATG |
| Argentina | ARGENTINA | AR | ARG |
| Armenia | ARMENIA | AM | ARM |
| Aruba | ARUBA | AW | ABW |
| Australia | AUSTRALIA | AU | AUS |
| Austria | AUSTRIA | AT | AUT |
| Azerbaijan | AZERBAIJAN | AZ | AZE |
| Bahamas | BAHAMAS | BS | BHS |
| Bahrain | BAHRAIN | BH | BHR |
| Bangladesh | BANGLADESH | BD | BGD |
| Barbados | BARBADOS | BB | BRB |
| Belarus | BELARUS | BY | BLR |
| Belgium | BELGIUM | BE | BEL |
| Belize | BELIZE | BZ | BLZ |
| Benin | BENIN | BJ | BEN |
| Bermuda | BERMUDA | BM | BMU |
| Bhutan | BHUTAN | BT | BTN |
| Bolivia | BOLIVIA | BO | BOL |
| Bonaire Sint Eustatius And Saba | BONAIRE_SINT_EUSTATIUS_AND_SABA | BQ | BES |
| Bosnia And Herzegovina | BOSNIA_AND_HERZEGOVINA | BA | BIH |
| Botswana | BOTSWANA | BW | BWA |
| Bouvet Island | BOUVET_ISLAND | BV | BVT |
| Brazil | BRAZIL | BR | BRA |
| British Indian Ocean Territory | BRITISH_INDIAN_OCEAN_TERRITORY | IO | IOT |
| Brunei | BRUNEI | BN | BRN |
| Bulgaria | BULGARIA | BG | BGR |
| Burkina Faso | BURKINA_FASO | BF | BFA |
| Burundi | BURUNDI | BI | BDI |
| Cambodia | CAMBODIA | KH | KHM |
| Cameroon | CAMEROON | CM | CMR |
| Canada | CANADA | CA | CAN |
| Cape Verde | CAPE_VERDE | CV | CPV |
| Cayman Islands | CAYMAN_ISLANDS | KY | CYM |
| Central African Republic | CENTRAL_AFRICAN_REPUBLIC | CF | CAF |
| Chad | CHAD | TD | TCD |
| Chile | CHILE | CL | CHL |
| China | CHINA | CN | CHN |
| Colombia | COLOMBIA | CO | COL |
| Comoros | COMOROS | KM | COM |
| Congo | CONGO | CG | COG |
| Cook Islands | COOK_ISLANDS | CK | COK |
| Costa Rica | COSTA_RICA | CR | CRI |
| Croatia | CROATIA | HR | HRV |
| Cuba | CUBA | CU | CUB |
| Curacao | CURACAO | CW | CUW |
| Cyprus | CYPRUS | CY | CYP |
| Czech Republic | CZECH_REPUBLIC | CZ | CZE |
| Denmark | DENMARK | DK | DNK |
| Djibouti | DJIBOUTI | DJ | DJI |
| Dominica | DOMINICA | DM | DMA |
| Dominican Republic | DOMINICAN_REPUBLIC | DO | DOM |
| East Timor | EAST_TIMOR | TL | TLS |
| Ecuador | ECUADOR | EC | ECU |
| Egypt | EGYPT | EG | EGY |
| El Salvador | EL_SALVADOR | SV | SLV |
| Equatorial Guinea | EQUATORIAL_GUINEA | GQ | GNQ |
| Eritrea | ERITREA | ER | ERI |
| Estonia | ESTONIA | EE | EST |
| Ethiopia | ETHIOPIA | ET | ETH |
| Falkland Islands | FALKLAND_ISLANDS | FK | FLK |
| Faroe Islands | FAROE_ISLANDS | FO | FRO |
| Fiji | FIJI | FJ | FJI |
| Finland | FINLAND | FI | FIN |
| France | FRANCE | FR | FRA |
| French Guiana | FRENCH_GUIANA | GF | GUF |
| French Polynesia | FRENCH_POLYNESIA | PF | PYF |
| French Southern Territories | FRENCH_SOUTHERN_TERRITORIES | TF | ATF |
| Gabon | GABON | GA | GAB |
| Gambia | GAMBIA | GM | GMB |
| Georgia | GEORGIA | GE | GEO |
| Germany | GERMANY | DE | DEU |
| Ghana | GHANA | GH | GHA |
| Gibraltar | GIBRALTAR | GI | GIB |
| Greece | GREECE | GR | GRC |
| Greenland | GREENLAND | GL | GRL |
| Grenada | GRENADA | GD | GRD |
| Guadeloupe | GUADELOUPE | GP | GLP |
| Guam | GUAM | GU | GUM |
| Guatemala | GUATEMALA | GT | GTM |
| Guernsey | GUERNSEY | GG | GGY |
| Guinea | GUINEA | GN | GIN |
| Guinea Bissau | GUINEA_BISSAU | GW | GNB |
| Guyana | GUYANA | GY | GUY |
| Haiti | HAITI | HT | HTI |
| Heard Island And Mcdonald Islands | HEARD_ISLAND_AND_MCDONALD_ISLANDS | HM | HMD |
| Honduras | HONDURAS | HN | HND |
| Hong Kong | HONG_KONG | HK | HKG |
| Hungary | HUNGARY | HU | HUN |
| Iceland | ICELAND | IS | ISL |
| India | INDIA | IN | IND |
| Indonesia | INDONESIA | ID | IDN |
| Iran | IRAN | IR | IRN |
| Iraq | IRAQ | IQ | IRQ |
| Ireland | IRELAND | IE | IRL |
| Isle Of Man | ISLE_OF_MAN | IM | IMN |
| Israel | ISRAEL | IL | ISR |
| Italy | ITALY | IT | ITA |
| Ivory Coast | IVORY_COAST | CI | CIV |
| Jamaica | JAMAICA | JM | JAM |
| Japan | JAPAN | JP | JPN |
| Jersey | JERSEY | JE | JEY |
| Jordan | JORDAN | JO | JOR |
| Kazakhstan | KAZAKHSTAN | KZ | KAZ |
| Kenya | KENYA | KE | KEN |
| Kiribati | KIRIBATI | KI | KIR |
| Korea North | KOREA_NORTH | KP | PRK |
| Korea South | KOREA_SOUTH | KR | KOR |
| Kosovo | KOSOVO | XK | XKX |
| Kuwait | KUWAIT | KW | KWT |
| Kyrgyzstan | KYRGYZSTAN | KG | KGZ |
| Laos | LAOS | LA | LAO |
| Latvia | LATVIA | LV | LVA |
| Lebanon | LEBANON | LB | LBN |
| Lesotho | LESOTHO | LS | LSO |
| Liberia | LIBERIA | LR | LBR |
| Libya | LIBYA | LY | LBY |
| Liechtenstein | LIECHTENSTEIN | LI | LIE |
| Lithuania | LITHUANIA | LT | LTU |
| Luxembourg | LUXEMBOURG | LU | LUX |
| Macau | MACAU | MO | MAC |
| Macedonia | MACEDONIA | MK | MKD |
| Madagascar | MADAGASCAR | MG | MDG |
| Malawi | MALAWI | MW | MWI |
| Malaysia | MALAYSIA | MY | MYS |
| Maldives | MALDIVES | MV | MDV |
| Mali | MALI | ML | MLI |
| Malta | MALTA | MT | MLT |
| Marshall Islands | MARSHALL_ISLANDS | MH | MHL |
| Martinique | MARTINIQUE | MQ | MTQ |
| Mauritania | MAURITANIA | MR | MRT |
| Mauritius | MAURITIUS | MU | MUS |
| Mayotte | MAYOTTE | YT | MYT |
| Mexico | MEXICO | MX | MEX |
| Micronesia | MICRONESIA | FM | FSM |
| Moldova | MOLDOVA | MD | MDA |
| Monaco | MONACO | MC | MCO |
| Mongolia | MONGOLIA | MN | MNG |
| Montenegro | MONTENEGRO | ME | MNE |
| Montserrat | MONTSERRAT | MS | MSR |
| Morocco | MOROCCO | MA | MAR |
| Mozambique | MOZAMBIQUE | MZ | MOZ |
| Myanmar | MYANMAR | MM | MMR |
| Namibia | NAMIBIA | NA | NAM |
| Nauru | NAURU | NR | NRU |
| Nepal | NEPAL | NP | NPL |
| Netherlands | NETHERLANDS | NL | NLD |
| Netherlands Antilles | NETHERLANDS_ANTILLES | AN | ANT |
| New Caledonia | NEW_CALEDONIA | NC | NCL |
| New Zealand | NEW_ZEALAND | NZ | NZL |
| Nicaragua | NICARAGUA | NI | NIC |
| Niger | NIGER | NE | NER |
| Nigeria | NIGERIA | NG | NGA |
| Niue | NIUE | NU | NIU |
| Norfolk Island | NORFOLK_ISLAND | NF | NFK |
| Northern Mariana Islands | NORTHERN_MARIANA_ISLANDS | MP | MNP |
| Norway | NORWAY | NO | NOR |
| Oman | OMAN | OM | OMN |
| Pakistan | PAKISTAN | PK | PAK |
| Palau | PALAU | PW | PLW |
| Palestine | PALESTINE | PS | PSE |
| Panama | PANAMA | PA | PAN |
| Papua New Guinea | PAPUA_NEW_GUINEA | PG | PNG |
| Paraguay | PARAGUAY | PY | PRY |
| Peru | PERU | PE | PER |
| Philippines | PHILIPPINES | PH | PHL |
| Pitcairn | PITCAIRN | PN | PCN |
| Poland | POLAND | PL | POL |
| Portugal | PORTUGAL | PT | PRT |
| Puerto Rico | PUERTO_RICO | PR | PRI |
| Qatar | QATAR | QA | QAT |
| Reunion | REUNION | RE | REU |
| Romania | ROMANIA | RO | ROU |
| Russia | RUSSIA | RU | RUS |
| Rwanda | RWANDA | RW | RWA |
| Saint Barthelemy | SAINT_BARTHELEMY | BL | BLM |
| Saint Helena Ascension And Tristan Da Cunha | SAINT_HELENA_ASCENSION_AND_TRISTAN_DA_CUNHA | SH | SHN |
| Saint Kitts And Nevis | SAINT_KITTS_AND_NEVIS | KN | KNA |
| Saint Lucia | SAINT_LUCIA | LC | LCA |
| Saint Martin | SAINT_MARTIN | MF | MAF |
| Saint Pierre And Miquelon | SAINT_PIERRE_AND_MIQUELON | PM | SPM |
| Saint Vincent And The Grenadines | SAINT_VINCENT_AND_THE_GRENADINES | VC | VCT |
| Samoa | SAMOA | WS | WSM |
| San Marino | SAN_MARINO | SM | SMR |
| Sao Tome And Principe | SAO_TOME_AND_PRINCIPE | ST | STP |
| Saudi Arabia | SAUDI_ARABIA | SA | SAU |
| Senegal | SENEGAL | SN | SEN |
| Serbia | SERBIA | RS | SRB |
| Seychelles | SEYCHELLES | SC | SYC |
| Sierra Leone | SIERRA_LEONE | SL | SLE |
| Singapore | SINGAPORE | SG | SGP |
| Sint Maarten | SINT_MAARTEN | SX | SXM |
| Slovakia | SLOVAKIA | SK | SVK |
| Slovenia | SLOVENIA | SI | SVN |
| Solomon Islands | SOLOMON_ISLANDS | SB | SLB |
| Somalia | SOMALIA | SO | SOM |
| South Africa | SOUTH_AFRICA | ZA | ZAF |
| South Georgia And The South Sandwich Islands | SOUTH_GEORGIA_AND_THE_SOUTH_SANDWICH_ISLANDS | GS | SGS |
| South Sudan | SOUTH_SUDAN | SS | SSD |
| Spain | SPAIN | ES | ESP |
| Sri Lanka | SRI_LANKA | LK | LKA |
| Sudan | SUDAN | SD | SDN |
| Suriname | SURINAME | SR | SUR |
| Svalbard And Jan Mayen | SVALBARD_AND_JAN_MAYEN | SJ | SJM |
| Swaziland | SWAZILAND | SZ | SWZ |
| Sweden | SWEDEN | SE | SWE |
| Switzerland | SWITZERLAND | CH | CHE |
| Syria | SYRIA | SY | SYR |
| Taiwan | TAIWAN | TW | TWN |
| Tajikistan | TAJIKISTAN | TJ | TJK |
| Tanzania | TANZANIA | TZ | TZA |
| Thailand | THAILAND | TH | THA |
| Togo | TOGO | TG | TGO |
| Tokelau | TOKELAU | TK | TKL |
| Tonga | TONGA | TO | TON |
| Trinidad And Tobago | TRINIDAD_AND_TOBAGO | TT | TTO |
| Tunisia | TUNISIA | TN | TUN |
| Turkey | TURKEY | TR | TUR |
| Turkmenistan | TURKMENISTAN | TM | TKM |
| Tuvalu | TUVALU | TV | TUV |
| Uganda | UGANDA | UG | UGA |
| Ukraine | UKRAINE | UA | UKR |
| United Arab Emirates | UNITED_ARAB_EMIRATES | AE | ARE |
| United Kingdom | UNITED_KINGDOM | GB | GBR |
| United States | UNITED_STATES | US | USA |
| United States Minor Outlying Islands | UNITED_STATES_MINOR_OUTLYING_ISLANDS | UM | UMI |
| Uruguay | URUGUAY | UY | URY |
| Uzbekistan | UZBEKISTAN | UZ | UZB |
| Vanuatu | VANUATU | VU | VUT |
| Vatican City | VATICAN_CITY | VA | VAT |
| Venezuela | VENEZUELA | VE | VEN |
| Vietnam | VIETNAM | VN | VNM |
| Wallis And Futuna | WALLIS_AND_FUTUNA | WF | WLF |
| Western Sahara | WESTERN_SAHARA | EH | ESH |
| Yemen | YEMEN | YE | YEM |
| Zambia | ZAMBIA | ZM | ZMB |
| Zimbabwe | ZIMBABWE | ZW | ZWE |
Reference by service
| Service | Endpoint | End-user model | Principal Accounts model |
|---|---|---|---|
| Ramps — manual Ramp-off | POST /v2/withdraws | userAnyId (end-user) | userAnyId (principal) + sender + optional recipient |
| Ramps — Ramp-on synthetic | POST /v2/synthetics/ramp-on | userAnyId (end-user) | userAnyId (principal) + sender (see Synthetics note above) |
| Ramps — Ramp-off synthetic | POST /v2/synthetics/ramp-off | userAnyId (end-user) | userAnyId (principal) + sender + optional recipient (see Synthetics note) |
| QR Payments — preview | POST /v2/payment-locks | userAnyId (end-user) + sender (same identity) | userAnyId (optional) + sender (real payer) |
| QR Payments — execute | POST /v2/synthetics/qr-payment | userAnyId (end-user) | userAnyId (optional) + sender + optional recipient (see Synthetics note) |
| Bill Payments — lock | POST /v2/bill-locks | userAnyId (end-user) + sender (same identity) | userAnyId (optional) + sender (real payer) |
| Bill Payments — execute | POST /v2/synthetics/bill-payment | userAnyId (end-user) | userAnyId (optional) + sender + optional recipient (see Synthetics note) |
Under the Principal Accounts model, userAnyId identifies the principal account (when sent). It is required on Ramps endpoints; on QR Payments and Bill Payments it is optional. Including recipient (when different from sender) marks the operation as a third-party transfer and triggers the Outbound limit.
Choosing your model
Contact your account manager to determine which model applies to your account. If your platform onboards end-users and meets the audit criteria, Principal Accounts can be enabled after homologation. Otherwise, integrate with the End-user model.
Updated 7 days ago