Katana Pay — Gateway Integration Kit

Contents

1. Credentials (Key + Salt)

Every merchant account gets its own dedicated Key and Salt, issued from the Katana dashboard (Integration → Generate Key + Salt, or ask your Katana account manager). They are not shared between merchants, and every order and callback is bound to the pair that signed it.

2. Endpoints

3. Create an order

POST /api/v1/katana-pay/order with a JSON body (form-encoded is also accepted). Idempotent on txnid — re-sending the same txnid returns the existing order rather than creating a second one, so a retry after a network timeout is always safe.

Request fields

Response (HTTP 201 new / 200 reused)

{
  "verified": true,
  "merchant": "UK-108",
  "order": { "id": "8d20c0b6-…", "order_id": "ORDER-1001", "amount": 100, "status": "PENDING", … },
  "pay_url": "https://katanapay.co/pay/8d20c0b6-…",   // redirect the customer here
  "deeplinks": { "upi": "upi://pay?…", … },
  "upi_intent": "upi://pay?…",
  "qr_payload": "upi://pay?…"
}

Take pay_url and send the browser there. If you are building your own payment screen instead, use qr_payload (render as a QR) or upi_intent (an app deeplink).

4. Sign the request

Compute hash with the scheme configured on your account (shown next to your Key in the dashboard), then send it as the hash field. You never send the scheme name — Katana already knows which one your account uses.

HMAC_SHA256 (recommended)

message = txnid + "|" + amount + "|" + productinfo + "|" + email
hash    = HMAC_SHA256( key = KEY + SALT , message )      // lowercase hex

Legacy SHA-512 format

Used by accounts migrated from an older checkout. Pipe-joined, with five user-defined fields and five reserved blanks before the salt:

seq  = KEY|txnid|amount|productinfo|firstname|email|||||||||||SALT   // 5 udf + 5 reserved blanks
hash = SHA512(seq)                                       // lowercase hex

5. Redirect to the payment page

Send the customer's browser to the pay_url from the response. The hosted page shows a UPI QR plus app buttons and live status. When the payment is confirmed it automatically redirects back to your return_url with query params:

https://your-site.com/return?order_id=ORDER-1001&status=SUCCESS&rrn=123456789012

6. Receive the status callback

On every terminal status Katana POSTs a JSON body to your notify_url (or your saved webhook URL). Reply HTTP 200. Delivery is queued and retried with backoff until you do, and every attempt is recorded — so a callback is never silently dropped.

Callback body

{
  "PAY_ID": "…", "ORDER_ID": "ORDER-1001", "TXN_ID": "…",
  "AMOUNT": "100", "CURRENCY_CODE": "356",
  "STATUS": "Captured", "RESPONSE_CODE": "000",
  "RRN": "123456789012", "RESPONSE_DATE_TIME": "2026-07-01T…Z",
  "HASH": "716346F5…EC21"
}

Verify the HASH (with your Salt)

1. Take every field except HASH.
2. Sort the keys ascending; join as KEY=value with ~ between pairs.
3. Append your SALT directly to the end of that string.
4. SHA256 it → hex → UPPERCASE. It must equal HASH.

Paid = STATUS is Captured and RESPONSE_CODE is 000.

7. Status enquiry (and long-poll)

At any time: GET /api/pay-status/{order_id}

{ "order_id": "ORDER-1001", "amount": 100, "currency_code": "INR",
  "status": "SUCCESS", "terminal": true, "rrn": "123456789012",
  "mode": "QR", "return_url": "…" }

terminal: true means the order has reached a final state and will not change again.

Long-poll: ?wait=1

Add ?wait=1 and the request is held open until the order becomes terminal (up to ~25s), instead of returning the current state immediately. This lets your own page flip to "Payment received" within about half a second of the money landing, without polling in a tight loop.

GET https://katanapay.co/api/pay-status/8d20c0b6-…?wait=1

Use plain enquiry (no wait) for reconciliation sweeps, and wait=1 only where a person is watching a screen. Either way, enquiry is the fallback if a callback was missed — it always reflects the truth.

8. Status & response codes

9. Traceability — following one payment end to end

Every pay-in carries four identifiers. Store all of them against your order; each answers a different question.

The lifecycle

