PayxMint API Integration Manual (Complete Developer Reference)
================================================================

1. AUTHENTICATION & IDEMPOTENCY
-------------------------------
Base URL: https://payxmint.com/api/v1
Pass your secret API key in the Authorization header:
  Authorization: Bearer <YOUR_API_KEY>

Idempotency Key (Prevent Double Charges):
Pass a unique UUID or Order ID header on POST /create-intent:
  Idempotency-Key: <UNIQUE_UUID_OR_ORDER_ID>


2. INITIATE PAYMENT (POST /api/v1/create-intent)
------------------------------------------------
curl --request POST \
  --url https://payxmint.com/api/v1/create-intent \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'Idempotency-Key: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d' \
  --header 'Content-Type: application/json' \
  --data '{
    "amount": "1850.00",
    "order_id": "tx_873491023",
    "customer_mobile": "8123456789",
    "customer_email": "johndoe@email.com",
    "redirect_url": "https://merchant.site/thankyou",
    "gateway": "GPAY"
  }'

Sample Response:
{
  "id": "ptx_8f2a9c3d1e",
  "object": "payment_intent",
  "amount": 1850.00,
  "currency": "INR",
  "status": "PENDING",
  "order_id": "tx_873491023",
  "checkout_url": "https://payxmint.com/pay/ptx_8f2a9c3d1e",
  "payment_token": "ptx_8f2a9c3d1e",
  "upi_link": "upi://pay?pa=merchant@upi&pn=Store&am=1850.00&cu=INR&tn=tx_873491023&tr=tx_873491023",
  "upi_links": {
    "upi": "upi://pay?pa=merchant@upi...",
    "gpay": "intent://...",
    "phonepe": "phonepe://...",
    "paytm": "paytmmp://..."
  },
  "qr_data": "upi://pay?pa=merchant@upi&pn=Store&am=1850.00&cu=INR&tn=tx_873491023&tr=tx_873491023",
  "metadata": {},
  "created": 1779187312
}


3. PAYMENT STATUS (POST or GET /api/v1/check-status)
----------------------------------------------------
curl --request POST \
  --url https://payxmint.com/api/v1/check-status \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "order_id": "tx_873491023"
  }'

Sample Response:
{
  "id": "ptx_8f2a9c3d1e",
  "object": "payment_intent",
  "amount": 1850.00,
  "currency": "INR",
  "status": "SUCCESS",
  "order_id": "tx_873491023",
  "payer": {
    "name": "John Doe",
    "upi": "johndoe@ybl"
  },
  "settlement": {
    "utr": "6120948375",
    "txn_id": "tx_612093847",
    "timestamp": "2026-05-19T17:11:45.000Z"
  }
}


4. WEBHOOKS & MANDATORY DOUBLE-CREDIT SAFETY NET
-------------------------------------------------
WARNING: Payment systems operate under at-least-once delivery guarantees.
Always implement the following 4-point idempotency safety net:

1. Check Status Before Crediting: If order_id is already SUCCESS in your DB, return HTTP 200 without crediting again.
2. Unique DB Index: Enforce a UNIQUE constraint on order_id / utr.
3. Atomic Transactions: Wrap balance increments inside BEGIN ... COMMIT.
4. Return HTTP 200: Always acknowledge webhook receipt so retries halt.

Node.js Verification & Idempotency Example:
------------------------------------------
const crypto = require('crypto');

function handleWebhook(req, res) {
  const signature = req.headers['x-payxmint-signature'];
  const rawBody = req.rawBody;

  const expectedSignature = crypto
    .createHmac('sha256', process.env.PAYXMINT_WEBHOOK_SECRET)
    .update(rawBody)
    .digest('hex');

  if (signature !== expectedSignature) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  const { order_id, amount, utr } = JSON.parse(rawBody);

  // Safety net: check if already credited
  const order = await db.orders.findOne({ order_id });
  if (!order || order.status === 'SUCCESS') {
    return res.status(200).json({ status: 'already_processed' });
  }

  // Atomic database transaction
  await db.transaction(async (tx) => {
    await tx.orders.update({ where: { order_id }, data: { status: 'SUCCESS', utr } });
    await tx.wallets.increment({ where: { userId: order.userId }, data: { balance: amount } });
  });

  return res.status(200).json({ status: 'success' });
}


5. CUSTOM CHECKOUT SCREEN (WEB & MOBILE)
----------------------------------------
A. Render Custom QR Code (React):
   import { QRCodeSVG } from 'qrcode.react';
   <QRCodeSVG value={intent.qr_data} size={200} />

B. Mobile Deep Link:
   <a href={intent.upi_link}>Pay with UPI App</a>

C. Client-Side Polling Loop:
   setInterval(async () => {
     const res = await fetch('/api/v1/check-status?order_id=' + orderId);
     const data = await res.json();
     if (data.status === 'SUCCESS') window.location.href = '/success';
   }, 3000);


6. GOOGLE PAY NATIVE INTENT FLOW (HIGH CONVERSION)
---------------------------------------------------
Deliver a seamless, high-conversion payment flow for Google Pay users on Android
devices using native intent image sharing with 100% gateway compatibility.
(Note: Google Pay Intent button is capped at ₹2,000 max; transactions over ₹2,000
use PhonePe, Paytm, or QR scan).

A. Web (React / Vanilla JS):
   function dataURItoFile(dataURI, filename) {
     const arr = dataURI.split(',');
     const mime = arr[0].match(/:(.*?);/)[1];
     const bstr = atob(arr[1]);
     let n = bstr.length;
     const u8arr = new Uint8Array(n);
     while (n--) u8arr[n] = bstr.charCodeAt(n);
     return new File([u8arr], filename, { type: mime });
   }

   async function handleGPayClick(qrDataUrl) {
     const file = dataURItoFile(qrDataUrl, 'payment_card.png');
     if (navigator.canShare && navigator.canShare({ files: [file] })) {
       await navigator.share({ files: [file], title: 'Pay with Google Pay' });
     } else {
       openQrModal(qrDataUrl); // Fallback modal for desktop
     }
   }

B. React Native:
   import Share from 'react-native-share';
   await Share.open({ url: qrBase64, type: 'image/png', title: 'Pay with Google Pay' });

C. Flutter:
   import 'package:share_plus/share_plus.dart';
   Share.shareXFiles([XFile(filePath)], text: 'Pay with Google Pay');

D. Android Native (Kotlin):
   val intent = Intent(Intent.ACTION_SEND).apply {
       type = "image/png"
       putExtra(Intent.EXTRA_STREAM, qrFileUri)
       addFlags(Intent.FLAG_GRANT_READ_URI_PERMISSION)
   }
   startActivity(Intent.createChooser(intent, "Pay with Google Pay"))

E. Universal 5:4 Safe-Zone Standard:
   Format voucher images at 1000 x 800px (5:4 aspect ratio) with 85% safe zone
   to guarantee full-bleed display on Samsung (1:1), Xiaomi (4:3), and Pixel (16:9).


7. WEBHOOK EVENT LOGS (GET /api/v1/events)
------------------------------------------
curl --request GET \
  --url 'https://payxmint.com/api/v1/events?limit=10&offset=0' \
  --header 'Authorization: Bearer <YOUR_API_KEY>'


Support: support@payxmint.com
================================================================