ID de la cuenta
El ID de la cuenta se envía desde el servidor del integrador durante el flujo de asociación. Se usa para ayudar a Google a identificar la cuenta subyacente de dos maneras. Primero, identifica varios instrumentos que usan la misma cuenta de usuario subyacente para evaluar el riesgo y el fraude. Los agentes del servicio de atención al cliente de Google usan esta información para identificar la cuenta. Este valor debe identificar de manera única la cuenta de usuario en todas las solicitudes de asociación. Además, debe ser inmutable en la cuenta específica y el usuario debe poder identificarla.
Por ejemplo, si un integrador usa una dirección de correo electrónico para la identidad, esta puede ser la dirección de correo electrónico. Sin embargo, si el integrador usa una dirección de correo electrónico para el acceso, pero esa dirección se puede cambiar, la dirección de correo electrónico no es la opción adecuada para el ID de la cuenta. Lo que se elija, su valor debe ser el mismo para varios intentos de asociación con la misma identidad de usuario del integrador de pagos.
Paquete de aplicación para Android (APK)
Es el formato de archivo de paquete que usa el sistema operativo Android para la distribución y la instalación de apps para dispositivos móviles.
Control de versiones de las APIs
Esta especificación admite el control de versiones. Las versiones compatibles se configuran en el servidor de Google. Cuando se pasa de la versión N a la M (en la que M es una versión principal superior a la N), el integrador debe admitir N y M hasta que Google verifique que todo el tráfico se migró a M. Las versiones se identifican de manera diferente según el contexto. Las APIs de Android y las APIs de WebRedirect pasarán la versión de la API como un parámetro a la solicitud. Las llamadas de servidor a servidor pasan la versión como una parte de la ruta de URL.
Las versiones no se corrigen por flujo. Por lo tanto, durante la migración de N a M, un integrador puede ver una captura con la versión M y un reembolso con la versión N por la misma transacción. Durante la asociación, el integrador puede recibir una solicitud de autenticación de la versión M con una solicitud de asociación de la versión N.
ID de asociación
El associationID identifica la asociación entre la cuenta del cliente y el instrumento de Google. associationId es muy similar a GPT. De hecho, tiene la misma vida útil que una GPT y tiene una cardinalidad de 1:1 con respecto a una GPT. associationId difiere de la GPT en cuanto a su sensibilidad. GPT es un token sensible que se usa para pagos. El associationId es un identificador público que representa la misma relación, pero no es de naturaleza tan sensible.
El associationId se pasa al integrador de pagos durante associateAccount. Este mismo valor se pasa al integrador durante la reautenticación. Esto permite que el integrador tenga contexto sobre qué cuenta se debe autenticar. Si se pasa el ID de asociación, la misma cuenta que se identificó durante la asociación original se debe completar previamente y autenticarse.
Se espera que el integrador de pagos almacene todos los IDs de asociación y los asocie con una cuenta de integrador en particular durante la vigencia del contrato entre el integrador y Google.
ID de solicitud de autenticación
Los métodos refreshToken, associateAccount y la captura (opcional) toman una referencia a una autenticación. Esta referencia tiene el formato del requestId de la autenticación específica a la que se refiere Google. El integrador de pagos usará este campo para verificar que, en efecto, el método se haya llevado a cabo con una autenticación exitosa.
Los métodos de captura pueden tener una requestId de autenticación propagada. Esto sucede en dos casos. Si Google autentica al usuario justo antes de una captura, Google propaga el campo de autenticación requestId. Además, Google a menudo autentica al usuario en el momento de la configuración cuando se establece una programación de pagos automáticos. Google escribe la requestId de autenticación según ese programa y envía la requestId junto con cada captura asociada con esa programación en particular.
Se espera que los integradores de pagos almacenen todos los requestIds de autenticación durante 30 días. Si un integrador de pagos desea auditar la requestIds de autenticación que puede estar presente en una solicitud de captura, incluidas las que se incluyen en las programaciones de pagos, el integrador debe almacenar todas las requestId de autenticación durante la vigencia del contrato entre el integrador y Google.
Empresa
Una empresa es un concepto definido dentro de la configuración y el contrato de Google. Una empresa define la relación entre el integrador y Google. Las claves de PGP y las CA raíz SSL (opcionalmente) están asociadas con la empresa. Lo más importante es que una empresa está asociada con uno o más IDs de cuenta de integrador de pagos. Las GPT creadas dentro de una empresa funcionan principalmente para todos los IDs de cuenta del integrador de pagos dentro de la empresa. Se aplican algunas excepciones. Por ejemplo, si la etiqueta GPT está asociada con una cuenta denominada en una moneda (y no admite tarifas de FX) y está intentando realizar una compra en un ID de cuenta del integrador de pagos en una moneda diferente.
Forma de pago (FOP)
Todas las transacciones incluyen una o más formas de pago (FOP), como una tarjeta de crédito o una transferencia electrónica de fondos, que los usuarios usan para pagar a Google por productos o servicios, o para pagar a los usuarios en el caso de usuarios de AdSense y desarrolladores de Google Play. Las formas de pago también se denominan Instrumentos de Pago, Instrumentos y Formas de Pago.
Token de pago de Google (GPT)
GPT es un valor aleatorio, seguro y codificado en base64 para la Web que genera el servidor de Google en el momento de la asociación y que se pasa al servidor del integrador. GPT es un identificador privado que representa la vinculación entre la cuenta del usuario con el integrador y el instrumento de Google. Una GPT es un token que reemplaza las credenciales del usuario o un ID de la cuenta. Este token se usa durante los flujos de compra para identificar la cuenta a la que se debe aplicar la tarjeta de crédito o débito, y es secreto para ambas partes. Las etiquetas GPT nunca se deben enviar en texto sin formato y se deben encriptar para garantizar la privacidad.
GPT es diferente de associationId porque associationId no está protegido
y se pasa libremente por medios públicos (URLs, conexiones no seguras). Solo Google y el integrador conocen GPT.
Se espera que el integrador de pagos almacene todas las GPTS y las asocie con una cuenta de integrador en particular durante la vigencia del contrato entre el integrador y Google.
Idempotencia
Una operación idempotente se puede aplicar varias veces sin cambiar el resultado ni tener efectos secundarios nuevos más allá de la aplicación inicial de la operación. Por lo general, la idempotencia usa una "clave" para identificar la misma solicitud. Todas las solicitudes definidas entre los dos servidores usan una clave de idempotencia definida en el encabezado de la solicitud. El encabezado de la solicitud tiene un ID de solicitud que se usa como clave de idempotencia. El ID de solicitud es único a nivel global. Las solicitudes Idempotentes deben ser del mismo cuerpo JSON, con una excepción. El requestTimestamp será diferente para cada solicitud. Esta es una distinción importante. requestTimestamp es la hora en la que el servidor envió esta solicitud. Es único por intento. Esto ayuda a reducir la capacidad de los ataques de repetición.
Del mismo modo, una respuesta idempotente debe ser exactamente el mismo cuerpo JSON, excepto que responseTimestamp será diferente para cada respuesta.
Todos los métodos de servidor a servidor, excepto el método Echo, deben ser idempotentes. Las solicitudes de autenticación a la IU del integrador (ya sea para Android o la Web) no son idempotentes.
Para ver ejemplos de comportamiento idempotente, consulta el documento de referencia.
Identificador (ID)
Los identificadores representan una transacción o comunicación entre el integrador de pago y Google.
Instrumento
El instrumento representa una forma de pago almacenada asociada con un solo cliente de Google. Estos son algunos ejemplos de instrumentos:
- Un número de tarjeta de crédito registrado
- Una cuenta bancaria y un número de ruta
Los usuarios pueden tener varios instrumentos asociados con su identidad de Google.
Micrómetros
Los valores monetarios de esta API se representan con un formato llamado "micros", un estándar de Google. Los micros son un formato de precisión fija basado en números enteros. Para representar un valor monetario en micros, multiplica el valor de la moneda estándar por 1,000,000.
Por ejemplo:
- USD 1.23 = 1230,000 microUSD
- USD 0.01 = 10,000 microUSD
Integrador de pagos
El integrador externo que procesa los pagos de una transacción del usuario
ID de cuenta de integrador de pagos
Este identificador representa restricciones en torno al contrato entre Google y el integrador. Google genera el ID de la cuenta del integrador y lo asigna al integrador durante la configuración. Por lo general, esto se denomina "MID". Todas las solicitudes y respuestas deben incluir este ID. Este identificador es opaco y nunca se debe analizar. Es posible que el formato de este identificador no sea coherente en todos los ID emitidos.
Este identificador nunca cambia durante el ciclo de vida de una transacción. En el caso de una captura y un reembolso, se usa el mismo identificador.
Las restricciones del ID de la cuenta del integrador se definen en el contrato en sí. Por lo general, las restricciones están relacionadas con la facturación. Por ejemplo, un integrador admite CAD y MXN que se facturan como USD, pero requiere que las transacciones de EUR se facturen en EUR. En este caso, se usarán dos IDs diferentes de la cuenta del integrador de pagos: uno para la facturación en USD y el otro para la facturación en euros.
El identificador se puede eliminar gradualmente para dar lugar a identificadores nuevos. Si un identificador deja de estar disponible, Google dejará de iniciar capturas para ese identificador. Sin embargo, el integrador debe respetar los reembolsos de las transacciones realizadas con ese identificador durante un año a partir de la última iniciación de captura (la iniciación de captura se define como el requestTimestamp que se encuentra en requestHeader).
PII
La información de identificación personal (PII) es la información que identifica de forma personal a una persona y cualquier otro dato que Google pueda vincular razonablemente a dicha información, como el nombre, la dirección de correo electrónico, la dirección de correo postal o el número de teléfono de un usuario, ya sea solos o en combinación.
Identificación de la solicitud
El requestId identifica toda la comunicación entre Google y el integrador de pagos.
IIPS
La información de identificación personal sensible (IIPS) es un subconjunto de la información de identificación personal (PII) que presenta un alto riesgo para el usuario si se ve comprometida o se usa de forma inadecuada. La SPII suele tener requisitos de almacenamiento y manejo restrictivos que imponen las entidades legales, regulatorias o de cumplimiento.
Token
Los tokens agregan una capa adicional de seguridad cuando se intercambian credenciales sensibles, como PII o IIPS, entre Google y el integrador.
Dirección del usuario
En el momento de la creación del instrumento, Google verifica si el usuario es cliente de Google Payments. Esto es independiente de ser cliente de Google. Para ser cliente de Google Payments, necesitamos la dirección de facturación del usuario. Algunas agencias reguladoras nos exigen que conozcamos la dirección completa del usuario, mientras que otras exigen un subconjunto de esa dirección.
Si el integrador de pagos tiene registrada una dirección de este usuario, Google desea obtenerla durante el flujo de asociación para completar previamente el formulario de dirección del usuario. El usuario tiene la opción de cambiar esa dirección que se completó previamente. Cuando se completa previamente la dirección del usuario, se disminuye la fricción para agregar un instrumento y se aumenta el porcentaje de conversiones de los usuarios que los agregan.
Si la dirección se comparte, Google también la usa como cálculo en su modelo de riesgo. Esto permite que el motor de riesgos de Google comprenda la dirección en la que el usuario dice que se le factura y la compara con la ubicación de IP en la que se encuentra actualmente.
Compartir direcciones es puramente una optimización. No hay problema y se espera que algunos integradores no tengan una dirección de facturación del usuario o no puedan compartir esta dirección.
Codificación Base64 segura para la Web
El estándar de codificación especificado en la sección 5 de RFC 4648, codificación Base64 con URL y nombre de archivo seguro del alfabeto, también a veces denominado codificación Base64 segura para la Web o "base64url". (Esto es lo mismo que la codificación base64 con el alfabeto seguro de URL y nombre de archivo de RFC 3548, sección 4). Todos los valores encriptados y firmados deben codificarse con este estándar.