Cykl życia transakcji płatności

Dowiedz się, jak sprzedawcy integrują aplikacje płatnicze i jak działają transakcje płatnicze za pomocą interfejsu Payment Request API.

Eiji Kitamura

Milica Mihajlija

Interfejsy API płatności internetowych to dedykowane funkcje płatności wbudowane po raz pierwszy w przeglądarce. Dzięki płatnościom internetowym integracja sprzedawcy z aplikacjami do płatności staje się prostsza, a wrażenia klientów płynniejsze i bezpieczniejsze.

Aby dowiedzieć się więcej o korzyściach płynących z użycia płatności internetowych, przeczytaj artykuł Wzmocnienie aplikacji do płatności za pomocą płatności internetowych.

Z tego artykułu dowiesz się, jak wygląda transakcja płatności w witrynie sprzedawcy, oraz jak działa integracja aplikacji do płatności.

Proces składa się z 6 etapów:

1. Sprzedawca inicjuje transakcję płatniczą.
2. Sprzedawca wyświetla przycisk płatności.

3. Klient naciska przycisk płatności.

   

4. Przeglądarka uruchamia aplikację płatniczą.

   

5. Jeśli klient zmieni jakiekolwiek szczegóły (np. opcje dostawy lub adres), sprzedawca zaktualizuje szczegóły transakcji, aby odzwierciedlić tę zmianę.

   

6. Gdy klient potwierdzi zakup, sprzedawca zweryfikuje płatność i dokończy transakcję.

   

Krok 1. Sprzedawca inicjuje transakcję płatniczą

Gdy klient zdecyduje się na zakup, sprzedawca inicjuje transakcję płatniczą, tworząc obiekt PaymentRequest. Ten obiekt zawiera ważne informacje o transakcji:

• akceptowane formy płatności i dane potrzebne do przetworzenia transakcji;
• szczegóły, takie jak łączna cena (wymagane) i informacje o produktach;
• Opcje, w których sprzedawcy mogą poprosić o informacje o dostawie, takie jak adres dostawy i opcja dostawy.
• Sprzedawcy mogą też poprosić o adres rozliczeniowy, imię i nazwisko płatnika, adres e-mail oraz numer telefonu.
• Sprzedawcy mogą też dodać opcjonalny typ dostawy (shipping, delivery lub pickup) w PaymentRequest. Aplikacja płatnicza może to wykorzystać jako wskazówkę, by wyświetlać prawidłowe etykiety w interfejsie.

const request = new PaymentRequest([{
  supportedMethods: 'https://bobpay.xyz/pay',
  data: {
    transactionId: '****'
  }
}], {
  displayItems: [{
    label: 'Anvil L/S Crew Neck - Grey M x1',
    amount: { currency: 'USD', value: '22.15' }
  }],
  total: {
    label: 'Total due',
    amount: { currency: 'USD', value : '22.15' }
  }
}, {
  requestShipping: true,
  requestBillingAddress: true,
  requestPayerEmail: true,
  requestPayerPhone: true,
  requestPayerName: true,
  shippingType: 'delivery'
});

Po otrzymaniu informacji o transakcji przeglądarka przechodzi przez proces wykrywania aplikacji do płatności określonych w PaymentRequest na podstawie identyfikatorów formy płatności. Dzięki temu przeglądarka może określić aplikację płatniczą, którą ma uruchomić, gdy tylko sprzedawca będzie gotowy do zrealizowania transakcji.

Aby dowiedzieć się więcej o procesie wykrywania, przeczytaj artykuł Konfigurowanie metody płatności.

Krok 2. Sprzedawca wyświetla przycisk płatności

Sprzedawcy mogą obsługiwać wiele form płatności, ale powinni wyświetlać przyciski płatności tylko w przypadku tych, których klient może faktycznie używać. Wyświetlanie przycisku płatności, który nie działa, to niewygoda dla użytkowników. Jeśli sprzedawca może przewidzieć, że metoda płatności określona w obiekcie PaymentRequest nie będzie odpowiednia dla klienta, może podać alternatywne rozwiązanie lub w ogóle nie wyświetlać tego przycisku.

Za pomocą instancji PaymentRequest sprzedawca może zapytać, czy klient ma dostępną aplikację płatniczą.

Czy klient ma aplikację do płatności?

