Estos son algunos casos de uso importantes que debes considerar, así como los lineamientos y las APIs que necesitas para implementar tu FOP en efectivo.
Casos de uso
La API de número de referencia se puede usar de diferentes maneras. En esta guía, se analizan 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, los usuarios deben pagarlo en efectivo en una ubicación física, como un minimercado. Para identificar la transacción, el usuario generará un número de referencia para llevar a la tienda y pagar. Además, Google le mostrará instrucciones al usuario para completar la compra. Idealmente, tan pronto como el usuario complete la compra, el integrador le notifique a Google para que pueda entregar el producto.
Su punto de contacto de Google le solicitará una muestra de sus instrucciones de pago habituales. 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 que Google reciba la ReferenceNumberPaidNotification en un plazo de tres minutos a partir del momento en que el cliente pagó el número de referencia. Una vez que se envía ReferenceNumberPaidNotification, el integrador no puede revertir la transacción.
VAN
Un usuario puede pagar un bien con su cuenta bancaria. Google le solicitará un número de cuenta virtual al integrador y le 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 a 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.
Sigue el comportamiento idempotente
La idempotencia significa que no debe intentar volver a procesar una solicitud (como un pago) que ya se procesó 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. Tu 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 envía un reintento, el ID de la solicitud será el mismo y el contenido será el mismo, pero la marca de tiempo será diferente. Usa la misma respuesta que enviaste antes. Si tu primera respuesta fue 200 (Listo), Google esperará 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 tu servidor no funciona la primera vez y, si vuelves a intentarlo, la solicitud tiene otra oportunidad para procesarse correctamente.
Para obtener más información, consulta esta guía detallada.
Usa el ID de cuenta de integrador 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, otra es YouTube y la otra es Google Ads. En ellas, se incluirán diferentes cuentas de comerciante para representar cada uno de estos parámetros de configuración.
Para la asignación de cada entidad en Google a cada cuenta de comerciante, Google proporciona IDs de cuentas de integradores 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 en Google a cada cuenta de comerciante, Google proporciona IDs de cuentas de integradores de pagos (PIAID). Para ver un ejemplo con la API de FOP de Cash, 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 que se necesitan en este caso son el paymentIntegratorAccountId que proporcionó tu punto de contacto en Google y tu cuenta del comerciante.
El integrador también puede tener cuentas diferentes según el país en el que se presta el servicio. Esto puede deberse a diversas leyes fiscales y otras diferencias de un país a otro. En este caso, se puede generar otro PIAID para cada país.
APIs para integrar
Las siguientes APIs controlan la generación de números de referencia y la notificación de pago.
Las siguientes APIs controlan las remesas y las liquidaciones.
- RemittanceStatementNotification
- RemittanceStatementDetails
- AcceptRemittanceStatement o AcceptRemittanceStatement con modificaciones
Tendrás que integrar todas las APIs anteriores para generar números de referencia y acordar 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 menor que 3 segundos.
Para las transacciones en efectivo, el número de referencia puede tener hasta 12 caracteres.
URL: POST https://[your basepath]/v1/generateReferenceNumber
JSON de la solicitud
{
"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"
}
JSON de la respuesta
{
"responseHeader": {
"responseTimestamp": "1561678947659"
},
"result": "SUCCESS",
"referenceNumber": "38a41c05-ba7b-4040-a909-4331d0b9ce46"
}
Java de muestra
`String generateReferenceNumberJson = Utils.decryptAndDecode(encodedEncryptedGenerateReferenceNumberRequest);`
GenerateReferenceNumberRequest request = gson.fromJson(generateReferenceNumberJson, GenerateReferenceNumberRequest.class);
Cancelar número de referencia
Google puede optar por 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 haya respondido correctamente a esta solicitud, debe asegurarse de que no se pueda pagar el número de referencia.
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 debe 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
JSON de la solicitud
{
"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"
}
JSON de la respuesta
{
"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 recibe esta notificación, se espera que la transacción finalice y no se pueda reservar.
URL del extremo de referenceNumberPaidNotification:
POST https://billpaynotification.googleapis.com/secure-serving/gsp/v1/referenceNumberPaidNotification/[PIAID]
JSON de la solicitud
{
"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"
}
JSON de la respuesta
{
"responseHeader": {
"responseTimestamp": "1561748642600"
},
"result": "SUCCESS"
}
Implementar la remesa
Una vez que hayas integrado las APIs para tu forma de pago en particular, estarás listo para las remesas. Las remesas funcionan de la misma manera en todas las formas de pago.
remittanceStatementNotification
Dos días después de la transacción, Google enviará una notificación remittanceStatementNotification con un resumen de las transacciones que registró ese día. Dos días después de la transacción, una notificación de muestra se ve de la siguiente manera:
POST https://www.integratordomain.com/v1/remittanceStatementNotification
JSON de la solicitud
{
"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 de la transacción más antiguos y más recientes, respectivamente.
Conciliación (remittanceStatementDetails)
Para la conciliación, el integrador llamará a remittanceStatementDetails para obtener la lista de eventos incluidos en remittanceStatementNotification.
Google responde a la solicitud de remittanceStatementDetails con una lista paginada de eventos. Se debe llamar a remittanceStatementDetails varias veces si la cantidad total de transacciones es superior a 1,000. Las solicitudes no tienen que realizarse 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 fragmento breve de una respuesta más amplia, en el que se describen 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 hay transacciones que no coinciden o faltan, comuníquese con Google para que realice una investigación más detallada. Si todas las transacciones coinciden y la tarifa del proceso no incluye impuestos, llama al acceptRemittanceStatement. Si los impuestos lo incluyen, llama a acceptRemittanceStatementWithModifications.
Se usa el método acceptRemittanceStatement cuando no hay impuestos sobre las tarifas.
Si se debe incluir un impuesto, llama a acceptRemittanceStatementWithModifications y define la tasa impositiva. Si cambia la tasa impositiva, asegúrate de actualizarla. Después de que se realice correctamente la acceptRemittanceStatement, inicia la transferencia bancaria a la Cuenta de Google.
URL de solicitud 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"
}
URL de solicitud 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"
}