iMoney PA-O Integration

What is iMoney PA-O?

iMoney's Payment Aggregator — Online (PA-O) lets merchants collect digital payments through a single API. The integration follows a two-step Init → Execute flow, after which iMoney notifies your server of the final outcome via webhook.

Environments

Three rules that govern everything

Quick Start #

Five steps to go from zero to a working integration.

Credentials & Onboarding #

Merchant Types #

Your account is provisioned as one of two types. Calling the wrong init endpoint returns error 104.

Security Model #

Every request passes through five gates in order:

Incoming Request
  │
  ├─ [1] API-KEY header        →  Identifies your merchant account
  ├─ [2] IP Whitelist          →  Request IP must be pre-registered with iMoney
  ├─ [3] X-Timestamp header    →  Unix timestamp, must be within ±5 minutes of server time
  ├─ [4] X-Signature header    →  HMAC integrity check (required on init endpoints)
  └─ [5] Encrypted body        →  AES-256-GCM payload confidentiality

Required headers on every request

Encryption #

All cryptographic operations are derived from your api_key + hash_key pair. Three steps: derive the key, encrypt the body, sign the request.

Key Derivation #

The 32-byte AES key is derived by SHA-256 hashing the concatenation of your api_key and hash_key.

import hashlib

def derive_key(api_key: str, hash_key: str) -> bytes:
    return hashlib.sha256(f"{api_key}{hash_key}".encode()).digest()

def derive_key_hex(api_key: str, hash_key: str) -> str:
    return hashlib.sha256(f"{api_key}{hash_key}".encode()).hexdigest()

const crypto = require('crypto');

function deriveKey(apiKey, hashKey) {
    return crypto.createHash('sha256').update(apiKey + hashKey).digest(); // Buffer
}

function deriveKeyHex(apiKey, hashKey) {
    return crypto.createHash('sha256').update(apiKey + hashKey).digest('hex');
}

function deriveKey(string $apiKey, string $hashKey): string {
    return hash('sha256', $apiKey . $hashKey, true); // raw binary
}

function deriveKeyHex(string $apiKey, string $hashKey): string {
    return hash('sha256', $apiKey . $hashKey); // hex string
}

import java.security.MessageDigest;

public static byte[] deriveKey(String apiKey, String hashKey) throws Exception {
    MessageDigest md = MessageDigest.getInstance("SHA-256");
    return md.digest((apiKey + hashKey).getBytes("UTF-8"));
}

public static String deriveKeyHex(String apiKey, String hashKey) throws Exception {
    byte[] raw = deriveKey(apiKey, hashKey);
    StringBuilder sb = new StringBuilder();
    for (byte b : raw) sb.append(String.format("%02x", b));
    return sb.toString();
}

Encrypting the Request Body #

All request payloads must be AES-256-GCM encrypted and wrapped in a JSON envelope before sending.

Wire format

nonce_hex : ciphertext_hex : tag_hex

Wrapped in JSON

{ "data": "a3f8c2...<nonce>:<ciphertext>:<tag>...hex" }

import os, json
from cryptography.hazmat.primitives.ciphers.aead import AESGCM

def encrypt_payload(payload: dict, api_key: str, hash_key: str) -> bytes:
    key   = derive_key(api_key, hash_key)
    nonce = os.urandom(12)
    plain = json.dumps(payload, sort_keys=True, separators=(',', ':')).encode()
    enc   = AESGCM(key).encrypt(nonce, plain, None)
    ct, tag = enc[:-16], enc[-16:]
    encrypted_str = f"{nonce.hex()}:{ct.hex()}:{tag.hex()}"
    return json.dumps({"data": encrypted_str}).encode()

function encryptPayload(payload, apiKey, hashKey) {
    const key    = deriveKey(apiKey, hashKey);
    const nonce  = crypto.randomBytes(12);
    const plain  = Buffer.from(JSON.stringify(payload), 'utf8');
    const cipher = crypto.createCipheriv('aes-256-gcm', key, nonce);
    const ct     = Buffer.concat([cipher.update(plain), cipher.final()]);
    const tag    = cipher.getAuthTag();
    const encStr = `${nonce.toString('hex')}:${ct.toString('hex')}:${tag.toString('hex')}`;
    return Buffer.from(JSON.stringify({ data: encStr }));
}