create order            → status PENDING      (you hold txnid + order.id)
customer pays by UPI    → credit confirmed
                        → status SUCCESS, RRN filled in
                        → signed callback POSTed to your notify_url  (retried until 200)
                        → customer redirected to your return_url

A payment that never completes ends Expired; one that fails ends Failed. Both are terminal and both fire a callback, so your side never has to guess.

Reconciling a day

• For any order, GET /api/pay-status/{order_id} is the authoritative answer at that moment.
• Match your ledger to the bank's on RRN — it is the only identifier both sides share.
• In the dashboard, Transactions lists every order for your account with its status, RRN and timestamps, and exports the same view as CSV for the period you filter to.
• If a callback never arrived, enquiry will still show the true status — a missed callback never means a lost payment.

10. Sample code

PHP — create order

$key="mk_xxx"; $salt="your_salt";
$o = ["txnid"=>"ORDER-1001","amount"=>"100","productinfo"=>"Order 1001","email"=>"d@e.com"];
$msg = $o["txnid"]."|".$o["amount"]."|".$o["productinfo"]."|".$o["email"];
$o["hash"] = hash_hmac("sha256", $msg, $key.$salt);
$o["key"]=$key; $o["return_url"]="https://you.com/return"; $o["notify_url"]="https://you.com/callback";
$ch=curl_init("https://katanapay.co/api/v1/katana-pay/order");
curl_setopt_array($ch,[CURLOPT_POST=>1,CURLOPT_RETURNTRANSFER=>1,
  CURLOPT_HTTPHEADER=>["Content-Type: application/json"],CURLOPT_POSTFIELDS=>json_encode($o)]);
$res=json_decode(curl_exec($ch),true);
header("Location: ".$res["pay_url"]);   // redirect customer

Node.js — create order

import crypto from "crypto";
const key="mk_xxx", salt="your_salt";
const o={ txnid:"ORDER-1001", amount:"100", productinfo:"Order 1001", email:"d@e.com" };
const msg=[o.txnid,o.amount,o.productinfo,o.email].join("|");
o.hash=crypto.createHmac("sha256",key+salt).update(msg).digest("hex");
const r=await fetch("https://katanapay.co/api/v1/katana-pay/order",{method:"POST",
  headers:{"Content-Type":"application/json"},
  body:JSON.stringify({...o,key,return_url:"https://you.com/return",notify_url:"https://you.com/callback"})});
const data=await r.json();   // redirect customer to data.pay_url

Python — create order

import hmac,hashlib,requests
key,salt="mk_xxx","your_salt"
o={"txnid":"ORDER-1001","amount":"100","productinfo":"Order 1001","email":"d@e.com"}
msg="|".join([o["txnid"],o["amount"],o["productinfo"],o["email"]])
o["hash"]=hmac.new((key+salt).encode(),msg.encode(),hashlib.sha256).hexdigest()
o.update(key=key, return_url="https://you.com/return", notify_url="https://you.com/callback")
data=requests.post("https://katanapay.co/api/v1/katana-pay/order",json=o).json()
# redirect customer to data["pay_url"]

Verify a callback (Node.js)

function verify(body, salt){
  const got=body.HASH; const f={...body}; delete f.HASH;
  const str=Object.keys(f).sort().map(k=>`${k}=${f[k]==null?"":f[k]}`).join("~")+salt;
  const exp=crypto.createHash("sha256").update(str,"utf8").digest("hex").toUpperCase();
  return exp===got;   // true → trust it; then check STATUS==="Captured"
}

Verify a callback (PHP)

function verify($body,$salt){
  $got=$body["HASH"]; unset($body["HASH"]); ksort($body);
  $parts=[]; foreach($body as $k=>$v){$parts[]="$k=".($v??"");}
  $str=implode("~",$parts).$salt;
  return strtoupper(hash("sha256",$str))===$got;
}

11. Go-live checklist

• Generate your Key + Salt and store the Salt securely (server-side only).
• Set your default return_url and webhook URL in the dashboard (or pass them per order).
• Store txnid, order.id, PAY_ID and RRN against your order (§9).
• Test with a small amount; confirm you receive the callback and the HASH verifies.
• Handle callbacks idempotently — the same ORDER_ID may arrive more than once.
• Make create-order retry-safe by always reusing the same txnid.
• Always confirm server-side before fulfilling — never trust the browser redirect alone.

Katana Pay · integration support: contact your Katana account manager.