Integrate third-party payouts

Send fiat from your principal account to bank accounts that belong to third parties, declaring the real payer and beneficiary on each request.

At a glance

  • Users: Principal Accounts model. Your end-users are not onboarded in Manteca: each request carries the real payer in sender and the beneficiary in recipient.
  • Funds: the balance of your principal account, debited when the payout is created.
  • Tracking: WITHDRAW_STATUS_UPDATE webhooks, or poll GET /crypto/v2/withdraws/{withdrawAnyId}.

How it works

  1. Manteca onboards your company once as a principal account, with a fixed userAnyId.
  2. You fund the principal account balance in the asset you pay out.
  3. For each payout, you optionally preview the destination to confirm who owns it.
  4. You create a withdraw from the principal account with destination, sender and recipient.
  5. You track it until EXECUTED or CANCELLED, and reconcile against the principal account's balance movements.

Before you start

  • Principal Accounts and third-party payouts need a compliance homologation, enabled per destination country. Ask your account manager for your principal account userAnyId and the countries enabled for you.
  • The principal account must hold the payout asset. See Funding your account.
  • Configure the webhook with PATCH /crypto/v2/company:
{
  "notificationInfo": {
    "type": "WEBHOOK",
    "secret": "your-webhook-secret",
    "webhooks": {
      "WITHDRAW_STATUS_UPDATE": "https://your-domain.example.com/webhooks/manteca",
      "SYSTEM_NOTICE": "https://your-domain.example.com/webhooks/manteca"
    }
  }
}

Webhooks are sent from four fixed IP addresses: allowlist all of them (see Webhooks).

1

Declare the sender and the recipient

Both objects have the same shape:

FieldRequiredNotes
legalIdNationalityYesCountry that issued the document. Full name (ARGENTINA) or ISO-2/ISO-3 code.
legalIdYesDocument number, validated with that country's rules.
nameYesFirst name, or company name.
surnameNoLast name.
legalIdTypeNoNATIONAL_ID, FOREIGN_ID, PPT or TAX_ID. Only relevant for Colombia, where it defaults to NATIONAL_ID.
  • sender is the real payer, your end-user. It is sent for compliance only.
  • recipient is the beneficiary. Its legalIdNationality must be the country of the payout asset (for example ARGENTINA for ARS).
  • For Argentina (BANK_TRANSFER: CBU, CVU or alias), Brazil (PIX) and Colombia (BREB), the recipient's legalId and name are filled in from the destination, so you can send only recipient.legalIdNationality. Everywhere else, send the full recipient.
2

Preview the destination (optional)

For Argentina, Brazil and Colombia (BRE-B), check who owns the destination before you send. Show the result to your user to confirm the beneficiary.

Request GET /crypto/v2/info/withdraw-destination/{destination}

GET /crypto/v2/info/withdraw-destination/0000000000000000000000

Add ?country=ARGENTINA (or BRAZIL, COLOMBIA) when a value could match more than one country. URL-encode emails and other keys.

Response

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

A 400 WITHDRAW_DESTINATION means the withdraw to that destination would also fail. Do not submit it.

3

Create the payout

Request POST /crypto/v2/withdraws

{
  "externalId": "payout-0001",
  "userAnyId": "100009352",
  "asset": "ARS",
  "amount": "50000",
  "destination": {
    "address": "0000000000000000000000",
    "network": "BANK_TRANSFER"
  },
  "sender": {
    "legalIdNationality": "BRAZIL",
    "legalId": "12345678909",
    "name": "JOHN",
    "surname": "DOE"
  },
  "recipient": {
    "legalIdNationality": "ARGENTINA"
  }
}
  • userAnyId is your principal account and is required.
  • externalId is your own ID for the payout. Reusing it returns 409 WITHDRAW_EXISTS and creates nothing, so retries are safe.
  • Every payout country, its network and execution time (instant or batch): Coverage. Only the countries enabled for your principal account accept payouts.
  • destination.network is set from the asset in every country except Colombia, where you choose BANK_TRANSFER or BREB. accountType and bankCode depend on the country. See Before the payment for the fields per country, Supported account types for accountType values, and Supported banks for bank codes.

