Przejdź do głównej zawartości

Zainstaluj i zainicjalizuj Card SDK

Na tej stronie wczytasz SDK na swoją stronę i utworzysz instancję PaymenticCard, z której korzystają wszystkie metody płatności.

Wczytaj SDK​

SDK jest serwowane przez Paymentic i nie jest dystrybuowane przez npm. Zawsze ładuj je z domeny Paymentic. Nie kopiuj pliku na własne serwery, żeby poprawki bezpieczeństwa docierały do Ciebie bez wdrożenia.

Tag script (zalecane)​

<script src="https://cards.sandbox.paymentic.com/sdk/v1/paymentic-card.js"></script>
<script>
    const paymentic = new PaymenticCard({ pointId: '000cb241' });
</script>

Skrypt definiuje jedną zmienną globalną: window.PaymenticCard.

SDK jest serwowane z osobnego hosta dla każdego środowiska:

ŚrodowiskoHost SDK
Produkcjahttps://cards.paymentic.com
Sandboxhttps://cards.sandbox.paymentic.com

Pełną listę hostów, z których SDK ładuje skrypty i ramki, zawiera inwentarz zasobów zewnętrznych.

Przykłady w tej dokumentacji ładują SDK z hosta sandboxowego, bo od niego zaczynasz integrację. Przed wejściem na produkcję podmień host na cards.paymentic.com i Point ID na produkcyjny. Zob. Testowanie i wdrożenie.

Żeby przypiąć dokładny build przez Subresource Integrity, odczytaj bieżące hashe z https://cards.paymentic.com/sdk/v1/integrity.json i dodaj do tagu integrity="sha384-…" crossorigin="anonymous". Przypięty hash przestaje pasować, gdy Paymentic wyda kompatybilną aktualizację, więc przypinaj tylko wtedy, gdy możesz szybko wdrożyć zmianę.

Moduł ES​

import { PaymenticCard } from 'https://cards.sandbox.paymentic.com/sdk/v1/paymentic-card.mjs';

TypeScript​

Deklaracje typów są publikowane obok bundle'a pod https://cards.paymentic.com/sdk/v1/types/. TypeScript nie pobiera deklaracji z URL-i, więc skopiuj je do projektu:

  1. Pobierz katalog types/ (np. do src/types/paymentic/).
  2. Upewnij się, że katalog jest objęty polem include w tsconfig.json.

types/global.d.ts typuje window.PaymenticCard, a types/index.d.ts eksportuje wszystkie publiczne typy:

import type { CardElement, TokenizeResult, CardChangeEvent } from './types/paymentic/index';

const paymentic = new window.PaymenticCard({ pointId: '000cb241' });

Jeśli używasz URL-a modułu ES, dodaj deklarację modułu, żeby import był otypowany:

// paymentic.d.ts
declare module 'https://cards.sandbox.paymentic.com/sdk/v1/paymentic-card.mjs' {
    export * from './types/paymentic/index';
}

Pobierz deklaracje ponownie, gdy zaczynasz korzystać z nowej funkcji SDK. Runtime jest wstecznie kompatybilny w ramach v1, więc nieaktualne deklaracje jedynie ukrywają nowe opcje.

Wczytywanie na żądanie​

W aplikacjach SPA wygodnie jest wstrzyknąć skrypt dopiero wtedy, gdy jest potrzebny. Poniższy helper ładuje go raz i zwraca zmienną globalną:

let sdkPromise: Promise<typeof window.PaymenticCard> | null = null;

export function loadPaymenticCard(): Promise<typeof window.PaymenticCard> {
    if (window.PaymenticCard) return Promise.resolve(window.PaymenticCard);
    if (sdkPromise) return sdkPromise;

    sdkPromise = new Promise((resolve, reject) => {
        const script = document.createElement('script');
        script.src = 'https://cards.sandbox.paymentic.com/sdk/v1/paymentic-card.js';
        script.async = true;
        script.onload = () => resolve(window.PaymenticCard);
        script.onerror = () => {
            sdkPromise = null;
            reject(new Error('Nie udało się wczytać Paymentic Card SDK'));
        };
        document.head.appendChild(script);
    });

    return sdkPromise;
}

Zainicjalizuj SDK​

const paymentic = new PaymenticCard({
    // Wymagane. 8-znakowy identyfikator punktu płatności.
    pointId: '000cb241',

    // Wymagane tylko dla portfeli: domyślne dane arkusza Google Pay / Apple Pay.
    // Każdą wartość można nadpisać przy pojedynczym wywołaniu.
    wallet: {
        payment: {
            amount: '149.00',      // kwota jako string dziesiętny, np. '10.00'
            currencyCode: 'PLN',   // ISO 4217
            countryCode: 'PL',     // ISO 3166-1 alpha-2
            label: 'Twój Sklep',   // etykieta w arkuszu portfela (opcjonalna)
        },
    },

    // Opcjonalne. Dokąd trafia diagnostyka. Domyślnie console.warn.
    logger: { warn: (message) => yourLogger.warn(message) },
});
OpcjaTypWymaganaOpis
pointIdstringtakIdentyfikator punktu płatności, dokładnie 8 znaków. W przeciwnym razie konstruktor rzuca INVALID_CONFIG.
wallet.payment.amountstringdla portfeliKwota całkowita jako string dziesiętny.
wallet.payment.currencyCodestringdla portfeliKod ISO 4217.
wallet.payment.countryCodestringdla portfeliKod kraju sprzedawcy ISO 3166-1 alpha-2.
wallet.payment.labelstringnieEtykieta w arkuszu portfela. Domyślnie nazwa sprzedawcy skonfigurowana dla punktu.
logger{ warn(message: string): void }nieOdbiornik diagnostyki SDK. Przekaż { warn() {} }, żeby ją wyciszyć.

Wszystko poza tym (identyfikatory sprzedawcy w Google Pay, dozwolone sieci kart, konfiguracja Apple Pay) jest przypisane do punktu po stronie Paymentic i pobierane przez SDK automatycznie. Nie konfigurujesz tego.

Jedna instancja na checkout wystarczy. Utwórz ją raz, zachowaj referencję i wywołaj destroy() przy zamykaniu checkoutu. Zob. Integracja w React i Vue.

Wersjonowanie​

  • SDK jest wersjonowane wersją główną w URL-u: /sdk/v1/ zawsze serwuje najnowszy wstecznie kompatybilny build 1.x, więc poprawki bezpieczeństwa i usprawnienia docierają bez zmian po Twojej stronie. Zmiany łamiące kompatybilność wychodzą pod nową ścieżką (/sdk/v2/) i nigdy nie wpływają na istniejące osadzenia v1.
  • Dokładny build jest dostępny w runtime jako PaymenticCard.VERSION. Hashe SRI bieżących bundle'i są publikowane pod /sdk/v1/integrity.json, a deklaracje typów pod /sdk/v1/types/.

Co dalej​