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 |
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). |
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). |
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 |
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 |
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 statusu Webhooks
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. |