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.94
  • 15.229.180.233
  • 177.71.146.43
  • 18.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 POST requests
  • Return a 2xx status 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.

AttemptDelay after previousCumulative time
1 (initial)—0 min
22 min2 min
34 min6 min
48 min14 min
516 min30 min
632 min62 min
764 min126 min (~2.1 h)
8128 min254 min (~4.2 h)
9256 min510 min (~8.5 h)
10512 min1022 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

EventPayload typeDescription
ORDER_STATUS_UPDATEIPrettyOrderOrder changed status
WITHDRAW_STATUS_UPDATEIPrettyWithdrawWithdrawal changed status (also company crypto withdrawals)
USER_ONBOARDING_UPDATEIUserOnboardingUpdateOnboarding task changed status
USER_STATUS_UPDATE(Deprecated)Legacy user status — use USER_ONBOARDING_UPDATE
USER_CRIPTO_STATUS_UPDATEIPrettyUserUser changed crypto status (ONBOARDING/ACTIVE/INACTIVE)
USER_WALLET_STATUS_UPDATEIPrettyUserUser changed Virtual Accounts status (ONBOARDING/ACTIVE/INACTIVE)
SYNTHETIC_STATUS_UPDATEISyntheticStatusUpdateSynthetic operation changed status
DEPOSIT_DETECTEDIPrettyDepositDeposit credited to the user (crypto or fiat)
WIDGET_FINISHEDIWidgetFinishedWidget flow completed
SYSTEM_NOTICEISystemNoticeRecoverable operational incident
COMPLIANCE_NOTICEIComplianceNoticeUser compliance data changed
PAYMENT_REFUNDIPrettyPaymentRefundPayment refund generated
VIRTUAL_ACCOUNT_STATUS_UPDATEIPrettyChildAccountVirtual account changed status (e.g. PENDING to ACTIVE)
VIRTUAL_ACCOUNT_TRANSFER_STATUSIPrettyTransferVirtual account deposit or withdrawal changed status
VIRTUAL_ACCOUNT_TRANSFER_REVERTEDIPrettyTransferRevertedVirtual 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:

TaskDescription
EMAIL_VALIDATIONUser confirmed email (retail only)
IDENTITY_DECLARATIONUser declared their legal ID
BASIC_PERSONAL_DATA_DEFINITIONUser submitted personal data
TYC_ACCEPTANCEUser accepted terms and conditions
POLITICAL_CONSTRAINTS_VALIDATIONPEP/FEP flag check completed
SECURITY_VALIDATIONTerrorism/blacklist check completed
BANK_ACCOUNT_DEFINITIONUser added bank account information
FEP_DOCUMENTATION_VALIDATIONFiscally exposed person documentation uploaded
PEP_DOCUMENTATION_VALIDATIONPolitically exposed person documentation uploaded
EXTERNAL_LIVENESS_VALIDATIONLiveness check completed by the user and verified
IDENTITY_VALIDATIONProof of identity uploaded (e.g. DNI)
IDENTITY_VALIDATION_BUSINESSCompany legal documentation uploaded
SELFIE_VALIDATIONSelfie 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 numberId field in webhook payloads can be used directly as userAnyId in 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).

FieldDescription
reversalIdUnique id of this reversal.
reversalNationalIdBanking-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.
transferIdid of the reversed transfer.
externalIdYour externalId on the reversed transfer, if you set one.
typeType of the reversed transfer: DEPOSIT or WITHDRAW.
currencyCurrency of the transfer.
amountAmount returned by this reversal.
filledAmountAmount of the transfer still delivered after this reversal.
totalAmountAmount of the transfer reversed so far, this reversal included.
partialtrue 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.
revertedAtWhen 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:

TypeMeaning
FLAGGED_AS_RISKYCrypto deposit held for compliance review
NETWORK_CONGESTIONTemporary network issue during withdrawal processing
WAITING_CONFIRMATIONSCrypto deposit detected on-chain but has insufficient block confirmations
SYNTHETIC_EXPIREDSynthetic 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_DETECTED as for any other deposit.
  • If compliance returns or discards the deposit instead, no DEPOSIT_DETECTED is sent; the outcome is reported through DEPOSIT_STATUS_UPDATE with status CANCELLED.
  • 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 through WITHDRAW_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

TypeMeaning
OPERATION_LIMIT_UPDATEDUser's operational limit changed
CLOSE_TO_OPERATION_LIMITUser is approaching their operational limit
USER_BLOCKEDUser was blocked and cannot operate
USER_UNBLOCKEDUser'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:

FieldTypeDescription
legalIdstringThe affected user's legal ID (CUIT in Argentina, RUT in Chile, etc.).
exchangestringVertical / 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.
typestringNotification subtype. For this case always CLOSE_TO_OPERATION_LIMIT.
messagestringHuman-readable summary message. Meant for logging or internal display.
payloadobjectDetails of the affected window (see table below).

payload for CLOSE_TO_OPERATION_LIMIT:

FieldTypeDescription
timeframe"MONTH" | "YEAR"Window crossed. MONTH for the monthly limit, YEAR for the yearly one.
operatedAmountstringTotal amount operated by the user in that window, in the limit's base currency.
limitstringTotal limit for the window, in the same currency. For this type, operatedAmount / limit ≥ 0.9 always holds.
typestringLimit the window belongs to: EXCHANGE for crypto operations, VIRTUAL_ACCOUNTS for virtual account transfers.

Numeric values travel as string to avoid precision loss. Convert to number or BigDecimal on 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_UPDATED is a different subtype with its own payload, see OPERATION_LIMIT_UPDATED. Route by type to 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:

FieldTypeDescription
updateReasonstringWhy 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.
limitActionstringRAISE, LOWER or ZERO.
newLimitstringAmount 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.
expirationTimestringISO 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:

PlatformThe user is blocked for
GENERALEverything — no product is available to them
CRIPTOCrypto operations
WALLETWallet operations, including virtual accounts
QRQR payments
REMITTANCERemittances

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_UNBLOCKED for QR means the user can use QR again, while receiving it for GENERAL does not mean there are no blocks left on another platform.
  • A user blocked on GENERAL is blocked everywhere, so lifting a more specific platform while a GENERAL block remains sends nothing.
  • The expiry of a temporary block does not guarantee a USER_UNBLOCKED. Use the expirationDate that arrives in USER_BLOCKED to know when the block stops applying.

Did this page help you?