Guia Cash FOP (API de número de referência)

Aqui estão alguns casos de uso importantes a serem considerados, bem como as diretrizes e APIs necessárias para implementar a forma de pagamento em dinheiro.

Casos de uso

A API Reference Number pode ser usada de várias formas. Este guia discutirá dois casos de uso e explicará a implementação deles.

• Dinheiro: o usuário paga em dinheiro em uma loja física.
• VAN: o usuário transfere dinheiro para um número de conta virtual.

Dinheiro

Um usuário pode comprar algo do Google pagando por ele em dinheiro em um local físico, como uma loja de conveniência. Para identificar a transação, o usuário vai gerar um número de referência para pagar na loja. Além disso, o Google vai mostrar instruções para o usuário sobre como concluir a compra. O ideal é que, assim que o usuário conclua a compra, o integrador notificará o Google para que o Google possa entregar o produto.

Seu ponto de contato no Google solicitará uma amostra das suas instruções normais de pagamento. Você vai trabalhar com seu contato do Google para otimizar e refinar a mensagem.

A experiência do usuário que o Google quer oferecer é que o pedido do cliente seja entregue assim que ele sai da loja. O Google espera que o ReferenceNumberPaidNotification seja recebido no Google dentro de três minutos após o cliente pagar o número de referência. Depois que o ReferenceNumberPagoNotification é enviado, a transação não pode ser revertida pelo integrador.

VAN

Um usuário pode pagar por um bem com a conta bancária. O Google vai solicitar um número de conta virtual ao integrador, apresentando o número e as instruções ao usuário. O usuário copia o número e o insere no aplicativo bancário, além do valor a ser transferido.

O integrador precisa verificar se o valor transferido corresponde ao valor da solicitação referenceNumberGeneration e notificar o Google que o número de referência foi pago.

Depois que o Google receber a ReferenceNumberPaidNotification, ele enviará o produto, e a transação não poderá ser revertida pelo integrador.

Enviar mensagens entre seus servidores e os servidores do Google

Quando enviar mensagens entre seus servidores e os do Google, ou vice-versa, faça isso de acordo com estas diretrizes.

Solicitação recebida: DecryptWithVendorPrivateKey(Base64UrlDecode(request))

Resposta enviada - Base64UrlEncode(EncryptWithGooglePublicKey(request))

Solicitação do Google - Base64UrlEncode(EncryptWithGooglePublicKey(request))

Resposta do Google - DecryptWithVendorPrivateKey(Base64UrlDecode(request))

Confira uma biblioteca e um exemplo de PGP em Java que mostram o processamento de solicitações e respostas.

Observação :verifique se os servidores usam HTTPS para todas as mensagens e transações.

Seguir o comportamento idempotente

Idempotência significa que você não deve tentar reprocessar qualquer solicitação (como um pagamento) que já foi processada. A resposta de processamento bem-sucedido deve ser informada.

Por que isso é importante

O Google pode repetir algumas solicitações para garantir que o estado do nosso lado seja o mesmo do fornecedor. Seu sistema não pode pensar que essa é outra transação. Portanto, a idempotência é muito importante. Isso significa que um integrador não deve reprocessar algo que já foi processado com sucesso. Nesse caso, a resposta anterior deve ser enviada.

Como implementar idempotência

Se o Google enviar uma nova tentativa, o ID da solicitação será o mesmo, e o conteúdo, mas o carimbo de data/hora será diferente. Use a mesma resposta que você enviou anteriormente. Se sua primeira resposta fosse 200 (sucesso), o Google esperaria a mesma resposta com um carimbo de data/hora diferente.

Se a resposta anterior foi um erro (400, 500 etc.), processe essa solicitação como uma nova solicitação, verificando novamente. Isso é útil se o servidor estava inativo na primeira vez, e uma nova tentativa dá à solicitação mais uma chance de ser processada.

Para saber mais, consulte este guia detalhado.

Usar o ID da conta do integrador de pagamentos (PIAID, na sigla em inglês)

As integrações com o Google podem exigir a integração com diferentes entidades comerciais do Google. Por exemplo, o Google Play é uma entidade, o YouTube e o Google Ads, o outro. Isso envolve diferentes contas de comerciantes para representar cada uma dessas configurações.

Para o mapeamento de cada entidade no Google para cada conta do comerciante, o Google fornece IDs de conta do integrador de pagamentos (PIAIDs, na sigla em inglês). Para um exemplo da API FOP em dinheiro, consulte generateReferenceNumber. Veja um exemplo que usa esse mapeamento.

