Omówienie
Płatności standardowe Google obsługują formy płatności bazujące na gotówce, takie jak zakupy w sklepach ogólnospożywczych (np. w 7-Eleven). Ogólnie rzecz biorąc, użytkownik, który chce zapłacić za towary, generuje numer referencyjny za pomocą integratora płatności. Użytkownik zabiera ten numer referencyjny do sklepu osiedlowego, kiosku lub banku i płaci ten numer referencyjny.
|
|
|
Pojęcia i terminologia
Symbole i Konwencje
Słowa kluczowe „MUSI”, „NIE MOŻE”, „WYMAGANE”, „SHALL”, „NIE”, „POWINNO”, „NIE POWINNO”, „ZALECANE”, „MAJ”, i „OPCJONALNY” w tych dokumentach należy interpretować w sposób opisany w RFC 2119.
Sygnatury czasowe
Wszystkie sygnatury czasowe są podawane w milisekundach od początku epoki uniksowej (1 stycznia 1970 r.) w czasie UTC.
Na przykład:
- 23 kwietnia 2019 r. o 20:23:25 GMT = 1556051005000 milisekund
- 16 sierpnia 2018 roku, 12:28:35 GMT = 1534422515000 milisekund
Kwoty
Wartości pieniężne w tym interfejsie API mają format „micros”, standardem w Google. Mikro to format oparty na liczbach całkowitych o stałej dokładności. Aby podać wartość pieniężną w mikro, pomnóż standardową wartość waluty przez 1 000 000.
Na przykład:
- 1,23 USD = 1230 000 mikroUSD
- 0,01 USD = 10 000 mikroUSD
Idempotentność
Wszystkie wywołania metod w tym interfejsie API muszą mieć działanie idempotentne. Google będzie sporadycznie ponawiać prośby, aby mieć pewność, że transakcje są w tym samym stanie po obu stronach. Integrator nie powinien próbować ponownie przetworzyć żadnego z żądań, które zostały już przetworzone. Zamiast tego należy zgłosić odpowiedź dotyczącą udanego przetwarzania. Wszystkie metody mają wspólny element RequestHeader, który zawiera requestId. Ten identyfikator żądania jest kluczem idempotentności we wszystkich wywołaniach.
Odpowiedź, która nie jest terminalem (błąd HTTP 200), nie może być przetwarzana idempotentnie. Zatem żądanie, które wcześniej uzyskało kod 400 (złe żądanie lub nieuzasadniony warunek wstępny), po ponownym wywołaniu nie może idempotentnie zwracać 400, dlatego musi zostać ponownie ocenione. Podczas ponownej oceny może on zwrócić błąd 400 lub zostać prawidłowo przetworzony.
Więcej informacji na temat idempotentności znajdziesz w tym szczegółowym przewodniku.
Integrator
Firma, która w swojej działalności korzysta z platformy płatniczej Google. Może to być firma wewnętrzna, np. YouTube lub AdWords. Może to być też zewnętrzna firma, która chce zintegrować swoją usługę z ekosystemem Google.
forma płatności
Forma płatności. To bardziej ogólne niż brzmienie instrumentu. Karty Visa, Mastercard i PayPal to tylko formy płatności.
Instrument
Konkretne wystąpienie formy płatności przez konkretnego klienta. Może to być na przykład karta kredytowa użytkownika lub jego konto PayPal. Tokenizowana forma płatności dla konkretnego klienta również jest instrumentem, ponieważ jest formą płatności bezpiecznie przechowywaną w naszym systemie dla tego klienta.
Token
Reprezentacja w systemie Google formy płatności użytkownika. Zawiera on wszystkie informacje potrzebne do dokonania zakupu, więc token jest też instrumentem. Może to obejmować numer konta użytkownika u integratora.
Przepływy kluczy
Google tworzy i opłaca te numery referencyjne, korzystając z 2 procesów:
- Generowanie przepływu numerów referencyjnych.
- Przepływ numeru referencyjnego płatności.
Później uzgodnienia i rozliczenie wynikające z zakupów są obsługiwane w ramach procesu płatności.
Poniższy diagram przedstawia każdy z tych przepływów.
Omówienie formy płatności gotówkowej
Pierwsze 2 procesy zostały szczegółowo opisane w dalszej części tego artykułu. Więcej informacji o tym procesie znajdziesz na stronie Proces przelewów.
Wygeneruj numer referencyjny
Celem procesu generowania numeru referencyjnego jest utworzenie i wymiana identyfikatora (numeru referencyjnego), który zarówno Google, jak i integrator mogą wykorzystać do identyfikacji zakupu. Użytkownik może użyć tego numeru referencyjnego w sklepie osiedlowym, kiosku lub banku, aby sfinalizować zakup. Ten identyfikator jest generowany przez integratora na żądanie Google przez wywołanie metody generateReferenceNumber. Żądanie wygenerowania numeru referencyjnego zawiera kwotę i opis transakcji.
Poniższy diagram przedstawia sposób generowania numeru referencyjnego i przesyłania go do klienta wraz z instrukcjami.
Wygeneruj przepływ numerów referencyjnych
Oto lista obiektów i ich reprezentacji:
- Użytkownik: osoba, która chce zapłacić za coś przy użyciu tej formy płatności.
- Interfejs Google: to interfejs, w którym użytkownik dokonuje zakupu. Możesz to zrobić w przeglądarce lub aplikacji.
- Serwer Google: serwer backendu Google, który żąda wygenerowania numeru referencyjnego i tworzy instrukcje płatności dla użytkownika.
- Serwer integratora płatności: serwer backendu integratora płatności, który śledzi szczegóły płatności i generuje numer referencyjny.
Proces ten rozpoczyna się od użytkownika, który chce użyć danej formy płatności.
- Użytkownik uzyskuje dostęp do interfejsu Google, który wysyła żądanie podania numeru referencyjnego.
- Interfejs Google wysyła do serwera Google komunikat, że potrzebuje numeru referencyjnego (
getReferenceNumber). - Serwer Google prosi serwer integratora płatności o wygenerowanie numeru referencyjnego (
generateReferenceNumber). - Serwer integratora płatności generuje i wysyła numer referencyjny do serwera Google.
- Serwer Google utworzy instrukcje dotyczące płatności wraz z numerem referencyjnym. Następnie wysyła te informacje do interfejsu Google.
- Interfejs Google wysyła te instrukcje oraz numer referencyjny do Użytkownika.
Uwagi dotyczące numerów referencyjnych
Numery referencyjne można opłacać tylko raz i można je anulować, wykonując operację anulowania numeru referencyjnego. Numery referencyjne muszą zawierać znaki alfanumeryczne i obsługiwać wiele formatów wyświetlania.
Oprócz wyświetlania numeru referencyjnego interfejs użytkownika Google mogą opcjonalnie przedstawiać numer referencyjny w formacie kodu 128 (kod kreskowy). Na żądanie mogą być też obsługiwane inne formaty kodów kreskowych.
Numer referencyjny płatności
Użytkownik użyje tego numeru referencyjnego w sklepie osiedlowym, kiosku lub banku, aby zidentyfikować zakup, za który chce zapłacić. Integrator powinien poprosić użytkownika o potwierdzenie zakupu przez wyświetlenie kwoty, daty i opisu transakcji przed dokonaniem płatności.
Gdy użytkownik zdecyduje się zapłacić, musi zapłacić w całości i tylko raz. Ten interfejs API nie obsługuje płatności powyżej ani niedostatecznej kwoty w ramach pojedynczego numeru referencyjnego. Wielokrotne płatności na jeden numer referencyjny również nie są obsługiwane.
Gdy użytkownik dokona płatności, integrator musi niezwłocznie powiadomić Google, że ten numer referencyjny został zapłacony za pomocą metody referenceNumberPaidNotification. Integrator, który wywołuje tę metodę w ciągu kilku sekund od dokonania płatności przez użytkownika, umożliwia mu szybkie odbiór towarów. Można je dodać do kolejki, jeśli sieć nie działa.
Po dokonaniu płatności numer referencyjny i kwota pojawią się na wyciągu wysłanym T+2 dni.
Oto schemat ilustrujący płatność za numer referencyjny.
Przepływ numeru referencyjnego płatności
Obiekty na diagramie reprezentują te elementy:
- Użytkownik: osoba, która chce zapłacić za coś przy użyciu tej formy płatności.
- Sklep osiedlowy: lokalizacja, w której użytkownik dokonuje płatności za pomocą numeru referencyjnego i podanych instrukcji, np. sklep osiedlowy.
- Serwer integratora płatności: serwer backendu integratora płatności, który przechowuje szczegóły płatności.
- Serwer Google: serwer backendu Google, który żąda wygenerowania numeru referencyjnego i tworzy instrukcje płatności dla użytkownika.
Proces ten rozpoczyna się w momencie, gdy użytkownik odwiedza sklep osiedlowy, aby dokonać płatności zgodnie z udzielonymi mu instrukcjami.
- Użytkownik udaje się do lokalnego sklepu, aby dokonać płatności.
- Po zakończeniu transakcji sklep powiadamia o tym integratora płatności.
- Serwer integratora płatności wysyła komunikat o powodzeniu do lokalnego sklepu.
- Sklep osiedlowy zaświadcza, że transakcja zakończyła się sukcesem dla Użytkownika, a towar zostanie mu wkrótce dostarczony.
- Serwer integratora płatności wysyła na serwer Google wiadomość z informacją o zapłaceniu numeru referencyjnego (
referenceNumberPaidNotification). Ten krok nie może blokować kroku 4. - Serwer Google odpowiada z komunikatem o powodzeniu na serwerze integratora płatności.
Anuluj numer referencyjny
Google może anulować numery referencyjne. Jeśli Google anuluje numer referencyjny, wywołana jest metoda cancelReferenceNumber. Po pomyślnym oddaniu połączenia nie można zapłacić za ten numer referencyjny, a integrator musi odmówić zapłaty za ten numer. Po udanym wywołaniu wszystkie kolejne wywołania referenceNumberPaidNotification będą kończyć się niepowodzeniem.
Jeśli proces płatności już się rozpoczął, na przykład użytkownik wpisał swój numer referencyjny w kiosku, ale jeszcze nie zapłacił, integrator powinien zwrócić kod odpowiedzi HTTP 423 z komunikatem ErrorResponse zawierającym USER_ACTION_IN_PROGRESS.
Dalej: Proces przelewu