Интеграция по API

Введение

Ниже представлено описание того как работает API, с помощью которого вы сможете сделать интеграцию с вашим проектом.

1. Начало работы

1.1. Базовый URL и форматы

Все запросы выполняются по HTTPS к вашему экземпляру Payshark, например https://payshark.eu. Обмен данными ведётся в формате JSON.

1.2. Аутентификация и заголовки

Каждый запрос должен содержать обязательные заголовки:

  • Accept: application/json — сообщает серверу, что клиент ожидает JSON.
  • Access-Token: token — токен авторизации, доступный в админке (раздел «Интеграция»).

Контроль времени ожидания

Дополнительно можно указать заголовок X-Max-Wait-Ms, задающий максимальное время ожидания ответа в миллисекундах (минимум 1000 мс). При превышении тайм-аута сервер вернёт ответ 504 с сообщением «Не удалось обработать запрос вовремя. Повторите попытку позже.»

1.3. Структура ответов и обработка ошибок

Не является ошибкой. Означает что нету подходящих реквизитов для текущего запроса

{
  "message": "Подходящие платежные реквизиты не найдены.",
  "success": false
}

Успех HTTP 200

{
    "success": true, 
    "data": [ //тело ответа
        //...
    ]
}

Ошибка валидации запроса HTTP 422

{
    "message": "Общее описание ошибки",
    "errors": {
        "название параметра": [
            "Описание ошибки поля"
        ],
        //...
    }
}

Ошибки в бизнес логике HTTP 400

{
    "success": false,
    "message": "Описание ошибки"
}

Ошибка сервера HTTP 500

{
    "message": "Internal Server Error"
}

Базовые методы

Доступные валюты

GET /api/currencies

Ответ сервера

{
  "success": true,
  "data": [
    {
      "currency": "rub",
      "precision": 2,
      "symbol": "₽",
      "name": "Российский рубль"
    },
    {
      "currency": "kzt",
      "precision": 2,
      "symbol": "₸",
      "name": "Казахстанский тенге"
    },
    {
      "currency": "byn",
      "precision": 2,
      "symbol": "Br",
      "name": "Белорусский рубль"
    },
...
  ]
}

Доступные платежные методы

GET /api/payment-gateways

Ответ сервера

{
  "success": true,
  "data": [
    {
      "name": "Сбербанк",
      "code": "sberbank",
      "schema": "100000000111",
      "sub_methods": null,
      "currency": "rub",
      "min_limit": "1000",
      "max_limit": "500000",
      "reservation_time": 10,
      "detail_types": ["card", "account_number", "phone"],
      "order_service_commission_rate": 10,
      "payout_service_commission_rate": 1,
      "buy_price_markup_rate": 7,
      "sell_price_markup_rate": 3,
      "base_conversion_price": "76.57",
      "conversion_price": "81.93"
    },
    {
      "name": "Альфа-Банк",
      "code": "alfabank",
      "schema": "100000000008",
      "sub_methods": null,
      "currency": "rub",
      "min_limit": "1000",
      "max_limit": "500000",
      "reservation_time": 20,
      "detail_types": ["phone", "card"],
      "order_service_commission_rate": 10,
      "payout_service_commission_rate": 1.5,
      "buy_price_markup_rate": 7,
      "sell_price_markup_rate": 2.5,
      "base_conversion_price": "76.57",
      "conversion_price": "81.93"
    },
    {
      "name": "Райффайзенбанк",
      "code": "raiffeisenbank",
      "schema": "100000000007",
      "sub_methods": null,
      "currency": "rub",
      "min_limit": "1000",
      "max_limit": "100000",
      "reservation_time": 20,
      "detail_types": ["card", "phone"],
      "order_service_commission_rate": 10,
      "payout_service_commission_rate": 1.5,
      "buy_price_markup_rate": 7,
      "sell_price_markup_rate": 2.5,
      "base_conversion_price": "76.57",
      "conversion_price": "81.93"
    }
  ]
}

Описание API

  • В системе есть два вида API - Merchant API и H2H API
  • Merchant API - упрощенная версия api для более простой интеграции.
  • H2H API - версия api дающая полную возможность управления сделками, спорами. Выдает больше информации.
  • Важное замечание - для сделок созданных через H2H API не предоставляется платежная ссылка.

