Developer Documentation

DEVELOPERS

Integrate Filoosy into your application with our powerful API and SDKs. Accept payments from 400+ banks worldwide across the GCC.

Getting Started

Follow these steps to integrate Filoosy into your application:

  1. 1

    Create a Filoosy account

    Sign up at filoosy.net and complete your merchant verification.

  2. 2

    Get your API keys

    Access your test and live API keys from the merchant dashboard.

  3. 3

    Install an SDK or use the REST API

    Choose your preferred language and start integrating.

  4. 4

    Test in sandbox

    Use test credentials and test card numbers to verify your integration.

// Initialize Filoosy
const filoosy = new Filoosy({
  apiKey: 'pk_live_xxxxxxxxxxxx',
  environment: 'production'
});

// Create a payment
const payment = await filoosy.payments.create({
  amount: 25000, // BD 250.000 in fils
  currency: 'BHD',
  description: 'Order #12345',
  customer: {
    email: 'customer@example.com',
    name: 'Ahmed Al-Khalifa'
  },
  metadata: {
    orderId: '12345'
  }
});

Authentication

All API requests require authentication using your API key. Include your key in the Authorization header as a Bearer token. Use pk_test_ keys for sandbox and pk_live_ for production.

// Authenticate API requests
// Include your API key in the Authorization header
const headers = {
  'Authorization': 'Bearer pk_live_xxxxxxxxxxxx',
  'Content-Type': 'application/json'
};

// Test mode: use pk_test_ prefix
// Live mode: use pk_live_ prefix
// Secret key (server-side only): sk_live_

⚠️ Keep your secret keys safe

Never expose secret keys (sk_) in client-side code. Use them only on your server.

Payments

Create payment sessions to accept payments via credit cards, debit cards, BENEFIT, Apple Pay, Google Pay, and more. Amounts are specified in the smallest currency unit (fils for BHD = 1/1000).

// Create a payment
const payment = await filoosy.payments.create({
  amount: 5000,       // Amount in fils (BD 5.000)
  currency: 'BHD',    // BHD, SAR, AED, KWD, OMR, QAR
  description: 'Invoice #4521',
  customer: {
    email: 'customer@example.com',
    name: 'Fatima Al-Ali'
  },
  redirect_url: 'https://yoursite.com/success',
  cancel_url: 'https://yoursite.com/cancel'
});

// Payment response
// { id: 'pay_xxxxxxx', status: 'pending', checkout_url: '...' }

Supported Currencies

BHDSARAEDKWDOMRQARUSDEURGBP

Refunds

Issue full or partial refunds for completed payments. Refunds are processed back to the original payment method and typically take 5-10 business days.

// Create a full refund
const refund = await filoosy.refunds.create({
  payment_id: 'pay_xxxxxxx',
  reason: 'customer_request'
});

// Create a partial refund
const partialRefund = await filoosy.refunds.create({
  payment_id: 'pay_xxxxxxx',
  amount: 2500, // BD 2.500
  reason: 'partial_return'
});

Webhooks

Webhooks notify your server in real-time when events occur — such as a payment being completed, failing, or a refund being issued. Set up a webhook endpoint in your dashboard and verify signatures for security.

Event Types

payment.created
payment.completed
payment.failed
payment.expired
refund.created
refund.completed
// Webhook endpoint (Node.js / Express)
app.post('/webhooks/filoosy', (req, res) => {
  const signature = req.headers['x-filoosy-signature'];
  const isValid = filoosy.webhooks.verify(
    req.body, signature, webhookSecret
  );

  if (!isValid) return res.status(400).send('Invalid');

  const event = req.body;
  switch (event.type) {
    case 'payment.completed':
      // Handle successful payment
      break;
    case 'payment.failed':
      // Handle failed payment
      break;
    case 'refund.completed':
      // Handle refund
      break;
  }
  res.status(200).send('OK');
});

SDKs & Libraries

Official SDKs are available for popular programming languages. Install via your package manager:

JavaScript

npm install @filoosy/js-sdk

PHP

composer require filoosy/php-sdk

Python

pip install filoosy

Ruby

gem install filoosy

Java

// Maven
<dependency>
  <groupId>net.filoosy</groupId>
  <artifactId>filoosy-java</artifactId>
  <version>2.0.0</version>
</dependency>

.NET

dotnet add package Filoosy

Testing

Use the sandbox environment to test your integration without processing real payments. Test API keys start with pk_test_.

// Use test API keys
const filoosy = new Filoosy({
  apiKey: 'pk_test_xxxxxxxxxxxx',
  environment: 'sandbox'
});

// Test card numbers:
// 4242 4242 4242 4242  - Successful payment
// 4000 0000 0000 0002  - Declined
// 4000 0000 0000 3220  - 3D Secure required

// Test BENEFIT card:
// 9400 1234 5678 9012  - Successful

// All test payments use BD 0.100 minimum

API Endpoints Reference

POST/v1/payments
GET/v1/payments/:id
GET/v1/payments
POST/v1/refunds
GET/v1/refunds/:id
GET/v1/transactions
POST/v1/webhooks
DELETE/v1/tokens/:id

Need Help?

Our developer support team is available 24/7

Contact Developer Support