Google Wallet API

Google Wallet API позволяет программно создавать, обновлять, получать списки и управлять картами Google Wallet. Он поддерживает те же операции, что и конструктор карт в Control Panel.

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

Базовый URL

https://apple-passkit.svc-nue.pushwoosh.com

Все эндпоинты обслуживаются по HTTPS. Запросы и ответы используют application/json, если не указано иное.

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

Каждый запрос должен включать заголовок Authorization с вашим токеном доступа к API Pushwoosh:

Authorization: Token <api-token>

Аккаунт, которому принадлежит токен, должен быть владельцем приложения, на которое ссылается applicationCode. Запрос для приложения, принадлежащего другому аккаунту, вернет 403 Forbidden.

Соглашения

Именование полей: Поля JSON используют lowerCamelCase (например, serialNumber, hexBackgroundColor, logoUrl).
Незаполненные поля: ответы включают все поля, даже если они пустые или имеют нулевое значение.
Идентификация: serialNumber всегда присваивается сервером при создании карты. Любое значение, которое вы отправляете при создании, игнорируется. Полный идентификатор объекта Google Wallet — {issuerId}.{serialNumber}.
Изображения: logoUrl и heroImageUrl — это публичные HTTPS URL-адреса изображений, которые загружает Google, а не загружаемые файлы.
Стиль карты: на карте должен быть установлен ровно один объект стиля (generic, offer, loyalty, eventTicket, giftCard, flight или transit). Стиль не может быть изменен после создания.

Ответы об ошибках

HTTP-статус	Значение
`400 Bad Request`	Неверный аргумент — обязательное поле отсутствует или имеет неверный формат.
`401 Unauthorized`	Отсутствует или недействителен заголовок `Authorization`.
`403 Forbidden`	Приложение не принадлежит аккаунту вызывающей стороны.
`404 Not Found`	Карта, шаблон или приложение не найдены.
`503 Service Unavailable`	Сервис перегружен или временно недоступен.

Эндпоинты

Метод	Путь	Описание
`POST`	`/api/google/pass/validate`	Проверить конфигурацию карты
`POST`	`/api/google/pass/create`	Создать новый объект карты и получить ссылку для сохранения
`POST`	`/api/google/pass/update/{serialNumber}`	Обновить существующую карту; Google доставит изменение
`GET`	`/api/google/pass/{applicationCode}/{serialNumber}/save-link`	Получить ссылку для сохранения “Добавить в Google Wallet”
`GET`	`/api/google/pass/{applicationCode}/{serialNumber}`	Получить одну карту
`GET`	`/api/google/passes`	Получить список всех карт для приложения
`POST`	`/api/google/pass/{applicationCode}/{serialNumber}/state`	Активировать или аннулировать карту
`DELETE`	`/api/google/pass/{applicationCode}/{serialNumber}`	Удалить карту
`GET`	`/api/google/config`	Получить конфигурацию Google Wallet для приложения
`GET`	`/api/google/templates`	Получить список доступных шаблонов карт
`GET`	`/api/google/templates/{filename}`	Получить один шаблон

Создать карту

Создает класс и объект карты в Google Wallet, затем возвращает присвоенный сервером серийный номер, полный идентификатор объекта и ссылку для сохранения “Добавить в Google Wallet”.

POST /api/google/pass/create

Тело запроса

Параметр	Тип	Обязательно	Описание
`pass`	object	Да	Объект карты, описывающий карту. Должен быть установлен ровно один стиль.
`userId`	string	Да	User ID Pushwoosh, которому выдана карта.
`applicationCode`	string	Да	Код приложения Pushwoosh.

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

{
  "applicationCode": "XXXXX-XXXXX",
  "userId": "user-123",
  "pass": {
    "hexBackgroundColor": "#3c414c",
    "logoUrl": "https://cdn.acme.com/logo.png",
    "loyalty": {
      "programName": "Acme Rewards",
      "accountName": "Jane Doe",
      "accountId": "1234567890",
      "pointsLabel": "Points",
      "pointsBalance": "1200",
      "rewardsTier": "Gold"
    },
    "barcode": {
      "format": "QR_CODE",
      "value": "1234567890"
    }
  }
}

Ответ

Поле	Тип	Описание
`serialNumber`	string	Уникальный идентификатор созданной карты, присвоенный сервером.
`objectId`	string	Полный идентификатор объекта Google Wallet: `{issuerId}.{serialNumber}`.
`saveLink`	string	Ссылка “Добавить в Google Wallet”: `https://pay.google.com/gp/v/save/{jwt}`.
`message`	string	Сообщение о результате.

