Na tej stronie znajdziesz informacje na temat onboardingu i aktualizacji submerchanta, a także, jak radzić sobie z błędami i sprawdzać kody statusu webhooka.

Onboarding Merchanta

Proces wdrażania oparty na API (FULL CODE) eliminuje potrzebę ręcznego wdrażania poprzez automatyczne generowanie submerchantów, placówek, cenników, terminali i odpowiadających im danych uwierzytelniających.

Sprawdź poniżej dostępne endpointy środowiska:

Środowisko	URL	Metoda działania i endpointy	Opis działania
PROD	api.sibsgateway.com	POST api/onboarding/version-id/ sponsored-merchant	Aby zainicjować ten proces, należy wykonać żądanie POST z następującymi danymi.
TEST	stargate-cer.qly.site1.sibs.pt	POST api/onboarding/version-id/ sponsored-merchant	Aby zainicjować ten proces, należy wykonać żądanie POST z następującymi danymi.
Sandbox	sandbox.sibsgateway.com	POST api/onboarding/version-id/ sponsored-merchant	Aby zainicjować ten proces, należy wykonać żądanie POST z następującymi danymi.

Aby zainicjować ten proces, należy wykonać żądanie POST z następującymi danymi.

Parametry nagłówka:

Parametr	Typ	Stan	Opis
Typ zawartości	Ciąg	Obowiązkowe	application/json.
X-Request-ID	Ciąg	Obowiązkowe	Identyfikator żądania, unikalny dla połączenia, określony przez stronę inicjującą.
x-ibm-client-id	Ciąg	Obowiązkowe	Token identyfikujący organizację klienta. Jest on dostarczany podczas procesu wdrażania i musi być używany w każdym połączeniu.

Parametry żądania:

Element danych	Type Length	Stan	Opis
sprzedawca	Ciąg	Obowiązkowe	Object that defines the Merchant.
name	Ciąg <=90	Obowiązkowe	Pełna nazwa firmy zgodnie z danymi w CEIDG
phone	Ciąg <=16	Obowiązkowe	Numer telefonu firmy
email	Ciąg <=55	Obowiązkowe	Adres e-mail firmy
NIP	Ciąg 8<11	Obowiązkowe	NIP zgodnie z CEIDG
mcc	Numer 4-4	Obowiązkowe	Kod MCC firmy
pkd	Ciąg 7-7	Obowiązkowe	PKD spółki (główne) według danych CEIDG
merchantType	Ciąg “Merchant” “Sponsored Merchant” Default: “Sponsored Merchant”	Obowiązkowe	Rodzaj merchanta
address	Ciąg	Obowiązkowe	Adres merchanta
street	Ciąg <=70	Obowiązkowe	Ulica
postalcode	Ciąg <=25	Obowiązkowe	Kod pocztowy
locality	Ciąg <=20	Obowiązkowe	Miejscowość
country	Ciąg 3-3 Format ISO 3166, Number 3 code (ex: Poland – 616)	Obowiązkowe	Kraj
website	Ciąg <=100	Obowiązkowe	Adres strony www
signedAgreements	logiczna “True” “False”	Obowiązkowe	Potwierdzenie podpisanych umów
backofficeEmail	Ciąg <=55	Obowiązkowe	SIBS Backoffice email address
pepStatus	Ciąg “Active” “Inactive” Default: “Active”	Obowiązkowe	Potentially Exposed Person status
beneficialOwnersData	Ciąg <=40	Warunkowy	Dane beneficjentów rzeczywistych. Obowiązkowe tylko, jeśli status PEP to „Aktywny”
Właściciel	Ciąg	Obowiązkowe	Object that defines the Company’s Owner account. Możliwe jest dodanie więcej niż jednego wpisu dla tego parametru
name	Ciąg <=40	Obowiązkowe	Nazwa właściciela
phone	Ciąg <=16	Warunkowy	Numer telefonu właściciela Należy podać telefon lub adres e-mail (przynajmniej jeden z nich).
email	Ciąg <=55	Warunkowy	E-mail właściciela Należy podać telefon lub adres e-mail (przynajmniej jeden z nich).
address	Ciąg <=100	Opcionalnie	Adres właściciela
tin	Numer 8<11	Obowiązkowe	Numer NIP właściciela
integrationSupportContact	Ciąg	Opcionalnie	Object that defines an integration support contact
name	Ciąg <=20	Opcionalnie	Imię i nazwisko osoby kontaktowej ds. wsparcia integracji
phone	Ciąg <=16	Warunkowy	Numer telefonu Kontakt dla wsparcia integracji. Należy podać telefon lub adres e-mail (przynajmniej jeden z nich).
email	Ciąg <=55	Warunkowy	Adres e-mail Kontakt w sprawie wsparcia integracji. Należy podać telefon lub adres e-mail (przynajmniej jeden z nich).
sklep		Obowiązkowe	Object that defines the Establishment
name	Ciąg <=40	Opcionalnie	Nazwa establishmentu. Gdy to pole jest puste, uwzględniane będą wartości sparametryzowane na poziomie merchanta.
address	Ciąg	Opcionalnie	Establishment Address Gdy te pola są puste, uwzględniane będą wartości sparametryzowane na poziomie merchanta.
street	Ciąg <=70	Opcionalnie	Ulica
postalcode	Ciąg <=25	Opcionalnie	Postal Code
locality	Ciąg <=20	Opcionalnie	Locality
country	Ciąg 3-3 Format ISO 3166, Number 3 code (ex: Poland – 616)	Opcionalnie	Kraj
email	Ciąg <=55	Opcionalnie	Establishment Email Gdy te pola są puste, uwzględniane będą wartości sparametryzowane na poziomie merchanta.
phoneNumber	Ciąg <=16	Opcionalnie	Establishment Phone Gdy te pola są puste, uwzględniane będą wartości sparametryzowane na poziomie merchanta.
typ	Ciąg “Banks” “Wholesale“ “Supermarket“ “Retail“ “Gas Stations“ “Restaurants“ “Hotels“ “Virtual Establishment“ “Foreign“ “Service Provider“ “Service Entity“ “EMV Tolls“	Obowiązkowe	Establishment Type
mcc	Ciąg 4-4	Obowiązkowe	Establishment MCC
pkd	Ciąg 7 Format tego parametru będzie następujący: 00.00.A (zobacz listę: https://www.biznes.gov.pl/en/table-pkd-code)	Obowiązkowe	Establishment CAE
InvoiceIndicator	Ciąg “Payment Facilitator” “Sponsored Merchant” Default: “Payment Facilitator”	Obowiązkowe	Establishment Invoice Indicator
products	Ciąg	Obowiązkowe	Object that defines the Establishment Products
productId	Ciąg „XPAY-APPL-0-0”, „XPAY-GGLE-0-0”, „INTP-BLIK-0-0”, „INTP-BLIK-1-0”, „BLMD-PYBL-0-0”, „KEVN-PYBL-0-0”, „MCC-1-C”, „MCC-1-D”, „MCC-1-P”, „MCC-2-C”, „MCC-2-P”, „MCC-4-C”, „MCC-4-D”, „MCC-4-P”, „MSI-1-D”, „MSI-1-P”, „MSI-2-D”, „MSI-2-P”, „VIS-01-C”, „VIS-01-D”, „VIS-01-P”, „VIS-02-C”, „VIS-02-D”, „VIS-02-P”, „VPY-03-D”, „VPY-03-P”, „VSL-01-C”, „VSL-01-D”, „VSL-01-P”	Obowiązkowe	Metody płatności wybrane przez klienta. Product ID’s to activate: “INTP-BLIK-0-0” InterPay-BLIK-Domestic “INTP-BLIK-1-0” – InterPay-BLIK-OneClick “BLMD-PYBL-0-0” BlueMedia-PayByLink-Domestic “KEVN-PYBL-0-0” – PayByLink-Kevin “MCC-1-C” – Mastercard-Mastercard-Consumer-Credit “MCC-1-D” – Mastercard-Mastercard-Consumer-Debit “MCC-1-P” – Mastercard-Mastercard-Consumer-Prepaid “MCC-2-C” – Mastercard-Mastercard-Commercial-Credit “MCC-2-P” – Mastercard-Mastercard-Commercial-Prepaid “MCC-4-C” – Mastercard-Mastercard-Other-Credit “MCC-4-D” – Mastercard-Mastercard-Other-Debit “MCC-4-P” – Mastercard-Mastercard-Other-Prepaid “MSI-1-D” – Mastercard-Maestro-Consumer-Debit “MSI-1-P” – Mastercard-Maestro-Consumer-Prepaid “MSI-2-D” – Mastercard-Maestro-Commercial-Debit “MSI-2-P” – Mastercard-Maestro-Commercial-Prepaid “VIS-02-C” – VISA-VISA-Commercial-Credit “VIS-02-D” – VISA-VISA-Commercial-Debit “VIS-02-P” – VISA-VISA-Commercial-Prepaid “VIS-01-C” – VISA-VISA-Consumer-Credit “VIS-01-D” – VISA-VISA-Consumer-Debit “VIS-01-P” – VISA-VISA-Consumer-Prepaid “VPY-03-D” – VISA-VPAY-VPAY-Debit “VPY-03-P” – VISA-VPAY-VPAY-Prepaid “VSL-01-C” – VISA-VISA Electron-Consumer-Credit “VSL-01-D” – VISA-VISA Electron-Consumer-Debit “VSL-01-P” – VISA-VISA Electron-Consumer-Prepaid
productInvoiceIndicator	Ciąg “Payment Facilitator” “Sponsored Merchant” Default: “Payment Facilitator”	Opcionalnie	Product Invoice Indicator
paymentMethodType	Ciąg “Direct Debit” “Bank Transfer” Default: “Direct Debit”	Warunkowy	Typ metody płatności do fakturowania submerchanta. To pole jest obowiązkowe, jeśli wskaźnik faktury to “Submerchant”
invoiceEmail	Ciąg <=55	Warunkowy	Invoice email address. To pole jest obowiązkowe, jeśli wskaźnik faktury to “Submerchant”
payout	Ciąg	Warunkowy	Object that defines the Payout Information. To pole jest obowiązkowe, jeśli wskaźnik faktury to “Submerchant”
bankAccount	Ciąg 26-26	Warunkowy	Sponsored Merchants bank account To pole jest obowiązkowe, jeśli wskaźnik faktury to “Submerchant”
iban	Ciąg <=34	Warunkowy	Sponsored Merchants iban To pole jest obowiązkowe, jeśli wskaźnik faktury to “Submerchant”
bic	Ciąg 8<11	Warunkowy	Sponsored Merchants bic To pole jest obowiązkowe, jeśli wskaźnik faktury to “Submerchant”
numDaysPayout	Numer	Opcionalnie	Sponsored Merchants Payout Number of Days Zarezerwowane do wykorzystania w przyszłości.
maxPercentLowRiskExemptions	Numer <=100	Opcionalnie	Maksymalny procent wyłączeń niskiego ryzyka dopuszczalny w systemie lub procesie.
scaExemption	Ciąg Default „0”	Opcionalnie	Pole do oceny zwolnień SCA musi być wypełnione cyfrą 1, aby zezwolić i 0, aby nie zezwolić.
typeOfIntegration	Ciąg “S2S” “SDK” “Plugin” Default “S2S”	Obowiązkowe	Typ integracji submerchanta
webhookNotification	Object	Warunkowy	Obiekt definiujący szczegóły konfiguracji webhooka Obowiązkowe jeżeli typeOfIntegration jest “Plugin”.
typ	Ciąg “URL” “Email”	Warunkowy	Typ powiadomień webhook. Obowiązkowe jeżeli typeOfIntegration jest “Plugin”. Jeżeli “Plugin”, wartość musi być “URL”
Wartość	Ciąg	Warunkowy	Adres e-mail dostawy (dla typu e-mail) lub adres URL HTTP(S) Obowiązkowe jeżeli typeOfIntegration jest “Plugin”
supportEmail	Ciąg <=55	Warunkowy	Adres e-mail, na który wszystkie nieudane połączenia SPG Webhook będą zgłaszane do końca dnia. Obowiązkowe jeżeli typeOfIntegration jest “Plugin”
securityKey	Ciąg >=32	Opcionalnie	Pseudolosowy klucz symetryczny, który zostanie użyty do zaszyfrowania zawartości webhooka.

Ponizej znajduje się przykład żadania POST

{
    "merchant": {
        "name": "JOHN DOE",
        "phone": "505102923",
        "email": "fds@op.pl",
        "nip": "6831968575",
        "mcc": "5969",
        "pkd": "86.90.E",
        "merchantType": "Sponsored Merchant",
        "address": {
            "street": "UL IMAGINARY",
            "postalCode": "85-132",
            "locality": "BYDGOSZCZ",
            "country": "616"
        },
        "website": "www.yolo.pl",
        "signedAgreements": true,
        "backofficeEmail": "fds@op.pl",
        "pepStatus": "Inactive",
        "owners": [
            {
                "name": "JANE DOE",
                "phone": "505102923",
                "email": "fds@op.pl",
                "address": "UL UGORY 85-132 BYDGOSZCZ POLSKA",
                "tin": "6831968575"
            }
        ],
        "shop": {
            "name": "YOLO",
            "address": {
                "street": "UL IMAGINARY",
                "postalCode": "85-132",
                "locality": "BYDGOSZCZ",
                "country": "616"
            },
            "email": "fds@op.pl",
            "phoneNumber": "505102923",
            "type": "Retail",
            "mcc": "5969",
            "pkd": "86.90.E",
            "invoiceIndicator": "Payment Facilitator",
            "products": [
                {
                    "productId": "INTP-BLIK-0-0",
                    "productInvoiceIndicator": "Payment Facilitator"
                },
                {
                    "productId": "KEVN-PYBL-0-0",
                    "productInvoiceIndicator": "Payment Facilitator"
                }
            ],
            "paymentMethodType": "Bank Transfer",
            "invoiceEmail": "fds@op.pl",
            "payout": {
                "bankAccount": "50116022020000000127761999",
                "iban": "PL50116022020000000127761999",
                "bic": "BIGBPLPW",
                "numDaysPayout": 1.0
            },
            "typeOfIntegration": "S2S",
      	  "webhookNotification": {
        	  	"type": "URL",
        		"value": ""
      	  },
      	  "supportEmail": "",
      	  "securityKey": ""
        }
    }
}

Po wykonaniu tej czynności interfejs API (FULL CODE) odpowie jednym z dwóch poniższych kodów stanu:

Kod statusu	Wiadomość	TransactionStatus
000	Sukces	“ACT” (Accepted Technical Validation)
999	Unexpected Error	“RJT” (Rejected)

Oto przykład udanej odpowiedzi onboardingowej:

{
"transactionStatus": "ACT",
    "returnStatus": {
        "statusCode": "000" 
        "statusMsg": "Success",
        "statusDescription": "string"
    }
}

Otrzymasz również onboarding Webhook, który zawiera następujące szczegóły onboardingu sprzedawcy i dane uwierzytelniające.

Oto zredagowany przykład udanego powiadomienia Webhook:

{
    "NotifyRequest": {
        "TrackingId": "00caa675-f811-45ed-aee3-b84c22ac3efc",
        "TIN": "000****123",
        "MerchantId": "PL-000****123-1",
        "ShopId": "SH-PL-000000321",
        "TerminalId": "POS000159",
        "ErrCode": "CRM000",
        "ErrDesc": "Success",
        "Agreements": {
            "AgreementType": "PLKV"
        },
        "Credentials": {
            "ApiClientId": "2a69a780-****-****-****-1c6308af85f0",
            "ApiClientSecret": "K1rK*******************************0uU6",
            "TerminalToken": "0277a2c645e93c43f59ce867ee55498293*******5272db028ad9c9fa250edd04d9cac5d42910950e2acb82034093d14830e649c3d6df2cc0f92268f79"
         }
    }
}

Aktualizacja merchanta

Zapewniamy również możliwość aktualizacji informacji o merchancie za pośrednictwem naszego API. Prosimy o zapoznanie się z listą dostępnych environment endpoints:

Środowisko	URL	Metoda działania i endpointy	Opis działania
PROD	api.sibsgateway.com	PUT /sibs/onboarding/v1/sponsored-merchant/{merchant-id}	Aktualizuj zasób merchanta
CER	stargate-cer.qly.site1.sibs.pt	PUT /sibs/onboarding/v1/sponsored-merchant/{merchant-id}	Aktualizuj zasób merchanta
Sandbox	sandbox.sibsgateway.com	PUT /sibs/onboarding/v1/sponsored-merchant/{merchant-id}	Aktualizuj zasób merchanta

Aby rozpocząć ten proces, należy wykonać żądanie PUT zawierające następujące dane:

Parametry

Parametr	Typ	Stan	Wymagania	Opis
Typ zawartości	Ciąg	Obowiązkowe	Nagłowek	application/json
X-Request-ID	Ciąg	Obowiązkowe	Nagłowek	Żadanie indentyfikatora ID, unikalne do połączenia, określony przez stronę inicjującą.
merchant-id	Ciąg	Obowiązkowe	Ścieżka	ID sponsorowanego merchanta
x-ibm-client-id	Ciąg	Obowiązkowe	Nagłowek	Token identyfikujący organizację klienta. Jest on dostarczany podczas procesu onboardingu i musi być używany w każdym połączeniu.

The following details outline the parameters eligible for modification, including their data types, length constraints, update conditions, and brief descriptions:

Parametry zapytania

Element danych	Type Length	Stan	Opis
Phone	Ciąg <=16	Obowiązkowe	Company’s phone number
Email	Ciąg <=55	Obowiązkowe	Company’s email address
Address	Ciąg	Obowiązkowe	Adres merchanta
street	Ciąg <=100	Obowiązkowe	Ulica
postalcode	Ciąg <=25	Obowiązkowe	Merchant’s Address Postal Code
locality	Ciąg <=20	Obowiązkowe	Miejscowość
website	Ciąg <=100	Obowiązkowe	Adres strony www

Sprawdź poniżej przykład żadania PUT:

{
  "merchant": {
    "phone": "505102923",
    "email": "fds@op.pl",
    "address": {
      "street": "UL IMAGINARY",
      "postalCode": "85-132",
      "locality": "BYDGOSZCZ"
    },
    "website": "www.yolo.pl"
  }
}

After the request, the API will respond with one of the two status codes:

Kod statusu	Wiadomość	TransactionStatus
000	Sukces	“ACT” (Accepted Technical Validation)
999	Unexpected Error	“RJT” (Rejected)

Obsługa błędów

Jeśli w procesie onboardingu wystąpi odrzucenie, otrzymana zostanie synchroniczna odpowiedź zawierająca status transakcji z wartością RJCT (odrzucony) i kodem statusu 999.

Ta odpowiedź będzie zawierać kod błędu i pola komunikatów, które mogą pomóc w zidentyfikowaniu i rozwiązaniu problemu.

Przykład odrzuconej odpowiedzi onboardingowej:

{
"transactionStatus": "RJCT",
    "returnStatus": {
        "statusCode": "999",
        "statusMsg": "Internal Server Error",
        "statusDescription": "When invoiceIndicator is Sponsored Merchant invoiceEmail and payout object are mandatory."
    }
}

Kody statusów w webhookach

Poniżej znajduje się zakres kodów statusu i wiadomości, które można odbierać za pośrednictwem webhooków.

Kod statusu	Wiadomość
CRM000	Sukces.
CRM001	Sponsorowany mechant już istnieje.
CRM002	PKD jest nie poprawny.
CRM003	Kod MCC jest niepoprawny.
CRM004	NIP jest niepoprawny.
CRM005	IBAN jest niepoprawny.
CRM006	Lista produktów nie jest zgodna z umową z dostawcą usług płatniczych.
CRM007	Brak wymaganego pola[field_name]
CRM008	Payment Facilitator jest nieprawidłowy.
CRM009	Produkt [product] jest zduplikowany.
CRM010	Wskaźnik faktury jest nieprawidłowy.
CRM011	Product of Establishment został już dodany jako Establishment Product
CRM012	Kod produktu [product_code] jest nieprawidłowy.
CRM013	Kraj sponsorowanego merchanta nie jest zgodny z krajem siedziby podmiotu pośredniczącego w płatnościach.
CRM014	Sponsorowany kraj merchanta nie jest zgodny z krajem dostawcy usług płatniczych.
CRM015	Produkt [product1] jest zależny od [product2] i nie jest cześcią listy produktów
CRM016	Produkt [product1] jest niekompatybilny z [product2] i oba znajdują się obecnie na liście produktów.
CRM017	Produkt [product1]jest obowiązkowy z [product2] i nie jest częścią listy produktów.
CRM018	Nieprawidłowy typ integracji.
CRM019	Dane Webhook są wymagane dla danego typu integracji.
CRM020	Nieprawidłowe powiadomienie webhook dla danego typu integracji.
CRM021	Nieprawidłowe powiadomienie webhook.
CRM022	Wartość powiadomienia Webhook nie jest zdefiniowana dla danego powiadomienia Webhook.
CRM023	Webhook Notification Value musi być prawidłowym adresem e-mail.
CRM024	Webhook Notification Value musi być prawidłowym adresem url http(s).
CRM025	Zamówienie na numer TIN wciąż w toku [TIN_value].
CRM026	Aktualizacja merchanta nie jest możliwa. Spróbuj ponownie później.
CRM027	Nie można zaktualizować establishmentu. Spróbuj ponownie później.
CRM028	Establishment jest nieprawidłowy dla Sponsorowanego merchanta, którego dotyczy odwołanie.
CRM029	Establishment ExternalID już istnieje.
CRM030	Zamówienie dla Establishment w ciąż toku [establishment_id].
CRM031	TerminalID już istnieje.
CRM032	Payment Facilitator jest nieprawidłowy.
CRM033	Sponsorowany merchant jest nieprawidłowy.
CRM034	Establishment jest nieprawidłowy.
CRM035	Terminal jest nieprawdiłowy.
CRM036	Ostatni terminal nie może zostać anulowany.
CRM037	Produkt nie jest ważny dla Establishment.
CRM038	[PaymentFacilitatorId] Nie jest Payment Facilitatorem.
CRM039	Zamówienie dla Merchanta wciąż w toku [merchant_id].
CRM040	Nie znaleziono kraju dla określonego [CountryCode].
CRM999	Nieoczekiwany błąd.