Estándares del protocolo

La API sigue un conjunto de estándares de la API de HTTP y admite idempotencia para facilitar un modelo y la integración de datos.

URLs alojadas en Google

La documentación para cada método alojado en Google proporciona una URL base, que incluye el nombre del método y el número de versión principal. Se crea la URL completa Para ello, agrega el ID de cuenta de integrador de pagos del emisor al final. Por ejemplo, la documentación sobre el método de eco alojado en Google especifica la URL:

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

Si el ID de cuenta de integrador de pagos del emisor es INTEGRATOR_1, deberá agregar al final de la URL para formar:

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

Nota: La página de documentación del extremo para el método específico al que con la implementación tendrán la URL más precisa para tu caso.

URLs alojadas por socios

La documentación para cada método de API alojado por el socio proporciona una URL base, que incluye el nombre del método y el número de versión principal. No debes incluir los ID de cuenta de integrador de pagos (PIAID) en las URLs que alojas.

Entornos de zona de pruebas y producción

Google aloja las APIs de Standard Payments en la zona de pruebas (para el desarrollo y con fines de prueba) y la producción. Solicitudes en el entorno de la zona de pruebas de Google no generan ninguna responsabilidad financiera real. La zona de pruebas y entornos de producción son completamente independientes y no comparten claves ni información de las transacciones.

Google espera que tu zona de pruebas esté siempre disponible, ya que usaremos zona de pruebas para probar primero los cambios y las funciones nuevas.

Ruta base de la zona de pruebas de Google

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

Nota: Si tu integración ya se lanzó y llama al https://billpaynotification.sandbox.googleapis.com, puedes continuar hazlo. Las nuevas integraciones deben llamarse "vgw.sandbox.google.com". host.

Ruta base de producción de Google

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

Nota: Si tu integración ya se lanzó y llama al https://billpaynotification.googleapis.com, puedes continuar haciéndolo. Las integraciones nuevas deberían llamar a “vgw.googleapis.com”. host.

En esta guía, se usarán los extremos de producción.

Tipo y codificación de contenido

Las cargas útiles de mensajes que usan encriptación de PGP deben usar el tipo de contenido application/octet-stream; charset=utf-8 Los organismos de solicitud de PGP deben se enviarán con la codificación base64url, como se define en rfc4648, sección 5 Las cargas útiles de mensajes que usan encriptación JWE deben usar el tipo de contenido application/jose; charset=utf-8 La opción Serialización compacta compatible con JWE/JWS maneja la codificación para el cuerpo de la solicitud final.

Códigos de estado HTTP

Las APIs de pagos estándar están diseñadas para mostrar un código de estado HTTP 200 para todas las solicitudes que el servidor puede procesar. Esto incluye tanto solicitudes exitosas y rechazadas desde la perspectiva del negocio la lógica de la aplicación. Las solicitudes que no se puedan procesar no deben generar código de estado HTTP 200, ya que representan un error entre Google y el socio. En su lugar, la respuesta de la API debe usar el estado de HTTP adecuado a continuación con un objeto ErrorResponse opcional.

Errores y motivos de HTTP
400	BAD REQUEST El cliente especificó un argumento no válido. También se puede mostrar si se rechazó la operación debido a que el sistema no esté en un estado necesario para la ejecución de la operación. Usa esta opción si los reintentos de la solicitud no pueden tener éxito hasta que el estado del sistema se corrigió explícitamente. Por ejemplo, si falla una solicitud de reembolso porque hace referencia a una captura que no existe, volver a intentarlo no tendrá éxito. hasta que la captura exista en el sistema integrador. Nota: No se debe usar BAD_REQUEST (400) para situaciones en las que hay disponible un error de aplicación adecuado. Para ejemplo, se deberían mostrar monedas incorrectas ACCOUNT_DOES_NOT_SUPPORT_CURRENCY con el código 200 si el estándar tiene ese campo o enumeración.
401	UNAUTHORIZED La solicitud no tiene credenciales de autenticación válidas para el una sola operación. Por ejemplo, las firmas no válidas o desconocidas devuelve 401.
403	FORBIDDEN / PERMISSION DENIED El emisor de la llamada no tiene permiso para ejecutar la operación especificada.
404	NOT FOUND No se encontró alguna entidad solicitada, como el pago o el usuario.
409	CONFLICT / ABORTED La operación se anuló, por lo general debido a un problema de simultaneidad, como fallas en la verificación del secuenciador, anulaciones de transacciones, etcétera.
412	PRECONDITION FAILED Este código debe usarse en situaciones en las que se agrega una clave de idempotencia reutilizados con diferentes parámetros.
429	RESOURCE EXHAUSTED / TOO MANY REQUESTS Se agotó un recurso del sistema.
499	CANCELLED Se canceló la operación (por lo general, la cancela el emisor).
500	INTERNAL ERROR Errores internos. Esto significa que algunas variantes que espera el sistema subyacente se rompió.
501	UNIMPLEMENTED La operación no se ha implementado, no se admite ni está habilitada en este servicio.
503	UNAVAILABLE El servicio no está disponible actualmente. Probablemente, esta sea una transitoria y puede corregirse de nuevo.
504	GATEWAY TIMEOUT / DEADLINE EXCEEDED El plazo venció antes de que la operación se pudiera completar. Para las operaciones que cambian el estado del sistema, este error puede devolverse incluso si el la operación se completó correctamente. Por ejemplo, una respuesta exitosa desde un servidor podría haberse retrasado lo suficiente como para que la fecha límite y vencer.

