Skip to content

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
countryNumber
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: “Active”
MandatoryPotentially 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
countryNumber
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”,
“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”
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
“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
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
webhookNotificationStringConditionalObject 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.

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 CodeMessage
CRM000Success
CRM001Sponsored Merchant already exists.
CRM002PKD is invalid
CRM003MCC code is invalid
CRM004NIP is invalid
CRM005IBAN is invalid
CRM006Product list doesn’t comply with Payment Facilitator agreement
CRM007Product code {} is invalid
CRM008Payment Facilitator is invalid
CRM009Product {} is not compatible with product {}
CRM010Invoice indicator is invalid for this Sponsored Merchant
CRM011This Product of Establishment has already been added as an Establishment Product.
CRM012Required field {} missing
CRM013The Country of the Establishment doesn’t match the Company Country
CRM014Sponsored Merchant Country does not match the Payment Facilitator Country
CRM999Unexpected Error