Миттєве повідомлення про оплату (IPN) - Документація PayU (Україна)

  • Створив Марія Кондорська , редагував Kirill Zadubrovskiy10.04.15

Ви переглядаєте стару версію цієї сторінки. Дивітьсяпоточну версію.

Загальний опис

Протокол IPN забезпечує автоматичну обробку замовлень усередині онлайн-платіжної системи, пов'язуючи сервер PayU та сервер ТСП. Цей метод сповіщення також дозволяє шукати та отримувати дані щодо операцій системи ТСП для управління замовленнями.

Іншими словами, протокол IPN формує реакцію сервера платіжної системи PayU на вихідний запит за протоколом LU, починається обробка платежу. У цей час відбувається блокування суми замовлення на рахунку покупця (перший етап двостадійного процесу). Для завершення платежу потрібне підтвердження можливості виконання замовлення ТСП через протокол IDN (другий етап).

Принцип дії

Поля запиту IPN

Загальні дані

SALEDATE

Дата розміщення замовлення у наступному форматі: рррр-мм-дд чч:мм:сс

COMPLETE_DATE

Дата завершення виконання замовлення у форматі: рррр-мм-дд чч:мм:сс

REFNO

Глобальний ідентифікаційний номер замовлення, що надається PayU (максимальна довжина: 9 знаків)

REFNOEXT

Глобальний ідентифікаційний номер замовлення, що надається продавцем (максимальна довжина: 100 знаків)

ORDERNO

Порядковий номер замовлення на обліковому записі. Для першого платежу 1. Для наступних 2, 3, 4 тощо.

ORDERSTATUS

Поточний статус замовлення.

суму повернуто (платіж повернуто)

аналогічно PAYMENT_AUTHORIZED для Євромережа та зв'язковий

Залежно від налаштувань системи ТСП, статуси PAYMENT_AUTHORIZED та COMPLETE можуть бути кінцевими етапамиобробки платежу, після яких його вважатимуться повністю завершеним.

PAYMETHOD

Використовуваний спосіб оплати. Підтримуються значення:

Реквізити платника

FIRSTNAME

Ім'я (максимальна довжина: 40 знаків)

LASTNAME

Прізвище (максимальна довжина: 40 знаків)

ADDRESS1

Адреса (максимальна довжина: 100 знаків)

CITY

Місто (максимальна довжина: 30 знаків)

STATE

Регіон/область/країна (максимальна довжина: 30 знаків)

ZIPCODE

Індекс/поштовий код (максимальна довжина: 20 знаків)

COUNTRY

Країна (максимальна довжина: 50 знаків)

PHONE

FAX

Номер факсу (максимальна довжина: 40 знаків)

CUSTOMEREMAIL

Адреса електронної пошти клієнта (максимальна довжина: 40 символів)

Параметри доставки

FIRSTNAME_D

Ім'я (максимальна довжина: 40 знаків)

LASTNAME_D

Прізвище (максимальна довжина: 40 знаків)

ADDRESS1_D

Адреса (максимальна довжина: 100 знаків)

CITY_D

Місто (максимальна довжина: 30 знаків)

STATE_D

Штат/регіон/країна (максимальна довжина: 30 знаків)

ZIPCODE_D

Індекс/поштовий код (максимальна довжина: 20 знаків)

COUNTRY_D

Країна (максимальна довжина: 50 знаків)

PHONE_D

IPADDRESS

Параметри замовлення

CURRENCY

Валюта, в якій проводиться обробка замовлення. Можливі значення: Рубль, євро, долар США

IPN_PID[]

Масив даних з ідентифікаційними кодами замовлених продуктів у складі бази даних PayU (ідентифікаційні номериPayU)

IPN_PNAME[]

Масив даних із назвами продуктів

IPN_PCODE[]

Масив даних із кодами продуктів, що присвоюються продавцем у системі (ідентифікаційні номери продавця)

IPN_INFO[]

Масив даних з додатковою інформацією, спрямованою на кожен замовлений продукт (якщо така інформація була направлена ​​PayU).

IPN_QTY[]

Масив даних про кількість продуктів.

IPN_PRICE[]

Масив даних з питомими цінами продуктів (без ПДВ) у румунських леях, з використанням точки (.) як десятковий роздільник

IPN_VAT[]

Масив даних із значеннями ПДВ для продуктів із використанням «.» як десятковий роздільник

IPN_VER[]

Масив даних із версіями продуктів (максимальна довжина: 50 знаків)

IPN_DISCOUNT[]

Масив даних із сумами знижок у рамках акції. Включаючи ПДВ.

IPN_PROMONAME[]

Масив даних із назвами акцій, у межах яких надаються знижки, зазначені вище.

