Referencia de la API

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).

https://flixypay.net/v1

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_…"
ClaveUso
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úmeroResultado
4242 4242 4242 4242Pago completado
5555 5555 5555 4444Pago completado (Mastercard)
4000 0025 0000 3155Se pide autenticación 3D Secure
4000 0000 0000 9995Rechazado: fondos insuficientes
4000 0000 0000 0002Rechazado: 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" }
}
400Parámetro ausente o no válido
401Clave ausente, no válida o revocada
403Cuenta suspendida o modo real aún no activado
404Recurso no encontrado
429Demasiadas solicitudes, inténtalo de nuevo en un momento

Pagos

POST/v1/payments

Crea 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}/refunds

Reembolsa 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

Saldo

GET/v1/balance

Devuelve los importes pendientes y disponibles de la cuenta, en la divisa de la cuenta.

Tap to Pay

POST/v1/terminal/connection_tokens

Devuelve 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.succeededUn pago se ha completado
payment.failedUn pago ha fallado
payment.refundedUn pago se ha reembolsado total o parcialmente
refund.createdSe ha creado un reembolso
dispute.createdUn cliente ha disputado un pago
dispute.closedUna disputa se ha cerrado
payout.paidUna transferencia ha llegado a la cuenta bancaria
account.updatedEl estado de la cuenta ha cambiado
link.paidSe ha pagado un enlace de pago