FlyExpense Developer Platform

Getting Started — Base URL & Test Credentials

All Payment Gateway API requests go to the base URL: https://flyexpense.com/pf/v1 Use sandbox credentials to test without processing real payments.

• Base URL: https://flyexpense.com/pf/v1
• Sandbox Client ID: pf_test_client_flyexpense_sandbox_2024
• Sandbox Client Secret: sk_test_51ABC123XYZ789DEF456GHI000JKL111MNO222PQR333
• Sandbox credentials only work in TEST mode — create an account for production keys
• Multi-PSP support: Stripe, iyzico, PayTR, and 36 more with automatic failover
• Built-in 3D Secure 2 authentication (SCA/PSD2 compliant)
• Smart routing: automatic provider selection with failover logic

Authentication — Required Headers

All Payment Gateway API requests require three headers: your Client ID, an HMAC-SHA256 signature, and a Unix timestamp in milliseconds. Signature = HMAC-SHA256(timestamp + requestBody, clientSecret).

• x-client-id: your API Client ID
• x-signature: HMAC-SHA256 of (timestamp + JSON request body) using your Client Secret
• x-timestamp: Unix timestamp in milliseconds (must be current — requests older than 5 minutes are rejected)
• Content-Type: application/json
• Node.js: crypto.createHmac('sha256', CLIENT_SECRET).update(timestamp + JSON.stringify(body)).digest('hex')
• Python: hmac.new(secret.encode(), (timestamp + json.dumps(body)).encode(), hashlib.sha256).hexdigest()
• PHP: hash_hmac('sha256', timestamp . json_encode(body), CLIENT_SECRET)

Authorize Payment — POST /pf/v1/payments/authorize

Create a new payment authorization. The system automatically routes to the best available provider based on currency, country, and provider availability.

• amount (number, required): total payment amount
• currency (string, required): ISO currency code — USD, EUR, TRY, AED, GBP
• merchantReference (string, required): your unique order/reference ID
• cardNumber / cardExpMonth / cardExpYear / cardCvc (string, required): card details
• is3DS (boolean, optional): enable 3D Secure — default false
• returnUrl (string, optional): callback URL for 3DS verification
• installment (number, optional): installment count — 1 means no installment
• buyer.firstName, buyer.lastName, buyer.email (string, required): buyer information
• billingAddress.address, billingAddress.city, billingAddress.country (string, required): billing address

Capture, Refund, Void & Get Transaction

Full payment lifecycle management after authorization.

• POST /pf/v1/payments/:id/capture — capture an authorized payment (transactionId required)
• POST /pf/v1/payments/:id/refund — refund a captured payment (amount optional for partial refund)
• POST /pf/v1/payments/:id/void — void an authorized but uncaptured payment
• GET /pf/v1/payments/:id — retrieve transaction status, provider response, and metadata
• All endpoints return: transactionId, status, amount, currency, provider, pspResponseCode

Error Codes & Test Cards

Standard error codes and test card numbers for sandbox testing.

• INSUFFICIENT_FUNDS: card declined due to insufficient funds — test with card 4111111111111112
• CARD_DECLINED: generic card decline — test with card 4111111111111113
• INVALID_CARD: card number/expiry/CVC invalid
• 3DS_FAILED: 3D Secure authentication failed
• PROVIDER_ERROR: upstream provider returned an error
• TIMEOUT: provider did not respond within the timeout window
• Success test card: 4111111111111111, expiry 12/2025, CVC 123

AI Assistant — Connect Claude & Cursor via MCP

FlyExpense provides a read-only MCP server so AI assistants can query your finance data in natural language. MCP server URL: https://flyexpense.com/mcp

• claude.ai web (online): Settings → Connectors → Add custom connector → paste https://flyexpense.com/mcp → sign in with FlyExpense account (OAuth 2.1, no token needed)
• Claude Desktop / Cursor: create an mcp_ token on the Developer page, add to MCP config as Authorization: Bearer <token>
• AI assistants can query expenses, cards, bills, vendors, reports, and dashboard stats
• Strictly read-only: AI cannot create, update, or delete any data
• All access is org-isolated: assistants only see your organization's data

Webhooks

Subscribe to real-time events from FlyExpense to trigger automations in your own systems. All payloads are signed with HMAC-SHA256.

• expense.submitted, expense.approved, expense.rejected
• card.transaction, card.frozen, card.limit_exceeded
• bill.received, bill.approved, bill.paid
• approval.requested, approval.completed
• Signed payloads with HMAC-SHA256 — validate the x-flyexpense-signature header
• Configurable retry with exponential backoff on delivery failure

Frequently Asked Questions