Skip to content

Merchant

On this page, you will find necessary information to onboard and update a sponsored merchant, as well as how to handle errors and check the webhook status codes.

Merchant onboarding

The API-based onboarding process eliminates the need for manual onboarding by automatically generating sponsored merchants, establishments, pricelists, terminals, and their corresponding credentials.

Notification

The Merchant’s NIP and backofficeEmail parameters in the POST request must each have unique values and should not be reused.
Attempting to reuse these values will results in an unsuccessful completion of the onboarding process.

Please check below the available environment endpoints:

EnvironmentURLOperation Method & EndpointOperation Description
PRODapi.sibsgateway.comPOST api/onboarding/version-id/ sponsored-merchantPerforms a request to create the sponsored merchant record.
TESTstargate-cer.qly.site1.sibs.ptPOST api/onboarding/version-id/ sponsored-merchantPerforms a request to create the sponsored merchant record.
Sandboxsandbox.sibsgateway.comPOST api/onboarding/version-id/ sponsored-merchantPerforms a request to create  the sponsored merchant record.

To initiate this process, you are required to perform a POST request with the following data:

Header parameters:
ParameterTypeConditionDescription
Content-typeStringMandatoryapplication/json.
X-Request-IDStringMandatoryID of the request, unique to the call, as determined by the initiating party.
x-ibm-client-idStringMandatoryToken that identifies a client organization. It is provided during onboarding process and must be used in every call.
Request parameters:
Data ElementType LengthConditionDescription
merchantStringMandatoryObject that defines the Merchant.
nameString
<=90
MandatoryCompany’s full name as per data in CEIDG.
phoneString
<=16
MandatoryCompany’s phone number.
emailString
<=55
MandatoryCompany’s email address.
nipString
8<11
MandatoryNIP as per CEIDG 
mccNumber
4-4
MandatoryCompany’s MCC Code
pkdString
7-7
MandatoryCompany’s PKD (main) as per data in CEIDG 
merchantTypeString
 
“Merchant”
“Sponsored Merchant”
Default: “Sponsored Merchant”
MandatoryMerchant type
addressStringMandatoryMerchant Address
streetString
<=70
MandatoryMerchant’s Address Street
postalcodeString
<=25
MandatoryMerchant’s Address Postal Code
localityString
<=20
MandatoryMerchant’s Address Locality
countryString
3-3
Format ISO 3166, Number 3 code (ex: Poland – 616)
MandatoryMerchant’s Address Country
websiteString
<=100
MandatoryMerchant’s website
signedAgreementsBoolean
“True”
“False”
MandatoryConfirmation of signed agreements
backofficeEmailString
<=55
MandatorySIBS Backoffice email address
pepStatusString
“Active”
“Inactive”
Default: “Inactive”
MandatoryPolitically Exposed Person status 
beneficialOwnersDataString
<=40
ConditionalBeneficial owners data.
Only Mandatory if PEP Status is ‘Active’
OwnerStringMandatoryObject that defines the Company’s Owner account.
It is possible to add more than one entry for this parameter
nameString
<=40
MandatoryOwner’s name
phoneString
<=16
ConditionalOwner’s phone.
Either the phone or the email (at least one of them) should be provided.
emailString
<=55
ConditionalOwner’s email
Either the phone or the email (at least one of them) should be provided.
addressString
<=100
OptionalOwner’s address
tinNumber
8<11
MandatoryOwner’s nip
integrationSupportContactStringOptionalObject that defines an integration support contact
nameString
<=20
OptionalFirst and Last Name Contact for integration Support
phoneString
<=16
ConditionalPhone number Contact for integration Support
Either the phone or the email (at least one of them) should be provided.
emailString
<=55
ConditionalEmail address Contact for integration Support
Either the phone or the email (at least one of them) should be provided.
shopMandatoryObject that defines the Establishment
nameString
<=40
OptionalEstablishment Name.
When this field is empty, the value to be considered will be the ones parametrized at the Merchant level.
addressStringOptionalEstablishment Address
When these fields are empty, the value to be considered will be the ones parametrized at the Merchant level.
streetString
<=70
OptionalStreet
postalcodeString
<=25
OptionalPostal Code
localityString
<=20
OptionalLocality
countryString
3-3
Format ISO 3166, Number 3 code (ex: Poland – 616)
OptionalCountry
emailString
<=55
OptionalEstablishment Email
When these fields are empty, the value to be considered will be the ones parametrized at the Merchant level.
phoneNumberString
<=16
OptionalEstablishment Phone
When these fields are empty, the value to be considered will be the ones parametrized at the Merchant level.
typeString
“Banks”
“Wholesale“
“Supermarket“
“Retail“
“Gas Stations“
“Restaurants“
“Hotels“
“Virtual Establishment“
“Foreign“
“Service Provider“
“Service Entity“
“EMV Tolls“
MandatoryEstablishment Type
mccString
4-4
MandatoryEstablishment MCC
pkdString
7
 
