Najpierw przeczytaj dokumentację. Po to jest.

Szybki start

Krócej, niż się spodziewasz

Jeden base URL, jeden nagłówek. Klucze API wydaje nasz zespół i przekazuje bezpiecznym kanałem — nie ma samoobsługowego generowania kluczy i nie będzie, dopóki nie da się tego zrobić bez osłabienia onboardingu.

# Sandbox
https://api.sandbox.bergopay.com/

Uwierzytelnianie zapytań

Każdy uwierzytelniony endpoint oczekuje tokenu bearer. To cała historia uwierzytelniania.

Authorization: Bearer {YOUR_AUTH_KEY}
Content-Type: application/json
Accept: application/json

Koperta odpowiedzi

Każda odpowiedź niesie te same cztery klucze, niezależnie od powodzenia. Sprawdzaj success, a przy wartości false czytaj code.

{
  "success": true,
  "message": "Transaction initiated",
  "code": "",
  "data": { ... }
}

Sprawdź swój klucz

Zwraca to, do czego uprawnia posiadany klucz. Przydatne pierwsze wywołanie, gdy coś zachowuje się nieoczekiwanie.

3-D Secure

Dziś nie będziesz obsługiwać CAVV

3DS jest zarządzane po stronie serwera. Nigdy nie budujesz ani nie przechowujesz CAVV, ECI czy DS Transaction ID — weryfikujesz, dostajesz id i przekazujesz id.

• Krok 1 — wywołaj endpoint weryfikacji z danymi karty, kwotą, walutą i swoim URL powrotnym
• Krok 2 — ścieżka frictionless zwraca od razu status: full_auth; challenge zwraca challenge_url
• Krok 3 — po challenge posiadacz karty wraca na Twój URL z identyfikatorem weryfikacji i statusem
• Krok 4 — zainicjuj transakcję z tym id w card_verification_data

{
  "amount": 12.5,
  "currency": "EUR",
  "card": {
    "name": "John Doe",
    "number": "4200000000000091",
    "exp_month": "12",
    "exp_year": "2030",
    "cvv": "123"
  },
  "auth_url": "https://yoursite.com/checkout/3ds-complete"
}

// 200 — frictionless
{
  "success": true,
  "data": {
    "id": 166,
    "status": "full_auth",
    "auth_type": "frictionless",
    "version": "2.2.0",
    "eci": "05"
  }
}

Przenieś to id do transakcji, a zapisane dane uwierzytelnienia zostaną dołączone za Ciebie.

Endpointy merchanta

Pięć wywołań pokrywa cały cykl życia płatności kartą

Zainicjuj transakcję

sale obciąża od razu. auth zakłada blokadę i wymaga capture, żeby się rozliczyć. Wybieraj świadomie — różnica ujawnia się w profilu zwrotów i sporów miesiące później.

{
  "amount": 12.5,
  "currency": "EUR",
  "transaction_type": "sale",
  "card": {
    "number": "4111111111111111",
    "exp_month": "12",
    "exp_year": "2030",
    "cvv": "111",
    "name": "John Doe"
  },
  "reference": "order-10001",
  "success_url": "https://yoursite.com/checkout/success",
  "error_url": "https://yoursite.com/checkout/error",
  "customer": {
    "merchant_customer_id": "cust-001",
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@example.com",
    "country_code": "PL",
    "ip_address": "198.51.100.5"
  },
  "card_verification_data": { "id": 43 }
}

Użyj vault_token zamiast obiektu karty, żeby obciążyć zapisany instrument. reference to Twój numer zamówienia i wraca w każdym powiązanym rekordzie.

// 200
{
  "success": true,
  "message": "Transaction initiated",
  "data": {
    "id": 2,
    "amount": 1250,
    "currency": "EUR",
    "status": "auth",
    "transaction_type": "auth",
    "merchant_trans_id": "ORDER-912346",
    "acquirer_trans_id": "514009741995",
    "acquirer_auth_code": "400066"
  }
}

Capture

Dotyczy wyłącznie transakcji typu auth. Podaj amount, żeby wykonać capture częściowy.

Zwrot

{ "amount": 12.5, "reason": "Customer returned item" }

Void

Anuluje autoryzację, zanim się rozliczy. Taniej i czyściej niż zwrot po fakcie.

Status

Statusy zwracane przez API to m.in. auth, captured, refunded i voided. Klucze partnerskie mogą odczytywać status akceptantów, z którymi są powiązane.

Endpointy partnera

Masz już bramkę. Nie będziemy Ci wysyłać checkoutu.

Klucze partnerskie zarządzają powiązanymi akceptantami. Zachowujesz własny checkout, tokenizację i identyfikatory akceptantów; my siedzimy wyżej w łańcuchu. Jedna zasada warta zapamiętania od razu: capture, zwrot i void pozostają wyłącznie po stronie merchanta, nawet gdy klucz partnerski może odczytać status.

Lista powiązanych akceptantów

Pobierz pojedynczego akceptanta

Transakcje akceptanta

Filtruj przez status, from, to i per_page. Maksymalny rozmiar strony to 100.

GET /api/v1/merchants/1/transactions
  ?status=success
  &from=2026-01-01
  &to=2026-12-31
  &per_page=25

Inicjowanie w imieniu akceptanta

Klucze partnerskie mogą wywoływać endpoint transakcji, ale muszą podać merchant_id akceptanta powiązanego z tym partnerem.

{
  "amount": 129.00,
  "currency": "EUR",
  "transaction_type": "sale",
  "merchant_id": 123,
  "card": { ... },
  "reference": "YOUR-ORDER-4471"
}

Kaskadowanie i ponowienia podlegają limitom opublikowanym na stronie bramki — nigdy jako obejście 3-D Secure, nigdy ponad limity ponowień organizacji kartowych.

Błędy

Błąd powinien mówić, co zrobić dalej

Niepowodzenia używają tej samej koperty, z maszynowo czytelnym code, a przy problemach walidacyjnych z obiektem errors per pole.

// 401
{
  "success": false,
  "message": "Authentication failed",
  "code": "ERR_AUTH_FAILED",
  "data": null
}

// 422
{
  "success": false,
  "message": "Validation errors",
  "code": "ERR_VALIDATION_FAILED",
  "data": null,
  "errors": {
    "amount": ["The transaction amount must be a number."]
  }
}

Rozgałęziaj logikę na code, nie na message. Komunikaty są pisane dla ludzi i mogą zostać przeredagowane.

Testowanie

Karty testowe na każdy zły dzień

Używaj ich na endpointcie weryfikacji 3DS. Testuj ścieżki nieudane — to właśnie one docierają do Twoich klientów.

Pełny zestaw obejmuje dalsze warianty frictionless i challenge, uwzględniające zwracanie danych metody. Napisz, a wyślemy kompletną listę razem z kluczem do sandboxa.