Key concepts

This section covers fundamental concepts that apply across the entire Manteca API.

Manteca APIs share a common operational model across all services. Understanding these primitives before building saves significant debugging time.


Identity model

Every entity (user, order, withdrawal, deposit, synthetic) has three identifiers:

FieldManaged byDescriptionFormat
idMantecaImmutable global identifier24-character hex string
numberIdMantecaNumeric identifier, unique per entity typePositive integer
externalIdClientYour business reference, must be unique per entity typeSee constraints below
sessionIdClientGrouping key to correlate related operationsNo uniqueness constraints

externalId constraints

  • Must be unique per entity type (two users cannot share an externalId; a user and an order can)
  • Must not be a 24-character hex string (would collide with the id format)
  • Must not be a purely numeric string (would collide with the numberId format)
  • Good: "user-9821", "order-ref-00441", "ramp-op-2024-03-15"
  • Bad: "64a1f2e3b4c5d6e7f8a9b0c1" (24-char hex), "10042" (pure integer)

AnyId convention

Most endpoints accept an anyId parameter (e.g., userAnyId, syntheticAnyId) that resolves any of the three identifier types automatically:

userAnyId = id  |  numberId  |  externalId

You don't need to track which format Manteca issued — pass whatever your system has. Manteca resolves it.


Synthetics

A synthetic is an orchestrated, multi-step operation tracked as a single entity. It chains individual stages — deposits, orders, withdrawals, payments — into one lifecycle with a shared id, numberId, and externalId.

Use SYNTHETIC_STATUS_UPDATE webhooks to track the overall operation. Individual stages also emit their own events.

Synthetic types

The type field tells you which operation the synthetic represents.

TypeDescription
RAMP_OPERATIONFull ramp: deposit, conversion, and payout to a destination. Each leg of an FX operation is one too.
PARTIAL_RAMP_OPERATIONRamp without the payout: deposit and conversion only. The funds stay in the user's balance.
QR3_PAYMENTArgentina dynamic QR payment
PIX_PAYMENTBrazil Pix payment, from a QR or a Pix key
PERU_QR_PAYMENTPeru QR payment
BOLIVIA_QR_PAYMENTBolivia QR payment
PARAGUAY_QR_PAYMENTParaguay QR payment
BREB_PAYMENTColombia BRE-B payment, from a QR or a BRE-B key
BILL_PAYMENTUtility or service bill payment
CHARGECollect a payment from a payer into one of your users, converted to the asset you want to receive
COLLECTPull a deposit from a user's virtual account into your master account
DISBURSEPush funds from your master account, through a user's virtual account, to an external destination

Don't confuse it with stageType, which each entry inside stages carries to describe that single step (DEPOSIT, ORDER, WITHDRAW, TRANSFER, and so on). BILL_PAYMENT exists in both, so match on the level you mean.


Person-level compliance

Compliance is enforced at the person level, not the user-record level. If the same legal entity operates under multiple user records, limits and checks apply across all of them collectively.


Principal Accounts model

Manteca supports two operational models. In the End-user model (default), each end-user is onboarded individually in Manteca and identified by their own userAnyId on every operation. In the Principal Accounts model, your company holds a single principal account in Manteca, end-user onboarding lives in your platform, and the end-user identity travels inline in each request via the sender object.

Principal Accounts requires a compliance homologation of your in-house onboarding process before it can be enabled. Contact your account manager to determine which model applies to your account.

Read more about onboarding models →


Error envelope

All API errors return a consistent JSON structure:

{
  "status": 400,
  "internalStatus": "NO_FUNDS",
  "message": "Insufficient funds.",
  "errors": []
}
FieldDescription
statusHTTP status code
internalStatusMachine-readable error code for programmatic handling
messageHuman-readable explanation
errorsArray of field-level validation details (present on 400 validation errors)

Handle internalStatus in code, not message — messages may change.


Related concepts


Did this page help you?