Skip to content
Reference

API reference

Base URL: https://payfly.site/api/v1 · JSON in, JSON out · HTTPS only.

Authentication

Send your secret key as a Bearer token. The key's prefix decides the mode: pf_test_ works only with test data, pf_live_ only with live data.

Authorization: Bearer pf_test_AbCd1234_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Keys carry scopes: payments:write, payments:read, links:write, links:read, refunds:write, transactions:read, invoices:read. Each endpoint below lists the scope it needs.

Conventions

  • Amounts are strings with up to two decimals, e.g. "1500.00". Currencies: BDT, USD.
  • Timestamps are ISO 8601 in UTC.
  • Idempotency: send Idempotency-Key: <unique string> on POST requests. Replays return the original response with header Idempotent-Replayed: true; reusing a key with a different body returns 422 idempotency_mismatch.
  • Rate limit: 120 requests per minute per account. Exceeding it returns 429 with Retry-After.
  • Pagination: ?limit= (1–100, default 20) and ?page=. Lists return total and has_more.

Errors

HTTP/1.1 422 Unprocessable Entity
{
  "error": {
    "code": "validation_error",
    "message": "The request is invalid.",
    "details": { "amount": "Must be a positive amount with at most 2 decimals." }
  }
}
HTTPCodeWhen
400invalid_json, invalid_idempotency_keyMalformed request
401invalid_api_keyMissing, wrong or revoked key
402plan_limit_reachedMonthly live transaction limit of your plan reached
403insufficient_scope, live_not_enabled, merchant_inactiveNot allowed
404not_foundUnknown ID (or belongs to the other mode)
409duplicate_order_id, request_in_progressConflict
422validation_error, amount_exceeds_refundable, partial_not_supported, idempotency_mismatchSemantic error
429rate_limitedToo many requests
500server_errorOur fault — retry with the same Idempotency-Key

Create a checkout

POST/api/v1/checkout
scope payments:write
FieldType
order_idstring, requiredYour reference, unique per mode. 1–100 chars A-Z a-z 0-9 . _ - / #
amountstring, requirede.g. "1500.00"
currencystringBDT (default) or USD
customerobjectname, email, phone — optional, shown on checkout
return_urlhttps URLWhere the customer goes after a verified payment
cancel_urlhttps URLWhere the customer goes if they cancel
metadataobjectUp to 4 KB, returned in responses and webhooks
expires_in_minutesinteger5–10080, default 30
curl -X POST https://payfly.site/api/v1/checkout \
  -H "Authorization: Bearer $PAYFLY_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ORDER-10001" \
  -d '{"order_id":"ORDER-10001","amount":"1500.00","currency":"BDT",
       "customer":{"name":"Test Customer","email":"customer@example.com","phone":"01700000000"},
       "return_url":"https://merchant.example.com/payment/return",
       "cancel_url":"https://merchant.example.com/payment/cancel"}'

Returns 201 with a payment object. Redirect the customer to checkout_url.

Retrieve a payment

GET/api/v1/payments/{id}
scope payments:read

Returns the current payment object.

Verify a payment

POST/api/v1/payments/verify
scope payments:read

Body: {"payment_id": "pay_…"} or {"order_id": "ORDER-10001"}. If a payment is still processing, Payfly asks the provider for the latest status before responding. The response is the payment object plus "verified": true|false — fulfil only when verified is true and the amount matches your order.

List transactions

GET/api/v1/transactions
scope transactions:read

Filters: status (paid, refund_pending, partially_refunded, refunded), from, to (YYYY-MM-DD, UTC), limit, page.

{ "object": "list", "data": [ { "id": "txn_…", "payment_id": "pay_…", "order_id": "ORDER-10001",
  "amount": "1500.00", "fee": "0.00", "net": "1500.00", "refunded_amount": "0.00", "currency": "BDT",
  "method": "bkash", "gateway_reference": "…", "status": "paid", "paid_at": "…" } ],
  "page": 1, "limit": 20, "total": 1, "has_more": false }
POST/api/v1/payment-links
scope links:write
titlerequired
amount_typefixed (default) or customer_entered
amountfor fixed links without items
min_amount, max_amountbounds for customer-entered amounts
items[{"name","unit_price","quantity","max_quantity"}] — customer chooses quantities
usage_limitmax successful payments (omit for unlimited)
expires_atYYYY-MM-DD HH:MM in Asia/Dhaka
collect_name, collect_email, collect_phonebooleans, default true
description, currency, customer_referenceoptional
GET/api/v1/payment-links/{id}
scope links:read

Returns {"id": "plink_…", "url": "https://payfly.site/pay/…", "active": true, "usage_count": 0, …}.

Refunds

POST/api/v1/refunds
scope refunds:write

Body: {"transaction_id": "txn_…", "amount": "500.00", "reason": "Customer returned item"}. Omit amount to refund the full remaining balance. The refund starts as requested (live refunds may need approval) and becomes completed only when the provider or Payfly operations confirms it — listen for refund.completed / refund.failed.

Invoices

GET/api/v1/invoices/{id}
scope invoices:read

{id} is inv_… or the invoice number (e.g. INV-2026-00001). Returns status, totals, amount_paid, items and the customer url.

Webhooks

Events: payment.created, payment.pending, payment.completed, payment.failed, payment.expired, refund.created, refund.completed, refund.failed, invoice.paid.

POST /your/webhook
Content-Type: application/json
Payfly-Event-Id: evt_…
Payfly-Event-Type: payment.completed
Payfly-Signature: t=1760700000,v1=5f2b…(hex HMAC-SHA256)

{ "id": "evt_…", "type": "payment.completed", "created": 1760700000, "livemode": false,
  "data": { …payment object… } }

Verify: compute HMAC_SHA256(secret, t + "." + raw_body), compare with v1 in constant time, and reject if t is more than 300 seconds from now. De-duplicate on id. Return any 2xx within 10 seconds.

The payment object

{
  "id": "pay_3brjdP2tsYY4bVo9YoiWsvEa",
  "object": "payment",
  "livemode": false,
  "order_id": "ORDER-10001",
  "amount": "1500.00",
  "currency": "BDT",
  "status": "paid",
  "source": "api",
  "checkout_url": "https://payfly.site/checkout/…",
  "customer": { "name": "Test Customer", "email": "customer@example.com", "phone": "01700000000" },
  "metadata": null,
  "expires_at": "2026-01-01T10:30:00+00:00",
  "paid_at": "2026-01-01T10:05:12+00:00",
  "created_at": "2026-01-01T10:00:00+00:00",
  "transaction": {
    "id": "txn_…", "method": "bkash", "method_name": "bKash",
    "gateway_reference": "…", "fee": "0.00", "net": "1500.00",
    "refunded_amount": "0.00", "status": "paid"
  }
}