Мерчант API

Создать сделку

POST /api/merchant/order

Пример запроса

curl -X POST 'https://payshark.eu/api/merchant/order' \
  -H 'Accept: application/json' \
  -H 'Access-Token: {token}' \
  -d 'merchant_id=MERCHANT_UUID' \
  -d 'external_id=123' \
  -d 'amount=1000' \
  -d 'payment_gateway=sberbank' \
  -d 'payment_detail_type=card' \
  -d 'white_triangle=true' \***
  -d 'client_id=abc-123'***

Заголовки

  • X-Max-Wait-Ms: 30000 - (не обязательный) Этот заголовок указывает в миллисекундах, как долго вы готовы ждать выдачу сделки. 1000 = 1сек. Минимальный срок — это одна секунда. Если вы укажете этот параметр, то при высокой нагрузке когда система за указанное время не успеет выдать сделку, то она вернет ошибку, что не успела обработать запрос HTTP 504. Таким образом, вам не нужно будет ждать долгий зависший запрос, не нужно будет обрывать запрос, и мы не будем создавать псевдо-сделку, которую вы никогда не обработаете.
  • По умолчанию система ждет полминуты прежде чем вернуть ошибку ниже.
{
  "success": false,
  "message": "Не удалось обработать запрос вовремя. Повторите попытку позже."
}

Параметры запроса

  • external_id* - id сделки на стороне внешнего сервиса. Должен быть уникальным для мерчанта.
  • amount* - сумма сделки. (целое число)
  • payment_gateway - код платежного метода. Не обязательно если указан currency.
  • currency - код валюты. Не обязательно если указан payment_gateway.
  • payment_detail_type - тип реквизита с которым будет создана сделка card, phone, mobile_commerce, account_number, iban, qr_code, urllink.
    • mobile_commerce — реквизиты мобильной коммерции с номером телефона.
    • iban — реквизиты IBAN, состоящие из латинских букв и цифр (15–34 символа).
  • merchant_id* - uuid мерчанта. Можно найти на странице мерчанта в разделе настройки.
  • callback_url - POST ссылка на которую будет направлена информация об изменении статуса сделки.
  • success_url - GET ссылка на которую перенаправлен пользователь в случае успешной оплаты.
  • fail_url - GET ссылка на которую будет перенаправлен пользователь в случае если оплата не была произведена.
  • manually - если передано со значением "1", то клиенту будет дана возможность самому выбрать платежный метод.
  • white_triangle (boolean) - если true, реквизиты будут выданы из списка включенных для БТ.
  • min_check (boolean) - флаг, указывающий, нужно ли применять лимиты "Минимального чека". Обязателен только для сделок, которые должны пройти по этой функции: если true, сумма сделки должна соответствовать лимиту "Минимального чека"; если false или параметр не передан, система выдаст реквизиты без учета этой функции.
  • client_id - идентификатор клиента на стороне мерчанта. Может содержать цифры, буквы и символ "-". В ответе и колбеках поле возвращается только при наличии параметра в запросе.

Ответ сервера

{
        "success": true,
        "data": {
            "order_id": "4b3a163b...", // uuid сделки внутри системы.
            "external_id": "...", 
            "merchant_id": "...",
            "amount": "1000",
            "currency": "rub",
            "status": "pending", // статус сделки. success, fail, pending.
            "sub_status": "pending", //accepted, successfully_paid, successfully_paid_by_resolved_dispute, waiting_details_to_be_selected, waiting_for_payment, waiting_for_dispute_to_be_resolved, canceled_by_dispute, expired, cancelled
            "callback_url": null,
            "success_url": null,
            "fail_url": null, 
            "payment_gateway": "sberbank", // код платежного метода
            "payment_gateway_schema": "100000000111", // nspk code
            "payment_gateway_name": "Сбербанк", // название платежного метода
            "finished_at": null, // время закрытия сделки
            "expires_at": 1731375451, // время когда сделка будет автоматически закрыта.
            "created_at": 1731375391, // время создания сделки.
            "payment_link": "https://payshark.eu/payment/4b3a163b..." // ссылка на оплату.
        }
}

Получить сделку

GET /api/merchant/order/{order_id}

  • Содержит тоже самое, что объект при создании сделки.
  • Альтернатива: /api/merchant/order/{merchant_id}/{external_id}

