Developer API Reference

Integration Reference

Welcome to the official Keio API documentation. Use this reference to integrate high-fidelity UPI automated payments securely into your applications with zero gateway fees.

Intent Status Codes

PENDINGAwaiting UPI scan

SUCCESSReconciled via UTR

EXPIREDTime window elapsed

Integration Simulator

Simulate successful payment transitions during development by sending an incoming POST request with your active order_id.

POST /api/v1/simulate-payment { "order_id": "your_order_id" }

API Environment Configuration

Authenticate all requests by including your secret API key in the Authorization header.

Production Base URL

https://keio.com/api/v1

Header AuthenticationPass your key as Authorization: Bearer YOUR_API_KEY on every request.

Section 1

Collections & Inbound Payments

POST

1. Initiate Payment (/create-intent)

Creates a new dynamic payment intent and returns the checkout URL alongside high-fidelity raw UPI deep links.

Endpoint URL

https://keio.com/api/v1/create-intent

Request Body Payload

Field	Type	Status
amount	string/number	Required
order_id	string	Optional (Unique ID)
customer_mobile	string	Optional
customer_email	string	Optional
redirect_url	string	Optional
gateway	string	Optional (GPAY, PAYTM, PHONEPE, PINELABS)

Interactive Request

Bash

curl --request POST \
  --url https://keio.com/api/v1/create-intent \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "amount": "5000.00",
    "order_id": "pay_202506038627",
    "customer_mobile": "9898989898",
    "customer_email": "amit_bansal@email.com",
    "redirect_url": "https://merchant.site/thankyou",
    "gateway": "GPAY"
  }'

Sample Response

JSON

{
  "id": "ptx_8f2a9c3d1e",
  "object": "payment_intent",
  "amount": 5000.00,
  "currency": "INR",
  "status": "PENDING",
  "order_id": "pay_202506038627",
  "checkout_url": "https://keio.com/pay/ptx_8f2a9c3d1e",
  "payment_token": "ptx_8f2a9c3d1e",
  "upi_links": {
    "gpay": "intent://...",
    "phonepe": "phonepe://...",
    "paytm": "paytmmp://..."
  },
  "qr_data": "upi://pay?pa=merchant@upi...",
  "created": 1779187312
}

POST

2. Payment Status (/check-status)

Queries and retrieves the exact transaction metadata, settlement details, and collection status using your order_id.

Endpoint URL

https://keio.com/api/v1/check-status

Interactive Request

Bash

curl --request POST \
  --url https://keio.com/api/v1/check-status \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "order_id": "pay_202506038627"
  }'

Sample Response

JSON

{
  "id": "ptx_8f2a9c3d1e",
  "object": "payment_intent",
  "amount": 5000.00,
  "currency": "INR",
  "status": "SUCCESS",
  "order_id": "pay_202506038627",
  "payer": {
    "name": "Amit Bansal",
    "upi": "amit@okaxis"
  },
  "settlement": {
    "utr": "6120948375",
    "txn_id": "tx_612093847",
    "timestamp": "2026-05-19T17:11:45.000Z"
  }
}

SECURITY

3. Process Webhook Data

Verify webhook signatures using HMAC-SHA256 hex digest against your webhook secret to guarantee authentic event delivery.

Cryptographic Headers

X-Keio-Eventpayment.success

X-Keio-SignatureHex-encoded HMAC-SHA256

Verification Implementation (Node.js)

Javascript

const crypto = require('crypto');

function verifyKeioWebhook(req, res) {
  const secret = process.env.KEIO_WEBHOOK_SECRET;
  const signature = req.headers['x-keio-signature'];
  const rawBody = req.rawBody;

  const expected = crypto.createHmac('sha256', secret).update(rawBody).digest('hex');

  if (crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) {
    // Process verified event
    const event = req.body;
    console.log('Payment successful for:', event.order_id, 'UTR:', event.utr);
    res.status(200).json({ status: 'success' });
  } else {
    res.status(400).json({ error: 'Invalid signature' });
  }
}

NATIVE

4. Custom Checkout Screen

Render the QR code directly inside your own application or trigger native mobile UPI apps.

React / JSX

import { QRCodeSVG } from 'qrcode.react';

function CustomUPIQR({ qr_data, amount }) {
  return (
    <div className="p-6 border border-slate-200 rounded-2xl text-center bg-white shadow-sm">
      <h3 className="text-sm font-bold text-[#0A2540] mb-4">
        Scan to Pay: ₹${amount}
      </h3>
      <div className="flex justify-center my-4">
        <QRCodeSVG value={qr_data} size={200} includeMargin={true} />
      </div>
      <p className="text-xs text-slate-400 font-medium">
        Scan using GPay, PhonePe, Paytm, or BHIM
      </p>
    </div>
  );
}

NO-CODE

5. eCommerce Plugins

Integrate Keio into WooCommerce or Shopify in minutes without writing code.

WooCommerce / WordPress

Full Gateway Integration

Download the official WooCommerce plugin
Upload via Plugins → Add New
Activate Keio Payment Gateway
Enter your API Keys in Settings

Download Plugin (.zip)

Shopify App

Coming Soon

Offsite Payment Gateway

Official Shopify App Store integration currently undergoing app review. Available soon.