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_1URL-адреса, размещенные партнерами
В документации для каждого метода API, размещенного у партнера, указан базовый URL-адрес, который включает имя метода и основной номер версии. Не следует включать идентификатор учетной записи платежного интегратора ( PIAID ) в размещаемые вами URL-адреса.
Песочница и производственная среда
Google размещает API стандартных платежей как в песочнице (для целей разработки и тестирования), так и в рабочей среде. Запросы в тестовой среде Google не влекут за собой никаких реальных финансовых обязательств. Песочница и производственная среда полностью разделены и не используют общие ключи или информацию о транзакциях.
Google ожидает, что ваша песочница будет постоянно доступна, поскольку мы будем использовать ее для первого тестирования изменений и новых функций.
Базовый путь песочницы Google
https://vgw. sandbox.google .com/secure-serving/gsp/Базовый путь Google для производства
https://vgw.googleapis.com/secure-serving/gsp/В этом руководстве будут использоваться конечные точки производства.
Тип контента и кодировка
Полезные данные сообщений, использующие шифрование 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Клиент указал недопустимый аргумент. Это также может быть возвращено, если операция была отклонена, поскольку система не находится в состоянии, необходимом для выполнения операции. Используйте это, если повторные попытки запроса не могут быть успешными, пока состояние системы не будет явно исправлено. Например, если запрос на возврат не выполнен, поскольку он ссылается на несуществующую запись, повторная попытка не будет успешной, пока запись не появится в системе интегратора. |
| 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: Соединение потеряно до получения ответа
Сценарий:
- Google отправляет запрос интегратору.
- Сервер интегратора получает этот запрос и успешно его обрабатывает.
- Сервер Google отключается до получения ответа на шаге 2.
- Питание сервера Google восстанавливается, и тот же запрос отправляется со всеми теми же параметрами (тот же идентификатор запроса и сведения о запросе, но обновленный
requestTimestamp) на сервер интегратора.
Исход:
В этом случае сервер-интегратор должен ответить тем же ответом, что и на шаге №2, поскольку все параметры, за исключением responseTimestamp , одинаковы. Побочный эффект возникает только один раз, на этапе 2. Шаг 4 не имеет побочного эффекта.
Пример 2. Запрос отправлен на сервер, находящийся на обслуживании.
Сценарий:
- База данных сервера интегратора отключена на техническое обслуживание.
- Google отправляет запрос интегратору.
- Интегратор правильно возвращает код состояния
UNAVAILABLE. - Сервер Google получает ответ и планирует повторную попытку.
- База данных сервера интегратора снова подключается к сети.
- Google повторно отправляет запрос с шага №2 (тот же идентификатор запроса и сведения о запросе, но обновленный
requestTimestamp). Обратите внимание, что идентификаторы запросов для обоих запросов должны быть одинаковыми. - Сервер-интегратор получает запрос и возвращает код состояния «ОК» вместе с полным ответом.
Исход:
В этом случае сервер интегратора должен обработать запрос на шаге №7 и не возвращать HTTP 503 ( UNAVAILABLE ). Вместо этого сервер интегратора должен полностью обработать запрос и вернуть ответ «ОК» с соответствующим сообщением. Обратите внимание: пока система UNAVAILABLE , Google может делать повторные запросы, аналогичные шагу №2. Каждый запрос должен привести к сообщению, аналогичному шагу №3. В конце концов, будут выполнены шаги №6 и №7.
Пример 3. Повторное сообщение не соответствует исходному из-за ошибки восстановления.
Сценарий:
- Google отправляет запрос интегратору.
- Сервер интегратора получает этот запрос и успешно его обрабатывает.
- Сервер Google отключается до получения ответа на шаге 2.
- Питание сервера Google восстановлено, и он пытается отправить тот же запрос, но, к сожалению, некоторые параметры отличаются.
Исход:
В этом случае сервер интегратора должен ответить кодом ошибки HTTP 412 ( PRECONDITION FAILED ), который указывает Google на наличие ошибки в этой системе.