Acquiring (v2403)

На кожну зміну статусу рахунку бекенд еквайрингу виконає до 3-х спроб POST запиту, поки у відповідь не отримує http-статус 200 OK. З параметром X-Sign у хідерах. Параметр містить підпис тіла запиту вебхуку по стандарту ECDSA. Приклади верифікації підпису наведено нижче.

API може працювати в режимі тестового середовища. Для цього потрібно використовувати токен із https://api.monobank.ua/

Для тестування не потрібно мати термінал або дозвіл для тестування эквайрингу, тестове середовище доступне всім клієнтам банку. В тестовому середовищі для оплати можна використовувати будь-які номер, дату та cvv картки, навіть якщо вони не є дійсними. Єдина умова: номер картки повинен бути валідним за алгоритмом Луна. При використанні даних реальної банківської картки, вона буде прийнята, але фінансова авторизація здійснюватись не буде.

Приклади верифікації підпису webhook

Go

  package main

  import (
    "crypto/ecdsa"
    "crypto/sha256"
    "crypto/x509"
    "encoding/base64"
    "encoding/pem"
    "log"
  )

  var (
    // example pubkey, you should receive one at https://api.monobank.ua/api/merchant/pubkey
    pubKeyBase64 = `LS0tLS1CRUdJTiBQVUJMSUMgS0VZLS0tLS0KTUZrd0V3WUhLb1pJemowQ0FRWUlLb1pJemowREFRY0RRZ0FFQUc1LzZ3NnZubGJZb0ZmRHlYWE4vS29CbVVjTgo3NWJSUWg4MFBhaEdldnJoanFCQnI3OXNSS0JSbnpHODFUZVQ5OEFOakU1c0R3RmZ5Znhub0ZJcmZBPT0KLS0tLS1FTkQgUFVCTElDIEtFWS0tLS0tCg==`

    // value from X-Sign header in webhook request
    xSignBase64 = `MEUCIQC/mVKhi8FKoayul2Mim3E2oaIOCNJk5dEXxTqbkeJSOQIgOM0hsW0qcP2H8iXy1aQYpmY0SJWEaWur7nQXlKDCFxA=`

    // webhook request body bytes
    bodyBytes = []byte(`{
    "invoiceId": "p2_9ZgpZVsl3",
    "status": "created",
    "failureReason": "string",
    "amount": 4200,
    "ccy": 980,
    "finalAmount": 4200,
    "createdDate": "2019-08-24T14:15:22Z",
    "modifiedDate": "2019-08-24T14:15:22Z",
    "reference": "84d0070ee4e44667b31371d8f8813947",
    "cancelList": [
      {
        "status": "processing",
        "amount": 4200,
        "ccy": 980,
        "createdDate": "2019-08-24T14:15:22Z",
        "modifiedDate": "2019-08-24T14:15:22Z",
        "approvalCode": "662476",
        "rrn": "060189181768",
        "extRef": "635ace02599849e981b2cd7a65f417fe"
      }
    ]
  }`)
  )

  func main() {
    pubKeyBytes, err := base64.StdEncoding.DecodeString(pubKeyBase64)
    if err != nil {
        panic(err)

    }

    signatureBytes, err := base64.StdEncoding.DecodeString(xSignBase64)
    if err != nil {
        panic(err)
    }

    block, _ := pem.Decode(pubKeyBytes)
    if block == nil {
        panic("invalid pem")
    }

    genericPubKey, err := x509.ParsePKIXPublicKey(block.Bytes)
    if err != nil {
        panic(err)
    }

    pubKey, ok := genericPubKey.(*ecdsa.PublicKey)
    if !ok {
        panic("invalid key")
    }

    hash := sha256.Sum256(bodyBytes)

    ok = ecdsa.VerifyASN1(pubKey, hash[:], signatureBytes)
    if !ok {
        panic("invalid X-Sign")
    }

    log.Println("OK")
  }      