IPN_DELIVEREDCODES[]

Масив даних з кодами, наданими клієнтам, якщо контракт з PayU передбачає таку можливість. Кожен елемент в рамках масиву даних представлений у вигляді рядка, в якому як роздільник для кожного відправленого коду використовується кома (,), якщо замовлена ​​кількість перевищує 1.

IPN_TOTAL[]

Проміжний підсумок у рядку замовлення (включаючи ПДВ) з точкою (.) як десятковий роздільник

IPN_TOTALGENERAL

Загальна сума угоди, включаючи ПДВ та вартість доставки, з точкою (.) як десятковий роздільник

IPN_SHIPPING

Сума, що стягується за перевезення з «.» в якостідесяткового роздільника

IPN_DATE

Надсилання дати за протоколом IPN POST здійснюється у наступному форматі: ммггммддччммсс (наприклад: 20120426145935)

HASH

Запит підпису (MD5 HMAC для всіх полів, зазначених вище)

Правило розрахунку підпису (HASH) для перевірки вхідного IPN

Під час формування підпису використовується секретний код ТСП та базовий рядок.

Базовий рядок для формування HMAC_MD5 IPN-запиту формується шляхом додавання на початок кожного поля його довжини байти (формат UTF-8).

Базовий рядок для розрахунку підпису (HASH) вхідного IPN-запиту (довжини полів у байтах виділені бірюзовим):

19 2012-04-04 12:04:267 63600856 1234562 344 TEST24 Visa/MasterCard/Eurocard4 test6 testov6 Russia16 +7(910)123- 45-6713 [email protected]4 test6 testov6 Russia16 +7 (910) 123-45-6713 84.253.97.1383 RUB6 1723219 some_name9 some_code9 some_info1 15 99.195 23.814 0.006 123.006 123.004 0.004 0.0014 20120404122732

Зверніть увагу, що знаки, що вводяться в полі HASH, можуть бути як у верхньому, так і нижньому регістрі (шістнадцятковий рядок).

  • Для тестових замовлень (TESTORDER=TRUE) ORDERSTATUS в IPN нотифікації завжди матиме значення “TEST”.
  • Для тестових замовлень (TESTORDER=TRUE) статус замовлення в Панелі керування також має значення "TEST".
  • Значення TESTORDER=TRUE застосовується лише до платежів за кредитними картками.
  • Обмін даними по IPN не залежить від підключення покупця на даний момент часу і не може бути будь-яким чином пов'язаний з йогосесією.
  • У разі відсутності підтвердження отримання відправлених даних, сервер PayU робить спроби повторного відправлення даних по HTTP POST раз на кілька хвилин до тих пір, поки не буде отримана належна відповідь або не закінчиться тайм на перенаправлення запиту (кілька днів).

Відповідь сайту ТСП на IPN запит

Система PayU очікує отримати відповідь від системи ТСП у будь-якому місці тіла відповіді у форматі:

Для прикладу вище відповідь виглядатиме так:

20120404122732613e959b380f101d17bd634ae0884a5d

Такий підпис (HASH) виходить шляхом складання базового рядка з IPN_PID[0], IPN_PNAME[0], IPN_DATE, DATE. IPN_PID[0] - перший елемент масиву IPN_PID[]. IPN_PNAME[0] - це перший елемент масиву IPN_PNAME[]. IPN_DATE – дата з IPN-запиту. DATE - дата у форматі yyyymmddhhmmss (наприклад 20111001121212).

З цих параметрів складається базовий рядок, за аналогією з рядком для перевірки вхідного IPN-запиту. Потім використовується функція HMAC із секретним ключем.

Якщо PayU не отримає від системи ТСП коректної відповіді, IPN-запит буде направлений повторно протягом декількох хвилин. Спроби продовжуватимуться протягом 4-х діб або до отримання коректної відповіді (дивлячись, що настане раніше).

payu

Налагодження IPN

Для того, щоб виконати налагодження IPN:

оплату

Завдання обробника IPN на стороні ТСП

Таким чином, обробник IPN ТСП повинен:

  1. Прийняти IPN-запит.
  2. Сформувати базовий рядок на основі полів IPN.
  3. Сформувати HASH з базового рядка та секретного коду.
  4. Звірити з HASH із IPN.
  5. При збігу прийняти IPN в обробку (виконувати логіку на стороні ТСП). При розбіжності повернутипомилку чи відповідати (на розсуд ТСП).
  6. Надіслати в нашу систему відповідь про успішну обробку IPN.

Робота без використання оброблювача IPN

Якщо ТСП не має можливості налаштувати обробник IPN, можна користуватися системою PayU без нього, але в цьому випадку доведеться обробляти кожне замовлення вручну. Необхідно виконати такі дії: