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
senderand the beneficiary inrecipient. - Funds: the balance of your principal account, debited when the payout is created.
- Tracking:
WITHDRAW_STATUS_UPDATEwebhooks, or pollGET /crypto/v2/withdraws/{withdrawAnyId}.
How it works
- Manteca onboards your company once as a principal account, with a fixed
userAnyId. - You fund the principal account balance in the asset you pay out.
- For each payout, you optionally preview the destination to confirm who owns it.
- You create a withdraw from the principal account with
destination,senderandrecipient. - You track it until
EXECUTEDorCANCELLED, 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
userAnyIdand 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).
Declare the sender and the recipient
Both objects have the same shape:
| Field | Required | Notes |
|---|---|---|
legalIdNationality | Yes | Country that issued the document. Full name (ARGENTINA) or ISO-2/ISO-3 code. |
legalId | Yes | Document number, validated with that country's rules. |
name | Yes | First name, or company name. |
surname | No | Last name. |
legalIdType | No | NATIONAL_ID, FOREIGN_ID, PPT or TAX_ID. Only relevant for Colombia, where it defaults to NATIONAL_ID. |
senderis the real payer, your end-user. It is sent for compliance only.recipientis the beneficiary. ItslegalIdNationalitymust be the country of the payout asset (for exampleARGENTINAfor ARS).- For Argentina (
BANK_TRANSFER: CBU, CVU or alias), Brazil (PIX) and Colombia (BREB), the recipient'slegalIdandnameare filled in from the destination, so you can send onlyrecipient.legalIdNationality. Everywhere else, send the full recipient.
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.
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"
}
}{
"externalId": "payout-0002",
"userAnyId": "100009352",
"asset": "BRL",
"amount": "1000",
"destination": {
"address": "[email protected]",
"network": "PIX"
},
"sender": {
"legalIdNationality": "ARGENTINA",
"legalId": "20300000003",
"name": "JUAN",
"surname": "PEREZ"
},
"recipient": {
"legalIdNationality": "BRAZIL"
}
}{
"externalId": "payout-0003",
"userAnyId": "100009352",
"asset": "PEN",
"amount": "100",
"destination": {
"address": "00211500011234567890",
"network": "BANK_TRANSFER",
"accountType": "SAVINGS",
"bankCode": "002"
},
"sender": {
"legalIdNationality": "ARGENTINA",
"legalId": "20300000003",
"name": "JUAN",
"surname": "PEREZ"
},
"recipient": {
"legalIdNationality": "PERU",
"legalId": "12345678",
"name": "JOHN",
"surname": "DOE"
}
}{
"externalId": "payout-0004",
"userAnyId": "100009352",
"asset": "COP",
"amount": "500000",
"destination": {
"address": "12345678901",
"network": "BANK_TRANSFER",
"accountType": "SAVINGS",
"bankCode": "1007"
},
"sender": {
"legalIdNationality": "BRAZIL",
"legalId": "12345678909",
"name": "JOHN",
"surname": "DOE"
},
"recipient": {
"legalIdNationality": "COLOMBIA",
"legalId": "1234567890",
"name": "JUAN",
"surname": "PEREZ"
}
}In Colombia destination.network is required. For a BRE-B key, send { "address": "@johndoe", "network": "BREB" } with no accountType or bankCode, and only recipient.legalIdNationality. For a mobile wallet, send the phone with its prefix (+573001234567) as address on BANK_TRANSFER: accountType is set to PHONE and no bankCode is needed.
{
"externalId": "payout-0005",
"userAnyId": "100009352",
"asset": "CLP",
"amount": "100000",
"destination": {
"address": "12345678901",
"network": "BANK_TRANSFER",
"accountType": "VISTA",
"bankCode": "318"
},
"sender": {
"legalIdNationality": "BRAZIL",
"legalId": "12345678909",
"name": "JOHN",
"surname": "DOE"
},
"recipient": {
"legalIdNationality": "CHILE",
"legalId": "12345678-5",
"name": "JUAN",
"surname": "PEREZ"
}
}{
"externalId": "payout-0006",
"userAnyId": "100009352",
"asset": "MXN",
"amount": "10000",
"destination": {
"address": "012180001234567897",
"network": "SPEI",
"accountType": "CHECKING",
"bankCode": "012"
},
"sender": {
"legalIdNationality": "BRAZIL",
"legalId": "12345678909",
"name": "JOHN",
"surname": "DOE"
},
"recipient": {
"legalIdNationality": "MEXICO",
"legalId": "XAXX010101000",
"name": "JUAN",
"surname": "PEREZ"
}
}A CLABE (18 digits) needs accountType and bankCode. With a debit card or phone number as address, accountType is set for you and bankCode is still required.
userAnyIdis your principal account and is required.externalIdis your own ID for the payout. Reusing it returns409 WITHDRAW_EXISTSand 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.networkis set from the asset in every country except Colombia, where you chooseBANK_TRANSFERorBREB.accountTypeandbankCodedepend on the country. See Before the payment for the fields per country, Supported account types foraccountTypevalues, 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.
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.
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"
}
}| Status | What it means | What to do |
|---|---|---|
PENDING | Created, funds debited, sent to the bank. Network errors are retried automatically. | Wait. |
EXECUTED | The transfer was completed. networkId is the bank reference. | Mark as paid, but keep listening. |
CANCELLED | The 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,
EXECUTEDis not final. If the receiving bank returns the whole transfer, the payout moves fromEXECUTEDtoCANCELLEDand the amount is credited back. If it returns only part, the payout staysEXECUTED,filledAmountdrops by the returned amount, and no webhook is sent for that change.
Reconcile
All payouts run on the principal account, so reconciliation happens at that level:
| What | Endpoint |
|---|---|
| List payouts by status and date | GET /crypto/v2/withdraws |
| Current balance | GET /crypto/v2/user-balances/USERANYID |
| Every debit and credit, with the operation behind it | GET /crypto/v2/stats/balance-activities |
| Closing balance snapshots | GET /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
- Onboarding models: how the Principal Accounts model works.
- Third-party operations: auto-resolved recipients and outbound limits.
- Before the payment: destination fields per country.
- Operation lifecycle statuses: full withdraw state machine.
- Ramps operational limits
- Reconciliation and reporting
Updated 1 day ago