Apple Pay

Apple Pay umożliwia dokonywanie płatności za pomocą kart płatniczych zapisanych w Apple Pay oraz w aplikacji Portfel (Apple Wallet). Gdy użytkownik zdecyduje się na płatność za pośrednictwem tego kanału i jest zalogowany na swoim urządzeniu na konto Apple, wyświetlona zostaje mu preferowana karta płatnicza. Istnieje również możliwość wyboru innej zapisanej karty oraz potwierdzenie transakcji za pomocą biometrii (Face ID, Touch ID) lub kodu dostępu, w zależności od urządzenia i ustawień bezpieczeństwa. Jeśli użytkownik nie jest zalogowany, pojawi się formularz logowania do konta Apple. Podczas przetwarzania płatności generowany jest przez Apple jednorazowy token płatniczy, który zastępuje dane karty podczas transakcji, co zwiększa bezpieczeństwo płatności.

Rodzaje obsługiwanych kart

Obecnie obsługujemy wyłącznie karty Visa i Mastercard.

Zanim zaczniesz

Upewnij się, że:

• Posiadasz dane autoryzacyjne do API.
• Obsługujesz notyfikacje transakcji.
• Posiadasz włączone płatności kartowe.
• Posiadasz włączony kanał płatności Apple Pay.

Transakcja Apple Pay

Realizuj płatności Apple Pay wykorzystując endpoint zakładania transakcji podając channelId: 75.

Wyślij zapytanie o utworzenie transakcji Apple Pay

Aby utworzyć transakcję Apple Pay, wyślij żądanie POST na endpoint:

https://api.tpay.com/transactions

W zapytaniu określ następujące parametry:

Podstawowe body żądania powinno wyglądać następująco:

{
  "amount": 0.1,
  "description": "Testowa płatność Apple Pay",
  "payer": {
    "email": "[email protected]",
    "name": "Jan Nowak"
  },
  "pay": {
    "channelId": 75
  }
}

Przykład:

curl --location 'https://api.tpay.com/transactions' \
--header 'Authorization: Bearer <access_token>' \
--header 'Content-Type: application/json' \
--data-raw '{
   "amount": 0.1,
   "description": "Testowa płatność Apple Pay",
   "payer": {
      "email": "[email protected]",
      "name": "Jan Nowak"
   },
   "pay": {
      "channelId": 75
   }
}'

Po wysłaniu żądania otrzymasz w odpowiedzi schemat TransactionCreated.

Najważniejsze parametry odpowiedzi:

Przykład odpowiedzi:

{
  "result": "success",
  "requestId": "786dee7ec39502226238",
  "transactionId": "01K5BK4HEPB0WBCGT51FMTYSYJ",
  "title": "TR-CWM-D14339X",
  "posId": "ps_e4dkPVDEm4Jg726q",
  "status": "pending",
  "date": {
    "creation": "2024-07-04 21:15:23",
    "realization": null
  },
  "amount": 0.1,
  "currency": "PLN",
  "description": "Testowa płatność Apple Pay",
  "hiddenDescription": "",
  "payer": {
    "payerId": "py_a9rjlZWxRLdG1bqY",
    "email": "[email protected]",
    "name": "Jan Nowak",
    "phone": "",
    "address": "",
    "city": "",
    "country": "PL",
    "postalCode": ""
  },
  "payments": {
    "status": "pending",
    "method": "pay_by_link",
    "amountPaid": 0,
    "date": {
      "realization": null
    }
  },
  "transactionPaymentUrl": "https://secure.tpay.com/?title=TR-CWM-D14339X&uid=01J1ZJREPKDXXJ5E4JRWYVXMN2"
}

Przekieruj płatnika na Panel Transakcyjny

Przekieruj płatnika na URL zawarty w odpowiedzi w polu transactionPaymentUrl.

Pod wskazanym URL płatnik zobaczy arkusz płatności z listą dostępnych kart płatniczych zapisanych na jego koncie Apple albo formularz logowania do konta Apple.

Płatnik wybiera kartę i finalizuje transakcję.

Płatnik zostanie przekierowany na stronę sukcesu lub porażki

Gdy płatność zostanie zakończona, płatnik zostanie przekierowany na stronę sukcesu (success page) lub stronę porażki (error page) w zależności od tego, czy transakcja się udała.

Obsłuż powiadomienie

Poinformujemy Ciebie o statusie transakcji za pośrednictwem notyfikacji po zaksięgowaniu transakcji.

Apple Pay on-site

Apple Pay on-site jest to integracja płatności Apple Pay bezpośrednio w Twojej witrynie/aplikacji mobilnej.

Polega ona na umieszczeniu mechanizmu do płatności Apple Pay w sposób umożliwiający klientom płatność bezpośrednio z poziomu Twojego systemu/aplikacji mobilnej.

