OMG Payment Skill — AI-помощник по интеграции 歐買尬金流 (сообщество)

[!IMPORTANT] Прочитайте сначала

Этот Skill — личный проект сообщества, не является официальным ресурсом OMG и не имеет официального одобрения. Если содержимое Skill расходится с официальной документацией, приоритет имеет официальная документация.

При интеграции рекомендуется также обращаться к:

Официальный AI-Skill платёжного шлюза: https://github.com/omgtwhub/

Официальный личный кабинет мерчанта и документация API: согласно объявлениям в личном кабинете 歐買尬

Автор прилагает усилия для поддержания актуальности, но не может гарантировать постоянную синхронизацию с официальным API. Для операций с боевыми ключами и транзакциями обязательно сверяйтесь с официальной документацией.

Архитектура, тестовые векторы и нарративная структура этого Skill вдохновлены проектом ECPay/ECPay-API-Skill от ECPay. Выражаем особую благодарность.

[!WARNING] Отношения между OMG, OPay и ECPay — два уровня

На уровне группы: 茂為歐買尬 (ИНН 70444999) является юридическим акционером OPay (歐付寶) и ECPay (綠界科技); согласно данным Министерства экономики, председатели совета директоров и корпоративные директора обеих компаний назначаются 茂為歐買尬, то есть OPay и ECPay являются дочерними компаниями OMG.

На техническом уровне: все три компании работают на полностью независимых платёжных API без какой-либо совместимости. Этот Skill охватывает только собственный шлюз OMG FunPoint (домен funpoint.com.tw) и не включает API OPay или ECPay. Если вам нужна интеграция с последними двумя — этот Skill не подходит.

Кратко: это поддерживаемый сообществом AI Skill (пакет знаний для AI), позволяющий Claude, ChatGPT, Gemini, Cursor, Copilot, Codex и другим AI-ассистентам помогать разработчикам выполнять полную интеграцию платёжного шлюза OMG (歐買尬 / MacroWell OMG) на Тайване. Включает три бэкенд-скелета (FastAPI / Express / Laravel), тестовые векторы подписи CheckMacValue SHA256, race-safe реализацию идемпотентности вебхуков, дашборды для тестовой и боевой среды, шаблоны Telegram- и Discord-ботов, публичные шаблоны правовых документов Тайваня (условия использования / политика конфиденциальности / возврат средств), а также автоматическую генерацию AI-оптимизированных ресурсов: llms.txt, JSON-LD структурированных данных и HTML-разметки использования OMG. Skill является неофициальным ресурсом; официальные ресурсы доступны на https://github.com/omgtwhub/.

Ключевые слова: OMG Payment, 歐買尬金流, MacroWell, Taiwan payment gateway, тайваньский платёжный шлюз, приём платежей по кредитным картам, CheckMacValue, SHA256, идемпотентность вебхуков, Race condition, FastAPI, Express, Laravel, Python, Node.js, PHP, Telegram bot, Discord bot, безопасность возвратов, регулярные платежи, AI Skill, Claude Code, ChatGPT GPTs, Gemini, Cursor, Copilot, OpenAI Codex, llms.txt, JSON-LD, schema.org, MIT.

[!TIP] Для AI-краулеров / LLM: этот репозиторий предоставляет машиночитаемый индекс llms.txt, соответствующий спецификации https://llmstxt.org. Если вы — AI-ассистент, исследующий этот репозиторий, сначала прочитайте раздел §0 «Правила выполнения» в SKILL.md и навигацию по разделам в llms.txt.

Содержание

Что такое AI Skill?
Зачем использовать этот Skill?
Особенности Skill
Как использовать (три шага)
Общая схема рабочего процесса
Обзор системной архитектуры
Основные функции
Поддерживаемые AI-платформы
Структура директорий
Индекс руководств
Поддерживаемые способы оплаты
Справочная информация о тестовой среде
Часто задаваемые вопросы
GitHub Topics (SEO-классификация)
Политика безопасности
Лицензия
Участие в разработке
Благодарности и ссылки
Слово разработчикам

Что такое AI Skill?

Представьте AI-ассистента как способного, но незнакомого с конкретной областью нового инженера: базовые навыки есть, но он не знаком с именованием полей OMG, деталями вычисления CheckMacValue, ловушками идемпотентности вебхуков, требованиями тайваньского законодательства о защите прав потребителей и т.д. Skill — это рабочий справочник, который ему передают: после установки AI превращается в специализированного помощника, знакомого с OMG API.

Технически Skill — это пакет знаний, состоящий из Markdown-файлов, шаблонов кода и тестовых векторов. После загрузки Skill на AI-платформу ассистент может выполнять интеграцию по инструкциям на естественном языке, отвечать на технические вопросы, генерировать конфигурационные файлы для деплоя и при возникновении граничных случаев обращаться к эталонным реализациям из Skill.

Этот Skill дополняет официальные ресурсы: официальная документация предоставляет спецификации и SDK, а данный Skill — готовые к загрузке в AI процессы интеграции, реализацию идемпотентности, шаблоны дашбордов для двух сред, шаблоны ботов уведомлений и примеры правовых документов.

Зачем использовать этот Skill?