Para o mapeamento de cada entidade no Google para cada conta do comerciante, o Google fornece IDs de conta do integrador de pagamentos (PIAIDs, na sigla em inglês). Para um exemplo com a API FOP em dinheiro, consulte generateReferenceNumber. Veja um exemplo que usa esse mapeamento.

{
  "requestHeader": {
    "protocolVersion": {
      "major": 1,
      "minor": 0,
      "revision": 0
    },
    "requestId": "bWVyY2hhbnQgdHJhbnNhY3Rpb24gaWQ",
    "requestTimestamp": "1502220196077"
  },
  "paymentIntegratorAccountId": "InvisiCashUSA_USD",
  "transactionDescription": "Google - Music",
  "currencyCode": "USD",
  "amount": "2000000"
}

Observe a parte destacada. Os dois valores necessários aqui são o paymentIntegratorAccountId fornecido pelo seu ponto de contato no Google e sua conta do comerciante.

O integrador também pode ter contas diferentes de acordo com cada país atendido. Isso pode acontecer por causa de várias leis fiscais e de outras diferenças de um país para outro. Nesse caso, outro PIAID pode ser gerado para cada país.

APIs para integrar

As APIs a seguir lidam com a geração de números de referência e a notificação de pagamento.

• GenerateReferenceNumber
• CancelReferenceNumber
• ReferenceNumberPaidNotification

As APIs a seguir lidam com remessas e quitações.

• RemittanceStatementNotification
• RemittanceStatementDetails
• AcceptRemittanceStatement/AcceptRemittanceStatement com modificações

Você vai precisar integrar todas as APIs acima para gerar números de referência e aceitar o Google.

Gerar número de referência

O Google chama GenerateReferenceNumber quando você inicia uma compra. Esperamos que você responda com um número de referência que identifica a transação ou a conta. A latência esperada é de < 3 segundos.

Para transações em dinheiro, o número de referência pode ter até 12 caracteres.

Observação :no momento, o Google não oferece suporte à reciclagem de números de referência. Os números precisam ser sempre exclusivos.

URL: POST https://[your basepath]/v1/generateReferenceNumber

Solicitação 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"
}

JSON de resposta

{
  "responseHeader": {
    "responseTimestamp": "1561678947659"
  },
  "result": "SUCCESS",
  "referenceNumber": "38a41c05-ba7b-4040-a909-4331d0b9ce46"
}

Exemplo de Java

`String generateReferenceNumberJson = Utils.decryptAndDecode(encodedEncryptedGenerateReferenceNumberRequest);`

GenerateReferenceNumberRequest request = gson.fromJson(generateReferenceNumberJson, GenerateReferenceNumberRequest.class);

Cancelar número de referência

O Google pode cancelar um número de referência e impedir que ele seja pago pelo usuário. Um exemplo de caso de uso é uma promoção que expirou. Após responder a essa solicitação com sucesso, verifique se o número de referência não pode ser pago.

Se o usuário já tiver iniciado o processo de pagamento, por exemplo, uma pesquisa de número de referência do ponto de venda, seu servidor responderá com uma resposta HTTP 423 e ErrorResponse no corpo da solicitação com um status de USER_ACTION_IN_PROGRESS.

URL: POST https://[your basepath]/v1/cancelReferenceNumber

Solicitação 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"
}

JSON de resposta

{
  "responseHeader": {
    "responseTimestamp": "1561680406459"
  },
  "result": "SUCCESS"
}

referenceNumberPaidNotification

Depois que o pagamento for aceito e a transação for concluída, seu serviço precisará notificar o Google que a transação foi concluída e vai entregar o produto ao usuário. Após receber a notificação, o Google espera que a transação esteja finalizada e não pode ser reservada.

URL do endpoint referenceNumberPaidNotification:

POST https://billpaynotification.googleapis.com/secure-serving/gsp/v1/referenceNumberPaidNotification/[PIAID]

Solicitação 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"
}

JSON de resposta

{
  "responseHeader": {
    "responseTimestamp": "1561748642600"
  },
  "result": "SUCCESS"
}

Implementar remessa

Depois de integrar as APIs para sua FOP específica, você poderá enviar remessas. A remessa funciona da mesma maneira em todas as FOPs.

remittanceStatementNotification

Dois dias após uma transação, o Google enviará uma remittanceStatementNotification com um resumo das transações registradas pelo Google naquele dia. Um exemplo de notificação tem esta aparência, dois dias após uma transação:

POST https://www.integratordomain.com/v1/remittanceStatementNotification

Solicitação 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",
  }
}

