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

TopicEnd-user modelPrincipal Accounts model
Who onboards end-usersManteca (via this section)Your platform, audited by Manteca compliance
Identifier sent per operationuserAnyId of the end-useruserAnyId of the principal account + sender with end-user data
Compliance data carrierTied to the onboarded user recordSent inline in sender (and recipient when applicable) per request
ReconciliationDistributed across end-usersConsolidated at the principal account level
Audit requirementNo partner-side KYC audit — Manteca runs KYC on end-usersCompliance homologation of the partner's own onboarding process
Typical userDirect B2C platforms, non-custodial wallets, brokersRegulated 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

  • userAnyId identifies your principal account in Manteca — not the end-user. It is required on Ramps endpoints (POST /v2/withdraws and ramp-on/ramp-off synthetics) and optional on QR Payments and Bill Payments endpoints.

  • The end-user identity travels in the sender object on each compliance-sensitive request. sender carries 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 the recipient object.

  • When the destination belongs to a different person from sender, also include recipient with the beneficiary's identity. This applies to POST /v2/withdraws and to synthetic endpoints with an outbound leg (POST /v2/synthetics/ramp-off, POST /v2/synthetics/qr-payment, POST /v2/synthetics/bill-payment). When recipient is present and differs from sender, 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 sender or recipient for 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:

FormatWhat it isExample (Argentina)
Full nameThe country name in UPPER_SNAKE_CASE — uppercase, spaces replaced by underscores, no accents. Case-sensitive.ARGENTINA
ISO alpha-2The 2-letter ISO 3166-1 alpha-2 country code. Case-insensitive.AR
ISO alpha-3The 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.

