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 headerIdempotent-Replayed: true; reusing a key with a different body returns422 idempotency_mismatch. - Rate limit: 120 requests per minute per account. Exceeding it returns
429withRetry-After. - Pagination:
?limit=(1–100, default 20) and?page=. Lists returntotalandhas_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." }
}
}
| HTTP | Code | When |
|---|---|---|
| 400 | invalid_json, invalid_idempotency_key | Malformed request |
| 401 | invalid_api_key | Missing, wrong or revoked key |
| 402 | plan_limit_reached | Monthly live transaction limit of your plan reached |
| 403 | insufficient_scope, live_not_enabled, merchant_inactive | Not allowed |
| 404 | not_found | Unknown ID (or belongs to the other mode) |
| 409 | duplicate_order_id, request_in_progress | Conflict |
| 422 | validation_error, amount_exceeds_refundable, partial_not_supported, idempotency_mismatch | Semantic error |
| 429 | rate_limited | Too many requests |
| 500 | server_error | Our fault — retry with the same Idempotency-Key |
Create a checkout
payments:write
| Field | Type | |
|---|---|---|
order_id | string, required | Your reference, unique per mode. 1–100 chars A-Z a-z 0-9 . _ - / # |
amount | string, required | e.g. "1500.00" |
currency | string | BDT (default) or USD |
customer | object | name, email, phone — optional, shown on checkout |
return_url | https URL | Where the customer goes after a verified payment |
cancel_url | https URL | Where the customer goes if they cancel |
metadata | object | Up to 4 KB, returned in responses and webhooks |
expires_in_minutes | integer | 5–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
payments:read
Returns the current payment object.
Verify a payment
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
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 }
Payment links
links:write
title | required |
amount_type | fixed (default) or customer_entered |
amount | for fixed links without items |
min_amount, max_amount | bounds for customer-entered amounts |
items | [{"name","unit_price","quantity","max_quantity"}] — customer chooses quantities |
usage_limit | max successful payments (omit for unlimited) |
expires_at | YYYY-MM-DD HH:MM in Asia/Dhaka |
collect_name, collect_email, collect_phone | booleans, default true |
description, currency, customer_reference | optional |
links:read
Returns {"id": "plink_…", "url": "https://payfly.site/pay/…", "active": true, "usage_count": 0, …}.
Refunds
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
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"
}
}