Listar y Crear Retiros

GET /withdraw

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

Autenticación

Bearer Token (Authorization: Bearer {token}).

Query parameters

Request

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

Response

{
  "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 respuesta

Errores

POST /withdraw

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

Autenticación

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.

Request

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

Parámetros

Response

{
  "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": "tron_usdt"
  }
}

Campos de respuesta

Idempotencia

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)

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 compliance

Códigos de propósito

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 obligatoria

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

Para 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 retiro

Notas

• Validación de wallet: Las direcciones de wallet para criptomonedas son validadas antes de crear el retiro.
• Rate limit: 1 solicitud cada 5 segundos por usuario.

Errores