CountryFull name (legalIdNationality)ISO alpha-2ISO alpha-3
AfghanistanAFGHANISTANAFAFG
Aland IslandsALAND_ISLANDSAXALA
AlbaniaALBANIAALALB
AlgeriaALGERIADZDZA
American SamoaAMERICAN_SAMOAASASM
AndorraANDORRAADAND
AngolaANGOLAAOAGO
AnguillaANGUILLAAIAIA
AntarcticaANTARCTICAAQATA
Antigua And BarbudaANTIGUA_AND_BARBUDAAGATG
ArgentinaARGENTINAARARG
ArmeniaARMENIAAMARM
ArubaARUBAAWABW
AustraliaAUSTRALIAAUAUS
AustriaAUSTRIAATAUT
AzerbaijanAZERBAIJANAZAZE
BahamasBAHAMASBSBHS
BahrainBAHRAINBHBHR
BangladeshBANGLADESHBDBGD
BarbadosBARBADOSBBBRB
BelarusBELARUSBYBLR
BelgiumBELGIUMBEBEL
BelizeBELIZEBZBLZ
BeninBENINBJBEN
BermudaBERMUDABMBMU
BhutanBHUTANBTBTN
BoliviaBOLIVIABOBOL
Bonaire Sint Eustatius And SabaBONAIRE_SINT_EUSTATIUS_AND_SABABQBES
Bosnia And HerzegovinaBOSNIA_AND_HERZEGOVINABABIH
BotswanaBOTSWANABWBWA
Bouvet IslandBOUVET_ISLANDBVBVT
BrazilBRAZILBRBRA
British Indian Ocean TerritoryBRITISH_INDIAN_OCEAN_TERRITORYIOIOT
BruneiBRUNEIBNBRN
BulgariaBULGARIABGBGR
Burkina FasoBURKINA_FASOBFBFA
BurundiBURUNDIBIBDI
CambodiaCAMBODIAKHKHM
CameroonCAMEROONCMCMR
CanadaCANADACACAN
Cape VerdeCAPE_VERDECVCPV
Cayman IslandsCAYMAN_ISLANDSKYCYM
Central African RepublicCENTRAL_AFRICAN_REPUBLICCFCAF
ChadCHADTDTCD
ChileCHILECLCHL
ChinaCHINACNCHN
ColombiaCOLOMBIACOCOL
ComorosCOMOROSKMCOM
CongoCONGOCGCOG
Cook IslandsCOOK_ISLANDSCKCOK
Costa RicaCOSTA_RICACRCRI
CroatiaCROATIAHRHRV
CubaCUBACUCUB
CuracaoCURACAOCWCUW
CyprusCYPRUSCYCYP
Czech RepublicCZECH_REPUBLICCZCZE
DenmarkDENMARKDKDNK
DjiboutiDJIBOUTIDJDJI
DominicaDOMINICADMDMA
Dominican RepublicDOMINICAN_REPUBLICDODOM
East TimorEAST_TIMORTLTLS
EcuadorECUADORECECU
EgyptEGYPTEGEGY
El SalvadorEL_SALVADORSVSLV
Equatorial GuineaEQUATORIAL_GUINEAGQGNQ
EritreaERITREAERERI
EstoniaESTONIAEEEST
EthiopiaETHIOPIAETETH
Falkland IslandsFALKLAND_ISLANDSFKFLK
Faroe IslandsFAROE_ISLANDSFOFRO
FijiFIJIFJFJI
FinlandFINLANDFIFIN
FranceFRANCEFRFRA
French GuianaFRENCH_GUIANAGFGUF
French PolynesiaFRENCH_POLYNESIAPFPYF
French Southern TerritoriesFRENCH_SOUTHERN_TERRITORIESTFATF
GabonGABONGAGAB
GambiaGAMBIAGMGMB
GeorgiaGEORGIAGEGEO
GermanyGERMANYDEDEU
GhanaGHANAGHGHA
GibraltarGIBRALTARGIGIB
GreeceGREECEGRGRC
GreenlandGREENLANDGLGRL
GrenadaGRENADAGDGRD
GuadeloupeGUADELOUPEGPGLP
GuamGUAMGUGUM
GuatemalaGUATEMALAGTGTM
GuernseyGUERNSEYGGGGY
GuineaGUINEAGNGIN
Guinea BissauGUINEA_BISSAUGWGNB
GuyanaGUYANAGYGUY
HaitiHAITIHTHTI
Heard Island And Mcdonald IslandsHEARD_ISLAND_AND_MCDONALD_ISLANDSHMHMD
HondurasHONDURASHNHND
Hong KongHONG_KONGHKHKG
HungaryHUNGARYHUHUN
IcelandICELANDISISL
IndiaINDIAININD
IndonesiaINDONESIAIDIDN
IranIRANIRIRN
IraqIRAQIQIRQ
IrelandIRELANDIEIRL
Isle Of ManISLE_OF_MANIMIMN
IsraelISRAELILISR
ItalyITALYITITA
Ivory CoastIVORY_COASTCICIV
JamaicaJAMAICAJMJAM
JapanJAPANJPJPN
JerseyJERSEYJEJEY
JordanJORDANJOJOR
KazakhstanKAZAKHSTANKZKAZ
KenyaKENYAKEKEN
KiribatiKIRIBATIKIKIR
Korea NorthKOREA_NORTHKPPRK
Korea SouthKOREA_SOUTHKRKOR
KosovoKOSOVOXKXKX
KuwaitKUWAITKWKWT
KyrgyzstanKYRGYZSTANKGKGZ
LaosLAOSLALAO
LatviaLATVIALVLVA
LebanonLEBANONLBLBN
LesothoLESOTHOLSLSO
LiberiaLIBERIALRLBR
LibyaLIBYALYLBY
LiechtensteinLIECHTENSTEINLILIE
LithuaniaLITHUANIALTLTU
LuxembourgLUXEMBOURGLULUX
MacauMACAUMOMAC
MacedoniaMACEDONIAMKMKD
MadagascarMADAGASCARMGMDG
MalawiMALAWIMWMWI
MalaysiaMALAYSIAMYMYS
MaldivesMALDIVESMVMDV
MaliMALIMLMLI
MaltaMALTAMTMLT
Marshall IslandsMARSHALL_ISLANDSMHMHL
MartiniqueMARTINIQUEMQMTQ
MauritaniaMAURITANIAMRMRT
MauritiusMAURITIUSMUMUS
MayotteMAYOTTEYTMYT
MexicoMEXICOMXMEX
MicronesiaMICRONESIAFMFSM
MoldovaMOLDOVAMDMDA
MonacoMONACOMCMCO
MongoliaMONGOLIAMNMNG
MontenegroMONTENEGROMEMNE
MontserratMONTSERRATMSMSR
MoroccoMOROCCOMAMAR
MozambiqueMOZAMBIQUEMZMOZ
MyanmarMYANMARMMMMR
NamibiaNAMIBIANANAM
NauruNAURUNRNRU
NepalNEPALNPNPL
NetherlandsNETHERLANDSNLNLD
Netherlands AntillesNETHERLANDS_ANTILLESANANT
New CaledoniaNEW_CALEDONIANCNCL
New ZealandNEW_ZEALANDNZNZL
NicaraguaNICARAGUANINIC
NigerNIGERNENER
NigeriaNIGERIANGNGA
NiueNIUENUNIU
Norfolk IslandNORFOLK_ISLANDNFNFK
Northern Mariana IslandsNORTHERN_MARIANA_ISLANDSMPMNP
NorwayNORWAYNONOR
OmanOMANOMOMN
PakistanPAKISTANPKPAK
PalauPALAUPWPLW
PalestinePALESTINEPSPSE
PanamaPANAMAPAPAN
Papua New GuineaPAPUA_NEW_GUINEAPGPNG
ParaguayPARAGUAYPYPRY
PeruPERUPEPER
PhilippinesPHILIPPINESPHPHL
PitcairnPITCAIRNPNPCN
PolandPOLANDPLPOL
PortugalPORTUGALPTPRT
Puerto RicoPUERTO_RICOPRPRI
QatarQATARQAQAT
ReunionREUNIONREREU
RomaniaROMANIAROROU
RussiaRUSSIARURUS
RwandaRWANDARWRWA
Saint BarthelemySAINT_BARTHELEMYBLBLM
Saint Helena Ascension And Tristan Da CunhaSAINT_HELENA_ASCENSION_AND_TRISTAN_DA_CUNHASHSHN
Saint Kitts And NevisSAINT_KITTS_AND_NEVISKNKNA
Saint LuciaSAINT_LUCIALCLCA
Saint MartinSAINT_MARTINMFMAF
Saint Pierre And MiquelonSAINT_PIERRE_AND_MIQUELONPMSPM
Saint Vincent And The GrenadinesSAINT_VINCENT_AND_THE_GRENADINESVCVCT
SamoaSAMOAWSWSM
San MarinoSAN_MARINOSMSMR
Sao Tome And PrincipeSAO_TOME_AND_PRINCIPESTSTP
Saudi ArabiaSAUDI_ARABIASASAU
SenegalSENEGALSNSEN
SerbiaSERBIARSSRB
SeychellesSEYCHELLESSCSYC
Sierra LeoneSIERRA_LEONESLSLE
SingaporeSINGAPORESGSGP
Sint MaartenSINT_MAARTENSXSXM
SlovakiaSLOVAKIASKSVK
SloveniaSLOVENIASISVN
Solomon IslandsSOLOMON_ISLANDSSBSLB
SomaliaSOMALIASOSOM
South AfricaSOUTH_AFRICAZAZAF
South Georgia And The South Sandwich IslandsSOUTH_GEORGIA_AND_THE_SOUTH_SANDWICH_ISLANDSGSSGS
South SudanSOUTH_SUDANSSSSD
SpainSPAINESESP
Sri LankaSRI_LANKALKLKA
SudanSUDANSDSDN
SurinameSURINAMESRSUR
Svalbard And Jan MayenSVALBARD_AND_JAN_MAYENSJSJM
SwazilandSWAZILANDSZSWZ
SwedenSWEDENSESWE
SwitzerlandSWITZERLANDCHCHE
SyriaSYRIASYSYR
TaiwanTAIWANTWTWN
TajikistanTAJIKISTANTJTJK
TanzaniaTANZANIATZTZA
ThailandTHAILANDTHTHA
TogoTOGOTGTGO
TokelauTOKELAUTKTKL
TongaTONGATOTON
Trinidad And TobagoTRINIDAD_AND_TOBAGOTTTTO
TunisiaTUNISIATNTUN
TurkeyTURKEYTRTUR
TurkmenistanTURKMENISTANTMTKM
TuvaluTUVALUTVTUV
UgandaUGANDAUGUGA
UkraineUKRAINEUAUKR
United Arab EmiratesUNITED_ARAB_EMIRATESAEARE
United KingdomUNITED_KINGDOMGBGBR
United StatesUNITED_STATESUSUSA
United States Minor Outlying IslandsUNITED_STATES_MINOR_OUTLYING_ISLANDSUMUMI
UruguayURUGUAYUYURY
UzbekistanUZBEKISTANUZUZB
VanuatuVANUATUVUVUT
Vatican CityVATICAN_CITYVAVAT
VenezuelaVENEZUELAVEVEN
VietnamVIETNAMVNVNM
Wallis And FutunaWALLIS_AND_FUTUNAWFWLF
Western SaharaWESTERN_SAHARAEHESH
YemenYEMENYEYEM
ZambiaZAMBIAZMZMB
ZimbabweZIMBABWEZWZWE

Reference by service

ServiceEndpointEnd-user modelPrincipal Accounts model
Ramps — manual Ramp-offPOST /v2/withdrawsuserAnyId (end-user)userAnyId (principal) + sender + optional recipient
Ramps — Ramp-on syntheticPOST /v2/synthetics/ramp-onuserAnyId (end-user)userAnyId (principal) + sender (see Synthetics note above)
Ramps — Ramp-off syntheticPOST /v2/synthetics/ramp-offuserAnyId (end-user)userAnyId (principal) + sender + optional recipient (see Synthetics note)
QR Payments — previewPOST /v2/payment-locksuserAnyId (end-user) + sender (same identity)userAnyId (optional) + sender (real payer)
QR Payments — executePOST /v2/synthetics/qr-paymentuserAnyId (end-user)userAnyId (optional) + sender + optional recipient (see Synthetics note)
Bill Payments — lockPOST /v2/bill-locksuserAnyId (end-user) + sender (same identity)userAnyId (optional) + sender (real payer)
Bill Payments — executePOST /v2/synthetics/bill-paymentuserAnyId (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.


Did this page help you?