Listar y Crear Retiros

GET /withdrawCopy Anchor Link

Retorna la lista paginada de retiros del usuario autenticado, ordenados del más reciente al más antiguo.

AutenticaciónCopy Anchor Link

Bearer Token (Authorization: Bearer {token}).

Query parametersCopy Anchor Link

RequestCopy Anchor Link

curl -X GET "https://api.qvapay.com/withdraw?page=1&take=20&status=paid&include_total=true" \
  -H "Authorization: Bearer {tu-token}"

ResponseCopy Anchor Link

{
  "result": "OK",
  "data": [
    {
      "id": "12345",
      "amount": 50.00,
      "receive": 48.50,
      "payment_method": "USDT",
      "status": "paid",
      "details": {
        "Wallet": "TXxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      },
      "tx_id": "abc123def456...",
      "evidence_url": "https://tronscan.org/#/transaction/abc123def456...",
      "transaction_uuid": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "created_at": "2026-05-20T14:30:00.000Z",
      "updated_at": "2026-05-20T15:00:00.000Z"
    }
  ],
  "meta": {
    "page": 1,
    "take": 20,
    "count": 1,
    "total": 1,
    "total_pages": 1
  }
}

Campos de respuestaCopy Anchor Link

ErroresCopy Anchor Link

POST /withdrawCopy Anchor Link

Crea un nuevo retiro de fondos. El retiro se procesa según el método de pago seleccionado.

AutenticaciónCopy Anchor Link

Bearer Token (Authorization: Bearer {token}) o Credenciales de App (app-id + app-secret en headers).

Cuando se usa Bearer Token, el parámetro pin es obligatorio. Con credenciales de App, el PIN no es requerido.

RequestCopy Anchor Link

{
  "amount": 50.00,
  "pay_method": "USDT",
  "details": {
    "Wallet": "TXxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  },
  "pin": "1234",
  "note": "Retiro semanal",
  "webhook": "https://mitienda.com/webhook/withdraw"
}

ParámetrosCopy Anchor Link

ResponseCopy Anchor Link

{
  "result": "OK",
  "data": {
    "withdraw_id": 12345,
    "transaction_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "receive_amount": 48.50,
    "receive_amount_coin": 48.50,
    "fee_to_apply": 1.50,
    "amount": 50.00,
    "coin": "USDT"
  }
}

Campos de respuestaCopy Anchor Link

IdempotenciaCopy Anchor Link

Si se envía idempotency_key y un retiro ya fue creado con esa misma clave, la respuesta es 200 con los datos del retiro original y el campo adicional "duplicate": true (no se debita saldo de nuevo). Si el retiro original aún está en proceso, se responde 409 con "code": "DUPLICATE_REQUEST" — reintenta unos segundos después.

Cumplimiento (compliance)Copy Anchor Link

QvaPay registra, junto a cada retiro, una autocertificación del cliente exigida por la normativa OFAC (31 CFR Part 515) y por el programa BSA/AML de la plataforma. El objeto compliance viaja en el mismo body del retiro (en envíos multipart, dentro del JSON de payload).

{
  "amount": 58.41,
  "pay_method": "USDTBSC",
  "details": { "Wallet": "0x7dba714e606Ac161f0FDe1A056F3Fd12Db3848D3" },
  "pin": "1234",
  "compliance": {
    "purposeCode": "W-1",
    "attestations": {
      "notProhibitedOfficial": true,
      "notProhibitedPartyMember": true,
      "notRestrictedList": true,
      "lawfulPurpose": true
    },
    "purposeNote": "Billetera personal",
    "language": "es"
  }
}

Campos de complianceCopy Anchor Link

Códigos de propósitoCopy Anchor Link

Con un purposeCode que no corresponde al tipo de retiro (p. ej. P-1 en un retiro cripto) el payload se descarta y el retiro se trata como enviado sin atestación.

Cuándo es obligatoriaCopy Anchor Link

La exigencia se despliega por canal para no romper integraciones existentes:

Excepción, cuentas US person (desde el 29 sep 2026): una cuenta US person (se declaró persona estadounidense, verificó con un documento emitido en EE. UU. o sus territorios, o tiene SSN/ITIN en su ficha) no tiene la exención de la tabla: un retiro cripto sin W-1 o un retiro con destino Cuba sin P-1…P-4 responde 400 (W1_ATTESTATION_REQUIRED / CACR_ATTESTATION_REQUIRED) desde cualquier canal.

Para las demás cuentas, en apps y clientes API la atestación es opcional hoy y recomendada: QvaPay anunciará con antelación cuando pase a ser obligatoria para todos los canales. Envíala desde ya si tu integración muestra al usuario el texto de la atestación. La atestación nunca se asume por defecto: si no llega, no se registra certificado alguno.

Otros controles regulatorios en el retiroCopy Anchor Link

Entrega de efectivo por zonaCopy Anchor Link

Las monedas de efectivo (p. ej. USDCASH) pueden tener un tarifario por municipio. Cuando lo tienen, details debe llevar la provincia y el municipio exactamente como los devuelve GET /withdraw/cash-zones, y el cargo de la zona (tarifa de entrega + margen de servicio) se suma al fee de la moneda.

El efectivo se entrega en billetes: en toda moneda de efectivo (con o sin tarifario) lo que recibe el beneficiario (receive_amount en USD para USDCASH, en CUP para CUPCASH) tiene que ser un entero múltiplo del paso de su unidad: 5 USD/EUR, 20 CUP (billetes). La comprobación es sobre lo entregado, no sobre amount: calcula el bruto a partir de lo que quieres entregar (p. ej. entregar $250 a Santa Clara son $260.41 de amount). Si no cumple, la respuesta es 400 CASH_AMOUNT_STEP con below y above (los dos importes válidos más cercanos, en la moneda del efectivo) y, desde el 2 de noviembre de 2026, amount_for_below y amount_for_above: el amount exacto en USD que deja cada uno con la tarifa vigente (null cuando esa opción no existe, p. ej. below 0). Si tu app no calcula el bruto con el tarifario por zonas, usa esos dos valores tal cual para ofrecer el ajuste; el error ya viene redactado en bruto («pon 79.80 para recibir 70 o 84.85 para recibir 75 USD»).

El ejemplo completo de un retiro USDCASH (los seis campos de details, cómo elegir la zona y cuánto se entrega) está en Ejemplos por método.

GET /withdraw/cash-zones?coin=USDCASHCopy Anchor Link

Público, sin autenticación. Una lista zones vacía significa que la moneda no funciona por zonas. El mismo tarifario viene en el campo cash_zones del coin (GET /coins, GET /coins/v2, GET /coins/:id).

{
  "coin": "USDCASH",
  "margin_pct": 1,
  "zones": [
    {
      "id": "12",
      "province_code": "CMG",
      "province_name": "Camagüey",
      "municipality": "Camagüey",
      "is_capital": true,
      "provider_pct": 3,
      "margin_pct": null,
      "total_pct": 4,
      "min_usd": 50,
      "small_flat_usd": 4,
      "eta_min_hours": 24,
      "eta_max_hours": 48,
      "home_delivery": true,
      "route": "p2p",
      "enabled": true
    }
  ]
}

Cargo de la zona sobre el amount del retiro: max(amount × provider_pct / 100, small_flat_usd) + amount × margin_pct / 100. Una vez asignada, una entrega solo puede cancelarse pasados 6 días.

NotasCopy Anchor Link

• Validación de wallet: Las direcciones de wallet para criptomonedas son validadas antes de crear el retiro.

• Número de tarjeta (BANK_CUP, BANK_MLC, CLASICA, TROPICAL): el campo Nro de tarjeta de details tiene que ser un string con exactamente 16 dígitos. Los espacios, guiones y puntos se aceptan y se quitan ("9227 0699 …" se guarda como "92270699…"). Envíalo como string, nunca como número JSON: un número de 16 dígitos pierde precisión al parsearse. Además, la tarjeta tiene que ser del tipo que paga ese método:

  Método	Tarjetas que acepta
  BANK_CUP	Tarjetas RED en CUP (9200, 9204, 9205, 9212, 9224, 9227, 9238…)
  BANK_MLC	Tarjetas RED en MLC (9225, 9226, 9228, 9229, 9235, 9245)
  TROPICAL (pay_method: "TROPICAL" o "BANDECPREPAGO")	Tropical, prepago en USD (9240, 9250, 9256)
  CLASICA	Clásica (9760) y Tropical

  El banco son los dígitos 5–8 (0699 BANDEC, 1299 BPA, 9598 Metropolitano) y el último dígito es un dígito de control Luhn. Si no se cumple, la respuesta es 400 INVALID_CARD_NUMBER con un reason (ver la tabla de errores más abajo). Una tarjeta RED de un banco conocido cuyo producto aún no está en la lista se acepta. El catálogo completo de prefijos está en qvapay/cuban_cards_prefixes. La misma regla aplica al guardar un método de pago de esos rails.

• Rate limit: 1 solicitud cada 5 segundos por usuario.

ErroresCopy Anchor Link