Introduction

P2P Market API - повна документація з детальними поясненнями інтеграції, прикладами коду та стандартними flow для прийому платежів через P2P обмін.

Base URL: https://api.p2p-market.net/

Ласкаво просимо до API документації P2P Market!

P2P Market - це платформа для прийому платежів через P2P обмін. Наша система автоматично з'єднує ваших клієнтів між собою, що дозволяє значно знизити комісії та підвищити конверсію.

🔑 Швидкий старт з X-API-Key

Всі запити до API повинні містити заголовок X-API-Key з вашим API ключем мерчанта.

Приклади використання:

cURL:

curl -X POST "https://p2p-market.net/api/v1/payout" \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "merchant_payout_id": "payout_12345",
    "amount_total": 1000.50,
    "currency": "UAH",
    "recipient_card_number": "4441111111111111",
    "partner_user_id": "user_67890"
  }'

JavaScript (fetch):

const response = await fetch("https://p2p-market.net/api/v1/auth/token", {
  method: "POST",
  headers: {
    "X-API-Key": "your-api-key-here",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    partner_user_id: "user_12345",
    redirect_url: "https://yoursite.com/success"
  })
});

const result = await response.json();

PHP:

$headers = [
    'X-API-Key: your-api-key-here',
    'Content-Type: application/json'
];

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://p2p-market.net/api/v1/payout');
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
curl_close($ch);

Python:

import requests

headers = {
    'X-API-Key': 'your-api-key-here',
    'Content-Type': 'application/json'
}

response = requests.post(
    'https://p2p-market.net/api/v1/auth/token',
    headers=headers,
    json={
        'partner_user_id': 'user_12345',
        'redirect_url': 'https://yoursite.com/success'
    }
)

result = response.json()

📋 Де отримати API ключ: Панель мерчанта → Налаштування → API ключі

🚀 Як працює P2P Market

Основна ідея: ваші клієнти обмінюються коштами між собою через нашу платформу.

Приклад: Клієнт А хоче поповнити баланс на 1000₴, а клієнт Б хоче вивести 1000₴. Система автоматично з'єднує їх, клієнт Б переказує 1000₴ клієнту А, обидва отримують свої послуги, а ви платите лише 11₴ комісії.

📋 Стандартна інтеграція

Крок 1: Створення виплати (Backend)

Коли у вас є клієнт, який хоче вивести кошти, створюєте виплату через API:

POST /api/v1/payout
{
  "merchant_payout_id": "payout_12345",
  "amount_total": 1000.50,
  "currency": "UAH",
  "recipient_card_number": "4441111111111111",
  "merchant_user_id": "user_67890",
  "metadata": {
    "customer_name": "Іван Петров"
  }
}

⚠️ Важливо: Валідація суми виплати

Сума виплати повинна бути кратна кроку платежу вашого мерчанта.

Приклад: якщо крок платежу = 50 ₴, то:

✅ Допустимі суми: 50, 100, 150, 200, 250, ..., 9950, 10000
❌ Заборонені суми: 75, 125, 1001, 2500.50

Для отримання актуальних лімітів використовуйте:

GET /api/v1/merchant/settings

Результат: Створюється виплата у статусі pending, очікує поповнень від інших користувачів.

Крок 2: Поповнення через токен авторизації (Рекомендований підхід)

Замість прямого API виклику для створення платежу, рекомендуємо перенаправляти користувачів на наш інтерфейс:

POST /api/v1/auth/token
{
  "partner_user_id": "user_12345",
  "redirect_url": "https://yoursite.com/payment-success",
  "metadata": {
    "name": "Марія Іванова",
    "email": "[email protected]"
  }
}

Відповідь:

{
  "success": true,
  "data": {
    "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
    "auth_url": "https://p2p-market.net/auth?token=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..."
  }
}

Переваги цього підходу:

🎯 Користувач сам обирає суму та банк
📱 Адаптивний мобільний інтерфейс
🔒 Автоматична верифікація PDF чеків
⚡ Миттєві сповіщення про статус
🏦 Підтримка 6 банків України

Крок 3: Webhook сповіщення

При створенні платежу (order.created)

{
  "id": 456,
  "merchant_payment_id": "payment_12345",
  "status": "new",
  "amount": 500.30,
  "currency": "UAH",
  "merchant_user_id": "user_98765",
  "created_at": "2024-01-15T14:00:00Z",
  "merchant_payout_id": "payout_67890"
}

При оплаті (order.paid)

{
  "id": 456,
  "merchant_payment_id": "payment_12345",
  "status": "paid",
  "amount": 500.30,
  "receipts": [
    {
      "id": 789,
      "official_url": "https://pb.com/receipt/abc123",
      "match_score": 0.95,
      "created_at": "2024-01-15T14:30:00Z"
    }
  ],
  "completed_at": "2024-01-15T14:35:00Z"
}

При підтвердженні через 24 години (order.confirmed)

{
  "id": 456,
  "merchant_payment_id": "payment_12345",
  "status": "confirmed",
  "amount": 500.30,
  "receipts": [
    {
      "id": 789,
      "official_url": "https://pb.com/receipt/abc123",
      "match_score": 0.95,
      "created_at": "2024-01-15T14:30:00Z"
    }
  ],
  "confirmed_at": "2024-01-16T14:35:00Z"
}

⚠️ Важливо: Логіка підтвердження платежів

Статуси платежів:

paid - Платіж оплачено і підтверджено
confirmed - Платіж автоматично підтверджено через 24 години після статусу "paid"
disputed - Платіж оскаржено користувачем

Правила оскарження:

🕐 24-годинне вікно: Користувачі можуть оскаржити платіж тільки протягом 24 годин після встановлення статусу "paid"
🔒 Автопідтвердження: Через 24 години статус автоматично змінюється на "confirmed"
❌ Заборона оскарження: Платежі зі статусом "confirmed" не можуть бути оскаржені
📧 Webhook: При зміні статусу на "confirmed" відправляється webhook order.confirmed

Повернення коштів:

Якщо користувач надав достатні докази того, що кошти не надійшли, платіж може бути переведений в статус "refunded"

🔧 Налаштування

1. Отримання API ключа

Зареєструйтесь в [кабінеті мерчанта]
Пройдіть верифікацію
Отримайте API ключ в розділі "Мерчанти" => "Налаштування"

2. Налаштування webhook URLs

В кабінеті мерчанта вкажіть:

webhook_payment - для сповіщень про платежі
webhook_payout - для сповіщень про виплати

3. Налаштування лімітів платежів

В кабінеті мерчанта налаштуйте:

Мінімальна сума - найменша сума для виплати
Максимальна сума - найбільша сума для виплати
Крок платежу - на яку суму можна збільшувати виплату (керується системою)

4. Sandbox режим

Для тестування увімкніть sandbox в налаштуваннях мерчанта. В цьому режимі:

Використовуються тестові дані
Реальні гроші не переказуються
Можна тестувати всі сценарії
Не відбувається верифікація квитанцій
Усі квитанції верифікуються як успішні

💡 Рекомендації по інтеграції

✅ Найкращі практики

Використовуйте токени авторизації замість прямих API викликів для створення платежів
Перевіряйте ліміти мерчанта перед створенням виплати через GET /merchant/settings
Валідуйте суми на кратність кроку платежу на своїй стороні
Налаштуйте webhook URLs для автоматичного отримання статусів
Перевіряйте підписи webhook'ів для безпеки
Обробляйте всі статуси платежів та виплат
Зберігайте merchant_payment_id для ідентифікації платежів

🔄 Типовий flow