Zarejestruj domenę w Apple Pay

Zarejestruj domenę w Apple Developer, w tym celu należy wgrać na swój serwer plik z konta Apple Pay, który będzie dostępny dla przeglądarek z poziomu domeny. Plik ten służy do weryfikacji domeny podczas jej rejestracji. Apple, w celu weryfikacji domeny, odpytuje zarejestrowaną domenę, jak na przykładzie poniżej.

https://{DOMAIN_NAME}/.well-known/apple-developer-merchantid-domain-association

https://secure.tpay.com/.well-known/apple-developer-merchantid-domain-association

Kolejnym krokiem w implementacji jest konfiguracja wcześniej wspomnianej domeny. W tym celu należy zalogować się do Panelu Akceptanta i wejść w zakładkę Integracji, a następnie wybrać z listy Apple Pay.

Następnie należy kliknąć przycisk edycji oraz ikonę plusa znajdującą się po lewej stronie Domains. Należy wprowadzić adres URL domeny, na której ma się znaleźć przycisk i zapisać ustawienia. Merchant może dodać więcej niż jedną domenę. W celu zdefiniowania, kolejnych należy ponownie użyć ikony plusa.

Dodaj przycisk płatność Apple Pay

W celu wygenerowania przycisku zaleca się wykorzystanie strony demo Apple. Można znaleźć ją tutaj.

Zaimplementuj bibliotekę Apple Pay

Po wygenerowaniu kodu należy umieścić go w kodzie źródłowym strony w miejscu, gdzie ma być dokonywana płatność. W tym samym miejscu należy również zaimplementować skrypt wykorzystywany do obsługi przycisku.

<script src="https://applepay.cdn-apple.com/jsapi/v1/apple-pay-sdk.js"></script>

Sprawdź urządzenie

Przy uruchomieniu kodu należy sprawdzić, czy urządzenie wspiera płatności Apple Pay. W tym celu sprawdza się, czy istnieje obiekt ApplePaySession w przeglądarce oraz, czy użytkownik ma podpiętą aktywną kartę Apple Pay.

/ Apple payment validation
// Check is Apple device and if user has active card in wallet
if (window.ApplePaySession) {
  ApplePaySession
    .canMakePaymentsWithActiveCard(merchantIdentifier)
    .then(function (canMakePayment) {
      if (!canMakePayment) {
        alert('Apple pay payment not supported');
      }
    });
}

Skonfiguruj płatność

Po pomyślnej weryfikacji należy utworzyć nową sesję, w której zdefiniowane zostaną wszystkie dane dotyczące płatności. Opcjonalnie można przekazać requiredShippingContactFields oraz requiredBillingContactFields, gdzie wskazane parametry umożliwiają otrzymanie od płatnika danych dostawy oraz kontakt. Więcej informacji o danych płatności znajdziesz tutaj.

// Apple Pay script version
const applePayVersion = 1;

// Payment data
const paymentRequest = {
  currencyCode: 985,
  countryCode: "POL",

  total: {
    label: "Payment description",
    amount: 10,
    type: "final",
  },

  supportedNetworks: ["visa", "masterCard", "electron", "maestro", "vPay"],

  merchantCapabilities: ["supports3DS"],

  //optional parameters
  requiredShippingContactFields: ["postalAddress", "name", "phone", "email"],

  requiredBillingContactFields: ["postalAddress"],
};

Po utworzeniu sesji należy obsłużyć event sprawdzający domenę akceptanta. W tym celu należy wysłać żądanie do własnego środowiska back-end, które odpyta API Tpay na endpoint POST /wallet/applepay/init oraz zwróci odpowiedź do aplikacji frontowej.

// Validate merchant domain
applePaySession.onvalidatemerchant = async function (event) {
  await fetch("/wallet/applepay/init", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      // Correct domain name ( same as in Tpay's Apple Pay Settings )
      domainName: "",
      // Name displayed when paying
      displayName: "",
      // The URL that is required to obtain an Apple Pay session
      validationUrl: event.validationURL,
    }),
  }).then(async (response) => {
    if (response.status === 200) {
      let json;
      try {
        json = await response.json();
      } catch {
        alert("Tpay error occurred");
        return;
      }
      applePaySession.completeMerchantValidation(response.session);
    } else {
      alert("Error occurred");
      return;
    }
  });
};

Wyślij zapytanie o utworzenie transakcji Apple Pay

Aby utworzyć transakcję Apple Pay, wyślij żądanie POST na endpoint:

https://api.tpay.com/transactions

W zapytaniu określ następujące parametry:

Podstawowe body żądania powinno wyglądać następująco:

