Стандарты протокола, стандарты протокола

API соответствует набору стандартов HTTP API и поддерживает идемпотентность , что обеспечивает более надежную интеграцию.

URL-адреса, размещенные в Google

В документации для каждого метода, размещенного в Google, указан базовый URL-адрес, который включает имя метода и основной номер версии. Полный URL-адрес создается путем добавления в конец идентификатора учетной записи Payment Integrator вызывающего абонента. Например, в документации по методу echo, размещенному в Google, указан URL-адрес:

https://vgw.googleapis.com/secure-serving/gsp/v1/echo

Если идентификатор учетной записи Payment Integrator вызывающего абонента — INTEGRATOR_1 , он должен добавить его в конец URL-адреса, чтобы сформировать:

https://vgw.googleapis.com/secure-serving/gsp/v1/echo/INTEGRATOR_1

Примечание. На странице документации конечной точки для конкретного метода, который вы реализуете, будет указан наиболее точный URL-адрес для вашего случая.

URL-адреса, размещенные партнерами

В документации для каждого метода API, размещенного у партнера, указан базовый URL-адрес, который включает имя метода и основной номер версии. Не следует включать идентификатор учетной записи платежного интегратора ( PIAID ) в размещаемые вами URL-адреса.

Песочница и производственная среда

Google размещает API стандартных платежей как в песочнице (для целей разработки и тестирования), так и в рабочей среде. Запросы в тестовой среде Google не влекут за собой никаких реальных финансовых обязательств. Песочница и производственная среда полностью разделены и не используют общие ключи или информацию о транзакциях.

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

Базовый путь песочницы Google

https://vgw. sandbox.google .com/secure-serving/gsp/

Примечание. Если ваша интеграция уже запущена и вызывает хост https://billpaynotification.sandbox.googleapis.com , вы можете продолжать это делать. Новые интеграции должны вызывать хост vgw.sandbox.google.com.

Базовый путь Google для производства

https://vgw.googleapis.com/secure-serving/gsp/

Примечание. Если ваша интеграция уже запущена и вызывает хост https://billpaynotification.googleapis.com , вы можете продолжать это делать. Новые интеграции должны вызывать хост vgw.googleapis.com.

В этом руководстве будут использоваться конечные точки производства.

Тип контента и кодировка

Полезные данные сообщений, использующие шифрование PGP, должны использовать тип контента application/octet-stream; charset=utf-8 . Тела запросов PGP должны отправляться с использованием кодировки base64url, как определено в rfc4648 §5 .Полезные данные сообщений, использующие шифрование JWE, должны использовать тип контента application/jose; charset=utf-8 . Опция компактной сериализации, поддерживаемая JWE/JWS, обрабатывает кодировку тела окончательного запроса.

Коды состояния HTTP

API стандартных платежей предназначены для возврата кода состояния HTTP 200 для всех запросов, которые могут быть обработаны сервером. Сюда входят как успешные, так и отклоненные запросы с точки зрения бизнес-логики или логики приложения. Запросы, которые невозможно обработать, не должны приводить к коду состояния HTTP 200 , поскольку они представляют собой ошибку между Google и партнером. Вместо этого в ответе API должны использоваться соответствующие коды состояния HTTP, указанные ниже, с дополнительным объектом ErrorResponse .

Ошибки HTTP и причины
400	BAD REQUEST Клиент указал недопустимый аргумент. Это также может быть возвращено, если операция была отклонена, поскольку система не находится в состоянии, необходимом для выполнения операции. Используйте это, если повторные попытки запроса не могут быть успешными, пока состояние системы не будет явно исправлено. Например, если запрос на возврат не выполнен, поскольку он ссылается на несуществующую запись, повторная попытка не будет успешной, пока запись не появится в системе интегратора. Примечание. BAD_REQUEST (400) нельзя использовать в ситуациях, когда имеется соответствующая ошибка приложения. Например, неправильные валюты должны возвращать ACCOUNT_DOES_NOT_SUPPORT_CURRENCY с кодом 200, если стандартный ответ имеет это поле или перечисление.
401	UNAUTHORIZED В запросе нет действительных учетных данных аутентификации для операции. Например, недействительные подписи или неизвестные подписи должны возвращать 401.
403	FORBIDDEN / PERMISSION DENIED У вызывающего объекта нет разрешения на выполнение указанной операции.
404	NOT FOUND Некоторый запрошенный объект, например платеж или пользователь, не найден.
409	CONFLICT / ABORTED Операция была прервана, как правило, из-за проблемы параллелизма, например сбоев проверки секвенсора, прерывания транзакций и т. д.
412	PRECONDITION FAILED Этот код следует использовать в ситуациях, когда ключ идемпотентности используется повторно с разными параметрами.
429	RESOURCE EXHAUSTED / TOO MANY REQUESTS Исчерпан какой-то системный ресурс.
499	CANCELLED Операция была отменена (обычно вызывающей стороной).
500	INTERNAL ERROR Внутренние ошибки. Это означает, что некоторые инварианты, ожидаемые базовой системой, были нарушены.
501	UNIMPLEMENTED Операция не реализована, не поддерживается и не включена в этой службе.
503	UNAVAILABLE В настоящее время услуга недоступна. Скорее всего, это временное состояние, которое можно исправить повторной попыткой.
504	GATEWAY TIMEOUT / DEADLINE EXCEEDED Срок истек до завершения операции. Для операций, изменяющих состояние системы, эта ошибка может возвращаться, даже если операция завершилась успешно. Например, успешный ответ от сервера мог быть отложен на время, достаточное для истечения крайнего срока.

