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. |
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: “Inactive” | Mandatory | Politically 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. |
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. |
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 |
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”, “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” | 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 “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 |
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 |
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 | Operations | Details |
---|---|---|---|
CRM000 | Success. | n/a | n/a |
CRM001 | Sponsored Merchant already exists. | Merchant Onboarding Operations | A Sponsored Merchant with the received NIF already exists. |
CRM002 | PKD is invalid. | Merchant Onboarding Operations Merchant Update Operations Create shop Operations Update shop Operations | PKD does not exist in the list of configured PKDs. |
CRM003 | MCC 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. |
CRM005 | IBAN is invalid. | Merchant Onboarding Operations | IBAN is invalid according to the implemented validation rules. |
CRM006 | Product 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). |
CRM007 | Required field [field_name] missing. | All | A required attribute in the API invocation was not sent. |
CRM008 | Payment Facilitator is invalid. | All | Payment Facilitator ID does not exist in the system. |
CRM009 | Product [product] is duplicated. | Merchant Onboarding Operations Create shop Operations Add payment method Operations Delete payment method Operations | Duplicate products in the API. |
CRM010 | Invoice 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. |
CRM011 | This Product of Establishment has already been added as an Establishment Product. | Add payment method Operations | The specified product is already among the products of the Establishment. |
CRM012 | Product 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. |
CRM013 | Sponsored 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. |
CRM015 | The 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. |
CRM016 | The 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. |
CRM017 | The 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. |
CRM018 | Invalid Type Of Integration. | Merchant Onboarding Operations Create shop Operations Update shop Operations | Integration type in the Webhook is invalid. |
CRM019 | Webhook 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. |
CRM020 | Invalid 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. |
CRM021 | Invalid Webhook Notification. | Merchant Onboarding Operations Create shop Operations Update shop Operations | Notification type in the Webhook is invalid. |
CRM022 | Webhook 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. |
CRM023 | Webhook 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. |
CRM024 | Webhook 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. |
CRM025 | Order still in progress for TIN [TIN_value]. | Merchant Onboarding Operations | There is an order in progress/processing for the indicated TIN. |
CRM029 | Establishment ExternalID already exists. | Create shop Operations | The Payment Facilitator is sending a request to create an Establishment that already exists in the system. |
CRM030 | Order 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. |
CRM031 | TerminalID already exists. | Create Terminal Operations | The Payment Facilitator is sending a request to create a Terminal that already exists in the system for the indicated Establishment. |
CRM032 | Payment 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. |
CRM033 | Sponsored 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. |
CRM034 | Establishment 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. |
CRM035 | Terminal is invalid. | Cancel terminal Operations | The indicated Terminal does not exist or is not in a valid state. |
CRM036 | Last Terminal cannot be cancelled. | Cancel terminal Operations | The indicated Terminal is the only one of the Establishment, therefore it cannot be canceled. |
CRM037 | Product is not valid for Establishment. | Delete payment method Operations | The indicated product does not exist in the Establishment or is not in a valid state. |
CRM038 | [PaymentFacilitatorId] is not a Payment Facilitator. | All | The indicated Payment Facilitator is not actually a Payment Facilitator. |
CRM039 | Order still in progress for Merchant [merchant_id]. | Merchant Update Operations | There is an order in progress for the indicated Merchant. |
CRM040 | No Country found for specified [CountryCode]. | Merchant Onboarding Operations Create shop Operations Merchant Update Operations | The specified country code does not exist. |
CRM041 | Transactional Country is invalid. | Create shop Operations | 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 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. |
CRM044 | Invalid Terminal Channel Type for this Establishment. | Create Terminal Operations | 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 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. |
CRM046 | Sponsored 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. |
CRM999 | Unexpected Error. | All | Unexpected error occurred. |