Documentación de la API
La API de Flixy Pay es una API REST. Las solicitudes usan parámetros de formulario o JSON y las respuestas son en JSON. Los importes van siempre en céntimos (2500 = 25,00).
Autenticación
Cada solicitud envía tu clave secreta en la cabecera Authorization. Las claves empiezan por fp_test_ en modo de prueba y por fp_live_ en modo real. Nunca pongas la clave secreta en una página web ni en una aplicación móvil.
curl https://flixypay.net/v1/balance \ -H "Authorization: Bearer fp_test_sk_…"
| Clave | Uso |
|---|---|
fp_test_pk_… / fp_live_pk_… | Clave pública: navegador y aplicación (formulario integrado). |
fp_test_sk_… / fp_live_sk_… | Clave secreta: solo en tu servidor. |
Modo de prueba
El modo de prueba está disponible desde el registro, antes de cualquier verificación de identidad. No circula dinero real. Usa estas tarjetas con una fecha de caducidad futura y cualquier código de 3 cifras:
| Número | Resultado |
|---|---|
4242 4242 4242 4242 | Pago completado |
5555 5555 5555 4444 | Pago completado (Mastercard) |
4000 0025 0000 3155 | Se pide autenticación 3D Secure |
4000 0000 0000 9995 | Rechazado: fondos insuficientes |
4000 0000 0000 0002 | Rechazado: tarjeta rechazada |
Errores
Los errores devuelven un código HTTP 4xx o 5xx y un objeto error con un tipo y un mensaje legible.
{
"error": { "type": "invalid_request", "message": "amount is required" }
}
400 | Parámetro ausente o no válido |
401 | Clave ausente, no válida o revocada |
403 | Cuenta suspendida o modo real aún no activado |
404 | Recurso no encontrado |
429 | Demasiadas solicitudes, inténtalo de nuevo en un momento |
Pagos
POST/v1/paymentsCrea un pago. Parámetros: amount (obligatorio, en céntimos), currency (eur por defecto), description, customer_email, success_url, cancel_url, metadata[clave].
curl https://flixypay.net/v1/payments \ -H "Authorization: Bearer fp_test_sk_…" \ -d amount=4900 -d currency=eur \ -d description="Abonnement mars" \ -d success_url="https://exemple.fr/merci" \ -d "metadata[order_id]=1048"
{
"id": "pay_9fK2…", "object": "payment", "livemode": false,
"amount": 4900, "currency": "eur", "status": "requires_payment",
"checkout_url": "https://flixypay.net/pay/pay_9fK2…",
"client_secret": "…", "metadata": { "order_id": "1048" }
}
GET/v1/payments/{id} GET/v1/payments?limit=20&status=succeeded Estados posibles: requires_payment, succeeded, failed, partially_refunded, refunded.
Página de pago alojada
La forma más sencilla: redirige al cliente a checkout_url. Tras el pago, vuelve a success_url con ?payment=pay_…; comprueba siempre el estado en el servidor o espera el webhook payment.succeeded antes de entregar.
Formulario integrado
Para que el cliente se quede en tu página, crea el pago en el servidor y muestra el formulario con flixypay.js y tu clave pública.
<div id="pay"></div> <script src="https://flixypay.net/js/flixypay.js"></script> <script> const fp = FlixyPay('fp_test_pk_…'); fp.mount('#pay', { payment: 'pay_9fK2…', clientSecret: '…', onSuccess: () => location.href = '/merci' }); </script>
Reembolsos
POST/v1/payments/{id}/refundsReembolsa todo o parte de un pago completado. Parámetros: amount (opcional, todo lo restante por defecto), reason.
curl https://flixypay.net/v1/payments/pay_9fK2…/refunds \ -H "Authorization: Bearer fp_test_sk_…" -d amount=1000
Enlaces de pago
POST/v1/links GET/v1/linksCrea un enlace reutilizable. Parámetros: title, amount, currency. La respuesta contiene url, para compartir tal cual.
Saldo
GET/v1/balanceDevuelve los importes pendientes y disponibles de la cuenta, en la divisa de la cuenta.
Tap to Pay
POST/v1/terminal/connection_tokensDevuelve un token de conexión que tu aplicación móvil usa para cobrar en persona. Llámalo desde tu servidor cada vez que la aplicación lo pida.
Webhooks
Añade la dirección de tu servidor en Panel → Webhooks. Cada evento se envía en POST JSON con la cabecera Flixy-Signature: t=marca_de_tiempo,v1=firma. La firma es un HMAC SHA-256 de «marca_de_tiempo.cuerpo» con el secreto del endpoint (whsec_…). Responde 2xx rápidamente.
// PHP — vérifier la signature $payload = file_get_contents('php://input'); parse_str(str_replace(',', '&', $_SERVER['HTTP_FLIXY_SIGNATURE']), $sig); $expected = hash_hmac('sha256', $sig['t'] . '.' . $payload, getenv('FLIXYPAY_WHSEC')); if (!hash_equals($expected, $sig['v1']) || abs(time() - $sig['t']) > 300) { http_response_code(400); exit; } $event = json_decode($payload, true); if ($event['type'] === 'payment.succeeded') { /* livrer la commande */ }
Tipos de eventos
payment.succeeded | Un pago se ha completado |
payment.failed | Un pago ha fallado |
payment.refunded | Un pago se ha reembolsado total o parcialmente |
refund.created | Se ha creado un reembolso |
dispute.created | Un cliente ha disputado un pago |
dispute.closed | Una disputa se ha cerrado |
payout.paid | Una transferencia ha llegado a la cuenta bancaria |
account.updated | El estado de la cuenta ha cambiado |
link.paid | Se ha pagado un enlace de pago |