Express Setup

Learn how to integrate Okito payments into your Express.js backend using the @okito/core package.

Prerequisites

Node.js 18+ installed
Basic knowledge of Express.js and TypeScript
An Okito API key (get one from app.okito.dev )

Installation

Install the required dependencies:


npm install @okito/core express dotenv
npm install -D @types/express @types/node tsx typescript
# or
yarn add @okito/core express dotenv
yarn add -D @types/express @types/node tsx typescript
# or
pnpm add @okito/core express dotenv
pnpm add -D @types/express @types/node tsx typescript

Project Structure

Your Express project should have the following structure:


your-express-app/
├── src/
│   ├── routes/
│   │   ├── okito.ts          # Payment session creation
│   │   └── webhook.ts        # Payment webhook handling
│   ├── server.ts             # Main server file
│   └── utils/
│       └── webhook.ts         # Webhook utilities
├── package.json
├── tsconfig.json
└── .env                      # Environment variables

Environment Variables

Create a .env file in your project root:


OKITO_API_KEY=your_okito_api_key_here
WEBHOOK_SECRET=your_webhook_secret_here

Payment Session Route

Create the payment session route at src/routes/okito.ts:


import { Router, Request, Response } from "express";
import { createPaymentSession } from "@okito/core";
 
const router: Router = Router();
 
router.post("/", async (req: Request, res: Response) => {
  try {
    const { products } = req.body ?? {};
    
 
    const session = await createPaymentSession({ 
      products, 
      apiKey: process.env.OKITO_API_KEY!
    });
    
    if (!session) {
      return res.status(500).json({ error: "Failed to create payment session" });
    }
 
    return res.status(200).json(session);
  } catch (_err) {
    return res.status(500).json({ error: "Internal server error" });
  }
});
 
export default router;

Webhook Handling

Create the webhook route at src/routes/webhook.ts:


import { Router, Request, Response } from "express";
 
const router: Router = Router();
 
router.post("/", async (req: Request, res: Response) => {
  try {
    // Simple auth header verification
    const authHeader = req.headers['authorization'];
    
    if (!authHeader || authHeader !== process.env.OKITO_WEBHOOK_SECRET) {
      return res.status(401).json({ error: 'Unauthorized' });
    }
    
    // Process your webhook data however you want
    console.log('Webhook received:', req.body);
    
    return res.status(200).json({ received: true });
  } catch (err) {
    return res.status(400).json({ error: "Webhook processing failed" });
  }
});
 
export default router;

Best Practices

Always validate input before processing payment requests
Use HTTPS in production environments
Implement proper error handling with appropriate HTTP status codes
Log all payment-related events for debugging and monitoring
Use environment variables for sensitive configuration
Implement rate limiting to prevent abuse
Verify webhook signatures to ensure authenticity
Test thoroughly in development before production deployment

Troubleshooting

Common Issues

Payment session creation fails:

Check if your API key is valid and properly set
Ensure the products array is correctly formatted
Verify your Express server is running and accessible

Webhook not received:

Check if your webhook URL is publicly accessible
Verify the webhook secret is correctly configured
Ensure your server can handle POST requests to the webhook endpoint

CORS issues:

Configure CORS properly for your frontend domain
Check if preflight requests are handled correctly

Next Steps

Visit our GitHub repository for examples and updates

Support

Need help? Reach out to us:

GitHub: @Playground
Twitter: @OkitoLabs