​

Step-by-Step Integration Guide

​

1. Initial Configuration

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

​

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

​

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

• 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)

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.