Raise limits

Raise limits

Raise limits is the operational path used when a Virtual Account transfer is blocked by the identity's current VIRTUAL_ACCOUNTS allowance.

Limits are per-person (per numberId), and each user's allowance is independent of the other users on your platform. There are two windows, monthly and yearly (Virtual Accounts has no daily window), and both directions draw from them: deposits and payouts consume the same pool. See Operational Limits for the full model.


Check current limits

Before initiating a raise, retrieve the user's current limit state:

GET /wallet/v1/limits/{numberId}

Response includes available limits by type and asset:

[
  {
    "exchangeCountry": "BRA",
    "type": "VIRTUAL_ACCOUNTS",
    "asset": "USDT",
    "monthlyLimit": "10000.00000000",
    "availableMonthlyLimit": "850.00000000",
    "yearlyLimit": "120000.00000000",
    "availableYearlyLimit": "112400.00000000"
  }
]

The response is an array and always carries the VIRTUAL_ACCOUNTS record: that is the only limit type this endpoint returns for Virtual Accounts. There are no dailyLimit / availableDailyLimit fields.

Monitor availableMonthlyLimit and availableYearlyLimit. When either approaches zero, prompt the user to initiate a raise before the next transfer is blocked.


COMPLIANCE_NOTICE webhook

Manteca fires a COMPLIANCE_NOTICE webhook when a user's available limit drops to 10% or less of the period limit. Use this signal to proactively surface the raise flow in your UX, before the user hits a hard block on the next transfer.


Practical sequence

  1. Detect the block. Enforcement is asynchronous: an outgoing payout over the limit is accepted at request time and later moves to FAILED carrying R3: Exceeds virtual account limits, and an incoming deposit over the limit is returned to the sender instead of being credited.
  2. Collect required supporting evidence.
  3. Upload the fund-origin documentation (see below).
  4. Wait for updated eligibility state.
  5. Retry transfer with the same traceability identifiers (e.g. externalId).

Additional fund origin documentation may be required during the review process depending on the amount and jurisdiction.


Submit fund-origin documentation

Upload proof of fund origin so the compliance team can review it and raise the user's VIRTUAL_ACCOUNTS limit. The review raises the monthly window; the yearly one is twelve times the monthly, so the monthly is always what a user hits first. Each document is uploaded in two steps: request a short-lived pre-signed URL, then PUT the file straight to it.

What counts as proof of fund origin

The document has to evidence where the user's money comes from, carry their name, and state an amount and the period it covers: their last three payslips, their most recent income tax return, a statement of income signed by a certified accountant, or evidence of a specific inflow such as the sale of a property or securities. An identity document, a bank statement, or a certificate of tax registration is not enough on its own: it identifies the person without evidencing income.

Send one file per upload. If the evidence spans several documents, merge them into a single file first. A partial upload is rejected. Local equivalents of the documents above are accepted; ask your integration contact if you are unsure whether a specific one qualifies.

Step 1: Get the upload URL

Call POST /wallet/v1/documentation-actions/get-upload-url with docType: "FUNDS". The response returns a pre-signed url.

curl -X POST https://sandbox.manteca.dev/wallet/v1/documentation-actions/get-upload-url \
  -H "md-api-key: $MD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "associatedSubId": "100037043",
      "docType": "FUNDS",
      "fileName": "proof-of-funds.pdf",
      "extension": "pdf"
  }'
{ "url": "https://manteca-documentation.s3.amazonaws.com/upload-target" }

Step 2: Upload the file to the signed URL

PUT the raw file binary directly to the url from Step 1. Do not include the md-api-key header: this request goes straight to the storage URL. Set Content-Type to match the file format.

curl -X PUT 'SIGNED_URL_FROM_STEP_1' \
  -H "Content-Type: application/pdf" \
  --data-binary '@/path/to/proof-of-funds.pdf'
🚧

The signed URL expires in 90 seconds, so upload immediately after requesting it.

The document is reviewed asynchronously. You can check its status with GET /wallet/v1/documentations/{documentationAnyId} (valid: true once approved). When the compliance team raises the limit, a COMPLIANCE_NOTICE webhook fires with OPERATION_LIMIT_UPDATED.


Encrypted document uploads (OpenPGP)

Documents can optionally be uploaded encrypted with OpenPGP. Encrypt the file with Manteca's public key (request it from your integration contact) before uploading.

Naming convention: keep the original extension and append .pgp (or .gpg), e.g. document.jpg.pgp. A bare document.pgp is also accepted: the actual format is auto-detected after decryption. The decrypted content must be one of the supported document formats (jpg, jpeg, jfif, png, webp, gif, bmp, pdf, heic, heif, tif, tiff).

gpg --encrypt --recipient <manteca-key-id> document.jpg
# produces document.jpg.gpg

Upload works exactly like a regular upload: request the upload URL with the encrypted file's name (e.g. fileName: "document.jpg.pgp") as in Step 1, then PUT the encrypted binary to the signed URL within its validity window, same as Step 2.

The file is decrypted automatically on arrival. If decryption fails, or the decrypted content isn't a supported document format, the document is not created. Each file is encrypted with a one-time session key under the OpenPGP standard.


Good practices

  • Persist original transfer payload and rejection context.
  • Keep client UX explicit while review is pending.
  • Do not retry automatically until updated state is confirmed.
  • Use GET /wallet/v1/limits/{numberId} to poll for limit state changes.

Related pages


Did this page help you?