IDempotencia de la solicitud

La idempotencia de la solicitud es una estrategia central que se utiliza en los pagos estándar Las APIs que se usan para garantizar que las interacciones del sistema entre Google y los socios se son robustos y tolerantes a errores. Las solicitudes Idempotentes son solicitudes que pueden se pueden enviar varias veces, pero tienen el mismo efecto que una sola solicitud. Esta estrategia facilita la coherencia eventual entre los sistemas asegurándole y reintentos seguros, lo que permite que nuestros sistemas lleguen a un acuerdo estado del recurso.

Nuestra API aprovecha la idempotencia para lo siguiente:

• reducir los problemas de conciliación, ya que permite que todas las acciones sean fáciles de rastrear auditables.
• evitar condiciones de carrera al garantizar que múltiples solicitudes idénticas de el mismo cliente no derivan en un estado final diferente.
• y minimizan el estado permitiendo que las solicitudes se entiendan de forma aislada, con para mejorar el rendimiento y la capacidad de procesamiento, ya que quita la carga del servidor causada por la retención de datos.
• Evitar la necesidad de campos adicionales para indicar si una solicitud es un reintento

Nota: Los resultados de errores nunca deben almacenarse en caché ni mostrarse de forma idempotente. Y... los reintentos automáticos para errores deben usar una estrategia de retirada exponencial.

Ejemplos

Ejemplo 1: Se perdió la conectividad antes de recibir la respuesta

Situación:

1. Google envía una solicitud al integrador.
2. El servidor integrador recibe esta solicitud y la procesa de forma correcta.
3. El servidor de Google se queda sin energía antes de recibir la respuesta del paso 2.
4. Se restablece la alimentación del servidor de Google y se envía la misma solicitud con los mismos parámetros (el mismo ID de solicitud y los detalles de la solicitud, pero actualizados requestTimestamp) al servidor del integrador

Resultado:

En este caso, el servidor integrador debe responder con la misma respuesta que se proporciona en paso 2, ya que todos los parámetros, excepto responseTimestamp, son iguales. El efecto secundario solo ocurre una vez, en el paso 2. El paso 4 no tiene efectos secundarios.

Ejemplo 2: Solicitud enviada a un servidor en mantenimiento

Situación:

1. La base de datos del servidor integrador está inactiva por tareas de mantenimiento.
2. Google envía una solicitud al integrador.
3. El integrador muestra correctamente el código de estado UNAVAILABLE.
4. El servidor de Google recibe la respuesta y programa un reintento.
5. La base de datos del servidor integrador vuelve a estar en línea.
6. Google vuelve a enviar la solicitud del paso 2 (el mismo ID de solicitud y los detalles de la solicitud) pero actualizó requestTimestamp). Ten en cuenta que los IDs de ambas solicitudes debería ser la misma.
7. El servidor integrador recibe una solicitud y muestra un código de estado OK con respuesta completa.

Resultado:

En este caso, el servidor integrador debe procesar la solicitud del paso 7 y no muestra HTTP 503 (UNAVAILABLE). En su lugar, el servidor integrador debería procesar la solicitud y mostrar OK con los mensajes adecuados. Ten en cuenta que, si bien el sistema está UNAVAILABLE. Google puede realizar solicitudes repetidas similares a Paso 2: Cada solicitud debe dar como resultado un mensaje similar al paso 3. Con el tiempo, se llevarán a cabo los pasos 6 y 7.

Ejemplo 3: El mensaje que se intentó reintentar no coincide con el mensaje inicial debido a un error de recuperación

Situación:

1. Google envía una solicitud al integrador.
2. El servidor integrador recibe esta solicitud y la procesa de forma correcta.
3. El servidor de Google se queda sin energía antes de recibir la respuesta del paso 2.
4. Se restablece la alimentación del servidor de Google y se intenta enviar la misma solicitud. pero, desafortunadamente, algunos de los parámetros son diferentes.

Resultado:

En este caso, el servidor integrador debe responder con 412 HTTP. (PRECONDITION FAILED), que le indica a Google que hay una en este sistema.