function encryptPayload(array $payload, string $apiKey, string $hashKey): string {
    $key   = deriveKey($apiKey, $hashKey);
    $nonce = random_bytes(12);
    ksort($payload);
    $plain = json_encode($payload, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES);
    $ct    = openssl_encrypt($plain, 'aes-256-gcm', $key, OPENSSL_RAW_DATA, $nonce, $tag, '', 16);
    $encStr = bin2hex($nonce) . ':' . bin2hex($ct) . ':' . bin2hex($tag);
    return json_encode(['data' => $encStr]);
}

import javax.crypto.Cipher;
import javax.crypto.spec.*;
import java.security.SecureRandom;
import java.util.Arrays;

public static String encryptPayload(String jsonPayload, String apiKey, String hashKey) throws Exception {
    byte[] key   = deriveKey(apiKey, hashKey);
    byte[] nonce = new byte[12];
    new SecureRandom().nextBytes(nonce);
    Cipher cipher = Cipher.getInstance("AES/GCM/NoPadding");
    cipher.init(Cipher.ENCRYPT_MODE, new SecretKeySpec(key, "AES"), new GCMParameterSpec(128, nonce));
    byte[] enc = cipher.doFinal(jsonPayload.getBytes("UTF-8"));
    byte[] ct  = Arrays.copyOf(enc, enc.length - 16);
    byte[] tag = Arrays.copyOfRange(enc, enc.length - 16, enc.length);
    String encStr = bytesToHex(nonce) + ":" + bytesToHex(ct) + ":" + bytesToHex(tag);
    return "{\"data\":\"" + encStr + "\"}";
}

Computing the Signature #

The X-Signature header is required on all init endpoint calls. It proves that the request body has not been tampered with in transit.

Signature inputs

def compute_signature(api_key: str, hash_key: str, timestamp: str,
                      merchant_ref: str, amount: str, body_bytes: bytes) -> str:
    key_hex   = derive_key_hex(api_key, hash_key)
    body_hash = hashlib.sha256(body_bytes).hexdigest()
    message   = f"{api_key}|{timestamp}|{merchant_ref}|{amount}|{body_hash}"
    return hashlib.sha256(f"{message}{key_hex}".encode()).hexdigest()

function computeSignature(apiKey, hashKey, timestamp, merchantRef, amount, bodyBuffer) {
    const keyHex   = deriveKeyHex(apiKey, hashKey);
    const bodyHash = crypto.createHash('sha256').update(bodyBuffer).digest('hex');
    const message  = `${apiKey}|${timestamp}|${merchantRef}|${amount}|${bodyHash}`;
    return crypto.createHash('sha256').update(message + keyHex).digest('hex');
}

function computeSignature(string $apiKey, string $hashKey, string $timestamp,
                           string $merchantRef, string $amount, string $bodyBytes): string {
    $keyHex   = deriveKeyHex($apiKey, $hashKey);
    $bodyHash = hash('sha256', $bodyBytes);
    $message  = "{$apiKey}|{$timestamp}|{$merchantRef}|{$amount}|{$bodyHash}";
    return hash('sha256', $message . $keyHex);
}

public static String computeSignature(String apiKey, String hashKey, String timestamp,
                                       String merchantRef, String amount, byte[] bodyBytes) throws Exception {
    String keyHex   = deriveKeyHex(apiKey, hashKey);
    MessageDigest md = MessageDigest.getInstance("SHA-256");
    String bodyHash  = bytesToHex(md.digest(bodyBytes));
    String message   = apiKey + "|" + timestamp + "|" + merchantRef + "|" + amount + "|" + bodyHash;
    md.reset();
    return bytesToHex(md.digest((message + keyHex).getBytes("UTF-8")));
}

Full Request Example #

A complete end-to-end payin init function in Python — encrypts the payload, computes the signature, and posts to iMoney.

import hashlib, json, os, time
from cryptography.hazmat.primitives.ciphers.aead import AESGCM
import requests

API_KEY  = "your_api_key"
HASH_KEY = "your_hash_key"
BASE_URL = "https://uatpayin.imoneypg.com"

