Onboarding API

In order to streamline the onboarding process for sponsored merchants on your platform, you can create a tailored user interface (UI) to collect merchants’ data and subsequently submits it to our API.

Within this guide, you will find an explanation of the entire process of onboarding a sponsored merchant.

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

CER

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

Before you start

Ensure that during the onboarding process your Account Manager shared with you the necessary credentials:

Client ID
Client Secret

Once you have these, you will be able to initiate the onboarding process via the API.

Keep your credentials confidential to maintain security of your transactions.

Onboard Sponsored Merchants

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

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

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

Condition

Description

merchant

String

Mandatory

Object that defines the Merchant

name

String
<=40

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

Number
4-4

Mandatory

NIP as per CEIDG

mcc

String
<=10

Mandatory

Company’s MCC Code

pkd

String
7-7

Check the list and format: https://www.biznes.gov.pl/en/table-pkd-code)

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
<=100

Mandatory

Merchant’s Address Street

postalcode

String
<=25

Mandatory

Merchant’s Address Postal Code

locality

String
<=20

Mandatory

Merchant’s Address Locality

country

Number
3-3
Format ISO 3166, Number 3 code (ex: Poland – 616)

Mandatory

Merchant’s Address Country

website

String
<=100

Mandatory

Merchant’s website

signedAgreements

String
“True”
“False”
If “False”, Sponsored Merchant will be registered but remain “Inactive”

Mandatory

Confirmation of signed agreements

backofficeEmail

String
<=55

Mandatory

SIBS Backoffice email address.

pepStatus

String
“Active”
“Inactive”
Default: “Active”

Mandatory

PEP 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

Optional

Owner’s phone

email

String
<=55

Optional

Owner’s email

address

String
<=100

Optional

Owner’s address

nif

Number
11-11

Mandatory

Owner’s nif

integrationSupportContact

String

Optional

Object that defines an integration support contact

name

String
<=40

Optional

First and Last Name Contact for integration Support

phone

String
<=16

Optional

Phone number Contact for integration Support

email

String
<=55

Optional

Email address Contact for integration Support

shop

Mandatory

Object that defines the Establishment

name

String
<=20

Mandatory

Establishment Name

address

String

Mandatory

Establishment Address

street

String
<=100

Mandatory

Street

postalcode

String
<=25

Mandatory

Postal Code

locality

String
<=20

Mandatory

Locality

country

Number
3-3
Format ISO 3166, Number 3 code (ex: Poland – 616)

Mandatory

Country

email

String
<=55

Mandatory

Establishment Email

phoneNumber

String
<=16

Mandatory

Establishment Phone

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

“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-02-C”
“VIS-02-D”
“VIS-02-P”
“VIS-01-C”
“VIS-01-D”
“VIS-01-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”

Mandatory

Product Invoice Indicator

paymentMethodType

String

“Direct Debit”
“Bank Transfer”
Default: “Direct Debit”

Mandatory

Payment method type for the invoicing of the sponsored merchant

invoiceEmail

String
<=55

Mandatory

Invoice email address

payout

String

Conditional

Object that defines the Payout Information.
Mandatory if InvoiceIndicator is “Sponsored Merchant”
When this fields are empty, the value to be considered will be the ones parametrized at the Payment Facilitator level.

bankAccount

String
26-26

Conditional

Sponsored Merchants bank account

iban

String
<=34

Conditional

Sponsored Merchants iban

bic

String
8<11

Conditional

Sponsored Merchants bic

numDaysPayout

Number

Conditional

Sponsored Merchants Payout Number of Days

Here is an example of a successful onboarding response:

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

KYC

Note that your sponsored merchants will be subject to thorough onboarding evaluations, encompassing KYC verifications, unless specific agreements have been made during your own onboarding.

If they are not required to undergo KYC at this stage, the onboarding process via API will proceed without any interruptions, and the Sponsored Merchants will be generated.

If the sponsored merchants are required to undergo KYC diligences, we will conduct asynchronous diligences and provide you with the results via webhook.

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

Below you can find the range of Status Codes and Messages with additional asynchronous messages that you can receive via webhooks as well:

Status Code

Message

Processing Mode

000

Success

Syncronous

001

Our Solutions

Products

Benefits

New Feature

More

Clients

Clients

Partners

More

Documentation

Developers

TPP PSD2

Onboarding API

Before you start

Onboard Sponsored Merchants

Error Handling

Welcome!

Register an account

Want to start testing in a closed environment

Are you ready to test in an end-to-end environment

Welcome!

Log In

Start testing in a closed environment

Test in an end-to-end environment

Bem vindo!

Inicie Sessão

Inicie os testes num ambiente fechado

Inicie os testes num ambiente em Produção

Bem vindo!

Crie uma conta

Quer começar a testar num ambiente fechado?

Está pronto para testar num ambiente em Produção

Por favor introduza o seu contacto e entraremos em contacto consigo brevemente