Oto kilka ważnych przypadków użycia, które warto wziąć pod uwagę, a także wytyczne i interfejsy API niezbędne do wdrożenia formy płatności gotówkowej.
Przypadki użycia
Interfejs Reference Number API ma wiele zastosowań. W tym przewodniku omawiamy 2 przypadki użycia i przeprowadzimy Cię przez proces ich wdrażania.
- Gotówka – użytkownik płaci gotówką w sklepie stacjonarnym.
- VAN – użytkownik przesyła pieniądze na numer konta wirtualnego (VAN).
Gotówka
Użytkownik może kupić coś od Google, płacąc za to gotówką w sklepie stacjonarnym, np. w sklepie osiedlowym. Aby zidentyfikować transakcję, użytkownik wygeneruje numer referencyjny, który zabierze do sklepu w celu dokonania płatności. Dodatkowo Google wyświetla użytkownikowi instrukcje dotyczące tego, jak dokonać zakupu. Najlepiej, gdy tylko użytkownik dokona zakupu, integrator powiadamia Google, aby umożliwić nam dostarczenie produktu.
Osoba kontaktowa w Google poprosi o próbkę typowych instrukcji płatności. Wspólnie z przedstawicielem Google zoptymalizujesz i doprecyzujesz przekaz.
Chcemy zapewnić użytkownikom wygodę korzystania z zamówień, które są dostarczane do klientów w momencie opuszczania sklepu. Google oczekuje, że numer ReferenceNumberPaidNotification dotrze do Google w ciągu 3 minut od dokonania przez klienta płatności za numer referencyjny. Po wysłaniu elementu ReferenceNumberpaidMetric do integratora nie może cofnąć transakcji.
VAN
Użytkownik może zapłacić za produkt, korzystając ze swojego konta bankowego. Google poprosi integratora o numer konta wirtualnego (VAN), pokazując go użytkownikowi oraz instrukcje. Następnie użytkownik skopiuje ten numer i wpisze go w swojej aplikacji bankowej oprócz kwoty przelewu.
Integrator musi sprawdzić, czy przenoszona kwota jest zgodna z kwotą żądania referenceNumberGeneration, a następnie powiadomić Google, że numer referencyjny został opłacony.
Gdy Google otrzyma numer ReferenceNumberPaidNotification, dostarczamy produkt, a integrator nie może cofnąć transakcji.
wysyłanie wiadomości między Twoimi serwerami a serwerami Google;
Podczas wysyłania wiadomości między swoimi serwerami a serwerami Google lub odwrotnie, postępuj zgodnie z tymi wskazówkami.
Prośba przychodząca – DecryptWithVendorPrivateKey(Base64UrlDecode(request))
Odpowiedź wychodząca – Base64UrlEncode(EncryptWithGooglePublicKey(request))
Prośba do Google – Base64UrlEncode(EncryptWithGooglePublicKey(request))
Odpowiedź Google – DecryptWithVendorPrivateKey(Base64UrlDecode(request))
Oto biblioteka PGP i przykład w języku Java, które pokazują obsługę żądań i odpowiedzi.
Postępuj zgodnie z idempotentnym zachowaniem
Idempotentność oznacza, że nie należy próbować ponownie przetworzyć żadnego żądania (np. płatności), które zostało już przetworzone. Zamiast tego należy zgłosić odpowiedź informującą o udanym przetwarzaniu.
Dlaczego to ważne?
Google może ponawiać żądania niektórych żądań, aby upewnić się, że stan po naszej stronie jest taki sam jak po stronie dostawcy. System nie powinien uznawać, że jest to inna transakcja. Dlatego idempotentność jest bardzo ważna. Oznacza to, że integrator nie powinien ponownie przetworzyć czegoś, co zostało już przetworzone prawidłowo. W takim przypadku należy wysłać poprzednią odpowiedź.
Jak wdrożyć idempotentność
Jeśli Google wyśle ponowną próbę, identyfikator żądania będzie taki sam, a treść będzie taka sama, ale sygnatura czasowa będzie inna. Odpowiedz taką samą odpowiedzią jak poprzednio. Jeśli pierwsza odpowiedź to 200 (powodzenie), Google oczekuje tej samej odpowiedzi z inną sygnaturą czasową.
Jeśli poprzednia odpowiedź była błędem (400 lub 500 itp.), prześlij to żądanie jako nowe żądanie i sprawdź je ponownie. Jest to przydatne, jeśli serwer nie działał po raz pierwszy, a ponowienie próby daje szansę na pomyślne przetworzenie żądania.
Więcej informacji znajdziesz w tym szczegółowym przewodniku.
Użyj identyfikatora konta integratora płatności (PIAID)
Integracja z Google może wymagać integracji z różnymi podmiotami gospodarczymi Google. Na przykład Google Play to jeden podmiot, drugi to YouTube, a jeszcze inny Google Ads. Wiąże się to z zastosowaniem różnych kont sprzedawców do reprezentowania każdej z tych konfiguracji.
W przypadku mapowania każdego podmiotu w Google na każde konto sprzedawcy Google dostarcza identyfikatory kont integratora płatności (PIAID). Przykład interfejsu API FOP gotówki znajdziesz w artykule generateReferenceNumber. Oto przykład, w którym używa się tego mapowania.
W przypadku mapowania każdego podmiotu w Google na każde konto sprzedawcy Google dostarcza identyfikatory kont integratora płatności (PIAID). Przykład wykorzystania interfejsu Cash FOP API znajdziesz tutaj: generateReferenceNumber. Oto przykład, w którym używa się tego mapowania.
{
"requestHeader": {
"protocolVersion": {
"major": 1,
"minor": 0,
"revision": 0
},
"requestId": "bWVyY2hhbnQgdHJhbnNhY3Rpb24gaWQ",
"requestTimestamp": "1502220196077"
},
"paymentIntegratorAccountId": "InvisiCashUSA_USD",
"transactionDescription": "Google - Music",
"currencyCode": "USD",
"amount": "2000000"
}
Zwróć uwagę na wyróżnioną część. Dwie wymagane wartości to paymentIntegratorAccountId podany przez osobę kontaktową w Google i Twoje konto sprzedawcy.
Integrator może też mieć różne konta w zależności od obsługiwanego kraju. Może to wynikać z różnych przepisów podatkowych i innych różnic między krajami. W takim przypadku dla każdego kraju może zostać wygenerowany inny identyfikator PIAID.
Interfejsy API do integracji
Poniższe interfejsy API obsługują generowanie numerów referencyjnych i powiadamianie o płatnościach.
Poniższe interfejsy API obsługują płatności i rozliczenia.
- RemittanceStatementNotification
- RemittanceStatementDetails
- AcceptRemittanceStatement/AcceptRemittanceStatement z modyfikacjami,
Aby wygenerować numery referencyjne i uzgodnić je z Google, musisz zintegrować wszystkie powyższe interfejsy API.
Wygeneruj numer referencyjny
Gdy inicjujesz zakup, Google wywołuje metodę generateReferenceNumber. Spodziewamy się w odpowiedzi podać numer referencyjny transakcji lub konta. Oczekiwane opóźnienie wynosi mniej niż 3 sekundy.
W przypadku transakcji gotówkowych numer referencyjny może mieć maksymalnie 12 znaków.
Adres URL: POST https://[your basepath]/v1/generateReferenceNumber
Plik JSON żądania
{
"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"
}
Plik JSON odpowiedzi
{
"responseHeader": {
"responseTimestamp": "1561678947659"
},
"result": "SUCCESS",
"referenceNumber": "38a41c05-ba7b-4040-a909-4331d0b9ce46"
}
Przykładowa wersja Java
`String generateReferenceNumberJson = Utils.decryptAndDecode(encodedEncryptedGenerateReferenceNumberRequest);`
GenerateReferenceNumberRequest request = gson.fromJson(generateReferenceNumberJson, GenerateReferenceNumberRequest.class);
Anuluj numer referencyjny
Google może anulować numer referencyjny i uniemożliwić użytkownikowi wypłacenie za jego pomocą środków. Przykładem może być promocja, która wygasła. Jeśli Twoja prośba zostanie rozpatrzona pozytywnie, musisz upewnić się, że nie można zapłacić numeru referencyjnego.
Jeśli użytkownik już zainicjował proces płatności, na przykład wyszukanie numeru referencyjnego w punkcie sprzedaży, serwer powinien wysłać odpowiedź HTTP 423 i ErrorResponse w treści żądania ze stanem USER_ACTION_IN_PROGRESS.
Adres URL: POST https://[your basepath]/v1/cancelReferenceNumber
Plik JSON żądania
{
"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"
}
Plik JSON odpowiedzi
{
"responseHeader": {
"responseTimestamp": "1561680406459"
},
"result": "SUCCESS"
}
referenceNumberPaidNotification
Po zaakceptowaniu płatności i sfinalizowaniu transakcji Twoja usługa musi powiadomić Google o tym, że transakcja została zrealizowana, i dostarczyć produkt użytkownikowi. Google oczekuje, że po otrzymaniu tego powiadomienia transakcja zostanie sfinalizowana i nie będzie można jej zarezerwować.
Adres URL punktu końcowego referenceNumberPaidNotification:
POST https://billpaynotification.googleapis.com/secure-serving/gsp/v1/referenceNumberPaidNotification/[PIAID]
Plik JSON żądania
{
"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"
}
Plik JSON odpowiedzi
{
"responseHeader": {
"responseTimestamp": "1561748642600"
},
"result": "SUCCESS"
}
Wdrożenie przelewu
Po zintegrowaniu interfejsów API z konkretną formą płatności można przesłać płatność. Przelew działa tak samo we wszystkich formach płatności.
remittanceStatementNotification
Po 2 dniach od dokonania transakcji Google wysyła powiadomienie remittanceStatementNotification z podsumowaniem transakcji zarejestrowanych w danym dniu. Przykładowe powiadomienie wygląda tak dwa dni po transakcji:
POST https://www.integratordomain.com/v1/remittanceStatementNotification
Plik JSON żądania
{
"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",
}
}
Zwróć uwagę na mapowanie totalDueByIntegrator. W tym wierszu widoczna jest kwota netto należna integratora (w mikro). W tej wiadomości pojawi się też data i typ waluty, przy czym okres rozliczeniowy oznacza odpowiednio 00:00:00.000 i 23:59:59, 999 dnia lub daty najwcześniejszej i ostatniej transakcji.
Uzgodnienia (remittanceStatementDetails)
W przypadku uzgodnienia integrator wywołuje metodę remittanceStatementDetails, aby pobrać listę zdarzeń uwzględnionych w powiadomieniu remittanceStatement.
Google odpowiada na żądanie remittanceStatementDetails, dzieląc listę zdarzeń na strony. Element remittanceStatementDetails powinien zostać wywołany kilka razy, jeśli łączna liczba transakcji jest większa niż 1000. Żądania nie muszą być wysyłane po kolei i mogą być równoległe.
Adres URL żądania
POST https://billpaynotification.googleapis.com/secure-serving/gsp/v1/remittanceStatementDetails
Przykładowy tekst żądania
{
"requestHeader": {
"protocolVersion": {
"major": 1,
"minor": 0,
"revision": 0
},
"requestId": "statement_detail_request_139932019",
"requestTimestamp": "1502551332087"
},
"paymentIntegratorAccountId": "InvisiCashUSA_USD",
"statementId": "0123434-statement-abc",
"numberOfEvents": 4
}
Oto krótki fragment większej odpowiedzi opisującej 2 zdarzenia przechwytywania (transakcje).
"captureEvents": [ {
{
"eventRequestId": "bWVyY2hhbnQgdHJhbnNhY3Rpb24gaWQ",
"paymentIntegratorEventId": "ioj32SOIjf23oijSDfoij",
"eventCharge": "700000000",
"eventFee": "-28000000"
},
{
"eventRequestId": "Ggghvh78200PQ3Yrpb",
"paymentIntegratorEventId": "iasdf23dSdfijSDfoij",
"eventCharge": "800000000",
"eventFee": "-32000000"
}
}
Więcej informacji znajdziesz na stronie remittanceStatementDetails.
acceptRemittanceStatement i acceptRemittanceStatementWithModifications
Integrator powinien porównać te zdarzenia ze zdarzeniami, które zarejestrował. Jeśli brakuje transakcji lub nie udało się ich znaleźć, skontaktuj się z Google, aby dokładniej zbadać problem. Jeśli wszystkie transakcje są takie same, a opłata za obsługę nie obejmuje podatków, wywołaj acceptRemittanceStatement. Jeśli podatki są wliczone w cenę, zadzwoń pod numer acceptRemittanceStatementWithModifications.
Metoda acceptRemittanceStatement jest używana w przypadku braku podatków od opłat.
Jeśli chcesz uwzględnić podatek, wywołaj funkcję acceptRemittanceStatementWithModifications i określ stawkę podatku. Jeśli Twoja stawka podatku się zmieni, zaktualizuj te dane. Po udanej transakcji acceptRemittanceStatement zainicjuj przelew bankowy na konto Google.
URL żądania dla: acceptRemittanceStatement
POST https://billpaynotification.googleapis.com/secure-serving/gsp/v1/acceptRemittanceStatement
Przykładowy tekst żądania
{
"requestHeader": {
"protocolVersion": {
"major": 1,
"minor": 0,
"revision": 0
},
"requestId": "0123434-abc",
"requestTimestamp": "1502545413098"
},
"paymentIntegratorAccountId": "InvisiCashUSA_USD",
"statementId": "0123434-statement-abc"
}
Przykładowa odpowiedź
{
"responseHeader": {
"responseTimestamp": "1519996752221"
}
"acceptRemittanceStatementResultCode": "SUCCESS"
}
URL żądania dla: acceptRemittanceStatementWithModifications
POST https://billpaynotification.googleapis.com/secure-serving/gsp/v1/acceptRemittanceStatementWithModifications
Przykładowy tekst żądania
{
"requestHeader": {
"protocolVersion": {
"major": 1,
"minor": 0,
"revision": 0
},
"requestId": "0123434-abc",
"requestTimestamp": "1502545413098"
},
"paymentIntegratorAccountId": "InvisiCashUSA_USD",
"statementId": "0123434-statement-abc"
"feeToVatModification": {
"vatToFeeRatioInMicros": "150000"
}
}
Przykładowa odpowiedź
{
"responseHeader": {
"responseTimestamp": "1519996752221"
}
"acceptRemittanceStatementWithModificationsResultCode": "SUCCESS"
}