Integration guide
Accept your first payment in about 30 minutes. Examples use plain PHP with cURL; any language that can make HTTPS requests works.
1. Get a test API key
Create an account, verify your email, then open Dashboard → API Keys and create a test key. Copy it immediately — it's shown only once. Store it in your server's environment, e.g. PAYFLY_KEY.
2. Create a checkout from your server
<?php
function payfly(string $method, string $path, ?array $body = null): array {
$ch = curl_init('https://payfly.site/api/v1' . $path);
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => $method,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => array_filter([
'Authorization: Bearer ' . getenv('PAYFLY_KEY'),
'Content-Type: application/json',
$body && isset($body['order_id']) ? 'Idempotency-Key: ' . $body['order_id'] : null,
]),
CURLOPT_POSTFIELDS => $body ? json_encode($body) : null,
CURLOPT_TIMEOUT => 20,
]);
$res = json_decode((string) curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);
if ($status >= 400) {
throw new RuntimeException($res['error']['message'] ?? 'Payfly error');
}
return $res;
}
$payment = payfly('POST', '/checkout', [
'order_id' => 'ORDER-' . $order->id, // unique per order
'amount' => number_format($order->total, 2, '.', ''),
'currency' => 'BDT',
'customer' => ['name' => $order->name, 'email' => $order->email, 'phone' => $order->phone],
'return_url' => 'https://yourshop.com/payfly/return',
'cancel_url' => 'https://yourshop.com/cart',
'metadata' => ['cart_id' => $order->cart_id],
]);
// Save $payment['id'] (pay_…) against your order.
Send amounts as strings with two decimals. The Idempotency-Key header makes retries safe: repeating the same request returns the same payment instead of creating a new one.
3. Redirect the customer
header('Location: ' . $payment['checkout_url'], true, 303);
exit;
The customer chooses a method and pays on the provider's page. Payfly then verifies the payment and sends the customer to your return_url with payment_id, order_id and status query parameters.
4. Verify on your return page
?status=paid into a URL.<?php // https://yourshop.com/payfly/return
$result = payfly('POST', '/payments/verify', ['payment_id' => $_GET['payment_id'] ?? '']);
$order = findOrderByPayflyId($result['id']); // your lookup
if ($result['verified'] && $result['amount'] === $order->totalString()) {
markOrderPaid($order, $result['transaction']['id']); // idempotent!
echo 'Thank you! Payment received.';
} elseif ($result['status'] === 'processing') {
echo 'We are confirming your payment…';
} else {
echo 'Payment not completed.';
}
5. Handle webhooks
Add an endpoint in Dashboard → Webhooks and copy its signing secret. Webhooks reach you even if the customer closes their browser, so treat them as the source of truth.
<?php // https://yourshop.com/payfly/webhook
$secret = getenv('PAYFLY_WEBHOOK_SECRET');
$body = file_get_contents('php://input');
$header = $_SERVER['HTTP_PAYFLY_SIGNATURE'] ?? '';
if (!preg_match('/t=(\d+),v1=([a-f0-9]{64})/', $header, $m)
|| abs(time() - (int) $m[1]) > 300
|| !hash_equals(hash_hmac('sha256', $m[1] . '.' . $body, $secret), $m[2])) {
http_response_code(400);
exit('invalid signature');
}
$event = json_decode($body, true);
if (alreadyProcessed($event['id'])) { // de-duplicate by event id
http_response_code(200);
exit;
}
if ($event['type'] === 'payment.completed') {
markOrderPaidByPayflyId($event['data']['id'], $event['data']['transaction']['id']);
}
rememberProcessed($event['id']);
http_response_code(200); // any 2xx = delivered
Respond within 10 seconds. Non-2xx responses and timeouts are retried with backoff (1 min, 5 min, 15 min, 1 h, 3 h, 6 h, 12 h, 24 h). You can also retry manually from the dashboard.
6. Test
- Create a checkout with your test key, open the
checkout_url, choose Test Payment (Sandbox) and click Approve → your return page should show paid and apayment.completedwebhook should arrive. - Repeat with Decline →
payment.failed; the checkout lets the customer try again. - Let a checkout expire →
payment.expired. - Refund a test payment from the dashboard or
POST /api/v1/refunds. - Use Send test on the Webhooks page to check your signature code.
7. Go live
- Submit KYC / Verification in your dashboard.
- After approval, create a
pf_live_key and a live webhook endpoint. - Swap the key on your server. Your code doesn't change.
- Make one small real payment and refund it to confirm everything end to end.
Without code
Use Payment Links (share a URL or QR code) or Invoices (emailed to your customer). Both use the same verified checkout and appear in your transactions.