Python

  import base64
  import hashlib

  import ecdsa

  # example pubkey, you should receive one at https://api.monobank.ua/api/merchant/pubkey
  pub_key_base64 = "LS0tLS1CRUdJTiBQVUJMSUMgS0VZLS0tLS0KTUZrd0V3WUhLb1pJemowQ0FRWUlLb1pJemowREFRY0RRZ0FFQUc1LzZ3NnZubGJZb0ZmRHlYWE4vS29CbVVjTgo3NWJSUWg4MFBhaEdldnJoanFCQnI3OXNSS0JSbnpHODFUZVQ5OEFOakU1c0R3RmZ5Znhub0ZJcmZBPT0KLS0tLS1FTkQgUFVCTElDIEtFWS0tLS0tCg=="

  # value from X-Sign header in webhook request
  x_sign_base64 = "MEUCIQC/mVKhi8FKoayul2Mim3E2oaIOCNJk5dEXxTqbkeJSOQIgOM0hsW0qcP2H8iXy1aQYpmY0SJWEaWur7nQXlKDCFxA="

  # webhook request body bytes
  body_bytes = b'''{
    "invoiceId": "p2_9ZgpZVsl3",
    "status": "created",
    "failureReason": "string",
    "amount": 4200,
    "ccy": 980,
    "finalAmount": 4200,
    "createdDate": "2019-08-24T14:15:22Z",
    "modifiedDate": "2019-08-24T14:15:22Z",
    "reference": "84d0070ee4e44667b31371d8f8813947",
    "cancelList": [
      {
        "status": "processing",
        "amount": 4200,
        "ccy": 980,
        "createdDate": "2019-08-24T14:15:22Z",
        "modifiedDate": "2019-08-24T14:15:22Z",
        "approvalCode": "662476",
        "rrn": "060189181768",
        "extRef": "635ace02599849e981b2cd7a65f417fe"
      }
    ]
  }'''

  if __name__ == '__main__':
      pub_key_bytes = base64.b64decode(pub_key_base64)
      signature_bytes = base64.b64decode(x_sign_base64)
      pub_key = ecdsa.VerifyingKey.from_pem(pub_key_bytes.decode())

      ok = pub_key.verify(signature_bytes, body_bytes, sigdecode=ecdsa.util.sigdecode_der, hashfunc=hashlib.sha256)
      if ok:
          print("OK")
      else:
          print("NOT OK")
Php

  <?php

  // example pubkey, you should receive one at https://api.monobank.ua/api/merchant/pubkey
  $pubKeyBase64 = "LS0tLS1CRUdJTiBQVUJMSUMgS0VZLS0tLS0KTUZrd0V3WUhLb1pJemowQ0FRWUlLb1pJemowREFRY0RRZ0FFQUc1LzZ3NnZubGJZb0ZmRHlYWE4vS29CbVVjTgo3NWJSUWg4MFBhaEdldnJoanFCQnI3OXNSS0JSbnpHODFUZVQ5OEFOakU1c0R3RmZ5Znhub0ZJcmZBPT0KLS0tLS1FTkQgUFVCTElDIEtFWS0tLS0tCg==";

  // value from X-Sign header in webhook request
  $xSignBase64 = "MEUCIQC/mVKhi8FKoayul2Mim3E2oaIOCNJk5dEXxTqbkeJSOQIgOM0hsW0qcP2H8iXy1aQYpmY0SJWEaWur7nQXlKDCFxA=";

  $message = '{
    "invoiceId": "p2_9ZgpZVsl3",
    "status": "created",
    "failureReason": "string",
    "amount": 4200,
    "ccy": 980,
    "finalAmount": 4200,
    "createdDate": "2019-08-24T14:15:22Z",
    "modifiedDate": "2019-08-24T14:15:22Z",
    "reference": "84d0070ee4e44667b31371d8f8813947",
    "cancelList": [
      {
        "status": "processing",
        "amount": 4200,
        "ccy": 980,
        "createdDate": "2019-08-24T14:15:22Z",
        "modifiedDate": "2019-08-24T14:15:22Z",
        "approvalCode": "662476",
        "rrn": "060189181768",
        "extRef": "635ace02599849e981b2cd7a65f417fe"
      }
    ]
  }';

  $signature = base64_decode($xSignBase64);
  $publicKey = openssl_get_publickey(base64_decode($pubKeyBase64));

  $result = openssl_verify($message, $signature, $publicKey, OPENSSL_ALGO_SHA256);

  echo $result === 1 ? "OK" : "NOT OK";