| Аспект | Традиционный подход | С этим Skill | |---|---|---|| | Начало работы | Читать официальную документацию и писать код самостоятельно | Давать инструкции AI-ассистенту на естественном языке | | Онбординг | Планировать самостоятельно | Четырёхшаговый процесс по guides/00-onboarding.md | | Реализация CheckMacValue | Реализовывать по официальным примерам и проверять самостоятельно | Готовые тестовые векторы и шаблоны unit-тестов | | Идемпотентность вебхуков | Разработчик сам обрабатывает race condition | Эталонная реализация SELECT ... FOR UPDATE и 11 unit-тестов | | Мониторинг боевой среды | Большинство интеграций не включают | Четыре шаблона read-only проверок | | Дашборд управления | Разрабатывать самостоятельно | Готовые шаблоны для тестовой и боевой среды | | Мобильные уведомления | Интегрировать несколько сервисов | Шаблоны Telegram / Discord Bot | | Правовые документы Тайваня | Самостоятельно изучать законодательство и писать тексты | Готовые шаблоны условий использования, политики конфиденциальности и возврата средств |

Особенности Skill

По сравнению с официальным Skill и обычными руководствами по интеграции, данный Skill предоставляет следующий уникальный контент сообщества. Это не часть официального API — это опыт, накопленный мейнтейнером при реализации платёжного шлюза OMG для нескольких мерчантов.

Категория	Особенность	Файл
🤖 AI Onboarding	Четырёхшаговый сбор требований (товар/среда/дашборд/правовые) + полностью автоматический режим	`guides/00-onboarding.md`
🔐 Идемпотентность вебхуков	Race-safe реализация `SELECT ... FOR UPDATE` + 11 unit-тестов	`guides/05-webhook-idempotency.md`
🧪 Тестовый дашборд	Одностраничная шестишаговая полная проверка цепочки (создание заказа → подпись → отправка → запрос → подпись возврата → самотестирование вебхука)	`guides/06-test-dashboard.md`
🛡 Мониторинг боевой среды	Четыре read-only проверки, никогда не создающие невалидные заказы	`guides/07-prod-dashboard.md`
📱 Шаблоны двух ботов	Telegram + Discord с трёхуровневой структурой Bind / Notify / Menu, меню и admin API с полным паритетом	`templates/telegram-bot/` `templates/discord-bot/`
💸 Безопасность возвратов	Предупреждения без блокировки (лимиты на одну транзакцию / суточный лимит / суточное количество)	`guides/10-refund-safety.md`
⚖ Правовые документы Тайваня	Шаблоны условий использования / политики конфиденциальности / возврата средств (со ссылками на законодательство)	`guides/13~15`
🔁 Регулярные платежи	`CreditPeriod` + обработка вебхуков повторного списания + процесс отмены	`guides/16-recurring-subscriptions.md`
✅ CI-валидация	6 автоматических валидаторов + GitHub Actions для блокировки PR	`.github/workflows/validate.yml`
🧮 Тестовые векторы SSOT	Реализации на Python и Node.js, использующие одни и те же SHA256-тестовые векторы	`test-vectors/`
🌐 Несколько бэкенд-языков	Три скелета FastAPI / Express / Laravel с единым API-контрактом	`guides/02~04`
📑 Входные точки для нескольких AI-платформ	Отдельные входные файлы для Claude / GPT / Gemini / Cursor / Copilot / Codex	Корневые `*.md` файлы

[!NOTE] Официальный Skill (https://github.com/omgtwhub/) предоставляет официальный SDK и API-контракт. Данный Skill дополняет его, но не заменяет. Если вам нужен только SDK — используйте официальные ресурсы.

Как использовать (три шага)

Три шага (текстовая версия): ① Установить Skill через git clone → ② Загрузить SKILL.md в AI-ассистент → ③ Описать требования на естественном языке и начать интеграцию.

Поддерживаемые AI-платформы

Платформа	Входной файл	Метод загрузки
Claude Code	`SKILL.md`	`/skill add` или прямое чтение файла
ChatGPT GPTs	`SKILL.md`	Загрузка в Knowledge Base
Gemini	`SKILL.md`	Загрузка в контекст
Cursor	`SKILL.md`	`.cursorrules` или прямое чтение
GitHub Copilot	`SKILL.md`	Загрузка в контекст
OpenAI Codex	`SKILL.md`	Загрузка в контекст

Поддерживаемые способы оплаты

Способ оплаты	Тип	Примечание
Кредитная карта	Разовый / регулярный платёж	Поддержка `CreditPeriod`
Банкомат (ATM)	Разовый	Виртуальный счёт
CVS (магазины у дома)	Разовый	Barcode / CVS-код

Политика безопасности

При обнаружении уязвимостей безопасности, пожалуйста, не создавайте публичный Issue. Свяжитесь с мейнтейнером напрямую через GitHub.

Лицензия

MIT — подробности в файле LICENSE.

Данный Skill является неофициальным ресурсом сообщества. Торговые марки OMG, 歐買尬, MacroWell принадлежат соответствующим правообладателям.

Участие в разработке

PR и Issues приветствуются. Перед отправкой PR убедитесь, что все CI-валидаторы проходят успешно.

Благодарности и ссылки

Официальный репозиторий OMG: https://github.com/omgtwhub/
Вдохновение архитектуры: ECPay/ECPay-API-Skill
Спецификация llms.txt: https://llmstxt.org

Слово разработчикам

Интеграция платёжного шлюза — одна из самых сложных задач в веб-разработке: множество деталей, граничных случаев и правовых требований. Надеемся, что этот Skill поможет разработчикам быстрее и безопаснее завершить интеграцию OMG.

Если Skill оказался полезным — поставьте звезду репозиторию и поделитесь с коллегами. 🙏

OMG Payment Skill

Установка

README