API documentation
The Flixy Pay API is a REST API. Requests use form parameters or JSON, responses are JSON. Amounts are always in cents (2500 = 25.00).
Authentication
Every request sends your secret key in the Authorization header. Keys start with fp_test_ in test mode and fp_live_ in live mode. Never put the secret key in a web page or a mobile app.
curl https://flixypay.net/v1/balance \ -H "Authorization: Bearer fp_test_sk_…"
| Key | Usage |
|---|---|
fp_test_pk_… / fp_live_pk_… | Publishable key: browser and app (embedded form). |
fp_test_sk_… / fp_live_sk_… | Secret key: on your server only. |
Test mode
Test mode is available from sign-up, before any identity verification. No real money moves. Use these cards with a future expiry date and any 3-digit code:
| Number | Result |
|---|---|
4242 4242 4242 4242 | Payment successful |
5555 5555 5555 4444 | Payment succeeds (Mastercard) |
4000 0025 0000 3155 | 3D Secure authentication required |
4000 0000 0000 9995 | Declined: insufficient funds |
4000 0000 0000 0002 | Declined: card declined |
Errors
Errors return an HTTP 4xx or 5xx code and an error object with a type and a readable message.
{
"error": { "type": "invalid_request", "message": "amount is required" }
}
400 | Missing or invalid parameter |
401 | Missing, invalid or revoked key |
403 | Account suspended or live mode not yet enabled |
404 | Resource not found |
429 | Too many requests, try again in a moment |
Payments
POST/v1/paymentsCreates a payment. Parameters: amount (required, in cents), currency (eur by default), description, customer_email, success_url, cancel_url, metadata[key].
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 Possible statuses: requires_payment, succeeded, failed, partially_refunded, refunded.
Hosted payment page
The simplest way: redirect the customer to checkout_url. After payment, they come back to success_url with ?payment=pay_…; always check the status server-side or wait for the payment.succeeded webhook before fulfilling.
Embedded form
To keep the customer on your page, create the payment server-side then display the form with flixypay.js and your publishable key.
<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>
Refunds
POST/v1/payments/{id}/refundsRefunds all or part of a successful payment. Parameters: amount (optional, the full remainder by default), reason.
curl https://flixypay.net/v1/payments/pay_9fK2…/refunds \ -H "Authorization: Bearer fp_test_sk_…" -d amount=1000
Payment links
POST/v1/links GET/v1/linksCreates a reusable link. Parameters: title, amount, currency. The response contains url, to share as is.
Balance
GET/v1/balanceReturns the account’s pending and available amounts, in the account currency.
Tap to Pay
POST/v1/terminal/connection_tokensReturns a connection token to pass to your mobile app to accept in-person payments. Call it from your server each time the app asks for one.
Webhooks
Add your server URL in Dashboard → Webhooks. Each event is sent as a JSON POST with the header Flixy-Signature: t=timestamp,v1=signature. The signature is an HMAC SHA-256 of “timestamp.body” with the endpoint secret (whsec_…). Respond 2xx quickly.
// 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 */ }
Event types
payment.succeeded | A payment succeeded |
payment.failed | A payment failed |
payment.refunded | A payment was fully or partially refunded |
refund.created | A refund was created |
dispute.created | A customer disputed a payment |
dispute.closed | A dispute was closed |
payout.paid | A payout arrived in the bank account |
account.updated | The account status changed |
link.paid | A payment link was paid |