Payfly documentation
Accept payments on your website or app with hosted checkout, a REST API and signed webhooks.
Core concepts
- Payment (
pay_…) — your request to collect an amount for anorder_id. It has a hostedcheckout_urland expires after a set time. - Attempt — each time the customer tries a payment method. A payment can have several attempts; at most one succeeds.
- Transaction (
txn_…) — the verified money record created when a payment is confirmed by the provider. It holds the gateway reference, fee and net amount. - Refund (
rf_…) — money returned against a transaction (full or partial where the method supports it). - Payment link (
plink_…) and invoice (inv_…) — reusable or one-off ways to create payments without code. - Event (
evt_…) — a webhook notification such aspayment.completed.
Test & live mode
Every account starts in test mode. Test API keys start with pf_test_; the checkout shows a "TEST MODE" banner and offers the Test Payment (Sandbox) method where you choose Approve or Decline. No real money moves.
After your business is verified (KYC) and approved, you can create pf_live_ keys. Live and test data are completely separate.
Payment lifecycle
| Status | Meaning |
|---|---|
pending | Created; waiting for the customer to pay. |
processing | The customer started paying with a provider; Payfly is waiting for confirmation. |
paid | Verified with the provider. Safe to fulfil the order. |
failed | The final attempt failed and the session ended. |
cancelled | The customer cancelled before paying. |
expired | Not paid before expires_at. |
A paid transaction may later be refund_pending, partially_refunded or refunded.
Security model
- A payment becomes
paidonly after Payfly verifies it server-to-server with the provider, inside a database transaction, with the amount and currency checked against your request. - The query string on your
return_urlis a convenience, not proof. Always confirm withPOST /api/v1/payments/verifyor a webhook before fulfilling. - Keep API keys on your server. Never put them in browser JavaScript or mobile apps.
- Verify webhook signatures and ignore events older than five minutes.