Skip to content
Developers

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 an order_id. It has a hosted checkout_url and 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 as payment.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

StatusMeaning
pendingCreated; waiting for the customer to pay.
processingThe customer started paying with a provider; Payfly is waiting for confirmation.
paidVerified with the provider. Safe to fulfil the order.
failedThe final attempt failed and the session ended.
cancelledThe customer cancelled before paying.
expiredNot paid before expires_at.

A paid transaction may later be refund_pending, partially_refunded or refunded.

Security model

  • A payment becomes paid only 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_url is a convenience, not proof. Always confirm with POST /api/v1/payments/verify or 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.

Next steps