Integracja

Checklista integracji

Użyj poniższej checklisty, aby upewnić się, że poprawnie zintegrowałeś się z usługami Paynow.

1. Utwórz konto na Sandbox tutaj
2. Znajdź swoje dane uwierzytalniające do API
3. Zintegruj się bezpośrednio przez API lub skorzystaj z naszych SDK lub pluginów do najpopularniejszych platform ecommerce
4. Skonfiguruj adres do powiadomień
5. Utwórz płatność - przetestuj pozytywną i negatywną ścieżkę procesu płatności
6. Utwórz zwrot

Dostęp do API

Dane uwierzytalniające

Api-Key oraz Signature-Key znajdziesz w zakładce Ustawienia > Sklepy i punkty płatności > Dane uwierzytalniające w panelu Merchanta.

Środowiska

Produkcyjne

Na środowisku produkcyjnym użyj następującego adresu URL: https://api.paynow.pl

Aby uzyskać dostęp do środowiska produkcyjnego:

1. Postępuj zgodnie z instrukcjami dostępnymi na stronie Paynow aby aktywować usługę paynow.
2. Po aktywacji usługi uzyskasz dostęp do Panelu Merchanta w zakładce Finanse > Paynow.

Testowe - Sandbox

Poniższe przykłady odnoszą się do środowiska testowego Sandbox: https://api.sandbox.paynow.pl

Aby korzystać z Sandbox, musisz najpierw zarejestrować nowe konto i użyć klucza API podanego w Panelu Merchanta środowiska Sandbox lub skorzystać z publicznych danych testowych bez rejestracji:

Przykład użycia	Dane uwierzytelniające
Standardowa integracja	Api-Key: 97a55694-5478-43b5-b406-fb49ebfdd2b5 Signature-Key: b305b996-bca5-4404-a0b7-2ccea3d2b64b
Integracja White Label	Api-Key: a5346108-639d-4a34-b408-afe86d89071f Signature-Key: 7201572b-1234-4853-8437-dd038a28a31d

Uwaga

Sandbox NIE powinien być używany w systemie produkcyjnym.

Specyficzne zachowania

Nie ma prawie żadnej różnicy między środowiskami testowym Sandbox i Produkcyjnym.

W środowisku Sandbox niektóre metody płatności zachowują się specyficznie, jeśli spełnione są określone warunki wstępne żądania. Pozwala nam to testować konkretne przypadki lub zapoznać się z zachowaniem paywall w przypadku konkretnych scenariuszy:

BLIK

W przypadku płatności BLIK podanie konkretnych kodów BLIK skutkuje różnymi odpowiedziami:

Kod	Wyjaśnienie
111111	Płatność zakończona pomyślnie
222222	Płatność pozostaje w statusie PENDING
333333	Autoryzacja płatności nie powiodła się, ponieważ podano błędny kod autoryzacyjny
333334	Autoryzacja płatności nie powiodła się, ponieważ podano wygasły kod autoryzacyjny
333335	Autoryzacja płatności nie powiodła się, ponieważ podano już wykorzystany kod autoryzacyjny
333336	Autoryzacja płatności nie powiodła się, ponieważ podczas procesu płatności wystąpiły inne problemy
444444	Płatność pozostaje w statusie NEW przez 20 sekund, a następnie przechodzi w ERROR i pozostaje w tym statusie

Pay-By-Link

W przypadku płatności pay-by-link, płatność kwotą równą 9999.99 PLN kończy się niepowodzeniem i w Paywallu pojawia się komunikat o błędzie. Ten scenariusz jest obsługiwany dla wszystkich metod płatności pay-by-link z wyjątkiem mTransfer.

Karty

Aby symulować płatność kartą, możesz użyć danych karty:

Płatność zakończona sukcesem

Card number: 4444 4444 4444 4000
Card name: dowolna
Card date: dowolna w przyszłości
CVC: 111

Nagłówek podpisu (Signature header)

Aby zapewnić integralność wymienianych wiadomości i potwierdzić, że ich zawartość nie została zmodyfikowana podczas transmisji, należy dołączyć dodatkowy nagłówek: Signature do wysyłanych zapytań POST oraz GET i zweryfikować go w otrzymanych odpowiedziach.

Obliczanie podpisu

Obiekt z paczką danych, dla którego obliczamy podpis, powinien zostać skonstruowany z następujących elementów (zwróć uwagę na ich kolejność):