Response (trimmed)

{
  "id": "695c7c9263f8f5a0fb931f00",
  "numberId": "100022740",
  "externalId": "payout-0001",
  "userNumberId": "100009352",
  "status": "PENDING",
  "asset": "ARS",
  "amount": "50000",
  "filledAmount": "50000",
  "destination": "0000000000000000000000",
  "network": "BANK_TRANSFER",
  "recipient": {
    "exchange": "ARGENTINA",
    "legalId": "20300000003",
    "name": "JUAN",
    "surname": "PEREZ"
  },
  "creationTime": "2026-01-06T00:08:02.502-03:00"
}

The amount is debited from the principal account when the payout is created. The response and the webhooks return recipient (with the resolved data) and sender, with the country in exchange.

4

Check the sender's limit

Payouts with a third-party recipient consume the sender's REMITTANCE limit, in USDT, with daily (rolling 24 hours), monthly and yearly windows. Since your end-users have no Manteca numberId, query by legal ID with GET /crypto/v2/limits:

GET /crypto/v2/limits?legalIdNationality=ARG&legalId=20300000003
[
  {
    "exchangeCountry": "ARG",
    "type": "REMITTANCE",
    "asset": "USDT",
    "yearlyLimit": "40000",
    "availableYearlyLimit": "38800",
    "monthlyLimit": "10000",
    "availableMonthlyLimit": "9350",
    "dailyLimit": "2500",
    "availableDailyLimit": "1850"
  }
]

A payout that exceeds any window is rejected with 400 BLOCKED_UIF. The limit is consumed when the payout executes, so two payouts sent close together can both pass the check and the second one can still be blocked.

5

Track the operation

Each status change sends a WITHDRAW_STATUS_UPDATE. The payload data is the same object that GET /crypto/v2/withdraws/{withdrawAnyId} returns.

{
  "event": "WITHDRAW_STATUS_UPDATE",
  "data": {
    "id": "695c7c9263f8f5a0fb931f00",
    "externalId": "payout-0001",
    "status": "CANCELLED",
    "statusMessage": "C3: Account number does not exist",
    "asset": "ARS",
    "amount": "50000",
    "destination": "0000000000000000000000",
    "network": "BANK_TRANSFER",
    "networkId": "AJ28AK192810218LPMN"
  }
}
StatusWhat it meansWhat to do
PENDINGCreated, funds debited, sent to the bank. Network errors are retried automatically.Wait.
EXECUTEDThe transfer was completed. networkId is the bank reference.Mark as paid, but keep listening.
CANCELLEDThe transfer failed or was returned. The full amount goes back to the principal account balance.Read statusMessage (match the code before the colon) and decide whether to retry with a new externalId.

For fiat, EXECUTED is not final. If the receiving bank returns the whole transfer, the payout moves from EXECUTED to CANCELLED and the amount is credited back. If it returns only part, the payout stays EXECUTED, filledAmount drops by the returned amount, and no webhook is sent for that change.

6

Reconcile

All payouts run on the principal account, so reconciliation happens at that level:

WhatEndpoint
List payouts by status and dateGET /crypto/v2/withdraws
Current balanceGET /crypto/v2/user-balances/USERANYID
Every debit and credit, with the operation behind itGET /crypto/v2/stats/balance-activities
Closing balance snapshotsGET /crypto/v2/stats/balance-snapshots

Partial bank returns only show up here (as a credit and a lower filledAmount), so reconcile balance activities, not just webhooks.

Errors

Every error body carries an internalStatus to branch on and a readable message. See Ramps error handling for the full list and the statusMessage codes.

Go deeper


Did this page help you?