def payin_init(payload: dict) -> dict:
    body      = encrypt_payload(payload, API_KEY, HASH_KEY)
    timestamp = str(int(time.time()))
    signature = compute_signature(
        API_KEY, HASH_KEY,
        timestamp,
        payload["merchant_ref"],
        payload["amount"],
        body
    )
    resp = requests.post(
        f"{BASE_URL}/api/v3/payin/init/",
        data=body,
        headers={
            "Content-Type":   "application/json",
            "API-KEY":        API_KEY,
            "X-Timestamp":    timestamp,
            "X-Signature":    signature,
            "X-Merchant-Ref": payload["merchant_ref"],
            "X-Customer-IP":  payload.get("customer_ip", ""),
        },
        timeout=30
    )
    return resp.json()

Transaction Lifecycle #

Your System                   iMoney Gateway                  Customer
    │                              │                              │
    │── Step 1: Init ─────────────▶│                              │
    │   (POST /payin/init/ or      │                              │
    │    POST /payin/bank/init/)   │                              │
    │◀── transaction_id + pg_ref ──│                              │
    │    (valid for 5 minutes)     │                              │
    │                              │                              │
    │── Step 2: Execute ──────────▶│                              │
    │   (POST /api/v3/payin/)      │                              │
    │◀── response_code: 001 ───────│                              │
    │    pg_ref, payment details   │                              │
    │                              │                              │
    │  [show QR / UPI link to customer]                           │
    │                              │◀──── customer pays ──────────│
    │                              │                              │
    │◀── WEBHOOK ──────────────────│                              │
    │    (final transaction_status)│                              │
    │                              │                              │
    │   [if no webhook after 5 min]│                              │
    │── Status Check (fallback) ──▶│                              │
    │◀── response_code: 000/003 ───│                              │

Step 1 — Init (Prepaid Merchants) #

Headers: API-KEY, X-Timestamp, X-Signature, X-Merchant-Ref, X-Customer-IP, Content-Type: application/json

Request Fields

Request

curl -X POST https://uatpayin.imoneypg.com/api/v3/payin/init/ \
  -H "API-KEY: 9b80b436a5ff" \
  -H "X-Timestamp: 1716374400" \
  -H "X-Signature: a3f8c2d1e5b7..." \
  -H "X-Merchant-Ref: ORDER-20260526-001" \
  -H "X-Customer-IP: 203.0.113.45" \
  -H "Content-Type: application/json" \
  -d '{"data":"<encrypted_string>"}'

{
  "uid": "CUSTOMER-001",
  "merchant_ref": "ORDER-20260526-001",
  "amount": "1000.00",
  "currency": "INR",
  "payin_type": "INTENT",
  "route_name": "YOUR_MERCHANT_ROUTE",
  "customer_name": "Raj Kumar",
  "customer_mobile": "9876543210",
  "customer_email": "raj@example.com",
  "customer_vpa": "raj@upi",
  "description": "Order #ORD-12345"
}

Response — Success

{
  "response_code": "000",
  "message": "OK",
  "data": {
    "transaction_id": "220260526143022123456",
    "pg_ref": "220260526143022ABCD",
    "expires_in": 300
  }
}

Response — Wrong Merchant Type

{
  "response_code": "104",
  "message": "This endpoint is for prepaid merchants. Non-prepaid merchants must use /api/v3/payin/bank/init/.",
  "data": {}
}

Step 1 — Init (Non-Prepaid Merchants) #

Same request fields as Prepaid, except route_name is not accepted — iMoney auto-selects the best available acquirer for the amount, currency, and payment type combination. If no matching route is available, response_code: 105 is returned.

Request

curl -X POST https://uatpayin.imoneypg.com/api/v3/payin/bank/init/ \
  -H "API-KEY: 197eaa2042e8" \
  -H "X-Timestamp: 1716374400" \
  -H "X-Signature: d4e6f8..." \
  -H "X-Merchant-Ref: ORDER-20260526-001" \
  -H "X-Customer-IP: 203.0.113.45" \
  -H "Content-Type: application/json" \
  -d '{"data":"<encrypted_string>"}'

