Materiały referencyjne API

Dokumentacja API Verification of Payee

Uwierzytelnianie, punkt końcowy weryfikacji, ładunki żądania i odpowiedzi, kody zgodności schematu SEPA oraz obsługa błędów - wszystko, czego programista potrzebuje do integracji weryfikacji IBAN/nazwy, wraz z gotowymi do skopiowania przykładami JSON i cURL.

POST {BASE_URL}/vop/v1/verify
Uwierzytelnianie
Token Bearer (OAuth 2.0)
Format danych
application/json

Bazowy adres URL i dane uwierzytelniające API są przekazywane podczas wdrożenia - skontaktuj się z nami, aby je otrzymać.

API Verification of Payee to pojedynczy uwierzytelniony punkt końcowy REST: wysyłasz żądaniem POST nazwę odbiorcy i IBAN, a w czasie rzeczywistym otrzymujesz znormalizowany wynik zgodności. Poniższe przykłady mają charakter poglądowy; dokładny bazowy adres URL i dane uwierzytelniające są przekazywane podczas wdrożenia.

Uwierzytelnianie

Każde żądanie jest uwierzytelniane za pomocą tokenu Bearer przez HTTPS. Token należy przesyłać w nagłówku Authorization; tokeny są wydawane osobno dla każdego środowiska (sandbox i produkcja).

Te same dane uwierzytelniające odblokowują również panel RoxBusiness, w którym można wykonywać doraźne weryfikacje bez pisania kodu.

Nagłówki HTTP 
Authorization: Bearer <YOUR_API_TOKEN>
Content-Type: application/json

Żądanie

Wyślij żądaniem POST treść JSON zawierającą nazwę odbiorcy i IBAN. Dla osób prawnych możesz dodatkowo przesłać identyfikator organizacji (np. włoski numer Partita IVA / Codice Fiscale) oraz opcjonalny external_id do celów uzgadniania.

Treść żądania

Pole Typ Wymagane Opis
name string Wymagane Nazwa odbiorcy do zweryfikowania, dokładnie tak jak wprowadził ją płatnik.
iban string Wymagane IBAN docelowy (weryfikowany pod względem formatu i sumy kontrolnej przed wywołaniem schematu).
account_type enum Opcjonalne NATURAL_PERSON lub LEGAL_PERSON. Pomaga bankowi odpowiadającemu poprawnie dopasować dane.
organisation_id string Opcjonalne Numer VAT / identyfikator podatkowy dla osób prawnych (np. Partita IVA). Weryfikowany względem zarejestrowanego posiadacza.
external_id string Opcjonalne Twój własny identyfikator referencyjny, zwracany w odpowiedzi w celu uzgadniania.
Treść żądania 
{
  "name": "ACME Trading S.r.l.",
  "iban": "IT60X0542811101000000123456",
  "account_type": "LEGAL_PERSON",
  "organisation_id": "IT01524770524",
  "external_id": "invoice-2025-00842"
}
cURL 
curl -X POST "$BASE_URL/vop/v1/verify" \
  -H "Authorization: Bearer $ROXPAY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "ACME Trading S.r.l.",
    "iban": "IT60X0542811101000000123456",
    "account_type": "LEGAL_PERSON",
    "organisation_id": "IT01524770524",
    "external_id": "invoice-2025-00842"
  }'

Odpowiedź

Odpowiedź 200 zwraca znormalizowany wynik, kod zgodności schematu SEPA, BIC banku odpowiadającego oraz czas przetwarzania. W przypadku częściowej zgodności zweryfikowana nazwa jest zwracana w polu suggested_name.

Treść odpowiedzi

Pole Typ Opis
verification_id string Unikalny identyfikator tej weryfikacji, do wykorzystania w Twoim dzienniku audytowym.
result enum MATCH, CLOSE_MATCH, NO_MATCH lub NOT_APPLICABLE.
scheme_code string Kod schematu SEPA VoP: MTCH, CMTC, NMTC lub NOAP.
suggested_name string Przy CLOSE_MATCH zweryfikowana nazwa posiadacza rachunku, którą warto zaproponować płatnikowi.
responding_bic string BIC instytucji, która odpowiedziała na weryfikację.
processing_time_ms integer Czas przetwarzania po stronie odpowiadającego PSP, w milisekundach.
external_id string Twój identyfikator referencyjny, zwracany bez zmian.
200 OK 
{
  "verification_id": "vop_3f9a1c2e7b",
  "result": "CLOSE_MATCH",
  "scheme_code": "CMTC",
  "suggested_name": "ACME Trading SRL",
  "responding_bic": "BCITITMMXXX",
  "processing_time_ms": 412,
  "external_id": "invoice-2025-00842"
}