1. [Backend] Отримання лімітів → GET /merchant/settings
2. [Backend] Валідація суми на кратність кроку
3. [Backend] Створення виплати → POST /payout
4. [Frontend] Створення токена → POST /auth/token
5. [Frontend] Редірект користувача → GET auth_url
6. [P2P Market] Користувач обирає суму/банк
7. [P2P Market] Створення платежу → webhook order.created
8. [P2P Market] Користувач оплачує → webhook order.paid
9. [P2P Market] Повна виплата → webhook payout.completed

🛡️ Безпека

Перевірка підпису webhook:

$receivedSignature = $_SERVER['HTTP_X_SIGNATURE'];
$jsonBody = file_get_contents('php://input');
$expectedSignature = hash_hmac('sha256', $jsonBody, $yourApiKey);

if (!hash_equals($expectedSignature, $receivedSignature)) {
    http_response_code(401);
    exit('Invalid signature');
}

📊 Основні можливості

💰 Створення виплат - автоматичне створення заявок на виплату з валідацією сум
📱 Токени авторизації - безпечний доступ користувачів до інтерфейсу
📊 Відстеження статусів - моніторинг стану операцій в реальному часі
🔗 Webhooks - автоматичні сповіщення про зміни статусів
🎯 Гнучкі ліміти - налаштування мінімальних/максимальних сум та кроків платежу
🧪 Sandbox режим - тестування без реальних коштів
🏦 6 банків - ПриватБанк, Монобанк, А-банк, Райффайзен, Ощадбанк, ПУМБ

🚀 Швидкий старт (5 хвилин)

Реєстрація: Створіть акаунт мерчанта
API ключ: Отримайте ключ в налаштуваннях
Ліміти: Налаштуйте мінімальні/максимальні суми в кабінеті
Webhook URLs: Вкажіть адреси для сповіщень
Sandbox: Увімкніть тестовий режим
Валідація: Отримайте ліміти через GET /merchant/settings
Тестування: Створіть тестову виплату з правильною сумою

Всі запити повинні містити заголовок X-API-Key з вашим API ключем.

Потрібна допомога? Напишіть в Telegram підтримку або email: [email protected]

Authenticating requests

To authenticate requests, include a X-API-Key header with the value "your-api-key-here".

All authenticated endpoints are marked with a requires authentication badge in the documentation below.

API ключ мерчанта для аутентифікації. Отримується в кабінеті мерчанта після реєстрації.

Аутентифікація

Створення токену авторизації

Створює тимчасовий токен для авторизації користувача в веб-інтерфейсі P2P системи.

Принцип роботи

Створення токену - генерується унікальний токен з терміном дії
Перенаправлення - користувач переходить по auth_url для авторизації
Автоматичний вхід - система автоматично авторизує користувача
Доступ до інтерфейсу - користувач отримує доступ до веб-інтерфейсу

Сценарії використання

Платежі - перенаправлення користувача на сторінку оплати
Виплати - доступ до особистого кабінету для перегляду виплат
Історія операцій - перегляд транзакцій та статусів
Підтримка - доступ до чату з підтримкою

Безпека

Токени мають обмежений час життя (за замовчуванням 60 хвилин)
Одноразове використання або обмежена кількість використань
Прив'язка до IP адреси (опціонально)
Автоматичне видалення прострочених токенів

🔄 Переспрямування після авторизації

Після автоматичної авторизації користувач може бути перенаправлений на конкретні сторінки системи додавши параметр page до auth_url.

*Доступні сторінки для переспрямування:**

Параметр	Призначення	Приклад URL
`deposit`	Сторінка створення поповнення	`/auth?token=...&page=deposit`
`payout`	Список виплат користувача	`/auth?token=...&page=payout`
`terms`	Умови користування	`/auth?token=...&page=terms`
`order`	Конкретне замовлення	`/auth?token=...&page=order&orderId=123`

Example request:

curl --request POST \
    "https://api.p2p-market.net/api/v1/auth/token" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"partner_user_id\": \"user_12345\",
    \"redirect_url\": \"https:\\/\\/yoursite.com\\/dashboard\",
    \"metadata\": {
        \"name\": \"Іван Петров\",
        \"email\": \"[email protected]\",
        \"phone\": \"+380501234567\"
    },
    \"expires_in_minutes\": 120
}"