• headers - Api-Key (dostęony w Panelu Merchanta) oraz Idempotency-Key (unikalna wartość żądania). Nagłówki powinny być używane w kolejności alfabetycznej. Nie używaj innych nagłówków podczas obliczania podpisu,
• parameters - lista użytych parametrów żądania w kolejności alfabetycznej. Jeśli nie ma parametrów, użyj pustej mapy parametrów: parameters: ,
• body - powinno być wyrażone jako string object: "body":"" i sformatowane w następujący sposób tabulacja powinna być wyrażona jako \t, nowe linie jako \n (UNIX) lub \r\n (Microsoft Windows). Cudzysłowy powinny być escapowane: np.: "response_type".

Przykład obiektu paczki danych do pobrania metod płatności:

{
  "headers": {
    "Api-Key": "97a55694-5478-43b5-b406-fb49ebfdd2b5",
    "Idempotency-Key": "d243fdb3-c287-484a-bb9c-58536f2794c1"
  },
  "parameters": {},
  "body": ""
}

Podpis powinien zostać obliczony przy użyciu algorytmu HMAC SHA256 wykorzystując przygotowaną paczkę danych oraz Signature-Key. Wynik w postaci binarnej funkcji hash powinien zostać zakodowany przy użyciu Base64 i być wysłany do Paynow w nagłówku Signature.

Dla powyższej przykładowej paczki danych i Signature-Key o wartości b305b996-bca5-4404-a0b7-2ccea3d2b64b, obliczony i zakodowany podpis powinien przyjąć następującą wartość: fXwLZRwo0WiGll90PPl5oULX9VKA0gpFA/3+E+NRp5E=.

Wskazówka

Pamiętaj, że znaki nowych linii, tabulatorów i spacji muszą znajdować się dokładnie w tych samych miejscach, co w paczce danych w żądaniu.

Przykład dla obliczania podpisu z wykorzystaniem PHP SDK:

$idempotencyKey = '';
$body = [];
$parameters = []
$signature = SignatureCalculator::generateV3(
    '97a55694-5478-43b5-b406-fb49ebfdd2b5',
    'b305b996-bca5-4404-a0b7-2ccea3d2b64b,
    $idempotencyKey,
    $body ? json_encode($body, JSON_UNESCAPED_SLASHES) : '',
    $parameters
);

Powiadomienia

Podczas procesu płatności Paynow dostarcza asynchroniczne powiadomienia o aktualnym statusie płatności za każdym razem, gdy status zostanie zmieniony. Powiadomienia są wysyłane na podany notification-url jako żądanie HTTP POST.

Aby włączyć powiadomienia, należy określić notification-url w Panelu Merchanta w zakładce Ustawienia > Sklepy i punkty płatności, wypełniając pole Adres powiadomień w konfiguracji sklepu.

Przykład wiadomości powiadomienia:

Dla poniższej przykładowej paczki danych i Signature-Key o wartości b305b996-bca5-4404-a0b7-2ccea3d2b64b, obliczony i zakodowany podpis powinien przyjąć następującą wartość: F69sbjUxBX4eFjfUal/Y9XGREbfaRjh/zdq9j4MWeHM=.

  curl -X POST \
  <notification-url> \
  -H 'Signature: F69sbjUxBX4eFjfUal/Y9XGREbfaRjh/zdq9j4MWeHM=' \
  -H 'Content-Type: application/json' \
  -d \
  '{
    "paymentId": "NOLV-8F9-08K-WGD",
    "externalId": "9fea23c7-cd5c-4884-9842-6f8592be65df",
    "status": "CONFIRMED",
    "modifiedAt": "2018-12-12T13:24:52"
  }'

Podpis dla powiadomień

Podpis powinien zostać obliczony przy użyciu algorytmu HMAC SHA256 wykorzystując przygotowaną paczkę danych oraz Signature-Key. Wynik w postaci binarnej funkcji hash powinien zostać zakodowany przy użyciu Base64 i być wysłany do Paynow w nagłówku Signature.

Przykłady dla obliczania podpisu dla powiadomień:

PHP SDK

$signatureCalculator = new SignatureCalculator(
  'b305b996-bca5-4404-a0b7-2ccea3d2b64b',
  json_encode([
    'paymentId' => 'NOLV-8F9-08K-WGD',
    'externalId' => '12345',
    'status' => 'CONFIRMED',
    'modifiedAt' => '2018-12-12T13:24:52',
  ], JSON_UNESCAPED_SLASHES)
);

Java

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.security.InvalidKeyException;
import java.security.NoSuchAlgorithmException;
import java.util.Base64;

public class HashCalculator {

