Descripción general
Los Pagos estándar de Google admiten FOP (formas de pago), como compras en tiendas de conveniencia (como 7-Eleven). A nivel general, un usuario que desea pagar bienes genera un número de referencia mediante el Integrador de pagos. Luego, el usuario lleva el número de referencia a un minimercado, quiosco o banco y paga el número de referencia.
Conceptos y terminología
Símbolos y convenciones
Las palabras clave "DEBE", "NO DEBE", "OBLIGATORIO", "DEBERÍA", "NO DEBERÁ", "DEBERÍA", "NO DEBERÁ", "RECOMENDADO", "PUEDE" y "OPCIONAL" de estos documentos se deben interpretar como se describe en RFC 2119.
Marcas de tiempo
Todas las marcas de tiempo se representan como milisegundos desde el tiempo Unix (1 de enero de 1970) en UTC.
Por ejemplo:
- 23 de abril de 2019 8:23:25 p.m. GMT = 1556051005000 milisegundos
- 16 de agosto de 2018 12:28:35 p.m. GMT = 1534422515000 milisegundos
Importes
Los valores monetarios de esta API están en 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
Idempotencia
Todas las llamadas de método dentro de esta API deben tener un comportamiento idempotente. Google reintentará las solicitudes de forma esporádica para asegurarse de que las transacciones estén en el mismo estado en ambos lados. Los integradores no deben intentar volver a procesar solicitudes que ya se procesaron correctamente. En su lugar, se debe informar la respuesta del procesamiento correcto. Todos los métodos tienen un RequestHeader
común que contiene un requestId. Este requestId es la clave de idempotencia para todas las llamadas.
Cualquier respuesta sin terminal (una respuesta correcta que no sea HTTP 200), no se debe procesar de forma idempotente. Por lo tanto, una solicitud que anteriormente obtuvo un 400 (solicitud incorrecta o condición previa fallida), cuando se la llamó por segunda vez, no debe mostrar 400 de forma idempotente, debe volver a evaluarse. En la reevaluación, podría mostrar un 400 o procesarse correctamente.
Para obtener más información sobre la idempotencia, consulta esta guía detallada.
Integrador
Ser una empresa que usa la plataforma de pagos de Google en su negocio. Pueden ser internos, como YouTube o AdWords, o empresas externas que desean integrar su servicio para que funcione con el ecosistema de Google.
forma de pago
Forma de pago. Esto es más general que un instrumento. Visa, Mastercard y PayPal son todas formas de pago.
Instrumento
Una instancia en particular de una forma de pago por parte de un cliente específico. Por ejemplo, la tarjeta de crédito de un usuario o su cuenta de PayPal. Una FOP con token para un cliente en particular también es un instrumento, ya que es una instancia de una forma de pago para ese cliente, almacenada de forma segura en nuestro sistema.
Token
Representación en el sistema de Google de la forma de pago de un usuario específico. Como contiene toda la información necesaria para realizar una compra, un token también es un instrumento. Esto puede incluir información como el número de cuenta que un usuario tiene con su integrador.
Flujos de claves
Google utiliza dos flujos clave para crear estos números de referencia y pagarlos:
- Genera un flujo de números de referencia.
- Flujo de número de referencia de pago
Luego, la conciliación y la liquidación de las compras resultantes se manejan a través del flujo de remesa.
En el siguiente diagrama, se ilustra cada uno de estos flujos.
Descripción general de Cash FOP
Los dos primeros flujos se describen con más detalle en las siguientes secciones. Consulta la página Flujo de remesas si deseas obtener más información al respecto.
Generar número de referencia
El propósito del flujo de generación de números de referencia es crear e intercambiar un identificador (número de referencia) que tanto Google como el integrador puedan usar para identificar una compra. Luego, el usuario podrá usar este número de referencia en un minimercado, un kiosco o un banco para completar la compra. A pedido de Google, el integrador genera este identificador llamando al método generateReferenceNumber
. La solicitud para generar el número de referencia incluye un importe y una descripción de la transacción.
En el siguiente diagrama, se ilustra cómo se genera un número de referencia y cómo se envía al cliente con instrucciones.
Flujo de generación de números de referencia
Esta es una lista de los objetos y lo que representan:
- Usuario: Es la persona que desea realizar un pago mediante esta forma de pago.
- IU de Google: Es la interfaz en la que el usuario realiza su compra. Podría ser a través de la Web o una aplicación.
- Servidor de Google: Es el servidor de backend de Google que solicita la generación del número de referencia y crea instrucciones de pago para el usuario.
- Servidor de integración de pagos: Es el servidor de backend de la integración de pagos que realiza un seguimiento de los detalles del pago y genera el número de referencia.
Este flujo comienza con el usuario que desea usar esta forma de pago en efectivo.
- El usuario accede a la IU de Google y envía una solicitud de un número de referencia.
- La IU de Google envía un mensaje al servidor de Google que necesita un número de referencia (
getReferenceNumber
). - El servidor de Google le solicita al servidor de integración de pagos que genere un número de referencia (
generateReferenceNumber
). - El servidor de integración de pagos genera y envía el número de referencia al servidor de Google.
- El servidor de Google crea instrucciones de pago junto con el número de referencia. Luego, envía esta información a la IU de Google.
- La IU de Google envía estas instrucciones y el número de referencia al usuario.
Notas sobre los números de referencia
Los números de referencia solo se pueden pagar una vez y se pueden cancelar mediante el flujo correspondiente. Además, los números de referencia deben ser alfanuméricos y admitir varios formatos de visualización.
Además de mostrar el número de referencia, las IU de Google pueden representar de manera opcional el número de referencia en el formato de Código 128 (un formato de código de barras). Se pueden solicitar otros formatos de códigos de barras.
Número de referencia de pago
El usuario utilizará este número de referencia en un minimercado, kiosco o banco para identificar la compra que desea pagar. El integrador debe hacer que el usuario confirme la compra que se está pagando mostrando el importe de la compra, la fecha y la descripción de la transacción antes de pagar.
Una vez que el usuario elige pagar, debe pagar en su totalidad y solo una vez. Esta API no admite pagos superiores o inferiores a un mismo número de referencia. Tampoco se admiten pagos múltiples a un único número de referencia.
Una vez que el usuario paga, el integrador debe notificar de inmediato a Google que este número de referencia se pagó con el método referenceNumberPaidNotification
. Al llamar a este método unos segundos después de que el usuario paga físicamente, el integrador le permite al usuario recibir rápidamente sus productos. (Esta llamada se puede agregar a una cola si la red no funciona).
Una vez pagado, el número de referencia y el importe se incluirán en el resumen de remesas enviado en un plazo de 2 días.
Este es un diagrama de secuencias que ilustra el pago de un número de referencia.
Flujo de pago del número de referencia
Los objetos del diagrama representan lo siguiente:
- Usuario: Es la persona que desea realizar un pago mediante esta forma de pago.
- Minimercado: Es la ubicación donde el usuario realiza el pago con el número de referencia y las instrucciones proporcionadas, como un minimercado.
- Servidor de integración de pagos: Es el servidor de backend del integrador de pagos que realiza un seguimiento de los detalles del pago.
- Servidor de Google: Es el servidor de backend de Google que solicita la generación del número de referencia y crea instrucciones de pago para el usuario.
Este flujo comienza con el usuario que va a un minimercado para realizar un pago de acuerdo con las instrucciones que se le proporcionaron.
- El usuario va a un minimercado para realizar un pago.
- Una vez completada la transacción, el minimercado notifica al integrador de pagos el pago.
- El servidor de integración de pagos envía un mensaje de éxito al minimercado.
- La tienda transmite que la transacción fue un éxito para el usuario, y los productos se entregarán al usuario pronto.
- El servidor de integración de pagos envía un mensaje al servidor de Google que indica que se pagó el número de referencia (
referenceNumberPaidNotification
). Este paso no debe bloquear el paso 4. - El servidor de Google responde con un mensaje de éxito al servidor de integración de pagos.
Cancelar número de referencia
Google puede cancelar los números de referencia. Si Google cancela un número de referencia, se llamará al método cancelReferenceNumber
. Si se devuelve correctamente esta llamada, no será válido pagar ese número de referencia, y el integrador deberá rechazar el pago de este número. Si la llamada se realiza de forma correcta, fallarán todas las llamadas futuras a referenceNumberPaidNotification
.
Si ya se inició el proceso de pago, por ejemplo, si el usuario ingresó su número de referencia en un kiosco, pero aún no pagó, el integrador deberá mostrar un código de respuesta HTTP 423 con ErrorResponse que contenga USER_ACTION_IN_PROGRESS
.
Siguiente: Flujo de remesa