Monobank Acquiring API

https://monobank.ua/api-docs/acquiring
Admin
Monobank Acquiring API is a comprehensive toolkit for merchants to integrate payment processing...
Tokens:108,563
Snippets:467
Trust Score:10
Update:2 days ago
Show doc for...
Tokens:
Raw
### Full integration example (HTML, JavaScript, CSS)

Source: https://monobank.ua/api-docs/acquiring/methods/ia/docs--widget-frame

Complete example combining HTML iframe, JavaScript event handling, and CSS centering. Includes a closeModal() helper function placeholder. The iframe container uses min-height: 100vh and padding: 20px.

```html
// html
<div class="iframe-container">
    <iframe
        id="payFrame"
        title="monopay"
        width="600"
        height="600"
        src="{{pageUrl}}"
        allow="payment *"
        style="border-radius: 24px;"
    ></iframe>
</div>

// javascript
// Обробка подій інтерфейсу
function listenFrame(event) {
    const data = JSON.parse(event.data || "{}");
   
    // Кнопка "назад" або "повернутись назад"
    if (data.message === "close-button") {
        closeModal();
    }
   
    // Діпклінк для мобільного додатку
    if (data.message === "monopay-link") {
        window.location.href = data.value;
    }
}

window.addEventListener("message", listenFrame, false);

// Допоміжні функції
function closeModal() {
    // Ваш код для закриття модального вікна
}

// css
.iframe-container {
    display: flex;
    justify-content: center;
    align-items: center;
    min-height: 100vh;
    padding: 20px;
}
```

--------------------------------

### Go Signature Verification Example

Source: https://monobank.ua/api-docs/acquiring/dev/webhooks/verify

Example Go code to verify the x-sign header of a webhook request using ECDSA.

```APIDOC
```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")
}
```
```

--------------------------------

### GET /api/merchant/qr/list - Response sample (200)

Source: https://monobank.ua/api-docs/acquiring/methods/qr/get--api--merchant--qr--list

Example JSON response for the QR list endpoint, showing a QR cashier with amountType set to null.

```json
{
  "list": [
    {
      "shortQrId": "OBJE",
      "qrId": "XJ_DiM4rTd5V",
      "amountType": null,
      "pageUrl": "https://pay.mbnk.biz/XJ_DiM4rTd5V"
    }
  ]
}
```

--------------------------------

### GET /api/merchant/qr/details - Response 200

Source: https://monobank.ua/api-docs/acquiring/methods/qr/get--api--merchant--qr--list

Example JSON response for getting QR cashier information. Only for activated QR cashiers. The response includes shortQrId, amount (in minor units), ccy (ISO 4217), and invoiceId (present only when amount is set).

```json
{
  "shortQrId": "OBJE",
  "amount": 4200,
  "ccy": 980,
  "invoiceId": "4EwIUTA12JIZ"
}
```

--------------------------------

### window.MonoPay.init()

Source: https://monobank.ua/api-docs/acquiring/methods/monopay/docs--js-widget

Initializes the Monopay widget and returns an object containing the button DOM element. Accepts configuration parameters and callbacks.

```APIDOC
## window.MonoPay.init()

### Description
Initializes the Monopay widget and returns an object containing the button DOM element. Accepts configuration parameters and callbacks.

### Method
JavaScript

### Parameters
#### Configuration Object
- **keyId** (string) - Required - Ідентифікатор ключа криптування, отриманий з API отримання списку ключів для підпису
- **signature** (string) - Required - Зашифрований підпис даних замовлення, згенерований на бекенді мерчанта за допомогою clientKey
- **requestId** (string) - Required - Унікальний ідентифікатор запиту з TTL 10 хвилин. Використовується для забезпечення ідемпотентності операцій
- **payloadBase64** (string) - Required - Base64 закодовані дані замовлення у форматі JSON. Структура ідентична параметрам API створення рахунку
- **ui** (object UIConfig) - Optional - Налаштування зовнішнього вигляду кнопки
- **callbacks** (object CallbackConfig) - Optional - Колбек-функції для обробки подій віджета

### Request Example
const { button } = window.MonoPay.init({
    keyId: "pk_test_your_key_id_here",
    signature: "generated_signature_hash", 
    requestId: "unique_request_id_12345",
    payloadBase64: "eyJhbW91bnQiOjUwMDAsImNjeSI6OTgwLCJtZXJjaGFudFBheW1JbmZvIjp7InJlZmVyZW5jZSI6Ijg0ZDAwNzBlZTRlNDQ2NjdiMzEzNzFkOGY4ODEzOTQ3IiwiZGVzdGluYXRpb24iOiLQn9C+0LrRg9C/0LrQsCDRidCw0YHRgtG8IiwiY29tbWVudCI6ItCf0L7QutGD0L/QutCwINGJ0LDRgdGC0Y8ifX0=",
    ui: {
        buttonType: "pay",
        theme: "dark",
        corners: "rounded",
    },
    callbacks: {
        onButtonReady: () => {
            console.log("MonoPay button is ready");
        },
        onClick: () => {
            console.log("Payment button clicked");
        },
        onInvoiceCreate: (data) => {
            console.log("Invoice created:", data);
        },
        onSuccess: (result) => {
            console.log("Payment successful:", result);
        },
        onError: (error) => {
            console.error("Payment error:", error);
        },
    },
});

// Додаємо кнопку на сторінку
const buttonContainer = document.getElementById("payment-container");
if (buttonContainer) {
    buttonContainer.appendChild(button);
}
```

