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.

Please check below the available environment endpoints:

Environment	URL	Operation Method & Endpoint	Operation Description
PROD	api.sibsgateway.com	POST api/onboarding/version-id/ sponsored-merchant	Performs a request to create the sponsored merchant record.
TEST	stargate-cer.qly.site1.sibs.pt	POST api/onboarding/version-id/ sponsored-merchant	Performs a request to create the sponsored merchant record.
Sandbox	sandbox.sibsgateway.com	POST api/onboarding/version-id/ sponsored-merchant	Performs 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:

Parameter	Type	Condition	Description
Content-type	String	Mandatory	application/json.
X-Request-ID	String	Mandatory	ID of the request, unique to the call, as determined by the initiating party.
x-ibm-client-id	String	Mandatory	Token that identifies a client organization. It is provided during onboarding process and must be used in every call.

Request parameters:

Data Element	Type Length	Condition	Description
merchant	String	Mandatory	Object that defines the Merchant.
name	String <=90	Mandatory	Company’s full name as per data in CEIDG.
phone	String <=16	Mandatory	Company’s phone number.
email	String <=55	Mandatory	Company’s email address.
nip	String 8<11	Mandatory	NIP as per CEIDG
mcc	Number 4-4	Mandatory	Company’s MCC Code
pkd	String 7-7	Mandatory	Company’s PKD (main) as per data in CEIDG
merchantType	String   “Merchant” “Sponsored Merchant” Default: “Sponsored Merchant”	Mandatory	Merchant type
address	String	Mandatory	Merchant Address
street	String <=70	Mandatory	Merchant’s Address Street
postalcode	String <=25	Mandatory	Merchant’s Address Postal Code
locality	String <=20	Mandatory	Merchant’s Address Locality
country	String 3-3 Format ISO 3166, Number 3 code (ex: Poland – 616)	Mandatory	Merchant’s Address Country
website	String <=100	Mandatory	Merchant’s website
signedAgreements	Boolean “True” “False”	Mandatory	Confirmation of signed agreements
backofficeEmail	String <=55	Mandatory	SIBS Backoffice email address
pepStatus	String “Active” “Inactive” Default: “Active”	Mandatory	Potentially Exposed Person status
beneficialOwnersData	String <=40	Conditional	Beneficial owners data. Only Mandatory if PEP Status is ‘Active’
Owner	String	Mandatory	Object that defines the Company’s Owner account. It is possible to add more than one entry for this parameter
name	String <=40	Mandatory	Owner’s name
phone	String <=16	Conditional	Owner’s phone. Either the phone or the email (at least one of them) should be provided.
email	String <=55	Conditional	Owner’s email Either the phone or the email (at least one of them) should be provided.
address	String <=100	Optional	Owner’s address
tin	Number 8<11	Mandatory	Owner’s nip
integrationSupportContact	String	Optional	Object that defines an integration support contact
name	String <=20	Optional	First and Last Name Contact for integration Support
phone	String <=16	Conditional	Phone number Contact for integration Support Either the phone or the email (at least one of them) should be provided.
email	String <=55	Conditional	Email address Contact for integration Support Either the phone or the email (at least one of them) should be provided.
shop		Mandatory	Object that defines the Establishment
name	String <=40	Optional	Establishment Name. When this field is empty, the value to be considered will be the ones parametrized at the Merchant level.
address	String	Optional	Establishment Address When these fields are empty, the value to be considered will be the ones parametrized at the Merchant level.
street	String <=70	Optional	Street
postalcode	String <=25	Optional	Postal Code
locality	String <=20	Optional	Locality
country	String 3-3 Format ISO 3166, Number 3 code (ex: Poland – 616)	Optional	Country
email	String <=55	Optional	Establishment Email When these fields are empty, the value to be considered will be the ones parametrized at the Merchant level.
phoneNumber	String <=16	Optional	Establishment Phone When these fields are empty, the value to be considered will be the ones parametrized at the Merchant level.
type	String “Banks” “Wholesale“ “Supermarket“ “Retail“ “Gas Stations“ “Restaurants“ “Hotels“ “Virtual Establishment“ “Foreign“ “Service Provider“ “Service Entity“ “EMV Tolls“	Mandatory	Establishment Type
mcc	String 4-4	Mandatory	Establishment MCC
pkd	String 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)	Mandatory	Establishment CAE
InvoiceIndicator	String   “Payment Facilitator” “Sponsored Merchant” Default: “Payment Facilitator”	Mandatory	Establishment Invoice Indicator
products	String	Mandatory	Object that defines the Establishment Products
productId	String “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”	Mandatory	Payment 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 “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	String “Payment Facilitator” “Sponsored Merchant” Default: “Payment Facilitator”	Optional	Product Invoice Indicator
paymentMethodType	String   “Direct Debit” “Bank Transfer” Default: “Direct Debit”	Conditional	Payment method type for the invoicing of the sponsored merchant. This field is mandatory if the Invoice indicator is “Sponsored Merchant”
invoiceEmail	String <=55	Conditional	Invoice email address. This field is mandatory if the Invoice indicator is “Sponsored Merchant”
payout	String	Conditional	Object that defines the Payout Information. Mandatory if InvoiceIndicator is “Sponsored Merchant”
bankAccount	String 26-26	Conditional	Sponsored Merchants bank account Mandatory if InvoiceIndicator is “Sponsored Merchant”
iban	String <=34	Conditional	Sponsored Merchants iban Mandatory if InvoiceIndicator is “Sponsored Merchant”
bic	String 8<11	Conditional	Sponsored Merchants bic Mandatory if InvoiceIndicator is “Sponsored Merchant”
numDaysPayout	Number	Optional	Sponsored Merchants Payout Number of Days Reserved for future use.
maxPercentLowRiskExemptions	Number <=100	Optional	The maximum percentage of low-risk exemptions allowed in a system or process.
scaExemption	String Default “0”	Optional	The field to evaluate SCA Exemptions must be filled with 1 to allow and 0 to not allow.
typeOfIntegration	String “S2S” “SDK” “Plugin” Default “S2S”	Mandatory	Sponsored merchant type of integration
webhookNotification	Object	Conditional	Object that defines the webhook configuration details Mandatory if typeOfIntegration is “Plugin”.
type	String “URL” “Email”	Conditional	Type of webhook notifications. Mandatory if typeOfIntegration is “Plugin”. If “Plugin”, the value must be “URL”
Value	String	Conditional	A delivery email address (for email type), or an HTTP(S) URL Mandatory if typeOfIntegration is “Plugin”
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”
securityKey	String >=32	Optional	A 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 Code	Message	TransactionStatus
000	Success	“ACT” (Accepted Technical Validation)
999	Unexpected 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"
         }
    }
}

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:

