Многоязычные письма из вебхуков Stripe
Масштабирование SaaS на глобальный рынок таит в себе скрытые ловушки. Одну из них мы обнаружили в наших вебхуках Stripe.
Наша система отправляла подтверждения покупок, уведомления о продлении и сообщения об ошибках оплаты на японском языке англоязычным пользователям. Этот баг существовал месяцами, потому что не привлекал внимания.
Мы решили эту проблему, определяя язык по валюте.
Мы рассмотрели три варианта реализации:
- Вариант А: Хранить язык в базе данных. Это требует миграций и заполнения данных для существующих пользователей.
- Вариант Б: Запрашивать данные через Stripe API. Это создает дополнительные API-вызовы, к тому же многие клиенты не указывают предпочтительный локаль.
- Вариант В: Использовать валюту из полезной нагрузки (payload) вебхука. Это бесплатно, не требует изменений в базе данных и сразу работает для текущих пользователей.
Мы выбрали вариант В. Валюта — это фиксированный сигнал в момент покупки. Если пользователь платит в USD, он получает письмо на английском. Если в JPY — на японском.
Логика проста:
function lang_from_currency(string $currency): string {
$en_currencies = ['usd'];
return in_array(strtolower($currency), $en_currencies, true) ? 'en' : 'ja';
}
Это работает для всех четырех основных событий Stripe:
- checkout.session.completed
- invoice.payment_succeeded
- invoice.payment_failed
- customer.subscription.updated
Мы также обнаружили техническую ловушку в PHP.
Использование mb_language('Japanese') кодирует тему письма в ISO-2022-JP. Если вы отправите тему на английском с этой настройкой, Gmail и Outlook воспримут её как странную кодировку. Это повышает ваш спам-рейтинг.
Решение — переключать кодировку в зависимости от языка:
mb_language($lang === 'en' ? 'uni' : 'Japanese');
Использование 'uni' применяет UTF-8 Base64. Это помогает избежать попадания ваших писем в папку «Спам».
Три урока, извлеченных из этого исправления:
- Используйте полезную нагрузку события. Если данные уже есть в вебхуке, не трогайте базу данных. Это снижает риски и затраты на обслуживание.
- Следите за кодировкой. Если вы поддерживаете несколько языков, убедитесь, что кодировка темы письма соответствует контенту, чтобы не попасть под спам-фильтры.
- Проверяйте жестко заданные значения. При выходе на международный рынок проверьте, нет ли в ваших функциях уведомлений жестко заданных настроек языка.
Stateless-дизайн делает вашу систему проще в обслуживании и устойчивее к сбоям.