{
  "uid": "CUSTOMER-001",
  "merchant_ref": "ORDER-20260526-001",
  "amount": "1000.00",
  "currency": "INR",
  "payin_type": "UPI",
  "customer_name": "Raj Kumar",
  "customer_mobile": "9876543210",
  "customer_email": "raj@example.com",
  "customer_vpa": "raj@upi",
  "description": "Order #ORD-12345"
}

Response — No Route Available

{
  "response_code": "105",
  "message": "No available routes for UPI with amount 1000.00 INR.",
  "data": {}
}

Step 2 — Execute #

Headers: API-KEY, X-Timestamp, Content-Type: application/json

Request Fields

Request

curl -X POST https://uatpayin.imoneypg.com/api/v3/payin/ \
  -H "API-KEY: 9b80b436a5ff" \
  -H "X-Timestamp: 1716374450" \
  -H "Content-Type: application/json" \
  -d '{"data":"<encrypted_string>"}'

{
  "transaction_id": "220260526143022123456",
  "amount": "1000.00",
  "payin_type": "INTENT"
}

Response — Accepted (Pending Customer Action)

{
  "response_code": "001",
  "message": "Transaction pending",
  "data": {
    "pg_ref": "PG20260526PAY001A",
    "transaction_id": "220260526143022123456",
    "payment_details": {
      "vpa": "merchant@upi",
      "qr_code": "<base64_or_svg_string>",
      "upi_link": "upi://pay?pa=merchant@upi&am=1000.00&cu=INR"
    }
  }
}

Status Check #

Headers: API-KEY, X-Timestamp

Request

curl -X GET "https://uatpayin.imoneypg.com/api/v3/payin/status/PG20260526PAY001A/" \
  -H "API-KEY: 9b80b436a5ff" \
  -H "X-Timestamp: 1716374700"

Response — Too Early

{
  "response_code": "109",
  "message": "Transaction is being processed. Retry status after 280 seconds.",
  "data": { "retry_after_seconds": 280 }
}

Response — Success

{
  "response_code": "000",
  "message": "Transaction successful",
  "data": {
    "pg_ref": "PG20260526PAY001A",
    "merchant_ref": "ORDER-20260526-001",
    "status": "Success",
    "captured_amount": "1000.00",
    "customer_utr": "CUT20260526999"
  }
}

Response — Failed

{
  "response_code": "003",
  "message": "Transaction failed",
  "data": {
    "pg_ref": "PG20260526PAY001A",
    "merchant_ref": "ORDER-20260526-001",
    "status": "Failed"
  }
}

Response — Under Dispute (Blocked)

{
  "response_code": "113",
  "message": "Transaction is under dispute. Status check and resend callback are not available. Await payin.dispute_resolved webhook.",
  "data": {
    "pg_ref": "PG20260526PAY001A",
    "dispute_id": "DSP20260526001"
  }
}

Response Code Reference #

Transaction Status Reference #

When to Mark Success, Fail, or Pending #

Use this table as the definitive decision guide for every state your integration will encounter.

Unexpected Scenarios — Always Keep Pending #

When something unexpected happens — a network error, an ambiguous response code, an exception in your own code during processing, a timeout — the correct action is always to keep the transaction in a Pending state.

What to do in an unexpected scenario

Webhook Integration #

Delivery Mechanism

When a payin transaction reaches a final state (Success, Failed, or Expired), iMoney sends an encrypted HTTP POST to your registered webhook URL.

• Webhooks are sent from a single static IP assigned to iMoney's notification service. Whitelist this IP on your server firewall.
• iMoney retries the webhook up to 9 times with increasing intervals if your endpoint does not return HTTP 200.
• Retry schedule: immediate → 30 seconds → 2 minutes → 10 minutes → 1 hour, continuing until all retries are exhausted.
• The same webhook may arrive more than once. Your endpoint must be idempotent — process each pg_ref exactly once.

Webhook Payload #

iMoney sends a POST with Content-Type: application/json and the following headers:

Content-Type: application/json
X-Webhook-Timestamp: <unix_epoch>
X-Pg-Ref: <pg_ref>
X-Api-Key: <your_api_key>
X-Merchant-Ref: <your_merchant_ref>

Use X-Api-Key to confirm the webhook is addressed to your merchant account. Use X-Merchant-Ref to look up the order before decrypting the body.

Raw body (before decryption)