Environment	URL	Operation Method & Endpoint	Operation Description
PROD	api.sibsgateway.com	PUT /sibs/onboarding/v1/sponsored-merchant/{merchant-id}	Update a merchant resource
CER	stargate-cer.qly.site1.sibs.pt	PUT /sibs/onboarding/v1/sponsored-merchant/{merchant-id}	Update a merchant resource
Sandbox	sandbox.sibsgateway.com	PUT /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

Parameter	Type	Condition	Required	Description
Content-type	String	Mandatory	Header	application/json
X-Request-ID	String	Mandatory	Header	ID of the request, unique to the call, as determined by the initiating party
merchant-id	String	Mandatory	Path	ID of Sponsored Merchant
x-ibm-client-id	String	Mandatory	Header	Token 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 Element	Type Length	Condition	Description
Phone	String <=16	Mandatory	Company’s phone number
Email	String <=55	Mandatory	Company’s email address
Address	String	Mandatory	Merchant Address
street	String <=100	Mandatory	Merchant’s Address Street
postalcode	String <=25	Mandatory	Merchant’s Address Postal Code
locality	String <=20	Mandatory	Merchant’s Address Locality
website	String <=100	Mandatory	Merchant’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 Code	Message	TransactionStatus
000	Success	“ACT” (Accepted Technical Validation)
999	Unexpected 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 Code	Message
CRM000	Success.
CRM001	Sponsored Merchant already exists.
CRM002	PKD is invalid.
CRM003	MCC code is invalid.
CRM004	NIP is invalid.
CRM005	IBAN is invalid.
CRM006	Product list doesn’t comply with Payment Facilitator agreement.
CRM007	Required field [field_name] missing.
CRM008	Payment Facilitator is invalid.
CRM009	Product [product] is duplicated.
CRM010	Invoice indicator is invalid.
CRM011	This Product of Establishment has already been added as an Establishment Product.
CRM012	Product code [product_code] is invalid.
CRM013	Sponsored Merchant´s Country doesn’t match any Payment Facilitator´s Establishment Country.
CRM014	Sponsored Merchant Country does not match the Payment Facilitator Country.
CRM015	The product [product1] has a dependecy on [product2] and this is not part of the products list.
CRM016	The product [product1] is incompatible with [product2] and both are currenctly on the products list.
CRM017	The product [product1] is mandatory with [product2] and this is not part of the products list.
CRM018	Invalid Type Of Integration.
CRM019	Webhook data is required for given Type Of Integration.
CRM020	Invalid Webhook Notification for given Type Of Integration.
CRM021	Invalid Webhook Notification.
CRM022	Webhook Notification Value is not defined for given Webhook Notification.
CRM023	Webhook Notification Value must be a valid email address.
CRM024	Webhook Notification Value must be a valid http(s) url address.
CRM025	Order still in progress for TIN [TIN_value].
CRM026	It’s not Possible to update Merchant. Please retry Later.
CRM027	It’s not Possible to update Establishment. Please retry Later.
CRM028	Establishment is invalid for referenced Sponsored Merchant.
CRM029	Establishment ExternalID already exists.
CRM030	Order still in progress for Establishment [establishment_id].
CRM031	TerminalID already exists.
CRM032	Payment Facilitator is invalid.
CRM033	Sponsored Merchant is invalid.
CRM034	Establishment is invalid.
CRM035	Terminal is invalid.
CRM036	Last Terminal cannot be cancelled.
CRM037	Product is not valid for Establishment.
CRM038	[PaymentFacilitatorId] is not a Payment Facilitator.
CRM039	Order still in progress for Merchant [merchant_id].
CRM040	No Country found for specified [CountryCode].
CRM999	Unexpected Error.