Webhooks
Manteca pushes lifecycle events to your HTTPS endpoint. Webhooks are required for reliable tracking of orders, withdrawals, deposits, and synthetic operations.
Webhooks originate from a fixed set of IPs (same in sandbox and production). Allowlist all of them in your firewall before testing:
18.229.68.9415.229.180.233177.71.146.4318.230.111.80
To configure your webhook URL and secret:
To rotate your webhook secret:
Each event type can be configured to deliver to a different endpoint URL.
Endpoint requirements
Your endpoint must:
- Accept
POSTrequests - Return a
2xxstatus code within 10 seconds - Be reachable over HTTPS
Any non-2xx response or timeout counts as a delivery failure and triggers the retry schedule, with one exception: a 401 is treated as non-recoverable and is not retried.
Webhook signature
Verify every request to protect against spoofed payloads. The signature is in the md-webhook-signature header.
import crypto from 'crypto';
export const verifyWebhookSignature = (body: any, header: string, secret: string): boolean => {
const dataString = JSON.stringify(body);
const hmac = crypto.createHmac('sha256', secret);
const signature = hmac.update(dataString, 'utf8').digest('hex');
return header === signature;
};Algorithm: HMAC SHA-256 over the raw JSON body. Compare the computed hex digest against the md-webhook-signature header value.
Key order matters. The signed payload is serialized with object keys sorted alphabetically. If your re-serialization doesn't preserve that order, the signatures won't match — you can use a stable stringifier such as
fast-json-stable-stringify.
Payload envelope
Every webhook uses the same outer structure:
interface IWebhookPayload {
event: string;
data: unknown;
}Retry schedule
If delivery fails, Manteca retries with exponential backoff. After 10 failed attempts the webhook is abandoned.
| Attempt | Delay after previous | Cumulative time |
|---|---|---|
| 1 (initial) | — | 0 min |
| 2 | 2 min | 2 min |
| 3 | 4 min | 6 min |
| 4 | 8 min | 14 min |
| 5 | 16 min | 30 min |
| 6 | 32 min | 62 min |
| 7 | 64 min | 126 min (~2.1 h) |
| 8 | 128 min | 254 min (~4.2 h) |
| 9 | 256 min | 510 min (~8.5 h) |
| 10 | 512 min | 1022 min (~17 h) — then abandoned |
A 401 response is treated as a non-recoverable error: the delivery is marked as failed immediately, without retries. Any other non-2xx response or timeout enters the retry schedule.
Design your endpoint to be idempotent. Retries deliver the same payload; processing it twice must not cause duplicate state.
System events
| Event | Payload type | Description |
|---|---|---|
ORDER_STATUS_UPDATE | IPrettyOrder | Order changed status |
WITHDRAW_STATUS_UPDATE | IPrettyWithdraw | Withdrawal changed status (also company crypto withdrawals) |
USER_ONBOARDING_UPDATE | IUserOnboardingUpdate | Onboarding task changed status |
USER_STATUS_UPDATE | (Deprecated) | Legacy user status — use USER_ONBOARDING_UPDATE |
USER_CRIPTO_STATUS_UPDATE | IPrettyUser | User changed crypto status (ONBOARDING/ACTIVE/INACTIVE) |
USER_WALLET_STATUS_UPDATE | IPrettyUser | User changed Virtual Accounts status (ONBOARDING/ACTIVE/INACTIVE) |
SYNTHETIC_STATUS_UPDATE | ISyntheticStatusUpdate | Synthetic operation changed status |
DEPOSIT_DETECTED | IPrettyDeposit | Deposit credited to the user (crypto or fiat) |
WIDGET_FINISHED | IWidgetFinished | Widget flow completed |
SYSTEM_NOTICE | ISystemNotice | Recoverable operational incident |
COMPLIANCE_NOTICE | IComplianceNotice | User compliance data changed |
PAYMENT_REFUND | IPrettyPaymentRefund | Payment refund generated |
VIRTUAL_ACCOUNT_STATUS_UPDATE | IPrettyChildAccount | Virtual account changed status (e.g. PENDING to ACTIVE) |
VIRTUAL_ACCOUNT_TRANSFER_STATUS | IPrettyTransfer | Virtual account deposit or withdrawal changed status |
VIRTUAL_ACCOUNT_TRANSFER_REVERTED | IPrettyTransferReverted | Virtual account transfer received a reversal, partial or total |
Payload examples
USER_ONBOARDING_UPDATE
{
"event": "USER_ONBOARDING_UPDATE",
"data": {
"user": {
"id": "64a1b2c3d4e5f6a7b8c9d0e1",
"numberId": "100009791",
"externalId": "client-ref-001",
"sessionId": "session-abc-123",
"email": "[email protected]",
"status": "ONBOARDING",
"type": "INDIVIDUAL",
"exchange": "ARGENTINA",
"banking": {
"accounts": [],
"addresses": []
},
"addresses": {
"depositAddresses": {},
"knownAddresses": []
},
"onboarding": {
"IDENTITY_DECLARATION": {
"required": true,
"status": "COMPLETED"
},
"BASIC_PERSONAL_DATA_DEFINITION": {
"required": true,
"status": "IN_PROGRESS"
},
"POLITICAL_CONSTRAINTS_VALIDATION": {
"required": true,
"status": "PENDING"
},
"SECURITY_VALIDATION": {
"required": true,
"status": "PENDING"
}
},
"creationTime": "2025-03-15T14:30:00.000Z",
"updatedAt": "2025-03-15T15:00:00.000Z"
},
"updatedTasks": ["IDENTITY_DECLARATION"]
}
}data.user contains the user's current state. The status field is one of three values: ONBOARDING, ACTIVE, or INACTIVE. Once the user completes all required onboarding tasks, status is set to ACTIVE.
When the last required task completes, the change to ACTIVE arrives in its own USER_ONBOARDING_UPDATE, sent shortly after that task's update, with the new data.user.status and an empty data.updatedTasks ([]). The last task's own update may still show status: "ONBOARDING". A later change to INACTIVE may arrive with updated tasks listed, or without any USER_ONBOARDING_UPDATE. To track ACTIVE and INACTIVE reliably, use USER_CRIPTO_STATUS_UPDATE / USER_WALLET_STATUS_UPDATE.
data.updatedTasks lists which onboarding tasks changed in this update; it is empty when the update only carries a status change. Possible task names:
| Task | Description |
|---|---|
EMAIL_VALIDATION | User confirmed email (retail only) |
IDENTITY_DECLARATION | User declared their legal ID |
BASIC_PERSONAL_DATA_DEFINITION | User submitted personal data |
TYC_ACCEPTANCE | User accepted terms and conditions |
POLITICAL_CONSTRAINTS_VALIDATION | PEP/FEP flag check completed |
SECURITY_VALIDATION | Terrorism/blacklist check completed |
BANK_ACCOUNT_DEFINITION | User added bank account information |
FEP_DOCUMENTATION_VALIDATION | Fiscally exposed person documentation uploaded |
PEP_DOCUMENTATION_VALIDATION | Politically exposed person documentation uploaded |
EXTERNAL_LIVENESS_VALIDATION | Liveness check completed by the user and verified |
IDENTITY_VALIDATION | Proof of identity uploaded (e.g. DNI) |
IDENTITY_VALIDATION_BUSINESS | Company legal documentation uploaded |
SELFIE_VALIDATION | Selfie verification uploaded |
Each task in data.user.onboarding has a status of PENDING, IN_PROGRESS, COMPLETED, FAILED, or EXPIRED, and a required flag indicating whether it blocks the user from operating. A rejectionReason field may be present when status is FAILED.
USER_CRIPTO_STATUS_UPDATE / USER_WALLET_STATUS_UPDATE
A per-product signal for the user's status change: USER_CRIPTO_STATUS_UPDATE for /crypto/v2, USER_WALLET_STATUS_UPDATE for Virtual Accounts (/wallet/v1). data is the user itself (not wrapped in user), with the same fields as USER_ONBOARDING_UPDATE's data.user; status is the user's status for that product.
{
"event": "USER_CRIPTO_STATUS_UPDATE",
"data": {
"id": "64a1b2c3d4e5f6a7b8c9d0e1",
"numberId": "100009791",
"externalId": "client-ref-001",
"sessionId": "session-abc-123",
"email": "[email protected]",
"status": "ACTIVE",
"type": "INDIVIDUAL",
"exchange": "ARGENTINA",
"banking": {
"accounts": [],
"addresses": []
},
"addresses": {
"depositAddresses": {},
"knownAddresses": []
},
"onboarding": {
"IDENTITY_DECLARATION": {
"required": true,
"status": "COMPLETED"
},
"BASIC_PERSONAL_DATA_DEFINITION": {
"required": true,
"status": "COMPLETED"
},
"POLITICAL_CONSTRAINTS_VALIDATION": {
"required": true,
"status": "COMPLETED"
},
"SECURITY_VALIDATION": {
"required": true,
"status": "COMPLETED"
}
},
"creationTime": "2025-03-15T14:30:00.000Z",
"updatedAt": "2025-03-15T15:12:40.000Z"
}
}SYNTHETIC_STATUS_UPDATE
{
"event": "SYNTHETIC_STATUS_UPDATE",
"data": {
"id": "687f839bc536d39525e68a6e",
"numberId": "5987",
"externalId": "ramp-ref-478",
"status": "COMPLETED",
"type": "RAMP_OPERATION",
"currentStage": 4,
"details": {
"depositAddress": "4310001343800000045110",
"depositAlias": "COMPANY.ARS",
"price": "1637.70",
"priceExpireAt": "2025-07-22T09:30:06.533-03:00",
"withdrawCostInAsset": "0.089815",
"withdrawCostInAgainst": "147.09",
"assetAmountOperated": "10.00000000",
"againstAmountOperated": "16403.5"
},
"userId": "685eba4842d304517432f6c5",
"userNumberId": "100009791",
"creationTime": "2025-07-22T09:27:07.506-03:00",
"updatedAt": "2025-07-22T09:33:19.701-03:00"
}
}data is the full IPrettySynthetic object. Key fields: status, type, currentStage, details (operation-specific metadata). Synthetics have no statusMessage: when status is CANCELLED, the reason is in the errors array of the stage that failed (stages[n].errors). For QR payments see QR Payments error handling, for withdrawals/ramps see Ramps error handling.
The
numberIdfield in webhook payloads can be used directly asuserAnyIdin any API endpoint. See Identity model and AnyId convention for details on how Manteca resolves different ID formats.
PAYMENT_REFUND
{
"event": "PAYMENT_REFUND",
"data": {
"refundId": "9b1c8e7a-2f4d-4a6b-8c3e-1d5f7a9b0c2d",
"amount": "5000.00",
"totalAmount": "10000.00",
"asset": "ARS",
"amountToRefund": "4.00",
"totalAmountToRefund": "8.00",
"assetToRefund": "USDT",
"paymentNumberId": "98765",
"paymentExternalId": "my-external-ref-001",
"networkId": "xxx-xxx-xxx-xxx",
"refundReason": "Refund",
"partial": true,
"refundedAt": "2026-02-21T15:35:00.000Z",
"userId": "64a1b2c3d4e5f6a7b8c9d0e2",
"userNumberId": "12345",
"userExternalId": "ext-001"
}
}data is the IPrettyPaymentRefund object. For full details on partial vs total refunds and accumulative fields, see QR Payments → After a payment.
ORDER_STATUS_UPDATE
{
"event": "ORDER_STATUS_UPDATE",
"data": {
"id": "6762f88e065d780e5d758045",
"numberId": "100020251",
"externalId": "example-external-id-1",
"sessionId": "example-session-id-1",
"userId": "6762f8c7767750522c90b55f",
"userNumberId": "100009352",
"userExternalId": "example-external-id-1",
"exchange": "ARGENTINA",
"status": "COMPLETED",
"type": "DIRECT",
"side": "SELL",
"asset": "USDT",
"against": "ARS",
"assetAmount": "10.00000000",
"filledAmount": "10.00000000",
"price": "1000.00",
"effectivePrice": "1001.15",
"referencePrices": {
"USDT_ARS": "1001.15"
},
"feeInfo": {
"platformFee": "0.001",
"companyProfit": "0.001",
"totalFee": "0.002"
},
"finalClaimInfo": {
"asset": "USDT",
"total": "10.00000000",
"base": "10.00000000",
"totalFees": "0.00",
"platformFee": "0.00",
"companyProfit": "0.00"
},
"finalCreditInfo": {
"asset": "ARS",
"total": "9980.00",
"base": "10000.00",
"totalFees": "20.00",
"platformFee": "10.00",
"companyProfit": "10.00"
},
"creationTime": "2024-12-13T12:22:54.290-03:00",
"updatedAt": "2024-12-13T12:22:54.290-03:00",
"legalEntity": "CRYPTO_ARG"
}
}data is the IPrettyOrder object. The status field is PENDING, COMPLETED (fully executed) or CANCELLED (reverted); see Order statuses. side is BUY or SELL relative to the asset.
WITHDRAW_STATUS_UPDATE
{
"event": "WITHDRAW_STATUS_UPDATE",
"data": {
"id": "64b2c3d4e5f6a7b8c9d0e1f2",
"numberId": "318",
"externalId": "withdraw-ref-00441",
"status": "EXECUTED",
"statusMessage": null,
"asset": "USDT",
"amount": "250.000000",
"destination": "0xABCDEF1234567890abcdef1234567890ABCDEF12",
"network": "POLYGON",
"networkId": "0xa1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2"
}
}This event is emitted for user withdrawals and also for company crypto withdrawals. statusMessage is populated when status is CANCELLED, providing a structured error code identifying the failure reason. A fiat withdrawal can reach CANCELLED after EXECUTED when the receiving bank returns the transfer; see Withdraw statuses. networkId is a network-level transaction identifier. For crypto, it is the on-chain transaction hash (can be used in a block explorer). For fiat, it is the banking network reference.
DEPOSIT_DETECTED
Sent once per deposit, when the deposit is already assigned to the user and credited to their balance. It covers crypto and fiat deposits alike, and the payload carries no status.
Crypto deposit:
{
"event": "DEPOSIT_DETECTED",
"data": {
"id": "64c3d4e5f6a7b8c9d0e1f2a3",
"numberId": "5507",
"externalId": "dep-ext-00992",
"userId": "6762f8c7767750522c90b55f",
"userNumberId": "100009352",
"userExternalId": "example-external-id-1",
"legalEntity": "CRYPTO_ARG",
"asset": "USDT",
"amount": "100.000000",
"source": "0x1234567890abcdef1234567890ABCDEF12345678",
"network": "BNB",
"networkId": "0x53f25b8bb53153e29539c8660670a72f1d869b457fb4f49ca313edafacd88a24"
}
}Fiat deposit:
{
"event": "DEPOSIT_DETECTED",
"data": {
"id": "64c3d4e5f6a7b8c9d0e1f2b4",
"numberId": "5508",
"userId": "6762f8c7767750522c90b55f",
"userNumberId": "100009352",
"userExternalId": "example-external-id-1",
"legalEntity": "CRYPTO_ARG",
"asset": "ARS",
"amount": "150000.00",
"network": "BANK_TRANSFER",
"networkId": "68f1c2d3e4a5b6c7d8e9f0a1"
}
}networkId identifies the transfer on its network. For crypto, it is the on-chain transaction hash (can be used in a block explorer). For fiat, it is Manteca's identifier for the incoming transfer. A fiat deposit has no source.
VIRTUAL_ACCOUNT_STATUS_UPDATE
{
"event": "VIRTUAL_ACCOUNT_STATUS_UPDATE",
"data": {
"address": "0000003100098765432100",
"alias": "COMPANY.USER.ARS",
"legalId": "20-12345678-9",
"platform": "WALLET",
"companyId": "64b2c3d4e5f6a7b8c9d0e1f2",
"status": "ACTIVE",
"externalId": "user-acc-001"
}
}This event fires when a virtual account changes status — most commonly when it moves from PENDING to ACTIVE after the bank confirms the account. Use this to know when the account is ready to receive deposits.
VIRTUAL_ACCOUNT_TRANSFER_STATUS
{
"event": "VIRTUAL_ACCOUNT_TRANSFER_STATUS",
"data": {
"id": "64c3d4e5f6a7b8c9d0e1f2a3",
"externalId": "dep-ext-00112",
"nationalId": "2026032600001234",
"type": "DEPOSIT",
"platform": "WALLET",
"from": "0140000003000012345678",
"fromLegalId": "20-87654321-0",
"to": "0000003100098765432100",
"toLegalId": "20-12345678-9",
"currency": "ARS",
"amount": "50000.00",
"filledAmount": "50000.00",
"status": "COMPLETED",
"concept": "VAR",
"companyId": "64b2c3d4e5f6a7b8c9d0e1f2",
"creationTime": "2026-03-26T14:30:00.000Z",
"updatedAt": "2026-03-26T14:30:05.000Z"
}
}This event fires when the status of a virtual-account transfer changes. A partial reversal does not change the status, so it is not reported here; it arrives as VIRTUAL_ACCOUNT_TRANSFER_REVERTED. Use data.type to distinguish deposits from withdrawals. platform is always WALLET.
Deposit paths are [PENDING] → COMPLETED, [PENDING] → CANCELLED, and [PENDING] → COMPLETED → CANCELLED; brackets indicate that PENDING is optional. CANCELLED before completion means rejection, while COMPLETED → CANCELLED confirms a manually requested return.
Withdrawal paths are PENDING → COMPLETED, PENDING → CANCELLED, and PENDING → COMPLETED → CANCELLED. A CANCELLED update before completion is a failure; one after completion is a reversal.
For both types, COMPLETED → CANCELLED means the whole amount came back. A partial reversal leaves the transfer in COMPLETED and lowers filledAmount by the reversed amount, with no status update; filledAmount reaches zero when the transfer becomes CANCELLED.
When a transfer is fully reverted (it was delivered, then all the funds came back), the payload carries the reversal fields:
{
"event": "VIRTUAL_ACCOUNT_TRANSFER_STATUS",
"data": {
"id": "64d4e5f6a7b8c9d0e1f2a3b4",
"externalId": "payout-ref-00441",
"nationalId": "E00000000202603261500ABCD1234WXYZ",
"reversalId": "c3d4e5f6-0000-4000-8000-000000000003",
"reversalNationalId": "D00000000202603261525IJKL9012WXYZ",
"type": "WITHDRAW",
"platform": "WALLET",
"from": "a1b2c3d4-0000-4000-8000-000000000001",
"fromLegalId": "12345678900",
"to": "e5f6a7b8-0000-4000-8000-000000000003",
"currency": "BRL",
"amount": "150.00",
"filledAmount": "0.00",
"status": "CANCELLED",
"genericErrorMessage": "E2: Transfer reverted",
"companyId": "64b2c3d4e5f6a7b8c9d0e1f2",
"creationTime": "2026-03-26T15:00:00.000Z",
"updatedAt": "2026-03-26T15:25:40.000Z"
}
}reversalId and reversalNationalId identify the reversal operation and its banking-network id. They always point to the latest reversal: after a partial one they are already present while the transfer is still COMPLETED, and on the final CANCELLED update they identify the reversal that completed the total, not the first one. The full list of reversals is in the VIRTUAL_ACCOUNT_TRANSFER_REVERTED events. See Sending funds → Track status for the full transfer field reference.
When a transfer becomes CANCELLED, the genericErrorMessage field carries a typed reason code. A reverted transfer (delivered, then returned) carries E2: Transfer reverted — distinct from a failed transfer (never delivered), which carries the failure's root cause, e.g. C3: Account number does not exist. The full code table is documented in Ramps error handling.
VIRTUAL_ACCOUNT_TRANSFER_REVERTED
{
"event": "VIRTUAL_ACCOUNT_TRANSFER_REVERTED",
"data": {
"reversalId": "b2c3d4e5-0000-4000-8000-000000000002",
"reversalNationalId": "D00000000202603261510EFGH5678WXYZ",
"transferId": "64d4e5f6a7b8c9d0e1f2a3b4",
"externalId": "payout-ref-00441",
"type": "WITHDRAW",
"currency": "BRL",
"amount": "50.00",
"filledAmount": "100.00",
"totalAmount": "50.00",
"partial": true,
"revertedAt": "2026-03-26T15:10:12.000-03:00"
}
}This event fires once per reversal a virtual-account transfer receives, partial or total. The example is the first reversal of the 150.00 BRL withdrawal shown above: 50.00 came back, 100.00 is still delivered, and the transfer stays COMPLETED, so no VIRTUAL_ACCOUNT_TRANSFER_STATUS is sent for it.
type tells you which side came back. WITHDRAW means a transfer you sent was returned to your account. DEPOSIT means a deposit you received was returned to its sender: either it was rejected before being credited (its last VIRTUAL_ACCOUNT_TRANSFER_STATUS was PENDING, for example by same-name enforcement), or it was returned after completing (its last status was COMPLETED).
| Field | Description |
|---|---|
reversalId | Unique id of this reversal. |
reversalNationalId | Banking-network id of this reversal, on the networks that assign one. On PIX it is the reversal's own end-to-end id, reported once the return is confirmed. Absent on networks that do not identify a return separately, so do not rely on it to match events. |
transferId | id of the reversed transfer. |
externalId | Your externalId on the reversed transfer, if you set one. |
type | Type of the reversed transfer: DEPOSIT or WITHDRAW. |
currency | Currency of the transfer. |
amount | Amount returned by this reversal. |
filledAmount | Amount of the transfer still delivered after this reversal. |
totalAmount | Amount of the transfer reversed so far, this reversal included. |
partial | true when this reversal returned less than the transfer's original amount. It does not tell you whether the transfer ended up fully reversed: read filledAmount for that. |
revertedAt | When the reversal was confirmed. |
filledAmount reaching "0.00" is what tells you the transfer is fully reversed, and that reversal also produces a VIRTUAL_ACCOUNT_TRANSFER_STATUS with status: CANCELLED. In the example, a second reversal of the remaining 100.00 BRL arrives with amount: "100.00", filledAmount: "0.00", totalAmount: "150.00" and partial: true, because those 100.00 are still less than the 150.00 the transfer was for. The CANCELLED update shown in the previous section arrives alongside it, carrying that second reversalId.
Deduplicate by transferId + reversalId. The same event may be delivered more than once, so treat that pair as your idempotency key and skip any event whose pair you have already processed. reversalId identifies a reversal within its own transfer, so scope it to the transferId instead of treating it as globally unique. Do not deduplicate by transferId or externalId alone either: a single transfer can receive several reversals over time and all of them share those two values, so deduping by them would drop legitimate partial reversals.
You receive one event per transfer of yours that is reversed. A transfer between two Manteca virtual accounts is two transfers, one on each side, and each one is reversed on its own: the sender is notified about its WITHDRAW and the recipient about its DEPOSIT, each event carrying its own transferId and its own reversalId, which do not have to match. If you own both accounts you receive both events for what is one movement, and they are not duplicates of each other: each one reports the reversal of a different transfer.
To track cumulative state per transfer, group reversals by transferId (or externalId) and rely on filledAmount / totalAmount rather than summing the per-event amount yourself. GET /wallet/v1/transfers/{transferAnyId} returns the same filledAmount, together with the reversalId of the latest reversal.
SYSTEM_NOTICE subtypes
SYSTEM_NOTICE carries an entityType, entity, type, and message. The type field identifies the incident:
| Type | Meaning |
|---|---|
FLAGGED_AS_RISKY | Crypto deposit held for compliance review |
NETWORK_CONGESTION | Temporary network issue during withdrawal processing |
WAITING_CONFIRMATIONS | Crypto deposit detected on-chain but has insufficient block confirmations |
SYNTHETIC_EXPIRED | Synthetic expired before a deposit was detected |
These events describe recoverable situations. Monitor them and surface relevant ones to your operations team.
FLAGGED_AS_RISKY
Notifies that a crypto deposit is on hold for compliance review, usually because screening flagged the address it was sent from. The funds are not credited to the user's balance while the deposit is under review, and no DEPOSIT_DETECTED is sent for it in the meantime. Use it to let your user know their deposit arrived but is being reviewed.
When it fires
- Once per crypto deposit, when the deposit reaches its required confirmations and is held for compliance review.
- If compliance clears the deposit, it is credited and you receive
DEPOSIT_DETECTEDas for any other deposit. - If compliance returns or discards the deposit instead, no
DEPOSIT_DETECTEDis sent; the outcome is reported throughDEPOSIT_STATUS_UPDATEwith statusCANCELLED. - Withdrawals do not produce this notice. A withdrawal to a flagged address is usually rejected when created, with
RISKY_WITHDRAW_ADDRESS(403); otherwise its status change is reported throughWITHDRAW_STATUS_UPDATE.
Example delivery
{
"event": "SYSTEM_NOTICE",
"data": {
"entityType": "DEPOSIT",
"entity": {
"id": "64c3d4e5f6a7b8c9d0e1f2a3",
"numberId": "5507",
"userId": "6762f8c7767750522c90b55f",
"userLegalId": "20300000003",
"userNumberId": "100009352",
"userExternalId": "example-external-id-1",
"legalEntity": "CRYPTO_ARG",
"asset": "USDT",
"amount": "100.000000",
"source": "0x1234567890abcdef1234567890ABCDEF12345678",
"network": "BNB",
"networkId": "0x53f25b8bb53153e29539c8660670a72f1d869b457fb4f49ca313edafacd88a24",
"creationTime": "2026-11-10T12:31:05.120-03:00",
"updatedAt": "2026-11-10T12:33:41.877-03:00"
},
"type": "FLAGGED_AS_RISKY",
"message": "The deposit is on hold until it is reviewed by compliance."
}
}entity has the same fields as the deposit in DEPOSIT_DETECTED. Match it to your records by id or networkId (the on-chain transaction hash).
COMPLIANCE_NOTICE subtypes
| Type | Meaning |
|---|---|
OPERATION_LIMIT_UPDATED | User's operational limit changed |
CLOSE_TO_OPERATION_LIMIT | User is approaching their operational limit |
USER_BLOCKED | User was blocked and cannot operate |
USER_UNBLOCKED | User's block was lifted |
CLOSE_TO_OPERATION_LIMIT
Notifies that a user is close to reaching their operational limit on one of the configured time windows (monthly or yearly). Useful to anticipate a block and warn the user before their next operation is rejected.
When it fires
- Evaluated after every operation that adds to the user's operated amount for the period (buys, sells, withdrawals, transfers).
- Fires when the operated amount reaches 90% of the limit (i.e. 10% or less remaining).
- Monthly and yearly windows are evaluated independently. If one operation crosses 90% on both at once, you receive two separate webhooks, one per window.
- Delivery is fire-and-forget from the Manteca backend: it does not block the operation that triggered it.
- The 90% threshold is fixed and not configurable per company.
How to subscribe
Enable the COMPLIANCE_NOTICE event in your company's webhook configuration. The webhook is delivered only to companies that have that event active in their subscription. The same channel also delivers the other COMPLIANCE_NOTICE subtypes (e.g. OPERATION_LIMIT_UPDATED), so your handler should route by the type field.
Payload
Every COMPLIANCE_NOTICE arrives in the standard payload envelope, with event: "COMPLIANCE_NOTICE". Fields of data:
| Field | Type | Description |
|---|---|---|
legalId | string | The affected user's legal ID (CUIT in Argentina, RUT in Chile, etc.). |
exchange | string | Vertical / country the notification applies to (e.g. ARGENTINA, CHILE). Optional: it may be absent in USER_BLOCKED and USER_UNBLOCKED when it cannot be resolved. |
type | string | Notification subtype. For this case always CLOSE_TO_OPERATION_LIMIT. |
message | string | Human-readable summary message. Meant for logging or internal display. |
payload | object | Details of the affected window (see table below). |
payload for CLOSE_TO_OPERATION_LIMIT:
| Field | Type | Description |
|---|---|---|
timeframe | "MONTH" | "YEAR" | Window crossed. MONTH for the monthly limit, YEAR for the yearly one. |
operatedAmount | string | Total amount operated by the user in that window, in the limit's base currency. |
limit | string | Total limit for the window, in the same currency. For this type, operatedAmount / limit ≥ 0.9 always holds. |
type | string | Limit the window belongs to: EXCHANGE for crypto operations, VIRTUAL_ACCOUNTS for virtual account transfers. |
Numeric values travel as
stringto avoid precision loss. Convert tonumberorBigDecimalon your side before comparing.
Example delivery
{
"event": "COMPLIANCE_NOTICE",
"data": {
"legalId": "20300000003",
"exchange": "ARGENTINA",
"type": "CLOSE_TO_OPERATION_LIMIT",
"message": "The user with CUIT 20300000003 has operated $5500 in the last month, approaching their monthly limit of $6000.",
"payload": {
"timeframe": "MONTH",
"operatedAmount": "5500",
"limit": "6000",
"type": "EXCHANGE"
}
}
}Notes
- The 90% threshold is fixed by Manteca and cannot be adjusted per company.
- Receiving this webhook does not block the user's operations. It is a preventive signal: the user can still operate until consuming 100% of the limit, at which point the next operation will return
OPERATION_BLOCKED(409). OPERATION_LIMIT_UPDATEDis a different subtype with its ownpayload, see OPERATION_LIMIT_UPDATED. Route bytypeto distinguish them.
OPERATION_LIMIT_UPDATED
Notifies that one of the user's operational limits changed. It fires after a reevaluation of the user's limits, after documentation that raises the limit is approved (proof of funds, identity document), or when Manteca changes the limit by hand.
Payload
data has the same fields as in CLOSE_TO_OPERATION_LIMIT, with type set to OPERATION_LIMIT_UPDATED. payload for OPERATION_LIMIT_UPDATED:
| Field | Type | Description |
|---|---|---|
updateReason | string | Why the limit changed, for example REEVALUATE, FUND_ORIGIN (proof of funds approved), ID_PICTURE (identity document approved) or MANUAL_LIMIT_CHANGE. Informational: other values can appear. |
limitAction | string | RAISE, LOWER or ZERO. |
newLimit | string | Amount of this change, in the limit's base currency. It is not always the resulting limit: read the current one with GET /crypto/v2/limits/{numberId}. |
timeframe | "MONTH" | "YEAR" | Window the change applies to. |
expirationTime | string | ISO 8601 date when the change stops applying. A change that does not expire carries the time the notice was generated. |
A change that applies to both windows arrives as two webhooks, one per timeframe.
Example delivery
{
"event": "COMPLIANCE_NOTICE",
"data": {
"legalId": "27300000008",
"exchange": "ARGENTINA",
"type": "OPERATION_LIMIT_UPDATED",
"message": "The operation limit for the user with CUIT 27300000008 has been updated.",
"payload": {
"updateReason": "FUND_ORIGIN",
"limitAction": "RAISE",
"expirationTime": "2027-04-22T00:00:00.000-03:00",
"newLimit": "5000000",
"timeframe": "YEAR"
}
}
}USER_BLOCKED
Notifies that a user was blocked and can no longer operate. A block can come from a match against sanction or PEP lists, a background check result, or a decision by the compliance team.
Example delivery
{
"event": "COMPLIANCE_NOTICE",
"data": {
"legalId": "20300000003",
"exchange": "ARGENTINA",
"type": "USER_BLOCKED",
"message": "The user with legal ID 20300000003 was blocked.",
"payload": {
"platform": "GENERAL",
"expirationDate": "2027-03-21T00:00:00.000Z"
}
}
}expirationDate is the ISO date on which the block runs out, or null for a permanent block.
platform tells you where the user stopped being able to operate:
| Platform | The user is blocked for |
|---|---|
GENERAL | Everything — no product is available to them |
CRIPTO | Crypto operations |
WALLET | Wallet operations, including virtual accounts |
QR | QR payments |
REMITTANCE | Remittances |
Notes
- A blocked user's operations are rejected until the block is lifted. Stop offering them the affected operations on your side as soon as this arrives.
- A user can accumulate blocks on more than one platform, each arriving as its own event.
USER_UNBLOCKED
Notifies that a block on one platform was lifted and the user can operate on it again. It fires when someone removes the block, once for each platform that was freed.
Example delivery
{
"event": "COMPLIANCE_NOTICE",
"data": {
"legalId": "20300000003",
"exchange": "ARGENTINA",
"type": "USER_UNBLOCKED",
"message": "The user with legal ID 20300000003 is no longer blocked on GENERAL.",
"payload": {
"platform": "GENERAL"
}
}
}platform describes the block that was lifted, with the same values as above.
Notes
- The state is per platform. A platform is reported only when no block that reaches it is left standing: receiving
USER_UNBLOCKEDforQRmeans the user can use QR again, while receiving it forGENERALdoes not mean there are no blocks left on another platform. - A user blocked on
GENERALis blocked everywhere, so lifting a more specific platform while aGENERALblock remains sends nothing. - The expiry of a temporary block does not guarantee a
USER_UNBLOCKED. Use theexpirationDatethat arrives inUSER_BLOCKEDto know when the block stops applying.
Updated about 20 hours ago