--------------------------------

### GET /api/merchant/details - Response 200 JSON

Source: https://monobank.ua/api-docs/acquiring/integrations/marketplace-and-agents/get--api--merchant--submerchant--list

Example response for the merchant details endpoint. Returns merchantId, merchantName, and edrpou fields.

```json
{
  "merchantId": "12o4Vv7EWy",
  "merchantName": "Your Favourite Company",
  "edrpou": "4242424242"
}
```

--------------------------------

### Update widget configuration with window.MonoPay.update()

Source: https://monobank.ua/api-docs/acquiring/methods/monopay/docs--js-widget

Use this method to apply new settings to the widget after initialization. It accepts the same configuration options as the init() method. The example changes the UI theme to light and replaces the success callback with a new handler.

```javascript
window.MonoPay.update({
    ui: { theme: "light" },
    callbacks: { onSuccess: newSuccessHandler }
});
```

--------------------------------

### GET /api/merchant/submerchant/list - Response 200 JSON

Source: https://monobank.ua/api-docs/acquiring/integrations/marketplace-and-agents/get--api--merchant--submerchant--list

Example response for the submerchant list endpoint. Returns a list of submerchants with code, iban, edrpou, and owner fields.

```json
{
  "list": [
    {
      "code": "0a8637b3bccb42aa93fdeb791b8b58e9",
      "iban": "UA213996220000026007233566001",
      "edrpou": "4242424242",
      "owner": "ТОВ Ворона"
    }
  ]
}
```

--------------------------------

### GET /api/merchant/wallet - Response 200 JSON

Source: https://monobank.ua/api-docs/acquiring/extras/tokens/delete--api--merchant--wallet--card

Example response for listing tokenized cards in a wallet. Returns a wallet array with cardToken, maskedPan, and optional country fields.

```json
{
  "wallet": [
    {
      "cardToken": "67XZtXdR4NpKU3",
      "maskedPan": "424242******4242",
      "country": "804"
    }
  ]
}
```

--------------------------------

### Initialize MonoPay widget with configuration

Source: https://monobank.ua/api-docs/acquiring/methods/monopay/docs--js-widget

Initializes the MonoPay widget using window.MonoPay.init() with required parameters (keyId, signature, requestId, payloadBase64) and optional UI and callbacks. The returned button is appended to a container element.

```JavaScript
function initializeMonoPay () {
	console.log("MonoPay script loaded successfully");

	const { button } = window.MonoPay.init({
		keyId: "pk_test_your_key_id_here",
		signature: "generated_signature_hash", 
		requestId: "unique_request_id_12345",
		payloadBase64: "eyJhbW91bnQiOjUwMDAsImNjeSI6OTgwLCJtZXJjaGFudFBheW1JbmZvIjp7InJlZmVyZW5jZSI6Ijg0ZDAwNzBlZTRlNDQ2NjdiMzEzNzFkOGY4ODEzOTQ3IiwiZGVzdGluYXRpb24iOiLQn9C+0LrRg9C/0LrQsCDRidCw0YHRgtG8IiwiY29tbWVudCI6ItCf0L7QutGD0L/QutCwINGJ0LDRgdGC0Y8ifX0=",
		// Налаштування UI
		ui: {
			buttonType: "pay",
			theme: "dark",
			corners: "rounded",
		},
		// Колбеки подій
		callbacks: {
			onButtonReady: () => {
				console.log("MonoPay button is ready");
			},
			onClick: () => {
				console.log("Payment button clicked");
			},
			onInvoiceCreate: (data) => {
				console.log("Invoice created:", data);
				// Можна додати додаткову логіку після створення інвойса
			},
			onSuccess: (result) => {
				console.log("Payment successful:", result);
				// Перенаправлення або показ повідомлення успіху
			},
			onError: (error) => {
				console.error("Payment error:", error);
				// Показ повідомлення про помилку
			},
		},
	});

	// Додаємо кнопку на сторінку
	const buttonContainer = document.getElementById("payment-container");
	if (buttonContainer) {
		buttonContainer.appendChild(button);
	}
}
```

--------------------------------

### GET /api/merchant/qr/list - Response 200

Source: https://monobank.ua/api-docs/acquiring/methods/qr/get--api--merchant--qr--list