Metoda PaymentRequest z parametrem canMakePayment() zwraca wartość true, jeśli na urządzeniu klienta jest dostępna aplikacja do płatności. „Dostępna” oznacza, że została wykryta aplikacja płatnicza obsługująca daną formę płatności i zainstalowana jest odpowiednia aplikacja płatnicza lub że internetowa aplikacja płatnicza jest gotowa do zarejestrowania.

const canMakePayment = await request.canMakePayment();
if (!canMakePayment) {
  // Fallback to other means of payment or hide the button.
}

Krok 3. Klient naciska przycisk płatności

Gdy klient naciśnie przycisk płatności, sprzedawca wywołuje metodę show() instancji PaymentRequest, która natychmiast uruchamia interfejs płatności.

Jeśli ostateczna łączna cena jest ustawiana dynamicznie (np. pobierana z serwera), sprzedawca może opóźnić uruchomienie interfejsu płatności do czasu, gdy będzie znana łączna kwota.

Odłożenie uruchomienia interfejsu płatności

Sprawdź wersję demonstracyjną odroczenia płatności z UI do czasu ustalenia ostatecznej ceny całkowitej.

Aby odroczyć interfejs płatności, sprzedawca przekazuje obietnicę formy show(). Przeglądarka będzie wyświetlać wskaźnik wczytywania, dopóki obietnica nie zostanie zrealizowana i transakcja będzie gotowa do rozpoczęcia.

const getTotalAmount = async () => {
  // Fetch the total amount from the server, etc.
};

try {
  const result = await request.show(getTotalAmount());
  // Process the result…
} catch(e) {
  handleError(e);
}

Jeśli jako argument funkcji show() nie zostanie podany żaden obietni, przeglądarka natychmiast uruchomi interfejs płatności.

Krok 4. Przeglądarka uruchamia aplikację do płatności

Przeglądarka może uruchomić aplikację do płatności na danej platformie lub aplikację internetową. (Więcej informacji o tym, jak Chrome określa, którą aplikację do płatności uruchomić)

Sposób tworzenia aplikacji do płatności zależy w dużej mierze od dewelopera, ale zdarzenia emitowane przez sprzedawcę i do niego oraz struktura danych przekazywanych wraz z tymi zdarzeniami są standardowe.

Gdy uruchomisz aplikację do płatności, otrzyma ona informacje o transakcji przekazane do obiektu PaymentRequest w kroku 1. Informacje te obejmują:

• Dane formy płatności
• Łączna cena
• Opcje płatności

Aplikacja do płatności używa informacji o transakcji do etykietowania interfejsu użytkownika.

Krok 5. Jak sprzedawca może zaktualizować szczegóły transakcji w zależności od działań klienta

Klienci mogą zmienić szczegóły transakcji, takie jak forma płatności i opcja dostawy, w aplikacji do płatności. Podczas wprowadzania zmian sprzedawca otrzymuje zdarzenia zmiany i aktualizuje szczegóły transakcji.

Sprzedawca może otrzymywać 4 typy zdarzeń:

• Zdarzenie zmiany formy płatności
• Zdarzenie zmiany adresu dostawy
• Zdarzenie zmiany opcji dostawy
• Zdarzenie weryfikacji sprzedawcy

Zdarzenie zmiany formy płatności

Aplikacja płatnicza może obsługiwać wiele form płatności, a sprzedawca może zaoferować specjalny rabat w zależności od wyboru klienta. Aby obsłużyć ten przypadek użycia, zdarzenie zmiany formy płatności może poinformować sprzedawcę o nowej formie płatności, aby mógł zaktualizować łączną cenę ze zniżką i zwrócić ją do aplikacji płatniczej.

request.addEventListener('paymentmethodchange', e => {
  e.updateWith({
    // Add discount etc.
  });
});

Zdarzenie zmiany adresu dostawy

Aplikacja płatnicza może opcjonalnie podać adres dostawy klienta. Jest to wygodne dla klientów, ponieważ nie muszą ręcznie wpisywać żadnych szczegółów w formularzu. Mogą też zapisać adres dostawy w preferowanych aplikacjach do płatności, zamiast w wielu różnych witrynach sprzedawców.

Jeśli klient zaktualizuje adres dostawy w aplikacji płatniczej po zainicjowaniu transakcji, do sprzedawcy zostanie wysłane zdarzenie 'shippingaddresschange'. To zdarzenie pomaga sprzedawcy określić koszt dostawy na podstawie nowego adresu, zaktualizować łączną cenę i zwrócić ją do aplikacji płatniczej.