Пример запроса

curl -X GET 'https://payshark.eu/api/merchant/order/{order_id}' \
  -H 'Accept: application/json' \
  -H 'Access-Token: {token}'

Создать payment page для individual_qr

POST /api/merchant/order/individual-qr/payment-page

Пример запроса

curl -X POST 'https://payshark.eu/api/merchant/order/individual-qr/payment-page' \
  -H 'Accept: application/json' \
  -H 'Access-Token: {token}' \
  -d 'merchant_id=MERCHANT_UUID' \
  -d 'payment_gateway=sberbank_rub' \
  -d 'callback_url=https://merchant.example/callback' \
  -d 'success_url=https://merchant.example/success' \
  -d 'fail_url=https://merchant.example/fail' \
 -d 'payment_gateway=уточните у поддержки' \
   -d 'currency=rub'

Параметры запроса

  • merchant_id* — uuid мерчанта.
  • payment_gateway* — код платежного метода, в рамках которого должна быть создана сделка после ввода суммы на payment page.
  • callback_url — POST ссылка для уведомления об изменении статуса сделки.
  • success_url — GET ссылка для редиректа после успешной оплаты.
  • fail_url — GET ссылка для редиректа, если оплата не была произведена.

Ответ сервера

{
    "success": true,
    "data": {
        "payment_page_url": "https://payshark.eu/payment/individual-qr/6f6c8d8e-...",
        "expires_in": 1800
    }
}

Пояснения к ответу

  • payment_page_url — ссылка на страницу процессинга, где клиент введет сумму и увидит QR.
  • expires_in — TTL ссылки в секундах. Сейчас ссылка живет 30 минут.

Загрузить чек по сделке в обработке

POST /api/merchant/order/{order_id}/processing-receipt

  • Доступно только для сделок Merchant API в статусе pending.
  • Чек хранится отдельно от файлов, которые мерчант прикладывает в спорах. Флаг processing_receipt_uploaded возвращается только в ответе на этот запрос.

Параметры запроса

  • processing_receipt* — base64-строка с файлом чека. Допустимые форматы: jpg, jpeg, png, pdf. Максимальный размер исходного файла — 5 МБ.

Пример запроса

curl -X POST 'https://payshark.eu/api/merchant/order/{order_id}/processing-receipt' \
  -H 'Accept: application/json' \
  -H 'Access-Token: {token}' \
  -d 'processing_receipt=BASE64_DATA'

Ответ сервера

{
    "success": true,
    "data": {
        "order_id": "4b3a163b...",
        "external_id": "...",
        "merchant_id": "...",
        "amount": "1000",
        "currency": "rub",
        "status": "pending",
        "sub_status": "pending",
        "callback_url": null,
        "success_url": null,
        "fail_url": null,
        "client_id": null,
        "payment_gateway": "sberbank",
        "payment_gateway_schema": "100000000111",
        "payment_gateway_name": "Сбербанк",
        "payment_detail": null,
        "processing_receipt_uploaded": true,
        "finished_at": null,
        "expires_at": 1731375451,
        "created_at": 1731375391,
        "payment_link": "https://payshark.eu/payment/4b3a163b..."
    }
}

Получить курс конвертации

GET /api/merchant/rate/{merchant_id}

Параметры запроса

  • currency* - код валюты (например rub)

Ответ сервера

{
    "success": true,
    "data": {
        "rate": "110.07"
    }
}

Получить свободные лимиты

GET /api/merchant/free-limits

Ответ сервера

{
    "success": true,
    "data": {
        "limits": [
            {
                "code": "rub",
                "name": "Российский рубль",
                "symbol": "₽",
                "total_free_limit": "1000.00"
            }
        ],
        "min_amount_stats": {
            "rub": {
                "no_limit": {
                    "title": "Не указан",
                    "count": 47,
                    "free_limit": "18390157.00",
                    "potential_limit": "18390157.00"
                },
                "1k": {
                    "title": "От 1,000",
                    "count": 5,
                    "free_limit": "450000.00",
                    "potential_limit": "450000.00"
                }
            }
        }
    }
}

GET /api/merchant/payout-free-limits

Ответ сервера

