Manual de Integración CriptoFacil
Guía completa para integrar pagos en criptomonedas con ambientes Sandbox y Producción
Proceso de Pago y Liquidación
CriptoFacil maneja todo el proceso de conversión y liquidación automáticamente. Tú como comercio solo recibes pesos chilenos en tu cuenta bancaria.
1
Cliente Genera Compra
El cliente realiza una compra por $50,000 CLP en tu tienda.
2
Conversión Automática a USDT
El sistema convierte automáticamente el monto CLP a USDT usando la tasa de cambio en tiempo real.
Ejemplo: $50,000 CLP = 54.35 USDT (tasa: 920 CLP/USDT)3
Cliente Paga con Crypto
El cliente paga usando su wallet de preferencia:
MetaMask (Descentralizada)Binance (Centralizada)
Pago procesado en la red Polygon con confirmación blockchain (12 confirmaciones)
4
CriptoFacil Recibe el USDT
Recibimos el pago en USDT y aplicamos la comisión correspondiente (0.9% + IVA para MetaMask, 1.2% + IVA para Binance).
5
Liquidación al Día Siguiente en CLP
Al día siguiente, te transferimos el monto en pesos chilenos directamente a tu cuenta bancaria.
Ejemplo:
- • Cliente pagó: $50,000 CLP
- • Comisión (MetaMask 0.9% + IVA): ~$535 CLP
- • Recibes en tu banco: ~$49,465 CLP
IMPORTANTE: Tú como comercio SIEMPRE recibes CLP en tu cuenta bancaria al día siguiente. No necesitas manejar criptomonedas ni hacer conversiones.
Inicio Rápido
Integra CriptoFacil en 3 pasos simples:
1
Obtén Credenciales
Contacta a martin@criptofacil.cl para recibir tus credenciales
- API Key (sk_live_...)
- Merchant ID
2
Crea un Pago
Envía un POST al endpoint con el monto y datos del cliente
POST /api/v1/payments/intent3
Recibe Webhooks
Configura tu webhook para recibir notificaciones
- payment.confirmed
- payment.failed
Obtener Credenciales
Tienes dos opciones para obtener tus credenciales de producción:
Opción 1: Registro en el sitio web (Recomendado)
Haz clic en el botón "Registro" en nuestro sitio web y completa el proceso de onboarding.
Recibirás tus credenciales automáticamente al finalizar el proceso.
Opción 2: Contacto directo
📧 Email:martin@criptofacil.cl
Información Requerida
{
"nombre_comercio": "Nombre de tu empresa",
"email": "contacto@tuempresa.cl",
"rut": "12.345.678-9",
"razon_social": "Empresa S.A.",
"sitio_web": "https://tuempresa.cl",
"webhook_url": "https://tuempresa.cl/webhooks/crypto-payments"
}Credenciales que Recibirás
API Key de Producción:
sk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0Merchant ID:
merchant_live_20251111_abc123URL Base de API:
https://pay.criptofacil.clIMPORTANTE
Guarda estas credenciales de forma segura. No las compartas ni las subas a repositorios públicos.
Endpoints de API
URL Base
https://pay.criptofacil.clPOST
/api/v1/payments/intentCrear una intención de pago
GET
/api/v1/payments/:payment_idConsultar estado de un pago
POST
/api/webhooks/payment-confirmationWebhook de confirmación (automático)
Crear un Pago
Request
Endpoint:
POST /api/v1/payments/intentHeaders:
Content-Type: application/json Authorization: Bearer sk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0
Body:
{
"merchant_id": "merchant_live_20251111_abc123",
"amount": 50000,
"currency": "CLP",
"order_id": "ORDER_2024_001",
"external_order_reference": "SHOP_ORDER_456",
"customer_info": {
"email": "cliente@email.com",
"name": "Juan Pérez García",
"rut": "12345678-9",
"phone": "+56912345678"
},
"redirect_urls": {
"success": "https://tuempresa.cl/pago-exitoso",
"cancel": "https://tuempresa.cl/pago-cancelado",
"webhook": "https://tuempresa.cl/webhooks/crypto-payments"
},
"metadata": {
"product_name": "Zapatillas Nike Air Max",
"product_id": "SKU_001",
"category": "calzado"
}
}Response Exitoso (201)
{
"success": true,
"data": {
"payment_id": "pay_cl_20251111_xyz789",
"payment_url": "https://pay.criptofacil.cl/pay/pay_cl_20251111_xyz789",
"amount_clp": 50000,
"amount_usdt": 54.347826,
"exchange_rate": {
"rate": 920,
"source": "coingecko",
"updated_at": "2025-01-11T15:30:00.000Z"
},
"payment_expires_at": "2025-01-11T15:45:00.000Z",
"status": "pending",
"fees": {
"wallet_type": "decentralized",
"platform_percentage": 0.9,
"platform_fee_usdt": 0.48913,
"iva_percentage": 19,
"iva_fee_usdt": 0.092935,
"net_amount_usdt": 53.765761,
"user_pays_gas": true,
"estimated_gas_cost": "~$0.01 USD"
}
}
}Consultar Estado de Pago
Endpoint:
GET /api/v1/payments/:payment_idEjemplo:
curl -X GET "https://pay.criptofacil.cl/api/v1/payments/pay_cl_20251111_xyz789" \ -H "Authorization: Bearer sk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0"
Estados Posibles
pendingEsperando pago del cliente
processingTransacción enviada, esperando confirmaciones
confirmedPago confirmado (12 confirmaciones)
failedPago falló o fue rechazado
expiredLink de pago expiró (15 minutos)
Webhooks
Configuración
Tu endpoint de webhook debe:
- Aceptar requests POST
- Estar disponible en HTTPS
- Responder con status 200 OK en menos de 5 segundos
- Validar la firma del webhook (recomendado)
Evento: payment.confirmed
{
"event": "payment.confirmed",
"payment_id": "pay_cl_20251111_xyz789",
"merchant_id": "merchant_live_20251111_abc123",
"order_id": "ORDER_2024_001",
"external_order_reference": "SHOP_ORDER_456",
"amount_clp": 50000,
"amount_usdt": 54.347826,
"net_amount_usdt": 53.765761,
"exchange_rate": 920,
"status": "confirmed",
"confirmed_at": "2025-01-11T15:35:00.000Z",
"transaction_hash": "0xabc123def456...",
"customer_info": {
"email": "cliente@email.com",
"name": "Juan Pérez García",
"rut": "12345678-9",
"phone": "+56912345678"
},
"fees": {
"wallet_type": "decentralized",
"platform_percentage": 0.9,
"platform_fee_usdt": 0.48913,
"iva_percentage": 19,
"iva_fee_usdt": 0.092935,
"platform_net_fee_usdt": 0.396195
},
"metadata": {
"product_name": "Zapatillas Nike Air Max",
"product_id": "SKU_001",
"category": "calzado"
}
}Ejemplos de Código
cURL
curl -X POST "https://pay.criptofacil.cl/api/v1/payments/intent" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer sk_live_..." \
-d '{
"merchant_id": "merchant_live_...",
"amount": 50000,
"currency": "CLP",
"order_id": "ORDER_2024_001",
"customer_info": {
"email": "cliente@email.com",
"name": "Juan Pérez"
},
"redirect_urls": {
"success": "https://tuempresa.cl/success",
"cancel": "https://tuempresa.cl/cancel",
"webhook": "https://tuempresa.cl/webhook"
}
}'JavaScript / Node.js
const API_KEY = 'sk_live_...'
const MERCHANT_ID = 'merchant_live_...'
const API_URL = 'https://pay.criptofacil.cl'
async function createPayment(orderData) {
const response = await fetch(`${API_URL}/api/v1/payments/intent`, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Authorization': `Bearer ${API_KEY}`
},
body: JSON.stringify({
merchant_id: MERCHANT_ID,
amount: orderData.amount,
currency: 'CLP',
order_id: orderData.orderId,
customer_info: {
email: orderData.customerEmail,
name: orderData.customerName
},
redirect_urls: {
success: 'https://tuempresa.cl/success',
cancel: 'https://tuempresa.cl/cancel',
webhook: 'https://tuempresa.cl/webhook'
}
})
})
const result = await response.json()
if (result.success) {
window.location.href = result.data.payment_url
}
}Python
import requests
API_KEY = 'sk_live_...'
MERCHANT_ID = 'merchant_live_...'
API_URL = 'https://pay.criptofacil.cl'
def create_payment(order_data):
headers = {
'Content-Type': 'application/json',
'Authorization': f'Bearer {API_KEY}'
}
payload = {
'merchant_id': MERCHANT_ID,
'amount': order_data['amount'],
'currency': 'CLP',
'order_id': order_data['order_id'],
'customer_info': {
'email': orderData['customer_email'],
'name': orderData['customer_name']
},
'redirect_urls': {
'success': 'https://tuempresa.cl/success',
'cancel': 'https://tuempresa.cl/cancel',
'webhook': 'https://tuempresa.cl/webhook'
}
}
response = requests.post(
f'{API_URL}/api/v1/payments/intent',
json=payload,
headers=headers
)
return response.json()PHP
<?php
$apiKey = 'sk_live_...';
$merchantId = 'merchant_live_...';
$apiUrl = 'https://pay.criptofacil.cl';
function createPayment($orderData) {
global $apiKey, $merchantId, $apiUrl;
$payload = [
'merchant_id' => $merchantId,
'amount' => $orderData['amount'],
'currency' => 'CLP',
'order_id' => $orderData['orderId'],
'customer_info' => [
'email' => $orderData['customerEmail'],
'name' => $orderData['customerName']
],
'redirect_urls' => [
'success' => 'https://tuempresa.cl/success',
'cancel' => 'https://tuempresa.cl/cancel',
'webhook' => 'https://tuempresa.cl/webhook'
]
];
$ch = curl_init($apiUrl . '/api/v1/payments/intent');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'Content-Type: application/json',
'Authorization: Bearer ' . $apiKey
]);
$response = curl_exec($ch);
return json_decode($response, true);
}
?>Comisiones y Tarifas
Wallets Descentralizadas
MetaMask, Trust Wallet, etc.
0.9% + IVA
Comisión de plataforma
Wallets Centralizadas
Binance, Coinbase, etc.
1.2% + IVA
Comisión de plataforma
Ejemplos de Cálculo
METAMASKPago de $50,000 CLP
Tasa de cambio:920 CLP/USDT
Amount USDT:50,000 / 920 = 54.35 USDT
Comisión (0.9%):- 0.49 USDT
IVA (19%):- 0.09 USDT
Recibes en tu banco (CLP):~$49,465
BINANCEPago de $50,000 CLP
Tasa de cambio:920 CLP/USDT
Amount USDT:50,000 / 920 = 54.35 USDT
Comisión (1.2%):- 0.65 USDT
IVA (19%):- 0.12 USDT
Recibes en tu banco (CLP):~$49,286
Tabla Comparativa
| Monto CLP | USDT Total | Recibes (MetaMask) | Recibes (Binance) |
|---|---|---|---|
| $10,000 | 10.87 USDT | ~$9,893 CLP | ~$9,857 CLP |
| $50,000 | 54.35 USDT | ~$49,465 CLP | ~$49,286 CLP |
| $100,000 | 108.70 USDT | ~$98,931 CLP | ~$98,572 CLP |
| $500,000 | 543.48 USDT | ~$494,653 CLP | ~$492,860 CLP |
| $1,000,000 | 1,086.96 USDT | ~$989,306 CLP | ~$985,720 CLP |
Seguridad
Protección de API Keys
- NUNCA expongas tus API keys en el frontend o repositorios públicos
- Utiliza variables de entorno en tu servidor backend
- Implementa rotación periódica de tus API keys
Verificación de Webhooks
- Valida SIEMPRE la firma HMAC (X-Signature)
- Implementa lógica de idempotencia
- Asegúrate de usar HTTPS
- Configura rate limiting
Validación de Pagos
- No confíes únicamente en webhooks
- Consulta el estado directamente vía API
- Verifica montos y moneda
- Maneja todos los estados posibles
¿Necesitas Ayuda?
Nuestro equipo está listo para ayudarte con tu integración