Документация для разработчиков — API интеграции для мерчантов India Payme

Обзор

India Payme предоставляет мерчантам два ключевых типа операций: приём платежей (Payin) — получение средств от конечных пользователей от имени мерчанта; выплаты (Payout) — перевод средств на указанный счёт от имени мерчанта. Все внешние методы работают по протоколу POST + JSON и обязательно требуют API-подписи. После обработки платформа уведомляет мерчанта через асинхронное уведомление, а также поддерживает самостоятельный запрос статуса заказа.

Возможность	Метод	Путь
Создание платежа (приём)	POST	`/transaction/payin/v1/apply`
Запрос статуса платежа (приём)	POST	`/transaction/payin/v1/query`
Создание выплаты	POST	`/transaction/payout/v1/apply`
Запрос статуса выплаты	POST	`/transaction/payout/v1/query`
Запрос баланса	POST	`/transaction/payout/v1/balance`

Базовый адрес (домен продуктивного шлюза предоставляется платформой после открытия счёта):

https://{домен_шлюза}

Подготовка к интеграции

Войдите в личный кабинет мерчанта → раздел «Ключи приложения»: у каждого приложения есть пара учётных данных — appKey и appSecret. При этом appKey используется как заголовок запроса appId; appSecret — это ключ подписи, который применяется только для локального вычисления подписи и никогда не передаётся по сети.

Все запросы должны содержать следующие HTTP-заголовки, Content-Type — application/json:

Header	Обязательно	Описание
`appId`	Да	ID приложения мерчанта (то есть appKey)
`timestamp`	Да	Unix-время в миллисекундах
`nonce`	Да	Случайная строка, ≥10 символов, одноразовая, повторное использование запрещено
`sign`	Да	Подпись, рассчитанная по правилам из следующего раздела

Правила подписи

Алгоритм подписи — чистый SHA-256 (в нижнем регистре, шестнадцатеричный), а не HMAC. appSecret добавляется непосредственно в конец подписываемой строки, после чего вычисляется SHA-256. Шаги:

Возьмите поля верхнего уровня тела запроса (только непустые) и объедините их с заголовками подписи appId, timestamp, nonce в единый Map (сам sign в этом не участвует);
отсортируйте по именам параметров в порядке возрастания ASCII и соберите строку вида key1=value1&key2=value2…;
в конец строки без разделителя добавьте appSecret и вычислите SHA-256 всей строки (в нижнем регистре, шестнадцатеричный) — это и есть sign.

# строка для подписи
signString = "key1=value1&key2=value2…&keyN=valueN" + appSecret
sign = SHA256_HEX(signString)   // нижний регистр, hex

Срок действия и защита от повторов:

Срок действия временной метки — 30 секунд: |время сервера − timestamp| ≤ 30s, при превышении возвращается timestamp has expired. Убедитесь, что часы клиента и шлюза синхронизированы (NTP).
Защита от повторов по nonce: один и тот же nonce можно использовать только один раз, при повторе возвращается ошибка nonce has been used (код ошибки 900).
Пустые поля не участвуют в подписи — набор полей, участвующих в подписи, должен полностью совпадать с фактически отправляемыми полями JSON.

Пример подписи на Node.js:

const crypto = require('crypto');

function buildSign(appId, appSecret, timestamp, nonce, body) {
  const params = { ...body, appId, timestamp, nonce };
  const signString = Object.keys(params)
    .filter(k => params[k] !== null && params[k] !== undefined)
    .sort()
    .map(k => `${k}=${params[k]}`)
    .join('&') + appSecret;
  return crypto.createHash('sha256').update(signString, 'utf8').digest('hex');
}

Создание платежа (приём) POST

POST /transaction/payin/v1/apply —— создаёт заказ на приём платежа и возвращает ссылку на кассу payUrl, по которой пользователь завершает оплату.