Example JSON response for listing all QR cashiers. The response contains a list of QR cashiers with qrId, shortQrId, amountType (merchant, client, or fix), and pageUrl.

```json
{
  "list": [
    {
      "qrId": "XJ_DiM4rTd5V",
      "shortQrId": "OBJE",
      "amountType": "merchant",
      "pageUrl": "https://pay.mbnk.biz/XJ_DiM4rTd5V"
    }
  ]
}
```

--------------------------------

### Verify webhook signature in Go

Source: https://monobank.ua/api-docs/acquiring/dev/webhooks/verify

Go example to verify the x-sign header of a webhook request. It decodes the base64-encoded public key and signature, parses the PEM public key, computes SHA-256 hash of the body, and verifies the ECDSA signature. Panics on any error, including invalid signature.

```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")
}
```

--------------------------------

### Response 200 for GET /api/merchant/statement

Source: https://monobank.ua/api-docs/acquiring/extras/statement/get--api--merchant--statement

Example JSON response returned when the request is successful. It contains a list of statement items with fields like invoiceId, status, maskedPan, date, amount, ccy, profitAmount, reference, destination, approvalCode, rrn, paymentScheme, shortQrId, and cancelList.

```json
{
  "list": [
    {
      "invoiceId": "2205175v4MfatvmUL2oR",
      "status": "success",
      "maskedPan": "444403******1902",
      "date": "2023-01-01T12:00:00Z",
      "amount": 4200,
      "ccy": 980,
      "profitAmount": 4100,
      "reference": "84d0070ee4e44667b31371d8f8813947",
      "destination": "Покупка щастя",
      "approvalCode": "662476",
      "rrn": "060189181768",
      "paymentScheme": "full",
      "shortQrId": null,
      "cancelList": []
    }
  ]
}
```

--------------------------------

### Initialize widget and insert button

Source: https://monobank.ua/api-docs/acquiring/methods/monopay/docs--js-widget

Shows how to call window.MonoPay.init() with keyId, signature, requestId, and payloadBase64, then insert the returned button DOM element into the page using appendChild or insertAdjacentElement.

```javascript
// Ініціалізуємо віджет
const monoPay = window.MonoPay.init({
	keyId: "your_key_id",
	signature: "your_signature",
	requestId: "unique_id",
	payloadBase64: "encoded_order_data"
});

// monoPay.button - готовий DOM елемент кнопки
const container = document.getElementById("payment-container");
container.appendChild(monoPay.button);

// Альтернативно:
document.querySelector("#payment-section").insertAdjacentElement("beforeend", monoPay.button);
```

--------------------------------

### GET /api/merchant/qr/details

Source: https://monobank.ua/api-docs/acquiring/methods/qr/get--api--merchant--qr--list

Get QR cashier information. Only for activated QR cashiers.

```APIDOC
## GET /api/merchant/qr/details

### Description
Get QR cashier information. Only for activated QR cashiers.

### Method
GET

### Endpoint
/api/merchant/qr/details

### Parameters
#### Headers
- **X-Token** (string) - Required - Merchant token

#### Query Parameters
- **qrId** (string) - Required - QR cashier ID

### Response
#### Success Response (200)
- **shortQrId** (string) - Required - Short QR cashier ID. Example: `OBJE`
- **amount** (integer) - Optional - Amount in minor units (present if amount is set). Example: `4200`
- **ccy** (integer) - Optional - ISO 4217 currency code. Example: `980`
- **invoiceId** (string) - Optional - Invoice ID (present only when amount is set). Example: `4EwIUTA12JIZ`

#### Response Example
```json
{
  "shortQrId": "OBJE",
  "amount": 4200,
  "ccy": 980,
  "invoiceId": "4EwIUTA12JIZ"
}
```

### Errors
400, 403, 404, 405, 429, 500 — see common errors in SKILL.md
```

--------------------------------

### Initialize Widget and Insert Button

Source: https://monobank.ua/api-docs/acquiring/methods/monopay/docs--js-widget

The init() method returns an object with a DOM button element that can be inserted anywhere on the page.

```APIDOC
## Initialize Widget and Insert Button

### Description
The `init()` method returns an object with a DOM button element that can be inserted anywhere on the page.

### Parameters
- **keyId** (string) - Your key ID.
- **signature** (string) - The generated signature.
- **requestId** (string) - Unique identifier.
- **payloadBase64** (string) - Encoded order data.

### Example
```javascript
// Initialize the widget
const monoPay = window.MonoPay.init({
	keyId: "your_key_id",
	signature: "your_signature",
	requestId: "unique_id",
	payloadBase64: "encoded_order_data"
});

// monoPay.button - ready DOM button element
const container = document.getElementById("payment-container");
container.appendChild(monoPay.button);

// Alternative:
document.querySelector("#payment-section").insertAdjacentElement("beforeend", monoPay.button);
```
```
Tokens:
Raw