{
    "success": true,
    "data": {
        "limits": [
            {
                "code": "rub",
                "name": "Российский рубль",
                "symbol": "₽",
                "total_free_limit": "101 436.00",
                "max_trader_limit_left": "67 624.00",
                "total_potential_limit": "103 812.00"
            }
        ]
    }
}

H2H API

Создать сделку

POST /api/h2h/order

Пример запроса

curl -X POST 'https://payshark.eu/api/h2h/order' \
  -H 'Accept: application/json' \
  -H 'Access-Token: {token}' \
  -d 'merchant_id=MERCHANT_UUID' \
  -d 'external_id=123' \
  -d 'amount=1000' \
  -d 'payment_gateway=sberbank' \
  -d 'payment_detail_type=card' \
  -d 'white_triangle=true' \***
  -d 'client_id=abc-123'***

Заголовки

  • X-Max-Wait-Ms: 30000 - (не обязательный) Этот заголовок указывает в миллисекундах, как долго вы готовы ждать выдачу сделки. 1000 = 1сек. Минимальный срок — это одна секунда. Если вы укажете этот параметр, то при высокой нагрузке когда система за указанное время не успеет выдать сделку, то она вернет ошибку, что не успела обработать запрос HTTP 504. Таким образом, вам не нужно будет ждать долгий зависший запрос, не нужно будет обрывать запрос, и мы не будем создавать псевдо-сделку, которую вы никогда не обработаете.
  • По умолчанию система ждет полминуты прежде чем вернуть ошибку ниже.
{
  "success": false,
  "message": "Не удалось обработать запрос вовремя. Повторите попытку позже."
}

Описание параметров запроса

  • external_id* - id сделки на стороне внешнего сервиса. Должен быть уникальным для мерчанта.
  • amount* - сумма сделки. (целое число)
  • payment_gateway - код платежного метода. Не обязательно если указан currency.
  • currency - код валюты. Не обязательно если указан payment_gateway.
  • payment_detail_type - тип реквизита с которым будет создана сделка card, phone, mobile_commerce, account_number, iban, qr_code, urllink.
  • merchant_id* - uuid мерчанта. Можно найти на странице мерчанта в разделе настройки.
  • callback_url - POST ссылка на которую будет направлена информация об изменении статуса сделки.
  • white_triangle (boolean) - если true, реквизиты будут выданы из списка включенных для БТ.
  • min_check (boolean) - флаг, указывающий, нужно ли применять лимиты "Минимального чека". Обязателен только для сделок, которые должны пройти по этой функции: если true, сумма сделки должна соответствовать лимиту "Минимального чека"; если false или параметр не передан, система выдаст реквизиты без учета этой функции.
  • client_id - идентификатор клиента на стороне мерчанта. Может содержать цифры, буквы и символ "-". В ответе и колбеках поле возвращается только при наличии параметра в запросе.

Ответ сервера

{
  "data": {
    "amount": "1519",
    "method": null,
    "profit": "19.52",
    "status": "pending",
    "currency": "rub",
    "merchant": {
      "name": "tes",
      "description": "tes"
    },
    "order_id": "b9ec0ab7-9cc4-4bd7-903c-e6224fe451c5",
    "created_at": 1764864315,
    "expires_at": 1764864915,
    "sub_status": "waiting_for_payment",
    "base_amount": "1519",
    "external_id": "39655218111122222222234567890",
    "finished_at": null,
    "merchant_id": "73d848b7-e217-4a59-a659-faa5bc1c9c9e",
    "method_name": null,
    "callback_url": "https://tes/tessite",
    "method_schema": null,
    "payment_detail": {
      "detail": "79800000334",
      "qr_link": null,
      "initials": "23543254",
      "bt_enabled": false,
      "detail_type": "phone",
      "min_check_enabled": false
    },
    "service_profit": "0",
    "merchant_profit": "17.57",
    "payment_gateway": "sberbank",
    "profit_currency": "usdt",
    "conversion_price": "77.83",
    "is_min_check_deal": false,
    "current_server_time": 1764864315,
    "payment_gateway_name": "Сбербанк",
    "base_conversion_price": "0",
    "payment_gateway_schema": "100000000111",
    "trader_commission_rate": "0",
    "conversion_price_currency": "rub",
    "service_commission_rate_total": "0",
    "service_commission_rate_client": "0",
    "service_commission_rate_merchant": "0"
  },
  "success": true
}
}