NodeJs

  const crypto = require('crypto');

  // example pubkey, you should receive one at https://api.monobank.ua/api/merchant/pubkey
  let pubKeyBase64 = "LS0tLS1CRUdJTiBQVUJMSUMgS0VZLS0tLS0KTUZrd0V3WUhLb1pJemowQ0FRWUlLb1pJemowREFRY0RRZ0FFQUc1LzZ3NnZubGJZb0ZmRHlYWE4vS29CbVVjTgo3NWJSUWg4MFBhaEdldnJoanFCQnI3OXNSS0JSbnpHODFUZVQ5OEFOakU1c0R3RmZ5Znhub0ZJcmZBPT0KLS0tLS1FTkQgUFVCTElDIEtFWS0tLS0tCg==";

  // value from X-Sign header in webhook request
  let xSignBase64 = "MEUCIQC/mVKhi8FKoayul2Mim3E2oaIOCNJk5dEXxTqbkeJSOQIgOM0hsW0qcP2H8iXy1aQYpmY0SJWEaWur7nQXlKDCFxA=";

  let message = `{
    "invoiceId": "p2_9ZgpZVsl3",
    "status": "created",
    "failureReason": "string",
    "amount": 4200,
    "ccy": 980,
    "finalAmount": 4200,
    "createdDate": "2019-08-24T14:15:22Z",
    "modifiedDate": "2019-08-24T14:15:22Z",
    "reference": "84d0070ee4e44667b31371d8f8813947",
    "cancelList": [
      {
        "status": "processing",
        "amount": 4200,
        "ccy": 980,
        "createdDate": "2019-08-24T14:15:22Z",
        "modifiedDate": "2019-08-24T14:15:22Z",
        "approvalCode": "662476",
        "rrn": "060189181768",
        "extRef": "635ace02599849e981b2cd7a65f417fe"
      }
    ]
  }`

  let signatureBuf = Buffer.from(xSignBase64, 'base64');
  let publicKeyBuf = Buffer.from(pubKeyBase64, 'base64');

  let verify = crypto.createVerify('SHA256');

  verify.write(message);
  verify.end();

  let result = verify.verify(publicKeyBuf, signatureBuf);

  console.log(result === true ? "OK" : "NOT OK");

Помилки в процесі оплати

