> ## 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 guide

# 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](https://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)

```javascript theme={null}
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)

```javascript theme={null}
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.

```javascript theme={null}
// 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`.