Skip to content
Guide

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

Never fulfil an order based on the query string alone. Anyone can type ?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 a payment.completed webhook 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

  1. Submit KYC / Verification in your dashboard.
  2. After approval, create a pf_live_ key and a live webhook endpoint.
  3. Swap the key on your server. Your code doesn't change.
  4. 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.