const url = new URL(
    "https://api.p2p-market.net/api/v1/auth/token"
);

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "partner_user_id": "user_12345",
    "redirect_url": "https:\/\/yoursite.com\/dashboard",
    "metadata": {
        "name": "Іван Петров",
        "email": "[email protected]",
        "phone": "+380501234567"
    },
    "expires_in_minutes": 120
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$url = 'https://api.p2p-market.net/api/v1/auth/token';
$response = $client->post(
    $url,
    [
        'headers' => [
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'json' => [
            'partner_user_id' => 'user_12345',
            'redirect_url' => 'https://yoursite.com/dashboard',
            'metadata' => [
                'name' => 'Іван Петров',
                'email' => '[email protected]',
                'phone' => '+380501234567',
            ],
            'expires_in_minutes' => 120,
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, Успішне створення токену):


{
    "success": true,
    "data": {
        "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
        "expires_at": "2024-01-15T12:30:00Z",
        "auth_url": "https://p2pmarket.com/auth?token=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..."
    }
}

Example response (200, Токен без redirect_url):


{
    "success": true,
    "data": {
        "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
        "expires_at": "2024-01-15T11:30:00Z"
    }
}

Example response (401, Невірний API ключ):


{
    "success": false,
    "message": "Невірний API ключ або аккаунт неактивний та не в тестовому режимі",
    "error_code": "INVALID_API_KEY"
}

Example response (422, Помилки валідації):


{
    "success": false,
    "message": "Помилки валідації",
    "errors": {
        "partner_user_id": [
            "ID користувача у системі мерчанта є обов'язковим"
        ],
        "expires_in_minutes": [
            "Час життя токену має бути числом"
        ]
    }
}

Example response (500, Внутрішня помилка сервера):


{
    "success": false,
    "message": "Помилка при створенні токена авторизації: Internal server error"
}

Received response:

Request failed with error:



Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

Request

POST api/v1/auth/token

Headers

Content-Type

Example: application/json

Accept

Example: application/json

Body Parameters

partner_user_id string

ID користувача в системі мерчанта. Example: user_12345

redirect_url string optional

URL для перенаправлення після авторизації. Example: https://yoursite.com/dashboard

metadata object optional

Додаткові дані користувача (ім'я, email, тощо).

expires_in_minutes integer optional

Час життя токену в хвилинах (за замовчуванням 60). Example: 120

Вебхуки

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

Інформація про вебхуки

Цей ендпоінт надає детальну інформацію про систему вебхуків P2P Market, включаючи всі типи подій, структуру даних та налаштування.

Огляд вебхуків

Система вебхуків P2P Market автоматично надсилає сповіщення про зміни статусів платежів та виплат на вказані вами URL адреси. Це дозволяє вашій системі миттєво отримувати інформацію про стан операцій.

Налаштування вебхуків

Вебхуки налаштовуються в кабінеті мерчанта або через API:

Платежі: webhook_payment - URL для сповіщень про платежі
Виплати: webhook_payout - URL для сповіщень про виплати

Безпека

Кожен вебхук підписується вашим API ключем:

Заголовок X-Signature містить HMAC SHA256 підпис
Для перевірки використовуйте: hash_hmac('sha256', $jsonBody, $yourApiKey)

Повторні спроби

При невдачі система робить до 5 спроб відправки з інтервалом:

1-а спроба: миттєво
2-а спроба: через 15 хвилин
3-я спроба: через 30 хвилин
4-а спроба: через 45 хвилин
5-а спроба: через 1 годину

Example request:

curl --request GET \
    --get "https://api.p2p-market.net/api/v1/webhooks/info" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

const url = new URL(
    "https://api.p2p-market.net/api/v1/webhooks/info"
);

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$url = 'https://api.p2p-market.net/api/v1/webhooks/info';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200):


{
    "message": "Webhook інформація",
    "events": {
        "payments": {
            "order.created": "Платіж створено",
            "order.paid": "Платіж оплачено",
            "order.canceled": "Платіж скасовано"
        },
        "payouts": {
            "payout.created": "Виплата створена",
            "payout.completed": "Виплата завершена",
            "payout.failed": "Виплата не вдалась",
            "payout.verification": "Виплата потребує верифікації"
        },
        "disputes": {
            "dispute.opened": "Спір відкрито",
            "dispute.resolved": "Спір вирішено"
        }
    },
    "headers": {
        "Content-Type": "application/json",
        "X-Signature": "hmac_sha256_signature",
        "X-Event-Type": "event_type"
    },
    "retry_policy": {
        "max_attempts": 5,
        "intervals": [
            "immediate",
            "15m",
            "1h",
            "6h",
            "24h"
        ]
    }
}

Received response:

Request failed with error:



Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

Приклад вебхука платежу

Демонстрація структури даних, які надсилаються при зміні статусу платежу. Ці дані приходять на URL, вказаний в налаштуваннях webhook_payment.

Коли надсилається:

order.created - при створенні нового платежу
order.paid - коли платіж оплачено (завантажено чек)
order.canceled - при скасуванні, закінченні терміну або поверненні

Заголовки:

Content-Type: application/json
X-Signature: {hmac_sha256_signature} - підпис для перевірки
X-Event-Type: {event_type} - тип події

Example request:

curl --request GET \
    --get "https://api.p2p-market.net/api/v1/webhooks/examples/payment" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

const url = new URL(
    "https://api.p2p-market.net/api/v1/webhooks/examples/payment"
);

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$url = 'https://api.p2p-market.net/api/v1/webhooks/examples/payment';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200):


{
    "id": 456,
    "merchant_payment_id": "payment_12345",
    "status": "completed",
    "currency": "UAH",
    "amount": 500.3,
    "merchant_user_id": "user_98765",
    "receipts": [
        {
            "id": 789,
            "official_url": "https://pb.com/receipt/abc123",
            "receipt_url": "https://p2pmarket.com/receipts/789",
            "created_at": "2024-01-15T14:30:00Z",
            "match_score": 100,
            "receipt_number": "1234567890"
        }
    ],
    "disputes": [],
    "has_overpayment": false,
    "created_at": "2024-01-15T14:00:00Z",
    "completed_at": "2024-01-15T14:35:00Z",
    "recipient_card_number": "1234********5678",
    "merchant_payout_id": "payout_67890"
}

Received response:

Request failed with error:



Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

Приклад вебхука виплати

Демонстрація структури даних, які надсилаються при зміні статусу виплати. Ці дані приходять на URL, вказаний в налаштуваннях webhook_payout.

Коли надсилається:

payout.created - при створенні нової виплати
payout.completed - при повному завершенні виплати
payout.failed - при скасуванні виплати
payout.verification - коли виплата потребує верифікації

Заголовки:

Content-Type: application/json
X-Signature: {hmac_sha256_signature} - підпис для перевірки
X-Event-Type: {event_type} - тип події

Example request:

curl --request GET \
    --get "https://api.p2p-market.net/api/v1/webhooks/examples/payout" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

const url = new URL(
    "https://api.p2p-market.net/api/v1/webhooks/examples/payout"
);

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$url = 'https://api.p2p-market.net/api/v1/webhooks/examples/payout';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200):


{
    "id": 123,
    "merchant_payout_id": "payout_67890",
    "status": "completed",
    "currency": "UAH",
    "amount_total": 1000.5,
    "amount_received": 750.3,
    "merchant_user_id": "user_98765",
    "orders": [
        {
            "id": 456,
            "status": "completed",
            "amount": 500.3,
            "receipts": [
                {
                    "id": 789,
                    "official_url": "https://pb.com/receipt/abc123",
                    "receipt_url": "https://p2pmarket.com/receipts/789",
                    "created_at": "2024-01-15T14:30:00Z",
                    "match_score": 0.95,
                    "receipt_number": "1234567890"
                }
            ],
            "created_at": "2024-01-15T14:00:00Z",
            "completed_at": "2024-01-15T14:35:00Z"
        },
        {
            "id": 457,
            "status": "completed",
            "amount": 250,
            "receipts": [
                {
                    "id": 790,
                    "official_url": "https://mono.com/receipt/def456",
                    "receipt_url": "https://p2pmarket.com/receipts/790",
                    "created_at": "2024-01-15T14:45:00Z",
                    "match_score": 0.98,
                    "receipt_number": "0987654321"
                }
            ],
            "created_at": "2024-01-15T14:15:00Z",
            "completed_at": "2024-01-15T14:50:00Z"
        }
    ],
    "created_at": "2024-01-15T13:45:00Z",
    "completed_at": "2024-01-15T14:50:00Z"
}

Received response:

Request failed with error:



Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

Стандартний flow інтеграції

Детальний опис стандартного процесу інтеграції з P2P Market з послідовністю API викликів та webhook сповіщень. Цей flow покриває 90% випадків використання.

Послідовність дій:

Етап 1: Підготовка виплати (Backend)

Мерчант створює виплату через API
Отримує merchant_payout_id для відстеження
Виплата переходить в статус "pending"

Етап 2: Поповнення користувачем (Frontend + P2P Market)

Мерчант створює токен авторизації для користувача
Перенаправляє користувача на auth_url
Користувач обирає суму та банк в інтерфейсі P2P Market
Система створює платіж та надсилає webhook order.created

Етап 3: Оплата (P2P Market)

Користувач завантажує PDF чек з банку
Система верифікує чек автоматично
Надсилається webhook order.paid при успішній верифікації

Етап 4: Завершення виплати (P2P Market)

Коли сума виплати повністю зібрана
Надсилається webhook payout.completed
Мерчант може надати послугу клієнту

Приклад timeline:

14:00 - POST /payout (merchant_payout_id: "payout_123")
14:05 - POST /auth/token → redirect користувача
14:10 - Webhook order.created (платіж 500₴)
14:15 - Користувач завантажує чек
14:16 - Webhook order.paid (платіж підтверджено)
14:20 - Webhook order.created (платіж 300₴)
14:25 - Webhook order.paid (другий платіж підтверджено)
14:26 - Webhook payout.completed (виплата 800₴ завершена)

Example request:

curl --request GET \
    --get "https://api.p2p-market.net/api/v1/webhooks/integration-flow" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

const url = new URL(
    "https://api.p2p-market.net/api/v1/webhooks/integration-flow"
);

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$url = 'https://api.p2p-market.net/api/v1/webhooks/integration-flow';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200):


{
    "integration_flow": {
        "step_1": {
            "title": "Створення виплати",
            "action": "POST /api/v1/payout",
            "description": "Мерчант створює виплату на backend",
            "webhook": null,
            "example": {
                "merchant_payout_id": "payout_12345",
                "amount_total": 1000,
                "recipient_card_number": "4441111111111111"
            }
        },
        "step_2": {
            "title": "Токен авторизації",
            "action": "POST /api/v1/auth/token",
            "description": "Створення токена для перенаправлення користувача",
            "webhook": null,
            "result": "auth_url для редіректу"
        },
        "step_3": {
            "title": "Створення платежу",
            "action": "Користувач в P2P Market інтерфейсі",
            "description": "Користувач обирає суму та банк",
            "webhook": "order.created",
            "timing": "Миттєво після вибору"
        },
        "step_4": {
            "title": "Оплата платежу",
            "action": "Завантаження PDF чека",
            "description": "Користувач завантажує чек з банку",
            "webhook": "order.paid",
            "timing": "Після верифікації чека"
        },
        "step_5": {
            "title": "Завершення виплати",
            "action": "Автоматично",
            "description": "Коли сума виплати повністю зібрана",
            "webhook": "payout.completed",
            "timing": "При досягненні повної суми"
        }
    },
    "best_practices": [
        "Використовуйте токени авторизації замість прямих API викликів",
        "Налаштуйте обробку всіх типів webhook сповіщень",
        "Зберігайте merchant_payment_id для ідентифікації",
        "Перевіряйте підписи webhook для безпеки",
        "Обробляйте повторні webhook (idempotency)"
    ],
    "timing": {
        "token_creation": "< 1 секунди",
        "user_payment_process": "2-5 хвилин",
        "pdf_verification": "< 30 секунд",
        "webhook_delivery": "< 5 секунд"
    }
}