{
  "encrypted": "<nonce_hex>:<ciphertext_hex>:<tag_hex>",
  "timestamp": "1716374800",
  "pg_ref": "PG20260526PAY001A"
}

Decrypted payload

{
  "event": "payin.status_update",
  "data": {
    "pg_ref": "PG20260526PAY001A",
    "merchant_ref": "ORDER-20260526-001",
    "transaction_status": "Success",
    "amount": "1000.00",
    "captured_amount": "1000.00",
    "payin_type": "INTENT",
    "customer_utr": "CUT20260526999",
    "customer_upi": "user@upi",
    "bank_ref": "UTR123456789",
    "currency": "INR",
    "created_at": "2026-05-26T10:05:00+05:30",
    "updated_at": "2026-05-26T10:05:30+05:30"
  }
}

Fields in the decrypted payload

Acknowledging the Webhook #

Your endpoint must return HTTP 200 to acknowledge receipt. This is the only response iMoney looks at — the body content of your response is ignored.

from django.http import HttpResponse
from django.views.decorators.csrf import csrf_exempt

@csrf_exempt
def payin_webhook(request):
    # Enqueue for async processing
    job_queue.enqueue(process_webhook, request.body)
    return HttpResponse("OK", status=200)  # Return 200 immediately

app.post('/webhook/payin', express.raw({ type: 'application/json' }), (req, res) => {
    jobQueue.add({ body: req.body });
    res.status(200).send('OK');   // Return 200 immediately
});

<?php
// Enqueue for async processing (use a queue like RabbitMQ, Redis, etc.)
$body = file_get_contents('php://input');
enqueueWebhook($body);

http_response_code(200);
echo 'OK';
exit;

Trusting & Verifying the Webhook #

Do not trust a webhook just because it arrived at your endpoint. Any party who knows your webhook URL can send a POST to it. Two layers of verification — use both:

Step-by-step verification checklist

FUNCTION verify_and_process_webhook(source_ip, raw_body):

    // Step 1: IP check
    IF source_ip NOT IN iMoney_static_ip_whitelist:
        LOG "Rejected webhook from unknown IP: " + source_ip
        RETURN HTTP 403   // or silently drop

    // Step 2: Parse outer envelope
    envelope = JSON_DECODE(raw_body)
    IF envelope missing "encrypted", "pg_ref", "timestamp":
        RETURN HTTP 400

    // Step 3: Decrypt
    TRY:
        payload = decrypt_webhook(envelope["encrypted"], api_key, hash_key)
    CATCH DecryptionError:
        LOG "Webhook decryption failed — possible tampering"
        RETURN HTTP 200   // Stop retries; do NOT process

    // Step 4: Verify pg_ref exists in your system
    txn = database.find_transaction(payload["data"]["pg_ref"])
    IF txn is None:
        RETURN HTTP 200   // Do not error-loop on unknown refs

    // Step 5: Idempotency check
    IF txn.is_final_state():
        RETURN HTTP 200   // Already processed; acknowledge and skip

    // Step 6: Process the status update
    UPDATE txn.status = payload["data"]["transaction_status"]
    IF transaction_status == "Success":
        release_order_or_credit_customer(txn)
    ELSE IF transaction_status in ["Failed", "Expired"]:
        allow_customer_retry(txn)

    RETURN HTTP 200

Decrypting the Webhook #

The webhook encrypted field uses the same key derivation as your outbound requests: SHA256(api_key + hash_key). Wire format is nonce_hex:ciphertext_hex:tag_hex.

def decrypt_webhook(encrypted_str: str, api_key: str, hash_key: str) -> dict:
    nonce_hex, ct_hex, tag_hex = encrypted_str.strip().split(':')
    key   = derive_key(api_key, hash_key)
    nonce = bytes.fromhex(nonce_hex)
    ct    = bytes.fromhex(ct_hex)
    tag   = bytes.fromhex(tag_hex)
    plain = AESGCM(key).decrypt(nonce, ct + tag, None)
    return json.loads(plain)

