Sending funds

Sending funds

Initiate withdrawals from a virtual account to an external bank account. The balance is validated and debited before the transfer is submitted to the banking network.

Use POST /wallet/v1/transfers to request a transfer.


Verify the destination first (optional)

This step is optional but recommended. Before submitting a transfer, you can call GET /wallet/v1/address-info/{address} to resolve the destination address and confirm the recipient's identity. The response includes the recipient's name and a masked legal ID, so you can double-check you are sending funds to the expected person or company. You can skip this step and go straight to submitting the transfer if you already trust the destination.

curl -X GET "https://sandbox.manteca.dev/wallet/v1/address-info/0000003100098765432100?exchange=ARGENTINA" \
  -H "md-api-key: $MD_API_KEY"

Response (200 OK)

{
    "exchange": "ARGENTINA",
    "asset": "ARS",
    "destination": "perez.mp",
    "recipientName": "JUAN PEREZ",
    "recipientLegalId": "20********87",
    "accountType": "CVU"
}

Use this to display a confirmation screen to your users before triggering the withdrawal.


Submit the transfer

Call POST /wallet/v1/transfers to request the withdrawal. The request must include:

  • from — the source virtual account address
  • to — the destination bank account (CBU, CVU, alias, or equivalent)
  • currency — the fiat currency of the transfer
  • amount — the amount as a string (precision-safe)

comments and externalId are optional. Use externalId as your own idempotency key: a value already used returns 409 TRANSFER_EXISTS and creates nothing, so on a retry fetch the transfer by externalId instead.

Example request

curl -X POST https://sandbox.manteca.dev/wallet/v1/transfers \
  -H "md-api-key: $MD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "from": "0000003100098765432100",
      "to": "0140000003000012345678",
      "currency": "ARS",
      "amount": "15000.00",
      "comments": "Monthly payout",
      "externalId": "tx-ref-001"
  }'

Response (202 Accepted)

{
    "id": "64b2c3d4e5f6a7b8c9d0e1f2",
    "externalId": "tx-ref-001",
    "type": "WITHDRAW",
    "platform": "WALLET",
    "from": "0000003100098765432100",
    "to": "0140000003000012345678",
    "currency": "ARS",
    "amount": "15000.00",
    "status": "PENDING",
    "companyId": "64b2c3d4e5f6a7b8c9d0e1f2",
    "creationTime": "2026-03-26T14:30:00.000Z",
    "updatedAt": "2026-03-26T14:30:00.000Z"
}

The transfer will be rejected with a NO_FUNDS error if the account does not have sufficient balance.


QR payments

A virtual account can also pay a QR code through POST /wallet/v1/transfers. Supported countries:

CountryNetworkCurrency
BrazilPIXBRL

Send the QR code's EMV string as to. Before paying, verify it with GET /wallet/v1/address-info: send the EMV string as the address query parameter, URL-encoded. The response includes amount for a fixed-amount QR code and omits it for an open-amount one.

amount is required in both cases:

  • Fixed-amount QR code: amount must equal the QR code's amount. Any other value is rejected with PAYMENT_DESTINATION_AMOUNT_MISMATCH (400). The transfer is not created and no funds move.
  • Open-amount QR code: send the amount to pay, greater than zero.

GET /wallet/v1/address-info returns PAYMENT_DESTINATION_NOT_FOUND (409) for a QR code that was already paid or has expired. Do not retry with the same QR code; request a new one from the recipient.

Once accepted, a QR payment is tracked like any other transfer (see Track status). If the payment cannot be completed, the transfer ends CANCELLED, the debited amount goes back to the virtual account, and the payment is not retried. genericErrorMessage uses the same codes as a transfer to a PIX key; see the code table.


Transfer limits

Outbound transfers count against the user's monthly and yearly Virtual Accounts limits. Incoming deposits draw from the same allowance, and there is no daily window. A payout that exceeds a limit is not rejected at request time: it fails asynchronously with R3.

Use GET /wallet/v1/limits/{numberId} to check the user's available allowance before initiating a transfer. See Operational limits for the default values and how to raise them.


Track status

Transfer execution is asynchronous. Track the outcome with webhooks or polling:

MethodEndpoint
WebhookVIRTUAL_ACCOUNT_TRANSFER_STATUS with type: WITHDRAW
WebhookVIRTUAL_ACCOUNT_TRANSFER_REVERTED, one event per reversal, partial or total
PollGET /wallet/v1/transfers/{transferAnyId}
ListGET /wallet/v1/transfers

GET /wallet/v1/transfers/{transferAnyId} resolves by the transfer id and also by your externalId. The list endpoint has no externalId filter — an ?externalId= query parameter is silently ignored — so to look up a transfer by your own reference, use the get-by-id endpoint.

Withdrawals follow PENDING → COMPLETED on success and PENDING → CANCELLED on failure. A completed withdrawal can later be reversed by the network, in one or several steps. Each partial reversal lowers filledAmount and leaves the status at COMPLETED; the withdrawal becomes CANCELLED only once the full amount has come back. Every reversal, partial or total, is notified through VIRTUAL_ACCOUNT_TRANSFER_REVERTED. See Lifecycle and statuses for details.

Besides status, these transfer fields matter for reconciliation:

FieldDescription
nationalIdThe transfer's id on the banking network (the end-to-end id for PIX). Reconcile it against your bank statement.
filledAmountAmount still delivered to the recipient. It equals amount until a reversal is confirmed and drops by the reversed amount on each one. A COMPLETED transfer with filledAmount lower than amount has been partially reversed; a CANCELLED transfer has filledAmount at zero.
reversalIdId of the latest reversal. Present as soon as a reversal is confirmed, so it can appear on a transfer that is still COMPLETED after a partial one. When several reversals hit the same transfer, only the latest is kept here; the full list arrives through VIRTUAL_ACCOUNT_TRANSFER_REVERTED.
reversalNationalIdBanking-network id of the latest reversal (its own end-to-end id for PIX), so you can reconcile the return leg too.

Did this page help you?