Помилки в процесі оплати
errCode з вебхуку або Статусу рахунку Текст помилки Куди звернутися
6 Операцію заблоковано банком-емітентом банк, який випустив картку
40 Карта втрачена. Витрати обмежені банк, який випустив картку
41 Карта втрачена. Витрати обмежені банк, який випустив картку
50 Витрати по карті обмежені банк, який випустив картку
51 У картки, з якої ви намагаєтеся зробити переказ, закінчився строк дії банк, який випустив картку
51 У картки, з якої ви намагаєтеся зробити переказ, закінчився строк дії банк, який випустив картку
52 Номер картки вказано невірно банк, який випустив картку
54 Стався технічний збій банк, який випустив картку
55 Помилка налаштувань торгівельної точки monobank
56 Тип карти не підтримує подібні оплати банк, який випустив картку
57 Транзакція не підтримується банк, який випустив картку
57 Помилка налаштувань торгівельної точки monobank
58 Витрати по карті обмежені на покупку банк, який випустив картку
58 Витрати по карті обмежені банк, який випустив картку
59 На картці недостатньо коштів для завершення покупки) банк, який випустив картку
60 На картці перевищено ліміт кількості видаткових операцій банк, який випустив картку
61 На картці перевищено інтернет-ліміт банк, який випустив картку
62 Досягнуто або перевищено ліміт на кількість неправильних вводів PIN-коду банк, який випустив картку
63 На картці перевищено інтернет-ліміт банк, який випустив картку
67 Помилка налаштувань торгівельної точки monobank
68 Відмова в проведені операції з боку МПС банк, який випустив картку
71 Операцію заблоковано банком-емітентом банк, який випустив картку
72 Операцію заблоковано банком-емітентом банк, який випустив картку
73 Помилка маршрутизації monobank
74 Помилка налаштувань торгівельної точки. ) monobank
75 Операцію заблоковано банком-емітентом банк, який випустив картку
80 Неправильний CVV код (3 цифри на звороті картки) банк, який випустив картку
81 Неправильний CVV2 код (3 цифри на звороті картки) банк, який випустив картку
82 Транзакція не дозволена з такими умовами проведення банк, який випустив картку
82 Транзакція не дозволена з такими умовами проведення банк, який випустив картку
82 Помилка налаштувань торгівельної точки monobank
83 Перевищені ліміти спроб оплати з карт банк, який випустив картку
84 Неправильне значення перевірочного числа 3D Secure Cardholder Authentication Verification Value monobank
98 Помилка налаштувань торгівельної точки monobank
1000 Здається, наш кіт облажався monobank
1005 Здається, наш кіт облажався monobank
1010 Здається, наш кіт облажався monobank
1014 Для проведення оплати потрібно вказати повні реквізити карти покупець
1034 3-D Secure перевірку не пройдено банк, який випустив картку
1035 3-D Secure перевірку не пройдено банк, який випустив картку
1036 Здається, наш кіт облажався monobank
1044 Помилка налаштувань торгівельної точки monobank
1045 3-D Secure перевірку не пройдено банк, який випустив картку
1053 Помилка налаштувань торгівельної точки monobank
1054 3-D Secure перевірку не пройдено monobank
1056 Переказ можливий тільки на картку українського банку monobank
1064 Оплата можлива лише з використанням карток Mastercard або Visa банк, який випустив картку
1066 Помилка налаштувань торгівельної точки monobank
1077 Сума оплати менша ніж допустима сума (налаштування МПС) API
1080 Термін дії карти вказаний невірно банк, який випустив картку
1090 Інформація про клієнта не знайдена monobank
1115 Помилка налаштувань торгівельної точки monobank
1121 Помилка налаштувань торгівельної точки monobank
1145 Мінімальна сума переказу monobank
1165 Операцію заблоковано банком-емітентом банк, який випустив картку
1187 Треба вказати імя отримувача API
1193 Операцію заблоковано банком-емітентом банк, який випустив картку
1194 Цей спосіб поповнення працює тільки з картами інших банків monobank
1200 Обов'язкова наявність CVV коду (3 цифри на звороті картки) банк, який випустив картку
1405 Платіжна система обмежила перекази банк, який випустив картку
1406 Карта заблокована риск-менеджемнтом банк, який випустив картку
1407 Операцію заблоковано ризик-менеджментом monobank
1408 Операцію заблоковано банком-емітентом банк, який випустив картку
1411 Цей вид операцій з гривневих карток тимчасово обмежений monobank
1413 Операцію заблоковано банком-емітентом банк, який випустив картку
1419 Термін дії карти вказаний невірно банк, який випустив картку
1420 Здається, наш кіт облажався monobank
1421 3-D Secure перевірку не пройдено банк, який випустив картку
1422 Виникла помилка на етапі 3-D Secure) банк, який випустив картку
1425 Виникла помилка на етапі 3-D Secure) банк, який випустив картку
1428 Операцію заблоковано банком-емітентом банк, який випустив картку
1429 3-D Secure перевірку не пройдено банк, який випустив картку
1433 Перевірте імʼя та прізвище отримувача. У випадку зазначення недостовірних даних, банк може відхилити переказ monobank
1436 Кацапське гівно не обслуговуємо monobank
1439 Недопустима операція для використання за програмою єВідновлення monobank
1458 Операция відхилена на кроці 3DS банк, який випустив картку
8001 Минув термін дії посилання на оплату покупець
8002 Клієнт відмінив оплату покупець
8003 Стався технічний збій monobank
8004 Проблеми з проведенням 3-D Secure банк, який випустив картку
8005 Ой, ой, перевищено ліміти на прийом оплат monobank
8006 Ой, ой, перевищено ліміти на прийом оплат monobank

Створення рахунку

Створення рахунку для оплати

header Parameters
X-Token
string

Токен з особистого кабінету https://web.monobank.ua/ або тестовий токен з https://api.monobank.ua/

X-Cms
string

Назва CMS, якщо ви розробляєте платіжний модуль для CMS

