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 specjalne funkcje płatności wbudowane w przeglądarkę po raz pierwszy. 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 płatność.
2. Sprzedawca wyświetla przycisk płatności.

3. Klient naciska przycisk płatności.

   

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

   

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ż podać opcjonalny typ dostawy (shipping, delivery lub pickup) w polu PaymentRequest. Aplikacja do płatności może użyć tego jako wskazówki, aby wyświetlić odpowiednie 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'
});

Dodawanie identyfikatora transakcji

Niektórzy dostawcy usług płatniczych mogą wymagać od sprzedawcy podania identyfikatora transakcji, który został wcześniej wydany jako część informacji o transakcji. Typowa integracja obejmuje komunikację między serwerem sprzedawcy a serwerem modułu płatności w celu zarezerwowania łącznej ceny. Dzięki temu szkodliwi klienci nie mogą manipulować ceną i oszukiwać sprzedawcy za pomocą weryfikacji na końcu transakcji.

Sprzedawca może przekazać identyfikator transakcji jako część właściwości data obiektu PaymentMethodData.

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ę do płatności, którą należy uruchomić, gdy tylko sprzedawca będzie gotowy do przeprowadzenia 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 przyciski płatności powinny być widoczne tylko dla tych, z których klient może faktycznie korzystać. Wyświetlanie przycisku płatności, który nie działa, to niewygoda dla użytkowników. Jeśli sprzedawca może przewidzieć, że forma płatności określona w obiekcie PaymentRequest nie zadziała dla klienta, może zastosować rozwiązanie zastępcze lub w ogóle nie wyświetlać tego przycisku.

Korzystając z interfejsu PaymentRequest, sprzedawca może sprawdzić, czy klient ma dostępną aplikację do płatności.

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 aplikacja obsługująca formę płatności została wykryta i zainstalowana (w przypadku aplikacji na daną platformę) lub że aplikacja internetowa 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 cena całkowita jest ustalana dynamicznie (np. pobierana z serwera), sprzedawca może odroczyć uruchomienie interfejsu płatności do momentu uzyskania znanej sumy.

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

Obejrzyj demonstrację odrywania płatności w interfejsie użytkownika do czasu ustalenia ostatecznej łącznej ceny.

Aby odłożyć wyświetlenie interfejsu płatności, sprzedawca przekazuje obietnicę do metody show(). Do momentu, aż obietnica zostanie spełniona i transakcja będzie gotowa do rozpoczęcia, przeglądarka będzie wyświetlać wskaźnik wczytywania.

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.

Uwaga: jeśli moduł płatności jest tak skonfigurowany, że po ustawieniu łącznej ceny zwraca identyfikator transakcji, identyfikator ten można przekazać jako część wyniku obietnicy.

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 płatniczej zależy w większości od dewelopera, ale zdarzenia generowane przez sprzedawcę i dla niego oraz struktura danych przekazywanych wraz z tymi zdarzeniami są ustandaryzowane.

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.

Istnieją 4 typy zdarzeń, które sprzedawca może otrzymywać:

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

Zdarzenie zmiany formy płatności

Aplikacja do płatności może obsługiwać wiele form płatności, a sprzedawca może oferować specjalny rabat w zależności od wyboru klienta. W tym przypadku zdarzenie zmiany formy płatności może poinformować sprzedawcę o nowej formie płatności, aby mógł zaktualizować łączną cenę o rabat i zwrócić ją z powrotem do aplikacji płatniczej.

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

Zdarzenie zmiany adresu dostawy

Aplikacja do płatności może opcjonalnie podać adres dostawy klienta. Jest to wygodne dla klientów, ponieważ nie muszą ręcznie wpisywać żadnych danych w formularzu i mogą zapisać adres dostawy w preferowanych aplikacjach płatniczych, a nie na wielu stronach różnych sprzedawców.

Jeśli po zainicjowaniu transakcji klient zaktualizuje adres dostawy w aplikacji do płatności, sprzedawca otrzyma 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.

Uwaga: sprzedawcy nie otrzymują pełnego adresu dostawy klienta, dopóki nie autoryzują płatności.

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 następnie 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 zapewnić dodatkowe bezpieczeństwo, aplikacja płatnicza może przeprowadzić weryfikację sprzedawcy, zanim przejdzie do procesu płatności. Sposób konfiguracji mechanizmu weryfikacji zależy od aplikacji płatniczej, ale zdarzenie weryfikacji sprzedawcy przekazuje sprzedawcy informacje o adresie URL, którego może on użyć do weryfikacji.

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

Uwaga: obsługa zdarzenia weryfikacji sprzedawcy jest ograniczona do przeglądarki Safari firmy Apple. Od maja 2020 r. to zdarzenie nie było zaimplementowane w przeglądarkach opartych na Chromium.

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

Gdy klient autoryzuje płatność, forma show() zwraca obietnicę złożoną 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.

Przetwarzam i weryfikuję płatność

Wartość details w elementach PaymentResponse to obiekt danych uwierzytelniających płatności zwrócony z aplikacji do dokonywania płatności. Sprzedawca może użyć tych danych, aby przetworzyć lub zweryfikować płatność. Sposób działania tego kluczowego procesu zależy od podmiotu obsługującego płatności.

Dokonywanie lub ponowne próbowanie transakcji

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

• Aby zrealizować transakcję i zamknąć wskaźnik wczytywania, wywołaj metodę .complete().
• 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.
• Więcej informacji o tworzeniu aplikacji do płatności na konkretnej platformie znajdziesz w przewodniku dla deweloperó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.