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.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.

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:

Data Element	Type Length	Condition	Description
merchant	Object	Mandatory	Root object for merchant data
merchant.name	String <=90	Mandatory	Merchant’s full name
merchant.phone	String <=16	Mandatory	Merchant’s phone number.
merchant.email	String <=55	Mandatory	Merchant’s email address
merchant.nip	String 8<11	Mandatory	Merchant’s tax identification number
merchant.mcc	Number 4-4	Mandatory	Merchant Category Code
merchant.pkd	String 7-7	Mandatory	Classification of economic activities code (Polish PKD system). The format of this parameter will be as Follows: 00.00.A
merchant.merchantType	Enum	Mandatory	Merchant type description Allowed value: “Sponsored Merchant”
merchant.address	object	Mandatory	Merchant’s Address
merchant.address.street	String <=70	Mandatory	Street name
merchant.address.postalCode	String <=25	Mandatory	Postal Code
merchant.address.locality	String <=20	Mandatory	City or locality
merchant.address.country	Number 3-3	Mandatory	Country code (Format ISO 3166, Number 3 code — ex: Poland – 616)
merchant.website	String <=100	Mandatory	Merchant’s website URL
merchant.signedAgreements	Enum	Mandatory	Flag indicating if agreements are signed Allowed Value: “False”
merchant.backofficeEmail	String <=55	Mandatory	SIBS Backoffice contact email
merchant.pepStatus	Enum	Mandatory	Politically Exposed Person status Allowed value: “Inactive”
merchant.owners	Array of objects	Mandatory	List of merchant owners
merchant.owners[].name	String <=20	Mandatory	Owner’s full name
merchant.owners[].phone	String <=16	Conditional	Owner’s phone number. At least one phone number or email must be provided.
merchant.owners[].email	String <=55	Conditional	Owner’s email address At least one phone number or email must be provided.
merchant.owners[].address	String <=100	Optional	Owner’s address
merchant.owners[].tin	String 8<11	Mandatory	Owner’s tax identification number
merchant.integrationSupportContact	Object	Optional	Contact person for integration support
merchant.integrationSupportContact.name	String <=20	Optional	Name of integration contact person
merchant.integrationSupportContact.phone	String <=16	Conditional	Phone number of integration contact At least one phone number or email must be provided.
merchant.integrationSupportContact.email	String <=55	Conditional	Email address Contact for integration Support At least one phone number or email must be provided.
merchant.shop	object	Mandatory	Shop details
merchant.shop.name	String <=40	Optional	Shop Name. If this field is left empty, the system will default to using the value specified at the Merchant level.
merchant.shop.address	object	Optional	Shop Address
merchant.shop.address.street	String	Optional	Shop street If this field is left empty, the system will default to using the value specified at the Merchant level.
merchant.shop.address.postalcode	String <=25	Optional	Shop postal code If this field is left empty, the system will default to using the value specified at the Merchant level.
merchant.shop.address.locality	String <=20	Optional	Shop city/locality If this field is left empty, the system will default to using the value specified at the Merchant level.
merchant.shop.address.country	Number 3-3	Optional	Shop country code (Format ISO 3166, Number 3 code — ex: Poland – 616) If this field is left empty, the system will default to using the value specified at the Merchant level.
merchant.shop.email	String <=55	Optional	Shop email address If this field is left empty, the system will default to using the value specified at the Merchant level.
merchant.shop.phoneNumber	String <=16	Optional	Shop phone number If this field is left empty, the system will default to using the value specified at the Merchant level.
merchant.shop.type	Enum	Mandatory	Shop Type Allowed values: “Banks”, “Wholesale”, “Supermarket”, “Retail”, “Gas Stations”, “Restaurants”, “Hotels”, “Others”, “Virtual Establishment”, “Foreign”, “Service Provider”, “Service Entity”, “EMV Tolls”
merchant.shop.mcc	String 4-4	Mandatory	Shop Merchant Category Code
merchant.shop.pkd	String 7-7	Mandatory	Classification of economic activities code (Polish PKD system). The format of this parameter will be as Follows: 00.00.A
merchant.shop.invoiceIndicator	Enum	Mandatory	Shop Invoice Indicator type Allowed value: “Payment Facilitator”
merchant.shop.products	Array of objects	Mandatory	List of products
merchant.shop.product[]productId	String	Mandatory	Payment methods to be activated. Allowed values: “INTP-BLIK-0-0” InterPay-BLIK-Domestic “INTP-BLIK-1-0” – InterPay-BLIK-OneClick “BLMD-PYBL-0-0” BlueMedia-PayByLink-Domestic “MRKP-CRTB-0-0” – Cartes Bancaires “SIBS-MBWY-0-0” – MB WAY “SPDD-BTOB-0-0” – SEPA DD B2B “SPDD-CORE-0-0” – SEPA DD Core “XPAY-APPL-0-0” – ApplePay “XPAY-GGLE-0-0” – GooglePay “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
merchant.shop.product[]productInvoiceIndicator	Enum 	Mandatory	Product Invoice Indicator Allowed Values: “Payment Facilitator”
merchant.shop.typeOfIntegration	Enum	Mandatory	Merchant type of integration Allowed Values: “S2S” “SDK” “Plugin” Default “S2S”
merchant.shop.webhookNotification	object	Conditional	Object that defines the webhook configuration details Mandatory if typeOfIntegration is “Plugin”.
merchant.shop.webhookNotification.type	Enum	Conditional	Type of webhook notifications. Allowed values: “URL” “Email” Mandatory if typeOfIntegration is “Plugin”. If “Plugin”, the value must be “URL”
merchant.shop.webhookNotification.Value	String	Conditional	A delivery email address (for email type), or an HTTP(S) URL Mandatory if typeOfIntegration is “Plugin”
merchant.shop.supportEmail	String <=55	Conditional	An email address to where all failed SPG Webhook calls will be reported by the end-of-day Mandatory if typeOfIntegration is “Plugin”
merchant.shop.securityKey	String >=32	Optional	A pseudo-random symmetric key that will be used to cipher the webhook content