    private static final String HMAC_SHA256_ALGORITHM_NAME = "HmacSHA256";

    public static void main(String[] args) throws Exception {
        String dataToHash =
                '{"paymentId":"NOLV-8F9-08K-WGD","externalId":"12345","status":"CONFIRMED","modifiedAt":"2018-12-12T13:24:52"}';
        String key = "b305b996-bca5-4404-a0b7-2ccea3d2b64b";
        String hmacHash = calculateHMAC(dataToHash.getBytes(), key.getBytes());
        System.out.println(hmacHash);
    }

    private static String calculateHMAC(byte[] data, byte[] key)
            throws NoSuchAlgorithmException, InvalidKeyException {
        SecretKeySpec signingKey = new SecretKeySpec(key, HMAC_SHA256_ALGORITHM_NAME);
        Mac mac = Mac.getInstance(HMAC_SHA256_ALGORITHM_NAME);
        mac.init(signingKey);
        byte[] hashedBytes = mac.doFinal(data);
        return Base64.getEncoder().encodeToString(hashedBytes);
    }
}

Python

import hmac
import hashlib
import base64

data_to_hash = '{"paymentId":"NOLV-8F9-08K-WGD","externalId":"12345","status":"CONFIRMED","modifiedAt":"2018-12-12T13:24:52"}'
key = 'b305b996-bca5-4404-a0b7-2ccea3d2b64b'


def calculate_hmac(data, key):
    hashed_object = hmac.new(key, data, hashlib.sha256).digest()
    return base64.b64encode(hashed_object)


hmac_hash = calculate_hmac(data_to_hash.encode(), key.encode())
print(hmac_hash.decode())

Weryfikacja nagłówka podpisu w otrzymanych wiadomościach

Za każdym razem, gdy Paynow wysyła powiadomienie, Twój system musi zweryfikować integralność przychodzącej wiadomości, weryfikując ją.
NIE PRZETWARZAJ tej wiadomości jeśli obliczony podpis nie odpowiada wartości obecnej w nagłówku Signature.

Harmonogram powiadomień

Po wysłaniu powiadomienia system Paynow wymaga odpowiedzi HTTP ze statusem 200 OK lub 202 Accepted (z pustym body). Jeśli Paynow nie otrzyma prawidłowej odpowiedzi, spróbuje ponownie dostarczyć powiadomienie zgodnie z następującym harmonogramem:

Próba	Czas od zmiany statusu(przyrostowo)
1	natychmiast
2	1min
3	1min
4	1min
5	2min
6	5min
7	15min
8	30min
9	1h
10	2h
11	4h
12	8h
13	16h
14	24h
15	48h

Jeśli z jakiegoś powodu powiadomienie nie może zostać pomyślnie dostarczone, Merchant powinien synchronicznie sprawdzić status transakcji przez endpoint statusu płatności aby sprawdzić ostateczny status płatności.

Ważne

Pamiętaj, że to samo powiadomienie może zostać wysłane więcej niż raz i że powiadomienia mogą dotrzeć do Twojego endpointu w niewłaściwej kolejności. Twój kod musi być przygotowany na takie scenariusze.

Sprawdź to

Jeśli Twój system filtruje ruch przychodzący, skontaktuj się z naszym działem pomocy technicznej pod adresemsupport@paynow.pl aby uzyskać listę adresów IP, które powinieneś dodać do swojej białej listy.

Harmonogram wypłat

Możesz wybrać jeden z dwóch wariantów częstotliwości wypłat na swoje konto bankowe::

Wariant	Opis
natychmiast	Otrzymaj wypłatę natychmiast po zakończeniu transakcji przez kupującego (dostępne tylko dla klientów detalicznych mBanku)
dziennie	Środki gromadzone są na Twoim koncie, wypłata odbywa się raz dziennie.

Harmonogram wypłat możesz skonfigurować w Panelu Merchanta, w zakładce, Ustawienia > Harmonogram wypłat.

Ważne

Pamiętaj, że wypłaty nie są możliwe, jeśli korzystasz z mechanizmu Mass Collect raz dziennie.

SDK oraz Pluginy

Wszystkie dostępne wtyczki oraz Software Development Kits(SDK) są dostępne w serwisie GitHub:

• PHP SDK
• WooCommerce plugin
• Prestashop plugin
• Opencart plugin
• Magento 2

Kolekcje Postmana

Proszę, sprawdź naszą Kolekcję przykładów Postman z podstawowymi żądaniami, które mogą pomóc Ci w tworzeniu pierwszych zapytań w naszym API w środowisku Sandbox.