To jest API V1, które nie jest już utrzymywane

Aby zapoznać się z aktualną dokumentacją, zobacz najnowszą wersję.

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 i zweryfikować go w otrzymanych odpowiedziach.

Obliczanie podpisu

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ład paczki danych do tworzenia płatności:

{
  "amount": 12345,
  "externalId": "12345",
  "description": "Payment description",
  "buyer": {
    "email": "jan.kowalski@melements.pl"
  }
}

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łady dla obliczania podpisu:

PHP SDK

$signatureCalculator = new SignatureCalculator(
  'b305b996-bca5-4404-a0b7-2ccea3d2b64b',
  json_encode([
    'amount' => '12345',
    'externalId' => '12345',
    'description' => 'Payment description',
    'buyer' => [
      'email' => 'jan.kowalski@melements.pl'
    ]
  ])
);

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 = "{\n"
                + "  \"amount\": \"12345\",\n"
                + "  \"externalId\": \"12345\",\n"
                + "  \"description\": \"Payment description\",\n"
                + "  \"buyer\": {\n"
                + "    \"email\": \"jan.kowalski@melements.pl\"\n"
                + "  }\n"
                + "}";
        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 = {
    "amount": "12345",
    "externalId": "12345",
    "description": "Payment description",
    "buyer": {
        "email": "jan.kowalski@melements.pl"
    }
}
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())

C#*

using System;
using System.Security.Cryptography;

public class HashCalculator {

    public static void Main() {
        string dataToHash = @"{
           'amount': '12345',
           'externalId': '12345',
           'description': 'Payment description',
           'buyer': {
             'email': 'jan.kowalski@melements.pl'
           }
         }";
        String key = "b305b996-bca5-4404-a0b7-2ccea3d2b64b";
        var encoder = new System.Text.UTF8Encoding();
    
        String hmacHash = calculateHMAC(encoder.GetBytes(dataToHash), encoder.GetBytes(key));
        Console.WriteLine(hmacHash);
    }
    
    private static string calculateHMAC(byte[] data, byte[] key) {
        var hmacsha256 = new HMACSHA256(key);
        byte[] hashmessage = hmacsha256.ComputeHash(data);
        return Convert.ToBase64String(hashmessage);
    }
}

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:

  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"
  }'

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.