Стандарты протоколов

API соответствует набору стандартов HTTP API и поддерживает механизм идемпотентности, повышающий надежность интеграции.

URL в Google

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

https://vgw.googleapis.com/gsp/chargeback-alert-v1/echo

Если инициатору вызова присвоен идентификатор аккаунта платежного интегратора со значением INTEGRATOR_1, то этот идентификатор следует добавить в конец URL:

https://vgw.googleapis.com/gsp/chargeback-alert-v1/echo/INTEGRATOR_1

Примечание. Наиболее подходящий URL указан на странице документации конечной точки, соответствующей выбранному вами методу.

URL на стороне партнера

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

Тестовая и рабочая среды

Chargeback Alert API размещены в тестовой и рабочей средах. Тестовая среда предназначена для разработки и тестирования. Запросы, отправленные в тестовой среде Google, не накладывают никаких реальных финансовых обязательств. Тестовая среда полностью отделена от рабочей. Ключи и информация о транзакциях в них не пересекаются.

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

Базовый путь тестовой среды Google

https://vgw.sandbox.google.com/gsp/

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

Базовый путь рабочей среды Google

https://vgw.googleapis.com/gsp/

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

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

Тип контента и шифрование

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

Коды статуса HTTP

Для всех запросов, которые могут быть обработаны сервером, Chargeback Alert 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 Крайний срок истек до завершения операции. Если операция изменяет состояние системы, то эта ошибка может быть возвращена, даже если операция выполнена успешно. Например, успешный ответ сервера мог быть отправлен с существенной задержкой, из-за чего время ожидания ответа истекло.

Идемпотентность запроса

Идемпотентность запроса – это ключевая стратегия, которая используется в Chargeback Alert 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. Сервер интегратора принимает запрос и возвращает код статуса OK вместе с полным ответом.

Результат

В этом случае сервер интегратора должен обработать запрос на шаге 7 и не возвращать код ошибки HTTP 503 (UNAVAILABLE). Вместо этого сервер интегратора должен полностью обработать запрос и вернуть код статуса OK с соответствующим сообщением. Обратите внимание, что, когда система находится в состоянии UNAVAILABLE, Google может повторно отправлять запросы, аналогичные запросу на шаге 2. Результатом каждого запроса должно быть сообщение, аналогичное сообщению на шаге 3. В конечном итоге будут выполнены шаги 6 и 7.

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

Сценарий

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

Результат

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