function decryptWebhook(encryptedStr, apiKey, hashKey) {
    const parts  = encryptedStr.trim().split(':');
    const nonce  = Buffer.from(parts[0], 'hex');
    const ct     = Buffer.from(parts[1], 'hex');
    const tag    = Buffer.from(parts[2], 'hex');
    const key    = deriveKey(apiKey, hashKey);
    const d      = crypto.createDecipheriv('aes-256-gcm', key, nonce);
    d.setAuthTag(tag);
    return JSON.parse(Buffer.concat([d.update(ct), d.final()]).toString());
}

function decryptWebhook(string $encryptedStr, string $apiKey, string $hashKey): array {
    [$nonceHex, $ctHex, $tagHex] = explode(':', trim($encryptedStr));
    $key   = deriveKey($apiKey, $hashKey);
    $plain = openssl_decrypt(
        hex2bin($ctHex),
        'aes-256-gcm',
        $key,
        OPENSSL_RAW_DATA,
        hex2bin($nonceHex),
        hex2bin($tagHex)
    );
    if ($plain === false) {
        throw new Exception('Webhook decryption failed — authentication tag mismatch');
    }
    return json_decode($plain, true);
}

public static Map<String, Object> decryptWebhook(String encryptedStr, String apiKey, String hashKey) throws Exception {
    String[] parts    = encryptedStr.trim().split(":");
    byte[] nonce      = hexToBytes(parts[0]);
    byte[] ct         = hexToBytes(parts[1]);
    byte[] tag        = hexToBytes(parts[2]);
    byte[] key        = deriveKey(apiKey, hashKey);

    Cipher cipher = Cipher.getInstance("AES/GCM/NoPadding");
    cipher.init(Cipher.DECRYPT_MODE, new SecretKeySpec(key, "AES"), new GCMParameterSpec(128, nonce));

    byte[] ctWithTag = new byte[ct.length + tag.length];
    System.arraycopy(ct, 0, ctWithTag, 0, ct.length);
    System.arraycopy(tag, 0, ctWithTag, ct.length, tag.length);

    byte[] plain = cipher.doFinal(ctWithTag);
    return parseJson(new String(plain, "UTF-8"));
}

Dispute Webhook Flow #

How Disputes Differ from Normal Flow

A dispute is raised when a transaction that has already reached a terminal state (e.g. Success) is contested — typically by the customer's bank, a chargeback, or an internal investigation. The dispute flow runs on a completely separate track from the normal transaction flow and has its own webhook events.

Normal Flow (terminal)        Dispute Flow (separate track)
        │                              │
  transaction_status                  │
      = "Success"              dispute raised
        │                             │
        │         ┌────────────────── iMoney blocks: ──────────────────┐
        │         │  • normal webhooks for this pg_ref                  │
        │         │  • status check  (returns RC=113)                   │
        │         │  • resend callback (returns RC=113)                 │
        │         └────────────────────────────────────────────────────┘
        │                             │
        │                    [dispute_raised webhook]
        │                    previous_status = "Success"
        │                    current_status  = "Dispute"
        │                             │
        │                    [iMoney investigates]
        │                             │
        │                    [dispute_resolved webhook]
        │                    previous_status  = "Dispute"
        │                    current_status   = final
        │                    not_settled_amount, charges,
        │                    debit, credit
        │                             │
        │                      dispute closed
        │                      (all blocks lifted)

Dispute Raised Webhook #

iMoney fires this webhook the moment a dispute is opened on a previously settled transaction. Update your internal status from its current value to Dispute upon receiving this event.

Additional headers

X-Webhook-Timestamp: <unix_epoch>
X-Pg-Ref: <pg_ref>
X-Api-Key: <your_api_key>
X-Merchant-Ref: <your_merchant_ref>
X-Dispute-Id: <dispute_id>
X-Event: payin.dispute_raised

Decrypted payload

{
  "event": "payin.dispute_raised",
  "data": {
    "pg_ref": "PG20260526PAY001A",
    "merchant_ref": "ORDER-20260526-001",
    "dispute_id": "DSP20260526001",
    "dispute_reason": "Customer claims payment not received",
    "dispute_category": "CHARGEBACK",
    "previous_status": "Success",
    "current_status": "Dispute",
    "amount": "1000.00",
    "currency": "INR",
    "raised_at": "2026-05-26T14:00:00+05:30"
  }
}

Fields

What to do on receipt