Запросить идемпотентность

Идемпотентность запросов – это центральная стратегия, используемая в API стандартных платежей, которая обеспечивает надежность и отказоустойчивость системного взаимодействия между Google и партнерами. Идемпотентные запросы — это запросы, которые потенциально могут быть отправлены несколько раз, но имеют тот же эффект, что и одиночный запрос. Эта стратегия обеспечивает конечную согласованность между системами, делая повторные попытки безопасными и позволяя нашим системам объединиться для достижения соглашения о состоянии ресурса.

Наш API использует идемпотентность для:

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

Примечание. Результаты ошибок никогда не должны кэшироваться или идемпотентно возвращаться. А автоматические повторные попытки обнаружения ошибок должны использовать стратегию экспоненциальной задержки.

Примеры

Пример 1: Соединение потеряно до получения ответа

Сценарий:

1. Google отправляет запрос интегратору.
2. Сервер интегратора получает этот запрос и успешно его обрабатывает.
3. Сервер Google отключается до получения ответа на шаге 2.
4. Питание сервера Google восстанавливается, и тот же запрос отправляется со всеми теми же параметрами (тот же идентификатор запроса и сведения о запросе, но обновленный requestTimestamp ) на сервер интегратора.

Исход:

В этом случае сервер-интегратор должен ответить тем же ответом, что и на шаге №2, поскольку все параметры, за исключением responseTimestamp , одинаковы. Побочный эффект возникает только один раз, на этапе 2. Шаг 4 не имеет побочного эффекта.

Пример 2. Запрос отправлен на сервер, находящийся на обслуживании.

Сценарий:

1. База данных сервера интегратора отключена на техническое обслуживание.
2. Google отправляет запрос интегратору.
3. Интегратор правильно возвращает код состояния UNAVAILABLE .
4. Сервер Google получает ответ и планирует повторную попытку.
5. База данных сервера интегратора снова подключается к сети.
6. Google повторно отправляет запрос с шага №2 (тот же идентификатор запроса и сведения о запросе, но обновленный requestTimestamp ). Обратите внимание, что идентификаторы запросов для обоих запросов должны быть одинаковыми.
7. Сервер интегратора получает запрос и возвращает код состояния «ОК» вместе с полным ответом.

Исход:

В этом случае сервер интегратора должен обработать запрос на шаге №7 и не возвращать HTTP 503 ( UNAVAILABLE ). Вместо этого сервер интегратора должен полностью обработать запрос и вернуть ответ «ОК» с соответствующим сообщением. Обратите внимание: пока система UNAVAILABLE Google может делать повторные запросы, аналогичные шагу №2. Каждый запрос должен привести к сообщению, аналогичному шагу №3. В конце концов, будут выполнены шаги №6 и №7.

Пример 3. Повторное сообщение не соответствует исходному из-за ошибки восстановления.

Сценарий:

1. Google отправляет запрос интегратору.
2. Сервер интегратора получает этот запрос и успешно его обрабатывает.
3. Сервер Google отключается до получения ответа на шаге 2.
4. Питание сервера Google восстановлено, и он пытается отправить тот же запрос, но, к сожалению, некоторые параметры отличаются.

Исход:

В этом случае сервер интегратора должен ответить кодом ошибки HTTP 412 ( PRECONDITION FAILED ), который указывает Google на наличие ошибки в этой системе.