request.addEventListener('shippingaddresschange', e => {
  e.updateWith({
    // Update the details
  });
});

Jeśli sprzedawca nie może wysłać przesyłki na zaktualizowany adres, może przesłać komunikat o błędzie, dodając parametr błędu do szczegółów transakcji zwracanych do aplikacji płatniczej.

Zdarzenie zmiany opcji dostawy

Sprzedawca może zaoferować klientowi kilka opcji dostawy i może przekazać wybór aplikacji do płatności. Opcje dostawy są wyświetlane jako lista cen i nazw usług, spośród których klient może wybierać. Na przykład:

• Dostawa standardowa – bezpłatna
• Przesyłka ekspresowa – 5 USD

Gdy klient zaktualizuje opcję dostawy w aplikacji do płatności, sprzedawca otrzyma zdarzenie 'shippingoptionchange'. Sprzedawca może wtedy określić koszt dostawy, zaktualizować łączną cenę i zwrócić ją do aplikacji płatniczej.

request.addEventListener('shippingoptionchange', e => {
  e.updateWith({
    // Update the details
  });
});

Sprzedawca może również dynamicznie modyfikować opcje dostawy na podstawie adresu dostawy klienta. Jest to przydatne, gdy sprzedawca chce zaoferować różne opcje dostawy klientom krajowym i zagranicznym.

Zdarzenie weryfikacji sprzedawcy

Aby zwiększyć bezpieczeństwo, aplikacja płatnicza może przeprowadzić weryfikację sprzedawcy przed przejściem do procesu płatności. Projekt mechanizmu weryfikacji zależy od aplikacji do płatności, ale zdarzenie weryfikacji sprzedawcy służy do informowania sprzedawcy o adresie URL, którego może użyć do weryfikacji.

request.addEventListener('merchantvalidation', e => {
  e.updateWith({
    // Use `e.validateURL` to validate
  });
});

Krok 6. Sprzedawca weryfikuje płatność i kończy transakcję

Gdy klient autoryzuje płatność, metoda show() zwraca obietnicę, która przekształca się w PaymentResponse. Obiekt PaymentResponse zawiera te informacje:

• Szczegóły wyniku płatności
• Adres dostawy
• Opcja dostawy
• Informacje kontaktowe

W tym momencie w interfejsie przeglądarki może być nadal widoczny wskaźnik wczytywania, co oznacza, że transakcja nie została jeszcze ukończona.

Jeśli aplikacja do płatności zostanie zakończona z powodu błędu lub nieudanej płatności, obietnica z show() zostanie odrzucona, a przeglądarka zakończy transakcję płatności.

Przetwarzanie i weryfikowanie płatności

details w PaymentResponse to obiekt danych uwierzytelniających płatność zwracany z aplikacji płatniczej. Sprzedawca może użyć tych danych uwierzytelniających, by przetworzyć lub zweryfikować płatność. Przebieg tego krytycznego procesu zależy od firmy obsługującej płatności.

Kończenie lub ponawianie transakcji

Gdy sprzedawca ustali, czy transakcja została zrealizowana, czy nie, może:

• Wywołaj metodę .complete(), aby zakończyć transakcję i zamknąć wskaźnik ładowania.
• Poproś klienta o ponowne wywołanie metody retry().

async function doPaymentRequest() {
  try {
    const request = new PaymentRequest(methodData, details, options);
    const response = await request.show();
    await validateResponse(response);
  } catch (err) {
    // AbortError, SecurityError
    console.error(err);
  }
}

async function validateResponse(response) {
  try {
    const errors = await checkAllValuesAreGood(response);
    if (errors.length) {
      await response.retry(errors);
      return validateResponse(response);
    }
    await response.complete("success");
  } catch (err) {
    // Something went wrong…
    await response.complete("fail");
  }
}
// Must be called as a result of a click
// or some explicit user action.
doPaymentRequest();

Następne kroki

• Więcej informacji o zadeklarowaniu identyfikatora formy płatności znajdziesz w artykule Konfigurowanie formy płatności.
• Aby dowiedzieć się, jak utworzyć aplikację płatniczą wybraną na danej platformie, przeczytaj przewodnik dla programistów aplikacji do płatności na Androida.
• Dowiedz się, jak tworzyć aplikacje do płatności internetowych, korzystając z przewodnika dla deweloperów.