FalconPay Global Payin API

Key Features

• Multi-country payment processing — Europe, India, LATAM, Brazil
• Real-time order status tracking — Instant payment status updates
• Webhook notifications — Signed real-time event delivery
• HMAC-SHA512 authentication — Enterprise-grade request signing
• RESTful design — Standard HTTP methods and JSON payloads
• Stablecoin settlement — USDT/USDC across multiple chains

Authentication

All API requests require authentication using a custom header-based system with HMAC-SHA512 signature verification. This ensures every request is cryptographically verified and protected against replay attacks.

Authentication Headers

Authentication Process

Payload Structure

{
  "timestamp": 1751294199081,
  "body": {
    "amount": 510.50,
    "countryCode": "IN",
    "merchantRecognitionId": "order_xyz_001"
  }
}

Complete Authentication Example — Python

import hmac, hashlib, base64, json, time, requests

API_KEY    = "fp_live_your_api_key"
API_SECRET = "fp_secret_your_secret"

def build_headers(body: dict) -> dict:
    payload = json.dumps({
        "timestamp": int(time.time() * 1000),
        "body": body
    })
    encoded = base64.b64encode(payload.encode()).decode()
    sig = hmac.new(
        API_SECRET.encode(),
        encoded.encode(),
        hashlib.sha512
    ).hexdigest()
    return {
        "X-Payin-Apikey":     API_KEY,
        "X-Payin-Payload":   encoded,
        "X-Payin-Signature": sig,
        "Content-Type":      "application/json"
    }

Order APIs

Create and track payment orders. These endpoints handle the core payment flow from initiation to completion.

Create Order

Initiates a new payment order. Returns a payment URL or order details for the customer to complete the payment.

{
  "amount": 510.50,
  "countryCode": "IN",
  "merchantRecognitionId": "your_unique_order_id"
}

{
  "success": true,
  "orderId": 12345,
  "merchantRecognitionId": "your_unique_order_id",
  "amount": 510.50,
  "countryCode": "IN",
  "status": "pending",
  "paymentUrl": "https://pay.falconpay.io/order/12345",
  "createdAt": "2025-07-10T10:30:00Z"
}

Get Order Status

Retrieves the current status and full details of an existing payment order.

{
  "searchBy": "orderId",
  "searchValue": 12345
}

{
  "success": true,
  "orderId": 12345,
  "merchantRecognitionId": "your_unique_order_id",
  "amount": 510.50,
  "countryCode": "IN",
  "status": "completed",
  "transactionId": "txn_abc123def456",
  "paymentMethod": "UPI",
  "createdAt": "2025-07-10T10:30:00Z",
  "completedAt": "2025-07-10T10:31:42Z"
}

Merchant APIs

Manage your merchant account settings, webhook configuration, and transaction history.

Set Webhook URL

Configures the HTTPS endpoint where FalconPay will deliver real-time payment event notifications.

{
  "webhookUrl": "https://yourapp.com/webhooks/falconpay"
}

Get Webhook URL

Retrieves the currently configured webhook URL for your merchant account.

{
  "success": true,
  "webhookUrl": "https://yourapp.com/webhooks/falconpay",
  "status": "active",
  "lastDelivery": "2025-07-10T08:22:11Z"
}

Get Order History

Retrieves a paginated list of orders for your merchant account within a specified date range.

{
  "from":   "2025-01-01",
  "upto":   "2025-07-10",
  "pageNo": "1"
}

Get Supported Countries

Returns the complete list of countries supported by FalconPay with their available features.

{
  "success": true,
  "countries": [
    {
      "code":     "IN",
      "name":     "India",
      "payIn":    true,
      "payOut":   true,
      "currency": "INR"
    },
    {
      "code":     "BR",
      "name":     "Brazil",
      "payIn":    true,
      "payOut":   true,
      "currency": "BRL"
    }
  ]
}

Error Handling

FalconPay uses standard HTTP status codes to indicate the success or failure of each request. All error responses follow a consistent JSON structure.

HTTP Status Codes

Error Response Format

{
  "success":   false,
  "error":     true,
  "code":      "INVALID_SIGNATURE",
  "message":   "Request signature verification failed",
  "timestamp": "2025-07-10T10:30:00Z"
}

Common Error Codes

Webhook Notifications

When a webhook URL is configured, FalconPay sends signed POST requests to your endpoint for all significant payment events.

Event Types

Webhook Payload

{
  "event":                 "payment.completed",
  "orderId":              12345,
  "merchantRecognitionId": "your_unique_order_id",
  "amount":               510.50,
  "currency":             "INR",
  "status":               "completed",
  "transactionId":        "txn_abc123def456",
  "paymentMethod":         "UPI",
  "timestamp":            "2025-07-10T10:31:42Z"
}

Verifying Webhook Signatures — Python

import hmac, hashlib
from flask import request, abort

API_SECRET = "fp_secret_your_secret"

def verify_webhook(req):
    received_sig = req.headers.get("X-Payin-Signature", "")
    payload      = req.headers.get("X-Payin-Payload", "")

    expected_sig = hmac.new(
        API_SECRET.encode(),
        payload.encode(),
        hashlib.sha512
    ).hexdigest()

    if not hmac.compare_digest(received_sig, expected_sig):
        abort(401, "Invalid webhook signature")

    return True

# In your Flask route:
@app.route("/webhooks/falconpay", methods=["POST"])
def webhook_handler():
    verify_webhook(request)
    data = request.get_json()
    # Process event...
    return "", 200

Integration Guide

Best Practices

• Always use HTTPS — All API requests must be made over TLS.
• Store credentials securely — Use environment variables or a secrets manager. Never hardcode API keys.
• Handle timeouts gracefully — Set a 30-second timeout on API calls. Implement exponential backoff for retries.
• Use webhooks for status — Don't poll order status; use webhooks for real-time updates.
• Log all interactions — Log request/response pairs (excluding secrets) for debugging and audit.
• Idempotent order IDs — Use unique, meaningful merchantRecognitionId values to prevent duplicates.
• Test in sandbox first — Validate your full integration before going to production.

Rate Limiting

Rate limits are defined per your merchant agreement. The following headers are returned on every response:

Complete Integration Checklist

• Received API key and secret from FalconPay team
• Implemented HMAC-SHA512 request signing
• Tested POST /order/create in sandbox
• Tested POST /order/status polling
• Configured HTTPS webhook endpoint
• Verified webhook signature validation
• Handled all order status transitions
• Implemented retry logic with exponential backoff
• Reviewed error handling for all error codes
• Confirmed production credentials with FalconPay

Support

Contact Channels

When Contacting Support, Include:

• Your Merchant ID
• The full request body (redact API secrets)
• The full response body including error codes
• Timestamps of the affected requests
• Steps to reproduce the issue
• SDK / language and version you are using