Third-Party Operations

Third-Party Operations

By default, operations follow a same-name policy: deposits must be funded by the user themselves, and withdrawals must go to an account owned by the user. Operating with third parties (collecting funds from third-party payers or sending funds to third-party beneficiaries) is done under the Principal Accounts model, declaring the real payer (sender) and beneficiary (recipient) inline on each request. These flows require an additional compliance homologation process before being enabled on your account, and payouts are subject to outbound limits.


Collection from third parties

How your end-users fund a Ramp-on depends on the country's rail (see Coverage for the authoritative per-country list of rails and account types):

  • Static account countries (Chile, Mexico, Peru): the deposit account is permanent. Share it with your end-users; when a user sends funds, listen for the DEPOSIT_DETECTED webhook, and then create the Ramp-on synthetic with skipDeposit: true so it consumes the already-credited balance instead of waiting for a new deposit.
  • Dynamic QR countries (Bolivia, Brazil, Colombia, Guatemala): create the Ramp-on synthetic first: the generated QR comes back in details.depositAddresses. The end-user pays the QR and the synthetic continues automatically.
  • Argentina (dynamic by default): Ramp-on normally generates a unique payment method per operation. By default this is a payment QR; if the payer prefers a bank transfer, send preferDepositAddress: true to receive a dedicated per-operation account (CVU) instead.

If a specific deposit route has been configured for your principal user or company with a label, send enforceDepositAddressLabel on the synthetic request. This filters eligible accounts without changing those network defaults. A matching static address is retained if deposit-request generation returns no instructions. See Select a deposit account by label before using this mode.

For funding instructions and deposit tracking details, see Ramp-on: Receive funds.


Payouts to third parties

To send funds to a third-party beneficiary, include sender and recipient as described below.

Recipient field

Use recipient to declare the third-party beneficiary. The recipient object is validated against the country's identity rules.

{
  "recipient": {
    "legalIdNationality": "COLOMBIA",
    "legalId": "1234567890",
    "name": "JUAN",
    "surname": "PEREZ",
    "legalIdType": "NATIONAL_ID"
  }
}

The recipient's country (recipient.legalIdNationality) defines which legal ID validation rules apply. It accepts the full country name or country codes (ISO-2 or ISO-3). The same field is used on the sender object. The destination is cross-checked against recipient identity to confirm the declared beneficiary is coherent with the Ramp-off destination.


Auto-resolved recipient fields

For these three destinations the recipient's name and legalId are auto-completed from the destination address, so you can omit them and only send recipient.legalIdNationality:

ExchangeNetworkAccepted destinations
ARGENTINABANK_TRANSFERCBU, CVU, alias
BRAZILPIXPIX key (email, CPF/CNPJ, phone, random UUID)
COLOMBIABREBBRE-B key (email, phone, document, random UUID)

For every other destination (MEXICO / SPEI, PERU / YAPE · PLIN · BANK_TRANSFER, CHILE, etc.), legalId, name and surname remain required. If you do provide them for auto-resolvable destinations, your values are honored and no lookup is performed.

To preview the resolved recipient before submitting, see Preview a destination.


Request examples

Argentina (auto-resolved recipient)

The destination is a CBU on BANK_TRANSFER, which is enrichable: legalId, name and surname are auto-completed from the destination address. Only recipient.legalIdNationality is required.

{
  "asset": "ARS",
  "amount": "50000",
  "destination": {
    "address": "0000003100010000000001",
    "network": "BANK_TRANSFER"
  },
  "sender": {
    "legalIdNationality": "BRAZIL",
    "legalId": "12345678909",
    "name": "JANE",
    "surname": "DOE"
  },
  "recipient": {
    "legalIdNationality": "ARGENTINA"
  }
}

Peru (full recipient)

PERU + BANK_TRANSFER is not auto-resolvable: you must provide the recipient's full identity.

{
  "asset": "PEN",
  "amount": "100",
  "destination": {
    "address": "00211500011234567890",
    "network": "BANK_TRANSFER",
    "accountType": "SAVINGS",
    "bankCode": "002"
  },
  "sender": {
    "legalIdNationality": "ARGENTINA",
    "legalId": "20100000009",
    "name": "JANE",
    "surname": "DOE"
  },
  "recipient": {
    "legalIdNationality": "PERU",
    "legalId": "12345678",
    "legalIdType": "NATIONAL_ID",
    "name": "JUAN",
    "surname": "PEREZ"
  }
}

Outbound limits

Payouts declaring a third-party recipient consume the sender's REMITTANCE limit, in USDT, which has a daily window on top of the monthly and yearly ones. Declaring only a sender does not make a payout a remittance. Your end-users have no Manteca numberId, so check the available allowance by legal ID with GET /crypto/v2/limits before submitting:

curl -X GET "https://sandbox.manteca.dev/crypto/v2/limits?legalIdNationality=BRA&legalId=12345678909" \
  -H "md-api-key: YOUR_MD_API_KEY"

The response is an array with one entry per limit type. The REMITTANCE entry is the one that governs third-party payouts:

[
  {
    "exchangeCountry": "BRA",
    "type": "REMITTANCE",
    "asset": "USDT",
    "yearlyLimit": "40000",
    "availableYearlyLimit": "38800",
    "monthlyLimit": "10000",
    "availableMonthlyLimit": "9350",
    "dailyLimit": "2500",
    "availableDailyLimit": "1850"
  }
]

The available* fields reflect remaining capacity after prior operations. dailyLimit and availableDailyLimit are returned for REMITTANCE only: a rolling 24h window, not a calendar day. Exceeding any of the three windows returns BLOCKED_UIF (400).

The limit is consumed only once the payout is executed, so two payouts submitted close together can both pass validation and still leave the second one blocked. See Ramps Operational Limits for thresholds per region.


Did this page help you?