Przejdź do głównej zawartości

Card Data API

Użycie Card Data API pozwala poznać cechy karty płatniczej jeszcze przed wykonaniem zamówienia.

Jest to rozwiązanie szczególnie użyteczne do precyzyjnego określania grupy docelowej, np. promocji na podstawie cech karty (np. wydawca, typ, kraj). Dzięki unikalnemu identyfikatorowi karty wykryjesz przypadki, gdy ten sam użytkownik zapisuje tę samą kartę na wielu kontach, aby wielokrotnie wykorzystywać promocje lub darmowe okresy próbne.

Dzięki skorzystaniu z tego API poznasz:

  • charakterystykę karty z tablicy BIN-dane pochodzące od organizacji płatniczej Visa lub Mastercard, takie jak:
    • organizacja płatnicza,
    • typ karty,
    • rodzaj karty,
    • kraj karty,
    • dane dotyczące wydawcy karty (nazwa i kraj),
    • oraz inne parametry szczegółowo opisane w sekcji Retrieve Card Data,
  • unikalny identyfikator karty płatniczej-niezmienny dla fizycznego numeru karty płatniczej (tzw. PAN), szczególnie użyteczny, gdy korzystasz z tokenizacji kart, a chcesz wiedzieć, czy klient nie zapisuje ponownie tej samej karty płatniczej,
  • dostępne opcje ratalne.

Jeśli jesteś zainteresowany wykorzystaniem Card Data API, skontaktuj się ze swoim opiekunem handlowym lub zespołem wsparcia PayU.

Integracja przy użyciu tokena kartowego​

Aby skorzystać z Card Data API, konieczne jest uwierzytelnienie żądania przynajmniej na poziomie client_credentials lub trusted_merchant.

Nie musisz obsługiwać pełnej tokenizacji kart, aby skorzystać z tego rozwiązania. Wystarczy, że masz zaimplementowane odbieranie danych karty w postaci Secure Form.

API wymaga podania jedynie wartości token, którą poznajesz po udanym przetworzeniu żądania utworzenia tokena kartowego (dowolnego typu: SINGLE, SINGLE_LONGTERM, MULTI) z wykorzystaniem Secure Form. Tak utworzony token zawsze ma prefiks TOK_ lub TOKD_.

Możesz zrobić to w dowolnym momencie cyklu życia płatności, z ograniczeniem do 11 minut dla tokenów typu SINGLE ze względu na specyfikę tego typu tokenów.

Jeśli korzystasz z tokenizacji kart, możesz pobrać tokeny kartowe, a następnie użyć tak pobranego tokena (z prefiksem TOKC_). Jego wartość podajesz również w polu token przy wysyłaniu żądania do tego API. Możesz to zrobić w dowolnym momencie cyklu życia tokena kartowego.

Przykład żądania przy użyciu tokena kartowego
curl -X POST 'https://secure.payu.com/api/v2_1/cards/lookup' \
  -H 'Authorization: Bearer 52a0da5b-fc06-4e93-bf15-b97a35b627c9' \
  -H 'Content-Type: application/json' \
  -d '{
    "token": "TOK_1LPMUT7LMLPU0361cHh88Cr0hHnP"
  }'
Przykład żądania przy użyciu tymczasowego tokena kartowego (SINGLE)
curl -X POST 'https://secure.payu.com/api/v2_1/cards/lookup' \
  -H 'Authorization: Bearer 52a0da5b-fc06-4e93-bf15-b97a35b627c9' \
  -H 'Content-Type: application/json' \
  -d '{
    "token": "TOKD_1LPMUT4FPPSS9k46204E39L5S0k"
  }'

W odpowiedzi uzyskasz cechy karty płatniczej zidentyfikowanej za pomocą podanego tokena kartowego.

Przykład odpowiedzi
{
  "maskedNumber": "536447******6443",
  "expirationMonth": 8,
  "expirationYear": 2029,
  "scheme": "MC",
  "description": "World Debit Mastercard Card",
  "type": "MDH",
  "countryCode": "RO",
  "classification": "DEBIT",
  "profile": "CONSUMER",
  "uniqueReference": "b75ddfb250cd8d9a647fa787718ec67f3f984d54bb51432373427c0e874f68c42438945f330bd6be07f3b41fde422fb548ccbe23c9cb51d0c1792ec7004ed23e",
  "issuer": {
    "name": "SUPER BANK LIMITED",
    "region": "EUROPE",
    "countryCode": "RO"
  },
  "installmentOptions": {
    "numbers": [1, 6, 12, 20, 21, 22, 23, 24],
    "provider": "SUPERBANK"
  }
}

Szczegółowe informacje na temat parametrów znajdziesz w sekcji Retrieve Card Data w naszej dokumentacji API.

Integracja z wykorzystaniem danych karty​

Wymagane PCI DSS

Ten typ integracji jest dostępny tylko dla podmiotów spełniających wymagania PCI DSS i zatwierdzonych do przetwarzania danych kart po swojej stronie.

Integracja ta wymaga również dodatkowej konfiguracji. Dlatego przed integracją skontaktuj się z opiekunem handlowym w PayU.

Jeżeli korzystasz z funkcjonalności podawania danych karty w postaci tekstowej, możesz skorzystać z Card Data API, podając numer karty płatniczej (PAN) wraz z jej datą ważności.

Możesz również wykorzystać do tego wirtualny numer karty płatniczej (VAN) wraz z datą ważności takiej wirtualnej karty płatniczej, np. odczytany z portfela cyfrowego (Google Pay, Apple Pay).

Sposób wysłania żądania API w obu przypadkach wygląda tak samo.

Przykład żądania z podanymi danymi karty
curl -X POST 'https://secure.payu.com/api/v2_1/cards/lookup' \
  -H 'Authorization: Bearer 52a0da5b-fc06-4e93-bf15-b97a35b627c9' \
  -H 'Content-Type: application/json' \
  -d '{
    "card": {
      "number": "4111111111111111",
      "expirationMonth": 12,
      "expirationYear": 2029
    }
  }'

Na tej stronie