Ponizej znajduje się przykład żadania POST

{
  "merchant": {
    "name": "Testing Company",
    "phone": "501234567",
    "email": "merchant@example.pl",
    "nip": "1234567890",
    "mcc": "5999",
    "pkd": "47.91.Z",
    "merchantType": "Sponsored Merchant",
    "address": {
      "street": "UL PRZYKŁADOWA 1",
      "postalCode": "00-001",
      "locality": "WARSZAWA",
      "country": "616"
    },
    "website": "https://www.testingcompany.pl",
    "signedAgreements": false,
    "backofficeEmail": "backoffice@example.pl",
    "pepStatus": "Inactive",
    "owners": [
      {
        "name": "Jane Doe",
        "email": "jane.doe@example.pl",
        "tin": "1234567890"
      }
    ],
    "shop": {
      "name": "Testing Store",
      "email": "shop@example.pl",
      "phoneNumber": "501234567",
      "type": "Retail",
      "mcc": "5999",
      "pkd": "47.91.Z",
      "invoiceIndicator": "Payment Facilitator",
      "products": [
        {
          "productId": "MCC-1-C",
          "productInvoiceIndicator": "Payment Facilitator"
        },
        {
          "productId": "MCC-1-D",
          "productInvoiceIndicator": "Payment Facilitator"
        },
        {
          "productId": "VIS-01-C",
          "productInvoiceIndicator": "Payment Facilitator"
        },
        {
          "productId": "VIS-01-D",
          "productInvoiceIndicator": "Payment Facilitator"
        }
      ],
      "typeOfIntegration": "S2S"
    }
  }
}

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	“ACTC” (Accepted Technical Validation)
999	Unexpected Error	“RJT” (Rejected)

Oto przykład udanej odpowiedzi onboardingowej:

