Transferencias
Retiros a cuentas bancarias o billeteras USDT.
Con las transferencias retiras tu saldo (en USDT) a un beneficiario bancario o a una billetera. Toda transferencia creada por API entra en pending_approval. Las de más de 1,000 USD requieren doble firma del comercio. Scope payouts:write para crear (límite 10 por minuto). El cuerpo JSON usa camelCase (destinationType, beneficiaryId, cryptoBeneficiaryId, purposeDetail). Las transferencias bancarias exigen el comprobante como archivo multipart en el campo file.
- pending_approval → dispatching: Aprobada
- pending_approval → rejected: Rechazada
- dispatching → processing: Aceptada por el proveedor
- dispatching → pending: En revisión del proveedor
- dispatching → dispatch_unknown: Resultado no confirmado
- dispatching → failed: Fallida
- dispatch_unknown → dispatching: Verificar
- dispatch_unknown → processing: Aceptada por el proveedor
- dispatch_unknown → pending: En revisión del proveedor
- dispatch_unknown → failed: Fallida
- pending → processing: Aceptada por el proveedor
- pending → failed: Fallida
- processing → completed: Completada
- processing → failed: Fallida
Configuración de transferencias
/api/v1/payouts/config
Métodos, umbral de doble firma y propósitos.
Parámetros
AuthorizationstringObligatorioBearer $CLOBEPAY_API_KEY. También se acepta X-API-Key con el mismo valor. No envíes ambos.
Respuestas
- HTTP 200Configuración.
Errores
- HTTP 400
ambiguous_credentialsAuthorization: Bearer y X-API-Key traen llaves distintas. - HTTP 401
missing_credentialsNo enviaste la llave (Authorization: Bearer o X-API-Key). - HTTP 401
invalid_api_keyLa llave no existe, está mal formada o no coincide. - HTTP 401
api_key_revokedLa llave fue revocada. - HTTP 401
api_key_expiredLa llave expiró. - HTTP 401
api_key_wrong_environmentLa llave es de otro ambiente (llave de prueba en producción o al revés). - HTTP 403
insufficient_scopeLa llave no tiene el scope de esta ruta. - HTTP 429
rate_limitedDemasiadas peticiones. Respeta Retry-After.
curl -X GET "$CLOBEPAY_API_BASE/payouts/config" \ -H "Authorization: Bearer $CLOBEPAY_API_KEY"Respuesta
HTTP 200{
"dualApprovalThresholdUsd": "1000.00",
"methods": [
"ach",
"wire",
"crypto"
]
}Cotizar una transferencia
/api/v1/payouts/quote
Costo, tipo de cambio referencial y si alcanza el saldo.
Parámetros
AuthorizationstringObligatorioBearer $CLOBEPAY_API_KEY. También se acepta X-API-Key con el mismo valor. No envíes ambos.
amountstringObligatorioImporte que recibe el beneficiario.
methodstringOpcionalach, wire o crypto.
ach · wire · crypto
destinationstringOpcionalbank o crypto.
bank · crypto
chainstringOpcionalRed si el destino es crypto.
tron · eth · polygon
Respuestas
- HTTP 200Cotización. Campos en camelCase (receiveAmount, totalDebit, requiredApprovals).
Errores
- HTTP 400
ambiguous_credentialsAuthorization: Bearer y X-API-Key traen llaves distintas. - HTTP 401
missing_credentialsNo enviaste la llave (Authorization: Bearer o X-API-Key). - HTTP 401
invalid_api_keyLa llave no existe, está mal formada o no coincide. - HTTP 401
api_key_revokedLa llave fue revocada. - HTTP 401
api_key_expiredLa llave expiró. - HTTP 401
api_key_wrong_environmentLa llave es de otro ambiente (llave de prueba en producción o al revés). - HTTP 403
insufficient_scopeLa llave no tiene el scope de esta ruta. - HTTP 429
rate_limitedDemasiadas peticiones. Respeta Retry-After. - HTTP 400
invalid_amountImporte o método inválido.
curl -X GET "$CLOBEPAY_API_BASE/payouts/quote?amount=100.00&method=ach&destination=bank" \ -H "Authorization: Bearer $CLOBEPAY_API_KEY"Respuesta
HTTP 200{
"destinationType": "bank",
"method": "ach",
"receiveAmount": "100.00",
"receiveCurrency": "USD",
"convertAmount": "100.00",
"fee": {
"amount": "1.50",
"currency": "USDT"
},
"totalDebit": "101.50",
"debitAsset": "USDT",
"sufficientBalance": true,
"requiredApprovals": 1,
"dualApprovalThresholdUsd": "1000.00"
}Crear una transferencia
/api/v1/payouts
Queda en pending_approval. Scope payouts:write. Bank exige file.
Parámetros
AuthorizationstringObligatorioBearer $CLOBEPAY_API_KEY. También se acepta X-API-Key con el mismo valor. No envíes ambos.
Idempotency-KeystringObligatorio1–255 caracteres. Obligatoria en este POST. Si repites la misma llave y el mismo cuerpo, se devuelve la respuesta original (Idempotent-Replayed: true). Si el cuerpo cambia, 422 idempotency_key_reuse.
destinationTypestringOpcionalbank (por defecto) o crypto.
bank · crypto
beneficiaryIduuidOpcionalBeneficiario bancario US. Obligatorio si destinationType es bank.
cryptoBeneficiaryIduuidOpcionalBilletera USDT. Obligatorio si destinationType es crypto.
amountstringObligatorioImporte que recibe el beneficiario (USD en bank, USDT en crypto).
purposestringOpcionalObligatorio en bank (p. ej. Invoice_Payment). Opcional en crypto.
purposeDetailstringOpcionalSolo con purpose = Other (máx. 140).
descriptionstringOpcionalConcepto (máx. 140).
filefileOpcionalComprobante obligatorio en transferencias bancarias (multipart). No aplica en crypto.
Respuestas
- HTTP 201Solicitud creada en pending_approval.
Errores
- HTTP 400
ambiguous_credentialsAuthorization: Bearer y X-API-Key traen llaves distintas. - HTTP 401
missing_credentialsNo enviaste la llave (Authorization: Bearer o X-API-Key). - HTTP 401
invalid_api_keyLa llave no existe, está mal formada o no coincide. - HTTP 401
api_key_revokedLa llave fue revocada. - HTTP 401
api_key_expiredLa llave expiró. - HTTP 401
api_key_wrong_environmentLa llave es de otro ambiente (llave de prueba en producción o al revés). - HTTP 403
insufficient_scopeLa llave no tiene el scope de esta ruta. - HTTP 429
rate_limitedDemasiadas peticiones. Respeta Retry-After. - HTTP 400
idempotency_key_requiredFalta el header Idempotency-Key. - HTTP 422
insufficient_balanceEl saldo no alcanza para el importe y el costo. - HTTP 422
invalid_purposeFalta purpose en un retiro bancario, no es un valor permitido o purposeDetail supera 140 caracteres. - HTTP 422
supporting_document_requiredFalta el archivo file en un retiro bancario.
curl -X POST "$CLOBEPAY_API_BASE/payouts" \ -H "Idempotency-Key: payout-10042" \ -H "Authorization: Bearer $CLOBEPAY_API_KEY" \ -F "destinationType=bank" \ -F "beneficiaryId=a41c82e7-3b6d-4c90-9e2a-5f17d0b8c4e3" \ -F "amount=100.00" \ -F "purpose=Invoice_Payment" \ -F "file=@invoice.pdf"Respuesta
HTTP 201{
"id": "e2a9c4d1-6f38-4b7e-a015-c8d94e2b70aa",
"destinationType": "bank",
"amount": "100.00",
"currency": "USD",
"method": "ach",
"status": "pending_approval",
"totalDebit": "101.50",
"debitAsset": "USDT",
"requiredApprovals": 1
}Listar transferencias
/api/v1/payouts
Historial de retiros. Scope payouts:read.
Parámetros
AuthorizationstringObligatorioBearer $CLOBEPAY_API_KEY. También se acepta X-API-Key con el mismo valor. No envíes ambos.
statusstringOpcionalFiltra por estado.
pagenumberOpcionalPágina (desde 1).
Respuestas
- HTTP 200Listado.
Errores
- HTTP 400
ambiguous_credentialsAuthorization: Bearer y X-API-Key traen llaves distintas. - HTTP 401
missing_credentialsNo enviaste la llave (Authorization: Bearer o X-API-Key). - HTTP 401
invalid_api_keyLa llave no existe, está mal formada o no coincide. - HTTP 401
api_key_revokedLa llave fue revocada. - HTTP 401
api_key_expiredLa llave expiró. - HTTP 401
api_key_wrong_environmentLa llave es de otro ambiente (llave de prueba en producción o al revés). - HTTP 403
insufficient_scopeLa llave no tiene el scope de esta ruta. - HTTP 429
rate_limitedDemasiadas peticiones. Respeta Retry-After.
curl -X GET "$CLOBEPAY_API_BASE/payouts?status=pending_approval" \ -H "Authorization: Bearer $CLOBEPAY_API_KEY"Respuesta
HTTP 200{
"items": [],
"page": 1
}Consultar una transferencia
/api/v1/payouts/{payoutId}
Detalle por UUID. Scope payouts:read.
Parámetros
AuthorizationstringObligatorioBearer $CLOBEPAY_API_KEY. También se acepta X-API-Key con el mismo valor. No envíes ambos.
payoutIduuidObligatorioUUID de la transferencia.
Respuestas
- HTTP 200Detalle en camelCase (destinationType, totalDebit, requiredApprovals).
Errores
- HTTP 400
ambiguous_credentialsAuthorization: Bearer y X-API-Key traen llaves distintas. - HTTP 401
missing_credentialsNo enviaste la llave (Authorization: Bearer o X-API-Key). - HTTP 401
invalid_api_keyLa llave no existe, está mal formada o no coincide. - HTTP 401
api_key_revokedLa llave fue revocada. - HTTP 401
api_key_expiredLa llave expiró. - HTTP 401
api_key_wrong_environmentLa llave es de otro ambiente (llave de prueba en producción o al revés). - HTTP 403
insufficient_scopeLa llave no tiene el scope de esta ruta. - HTTP 429
rate_limitedDemasiadas peticiones. Respeta Retry-After. - HTTP 404
not_foundNo existe o no es tuya. También si payoutId no es un UUID.
curl -X GET "$CLOBEPAY_API_BASE/payouts/e2a9c4d1-6f38-4b7e-a015-c8d94e2b70aa" \ -H "Authorization: Bearer $CLOBEPAY_API_KEY"Respuesta
HTTP 200Detalle en camelCase (destinationType, totalDebit, requiredApprovals).