Received response:

Request failed with error:



Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

Перевірка підпису вебхука

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

Алгоритм перевірки:

Отримайте JSON тіло запиту як рядок
Згенеруйте підпис: hash_hmac('sha256', $jsonBody, $yourApiKey)
Порівняйте з заголовком X-Signature

Приклад коду (PHP):

$receivedSignature = $_SERVER['HTTP_X_SIGNATURE'];
$jsonBody = file_get_contents('php://input');
$expectedSignature = hash_hmac('sha256', $jsonBody, $yourApiKey);

if (!hash_equals($expectedSignature, $receivedSignature)) {
    http_response_code(401);
    exit('Invalid signature');
}

Example request:

curl --request GET \
    --get "https://api.p2p-market.net/api/v1/webhooks/signature-verification" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

const url = new URL(
    "https://api.p2p-market.net/api/v1/webhooks/signature-verification"
);

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$url = 'https://api.p2p-market.net/api/v1/webhooks/signature-verification';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200):


{
    "algorithm": "HMAC SHA256",
    "header": "X-Signature",
    "input": "JSON тіло запиту + ваш API ключ",
    "example": {
        "json_body": "{\"id\":123,\"status\":\"completed\"}",
        "api_key": "your-api-key-here",
        "signature": "5f3c4b2a1e9d8c7b6a5f4e3d2c1b0a9f8e7d6c5b4a3f2e1d0c9b8a7f6e5d4c3b2a1"
    },
    "security_notes": [
        "Завжди використовуйте hash_equals() для порівняння підписів",
        "Перевіряйте підпис перед обробкою даних",
        "Зберігайте API ключ в безпеці",
        "Логуйте невалідні спроби для моніторингу"
    ]
}

Received response:

Request failed with error:



Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

Тестування вебхука

requires authentication

Відправити тестовий вебхук на вказаний URL для перевірки вашої інтеграції. Це допоможе переконатися, що ваша система правильно обробляє вебхуки.

Що надсилається:

Тестові дані платежу або виплати
Правильні заголовки з підписом
Вказаний тип події

Example request:

curl --request POST \
    "https://api.p2p-market.net/api/v1/webhooks/test" \
    --header "X-API-Key: your-api-key-here" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"url\": \"https:\\/\\/yoursite.com\\/webhook\",
    \"event_type\": \"order.confirmed\",
    \"data_type\": \"order\"
}"

const url = new URL(
    "https://api.p2p-market.net/api/v1/webhooks/test"
);

