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:
| Field | Managed by | Description | Format |
|---|---|---|---|
id | Manteca | Immutable global identifier | 24-character hex string |
numberId | Manteca | Numeric identifier, unique per entity type | Positive integer |
externalId | Client | Your business reference, must be unique per entity type | See constraints below |
sessionId | Client | Grouping key to correlate related operations | No 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
idformat) - Must not be a purely numeric string (would collide with the
numberIdformat) - 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.
| Type | Description |
|---|---|
RAMP_OPERATION | Full ramp: deposit, conversion, and payout to a destination. Each leg of an FX operation is one too. |
PARTIAL_RAMP_OPERATION | Ramp without the payout: deposit and conversion only. The funds stay in the user's balance. |
QR3_PAYMENT | Argentina dynamic QR payment |
PIX_PAYMENT | Brazil Pix payment, from a QR or a Pix key |
PERU_QR_PAYMENT | Peru QR payment |
BOLIVIA_QR_PAYMENT | Bolivia QR payment |
PARAGUAY_QR_PAYMENT | Paraguay QR payment |
BREB_PAYMENT | Colombia BRE-B payment, from a QR or a BRE-B key |
BILL_PAYMENT | Utility or service bill payment |
CHARGE | Collect a payment from a payer into one of your users, converted to the asset you want to receive |
COLLECT | Pull a deposit from a user's virtual account into your master account |
DISBURSE | Push 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": []
}| Field | Description |
|---|---|
status | HTTP status code |
internalStatus | Machine-readable error code for programmatic handling |
message | Human-readable explanation |
errors | Array of field-level validation details (present on 400 validation errors) |
Handle internalStatus in code, not message — messages may change.
Related concepts
Updated 2 months ago