Пример ответа

{
  "serialNumber": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
  "objectId": "XXXXXXXXXXXXXXX.XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
  "saveLink": "https://pay.google.com/gp/v/save/{jwt}",
  "message": "Pass created successfully"
}

Проверить карту

Проверяет конфигурацию карты на соответствие требованиям Google без ее создания. Полезно перед вызовом create.

POST /api/google/pass/validate

Тело запроса

Параметр	Тип	Обязательно	Описание
`pass`	object	Да	Объект карты для проверки.

Ответ

Поле	Тип	Описание
`valid`	boolean	Проходит ли карта проверку.
`errors`	array of strings	Блокирующие проблемы, которые необходимо исправить.
`warnings`	array of strings	Неблокирующие рекомендации.

Обновить карту

Обновляет объект карты новым содержимым. Затем Google доставляет обновленную версию на каждое устройство, сохранившее карту. Опционально отправляет уведомление на Android с обновлением.

POST /api/google/pass/update/{serialNumber}

Параметры пути

Параметр	Тип	Описание
`serialNumber`	string	Серийный номер, возвращенный при создании карты.

Тело запроса

Параметр	Тип	Обязательно	Описание
`updates`	object	Да	Объект карты с новым содержимым. Стиль не может быть изменен.
`applicationCode`	string	Да	Код приложения Pushwoosh.
`notifyMessage`	string	Нет	Если не пусто, отправляет push-уведомление на Android с этим текстом всем, кто сохранил карту. Пустое значение означает тихое обновление.
`notifyOnUpdate`	boolean	Нет	Запросить уведомление об обновлении поля. Уведомления отправляют только карты `loyalty`, `eventTicket` и `flight`; другие стили принимают флаг, но никогда не отправляют уведомление. Уведомления срабатывают только в течение 3 часов до соответствующего времени начала, и Google ограничивает их до 3 уведомлений на карту в сутки.

Ответ

Поле	Тип	Описание
`success`	boolean	Успешно ли прошло обновление.
`message`	string	Сообщение о результате.

Получить ссылку для сохранения

Возвращает ссылку для сохранения “Добавить в Google Wallet” для уже созданной карты. Объект карты должен уже существовать (создан через Создать карту).

GET /api/google/pass/{applicationCode}/{serialNumber}/save-link

Ответ

Поле	Тип	Описание
`saveLink`	string	`https://pay.google.com/gp/v/save/{jwt}`.

Получить карту

Возвращает одну сохраненную карту, включая ее полный объект карты.

GET /api/google/pass/{applicationCode}/{serialNumber}

Ответ

Возвращает { "pass": { ... } }, одну запись карты.

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

Возвращает постраничный, отсортированный список карт, хранящихся для приложения.

GET /api/google/passes?applicationCode=XXXXX-XXXXX&page=0&perPage=20

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

Параметр	Тип	Обязательно	Описание
`applicationCode`	string	Да	Код приложения Pushwoosh.
`orderBy`	string	Нет	Поле сортировки: `UPDATED` (по умолчанию) или `CREATED`.
`orderDirection`	string	Нет	Направление сортировки: `DESC` (по умолчанию, сначала новые) или `ASC`.
`page`	integer	Нет	Индекс страницы с нуля. По умолчанию `0`.
`perPage`	integer	Нет	Размер страницы. `0` или пропущенное значение использует значение по умолчанию сервера.

Ответ

Поле	Тип	Описание
`passes`	array of objects	Текущая страница записей карт.
`page`	integer	Возвращенный индекс страницы.
`perPage`	integer	Размер страницы, использованный для этого ответа.
`total`	integer	Общее количество карт для приложения на всех страницах.

Установить состояние карты

Активирует или аннулирует карту. Аннулированная (неактивная) карта перемещается в раздел Карты с истекшим сроком действия в Google Wallet; запись сохраняется, чтобы ее можно было повторно активировать.

POST /api/google/pass/{applicationCode}/{serialNumber}/state

Тело запроса

Параметр	Тип	Обязательно	Описание
`active`	boolean	Да	`true` устанавливает состояние карты `ACTIVE`; `false` аннулирует ее (`INACTIVE`).

Ответ

Возвращает пустой объект {} в случае успеха.