{
"transactionStatus": "ACTC",
    "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 /api/onboarding/v1/sponsored-merchant/{merchant-id}	Aktualizuj zasób merchanta
TEST	stargate.qly.site1.sibs.pt	PUT /api/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
Content-type	Ciąg	Obowiązkowe	Nagłowek	application/json
X-Request-ID	Ciąg	Obowiązkowe	Nagłowek	Żądanie 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

Data Element	Type Length	Condition	Description
merchant	Object	Mandatory	Main object containing merchant details
merchant.phone	String <=16	Mandatory	Phone number of the merchant
merchant.email	String <=55	Mandatory	Email address of the merchant
merchant.address	Object	Mandatory	Merchant’s address object
merchant.address.street	String <=100	Mandatory	Street name of the merchant’s address
merchant.address.postalCode	String <=25	Mandatory	Postal code of the merchant’s address
merchant.address.locality	String <=20	Mandatory	City/locality of the merchant’s address
merchant.website	String <=100	Mandatory	Merchant’s website URL

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ść	Operations	Details
CRM000	Sukces.	n/a	n/a
CRM001	Sponsorowany mechant już istnieje.	Merchant Onboarding	A Sponsored Merchant with the received TIN already exists.
CRM002	PKD jest nie poprawny.	Merchant Onboarding Merchant Update Create shop Update shop	PKD does not exist in the list of configured PKDs.
CRM003	Kod MCC jest niepoprawny.	Merchant Onboarding Merchant Update Create shop Update shop	MCC does not exist in the list of configured MCCs.
CRM005	IBAN jest niepoprawny.	Merchant Onboarding	IBAN is invalid according to the implemented validation rules.
CRM006	Lista produktów nie jest zgodna z umową z dostawcą usług płatniczych.	Merchant Onboarding Create shop Add payment method	Sent products are not listed among the products enabled for the Payment Facilitator (PF).
CRM007	Brak wymaganego pola [field_name]	All	A required attribute in the API invocation was not sent.
CRM008	Payment Facilitator jest nieprawidłowy.	All	Payment Facilitator ID does not exist in the system.
CRM009	Produkt [product] jest zduplikowany.	Merchant Onboarding Create shop Add payment method Delete payment method	Duplicate products in the API.
CRM010	Wskaźnik faktury jest nieprawidłowy.	Merchant Onboarding Create shop Add payment method	The value of the „Invoice Indicator” attribute is not compatible with the PF configuration.
CRM011	Product of Establishment został już dodany jako Establishment Product	Add payment method	The specified product is already among the products of the Establishment.
CRM012	Kod produktu [product_code] jest nieprawidłowy.	Merchant Onboarding Create shop Add payment method	Product does not exist in the list of products accepted via API.
CRM013	Kraj sponsorowanego merchanta nie jest zgodny z krajem siedziby podmiotu pośredniczącego w płatnościach.	Merchant Onboarding Create shop Update shop	Establishment’s country code does not match the country code of the Payment Facilitator.
CRM015	Produkt [product1] jest zależny od [product2] i nie jest cześcią listy produktów	Merchant Onboarding Create shop Add payment method Delete payment method	Failed to validate product compatibility rules.
CRM016	Produkt [product1] jest niekompatybilny z [product2] i oba znajdują się obecnie na liście produktów.	Merchant Onboarding Create shop Add payment method Delete payment method	Failed to validate product compatibility rules.
CRM017	Produkt [product1]jest obowiązkowy z [product2] i nie jest częścią listy produktów.	Merchant Onboarding Create shop Add payment method Delete payment method	Failed to validate product compatibility rules.
CRM018	Nieprawidłowy typ integracji.	Merchant Onboarding Create shop Update shop	Integration type in the Webhook is invalid.
CRM019	Dane Webhook są wymagane dla danego typu integracji.	Merchant Onboarding Create shop Update shop	Integration type in the Webhook does not match the submitted data.
CRM020	Nieprawidłowe powiadomienie webhook dla danego typu integracji.	Merchant Onboarding Create shop Update shop	Notification type defined in the Webhook does not match the Webhook type.
CRM021	Nieprawidłowe powiadomienie webhook.	Merchant Onboarding Create shop Update shop	Notification type in the Webhook is invalid.
CRM022	Wartość powiadomienia Webhook nie jest zdefiniowana dla danego powiadomienia Webhook.	Merchant Onboarding Create shop Update shop	Notification type defined in the Webhook does not match the Webhook type
CRM023	Webhook Notification Value musi być prawidłowym adresem e-mail.	Merchant Onboarding Create shop Update shop	For the notification type defined in the Webhook, a valid email must be provided.
CRM024	Webhook Notification Value musi być prawidłowym adresem url http(s).	Merchant Onboarding Create shop Update shop	For the notification type defined in the Webhook, a valid URL must be provided.
CRM025	Zamówienie na numer TIN wciąż w toku [TIN_value].	Merchant Onboarding	There is an order in progress/processing for the indicated TIN.
CRM029	Establishment ExternalID już istnieje.	Create shop	The Payment Facilitator is sending a request to create an Establishment that already exists in the system.
CRM030	Zamówienie dla Establishment wciąż toku [establishment_id].	Create shop Update shop Create Terminal Add payment method Cancel terminal Delete payment method	There is an order in progress for the indicated Establishment.
CRM031	TerminalID już istnieje.	Create Terminal	The Payment Facilitator is sending a request to create a Terminal that already exists in the system for the indicated Establishment.
CRM032	Payment Facilitator jest nieprawidłowy.	Create shop Create Terminal Merchant Update Update shop	During SM creation, the Payment Facilitator’s configuration is not complete.
CRM033	Sponsorowany merchant jest nieprawidłowy.	Merchant Update Create shop Update shop Create Terminal Cancel shop Cancel terminal Delete payment method	The indicated Sponsored Merchant does not exist or is not in a valid state.
CRM034	Establishment jest nieprawidłowy.	Update shop Create Terminal Cancel shop Cancel terminal Delete payment method	The indicated Establishment does not exist or is not in a valid state.
CRM035	Terminal jest nieprawidłowy.	Cancel terminal	The indicated Terminal does not exist or is not in a valid state.
CRM036	Ostatni terminal nie może zostać anulowany.	Cancel terminal	The indicated Terminal is the only one of the Establishment, therefore it cannot be canceled.
CRM037	Produkt nie jest prawidłowy dla Establishment.	Delete payment method	The indicated product does not exist in the Establishment or is not in a valid state.
CRM038	[PaymentFacilitatorId] Nie jest Payment Facilitatorem.	All	The indicated Payment Facilitator is not actually a Payment Facilitator.
CRM039	Zamówienie dla Merchanta wciąż w toku [merchant_id].	Merchant Update	There is an order in progress for the indicated Merchant.
CRM040	Nie znaleziono kraju dla określonego [CountryCode].	Merchant Onboarding Create shop Merchant Update	The specified country code does not exist.
CRM041	Transactional Country is invalid.	Create shop	The specified country code does not exist or does not have a currency.
CRM042	[terminal_type] is not a valid Terminal Type for the Terminal Channel [terminal_channel].	Merchant Onboarding Create shop Create Terminal	The Terminal Type does not match the defined Terminal Channel Type.
CRM043	[terminal_model] is not a valid Terminal Model for the Terminal Channel [terminal_channel].	Merchant Onboarding Create shop Create Terminal	The Terminal Model does not match the defined Terminal Channel Type.
CRM044	Invalid Terminal Channel Type for this Establishment.	Create Terminal	The terminal type is different from the Establishment’s.
CRM045	Sponsored Merchant´s Terminal Channel doesn’t match any Payment Facilitator´s Establishments.	Merchant Onboarding Create shop	The selected Payment Facilitator does not have an active Establishment with the same country and terminal channel as the Sponsored Merchant in the request.
CRM046	Sponsored Merchant´s Terminal Type doesn’t match any Payment Facilitator´s Terminals.	Merchant Onboarding Create shop Create Terminal	The selected Payment Facilitator does not have an active Terminal with the terminal type of the Sponsored Merchant in the request.
CRM999	Nieoczekiwany błąd.	All	Unexpected error occurred.