Получить сделку

GET /api/h2h/order/{order_id}

  • Возвращает такой же объект как при создании сделки.
  • Альтернатива: /api/h2h/order/{merchant_id}/{external_id}

Пример запроса

curl -X GET 'https://payshark.eu/api/h2h/order/{order_id}' \
  -H 'Accept: application/json' \
  -H 'Access-Token: {token}'

Загрузить чек по сделке в обработке

POST /api/h2h/order/{order_id}/processing-receipt

  • Доступно только для сделок H2H API в статусе pending.
  • Чек хранится отдельно от файлов споров. Флаг processing_receipt_uploaded возвращается только в ответе на этот запрос.

Параметры запроса

  • processing_receipt* — base64-строка с файлом чека. Допустимые форматы: jpg, jpeg, png, pdf. Максимальный размер исходного файла — 5 МБ.

Пример запроса

curl -X POST 'https://payshark.eu/api/h2h/order/{order_id}/processing-receipt' \
  -H 'Accept: application/json' \
  -H 'Access-Token: {token}' \
  -d 'processing_receipt=BASE64_DATA'

Ответ сервера

{
    "success": true,
    "data": {
        "order_id": "3db07a16...",
        "external_id": "...",
        "merchant_id": "3db07a16...",
        "base_amount": "1000",
        "amount": "1040",
        "currency": "rub",
        "status": "pending",
        "sub_status": "pending",
        "payment_gateway": "sberbank",
        "payment_gateway_schema": "100000000111",
        "payment_gateway_name": "Сбербанк",
        "processing_receipt_uploaded": true,
        "payment_detail": {
            "detail": "1000200030004000",
            "qr_link": "https://...",
            "detail_type": "card",
            "initials": "Пол Атрейдес"
        },
        "merchant": {
            "name": "...",
            "description": "..."
        },
        "finished_at": null,
        "expires_at": 1731375451,
        "created_at": 1731375391,
        "current_server_time": 1731655862
    }
}

Закрыть сделку

PATCH /api/h2h/order/{order_id}/cancel

  • Досрочно закрывает сделку если она находится в статусе pending и не имеет открытых споров.

Пример запроса

curl -X PATCH 'https://payshark.eu/api/h2h/order/{order_id}/cancel' \
  -H 'Accept: application/json' \
  -H 'Access-Token: {token}'

Открыть спор

POST /api/h2h/order/{order_id}/dispute

  • Если сделка все еще открыта, то она будет закрыта перед открытием спора, так если бы вы вызвали предыдущий метод выше.

Пример запроса

curl -X POST 'https://payshark.eu/api/h2h/order/{order_id}/dispute' \
  -H 'Accept: application/json' \
  -H 'Access-Token: {token}' \
  -d 'receipt=BASE64_DATA'

Описание параметров запроса

  • receipt* - изображение jpeg,jpg,png,pdf преобразованное в base64. Размер файла до 5МБ.

Ответ сервера

{
        "success": true,
        "data": {
            "order_id": "3db07a16...",
            "status": "pending",
            "cancel_reason": null // причина отказа
        }
}

Получить спор

GET /api/h2h/order/{order_id}/dispute

  • Ответ такой же как при открытии спора.

Пример запроса

curl -X GET 'https://payshark.eu/api/h2h/order/{order_id}/dispute' \
  -H 'Accept: application/json' \
  -H 'Access-Token: {token}'

Вывод с баланса

Получить доступный баланс

GET /api/wallet/balance

Ответ сервера

{
    "success": true,
    "data": {
        "balance": "10000.00"
    }
}

Создать запрос на вывод

POST /api/wallet/withdraw

Мерчант отправляет заявку на вывод, после чего она попадает в админку на ручную обработку (Admin Pro / Super Admin).

Описание параметров запроса

  • merchant_id* - UUID мерчанта.
  • amount* - сумма вывода (целое число).
  • address* - адрес вывода.
  • network* - сеть USDT: bsc, arb, trx.

Адрес вывода обязательно должен быть добавлен в белый список адресов мерчанта, иначе API вернет ошибку.

Пример запроса

