Jak zintegrować się z Perno Orchestration przez API?

Zanim zaczniesz: dwa różne sekrety

Integracja z Orchestration korzysta z dwóch oddzielnych sekretów, które łatwo pomylić:

Transaction Signing Key znajdziesz w ustawieniach Orchestration (kontekst Perno Orchestration → Perno Orchestration w lewym sidebarze), razem z domyślną bramką płatności, adresami powrotu (Default/Success/Cancel Return URL) i adresami powiadomień (Transaction i Payment Link Notification URL). Pola return_url* i notification_url w API są opcjonalne właśnie dlatego - jeśli ich nie podasz, Perno użyje wartości ustawionych tutaj.

Krok 1: sprawdź lub utwórz konto sprzedawcy

Pobierz listę kont sprzedawców podpiętych do Twojego konta Orchestration:

curl -X GET "https://perno.io/api/v1/orchestration/merchant-accounts/" \
  -H "Authorization: Token YOUR_API_TOKEN"

Znajdź w odpowiedzi konto z polem "default": true - to na nie trafi płatność, jeśli w linku płatniczym nie wskażesz innego. Zobacz pełny opis w dokumentacji: Retrieve merchant accounts.

Jeśli wolisz utworzyć konto sprzedawcy programistycznie zamiast w panelu, użyj Create merchant account:

curl -X POST "https://perno.io/api/v1/orchestration/merchant-accounts/" \
  -H "Authorization: Token YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "merchant_account_name": "Stripe EU",
    "payment_gateway": "stripe",
    "payment_gateway_type": {"type": "production"},
    "default": true,
    "api_data_1": "sk_live_..."
  }'

supported_currencies, supported_languages, supported_countries i supported_payment_methods to tablice identyfikatorów odnoszące się do słowników Perno, nie kody tekstowe. Najprościej skonfigurować je raz w panelu (Jak dodać konto sprzedawcy w Perno?), a potem odczytać gotowe wartości przez GET - albo sprawdzić kody metod płatności w kroku 2 poniżej.

Aby zmienić, które konto jest domyślne, wywołaj Set default merchant account:

curl -X POST "https://perno.io/api/v1/orchestration/merchant-accounts/{account_id}/set-default/" \
  -H "Authorization: Token YOUR_API_TOKEN"

Krok 2: sprawdź dostępne metody płatności

Jeśli budujesz własny checkout i chcesz z góry pokazać klientowi dostępne metody płatności (zamiast kierować go od razu na hostowaną stronę Perno), pobierz je z List payment methods:

curl -X GET "https://perno.io/api/v1/orchestration/payment-methods/?merchant_account_id=1¤cy=PLN&amount=10.00" \
  -H "Authorization: Token YOUR_API_TOKEN"

Odpowiedź to lista obiektów {code, name, active, sequence}. Endpoint przyjmuje też opcjonalne country, language i payment_gateway_type (production lub sandbox), więc możesz zawęzić wynik do tego, co faktycznie zobaczy dany klient.

Krok 3: podpisz i utwórz link płatniczy

Tworzenie linku płatniczego wymaga poprawnej wartości trx_hash, obliczonej z użyciem Transaction Signing Key:

trx_hash = SHA256("|" + amount + "|" + trx_id + "|" + transaction_signing_key)

Perno przelicza ten sam hash po swojej stronie i porównuje wynik - jeśli się nie zgadza, żądanie zostaje odrzucone z błędem Wrong hash. Przykład w Pythonie:

import hashlib

def build_trx_hash(amount, trx_id, transaction_signing_key):
    raw = f"|{amount}|{trx_id}|{transaction_signing_key}"
    return hashlib.sha256(raw.encode()).hexdigest()

Mając poprawny trx_hash, wywołaj Create payment link:

curl -X POST "https://perno.io/api/v1/payment_links/" \
  -H "Authorization: Token YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "merchant_account": 1,
    "amount": "10.00",
    "currency": "PLN",
    "trx_id": "order-4821",
    "trx_hash": "…obliczony hash…",
    "customer_email": "[email protected]",
    "one_time_link": true
  }'

Pole merchant_account możesz pominąć - wtedy Perno użyje konta domyślnego z kroku 1. To samo dotyczy return_url, return_url_success, return_url_cancel i notification_url - podawaj je tylko wtedy, gdy dla tej konkretnej płatności potrzebujesz innych adresów niż domyślne z ustawień Orchestration. one_time_link: true blokuje ponowne użycie linku po opłaceniu. Odpowiedź zawiera payment_hash - unikalny identyfikator utworzonego linku.

Krok 4: udostępnij link klientowi

API nie zwraca gotowego adresu URL do wklejenia klientowi - zarządza samym rekordem. Link utworzony przez API pojawia się na tej samej liście co linki tworzone ręcznie: w panelu, w kontekście Perno Orchestration → Payment links, każdy wpis ma własny hostowany adres w kolumnie Link - skopiuj go stamtąd i wyślij klientowi (zobacz Jak zarządzać linkami płatniczymi w Perno?). Po otwarciu link prowadzi do strony płatności z podsumowaniem kwoty oraz metodami płatności takimi jak karta, Apple Pay, Revolut Pay czy Klarna.

Krok 5: potwierdź płatność

Najlepszy sposób to webhook: skonfigurowany w ustawieniach Orchestration Payment Link Notification URL jest wywoływany, gdy status linku się zmienia, więc Twój endpoint dowiaduje się o płatności bez odpytywania. Jeśli w ustawieniach włączona jest opcja Send multiple webhooks, licz się z tym, że to samo zdarzenie może dotrzeć więcej niż raz - obsługa webhooka powinna być idempotentna (np. na podstawie trx_id lub payment_hash).

Jeśli wolisz (albo dodatkowo chcesz) sprawdzić status samodzielnie, pobierz szczegóły linku przez Get payment link details:

curl -X GET "https://perno.io/api/v1/payment-links/{payment_hash}/" \
  -H "Authorization: Token YOUR_API_TOKEN"

Pole used zmienia się na true, gdy link został opłacony (lub wykorzystany, jeśli to link jednorazowy). Pełny, szczegółowy rekord płatności - z bramką, statusem (np. paid, pending, need 3ds) i powiązaniem z linkiem płatniczym - zobaczysz w panelu, w widoku Transactions (zobacz Czym jest transakcja w Perno Orchestration?); w API v1 transakcje nie są jeszcze udostępnione jako osobny zasób.

Krok 6: monitoruj integrację

Do sprawdzania, czy endpointy linków płatniczych działają, użyj Health check payment links API - dobry kandydat do własnego monitoringu uptime:

curl -X GET "https://perno.io/api/v1/payment_links/health_check" \
  -H "Authorization: Token YOUR_API_TOKEN"

Podsumowanie przepływu

• Skonfiguruj konto sprzedawcy i Transaction Signing Key (raz).
• Sprawdź domyślne konto sprzedawcy i, opcjonalnie, dostępne metody płatności.
• Policz trx_hash i utwórz link płatniczy dla zamówienia.
• Pobierz jego adres z panelu i wyślij klientowi.
• Odbierz webhook albo sprawdź pole used, żeby potwierdzić płatność.