The format of this parameter will be as Follows:
00.00.A
(see list here: https://www.biznes.gov.pl/en/table-pkd-code)
MandatoryEstablishment CAE
InvoiceIndicatorString
 
“Payment Facilitator”
“Sponsored Merchant”
Default: “Payment Facilitator”
MandatoryEstablishment Invoice Indicator
productsStringMandatoryObject that defines the Establishment Products
productIdString
“XPAY-APPL-0-0”,
“XPAY-GGLE-0-0”,
“INTP-BLIK-0-0”,
“INTP-BLIK-1-0”,
“BLMD-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”,
“PPRO-BIZM-0-0”,
“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”
MandatoryPayment methods selected by the customer.
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
“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
“PPRO-BIZM-0-0” – Bizum
“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
productInvoiceIndicatorString
“Payment Facilitator”
“Sponsored Merchant”
Default: “Payment Facilitator”
OptionalProduct Invoice Indicator
paymentMethodTypeString
 
“Direct Debit”
“Bank Transfer”
Default: “Direct Debit”
ConditionalPayment method type for the invoicing of the sponsored merchant. This field is mandatory if the Invoice indicator is “Sponsored Merchant”
invoiceEmailString
<=55
ConditionalInvoice email address.
This field is mandatory if the Invoice indicator is “Sponsored Merchant”
payoutStringConditionalObject that defines the Payout Information.
Mandatory if InvoiceIndicator is “Sponsored Merchant”
bankAccountString
26-26
ConditionalSponsored Merchants bank account
Mandatory if InvoiceIndicator is “Sponsored Merchant”
ibanString
<=34
ConditionalSponsored Merchants iban
Mandatory if InvoiceIndicator is “Sponsored Merchant”
bicString
8<11
ConditionalSponsored Merchants bic
Mandatory if InvoiceIndicator is “Sponsored Merchant”
numDaysPayoutNumberOptionalSponsored Merchants Payout Number of Days
Reserved for future use.
maxPercentLowRiskExemptionsNumber
<=100
OptionalThe maximum percentage of low-risk exemptions allowed in a system or process.
scaExemptionString
Default “0”
OptionalThe field to evaluate SCA Exemptions must be filled with 1 to allow and 0 to not allow.
typeOfIntegrationString
“S2S”
“SDK”
“Plugin”
Default “S2S”
MandatorySponsored merchant type of integration
webhookNotificationObjectConditionalObject that defines the webhook configuration details
Mandatory if typeOfIntegration is “Plugin”.
typeString
“URL”
“Email”
ConditionalType of webhook notifications.
Mandatory if typeOfIntegration is “Plugin”.
If “Plugin”, the value must be “URL”
ValueStringConditionalA delivery email address (for email type), or an HTTP(S) URL
Mandatory if typeOfIntegration is “Plugin”
supportEmailString
<=55
ConditionalAn email address to where all failed SPG Webhook calls will be reported by the end-of-day
Mandatory if typeOfIntegration is “Plugin”
securityKeyString
>=32
OptionalA pseudo-random symmetric key that will be used to cipher the webhook content

Find below a POST request example:

{
    "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": ""
        }
    }
}

Upon this action, the API will respond with one of the following two status codes:

Status CodeMessageTransactionStatus
000Success“ACT” (Accepted Technical Validation)
999Unexpected Error“RJT” (Rejected)

Here is an example of a successful onboarding response:

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

You will also receive the onboarding webhook, which includes the following merchant onboarding details and credentials.

Here’s a redacted example of a successful Webhook notification:

{
    "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"
         }
    }
}
Notification

Please note the following essential credentials for your API Integrations:

 

Credentials.ApiClientId: The API Client ID needed for calling the Payment API, provided as the ‘x-ibm-client-id’HTTP header.

 

Credentials.ApiClientSecret: Currently not required for any Payment API, but it should be stored securely in case it’s needed in the future.

 

Credentials.TerminalToken: The OAuth Bearer Token to be used as the ‘Authorization:Bearer’ HTTP header for the Checkout API and Backoffice API.

Merchant update

We also provide the capability to update merchant information through our APIs. Please refer to the list of available environment endpoints provided below:

EnvironmentURLOperation Method & EndpointOperation Description
PRODapi.sibsgateway.comPUT /sibs/onboarding/v1/sponsored-merchant/{merchant-id}Update a merchant resource
CERstargate-cer.qly.site1.sibs.ptPUT /sibs/onboarding/v1/sponsored-merchant/{merchant-id}Update a merchant resource
Sandboxsandbox.sibsgateway.comPUT /sibs/onboarding/v1/sponsored-merchant/{merchant-id}Update a merchant resource

To initiate this process, you are required to perform a PUT request with the following data:

Parameters
ParameterTypeConditionRequiredDescription
Content-typeStringMandatoryHeaderapplication/json
X-Request-IDStringMandatoryHeaderID of the request, unique to the call, as determined by the initiating party
merchant-idStringMandatoryPathID of Sponsored Merchant
x-ibm-client-idStringMandatoryHeaderToken that identifies a client organization. It is provided during onboarding process and must be used in every call

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

Request parameters
Data ElementType LengthConditionDescription
PhoneString
<=16
MandatoryCompany’s phone number
EmailString
<=55
MandatoryCompany’s email address
AddressStringMandatoryMerchant Address
streetString
<=100
MandatoryMerchant’s Address Street
postalcodeString
<=25
MandatoryMerchant’s Address Postal Code
localityString
<=20
MandatoryMerchant’s Address Locality
websiteString
<=100
MandatoryMerchant’s website

Find below a PUT request example:

{
  "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:

Status CodeMessageTransactionStatus
000Success“ACT” (Accepted Technical Validation)
999Unexpected Error“RJT” (Rejected)

Error handling

If a rejection occurs on the onboarding process, a synchronous response will be received that include a transactionstatus with the value RJCT (rejected) and a 999 StatusCode.

This response will contain error code and message fields that can assist you in identifying and resolving the issue.

Rejected onboarding response example:

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

Webhooks Status Codes

Below you can find the range of Status Codes and Messages that you can receive via webhooks.

Status CodeMessageOperationsDetails
CRM000Success.n/an/a
CRM001Sponsored Merchant already exists.Merchant Onboarding OperationsA Sponsored Merchant with the received NIF already exists.
CRM002PKD is invalid.Merchant Onboarding Operations

Merchant Update Operations

Create shop Operations

Update shop Operations
PKD does not exist in the list of configured PKDs.
CRM003MCC code is invalid.Merchant Onboarding Operations

Merchant Update Operations

Create shop Operations

Update shop Operations
MCC does not exist in the list of configured MCCs.
CRM005IBAN is invalid.Merchant Onboarding OperationsIBAN is invalid according to the implemented validation rules.
CRM006Product list doesn’t comply with Payment Facilitator agreement.Merchant Onboarding Operations

Create shop Operations

Add payment method Operations
Sent products are not listed among the products enabled for the Payment Facilitator (PF).
CRM007Required field [field_name] missing.AllA required attribute in the API invocation was not sent.
CRM008Payment Facilitator is invalid.AllPayment Facilitator ID does not exist in the system.
CRM009Product [product] is duplicated.Merchant Onboarding Operations

Create shop Operations

Add payment method Operations

Delete payment method Operations
Duplicate products in the API.
CRM010Invoice indicator is invalid.Merchant Onboarding Operations

Create shop Operations

Add payment method Operations
The value of the “Invoice Indicator” attribute is not compatible with the PF configuration.
CRM011This Product of Establishment has already been added as an Establishment Product.Add payment method OperationsThe specified product is already among the products of the Establishment.
CRM012Product code [product_code] is invalid.Merchant Onboarding Operations

Create shop Operations

Add payment method Operations
Product does not exist in the list of products accepted via API.
CRM013Sponsored Merchant´s Country doesn’t match any Payment Facilitator´s Establishments.Merchant Onboarding Operations

Create shop Operations

Update shop Operations
Establishment’s country code does not match the country code of the Payment Facilitator.
CRM015The product [product1] has a dependency on [product2] and this is not part of the products list.Merchant Onboarding Operations

Create shop Operations

Add payment method Operations

Delete payment method Operations
Failed to validate product compatibility rules.
CRM016The product [product1] is incompatible with [product2] and both are currently on the products list.Merchant Onboarding Operations

Create shop Operations

Add payment method Operations

Delete payment method Operations
Failed to validate product compatibility rules.
CRM017The product [product1] is mandatory with [product2] and this is not part of the products list.Merchant Onboarding Operations

Create shop Operations

Add payment method Operations

Delete payment method Operations
Failed to validate product compatibility rules.
CRM018Invalid Type Of Integration.Merchant Onboarding Operations

Create shop Operations

Update shop Operations
Integration type in the Webhook is invalid.
CRM019Webhook data is required for given Type Of Integration.Merchant Onboarding Operations

Create shop Operations

Update shop Operations
Integration type in the Webhook does not match the submitted data.
CRM020Invalid Webhook Notification for given Type Of Integration.Merchant Onboarding Operations

Create shop Operations

Update shop Operations
Notification type defined in the Webhook does not match the Webhook type.
CRM021Invalid Webhook Notification.Merchant Onboarding Operations

Create shop Operations

Update shop Operations
Notification type in the Webhook is invalid.
CRM022Webhook Notification Value is not defined for given Webhook Notification.Merchant Onboarding Operations

Create shop Operations

Update shop Operations
Notification type defined in the Webhook does not match the Webhook type.
CRM023Webhook Notification Value must be a valid email address.Merchant Onboarding Operations

Create shop Operations

Update shop Operations
For the notification type defined in the Webhook, a valid email must be provided.
CRM024Webhook Notification Value must be a valid http(s) url address.Merchant Onboarding Operations

Create shop Operations

Update shop Operations
For the notification type defined in the Webhook, a valid URL must be provided.
CRM025Order still in progress for TIN [TIN_value].Merchant Onboarding OperationsThere is an order in progress/processing for the indicated TIN.
CRM029Establishment ExternalID already exists.Create shop OperationsThe Payment Facilitator is sending a request to create an Establishment that already exists in the system.
CRM030Order still in progress for Establishment [establishment_id].Create shop Operations

Update shop Operations

Create Terminal Operations

Add payment method Operations

Cancel terminal Operations

Delete payment method Operations
There is an order in progress for the indicated Establishment.
CRM031TerminalID already exists.Create Terminal OperationsThe Payment Facilitator is sending a request to create a Terminal that already exists in the system for the indicated Establishment.
CRM032Payment Facilitator is invalid.Create shop Operations

Create Terminal Operations

Merchant Update Operations

Update shop Operations
During SM creation, the Payment Facilitator’s configuration is not complete.
CRM033Sponsored Merchant is invalid.Merchant Update Operations

Create shop Operations

Update shop Operations

Create Terminal Operations

Cancel shop Operations

Cancel terminal Operations

Delete payment method Operations
The indicated Sponsored Merchant does not exist or is not in a valid state.
CRM034Establishment is invalid.Update shop Operations

Create Terminal Operations

Cancel shop Operations

Cancel terminal Operations

Delete payment method Operations
The indicated Establishment does not exist or is not in a valid state.
CRM035Terminal is invalid.Cancel terminal OperationsThe indicated Terminal does not exist or is not in a valid state.
CRM036Last Terminal cannot be cancelled.Cancel terminal OperationsThe indicated Terminal is the only one of the Establishment, therefore it cannot be canceled.
CRM037Product is not valid for Establishment.Delete payment method OperationsThe indicated product does not exist in the Establishment or is not in a valid state.
CRM038[PaymentFacilitatorId] is not a Payment Facilitator.AllThe indicated Payment Facilitator is not actually a Payment Facilitator.
CRM039Order still in progress for Merchant [merchant_id].Merchant Update OperationsThere is an order in progress for the indicated Merchant.
CRM040No Country found for specified [CountryCode].Merchant Onboarding Operations

Create shop Operations

Merchant Update Operations
The specified country code does not exist.
CRM041Transactional Country is invalid.Create shop OperationsThe 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 Operations

Create shop Operations

Create Terminal Operations
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 Operations

Create shop Operations

Create Terminal Operations
The Terminal Model does not match the defined Terminal Channel Type.
CRM044Invalid Terminal Channel Type for this Establishment.Create Terminal OperationsThe terminal type is different from the Establishment’s.
CRM045Sponsored Merchant´s Terminal Channel doesn’t match any Payment Facilitator´s Establishments.Merchant Onboarding Operations

Create shop Operations
The selected Payment Facilitator does not have an active Establishment with the same country and terminal channel as the Sponsored Merchant in the request.
CRM046Sponsored Merchant´s Terminal Type doesn’t match any Payment Facilitator´s Terminals.Merchant Onboarding Operations

Create shop Operations

Create Terminal Operations
The selected Payment Facilitator does not have an active Terminal with the terminal type of the Sponsored Merchant in the request.
CRM999Unexpected Error.AllUnexpected error occurred.
Privacy Overview

This website uses cookies so that we can provide you with the best user experience possible. Cookie information is stored in your browser and performs functions such as recognising you when you return to our website and helping our team to understand which sections of the website you find most interesting and useful.

Strictly Necessary Cookies

Strictly Necessary Cookie should be enabled at all times so that we can save your preferences for cookie settings.

If you disable this cookie, we will not be able to save your preferences. This means that every time you visit this website you will need to enable or disable cookies again.