Удалить карту

Аннулирует карту в Google и удаляет ее сохраненную запись в Pushwoosh.

DELETE /api/google/pass/{applicationCode}/{serialNumber}

Ответ

Возвращает пустой объект {} в случае успеха.

Получить конфигурацию

Возвращает состояние конфигурации Google Wallet для приложения.

GET /api/google/config?applicationCode=XXXXX-XXXXX

Ответ

Поле	Тип	Описание
`hasServiceAccount`	boolean	Настроен ли ключ сервисного аккаунта.
`issuerId`	string	Настроенный Issuer ID из Google Pay & Wallet Console.
`serviceAccountEmail`	string	`client_email` настроенного сервисного аккаунта.

Шаблоны

Получить список доступных примеров шаблонов карт или загрузить один из них в виде объекта карты, который можно использовать в качестве отправной точки.

GET /api/google/templates — возвращает { "templates": [ { "filename", "name", "description", "style" } ] }.

GET /api/google/templates/{filename} — возвращает { "template": { ...объект карты... } }.

Справочник объектов

Объект карты (Pass object)

Поле	Тип	Описание
`serialNumber`	string	Присваивается сервером при создании; идентифицирует карту.
`generic` / `offer` / `loyalty` / `eventTicket` / `giftCard` / `flight` / `transit`	object	Стиль карты. Должен быть установлен ровно один. См. объекты стилей ниже.
`hexBackgroundColor`	string	Цвет фона карты, `#rrggbb`.
`logoUrl`	string	Публичный HTTPS URL изображения логотипа. Обязательно для карт лояльности и проездных.
`heroImageUrl`	string	Публичный HTTPS URL широкого баннерного изображения.
`barcode`	object	Объект штрих-кода, отображаемый на карте.
`textModules`	array	Текстовые модули, отображаемые в детальном представлении.
`links`	array	Модули ссылок, отображаемые в детальном представлении.
`expirationTime`	string	Время в формате ISO 8601, когда Google автоматически аннулирует карту. Пустое значение означает отсутствие срока действия.
`appLink`	object	Ссылка на приложение: кнопка CTA на лицевой стороне карты.
`locations`	array	Местоположения, которые вызывают уведомление с геозоной (максимум 10).
`holdersPolicy`	string	Кто может сохранить карту: `ONE_USER_ALL_DEVICES` (по умолчанию), `ONE_USER_ONE_DEVICE` или `MULTIPLE_HOLDERS`.

Объект Generic

Поле	Тип	Описание
`cardTitle`	string	Обязательно. Название эмитента/программы в верхней части карты.
`header`	string	Обязательно. Основной заголовок карты.
`subheader`	string	Второстепенный заголовок.
`cardFields`	array	До 6 текстовых модулей, закрепленных на лицевой стороне (до 3 рядов по 2).

Объект Offer

Поле	Тип	Описание
`title`	string	Обязательно. Например, `Скидка 20% на все`.
`provider`	string	Обязательно. Название продавца.
`details`	string	Детали предложения.
`finePrint`	string	Условия и положения.
`redemptionChannel`	string	`ONLINE`, `INSTORE`, `BOTH` (по умолчанию) или `TEMPORARY_PRICE_REDUCTION`.
`issuerName`	string	Отображается на поверхностях Google “выпущено”; по умолчанию `provider`.

Объект Loyalty

Поле	Тип	Описание
`programName`	string	Обязательно. Требует `logoUrl` на карте.
`accountName`	string	Имя участника, отображаемое на карте.
`accountId`	string	ID участника, отображаемый на карте.
`pointsLabel`	string	Например, `Баллы`. Отображается только с балансом.
`pointsBalance`	string	Баланс баллов.
`rewardsTier`	string	Например, `Золотой`.
`rewardsTierLabel`	string	Метка рядом с уровнем; по умолчанию `Уровень`.
`issuerName`	string	По умолчанию `programName`.

Объект Event ticket

Поле	Тип	Описание
`eventName`	string	Обязательно.
`venueName` / `venueAddress`	string	Детали места проведения.
`startDateTime` / `endDateTime`	string	ISO 8601 со смещением (например, `2026-07-01T19:30:00+02:00`).
`ticketHolderName` / `ticketNumber` / `ticketType`	string	Детали о владельце и билете.
`section` / `row` / `seat` / `gate`	string	Детали о месте.
`issuerName`	string	По умолчанию `eventName`.

