API reference

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

https://flixypay.net/v1

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_…"
KeyUsage
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:

NumberResult
4242 4242 4242 4242Payment successful
5555 5555 5555 4444Payment succeeds (Mastercard)
4000 0025 0000 31553D Secure authentication required
4000 0000 0000 9995Declined: insufficient funds
4000 0000 0000 0002Declined: 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" }
}
400Missing or invalid parameter
401Missing, invalid or revoked key
403Account suspended or live mode not yet enabled
404Resource not found
429Too many requests, try again in a moment

Payments

POST/v1/payments

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

Refunds 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

Balance

GET/v1/balance

Returns the account’s pending and available amounts, in the account currency.

Tap to Pay

POST/v1/terminal/connection_tokens

Returns 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.succeededA payment succeeded
payment.failedA payment failed
payment.refundedA payment was fully or partially refunded
refund.createdA refund was created
dispute.createdA customer disputed a payment
dispute.closedA dispute was closed
payout.paidA payout arrived in the bank account
account.updatedThe account status changed
link.paidA payment link was paid