1. Acknowledge with HTTP 200 immediately.
2. Look up the transaction by pg_ref in your system.
3. Change the transaction status from previous_status → Dispute.
4. Store dispute_id — you will need it when the dispute is resolved.
5. Do not release or reverse any funds. The dispute is under investigation.
6. Do not expect any further normal-flow webhooks for this pg_ref.

Dispute Resolved Webhook #

iMoney fires this webhook when the dispute investigation concludes. Resolution may favour the merchant or the customer. This webhook carries the financial settlement detail.

Example — Merchant Loss (chargeback upheld)

{
  "event": "payin.dispute_resolved",
  "data": {
    "pg_ref": "PG20260526PAY001A",
    "merchant_ref": "ORDER-20260526-001",
    "dispute_id": "DSP20260526001",
    "previous_status": "Dispute",
    "current_status": "Failed",
    "resolution": "MERCHANT_LOSS",
    "resolution_remark": "Chargeback upheld by customer bank",
    "amount": "1000.00",
    "not_settled_amount": "1000.00",
    "charges": "25.00",
    "debit": "1025.00",
    "credit": "0.00",
    "currency": "INR",
    "resolved_at": "2026-05-28T10:30:00+05:30"
  }
}

Example — Merchant Win (dispute rejected)

{
  "event": "payin.dispute_resolved",
  "data": {
    "pg_ref": "PG20260526PAY001A",
    "merchant_ref": "ORDER-20260526-001",
    "dispute_id": "DSP20260526001",
    "previous_status": "Dispute",
    "current_status": "Success",
    "resolution": "MERCHANT_WIN",
    "resolution_remark": "Dispute rejected — original payment confirmed valid",
    "amount": "1000.00",
    "not_settled_amount": "0.00",
    "charges": "0.00",
    "debit": "0.00",
    "credit": "1000.00",
    "currency": "INR",
    "resolved_at": "2026-05-28T10:30:00+05:30"
  }
}

Fields

What to do on receipt

1. Acknowledge with HTTP 200 immediately.
2. Look up by dispute_id or pg_ref.
3. Update transaction status: Dispute → current_status.
4. Record not_settled_amount, charges, debit, credit for accounting.
5. If MERCHANT_LOSS: funds reversed. Reflect in books.
6. If MERCHANT_WIN: original settlement stands. No action on customer order.

When to Mark Status During a Dispute #

Routing dispute events

Dispute webhooks use identical encryption to normal payin webhooks. Same decryption function, same verification steps. Route on the event field after decryption:

DISPUTE_HANDLERS = {
    "payin.status_update":    handle_normal_webhook,
    "payin.dispute_raised":   handle_dispute_raised,
    "payin.dispute_resolved": handle_dispute_resolved,
}

def payin_webhook_handler(source_ip: str, raw_body: bytes) -> int:
    if source_ip not in IMONEY_STATIC_IPS:
        return 403
    envelope = json.loads(raw_body)
    try:
        payload = decrypt_webhook(envelope["encrypted"], API_KEY, HASH_KEY)
    except Exception:
        return 200   # Decryption failed — log and drop
    event = payload.get("event")
    handler = DISPUTE_HANDLERS.get(event)
    if handler:
        handler(payload["data"])
    return 200

const handlers = {
    'payin.status_update':    handleNormalWebhook,
    'payin.dispute_raised':   handleDisputeRaised,
    'payin.dispute_resolved': handleDisputeResolved,
};

function routeWebhook(sourceIp, rawBody) {
    if (!IMONEY_STATIC_IPS.includes(sourceIp)) return 403;
    let payload;
    try {
        const envelope = JSON.parse(rawBody);
        payload = decryptWebhook(envelope.encrypted, API_KEY, HASH_KEY);
    } catch (e) {
        return 200; // Decryption failed — log and drop
    }
    const handler = handlers[payload.event];
    if (handler) handler(payload.data);
    return 200;
}

Payout Service #

Escalation & Support #

When escalating, always provide:

1. merchant_ref — your order reference
2. pg_ref — iMoney's reference (if you received it)
3. Exact timestamp of the transaction
4. The full response received from iMoney (or the error you encountered)

This document is confidential and intended solely for the named merchant. iMoney reserves the right to update API specifications. Breaking changes will be communicated separately with a migration guide.