Объект Gift card

Поле	Тип	Описание
`merchantName`	string	Обязательно.
`cardNumber`	string	Обязательно.
`pin`	string	PIN-код карты.
`balance`	string	Десятичная сумма, например `25.00`. Требует `balanceCurrency`.
`balanceCurrency`	string	Код валюты ISO 4217, например `USD`.
`issuerName`	string	По умолчанию `merchantName`.

Объект Flight

Поле	Тип	Описание
`carrierIataCode`	string	Обязательно. 2-буквенный код IATA, например `LX`.
`airlineName`	string	Отображаемое название авиакомпании.
`flightNumber`	string	Обязательно. Только цифры, например `113`.
`originAirportCode` / `destinationAirportCode`	string	Обязательно. 3-буквенные коды IATA.
`originTerminal` / `originGate` / `destinationTerminal`	string	Детали о терминале и выходе на посадку.
`departureDateTime`	string	Обязательно. Местное время аэропорта отправления, ISO 8601 без смещения (например, `2026-09-01T06:30:00`).
`boardingTime` / `arrivalDateTime`	string	Тот же локальный формат. `arrivalDateTime` — местное время в пункте назначения.
`passengerName`	string	Обязательно.
`confirmationCode` / `seatNumber` / `seatClass` / `boardingGroup`	string	Детали о пассажире.
`issuerName`	string	По умолчанию `airlineName`, затем код перевозчика.

Объект Transit

Поле	Тип	Описание
`transitType`	string	Обязательно. `BUS`, `RAIL`, `TRAM`, `FERRY` или `OTHER`.
`transitOperatorName`	string	Обязательно. Требует `logoUrl` на карте.
`passengerName`	string	Обязательно.
`ticketNumber`	string	Номер билета.
`tripType`	string	`ONE_WAY` (по умолчанию) или `ROUND_TRIP`.
`legs`	array	Один или несколько отрезков пути в порядке следования.
`issuerName`	string	По умолчанию `transitOperatorName`.

Объект отрезка пути (Transit leg object)

Поле	Тип	Описание
`originName` / `destinationName`	string	Обязательно.
`departureDateTime` / `arrivalDateTime`	string	ISO 8601; смещение опционально (местное время, если опущено).
`platform` / `coach` / `seat`	string	Детали о посадке.
`fareName`	string	Например, `Anytime Single`.

Объект штрих-кода (Barcode object)

Поле	Тип	Описание
`format`	string	`QR_CODE`, `PDF_417`, `AZTEC`, `CODE_128`, `EAN_13` и другие типы штрих-кодов Google Wallet.
`value`	string	Данные, закодированные в штрих-коде.
`altText`	string	Текст, отображаемый под штрих-кодом.

Объект текстового модуля (Text module object)

Поле	Тип	Описание
`id`	string	Идентификатор модуля.
`header`	string	Заголовок модуля.
`body`	string	Текст модуля.

Объект модуля ссылки (Link module object)

Поле	Тип	Описание
`uri`	string	URL внешней ссылки.
`description`	string	Метка ссылки, отображаемая в детальном представлении.

Объект ссылки на приложение (App link object)

Поле	Тип	Описание
`uri`	string	Веб-URL или URI цели диплинка.
`androidPackageName`	string	Опционально. Если установлено, открывает приложение Android.
`description`	string	Внутреннее описание целевого URI (не видимая метка кнопки); по умолчанию URI.

Объект местоположения (Location object)

Поле	Тип	Описание
`latitude`	number	от `-90.0` до `+90.0`.
`longitude`	number	от `-180.0` до `+180.0`.

Объект записи карты (Pass record object)

Возвращается эндпоинтами list/get.

Поле	Тип	Описание
`serialNumber`	string	Серийный номер карты.
`objectId`	string	Полный идентификатор объекта Google Wallet `{issuerId}.{serialNumber}`.
`cardTitle`	string	Отображаемый заголовок/название для карты.
`header`	string	Второстепенный отображаемый заголовок.
`userId`	string	User ID Pushwoosh, которому была выдана карта.
`createdAt` / `updatedAt`	string	Временные метки создания и последнего обновления.
`state`	string	`ACTIVE` или `INACTIVE`.
`style`	string	`generic`, `offer`, `loyalty`, `eventTicket`, `giftCard`, `flight` или `transit`.
`pass`	object	Полный объект карты для редактирования.