Поле	Тип	Обязательно	Описание
`merchantOrderNo`	string	Да	Номер заказа мерчанта, не должен повторяться
`amount`	number	Да	Сумма заказа, десятичное число (например, `100.02`)
`name`	string	Да	Имя пользователя. Только латиница, ≥3 буквы, пробелы допускаются, без символов и цифр
`phone`	string	Да	Номер телефона
`email`	string	Да	Email
`currency`	string	Да	Валюта: `INR` / `PKR` / `USDT` / `BDT`
`product`	string	Да	Код платёжного продукта, предоставляется платформой согласно договору
`notifyUrl`	string	Нет	Адрес асинхронных уведомлений; если не указан, используется адрес по умолчанию для мерчанта
`returnUrl`	string	Нет	Страница перенаправления после успешной оплаты
`payType`	string	Нет	Способ прямой оплаты через кошелёк: `JAZZCASH` / `EASYPAISA` / `BKASH` / `NAGAD`

POST /transaction/payin/v1/apply
{
  "merchantOrderNo": "ORD1751731200123",
  "amount": "600.00",
  "currency": "INR",
  "product": "{код_продукта}",
  "name": "John Doe",
  "phone": "9910099100",
  "email": "john@example.com",
  "notifyUrl": "https://shop.example/pay/notify"
}

// ответ
{
  "code": 0,
  "msg": "Success",
  "data": {
    "orderNo": "P1751731200999",
    "merchantOrderNo": "ORD1751731200123",
    "amount": 600,
    "currency": "INR",
    "payUrl": "https://{домен_кассы}/cashier/xxxx",
    "payStatus": 0
  }
}

После получения payUrl перенаправьте пользователя для оплаты; окончательный результат определяется асинхронным уведомлением.

Создание выплаты POST

POST /transaction/payout/v1/apply —— инициирует выплату на указанный счёт. Асинхронная обработка: сначала выполняется проверка счёта и блокировка средств, затем платформа асинхронно подбирает канал для выплаты; в ответе обычно возвращается payStatus=0 (заявка принята), а итоговый статус определяется по запросу или уведомлению.

Поле	Тип	Обязательно	Описание
`merchantOrderNo`	string	Да	Номер заказа мерчанта
`amount`	number	Да	Сумма выплаты, минимум 100.00
`accountName`	string	Да	Имя получателя. Только латиница, ≥3 буквы, пробелы допускаются
`account`	string	Да	Номер счёта получателя
`phone`	string	Да	Номер телефона
`email`	string	Да	Email
`currency`	string	Да	Валюта: `INR` / `PKR` / `USDT` / `BDT`
`bizCode`	string	Да	Тип операции выплаты: `IMPS` / `UPI` / `BANK` / `JAZZCASH` / `EASYPAISA` / `BKASH` / `NAGAD` / `ECARD`
`payCode`	string	Да	Способ выплаты: `CARD` / `WALLET` / `NBK` / `ITT` / `VC`
`branchCode`	string	Да	Клиринговый код: для Индии — IFSC; для Пакистана — bankcode; для Бангладеш — согласно bizCode
`product`	string	Да	Код платёжного продукта для выплаты, предоставляется платформой
`bankName`	string	Нет	Название банка
`swiftCode`	string	Нет	SWIFT-код (используется при международном переводе ITT)

POST /transaction/payout/v1/apply
{
  "merchantOrderNo": "PO1751731200123",
  "amount": "1500.00",
  "currency": "INR",
  "product": "{код_продукта}",
  "accountName": "John Doe",
  "account": "1234567890",
  "bizCode": "IMPS",
  "payCode": "NBK",
  "branchCode": "HDFC0000001",
  "bankName": "HDFC",
  "phone": "9910099100",
  "email": "john@example.com"
}

Запрос статуса заказа POST

Для приёма — POST /transaction/payin/v1/query, для выплат — POST /transaction/payout/v1/query. Заказ определяется по merchantOrderNo или orderNo. Ограничение: 5 запросов в секунду.

POST /transaction/payin/v1/query
{ "merchantOrderNo": "ORD1751731200123" }

// возвращаемые данные (data)
{
  "orderNo": "P1751731200999",
  "merchantOrderNo": "ORD1751731200123",
  "amount": 600,
  "realAmount": 600,
  "currency": "INR",
  "payStatus": 1        // 0 — в обработке / 1 — оплачено / -1 — отменено
}

Запрос баланса POST

POST /transaction/payout/v1/balance —— запрос баланса счёта мерчанта. Ограничение: 5 запросов в секунду.

POST /transaction/payout/v1/balance
{ "currency": "INR" }

