Descripción general
Google Standard Payments admite formas de pago (formas de pago) basadas en dinero en efectivo, como las compras en tiendas de conveniencia (como las tiendas 7-Eleven). En términos generales, un usuario que desea pagar bienes genera un número de referencia a través del integrador de pago. Luego, el usuario lleva el número de referencia a un minimercado, un kiosco o un banco para pagarlo.
|
|
|
Conceptos y terminología
Símbolos & Convenciones
Las palabras clave “DEBEN”, "NO DEBE", "OBLIGATORIO", "SHALL", "NO DEBERÁ", "DEBERÍA", «NO DEBERÍAS», "RECOMENDADO", "MAYO", y "OPTIONAL" en 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 en esta API están en un formato llamado "micros", un estándar en 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 = 1230000 micro USD
- USD 0.01 = 10,000 microUSD
Idempotencia
Todas las llamadas a métodos dentro de esta API deben tener un comportamiento idempotente. Google volverá a intentar las solicitudes de manera 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 ninguna solicitud que ya se haya procesado 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 que no sea terminal (no HTTP 200-success) no debe procesarse de forma idempotente. Por lo tanto, una solicitud que previamente obtuvo un 400 (solicitud incorrecta/condición previa con errores), cuando se llamó por segunda vez, no debe mostrar 400 de forma idempotente, se debe volver a evaluar. En la reevaluación, podría mostrar un error 400 o procesarse correctamente.
Para obtener más información sobre la idempotencia, consulta esta guía detallada.
Integrador
Una empresa que usa la plataforma de pagos de Google para su negocio. Podría ser una empresa interna (propia), como YouTube o AdWords, o una empresa externa (de terceros) que desea integrar su servicio para funcionar con el ecosistema de Google.
Forma de pago
Forma de pago. Esto es más general que un instrumento. Visa, Mastercard y PayPal son formas de pago.
Instrumento
Es una instancia particular de una forma de pago realizada por un cliente específico. Por ejemplo, la tarjeta de crédito de un usuario o su cuenta de PayPal. Una FOP con tokens asignados a un cliente en particular también es un instrumento porque es una instancia de una forma de pago para ese cliente que se almacena de forma segura en nuestro sistema.
Token
Es una representación, en el sistema de Google, de la forma de pago de un usuario específico. Debido a que 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 clave
Google utiliza dos flujos clave para crear y pagar estos números de referencia:
- Generar flujo de número de referencia
- Flujo de número de referencia de pago.
Posteriormente, la conciliación y la liquidación de las compras resultantes se manejan mediante el flujo de remesas.
En el siguiente diagrama, se ilustra cada uno de estos flujos.
Descripción general de las formas de pago
Los dos primeros flujos se describen con más detalle en las siguientes secciones. Consulta la página Flujo de remesas si quieres obtener más información sobre ese flujo.
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. El integrador genera este identificador a pedido de Google 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 se envía al cliente con instrucciones.
Flujo de generación del número de referencia
A continuación, se muestra una lista de los objetos y lo que representan:
- Usuario: Es la persona que desea realizar un pago con esta forma de pago.
- IU de Google: Es la interfaz en la que el usuario realiza la compra. ya sea a través de la Web o de una app.
- Servidor de Google: Es el servidor de backend de Google que solicita la generación del número de referencia y crea las instrucciones de pago para el usuario.
- Servidor de integración de pagos: Es el servidor de backend del integrador 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, que envía una solicitud de un número de referencia.
- La IU de Google envía un mensaje al servidor de Google indicando que necesita un número de referencia (
getReferenceNumber). - El servidor de Google le solicita al servidor integrador 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 que acompañan al 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 a través del flujo de cancelación de números de referencia. Además, los números de referencia deben ser alfanuméricos y deben admitir varios formatos de visualización.
Además de mostrar el número de referencia, las IU de Google pueden representar opcionalmente el número de referencia con el formato Código 128 (un formato de código de barras). Se pueden admitir otros formatos de códigos de barras a pedido.
Número de referencia de pago
El usuario utilizará este número de referencia en un minimercado, un kiosco o un banco para identificar la compra que desee pagar. El integrador debe pedirle al usuario que muestre el importe, la fecha y la descripción de la transacción para confirmar que se está pagando la compra antes de pagar.
Una vez que el usuario elige pagar, debe pagar el importe total y solo una vez. Esta API no admite pagos superiores o inferiores a un solo 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. Cuando se llama a este método unos segundos después de que el usuario paga físicamente, el integrador le permite recibir rápidamente sus productos. (Esta llamada se puede agregar a una cola si la red no funciona).
Una vez que se pague, el número de referencia y el importe se incluirán en el resumen de remesas enviado en T+2 días.
A continuación, se muestra un diagrama de secuencia 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 con esta forma de pago.
- Pago en 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 las instrucciones de pago para el usuario.
Este flujo se inicia con el usuario que va a un minimercado para realizar un pago de acuerdo con las instrucciones que se le dan.
- El usuario va a una tienda de conveniencia para realizar un pago.
- Una vez que se completa la transacción, el minimercado notifica el pago al integrador de pagos.
- El servidor de integración de pagos envía un mensaje de éxito a la tienda de conveniencia.
- La tienda comunica que la transacción fue exitosa para el usuario y que la mercadería le llegará pronto.
- El servidor de integración de pagos envía un mensaje al servidor de Google indicando 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 integrador 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 la llamada se devuelve correctamente, no es válido pagar ese número de referencia, y el integrador debe rechazar el pago por este número. Si la llamada se realiza correctamente, fallarán todas las llamadas futuras a referenceNumberPaidNotification.
Si el proceso de pago ya comenzó, por ejemplo, si el usuario ingresó su número de referencia en un kiosco, pero todavía no pagó, el integrador debe mostrar un código de respuesta HTTP 423 con ErrorResponse que contenga USER_ACTION_IN_PROGRESS.
Siguiente: Flujo de remesas