Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.fype.dev/llms.txt

Use this file to discover all available pages before exploring further.

​
Step-by-Step Integration Guide

This guide provides a linear, definitive path to integrating Fype into your application. Following these steps ensures a secure and resilient implementation.

​
1. Initial Configuration

Before writing any code, prepare your Fype environment:
  1. Create a Merchant Account: Sign up at dashboard.fype.dev.
  2. Obtain Test Keys: Go to Developers > API Keys and generate a test key (fype_test_...).
  3. Connect a Provider: Even for testing, ensure a provider is “connected.” Use the Simulator for zero-config testing or connect Razorpay Sandbox for a more realistic flow.
  4. Configure a Local Webhook Tunnel: Use a tool like ngrok or localtunnel to expose your local server (e.g., https://your-tunnel.ngrok-free.app/webhooks/fype). Add this URL in Developers > Webhooks.

​
2. Server-Side: Create a Payment

When a customer clicks “Checkout” on your site, your backend must call Fype to create a payment intent. Never call this API from the frontend/browser.

​
Request Construction

  • Amount: Must be in subunits (e.g., 50000 for ₹500.00).
  • Reference ID: Pass your internal Order ID for reconciliation.
  • Idempotency: Always send an Idempotency-Key to prevent duplicate charges.

​
Example (Node.js)

const payment = await fype.payments.create({
  amount: order.totalAmount,
  currency: 'INR',
  customer_email: user.email,
  reference_id: order.id,
  success_url: 'https://myapp.com/success?order_id={PAYMENT_ID}',
  cancel_url: 'https://myapp.com/checkout',
}, {
  idempotencyKey: `order_${order.id}`
});

// Store the Fype payment.id in your database linked to your order
await db.orders.update(order.id, { fypePaymentId: payment.id });

return { checkoutUrl: payment.checkout_url };

​
3. Client-Side: Redirection

Once your server receives the checkout_url, send it to your frontend and redirect the customer.

​
Example (Frontend JS)

const response = await api.post('/create-fype-payment', { cartItems });
const { checkoutUrl } = await response.json();

// Redirect to Fype's hosted checkout
window.location.href = checkoutUrl;

​
4. Handle Redirection Back to Your Site

After the payment is processed (or cancelled), Fype redirects the customer back to your success_url or cancel_url.
  • Success URL: Use this page to show a “Payment Received” message. Do not fulfill the order yet. Statuses can still change (e.g., a capture could fail later).
  • Placeholders: Use {PAYMENT_ID} in your URL to know which order the user is returning from.

​
5. Secure Order Fulfillment (Webhooks)

This is the most critical step. Your server must listen for Fype webhooks to update your database and trigger fulfillment (shipping, digital access, etc.).
  1. Receive the POST request: Listen on your configured webhook URL.
  2. Verify the Signature: Use the X-Fype-Signature and your whsec_ secret. If invalid, return 401.
  3. Check the Event Type:
    • payment.succeeded: Mark the order as PAID in your DB.
    • payment.failed: Notify the user or mark the order as FAILED.
  4. Acknowledge: Return a 200 OK response immediately to stop Fype from retrying.
// Example Webhook Logic
if (event.type === 'payment.succeeded') {
  const fypePayment = event.data.object;
  const myOrder = await db.orders.findByFypeId(fypePayment.id);
  
  if (myOrder.status !== 'PAID') {
    await fulfillOrder(myOrder);
    await db.orders.update(myOrder.id, { status: 'PAID' });
  }
}

​
6. Testing the Flow

  1. Use the Simulator: In the Fype Checkout page (Test Mode), click Simulate Success.
  2. Verify Webhook: Check your server logs to ensure the signature was verified and the database was updated.
  3. Verify Dashboard: Go to the Fype Dashboard and ensure the payment status shows as Succeeded.

​
7. Moving to Production

  1. Switch Modes: Toggle to Live Mode in the Fype Dashboard.
  2. Connect Live Provider: Add your production Razorpay Key ID and Key Secret.
  3. Generate Live API Key: Use this key (fype_live_...) in your production environment variables.
  4. Live Webhook: Add your production webhook URL and update your FYPE_WEBHOOK_SECRET.