curl -X POST 'https://payshark.eu/api/wallet/withdraw' \
  -H 'Accept: application/json' \
  -H 'Access-Token: {token}' \
  -H 'Content-Type: application/json' \
  -d '{
    "merchant_id": "{merchant_uuid}",
    "amount": 1000,
    "address": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE",
    "network": "trx"
  }'

Ответ сервера

{
    "success": true,
    "data": {
        "invoice_id": 123,
        "status": "pending"
    }
}

Пример ошибки (адрес не в белом списке)

{
    "success": false,
    "message": "Адрес не находится в белом списке. Обратитесь к администратору для добавления вашего адреса в белый список."
}

Описание статусов сделок

Status

Значение Описание
success Операция успешно завершена.
pending Операция находится в ожидании обработки.
fail Операция завершилась неудачно.

Sub Status

Значение Описание
accepted Закрыт вручную.
successfully_paid Закрыт автоматически.
successfully_paid_by_resolved_dispute Закрыт в результате принятого спора.
waiting_details_to_be_selected Ждет выбора реквизитов.
waiting_for_payment Ждет платежа.
waiting_for_dispute_to_be_resolved Ждет решения спора.
canceled_by_dispute Отменен в результате спора.
expired Отменен по истечению времени.
cancelled Отменен вручную.

Общее дополнение к описанию API

  • Не для всех вариантов параметров может быть доступный реквизит. Поэтому сервер вернет сообщение, что реквизит не найден.
  • Параметр payment_gateway - создаст сделку только для этого платежного метода. В то время как параметр currency создаст сделку в рамках это валюты, но для любого платежного метода.
  • Параметры payment_gateway и currency взаимоисключающие и не могут быть использованы одновременно.
  • Если сумма сделки выходит за лимиты указанного платежного метода или всех доступных методов указанных в /api/payment-gateways то сервер вернет ошибку что подходящий платежный метод не найден.
  • Параметр callback_url также есть в настройках мерчанта, но если параметр передать в запросе к API, то он будет старше. Т.е. уведомление будет отправлено по url указанного в запросе, но не в админке.
  • Параметр payment_detail_type нужно использовать аккуратно. И чаще всего в связке с параметров currency. Так как не для всех платежных методов если реквизиты всех типов.
  • Если платежный метод поддерживает только реквизиты mobile_commerce или вы хотите получить именно такие реквизиты, указывайте в запросе payment_detail_type=mobile_commerce. При его отсутствии мобильная коммерция будет пропущена, но другие подходящие реквизиты продолжат выдаваться.
  • Cумма сделки может изменить после ее создания. Вернется в параметре amount. Так как существует наценка в виде комиссии клиента. Указывается в настройках мерчанта. Например при комиссии клиента в 4%, сумма 1000 будет изменена на 1040.
  • Сделкой можно управлять только через соответствующий API

Уведомление об изменении статуса платежа

  • По ссылке указанной в настройках мерчанта, или переданной в параметре callback_url при создании сделки, будет отправлено уведомление (POST запрос) если сделка изменит свой статус.
  • Уведомление содержит данные соответствующие данным которы возвращает метод GET /api/h2h/order/{order_id} или GET /api/merchant/order/{order_id} в зависимости от используемого API. Ниже пример для H2H API.

API для выплат

  • Доступ нужно запросить у администратора.

Методы

Получить список предложений на выплату

GET /api/payout/offers

Пример запроса

curl -X GET 'https://payshark.eu/api/payout/offers' \
  -H 'Accept: application/json' \
  -H 'Access-Token: {token}'

Ответ сервера

{
    "success": true,
    "data": {
        "rub": {
            "sberbank_rub": {
                "max_amount": 100000,
                "min_amount": 1000,
                "currency": "rub",
                "detail_type": "card",
                "payment_gateway": {
                    "name": "Сбербанк",
                    "name_with_currency": "Сбербанк rub",
                    "code": "sberbank_rub",
                },
                "offers_count": 1,
                "recommended_max_amount": 100000,
                "recommended_min_amount": 1000
            },
            //...
        },
        //...
    }
}

Создать выплату

POST /api/payout

Пример запроса