Observe o mapeamento totalDueByIntegrator. Nesta linha, é possível ver o valor líquido devido do integrador (em micros). Além disso, a data e o tipo de moeda aparecem nessa mensagem, com o período de faturamento representando 00:00:00.000 e 23:59:59.999 dos dias de transação mais antigos e mais recentes, respectivamente.

Reconciliação (remittanceStatementDetails)

Para a reconciliação, o integrador vai chamar remittanceStatementDetails para conferir a lista de eventos incluídos em remittanceStatementNotification.

O Google responde à solicitação remittanceStatementDetails com uma lista paginada de eventos. remittanceStatementDetails precisará ser chamado várias vezes se o número total de transações for maior que 1.000. As solicitações não precisam ser feitas em sequência e podem ser carregadas em paralelo.

Request URL

POST https://billpaynotification.googleapis.com/secure-serving/gsp/v1/remittanceStatementDetails

Exemplo de corpo da solicitação

{
  "requestHeader": {
    "protocolVersion": {
      "major": 1,
      "minor": 0,
      "revision": 0
    },
    "requestId": "statement_detail_request_139932019",
    "requestTimestamp": "1502551332087"
  },
  "paymentIntegratorAccountId": "InvisiCashUSA_USD",
  "statementId": "0123434-statement-abc",
  "numberOfEvents": 4
}

Veja um pequeno snippet de uma resposta maior que descreve dois eventos de captura (transações).

"captureEvents": [ {
    {
      "eventRequestId": "bWVyY2hhbnQgdHJhbnNhY3Rpb24gaWQ",
      "paymentIntegratorEventId": "ioj32SOIjf23oijSDfoij",
      "eventCharge": "700000000",
      "eventFee": "-28000000"
    },
    {
      "eventRequestId": "Ggghvh78200PQ3Yrpb",
      "paymentIntegratorEventId": "iasdf23dSdfijSDfoij",
      "eventCharge": "800000000",
      "eventFee": "-32000000"
    }
  }

Consulte remittanceStatementDetails para saber mais.

acceptRemittanceStatement e acceptRemittanceStatementWithModifications

Os integradores precisam comparar esses eventos com os eventos que registraram. Se alguma transação não for correspondente ou estiver ausente, entre em contato com o Google para uma investigação mais detalhada. Se todas as transações forem correspondentes e a taxa do processo não incluir tributos, chame acceptRemittanceStatement. Se os tributos forem incluídos, chame acceptRemittanceStatementWithModifications.

Observação :se uma transação ocorrer perto da meia-noite, ela poderá ser incluída em outro extrato. Isso ocorre porque o Google usa o carimbo de data/hora da contabilidade em vez do carimbo de data/hora da solicitação ou da resposta.

O método acceptRemittanceStatement é usado quando não há tributos sobre as taxas.

Se for necessário incluir um tributo, chame acceptRemittanceStatementWithModifications e defina a alíquota. Se a alíquota mudar, confira se ela está atualizada. Após acceptRemittanceStatement, inicie sua transferência bancária para a Conta do Google.

URL da solicitação para acceptRemittanceStatement

POST https://billpaynotification.googleapis.com/secure-serving/gsp/v1/acceptRemittanceStatement

Exemplo de corpo da solicitação

{
  "requestHeader": {
    "protocolVersion": {
      "major": 1,
      "minor": 0,
      "revision": 0
    },
    "requestId": "0123434-abc",
    "requestTimestamp": "1502545413098"
  },
  "paymentIntegratorAccountId": "InvisiCashUSA_USD",
  "statementId": "0123434-statement-abc"
}

Exemplo de resposta

{
  "responseHeader": {
    "responseTimestamp": "1519996752221"
  }
  "acceptRemittanceStatementResultCode": "SUCCESS"
}

URL da solicitação para acceptRemittanceStatementWithModifications

POST https://billpaynotification.googleapis.com/secure-serving/gsp/v1/acceptRemittanceStatementWithModifications

Exemplo de corpo da solicitação

{
  "requestHeader": {
    "protocolVersion": {
      "major": 1,
      "minor": 0,
      "revision": 0
    },
    "requestId": "0123434-abc",
    "requestTimestamp": "1502545413098"
  },
  "paymentIntegratorAccountId": "InvisiCashUSA_USD",
  "statementId": "0123434-statement-abc"
  "feeToVatModification": {
    "vatToFeeRatioInMicros": "150000"
  }
}

Exemplo de resposta

{
  "responseHeader": {
    "responseTimestamp": "1519996752221"
  }
  "acceptRemittanceStatementWithModificationsResultCode": "SUCCESS"
}