Kody wyniku zgodności

Każda odpowiedź odpowiada jednemu z czterech kodów schematu SEPA VoP. Rozgałęziaj logikę na podstawie scheme_code, aby pozostała stabilna.

Kod Wynik Znaczenie Zalecane działanie
MTCH MATCH Nazwa zgadza się z posiadaczem rachunku. Kontynuuj z pewnością.
CMTC CLOSE_MATCH Niemal poprawna (np. nazwa handlowa a nazwa prawna). Wyświetl suggested_name; poproś płatnika o potwierdzenie.
NMTC NO_MATCH Nazwa nie należy do tego IBAN. Twarde zatrzymanie - ostrzeż i zablokuj automatyczne zatwierdzenie.
NOAP NOT_APPLICABLE Weryfikacja niemożliwa. Poinformuj płatnika; pozostaw mu decyzję.

Obsługa błędów

NO_MATCH to prawidłowy wynik 200, a nie błąd - nigdy nie traktuj go jako awarii transportu. Rzeczywiste błędy używają kodów statusu 4xx/5xx wraz z kodem błędu odczytywalnym maszynowo oraz request_id na potrzeby wsparcia.

HTTP Kod błędu Kiedy występuje
400 invalid_iban IBAN nie przeszedł walidacji formatu lub sumy kontrolnej.
400 missing_field Brakuje wymaganego pola (name lub iban).
401 unauthorized Brak lub nieprawidłowy token Bearer.
429 rate_limited Zbyt wiele żądań - zastosuj mechanizm opóźnienia wykładniczego (backoff) i spróbuj ponownie.
503 scheme_unavailable Schemat VoP / odpowiadający PSP jest tymczasowo niedostępny.
400 Bad Request 
{
  "error": "invalid_iban",
  "message": "The 'iban' field failed checksum validation.",
  "request_id": "req_8a2b1f0c"
}

Integracja w czterech krokach

Standardowa integracja REST, którą włączysz w istniejący proces płatności.

  1. 1

    Uzyskaj dane uwierzytelniające

    Przejdź proces wdrożenia i otrzymaj token Bearer oraz bazowy adres URL dla środowiska sandbox i produkcyjnego.

  2. 2

    Wywołaj /verify

    Wyślij żądaniem POST nazwę odbiorcy i IBAN, z opcjonalnym external_id i organisation_id.

  3. 3

    Odczytaj scheme_code

    Rozgałęź logikę na MTCH / CMTC / NMTC / NOAP i zapisz verification_id.

  4. 4

    Podejmij działanie w swoim UI

    Pokaż płatnikowi jasny sygnał albo uzależnij wykonanie przelewu lub mandatu od wyniku.

Materiały referencyjne API

FAQ dla programistów

Pytania, które zespoły integracyjne zadają jako pierwsze.

Treść JSON zawierająca name i iban (wymagane), a także opcjonalne account_type, organisation_id (numer VAT / identyfikator podatkowy dla osób prawnych) oraz Twój external_id. Zobacz przykład żądania powyżej.

NO_MATCH (kod schematu NMTC) to prawidłowa odpowiedź 200, a nie błąd. Traktuj ją jako twarde zatrzymanie: ostrzeż płatnika, zablokuj automatyczne zatwierdzenie i wymagaj ponownej weryfikacji przed wysłaniem.

Tak. Tokeny są wydawane osobno dla każdego środowiska, dzięki czemu możesz integrować się i testować w sandbox przed przełączeniem bazowego adresu URL na produkcję.

Tak - wyślij organisation_id razem z account_type LEGAL_PERSON. Pomaga to, gdy nazwa handlowa różni się od nazwy zarejestrowanej.

Wyślij w żądaniu własny external_id; jest on zwracany bez zmian, a każda odpowiedź zawiera także unikalny verification_id.

Czytaj dalej

API Verification of Payee Przegląd, odbiorcy i przypadki użycia. RoxPay Verification of Payee Jak usługa jest dostarczana w RoxPay. Słownik pojęć Terminy VoP, SEPA i kody schematów.

Uzyskaj dane uwierzytelniające API

Przejdź proces wdrożenia do schematu SEPA VoP dzięki jednej integracji REST i wdróż się przed swoim terminem.

Porozmawiaj z ekspertem O API VoP