Estos son algunos casos de uso importantes que debes considerar, así como los lineamientos y las APIs necesarios para implementar tu forma de pago en efectivo.
Casos de uso
La API de Reference Number tiene varios usos. En esta guía, se analizarán dos casos de uso y se te guiará a través de su implementación.
- Efectivo: El usuario paga en efectivo en una ubicación física.
- VAN: El usuario transfiere dinero a un número de cuenta virtual.
Efectivo
Para comprar un producto de Google, un usuario puede pagarlo en efectivo en una ubicación física, como un minimercado. A fin de identificar la transacción, el usuario generará un número de referencia que llevará a la tienda para pagar. Además, Google mostrará instrucciones al usuario para completar la compra. Idealmente, tan pronto como el usuario completa la compra, el integrador notifica a Google para que Google pueda entregar el producto.
Tu punto de contacto en Google te pedirá una muestra de tus instrucciones de pago típicas. Trabajarás con tu contacto de Google para optimizar y definir mejor los mensajes.
La experiencia del usuario que Google desea proporcionar es que el pedido del cliente se entrega cuando sale de la tienda. Google espera recibir la ReferenceNumberPaidNotification en un plazo de tres minutos a partir de la fecha en que el cliente haya pagado el número de referencia. Una vez que se envía ReferenceNumberPaymentsNotification, el integrador no puede revertir la transacción.
VAN
Un usuario puede pagar un bien con su cuenta bancaria. Google solicitará un número de cuenta virtual al integrador y presentará el número y las instrucciones al usuario. Luego, el usuario copiará el número y lo ingresará en su aplicación bancaria además del importe que desea transferir.
El integrador debe verificar que el importe transferido coincida con el importe de la solicitud referenceNumberGeneration y, luego, notificar a Google que se pagó el número de referencia.
Una vez que Google reciba la ReferenceNumberPaidNotification, entregará el producto, y el integrador no podrá revertir la transacción.
Cómo enviar mensajes entre sus servidores y los de Google
Cuando envíes mensajes entre tus servidores y los de Google, o viceversa, hazlo de acuerdo con estos lineamientos.
Solicitud entrante: DecryptWithVendorPrivateKey(Base64UrlDecode(request))
Respuesta saliente - Base64UrlEncode(EncryptWithGooglePublicKey(request))
Solicitud de Google: Base64UrlEncode(EncryptWithGooglePublicKey(request))
Respuesta de Google - DecryptWithVendorPrivateKey(Base64UrlDecode(request))
Estos son una biblioteca y una muestra de PGP en Java que muestran el control de solicitudes y respuestas.
Seguir el comportamiento idempotente
La idempotencia significa que no debes intentar volver a procesar ninguna solicitud (como un pago) que ya se haya procesado correctamente. En su lugar, se debe informar la respuesta del procesamiento correcto.
Por qué es importante
Google puede reintentar algunas solicitudes para asegurarse de que el estado de nuestro lado sea el mismo que el del proveedor. El sistema no debería pensar que se trata de otra transacción. Por lo tanto, la idempotencia es muy importante. Esto significa que un integrador no debe volver a procesar algo que ya se procesó de forma correcta. En ese caso, se debe enviar la respuesta anterior.
Cómo implementar la idempotencia
Si Google vuelve a intentar, el ID de solicitud será el mismo y el contenido será el mismo, pero la marca de tiempo será diferente. Responde con la misma respuesta que enviaste anteriormente. Si tu primera respuesta fue 200 (Listo), entonces Google espera la misma respuesta con una marca de tiempo diferente.
Si tu respuesta anterior fue un error (400 o 500, etc.), debes procesar esa solicitud como una solicitud nueva y volver a verificarla. Esto es útil si el servidor estuvo inactivo la primera vez y, si vuelves a intentarlo, la solicitud tendrá otra oportunidad de procesarse correctamente.
Para obtener más información, consulta esta guía detallada.
Usa el ID de cuenta de integración de pagos (PIAID)
Las integraciones con Google pueden requerir la integración con las diferentes entidades comerciales de Google. Por ejemplo, Google Play es una entidad, la otra es YouTube y la otra es Google Ads. Para representar cada configuración, se incluirán diferentes cuentas de comerciante.
Para la asignación de cada entidad de Google a cada cuenta de comerciante, Google proporciona los IDs de cuenta de integrador de pagos (PIAID). Para ver un ejemplo de la API de FOP en efectivo, consulta generateReferenceNumber. A continuación, se muestra un ejemplo en el que se usa esta asignación.
Para la asignación de cada entidad de Google a cada cuenta de comerciante, Google proporciona los IDs de cuenta de integrador de pagos (PIAID). Para ver un ejemplo en el que se usa la API de FOP de efectivo, consulta generateReferenceNumber. A continuación, se muestra un ejemplo en el que se usa esta asignación.
{
"requestHeader": {
"protocolVersion": {
"major": 1,
"minor": 0,
"revision": 0
},
"requestId": "bWVyY2hhbnQgdHJhbnNhY3Rpb24gaWQ",
"requestTimestamp": "1502220196077"
},
"paymentIntegratorAccountId": "InvisiCashUSA_USD",
"transactionDescription": "Google - Music",
"currencyCode": "USD",
"amount": "2000000"
}
Observa la parte destacada. Los dos valores necesarios aquí son los paymentIntegratorAccountId que proporcionó tu punto de contacto en Google y tu cuenta del comerciante.
El integrador también puede tener cuentas diferentes según cada país en el que se presta servicio. Esto puede deberse a diversas leyes fiscales y a otras diferencias de un país a otro. En este caso, se podría generar otro PIAID para cada país.
APIs para integrar
Las siguientes APIs controlan la generación del número de referencia y las notificaciones de pago.
Las siguientes APIs manejan las remesas y las liquidaciones.
- RemittanceStatementNotification
- RemittanceStatementDetails
- AcceptRemittanceStatement/AcceptRemittanceStatement con modificaciones
Deberás integrar todas las APIs mencionadas anteriormente para generar números de referencia y establecer un acuerdo con Google.
Generar número de referencia
Google llama a GenerateReferenceNumber cuando inicias una compra. Esperamos que respondas con un número de referencia que identifique la transacción o cuenta. La latencia esperada es inferior a 3 segundos.
En el caso de las transacciones en efectivo, el número de referencia puede tener hasta 12 caracteres.
URL: POST https://[your basepath]/v1/generateReferenceNumber
Cómo solicitar JSON
{
"requestHeader": {
"protocolVersion": {
"major": 1,
"minor": 0,
"revision": 0
},
"requestId": "cf9fde73-3735-4463-8e6e-c999fda35af6",
"requestTimestamp": "1561678470395"
},
"paymentIntegratorAccountId": "Sample_Cash_Vendor_282",
"transactionDescription": "Google Play - Tester",
"currencyCode": "USD",
"amount": "10000000"
}
Respuesta JSON
{
"responseHeader": {
"responseTimestamp": "1561678947659"
},
"result": "SUCCESS",
"referenceNumber": "38a41c05-ba7b-4040-a909-4331d0b9ce46"
}
Ejemplo de Java
`String generateReferenceNumberJson = Utils.decryptAndDecode(encodedEncryptedGenerateReferenceNumberRequest);`
GenerateReferenceNumberRequest request = gson.fromJson(generateReferenceNumberJson, GenerateReferenceNumberRequest.class);
Cancelar número de referencia
Google puede cancelar un número de referencia y evitar que el usuario lo pague. Un ejemplo de caso de uso es una promoción que venció. Una vez que hayas respondido con éxito a esta solicitud, debes asegurarte de que el número de referencia no se pueda pagar.
Si el usuario ya inició el proceso de pago, por ejemplo, una búsqueda de número de referencia desde el punto de venta, tu servidor debería responder con una respuesta HTTP 423 y ErrorResponse en el cuerpo de la solicitud con el estado USER_ACTION_IN_PROGRESS.
URL: POST https://[your basepath]/v1/cancelReferenceNumber
Cómo solicitar JSON
{
"requestHeader": {
"protocolVersion": {
"major": 1,
"minor": 0,
"revision": 0
},
"requestId": "51e00f16-36ba-4490-b228-0a670d202206",
"requestTimestamp": "1561678947926"
},
"paymentIntegratorAccountId": "Sample_Cash_Vendor_282",
"referenceNumber": "38a41c05-ba7b-4040-a909-4331d0b9ce46"
}
Respuesta JSON
{
"responseHeader": {
"responseTimestamp": "1561680406459"
},
"result": "SUCCESS"
}
referenceNumberPaidNotification
Una vez que se acepte el pago y se complete la transacción, tu servicio deberá notificar a Google que la transacción se completó y entregar el producto al usuario. Una vez que Google reciba esta notificación, espera que la transacción finalice y no se pueda reservar.
URL del extremo referenceNumberPaidNotification:
POST https://billpaynotification.googleapis.com/secure-serving/gsp/v1/referenceNumberPaidNotification/[PIAID]
Cómo solicitar JSON
{
"requestHeader": {
"requestTimestamp": "1561748625577",
"requestId": "ae8e310a-92de-436a-a32c-0bd753ae4e4b",
"protocolVersion": {
"major": 1,
"minor": 0,
"revision": 0
}
},
"paymentIntegratorTransactionId": "cf9fde73-3735-4463-8e6e-c999fda35af6",
"referenceNumber": "e4e15b5d-8154-4068-b6eb-560e2a65ac48",
"paymentLocation": {
"brandName": "TestMart",
"locationId": "1234"
},
"paymentIntegratorAccountId": "Sample_Cash_Vendor_282",
"paymentTimestamp": "1561748625577"
}
Respuesta JSON
{
"responseHeader": {
"responseTimestamp": "1561748642600"
},
"result": "SUCCESS"
}
Implementar remesas
Una vez que hayas integrado las APIs de tu forma de pago específica, estarás listo para recibir las remesas. Las remesas funcionan de la misma manera en todas las formas de pago.
remittanceStatementNotification
Dos días después de una transacción, Google enviará una remittanceStatementNotification con un resumen de las transacciones que registró ese día. Dos días después de la transacción, se ve una notificación de ejemplo de esta manera:
POST https://www.integratordomain.com/v1/remittanceStatementNotification
Cómo solicitar JSON
{
"requestHeader": {
"protocolVersion": {
"major": 1,
"minor": 0,
"revision": 0
},
"requestId": "0123434-statement-abc",
"requestTimestamp": "1502632800000"
},
"paymentIntegratorAccountId": "InvisiCashUSA_USD",
"remittanceStatementSummary": {
"statementDate": "1502607600000",
"billingPeriod": {
"startDate": "1502434800000",
"endDate": "1502521199000",
},
"dateDue": "1503212400000",
"currencyCode": "INR",
"totalDueByIntegrator": "1076000000",
}
}
Observa la asignación de totalDueByIntegrator. En esta línea, puedes ver el importe neto que debe el integrador (en micros). Además, la fecha y el tipo de moneda aparecen en este mensaje, y el período de facturación representa 00:00:00.000 y 23:59:59.999 de los días más antiguos y más recientes de la transacción, respectivamente.
Conciliación (remittanceStatementDetails)
Para la conciliación, el integrador llamará a remittanceStatementDetails a fin de obtener la lista de eventos incluidos en remittanceStatementNotification.
Google responde a la solicitud remittanceStatementDetails con una lista paginada de eventos. Se debe llamar a remittanceStatementDetails varias veces si la cantidad total de transacciones es mayor que 1,000. No es necesario realizarlas de forma secuencial y se pueden paralelizar.
Solicitar URL
POST https://billpaynotification.googleapis.com/secure-serving/gsp/v1/remittanceStatementDetails
Cuerpo de la solicitud de muestra
{
"requestHeader": {
"protocolVersion": {
"major": 1,
"minor": 0,
"revision": 0
},
"requestId": "statement_detail_request_139932019",
"requestTimestamp": "1502551332087"
},
"paymentIntegratorAccountId": "InvisiCashUSA_USD",
"statementId": "0123434-statement-abc",
"numberOfEvents": 4
}
A continuación, se muestra un breve fragmento de una respuesta más amplia que describe dos eventos de captura (transacciones).
"captureEvents": [ {
{
"eventRequestId": "bWVyY2hhbnQgdHJhbnNhY3Rpb24gaWQ",
"paymentIntegratorEventId": "ioj32SOIjf23oijSDfoij",
"eventCharge": "700000000",
"eventFee": "-28000000"
},
{
"eventRequestId": "Ggghvh78200PQ3Yrpb",
"paymentIntegratorEventId": "iasdf23dSdfijSDfoij",
"eventCharge": "800000000",
"eventFee": "-32000000"
}
}
Consulta remittanceStatementDetails para obtener más información.
acceptRemittanceStatement y acceptRemittanceStatementWithModifications
Los integradores deben comparar estos eventos con los que registraron. Si alguna transacción no coincide o no se encuentra, comunícate con Google para obtener más detalles. Si todas las transacciones coinciden y la tarifa del proceso no incluye impuestos, llama a acceptRemittanceStatement. Si los impuestos son inclusivos, llama al acceptRemittanceStatementWithModifications.
El método acceptRemittanceStatement se usa cuando no hay impuestos sobre las tarifas.
Si se incluirá un impuesto, llama a acceptRemittanceStatementWithModifications y define la tasa impositiva. Si la tasa impositiva cambia, asegúrate de que esté actualizada. Después de acceptRemittanceStatement con éxito, inicie la transferencia bancaria a la Cuenta de Google.
Solicitar URL para acceptRemittanceStatement
POST https://billpaynotification.googleapis.com/secure-serving/gsp/v1/acceptRemittanceStatement
Cuerpo de la solicitud de muestra
{
"requestHeader": {
"protocolVersion": {
"major": 1,
"minor": 0,
"revision": 0
},
"requestId": "0123434-abc",
"requestTimestamp": "1502545413098"
},
"paymentIntegratorAccountId": "InvisiCashUSA_USD",
"statementId": "0123434-statement-abc"
}
Respuesta de muestra
{
"responseHeader": {
"responseTimestamp": "1519996752221"
}
"acceptRemittanceStatementResultCode": "SUCCESS"
}
Solicitar URL para acceptRemittanceStatementWithModifications
POST https://billpaynotification.googleapis.com/secure-serving/gsp/v1/acceptRemittanceStatementWithModifications
Cuerpo de la solicitud de muestra
{
"requestHeader": {
"protocolVersion": {
"major": 1,
"minor": 0,
"revision": 0
},
"requestId": "0123434-abc",
"requestTimestamp": "1502545413098"
},
"paymentIntegratorAccountId": "InvisiCashUSA_USD",
"statementId": "0123434-statement-abc"
"feeToVatModification": {
"vatToFeeRatioInMicros": "150000"
}
}
Respuesta de muestra
{
"responseHeader": {
"responseTimestamp": "1519996752221"
}
"acceptRemittanceStatementWithModificationsResultCode": "SUCCESS"
}