const headers = {
    "X-API-Key": "your-api-key-here",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "url": "https:\/\/yoursite.com\/webhook",
    "event_type": "order.confirmed",
    "data_type": "order"
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$url = 'https://api.p2p-market.net/api/v1/webhooks/test';
$response = $client->post(
    $url,
    [
        'headers' => [
            'X-API-Key' => 'your-api-key-here',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'json' => [
            'url' => 'https://yoursite.com/webhook',
            'event_type' => 'order.confirmed',
            'data_type' => 'order',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200):


{
    "success": true,
    "message": "Тестовий вебхук надіслано",
    "response": {
        "status_code": 200,
        "response_time": "125ms",
        "headers": {
            "Content-Type": "application/json",
            "X-Signature": "5f3c4...abc123",
            "X-Event-Type": "order.paid"
        }
    }
}

Example response (422):


{
    "success": false,
    "message": "Помилки валідації",
    "errors": {
        "url": [
            "Поле URL є обов'язковим"
        ],
        "event_type": [
            "Невірний тип події"
        ]
    }
}

Received response:

Request failed with error:



Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

Request

POST api/v1/webhooks/test

Headers

X-API-Key

Example: your-api-key-here

Content-Type

Example: application/json

Accept

Example: application/json

Body Parameters

url string

URL для тестового вебхука. Example: https://yoursite.com/webhook

event_type string

Тип події для тестування. Example: order.confirmed

data_type string

Тип даних (order або payout). Example: order

Виплати

Отримання статусу виплати

Повертає поточний статус виплати за її merchant_payout_id.

Можливі статуси виплати

pending - Виплата створена, очікує обробки
processing - Виплата в процесі обробки
partially_paid - Виплата частково сплачена
completed - Виплата повністю сплачена
cancelled - Виплата скасована
requires_verification - Потребує ручної перевірки

Додаткова інформація

Відповідь містить детальну інформацію про:

Суму виплати та отриману суму
Дані про отримувача (номер карти, банк)
Список платежів за цією виплатою
Sandbox статус (якщо застосовно)

Example request:

curl --request GET \
    --get "https://api.p2p-market.net/api/v1/payout/status?merchant_payout_id=payout_67890" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"merchant_payout_id\": \"lcqfq\"
}"

const url = new URL(
    "https://api.p2p-market.net/api/v1/payout/status"
);

const params = {
    "merchant_payout_id": "payout_67890",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "merchant_payout_id": "lcqfq"
};

fetch(url, {
    method: "GET",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$url = 'https://api.p2p-market.net/api/v1/payout/status';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'query' => [
            'merchant_payout_id' => 'payout_67890',
        ],
        'json' => [
            'merchant_payout_id' => 'lcqfq',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, Успішне отримання статусу):


{
    "success": true,
    "data": {
        "id": 123,
        "merchant_payout_id": "payout_67890",
        "amount_total": 1000.5,
        "amount_received": 750.3,
        "currency": "UAH",
        "status": "partially_paid",
        "recipient_card_number": "1234567890123456",
        "recipient_card_holder_name": "Ivan Petrov",
        "recipient_bank_name": "PrivatBank",
        "is_sandbox": false,
        "created_at": "2024-01-15T10:30:00Z",
        "updated_at": "2024-01-15T12:15:00Z",
        "orders": [
            {
                "id": 456,
                "amount": 500.3,
                "status": "confirmed",
                "created_at": "2024-01-15T11:00:00Z"
            },
            {
                "id": 457,
                "amount": 250,
                "status": "confirmed",
                "created_at": "2024-01-15T12:00:00Z"
            }
        ]
    },
    "sandbox_mode": false
}

Example response (200, Статус sandbox виплати):


{
    "success": true,
    "data": {
        "id": 124,
        "merchant_payout_id": "test_payout_123",
        "amount_total": 500,
        "amount_received": 500,
        "currency": "UAH",
        "status": "completed",
        "recipient_card_number": "1234567890123456",
        "recipient_card_holder_name": "Test User",
        "recipient_bank_name": "Test Bank",
        "is_sandbox": true,
        "created_at": "2024-01-15T10:31:00Z",
        "updated_at": "2024-01-15T10:32:00Z",
        "orders": []
    },
    "sandbox_mode": true,
    "sandbox_notice": "Тестова виплата - не впливає на реальний баланс"
}

Example response (401, Невірний API ключ):


{
    "success": false,
    "message": "Невірний API ключ або аккаунт неактивний та не в тестовому режимі",
    "error_code": "INVALID_API_KEY"
}

Example response (404, Виплата не знайдена):


{
    "success": false,
    "message": "Заявку на виплату не знайдено",
    "error_code": "PAYOUT_NOT_FOUND",
    "sandbox_mode": false
}

Example response (500, Внутрішня помилка сервера):


{
    "success": false,
    "message": "Помилка при отриманні статусу заявки на виплату: Internal server error",
    "error_code": "INTERNAL_ERROR",
    "sandbox_mode": false
}

Received response:

Request failed with error:



Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

Request

GET api/v1/payout/status

Headers

Content-Type

Example: application/json

Accept

Example: application/json

Query Parameters

merchant_payout_id string

ID виплати в системі мерчанта. Example: payout_67890

Body Parameters

merchant_payout_id string

Must not be greater than 191 characters. Example: lcqfq

Створення виплати

Створює нову заявку на виплату в P2P маркетплейсі.

Принцип роботи

Перевірка унікальності - система перевіряє чи не існує виплати з таким merchant_payout_id
Валідація суми - перевірка кратності суми кроку платежу та лімітів мерчанта
Створення користувача - якщо користувач з partner_user_id не існує, він буде створений автоматично
Резервування коштів - сума + комісія резервується на балансі мерчанта
Пошук плательщиків - система автоматично шукає користувачів готових здійснити оплату
Webhook сповіщення - надсилається сповіщення про створення виплати (якщо налаштовано)

Валідація суми виплати

Сума виплати повинна бути кратна кроку платежу мерчанта.

Приклад: якщо крок платежу = 50, то допустимі суми:

✅ 50, 100, 150, 200, 250... 9950, 10000
❌ 75, 125, 1001, 2500.50

Також сума повинна відповідати лімітам:

Мінімальна сума: отримується з налаштувань мерчанта
Максимальна сума: отримується з налаштувань мерчанта

Для отримання актуальних лімітів використовуйте GET /api/v1/merchant/settings

Sandbox режим

У тестовому режимі:

Всі операції помічаються як is_sandbox: true
Не впливають на реальний баланс
Автоматично підтверджуються платежі
Ізольовані від production даних

Example request:

curl --request POST \
    "https://api.p2p-market.net/api/v1/payout" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"partner_user_id\": \"user_12345\",
    \"amount_total\": 100000,
    \"currency\": \"UAH\",
    \"recipient_card_number\": \"1234567890123456\",
    \"recipient_card_holder_name\": \"Ivan Petrov\",
    \"recipient_bank_name\": \"PrivatBank\",
    \"wallet_address\": \"bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh\",
    \"rate\": 41.5,
    \"merchant_payout_id\": \"payout_67890\",
    \"meta\": {
        \"order_id\": \"123\",
        \"description\": \"Виплата за послуги\"
    }
}"

const url = new URL(
    "https://api.p2p-market.net/api/v1/payout"
);

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "partner_user_id": "user_12345",
    "amount_total": 100000,
    "currency": "UAH",
    "recipient_card_number": "1234567890123456",
    "recipient_card_holder_name": "Ivan Petrov",
    "recipient_bank_name": "PrivatBank",
    "wallet_address": "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh",
    "rate": 41.5,
    "merchant_payout_id": "payout_67890",
    "meta": {
        "order_id": "123",
        "description": "Виплата за послуги"
    }
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$url = 'https://api.p2p-market.net/api/v1/payout';
$response = $client->post(
    $url,
    [
        'headers' => [
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'json' => [
            'partner_user_id' => 'user_12345',
            'amount_total' => 100000.0,
            'currency' => 'UAH',
            'recipient_card_number' => '1234567890123456',
            'recipient_card_holder_name' => 'Ivan Petrov',
            'recipient_bank_name' => 'PrivatBank',
            'wallet_address' => 'bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh',
            'rate' => 41.5,
            'merchant_payout_id' => 'payout_67890',
            'meta' => [
                'order_id' => '123',
                'description' => 'Виплата за послуги',
            ],
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, Успішне створення виплати):


{
    "success": true,
    "data": {
        "id": 123,
        "merchant_payout_id": "payout_67890",
        "amount_total": 1000,
        "amount_received": 0,
        "currency": "UAH",
        "status": "pending",
        "recipient_card_number": "1234567890123456",
        "recipient_card_holder_name": "Ivan Petrov",
        "recipient_bank_name": "PrivatBank",
        "is_sandbox": false,
        "created_at": "2024-01-15T10:30:00Z",
        "updated_at": "2024-01-15T10:30:00Z"
    },
    "sandbox_mode": false
}

Example response (200, Створення в sandbox режимі):


{
    "success": true,
    "data": {
        "id": 124,
        "merchant_payout_id": "test_payout_123",
        "amount_total": 500,
        "amount_received": 0,
        "currency": "UAH",
        "status": "pending",
        "recipient_card_number": "1234567890123456",
        "recipient_card_holder_name": "Test User",
        "recipient_bank_name": "Test Bank",
        "is_sandbox": true,
        "created_at": "2024-01-15T10:31:00Z",
        "updated_at": "2024-01-15T10:31:00Z"
    },
    "sandbox_mode": true,
    "sandbox_notice": "Тестова виплата - не впливає на реальний баланс"
}

Example response (400, Дублювання ID виплати):


{
    "success": false,
    "message": "Заявка з таким merchant_payout_id вже існує",
    "error_code": "DUPLICATE_PAYOUT_ID",
    "sandbox_mode": false
}

Example response (401, Невірний API ключ):


{
    "success": false,
    "message": "Невірний API ключ або аккаунт неактивний та не в тестовому режимі",
    "error_code": "INVALID_API_KEY"
}

Example response (422, Помилки валідації):


{
    "success": false,
    "message": "Помилки валідації",
    "errors": {
        "partner_user_id": [
            "ID користувача у системі мерчанта є обов'язковим"
        ],
        "amount_total": [
            "Сума виплати повинна бути кратна кроку платежу 50 UAH. Допустимі суми: 50, 100, 150, 200, 250",
            "Сума виплати не може бути меншою за 50 UAH"
        ],
        "recipient_card_number": [
            "Необхідно вказати або номер карти або адресу гаманця"
        ]
    }
}

Example response (500, Внутрішня помилка сервера):


{
    "success": false,
    "message": "Помилка при створенні заявки на виплату: Internal server error",
    "error_code": "INTERNAL_ERROR",
    "sandbox_mode": false
}

Received response:

Request failed with error:



Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

Request

POST api/v1/payout

Headers

Content-Type

Example: application/json

Accept

Example: application/json

Body Parameters

partner_user_id string

ID користувача в системі мерчанта. Максимум 191 символ. Example: user_12345

amount_total number

Сума виплати. Повинна бути кратна кроку платежу мерчанта. Мінімум 50. Example: 100000

currency string

Валюта виплати (3 символи). Example: UAH

recipient_card_number string optional

Номер карти отримувача (16 цифр). Example: 1234567890123456

recipient_card_holder_name string optional

Ім'я власника карти. Обов'язкове якщо вказано номер карти. Example: Ivan Petrov

recipient_bank_name string optional

Назва банку. Визначається автоматично по номеру карти. Example: PrivatBank

wallet_address string optional

Адреса криптогаманця. Альтернатива номеру карти. Example: bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh

rate number optional

Курс обміну (опціонально). Example: 41.5

merchant_payout_id string optional

Унікальний ID виплати в системі мерчанта. Максимум 191 символ. Example: payout_67890

meta object optional

Додаткові дані (опціонально).

Налаштування мерчанта

Отримати налаштування мерчанта

Повертає базові налаштування мерчанта для інтеграції.

Інформація що повертається

Валюта - основна валюта мерчанта
Ліміти сум - мінімальна/максимальна суми платежів
Крок платежу - на яку суму можна збільшувати платіж
Дозволені банки - список банків для прийому платежів

Використання

Ці налаштування необхідні для:

Валідації сум перед створенням виплат
Відображення доступних банків у користувацькому інтерфейсі
Розрахунку комісій
Налаштування логіки автопідтвердження

Example request:

curl --request GET \
    --get "https://api.p2p-market.net/api/v1/merchant/settings" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

const url = new URL(
    "https://api.p2p-market.net/api/v1/merchant/settings"
);

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$url = 'https://api.p2p-market.net/api/v1/merchant/settings';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, Успішне отримання налаштувань):


{
    "success": true,
    "data": {
        "currency": "UAH",
        "min_payment_amount": 50,
        "max_payment_amount": 50000,
        "payment_step": 10,
        "allowed_banks": [
            "privatbank",
            "monobank",
            "abank"
        ],
        "auto_confirm_payments": true,
        "payment_timeout_minutes": 30,
        "commission_percentage": 1.5
    }
}

Example response (401, Невірний API ключ):


{
    "success": false,
    "message": "Невірний API ключ або аккаунт неактивний та не в тестовому режимі",
    "error_code": "INVALID_API_KEY"
}

Example response (404, Мерчант не знайдений):


{
    "success": false,
    "message": "Мерчант не знайдений"
}

Example response (500, Внутрішня помилка сервера):


{
    "success": false,
    "message": "Помилка при отриманні налаштувань: Internal server error"
}

Received response:

Request failed with error:



Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

Платежі

Отримання статусу платежу

requires authentication

Повертає детальну інформацію про платіж (замовлення) за його ID. Цей метод використовує загальний API ключ мерчанта.

Життєвий цикл платежу та логіка підтвердження

new - Платіж створений, очікує оплати
pending - Платіж призначений плательщику, очікує підтвердження
paid - Платіж оплачений, завантажено чек ✅
confirmed - Платіж автоматично підтверджено через 24 години після статусу "paid" 🔒
disputed - Відкрито спір по платежу ⚠️
expired - Час на оплату вичерпано
cancelled - Платіж скасований
refunded - Платіж повернено 💸

⚠️ Важливо: Правила оскарження платежів

24-годинне вікно оскарження:

Після встановлення статусу paid користувачі мають 24 години для подання скарги
Через 24 години статус автоматично змінюється на confirmed
Платежі зі статусом confirmed не можуть бути оскаржені
При зміні статусу на confirmed відправляється webhook order.confirmed

Повернення коштів:

Якщо користувач надав достатні докази того, що кошти не надійшли, платіж може бути переведений в статус refunded

Особливості Sandbox режиму

У тестовому режимі:

Платежі автоматично підтверджуються без ручної перевірки
Додаються спеціальні мітки sandbox_auto_confirm: true
Не впливають на реальні баланси

Приклад використання (PHP)

// Простий запит статусу платежу
$paymentId = 12345; // ID платежу отриманий при створенні

$ch = curl_init();
curl_setopt_array($ch, [
    CURLOPT_URL => 'https://domain.com/api/v1/order/status?payment_id=' . $paymentId,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['X-API-Key: YOUR_API_KEY']
]);

$response = curl_exec($ch);
$data = json_decode($response, true);

if ($data['success']) {
    $status = $data['data']['status'];
    $amount = $data['data']['amount'];

    switch ($status) {
        case 'pending':
            echo "Платіж очікує оплати на суму {$amount} UAH";
            break;
        case 'paid':
            echo "Платіж оплачений, очікує підтвердження";
            break;
        case 'confirmed':
            echo "Платіж успішно завершений!";
            break;
        case 'expired':
            echo "Термін оплати вичерпано";
            break;
        default:
            echo "Статус платежу: {$status}";
    }
} else {
    echo "Помилка: " . $data['message'];
}

Безпека

Кожен мерчант може отримувати інформацію тільки про власні платежі
Перевіряється відповідність sandbox/production режимів
Логуються всі запити для аудиту

Example request:

curl --request GET \
    --get "https://api.p2p-market.net/api/v1/order/status?payment_id=456" \
    --header "X-API-Key: your-api-key-here" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"payment_id\": \"qwajloqfeapbqtpr\"
}"

const url = new URL(
    "https://api.p2p-market.net/api/v1/order/status"
);

const params = {
    "payment_id": "456",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "X-API-Key": "your-api-key-here",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "payment_id": "qwajloqfeapbqtpr"
};

fetch(url, {
    method: "GET",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$url = 'https://api.p2p-market.net/api/v1/order/status';
$response = $client->get(
    $url,
    [
        'headers' => [
            'X-API-Key' => 'your-api-key-here',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'query' => [
            'payment_id' => '456',
        ],
        'json' => [
            'payment_id' => 'qwajloqfeapbqtpr',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, Успішне отримання статусу платежу):


{
    "success": true,
    "data": {
        "id": 456,
        "merchant_payment_id": "ORDER_123456",
        "status": "confirmed",
        "currency": "UAH",
        "amount": 500.3,
        "merchant_user_id": "customer_123",
        "created_at": "2024-01-15T11:00:00.000000Z",
        "completed_at": "2024-01-15T11:30:00.000000Z",
        "has_overpayment": false,
        "recipient_card_number": "5375 41** **** 1234",
        "merchant_payout_id": "payout_67890",
        "receipts": [
            {
                "id": 789,
                "official_url": "https://check.gov.ua/...",
                "receipt_url": "https://example.com/receipts/789.jpg",
                "match_score": 95.5,
                "receipt_number": "12345",
                "created_at": "2024-01-15T11:15:00.000000Z"
            }
        ],
        "disputes": [],
        "sandbox_mode": false
    }
}

Example response (200, Статус sandbox платежу):


{
    "success": true,
    "data": {
        "id": 457,
        "merchant_payment_id": "TEST_ORDER_123",
        "status": "confirmed",
        "currency": "UAH",
        "amount": 250,
        "merchant_user_id": "test_customer_456",
        "created_at": "2024-01-15T10:32:00.000000Z",
        "completed_at": "2024-01-15T10:32:00.000000Z",
        "has_overpayment": false,
        "recipient_card_number": "1234567890123456",
        "merchant_payout_id": "test_payout_123",
        "receipts": [],
        "disputes": [],
        "sandbox_mode": true
    }
}

Example response (200, Платіж в процесі):


{
    "success": true,
    "data": {
        "id": 458,
        "merchant_payment_id": "ORDER_789",
        "status": "pending",
        "currency": "UAH",
        "amount": 300,
        "merchant_user_id": "customer_789",
        "created_at": "2024-01-15T12:00:00.000000Z",
        "completed_at": null,
        "has_overpayment": false,
        "recipient_card_number": null,
        "merchant_payout_id": null,
        "receipts": [],
        "disputes": [],
        "sandbox_mode": false
    }
}

Example response (200, Платіж з переплатою):


{
    "success": true,
    "data": {
        "id": 459,
        "merchant_payment_id": "ORDER_999",
        "status": "paid",
        "currency": "UAH",
        "amount": 1000,
        "merchant_user_id": "customer_999",
        "created_at": "2024-01-15T13:00:00.000000Z",
        "completed_at": null,
        "has_overpayment": true,
        "recipient_card_number": "5375 41** **** 5678",
        "merchant_payout_id": "payout_999",
        "receipts": [
            {
                "id": 101,
                "official_url": "https://check.gov.ua/...",
                "receipt_url": "https://example.com/receipts/101.jpg",
                "match_score": 88.2,
                "receipt_number": "98765",
                "created_at": "2024-01-15T13:05:00.000000Z"
            }
        ],
        "disputes": [],
        "sandbox_mode": false
    }
}

Example response (200, Платіж зі спором):


{
    "success": true,
    "data": {
        "id": 460,
        "merchant_payment_id": "ORDER_DISPUTE",
        "status": "disputed",
        "currency": "UAH",
        "amount": 750,
        "merchant_user_id": "customer_dispute",
        "created_at": "2024-01-15T09:00:00.000000Z",
        "completed_at": null,
        "has_overpayment": false,
        "recipient_card_number": "4441 11** **** 9999",
        "merchant_payout_id": "payout_dispute",
        "receipts": [
            {
                "id": 102,
                "official_url": "https://check.gov.ua/...",
                "receipt_url": "https://example.com/receipts/102.jpg",
                "match_score": 45.3,
                "receipt_number": "11111",
                "created_at": "2024-01-15T09:15:00.000000Z"
            }
        ],
        "disputes": [
            {
                "id": 15,
                "status": "open",
                "reason": "Amount mismatch",
                "initiator": "system",
                "created_at": "2024-01-15T09:30:00.000000Z",
                "resolved_at": null
            }
        ],
        "sandbox_mode": false
    }
}

Example response (400, Невідповідність режимів):


{
    "success": false,
    "message": "Невідповідність режимів. Запит в production режимі, але замовлення створено в sandbox режимі",
    "error_code": "MODE_MISMATCH",
    "sandbox_mode": false
}

Example response (401, Невірний API ключ):


{
    "success": false,
    "message": "Невірний API ключ або аккаунт неактивний та не в тестовому режимі",
    "error_code": "INVALID_API_KEY"
}

Example response (403, Платіж не належить мерчанту):


{
    "success": false,
    "message": "Платіж не належить цьому мерчанту",
    "error_code": "ACCESS_DENIED",
    "sandbox_mode": false
}

Example response (404, Платіж не знайдений):


{
    "success": false,
    "message": "Платіж не знайдено",
    "error_code": "ORDER_NOT_FOUND",
    "sandbox_mode": false
}

Example response (500, Внутрішня помилка сервера):


{
    "success": false,
    "message": "Помилка при отриманні статусу платежу: Internal server error",
    "error_code": "INTERNAL_ERROR",
    "sandbox_mode": false
}

Received response:

Request failed with error:



Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

Request

GET api/v1/order/status

Headers

X-API-Key

Example: your-api-key-here

Content-Type

Example: application/json

Accept

Example: application/json

Query Parameters

payment_id string

ID платежу для отримання статусу. Example: 456

Body Parameters

payment_id string

Must not be greater than 191 characters. Example: qwajloqfeapbqtpr

Отримати доступні ліміти для створення платежу

requires authentication

Перевіряє можливість створення платежу та повертає доступні ліміти. Автоматично створює користувача, якщо він не існує.

Особливості

Автоматичне створення користувача: При першому запиті користувач буде створений автоматично
Перевірка лімітів: Система перевіряє чи може користувач створити новий платіж
Налаштування мерчанта: Повертає налаштування сум та банків для вашого мерчанта

Приклад використання (PHP)

$ch = curl_init();
curl_setopt_array($ch, [
    CURLOPT_URL => 'https://domain.com/api/v1/order-limits?partner_user_id=customer_123&amount=500',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['X-API-Key: YOUR_API_KEY']
]);

$response = curl_exec($ch);
$data = json_decode($response, true);

if ($data['success'] && $data['data']['can_create_payment']) {
    echo "Можна створити платіж на суму: " . $data['data']['limits']['max_amount'];
} else {
    echo "Помилки: " . implode(', ', $data['data']['errors']);
}

Example request:

curl --request GET \
    --get "https://api.p2p-market.net/api/v1/order-limits?partner_user_id=customer_123&amount=500" \
    --header "X-API-Key: your-api-key-here" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"amount\": 12,
    \"partner_user_id\": \"hsnedtmvxfzqiwhvofuqdrl\"
}"

const url = new URL(
    "https://api.p2p-market.net/api/v1/order-limits"
);

const params = {
    "partner_user_id": "customer_123",
    "amount": "500",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "X-API-Key": "your-api-key-here",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "amount": 12,
    "partner_user_id": "hsnedtmvxfzqiwhvofuqdrl"
};

fetch(url, {
    method: "GET",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$url = 'https://api.p2p-market.net/api/v1/order-limits';
$response = $client->get(
    $url,
    [
        'headers' => [
            'X-API-Key' => 'your-api-key-here',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'query' => [
            'partner_user_id' => 'customer_123',
            'amount' => '500',
        ],
        'json' => [
            'amount' => 12,
            'partner_user_id' => 'hsnedtmvxfzqiwhvofuqdrl',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, Успішна перевірка лімітів):


{
    "success": true,
    "data": {
        "merchant_id": 1,
        "merchant_name": "Тестовий мерчант",
        "can_create_payment": true,
        "partner_user_id": "customer_123",
        "limits": {
            "currency": "UAH",
            "min_amount": 50,
            "max_amount": 10000,
            "payment_step": 50,
            "available_amounts": [
                50,
                100,
                150,
                200,
                500,
                1000
            ],
            "allowed_banks": {
                "monobank": "Monobank",
                "privatbank": "PrivatBank",
                "abank": "A-Bank"
            }
        },
        "errors": []
    }
}

Example response (200, Платіж неможливий через обмеження):


{
    "success": true,
    "data": {
        "merchant_id": 1,
        "merchant_name": "Тестовий мерчант",
        "can_create_payment": false,
        "partner_user_id": "customer_123",
        "limits": null,
        "errors": [
            "У вас вже є активний платіж. Завершіть або скасуйте його для створення нового."
        ]
    }
}

Example response (401, Невірний API ключ):


{
    "success": false,
    "error": "Invalid API key or merchant is not active",
    "code": "INVALID_API_KEY"
}

Example response (422, Помилка валідації):


{
    "success": false,
    "errors": [
        "Поле partner_user_id є обов'язковим."
    ],
    "code": "VALIDATION_ERROR"
}

Received response:

Request failed with error:



Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

Request

GET api/v1/order-limits

Headers

X-API-Key

Example: your-api-key-here

Content-Type

Example: application/json

Accept

Example: application/json

Query Parameters

partner_user_id string

ID користувача від мерчанта (унікальний ідентифікатор вашого клієнта). Example: customer_123

amount number optional

Сума платежу для перевірки (опціонально). Example: 500

Body Parameters

amount number optional

Must be at least 0. Example: 12

partner_user_id string

Must not be greater than 255 characters. Example: hsnedtmvxfzqiwhvofuqdrl

Створити платіж

requires authentication

Створює новий платіж з автоматичним вибором карти для переказу. Автоматично створює або оновлює користувача з переданими даними.

Принцип роботи

Створення/оновлення користувача - Якщо користувач не існує, він буде створений з переданими метаданими
Валідація даних - Перевірка суми, банку та інших параметрів
Автоматичний вибір карти - Система автоматично вибирає найкращу карту для переказу
Створення замовлення - Формується замовлення з інструкціями для клієнта
Повернення даних - Отримуєте всю необхідну інформацію для показу клієнту

Приклад використання (PHP)

$data = [
    'amount' => 500,
    'bank' => 'monobank',
    'partner_user_id' => 'customer_123',
    'merchant_payment_id' => 'ORDER_' . time(),
    'description' => 'Оплата за товар',
    'metadata' => [
        'name' => 'Іван Петров',
        'email' => '[email protected]'
    ]
];

$ch = curl_init();
curl_setopt_array($ch, [
    CURLOPT_URL => 'https://domain.com/api/v1/order',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => json_encode($data),
    CURLOPT_HTTPHEADER => [
        'X-API-Key: YOUR_API_KEY',
        'Content-Type: application/json'
    ]
]);

$response = curl_exec($ch);
$result = json_decode($response, true);

if ($result['success']) {
    $paymentUrl = $result['data']['payment_url'];
    $redirectUrl = $result['data']['redirect_url'];
    $cardNumber = $result['data']['payout_details']['card_number'];

    echo "Платіж створено! Переведіть {$data['amount']} UAH на карту {$cardNumber}";
    echo "Інструкції: {$paymentUrl}";
    echo "Перенаправити користувача: {$redirectUrl}";
} else {
    echo "Помилка: " . implode(', ', $result['errors']);
}

Example request:

curl --request POST \
    "https://api.p2p-market.net/api/v1/order" \
    --header "X-API-Key: your-api-key-here" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"amount\": 500,
    \"bank\": \"monobank\",
    \"partner_user_id\": \"customer_123\",
    \"merchant_payment_id\": \"ORDER_123456\",
    \"description\": \"Оплата за замовлення #123456\",
    \"redirect_url\": \"http:\\/\\/www.barton.com\\/qui-est-illum-voluptas-officia-quidem-officia-qui.html\",
    \"metadata\": {
        \"name\": \"Іван Петров\",
        \"email\": \"[email protected]\",
        \"telegram_id\": \"123456789\"
    },
    \"webhook_url\": \"https:\\/\\/yoursite.com\\/webhook\"
}"

const url = new URL(
    "https://api.p2p-market.net/api/v1/order"
);

const headers = {
    "X-API-Key": "your-api-key-here",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "amount": 500,
    "bank": "monobank",
    "partner_user_id": "customer_123",
    "merchant_payment_id": "ORDER_123456",
    "description": "Оплата за замовлення #123456",
    "redirect_url": "http:\/\/www.barton.com\/qui-est-illum-voluptas-officia-quidem-officia-qui.html",
    "metadata": {
        "name": "Іван Петров",
        "email": "[email protected]",
        "telegram_id": "123456789"
    },
    "webhook_url": "https:\/\/yoursite.com\/webhook"
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$url = 'https://api.p2p-market.net/api/v1/order';
$response = $client->post(
    $url,
    [
        'headers' => [
            'X-API-Key' => 'your-api-key-here',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'json' => [
            'amount' => 500.0,
            'bank' => 'monobank',
            'partner_user_id' => 'customer_123',
            'merchant_payment_id' => 'ORDER_123456',
            'description' => 'Оплата за замовлення #123456',
            'redirect_url' => 'http://www.barton.com/qui-est-illum-voluptas-officia-quidem-officia-qui.html',
            'metadata' => [
                'name' => 'Іван Петров',
                'email' => '[email protected]',
                'telegram_id' => '123456789',
            ],
            'webhook_url' => 'https://yoursite.com/webhook',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (201, Успішне створення платежу):


{
    "success": true,
    "data": {
        "order_id": 12345,
        "merchant_payment_id": "ORDER_123456",
        "amount": 500,
        "currency": "UAH",
        "status": "pending",
        "merchant_id": 1,
        "partner_user_id": "customer_123",
        "payout_details": {
            "card_number": "5375 41** **** 1234",
            "card_holder": "ІВАН ПЕТРОВ",
            "bank_name": "Monobank"
        },
        "payment_url": "https://domain.com/deposit/instructions/12345",
        "redirect_url": "https://domain.com/deposit/instructions/12345?token=auth_token",
        "expires_at": "2024-01-15T15:30:00.000Z",
        "instructions": "Переведіть зазначену суму на карту та завантажте чек про оплату"
    }
}

Example response (401, Невірний API ключ):


{
    "success": false,
    "error": "Invalid API key or merchant is not active",
    "code": "INVALID_API_KEY"
}

Example response (422, Помилка валідації):


{
    "success": false,
    "errors": [
        "Поле amount є обов'язковим.",
        "Поле bank є обов'язковим."
    ],
    "code": "VALIDATION_ERROR"
}

Example response (422, Неправильний банк):


{
    "success": false,
    "errors": [
        "Вибраний банк не підтримується"
    ],
    "code": "INVALID_BANK"
}

Example response (503, Немає доступних карт):


{
    "success": false,
    "errors": [
        "Немає доступних карт для створення платежу"
    ],
    "code": "NO_AVAILABLE_CARDS"
}

Received response:

Request failed with error:



Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

Request

POST api/v1/order

Headers

X-API-Key

Example: your-api-key-here

Content-Type

Example: application/json

Accept

Example: application/json

Body Parameters

amount number

Сума платежу (від 50 до 10000 UAH). Example: 500

bank string

ID банку для переказу (monobank, privatbank, abank та ін.). Example: monobank

partner_user_id string

ID користувача від мерчанта (унікальний ідентифікатор вашого клієнта). Example: customer_123

merchant_payment_id string optional

Унікальний ID замовлення від мерчанта (якщо не вказати, згенерується автоматично). Example: ORDER_123456

description string optional

Опис платежу (відображається клієнту). Example: Оплата за замовлення #123456

redirect_url string optional

Must be a valid URL. Must not be greater than 255 characters. Example: http://www.barton.com/qui-est-illum-voluptas-officia-quidem-officia-qui.html

metadata object optional

Додаткові дані користувача для створення/оновлення профілю.

name string optional

Ім'я користувача. Example: Іван Петров

email string optional

Email користувача. Example: [email protected]

telegram_id string optional

Telegram ID користувача. Example: 123456789

webhook_url string optional

URL для отримання сповіщень про зміну статусу платежу. Example: https://yoursite.com/webhook

Introduction

Ласкаво просимо до API документації P2P Market!

🔑 Швидкий старт з X-API-Key

Приклади використання:

🚀 Як працює P2P Market

📋 Стандартна інтеграція

Крок 1: Створення виплати (Backend)

Крок 2: Поповнення через токен авторизації (Рекомендований підхід)

Крок 3: Webhook сповіщення

При створенні платежу (order.created)

При оплаті (order.paid)

При підтвердженні через 24 години (order.confirmed)

⚠️ Важливо: Логіка підтвердження платежів

🔧 Налаштування

1. Отримання API ключа

2. Налаштування webhook URLs

3. Налаштування лімітів платежів

4. Sandbox режим

💡 Рекомендації по інтеграції

✅ Найкращі практики

🔄 Типовий flow

🛡️ Безпека

📊 Основні можливості

🚀 Швидкий старт (5 хвилин)

Authenticating requests

Аутентифікація

Створення токену авторизації

Принцип роботи

Сценарії використання

Безпека

🔄 Переспрямування після авторизації

Request Try it out ⚡ Cancel 🛑 Send Request 💥

Headers

Body Parameters

Вебхуки

Інформація про вебхуки

Огляд вебхуків

Налаштування вебхуків

Безпека

Повторні спроби

Request Try it out ⚡ Cancel 🛑 Send Request 💥

Headers

Приклад вебхука платежу

Коли надсилається:

Заголовки:

Request Try it out ⚡ Cancel 🛑 Send Request 💥

Headers

Приклад вебхука виплати

Коли надсилається:

Заголовки:

Request Try it out ⚡ Cancel 🛑 Send Request 💥

Headers

Стандартний flow інтеграції

Рекомендований підхід інтеграції

Послідовність дій:

Етап 1: Підготовка виплати (Backend)

Етап 2: Поповнення користувачем (Frontend + P2P Market)

Етап 3: Оплата (P2P Market)

Етап 4: Завершення виплати (P2P Market)

Приклад timeline:

Request Try it out ⚡ Cancel 🛑 Send Request 💥

Headers

Перевірка підпису вебхука

Алгоритм перевірки:

Приклад коду (PHP):

Request Try it out ⚡ Cancel 🛑 Send Request 💥

Headers

Тестування вебхука

Що надсилається:

Request Try it out ⚡ Cancel 🛑 Send Request 💥

Headers

Body Parameters

Виплати

Отримання статусу виплати

Можливі статуси виплати

Додаткова інформація

Request Try it out ⚡ Cancel 🛑 Send Request 💥

Headers

Query Parameters

Body Parameters

Request

Request

Request

Request

Request

Request

Request

Request

Request

Request

Request

Request

Request