Forma de pago en efectivo

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.

Agregar forma de pago
1) El usuario agrega una forma de pago
Elige dónde pagar
2) Luego, elige dónde pagar.
Instrucciones de pago
3) Por último, se les proporcionan instrucciones de pago.

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:

  1. Genera un flujo de números de referencia.
  2. 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

Descripción general de alto nivel de la forma de pago en efectivo

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

Número de referencia de generación de efectivo

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.

  1. El usuario accede a la IU de Google y envía una solicitud de un número de referencia.
  2. La IU de Google envía un mensaje al servidor de Google que necesita un número de referencia (getReferenceNumber).
  3. El servidor de Google le solicita al servidor de integración de pagos que genere un número de referencia (generateReferenceNumber).
  4. El servidor de integración de pagos genera y envía el número de referencia al servidor de Google.
  5. 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.
  6. 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

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.

  1. El usuario va a un minimercado para realizar un pago.
  2. Una vez completada la transacción, el minimercado notifica al integrador de pagos el pago.
  3. El servidor de integración de pagos envía un mensaje de éxito al minimercado.
  4. La tienda transmite que la transacción fue un éxito para el usuario, y los productos se entregarán al usuario pronto.
  5. 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.
  6. 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