curl -X POST 'https://payshark.eu/api/payout' \
  -H 'Accept: application/json' \
  -H 'Access-Token: {token}' \
  -d 'merchant_id=MERCHANT_UUID' \
  -d 'external_id=123' \
  -d 'detail=2200200020002000' \
  -d 'detail_type=card' \
  -d 'detail_initials=Иван Иванов' \
  -d 'amount=1000' \
  -d 'currency=rub'

Описание параметров запроса

  • merchant_id - uuid мерчанта, находится в админке.
  • external_id - id сделки на стороне внешнего сервиса. Должен быть уникальным для данного мерчанта.
  • detail - реквизиты на которые будут отправлены средства.
  • detail_type - тип реквизитов.
  • detail_initials - держатель реквизитов.
  • amount - сумма выплаты (в выбранной валюте).
  • currency - валюта выплаты.
  • bank - название банка получателя. Может быть любым текстом и обязателен, если detail_type=phone.
  • callback_url - ссылка на которую будет направлена информация об изменении статуса выплаты. обязательный параметр .

Ответ сервера

{
    "success": true,
    "data": {
        "uuid": "...",
        "external_id": "...",
        "detail": "1000200030004000",
        "detail_type": "card",
        "detail_initials": "Петр К.",
        "payout_amount": "1000",
        "currency": "rub", 
        "base_liquidity_amount": "9.31",
        "liquidity_amount": "10.14",
        "liquidity_amount_in_payout_currency": "1090.14",
        "liquidity_currency": "usdt",
        "service_commission_rate": 9,
        "service_commission_amount": "0.83",
        "base_exchange_price": "110.07",
        "exchange_price": "107.32",
        "receipt_url": null,
        "image_receipt_url": null,
        "status": "pending",
        "sub_status": "processing_by_trader",
        "callback_url": "https://payshark.eu/callback",
        "bank": null,
        "merchant": {
            "name": "мерчант 1"
        },
        "finished_at": null,
        "expires_at": 1736145380,
        "created_at": 1736144380
    }
}

Создать выплату в пул

POST /api/payout/pool

Эндпоинт создаёт выплату без привязки к конкретному предложению трейдера. Заявка размещается в пуле и доступна всем трейдерам.

Дополнительный параметр запроса

  • waiting_time – время ожидания в минутах, в течение которого выплата будет находиться в пуле. По истечении таймера она автоматически отменится.
  • Важно – waiting_time не является временем обработки выплаты, данным параметром мерчант задает время нахождения выплаты в пуле. Время обработки выплаты трейдером задается администратором по условиям мерчанта. Особенности ответа

Помимо стандартных полей, ответ содержит:

{
    "success": true,
    "data": {
        "is_pool": true,
        "pool_waiting_minutes": 30,
        "pool_waiting_until": 1736145380,
        "pool_taken_at": null,
        "sub_status": "waiting_for_trader"
    }
}

Поле pool_waiting_until возвращается в формате unix timestamp и показывает, до какого момента заявка будет доступна в пуле.

Последовательность колбеков статуса по выплатам

При изменении статуса выплаты система отправляет уведомления на указанный callback_url. Ниже перечислены возможные последовательные значения полей status и sub_status в рамках жизненного цикла одной выплаты:

  1. В ожидании трейдера — выплата создана и ожидает, пока трейдер возьмёт её в работу.
    {
    "status": "pending",
    "sub_status": "waiting_for_trader"
}
  2. Трейдер принял выплату в обработку — трейдер начал работать по заявке.
    {
    "status": "pending",
    "sub_status": "processing_by_trader"
}
  3. Трейдер обработал выплату (не конечная точка) — выплата передана администратору для проверки.
    {
    "status": "pending",
    "sub_status": "processing_by_administrator"
}
  4. Администратор подтвердил выплату как успешно выполненную (конечная точка) — обработка завершена.
    {
    "status": "success",
    "sub_status": "fully_completed"
}

    "Важно" Повторное уведомление со статусом processing_by_administrator — выплата была передана другому трейдеру и вновь находится на проверке администратора.

    {
    "status": "pending",
    "sub_status": "processing_by_administrator"
}

Получение повторного уведомления с processing_by_administrator означает, что выплата была передана другому трейдеру и в настоящее время ожидает подтверждения администратора.

Получить выплату

GET /api/payout/{uuid}

Пример запроса

