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

Confira alguns casos de uso importantes a serem considerados, assim 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 orientará você na 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 isso com dinheiro em um local físico, como uma loja de conveniência. Para identificar a transação, o usuário gerará um número de referência para levar até a loja para pagar. Além disso, o Google exibirá instruções para o usuário sobre como concluir a compra. O ideal é que o integrador notifique o Google assim que o usuário concluir a compra para que ele possa entregar o produto.

Seu ponto de contato no Google solicitará uma amostra das suas instruções típicas 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 o recebimento do ReferenceNumberPaidNotification no Google em até três minutos após o cliente pagar o número de referência. Depois que o ReferNumberpaidNotification é enviado, a transação não pode ser revertida pelo integrador.

VAN

Um usuário pode pagar por um produto com sua conta bancária. O Google vai solicitar um número de conta virtual do integrador, apresentando o número e as instruções ao usuário. O usuário copiará o número e o inserirá 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, em seguida, notificar o Google sobre o pagamento do número de referência.

Depois que o Google receber o ReferenceNumberPaidNotification, ele vai 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 processar novamente uma solicitação (como um pagamento) que já tenha sido processada. Em vez disso, a resposta do processamento bem-sucedido deve ser informada.

Por que isso é importante

O Google pode repetir algumas solicitações para garantir que nosso estado seja o mesmo do fornecedor. Seu sistema não deve pensar que se trata de 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 a idempotência

Se o Google enviar uma nova tentativa, o ID da solicitação e o conteúdo serão iguais, mas o carimbo de data/hora será diferente. Responda com a mesma resposta enviada anteriormente. Se sua primeira resposta for 200 (Sucesso), o Google vai esperar a mesma resposta com um carimbo de data/hora diferente.

Se sua resposta anterior foi um erro (400, 500 etc.), você deve processar essa solicitação como uma nova solicitação e verificá-la novamente. Isso é útil se o servidor estava fora do ar pela primeira vez e tentar novamente dá à solicitação outra chance de ser processada com êxito.

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 integração com as diferentes entidades comerciais do Google. Por exemplo, o Google Play é uma entidade, outra é o YouTube e outra é o Google Ads. Elas envolverão diferentes contas do comerciante para representar cada uma dessas configurações.

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

Para fazer o mapeamento de cada entidade do Google para cada conta do comerciante, o Google fornece IDs da conta do integrador de pagamentos (PIAIDs, na sigla em inglês). Para ver um exemplo usando a API FOP Cash, consulte generateReferenceNumber. Aqui está 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 os paymentIntegratorAccountId informados pelo seu ponto de contato no Google e sua conta de comerciante.

O integrador também pode ter contas diferentes de acordo com o país atendido. Isso pode ocorrer devido a diversas leis fiscais e a outras diferenças de um país para outro. Nesse caso, outro PIAID pode ser gerado para cada país.

APIs a serem integradas

As APIs a seguir processam 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 liquidações.

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

Você precisará integrar todas as APIs acima para gerar números de referência e fechar com 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 é < 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 permite a 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. Depois de responder com sucesso a essa solicitação, 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 busca de número de referência no ponto de venda, o servidor responderá com uma resposta HTTP 423 e ErrorResponse no corpo da solicitação com o status 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 de que a transação foi concluída e entregar o produto ao usuário. Depois que essa notificação é recebida, o Google espera que a transação seja finalizada e não poderá 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 à sua FOP específica, você estará pronto para a remessa. A remessa funciona da mesma forma em todos os FOPs.

remittanceStatementNotification

Dois dias após uma transação, o Google vai enviar uma remittanceStatementNotification com um resumo das transações registradas no dia. Um exemplo de notificação é semelhante a este, 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. Nessa linha, é possível ver o valor líquido que o integrador deve (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 do(s) dia(s) de transação mais cedo e mais recente, respectivamente.

Reconciliação (remittanceStatementDetails)

Para reconciliação, o integrador vai chamar remittanceStatementDetails para receber a lista de eventos incluídos na 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 sequencialmente e podem ser paralelas.

URL de solicitação

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
}

Este é 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 que foram registrados. Se alguma transação não corresponder ou estiver faltando, 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 estiverem incluídos, chame acceptRemittanceStatementWithModifications.

Observação: se uma transação ocorrer perto da meia-noite, ela poderá ser incluída em uma declaração de remessa diferente. Isso ocorre porque o Google usa o carimbo de data/hora da contabilidade do Google 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 um tributo for incluído, chame acceptRemittanceStatementWithModifications e defina a alíquota. Se a taxa fiscal mudar, verifique se ela está atualizada. Depois de uma acceptRemittanceStatement bem-sucedida, inicie a transferência bancária para a Conta do Google.

Solicitar URL para acceptRemittanceStatement

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

Corpo da solicitação de amostra

{
  "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"
}