X-Cms-Version
string

Версія CMS, якщо ви розробляєте платіжний модуль для CMS

Request Body schema: application/json
amount
required
integer <int64>

Сума оплати у мінімальних одиницях (копійки для гривні)

ccy
integer <int32>

ISO 4217 код валюти, за замовчуванням 980 (гривня)

object (MerchantPaymInfoItem)

Інформаційні дані замовлення, яке буде оплачуватсь. Обовʼязково вказувати при активній звʼязці з ПРРО (звʼязка створюється у веб-кабінеті https://web.monobank.ua)

redirectUrl
string

Адреса для повернення (GET) - на цю адресу буде переадресовано користувача після завершення оплати (у разі успіху або помилки)

webHookUrl
string

Адреса для CallBack (POST) – на цю адресу буде надіслано дані про стан платежу при кожній зміні статусу. Зміст тіла запиту ідентичний відповіді запиту “Статус рахунку”. Гарантії доставки повідомлень одне за одним не надається. Тобто, може бути ситуація, коли вебхук про успішну оплату (status=success) прийде пізніше за вебхук про обробку цієї оплати (status=processing). Краще орієнтуватись на поле modifiedDate при аналізі поточного статусу рахунку. Вебхук із більшим modifiedDate буде актуальним

validity
integer <int64>

Строк дії в секундах, за замовчуванням рахунок перестає бути дійсним через 24 години

paymentType
string
Default: "debit"
Enum: "debit" "hold"

Тип операції. Для значення hold термін складає 9 днів. Якщо через 9 днів холд не буде фіналізовано — він скасовується

qrId
string

Ідентифікатор QR-каси для встановлення суми оплати на існуючих QR-кас

code
string

Код терміналу субмерчанта, з апі "Список субмерчантів". Доступний обмеженому колу мерчантів, які точно знають, що їм це потрібно

object

Дані для збереження (токенізації) картки. Для підключення функції, зверніться, будь ласка, в підтримку monobank. Токенізація недоступна за замовчуванням

Responses

Request samples

Content type
application/json
{
  • "amount": 4200,
  • "ccy": 980,
  • "merchantPaymInfo": {
    },
  • "validity": 3600,
  • "paymentType": "debit",
  • "qrId": "XJ_DiM4rTd5V",
  • "code": "0a8637b3bccb42aa93fdeb791b8b58e9",
  • "saveCardData": {
    }
}

Response samples

Content type
application/json
{}

Статус рахунку

Метод перевірки статусу рахунку при розсинхронізації з боку продавця або відсутності webHookUrl при створенні рахунку.

query Parameters
invoiceId
string
Example: invoiceId=p2_9ZgpZVsl3

Ідентифікатор рахунку

header Parameters
X-Token
string

Токен з особистого кабінету https://web.monobank.ua/ або тестовий токен з https://api.monobank.ua/

Responses

Response samples

Content type
application/json
{
  • "invoiceId": "p2_9ZgpZVsl3",
  • "status": "created",
  • "failureReason": "Неправильний CVV код",
  • "errCode": "59",
  • "amount": 4200,
  • "ccy": 980,
  • "finalAmount": 4200,
  • "createdDate": "2019-08-24T14:15:22Z",
  • "modifiedDate": "2019-08-24T14:15:22Z",
  • "reference": "84d0070ee4e44667b31371d8f8813947",
  • "destination": "Покупка щастя",
  • "cancelList": [
    ],
  • "paymentInfo": {
    },
  • "walletData": {
    }
}

Скасування оплати

Скасування успішної оплати рахунку

header Parameters
X-Token
string

Токен з особистого кабінету https://web.monobank.ua/ або тестовий токен з https://api.monobank.ua/

Request Body schema: application/json
invoiceId
required
string

Ідентифікатор рахунку

extRef
string

Референс операції скасування, який визначається продавцем

amount
integer <int64>

Сума у мінімальних одиницях (при частковому поверненні)

Array of objects (FiscalizationItem)

Список товарів для створення чеку повернення, поле обов'язкове у випадку активованої опції фіскалізації

Responses

Request samples

Content type
application/json
{
  • "invoiceId": "p2_9ZgpZVsl3",
  • "extRef": "635ace02599849e981b2cd7a65f417fe",
  • "amount": 5000,
  • "items": [
    ]
}

Response samples

Content type
application/json
{
  • "status": "processing",
  • "createdDate": "2019-08-24T14:15:22Z",
  • "modifiedDate": "2019-08-24T14:15:22Z"
}

Інвалідація рахунку

Інвалідація рахунку, якщо за ним ще не було здіснено оплати

header Parameters
X-Token
string

Токен з особистого кабінету https://web.monobank.ua/ або тестовий токен з https://api.monobank.ua/

Request Body schema: application/json
invoiceId
required
string

Ідентифікатор рахунку

Responses

Request samples

Content type
application/json
{
  • "invoiceId": "p2_9ZgpZVsl3"
}

Response samples

Content type
application/json
{ }

Відкритий ключ для верифікації підписів

Отримання відкритого ключа для перевірки підпису, який включено у вебхуки. Ключ можна кешувати і робити запит на отримання нового, коли верифікація підпису з поточним ключем перестане працювати. Кожного разу робити запит на отримання ключа не треба

header Parameters
X-Token
string

Токен з особистого кабінету https://web.monobank.ua/ або тестовий токен з https://api.monobank.ua/

Responses

Response samples

Content type
application/json
{
  • "key": "LS0tLS1CRUdJTiBQVUJMSUMgS0VZLS0tLS0KTUZrd0V3WUhLb1pJemowQ0FRWUlLb1pJemowREFRY0RRZ0FFK0UxRnBVZzczYmhGdmp2SzlrMlhJeTZtQkU1MQpib2F0RU1qU053Z1l5ZW55blpZQWh3Z3dyTGhNY0FpT25SYzNXWGNyMGRrY2NvVnFXcVBhWVQ5T3hRPT0KLS0tLS1FTkQgUFVCTElDIEtFWS0tLS0tCg=="
}

Фіналізація суми холду

header Parameters
X-Token
string

Токен з особистого кабінету https://web.monobank.ua/ або тестовий токен з https://api.monobank.ua/

Request Body schema: application/json
invoiceId
required
string

Ідентифікатор рахунку

amount
integer <int64>

Сума у мінімальних одиницях

Array of objects (FiscalizationItem)

Список товарів для для фіскалізації, коли сума фіналізації холду не співпадає з оригінальною сумою оплати

Responses

Request samples

Content type
application/json
{
  • "invoiceId": "p2_9ZgpZVsl3",
  • "amount": 4200,
  • "items": [
    ]
}

Response samples

Content type
application/json
{
  • "status": "success"
}

Інформація про QR-касу

Інформація про QR-касу, лише для активованих QR-кас

query Parameters
qrId
string
Example: qrId=OBJE

Ідентифікатор QR-каси

header Parameters
X-Token
string

Токен з особистого кабінету https://web.monobank.ua/ або тестовий токен з https://api.monobank.ua/

Responses

Response samples

Content type
application/json
{
  • "shortQrId": "OBJE",
  • "invoiceId": "4EwIUTA12JIZ",
  • "amount": 4200,
  • "ccy": 980
}

Видалення суми оплати

header Parameters
X-Token
string

Токен з особистого кабінету https://web.monobank.ua/ або тестовий токен з https://api.monobank.ua/

Request Body schema: application/json
qrId
required
string

Ідентифікатор QR-каси

Responses

Request samples

Content type
application/json
{
  • "qrId": "XJ_DiM4rTd5V"
}

Response samples

Content type
application/json
{ }

Список QR-кас

header Parameters
X-Token
string

Токен з особистого кабінету https://web.monobank.ua/ або тестовий токен з https://api.monobank.ua/

Responses

Response samples

Content type
application/json
{}

Дані мерчанта

header Parameters
X-Token
string

Токен з особистого кабінету https://web.monobank.ua/ або тестовий токен з https://api.monobank.ua/

Responses

Response samples

Content type
application/json
{
  • "merchantId": "12o4Vv7EWy",
  • "merchantName": "Your Favourite Company",
  • "edrpou": "4242424242"
}

Виписка за період

query Parameters
from
integer <int64>
Example: from=1649329978

utc unix timestamp

to
integer <int64>
Example: to=1649329978

utc unix timestamp

header Parameters
X-Token
string

Токен з особистого кабінету https://web.monobank.ua/ або тестовий токен з https://api.monobank.ua/

Responses

Response samples

Content type
application/json
{
  • "list": [
    ]
}

Видалення токенізованої картки

query Parameters
cardToken
string
Example: cardToken=67XZtXdR4NpKU3

Токен картки

header Parameters
X-Token
string

Токен з особистого кабінету https://web.monobank.ua/ або тестовий токен з https://api.monobank.ua/

Responses

Response samples

Content type
application/json
{ }

Список карток у гаманці

query Parameters
walletId
string
Example: walletId=c1376a611e17b059aeaf96b73258da9c

Ідентифікатор гаманця покупця

header Parameters
X-Token
string

Токен з особистого кабінету https://web.monobank.ua/ або тестовий токен з https://api.monobank.ua/

Responses

Response samples

Content type
application/json
{
  • "wallet": [
    ]
}

Оплата по токену

Створення платежу за токеном картки

header Parameters
X-Token
string

Токен з особистого кабінету https://web.monobank.ua/ або тестовий токен з https://api.monobank.ua/

X-Cms
string

Назва CMS, якщо ви розробляєте платіжний модуль для CMS

X-Cms-Version
string

Версія CMS, якщо ви розробляєте платіжний модуль для CMS

Request Body schema: application/json
cardToken
required
string

Токен картки

amount
required
integer <int64>

Сума у мінімальних одиницях

ccy
required
integer <int32>

ISO 4217 код валюти

redirectUrl
string

Адреса для повернення (GET) - на цю адресу буде переадресовано користувача за умови проведення 3DS

webHookUrl
string

Адреса для CallBack (POST) – на цю адресу буде надіслано дані про стан платежу при кожній зміні статусу. Зміст тіла запиту ідентичний відповіді запиту “Статус рахунку”. Гарантії доставки повідомлень одне за одним не надається. Тобто, може бути ситуація, коли вебхук про успішну оплату (status=success) прийде пізніше за вебхук про обробку цієї оплати (status=processing). Краще орієнтуватись на поле modifiedDate при аналізі поточного статусу рахунку. Вебхук із більшим modifiedDate буде актуальним

initiationKind
required
string
Enum: "merchant" "client"

Тип проведення платежу:

merchant - платіж з ініціативи мерчанта, наприклад, регулярний платіж — коли клієнт не бере участі у підтвердженні платежу

client - платіж за вимогою клієнта, наприклад, клієнт виконує оплату зі збереженої картки

object (MerchantPaymInfoItem)

Інформаційні дані замовлення, яке буде оплачуватсь. Обовʼязково вказувати при активній звʼязці з ПРРО (звʼязка створюється у веб-кабінеті https://web.monobank.ua)

Responses

Request samples

Content type
application/json
{
  • "cardToken": "67XZtXdR4NpKU3",
  • "amount": 4200,
  • "ccy": 980,
  • "initiationKind": "merchant",
  • "merchantPaymInfo": {
    }
}

Response samples

Content type
application/json
{
  • "invoiceId": "2210012MPLYwJjVUzchj",
  • "status": "success",
  • "failureReason": "Неправильний CVV код",
  • "amount": 4200,
  • "ccy": 980,
  • "createdDate": "2019-08-24T14:15:22Z",
  • "modifiedDate": "2019-08-24T14:15:22Z"
}

Оплата за реквізитами

Створення рахунку та його оплата за реквізитами картки. Увага, це апі буде працювати тільки за умови наявності у мерчанта активного PCI DSS сертифіката!

header Parameters
X-Token
string

Токен з особистого кабінету https://web.monobank.ua/ або тестовий токен з https://api.monobank.ua/

X-Cms
string

Назва CMS, якщо ви розробляєте платіжний модуль для CMS

X-Cms-Version
string

Версія CMS, якщо ви розробляєте платіжний модуль для CMS

Request Body schema: application/json
amount
required
integer <int64>

Сума оплати у мінімальних одиницях (копійки для гривні)

ccy
integer <int32>

ISO 4217 код валюти, за замовчуванням 980 (гривня)

required
object

Дані картки

object (MerchantPaymInfoItem)

Інформаційні дані замовлення, яке буде оплачуватсь. Обовʼязково вказувати при активній звʼязці з ПРРО (звʼязка створюється у веб-кабінеті https://web.monobank.ua)

webHookUrl
string

Адреса для CallBack (POST) – на цю адресу буде надіслано дані про стан платежу при кожній зміні статусу. Зміст тіла запиту ідентичний відповіді запиту “Статус рахунку”. Гарантії доставки повідомлень одне за одним не надається. Тобто, може бути ситуація, коли вебхук про успішну оплату (status=success) прийде пізніше за вебхук про обробку цієї оплати (status=processing). Краще орієнтуватись на поле modifiedDate при аналізі поточного статусу рахунку. Вебхук із більшим modifiedDate буде актуальним

paymentType
string
Default: "debit"
Enum: "debit" "hold"

Тип операції. Для значення hold термін складає 9 днів. Якщо через 9 днів холд не буде фіналізовано — він скасовується

object

Дані для збереження (токенізації) картки. Для підключення функції, зверніться, будь ласка, в підтримку monobank. Токенізація недоступна за замовчуванням

redirectUrl
string

Адреса для повернення (GET) - на цю адресу буде переадресовано користувача після завершення оплати (у разі успіху або помилки), це поле обовʼязкове при initiationKind=client

initiationKind
string
Enum: "merchant" "client"

Тип проведення платежу:

merchant - платіж з ініціативи мерчанта, наприклад, регулярний платіж — коли клієнт не бере участі у підтвердженні платежу

client - платіж за вимогою клієнта

Responses

Request samples

Content type
application/json
{
  • "amount": 4200,
  • "ccy": 980,
  • "cardData": {
    },
  • "merchantPaymInfo": {
    },
  • "paymentType": "debit",
  • "saveCardData": {
    },
  • "initiationKind": "merchant"
}

Response samples

Content type
application/json
{
  • "invoiceId": "2210012MPLYwJjVUzchj",
  • "status": "success",
  • "failureReason": "Неправильний CVV код",
  • "amount": 4200,
  • "ccy": 980,
  • "createdDate": "2019-08-24T14:15:22Z",
  • "modifiedDate": "2019-08-24T14:15:22Z"
}

Список субмерчантів

Дане апі потрібне обмеженому колу осіб, яким при створенні рахунку треба явно вказувати термінал

header Parameters
X-Token
string

Токен з особистого кабінету https://web.monobank.ua/ або тестовий токен з https://api.monobank.ua/

Responses

Response samples

Content type
application/json
{
  • "list": [
    ]
}

Фіскальні чеки

Метод для отримання даних фіскальних чеків та їх статусів

query Parameters
invoiceId
string
Example: invoiceId=p2_9ZgpZVsl3

Ідентифікатор рахунку

header Parameters
X-Token
string

Токен з особистого кабінету https://web.monobank.ua/ або тестовий токен з https://api.monobank.ua/

Responses

Response samples

Content type
application/json
{
  • "checks": [
    ]
}

DEPRECATED — Розширена інформація про успішну оплату

Дані апі застаріле! Слід використовувати Статус рахунку, замість цього апі

Дані про успішну оплату, якщо вона була здійснена

query Parameters
invoiceId
string
Example: invoiceId=p2_9ZgpZVsl3

Ідентифікатор рахунку

header Parameters
X-Token
string

Токен з особистого кабінету https://web.monobank.ua/ або тестовий токен з https://api.monobank.ua/

Responses

Response samples

Content type
application/json
{
  • "maskedPan": "444403******1902",
  • "approvalCode": "662476",
  • "rrn": "060189181768",
  • "amount": 4200,
  • "ccy": 980,
  • "finalAmount": 4200,
  • "createdDate": "2019-08-24T14:15:22Z",
  • "terminal": "MI001088",
  • "paymentScheme": "full",
  • "paymentMethod": "pan",
  • "fee": 420,
  • "domesticCard": true,
  • "country": "804",
  • "cancelList": [
    ]
}