// возвращаемые данные (data)
{
  "accountNo": "ACC0001",
  "currency": "INR",
  "balance": 100000.00,       // общий баланс
  "balanceActive": 98500.00,  // доступный баланс
  "balanceFreeze": 1500.00    // заблокированный баланс
}

Асинхронные уведомления

Когда заказ переходит в конечный статус, платформа отправляет POST-уведомление (JSON) на notifyUrl мерчанта (если не указан — используется адрес по умолчанию), вместе с теми же заголовками подписи (appId/timestamp/nonce/sign). Мерчант должен пересчитать подпись по тем же правилам с использованием собственного appSecret и сверить её, чтобы подтвердить подлинность уведомления.

Уведомление о приёме платежа содержит: merchantOrderNo, orderNo, currency, product, amount, realAmount, status (значение "1" означает успешный приём). Уведомление о выплате дополнительно содержит utr (номер банковской транзакции) и statusDes (описание статуса); status принимает значения "1" — успех / "2" — ошибка.

// пример тела уведомления о приёме платежа
{
  "merchantOrderNo": "ORD1751731200123",
  "orderNo": "P1751731200999",
  "currency": "INR",
  "product": "{код_продукта}",
  "amount": "600.00",
  "realAmount": "600.00",
  "status": "1"
}

Мерчант обязан вернуть простой текст OK или success (без учёта регистра). В противном случае платформа поставит уведомление в очередь повторной отправки: не более 5 попыток с увеличивающимся интервалом в минутах (1 / 2 / 5 / 10 / 30 / 60 / 120). Поэтому обработчик на стороне мерчанта должен быть идемпотентным (один и тот же orderNo может быть отправлен повторно).

Статусы заказа

При интеграции ориентируйтесь на приведённые ниже внешние статусы (внутренняя логика статусов более детализирована и напрямую не раскрывается):

Сценарий	Поле	Значения
Ответ на создание заказа	`payStatus`	`0` создан / `1` успех / `2` ошибка / `3` отменён
Запрос статуса приёма	`payStatus`	`0` в обработке / `1` оплачено / `-1` отменено
Запрос статуса выплаты	`payStatus`	`0` ожидает выплаты / `1` выплачено / `-1` отменено
Асинхронное уведомление	`status`	приём — успех `"1"`; выплата — `"1"` успех / `"2"` ошибка

Коды ошибок

Если в теле ответа code != 0, запрос завершился ошибкой, а msg содержит пояснение. Часто встречающиеся коды ошибок:

code	Описание
`0`	Успех
`400`	Ошибка параметров / ошибка проверки подписи (Sign invalid)
`900`	Повторный запрос / повтор nonce
`10000` / `10001`	Приложение не найдено / приложение недоступно
`10002`	Валюта не поддерживается
`10003` / `10007`	Мерчант недоступен / счёт мерчанта недоступен
`10004`	Продукт не подключён либо истёк срок договора
`10005` / `10009`	Нет доступных каналов / канал временно недоступен
`10008`	Недостаточно средств на счёте
`10010`	IP-адрес отсутствует в белом списке
`10011` / `10012`	Недействительный продукт / недействительный способ оплаты
`10020`	Номер заказа мерчанта уже используется
`30001` / `30002`	Неверный номер заказа / неверная валюта либо счёт не активирован

Полный процесс интеграции

На примере приёма платежа:

Сформируйте тело запроса (см. поля раздела «Создание платежа (приём)»).
Сгенерируйте timestamp (в миллисекундах) и nonce (случайная строка ≥10 символов).
Рассчитайте sign согласно разделу «Правила подписи».
Отправьте POST /transaction/payin/v1/apply с 4 заголовками подписи и телом JSON.
Если code==0, возьмите data.payUrl и перенаправьте пользователя для оплаты.
Ожидайте асинхронное уведомление; также можно самостоятельно запросить статус заказа для сверки итогового результата.
После получения уведомления проверьте подпись, обработайте бизнес-логику и верните простой текст OK.

Примечание: пути методов, поля и коды статусов в этом документе соответствуют продуктивной реализации; домен продуктивного шлюза, доступные коды продуктов product и политика белого списка IP предоставляются платформой после открытия счёта.

API приёма и выплат: подключение в несколько шагов