curl -X GET 'https://payshark.eu/api/payout/{uuid}' \
  -H 'Accept: application/json' \
  -H 'Access-Token: {token}'
  • Альтернатива: /api/payout/{merchant_id}/{external_id}
  • Ответ такой же, как при создании выплаты.

Если указан неверный uuid, вернётся ошибка:

{
    "success": false,
    "message": "Указан неверный uuid"
}

Открыть спор по выплате

POST /api/payout/{uuid}/dispute

  • Альтернатива: /api/payout/{merchant_id}/{external_id}/dispute
  • Позволяет инициировать спор по завершённой выплате. Если выплата не имеет статуса success, вернётся ошибка.

Пример запроса

curl -X POST 'https://payshark.eu/api/payout/{uuid}/dispute' \
  -H 'Accept: application/json' \
  -H 'Access-Token: {token}'

Ответ сервера

{
    "success": true,
    "data": {
        "payout_id": "3db07a16...",
        "status": "pending",
        "reason": null,
        "sub_status": "dispute"
    }
}

Получить спор по выплате

GET /api/payout/{uuid}/dispute

  • Альтернатива: /api/payout/{merchant_id}/{external_id}/dispute
  • Ответ такой же как при открытии спора.

Пример запроса

curl -X GET 'https://payshark.eu/api/payout/{uuid}/dispute' \
  -H 'Accept: application/json' \
  -H 'Access-Token: {token}'

Описание статусов выплат

Status

Значение Описание
success Выплата успешно завершена.
pending Выплата находится в ожидании обработки.
fail Выплата отменена.

Sub Status

Значение Описание
processing_by_trader Обрабатывается трейдером.
processing_by_administrator На проверке администратора.
dispute Спор.
dispute_closed Спор закрыт.
fully_completed Завершена.
canceled_by_timeout Отменена по времени.
waiting_for_trader Заявка ожидает, когда трейдер возьмёт её из пула.
expired Просрочена.

Merchant Payment Widget - СКОРО

Demo-страница: https://payshark.eu/widgets/demo.html (Только для ознакомления).

JS-виджет для запуска оплаты на стороне мерчанта.

Подключение

<script src="https://payshark.eu/widgets/payshark-widget.js"></script>

Инициализация

<script>
  const widget = window.PaysharkWidget.init({
    apiBaseUrl: 'https://payshark.eu',
    merchantId: 'MERCHANT_UUID',
    accessToken: 'ACCESS_TOKEN',

    // modal | embed | redirect
    mode: 'modal',

    // required for embed mode
    container: '#payment-widget',

    pollIntervalMs: 3000,
    enableGatewayPicker: true,

    onOrderCreated: (order) => console.log('order-created', order),
    onStatus: (order) => console.log('status', order.status),
    onSuccess: (order) => console.log('success', order),
    onFail: (order) => console.log('fail', order),
    onError: (error) => console.error('widget-error', error),
  });

  async function pay() {
    await widget.open({
      external_id: 'ORDER-100500',
      amount: 1000,
      payment_gateway: 'sberbank',
      payment_detail_type: 'card',
      callback_url: 'https://merchant.site/api/payment/callback',
      success_url: 'https://merchant.site/payment/success',
      fail_url: 'https://merchant.site/payment/fail'
    });
  }
</script>

Режимы

  • modal — откроет ссылку оплаты во всплывающем окне.
  • embed — встроит оплату в контейнер (container).
  • redirect — сразу отправит пользователя на payment_link.

События

  • onOrderCreated(order) — сделка создана.
  • onOpened(payload) — виджет открыт.
  • onClosed(payload) — виджет закрыт.
  • onStatus(order) — обновление статуса сделки.
  • onSuccess(order) — статус success.
  • onFail(order) — статус fail.
  • onStatusTimeout(payload) — вышло время ожидания статуса.
  • onError(error) — ошибка виджета.
  • onEvent(name, payload) — универсальный обработчик.

Важно

  • Виджет использует Merchant API (/api/merchant/order) и требует Access-Token.
  • Платежная страница берется из payment_link в ответе на создание сделки.
  • Строго использовать уникальный external_id для каждой попытки создания сделки.

Для виджета

GET /api/merchant/widget/options?merchant_id=MERCHANT_UUID

Возвращает список доступных банков/шлюзов (с учетом настроек мерчанта), лимиты и доступные способы оплаты.