Manual de Integración CriptoFacil
Guía completa para integrar pagos en USDC con liquidación automática en CLP
Proceso de Pago y Liquidación
CriptoFacil maneja todo el proceso de conversión y liquidación. Tú como comercio siempre recibes pesos chilenos en tu cuenta bancaria — nunca necesitas manejar criptomonedas.
1
Cliente Genera Compra
El cliente realiza una compra en tu tienda. Tú envías el monto en CLP a nuestra API.
2
Conversión Automática a USDC
El sistema convierte automáticamente el monto CLP a USDC usando la tasa de cambio en tiempo real de Buda.com.
Ejemplo: $100,000 CLP ≈ 108.70 USDC (tasa: 920 CLP/USDC)3
Cliente Elige y Paga
El cliente selecciona su método de pago preferido y completa la transacción.
MetaMask (Polygon)Binance Pay
4
CriptoFacil Confirma el Pago
Verificamos la transacción (MetaMask: confirmaciones en blockchain / Binance Pay: confirmación instantánea) y notificamos a tu sistema via webhook.
5
Liquidación al Día Hábil Siguiente en CLP
Al día hábil siguiente, transferimos el monto en pesos chilenos directamente a la cuenta bancaria que registraste al crear tu cuenta.
Datos bancarios necesarios al registrarse:
- Banco
- Tipo de cuenta (Corriente / Vista / Ahorro)
- Número de cuenta
- RUT titular
- Nombre titular
Tú como comercio SIEMPRE recibes CLP en tu cuenta bancaria. No necesitas manejar criptomonedas ni hacer conversiones.
Inicio Rápido
Integra CriptoFacil en 3 pasos:
1
Obtén Credenciales
Contacta a martin@criptofacil.cl o regístrate en nuestro sitio.
- API Key (sk_live_...)
- Merchant ID
2
Crea un Pago
Envía un POST al endpoint con el monto en CLP y los datos del cliente.
POST /api/v1/payments/intent3
Recibe Webhooks
Configura tu endpoint para recibir notificaciones en tiempo real.
- payment.confirmed
- payment.failed
- payment.expired
Obtener Credenciales
Opción 1: Registro en el sitio web (Recomendado)
Haz clic en "Registro" en nuestro sitio web y completa el proceso de onboarding. Recibirás tus credenciales automáticamente.
Opción 2: Contacto directo
Información Requerida al Registrarse
{
"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/pagos",
"datos_bancarios": {
"banco": "Banco de Chile",
"tipo_cuenta": "Corriente / Vista / Ahorro",
"numero_cuenta": "1234567890",
"rut_titular": "12.345.678-9",
"nombre_titular": "Empresa S.A."
}
}IMPORTANTE: Los datos bancarios son necesarios para realizar la liquidación en CLP al día hábil siguiente. Sin ellos no es posible activar tu cuenta.
Credenciales que Recibirás
API Key de Producción:
sk_live_a1b2c3d4e5f6...Merchant ID:
merchant_...URL Base de API:
https://pay.criptofacil.clEndpoints 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
Crear un Pago
Headers:
Content-Type: application/json Authorization: Bearer sk_live_...
Body:
{
"merchant_id": "merchant_...",
"amount": 100000,
"currency": "CLP",
"order_id": "ORDER_001",
"customer_info": {
"email": "cliente@email.com",
"name": "Juan Pérez",
"rut": "12345678-9",
"phone": "+56912345678"
},
"redirect_urls": {
"success": "https://tuempresa.cl/pago-exitoso",
"cancel": "https://tuempresa.cl/pago-cancelado",
"webhook": "https://tuempresa.cl/webhooks/pagos"
},
"metadata": {
"product_name": "Nombre del Producto",
"product_id": "SKU_001"
}
}Parámetros
| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
merchant_id | string | ✅ | Tu Merchant ID |
amount | number | ✅ | Monto en CLP (mín: 100, máx: 40.000.000) |
currency | string | ✅ | Siempre "CLP" |
order_id | string | ✅ | ID único de tu orden |
customer_info.email | string | ✅ | Email del cliente |
customer_info.name | string | ✅ | Nombre completo del cliente |
customer_info.rut | string | ❌ | RUT chileno (formato: 12345678-9) |
customer_info.phone | string | ❌ | Teléfono (+56912345678) |
redirect_urls.success | string | ✅ | URL de éxito (HTTPS) |
redirect_urls.cancel | string | ✅ | URL de cancelación (HTTPS) |
redirect_urls.webhook | string | ✅ | URL del webhook (HTTPS) |
metadata | object | ❌ | Datos personalizados (JSON libre) |
Response Exitoso (201)
{
"success": true,
"data": {
"payment_id": "pay_...",
"payment_url": "https://pay.criptofacil.cl/pay/pay_...",
"amount_clp": 100000,
"amount_cripto": 108.695652,
"currency_cripto": "USDC",
"exchange_rate": {
"rate": 920,
"source": "buda.com",
"updated_at": "2025-01-11T15:30:00.000Z"
},
"payment_expires_at": "2025-01-11T15:45:00.000Z",
"status": "pending"
}
}Errores Comunes
400
Minimum amount is $100 CLPEl monto mínimo es 100 CLP
401
Invalid merchant or API keyCredenciales incorrectas o faltantes
400
Invalid email formatEl email del cliente no es válido
400
Webhook URL must be HTTPSTodas las URLs deben usar HTTPS
400
Order ID already existsEl order_id debe ser único por comercio
Consultar Estado de Pago
curl -X GET "https://pay.criptofacil.cl/api/v1/payments/pay_..." \ -H "Authorization: Bearer sk_live_..."
Estados Posibles
pendingEsperando pago del cliente
processingTransacción enviada, esperando confirmaciones
confirmedPago confirmado exitosamente
failedPago fallido o rechazado
expiredLink de pago expiró (15 minutos)
Webhooks
Requisitos del Endpoint
- Aceptar requests POST
- Disponible en HTTPS
- Responder con HTTP 200 en menos de 5 segundos
- Validar la firma X-Signature (recomendado)
Evento: payment.confirmed
{
"event": "payment.confirmed",
"payment_id": "pay_...",
"merchant_id": "merchant_...",
"order_id": "ORDER_001",
"amount": 100000,
"currency": "CLP",
"amount_cripto": 108.695652,
"currency_cripto": "USDC",
"status": "confirmed",
"confirmed_at": "2025-01-11T15:35:00.000Z",
"transaction_hash": "0xabc123...",
"payment_method": "metamask | binance_pay",
"customer_info": {
"email": "cliente@email.com",
"name": "Juan Pérez",
"rut": "12345678-9",
"phone": "+56912345678"
},
"fees": {
"platform_fee_cripto": 1.304348,
"iva_fee_cripto": 0.247826,
"platform_net_fee_cripto": 1.056522
},
"metadata": {
"product_name": "Nombre del Producto",
"product_id": "SKU_001"
}
}Validar Firma del Webhook
const crypto = require('crypto')
function validateWebhookSignature(payload, signature, secret) {
const expected = crypto
.createHmac('sha256', secret)
.update(JSON.stringify(payload))
.digest('hex')
return signature === expected
}
app.post('/webhooks/pagos', (req, res) => {
const signature = req.headers['x-signature']
const isValid = validateWebhookSignature(
req.body,
signature,
process.env.WEBHOOK_SECRET
)
if (!isValid) return res.status(401).send('Invalid signature')
if (req.body.event === 'payment.confirmed') {
const { order_id, amount, currency } = req.body
// Actualizar tu orden en la BD
// Enviar email/notificación al cliente
}
res.status(200).send('OK')
})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_...",
"amount": 100000,
"currency": "CLP",
"order_id": "ORDER_001",
"customer_info": {
"email": "cliente@email.com",
"name": "Juan Pérez"
},
"redirect_urls": {
"success": "https://tuempresa.cl/pago-exitoso",
"cancel": "https://tuempresa.cl/pago-cancelado",
"webhook": "https://tuempresa.cl/webhooks/pagos"
}
}'JavaScript / Node.js
const API_KEY = 'sk_live_...'
const MERCHANT_ID = 'merchant_...'
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, // monto en CLP
currency: 'CLP',
order_id: orderData.orderId,
customer_info: {
email: orderData.email,
name: orderData.name
},
redirect_urls: {
success: 'https://tuempresa.cl/pago-exitoso',
cancel: 'https://tuempresa.cl/pago-cancelado',
webhook: 'https://tuempresa.cl/webhooks/pagos'
},
metadata: {
product_name: orderData.productName
}
})
})
const result = await response.json()
if (result.success) {
// Redirigir al cliente a la página de pago
window.location.href = result.data.payment_url
} else {
console.error('Error:', result.error)
}
}Python
import requests
API_KEY = 'sk_live_...'
MERCHANT_ID = 'merchant_...'
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'], # monto en CLP
'currency': 'CLP',
'order_id': order_data['order_id'],
'customer_info': {
'email': order_data['email'],
'name': order_data['name']
},
'redirect_urls': {
'success': 'https://tuempresa.cl/pago-exitoso',
'cancel': 'https://tuempresa.cl/pago-cancelado',
'webhook': 'https://tuempresa.cl/webhooks/pagos'
}
}
response = requests.post(
f'{API_URL}/api/v1/payments/intent',
json=payload,
headers=headers
)
result = response.json()
if result.get('success'):
return result['data']['payment_url']
else:
raise Exception(result.get('error'))PHP
<?php
$apiKey = 'sk_live_...';
$merchantId = 'merchant_...';
$apiUrl = 'https://pay.criptofacil.cl';
function createPayment($orderData) {
global $apiKey, $merchantId, $apiUrl;
$payload = [
'merchant_id' => $merchantId,
'amount' => $orderData['amount'], // monto en CLP
'currency' => 'CLP',
'order_id' => $orderData['orderId'],
'customer_info' => [
'email' => $orderData['email'],
'name' => $orderData['name']
],
'redirect_urls' => [
'success' => 'https://tuempresa.cl/pago-exitoso',
'cancel' => 'https://tuempresa.cl/pago-cancelado',
'webhook' => 'https://tuempresa.cl/webhooks/pagos'
]
];
$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
]);
$result = json_decode(curl_exec($ch), true);
curl_close($ch);
if ($result['success']) {
header('Location: ' . $result['data']['payment_url']);
exit;
} else {
throw new Exception($result['error']);
}
}
?>Seguridad
Protección de API Keys
- NUNCA expongas tu API key en el frontend, JavaScript del cliente o repositorios públicos
- Usa siempre 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-SHA256 del header X-Signature
- Implementa idempotencia: guarda los payment_id ya procesados para no procesar duplicados
- Tu endpoint de webhook debe usar HTTPS obligatoriamente
- Responde con HTTP 200 inmediatamente y procesa en segundo plano si necesitas más tiempo
Validación de Pagos
- No confirmes pedidos basándote únicamente en el webhook — consulta también el estado vía GET /api/v1/payments/:id
- Verifica que el amount y currency del webhook coincidan con tu orden original
- Maneja todos los estados posibles: confirmed, failed, expired
- Implementa timeouts y notifica al cliente si un pago expira
¿Necesitas Ayuda?
Nuestro equipo está listo para ayudarte con tu integración