{
  "amount": 0.1,
  "description": "Testowa płatność Apple Pay",
  "payer": {
    "email": "[email protected]",
    "name": "Jan Nowak",
    "ip": "127.0.0.1"
  },
  "pay": {
    "channelId": 75
  }
}

Przykład:

curl --location 'https://api.tpay.com/transactions' \
--header 'Authorization: Bearer <access_token>' \
--header 'Content-Type: application/json' \
--data-raw '{
   "amount": 0.1,
   "description": "Testowa płatność Apple Pay",
   "payer": {
      "email": "[email protected]",
      "name": "Jan Nowak"
      “ip”: “127.0.0.1”
   },
   "pay": {
      "channelId": 75
   }
}'

Po wysłaniu żądania otrzymasz w odpowiedzi schemat TransactionCreated.

Najważniejsze parametry odpowiedzi:

Przykładowa odpowiedź:

{
  "result": "success",
  "requestId": "b72641d11e4edbaf6110",
  "transactionId": "01K5BK4HEPB0WBCGT51FMTYSYJ",
  "title": "TR-CWM-D14908X",
  "posId": "ps_e4dkPVDEm4Jg726q",
  "status": "pending",
  "date": {
    "creation": "2024-07-04 21:37:04",
    "realization": null
  },
  "amount": 0.1,
  "currency": "PLN",
  "description": "Testowa płatność Apple Pay",
  "hiddenDescription": "",
  "payer": {
    "payerId": "py_a9rjlZWxRLdG1bqY",
    "email": "[email protected]",
    "name": "Jan Nowak",
    "ip": "127.0.0.1",
    "phone": "",
    "address": "",
    "city": "",
    "country": "PL",
    "postalCode": ""
  },
  "payments": {
    "status": "pending",
    "method": "pay_by_link",
    "amountPaid": 0,
    "date": {
      "realization": null
    }
  },
  "transactionPaymentUrl": "https://secure.tpay.com/?title=TR-CWM-D14908X&uid=01J1ZM04S5BJ9RFRMAT13NMPFQ"
}

Opłać transakcję wykorzystując token płatniczy

W tym evencie należy wysłać żądanie do własnego środowiska backend, które odpyta Tpay API na endpoint POST /transactions oraz zwróci rezultat do aplikacji frontendowej. W evencie zwracane są również informacje o płatniku (ApplePayPayment | Apple Developer Documentation), które mogą zostać wykorzystane do uzupełniania danych transakcji. Dane dostawy lub/i kontakt są dostępne, jeśli zostały wskazane w paymentRequest.

Opłać transakcję wykorzystując token płatniczy

W celu opłacenia transakcji Apple Pay on-site wykorzystaj wcześniej przechowany parametr transactionId, wysyłając żądanie POST na adres:

https://api.tpay.com/transactions/{transactionId}/pay

Umieść {transactionId} w adresie url np.:

https://api.tpay.com/transactions/01K5BK4HEPB0WBCGT51FMTYSYJ/pay

W zapytaniu określ następujące parametry:

Przykład implementacji:

// Payment finalization
applePaySession.onpaymentauthorized = async function (event) {
  if (event.payment || event.payment.token || event.payment.token.paymentData) {
    applePaySession.completePayment(ApplePaySession.STATUS_FAILURE);
    return;
  }

  //Get billingContact if required in paymentRequest
  //event.payment.billingContact
  //Get shippingContact if required in paymenRequest
  //event.payment.shippingContact
  await fetch("/transactions", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      base64_payment_data: btoa(encodeURIComponent(event.payment.token.paymentData)),
    }),
  }).then(async (response) => {
    let status = ApplePaySession.STATUS_FAILURE;

    if (response.status === 200) {
      let json;
      try {
        json = await response.json();
      } catch {
        alert("Tpya error occurred");
      }
      if (json.result && json.result === true) {
        status = ApplePaySession.STATUS_SUCCESS;
      }
    } else {
      alert("Error occurred");
    }
    applePaySession.completePayment(status);
  });
};

Podstawowe body żądania powinno wyglądać następująco:

{
  "channelId": 75,
  "applePayPaymentData": "ewogInRwYXkiIDogIkhlbGxvIFdvcmxkIgp9"
}

Obsłuż powiadomienie

Poinformujemy Ciebie o statusie transakcji za pośrednictwem notyfikacji po zaksięgowaniu transakcji.

Wyświetl wynik transakcji

Po otrzymaniu notyfikacji o statusie transakcji wykorzystaj pole tr_status i wyświetl wynik transakcji.

Dokumentacja Apple Pay

Po więcej informacji dotyczących implementacji przycisku płatności Apple Pay odsyłamy do oficjalnej dokumentacji znajdującej się tutaj.