Getting Started guide
Welcome to the Developer Portal's "Getting Started Guide." This resource offers essential information to help TPPs kickstart their API journey, including details on registration process to the Developer portal, APIs, their functionalities, and the security measures in place.
Registration
To get access to the Developer Portal, TPPs need to do the following steps:
- Register and fill in a registration form to create a Developer portal account. Upon registration you will be asked to fill in your profile information and create a password. Having an account gives you access to create applications that are necessary to test the integration with our APIs.
- Read and accept the Terms and Conditions and Data Privacy Notice.
- Submit the registration form. After submitting the registration form, you will receive an e-mail with an activation link. Clicking the activation link received in the email completes your registration process, activates your account, and transfers you to the "Sign In" page. After registration, you will get access to test our APIs in Sandbox environment, but before you can start working with our APIs in production environment, make sure you have the National Bank of the Republic of Macedonia license and eIDAS certificates.
Sign In
Signing in to the Bank portal is granted after successful registration and account activation. To sign-in, you must enter a username or e-mail and password. Signing in grants access to the authorized Developer portal functionality: Application management, Certificate management, User settings and Sandbox.
Environments
We offer two distinct environments: Production and Sandbox.
The Production environment is designed for live API calls, providing a fully operational setting for real-world interactions.
On the other hand, the Sandbox environment serves as a dedicated testing environment, enabling you to experiment, develop, and test API functionalities.
Sandbox is isolated from the production environment, so operations that you perform in the Sandbox don't affect the production environment. The production version of the API provides access to the real customer data, i.e. you will be able to initiate real payments, access account information, confirm funds with Payment Service User’s (PSU’s) permission.
Each environment has its own URL.
Production URL:
https://api.ob.stb.kibs.mk/xs2a/{version}/{service}Sandbox URL:
https://sandbox-api.ob.stb.kibs.mk/xs2a/{version}/{service}API Product catalogue
The Developer portal offers a short description about each API Product and by following the according links available in the API Product Catalogue, you can view the related API Specification of each API Product.
Currently we offer the following API Products:
- Account Information Service. This service enables TPPs to securely access PSU account data.
- Payment Initiation Service. This service empowers TPPs to initiate payments on behalf of the PSU.
- Fund Confirmation Service. This service allows TPPs to verify the availability of funds.
API Reference
API Reference provides a concise and structured description of API endpoints, along with examples of request and response data. Additionally, it includes valuable information on error codes and their meanings, aiding you in effectively integrating and interacting with the APIs.
Our Developer portal offers API Specification for all of our listed API Products.
API Security
Client Credentials Access tokens
The APIs are secured using the OAuth 2.0 Client Credentials Grant, providing a robust authentication mechanism. To access the APIs, you must obtain an access token. To acquire this access token, you need to make a request that included client secret and client ID, both of which are generated upon the creation of an Application.
Transport Layer Security
The communication between the TPP and us is always secured by using TLS version 1.2 or higher. TLS (Transport Layer Security) is a cryptographic protocol used to secure communications over a network. It provides a secure and encrypted connection between you and our APIs.
Applications
Applications play a crucial role in the authorization process, granting TPPs the permission to access our APIs. They are pivotal for acquiring OAuth 2.0 access tokens, which, in turn, enable access to our API resources.
To configure an application, navigate to the Applications section within the Developer portal. You have the flexibility to create applications for both the Sandbox and Production environments. Upon creating an application, you can specify its name, provide a description, set the API scope, and designate the version.
The API Scope outlines the extent of your API access. You can only create applications for the API Services permitted by your TPP role. The API scope is defined with a range of factors including API group, group version, the API itself, API version, as well as specific operations and features.
Once an application is successfully created, it generates an OAuth 2.0 client ID and client secret. These credentials are essential for obtaining OAuth 2.0 tokens, which in turn are used to securely execute API calls and access our API resources.
Applications management
Within the Applications section, TPPs can do the following actions:
- Create Applications - TPPs can freely create applications according to their needs. When creating an Application, TPP has to provide with Application details such as the Application name, description and set an API scope for the Application. Application have can several API Scopes. Upon Application creation, Client ID and Client Secret will be generated.
- Edit Applications - TPPs are allowed to update various attributes of the Application, including the name, description, and API Scopes.
- Create New Versions - TPPs can create new versions of the existing Application, allowing for updates and improvements without affecting the stability of previous versions. Each version can include one or several new API scopes.
- Application Deletion - TPPs can easily delete Applications when they become obsolete or are no longer required.
Sandbox
The Sandbox within the Developer portal provides TPPs with tools and information for API testing purposes. It provides the same APIs as our production environment but with test data, allowing TPPs to freely experiment with APIs.
To assist TPPs in ensuring accurate API calls, the Developer portal has API Specification for each of our API services. API Specifications contain detailed descriptions on our APIs, endpoints and contains various request scenarios with practical code examples.
Additionally, by navigating to the overview sections of each API Service, you will find detailed request scenarios with request examples that will aid you in understanding how our API services work.
By using specification and examples available in the the Documentation, TPP can test the following APIs:
- Access to Account Information API
- Payment initiation API
- Account Consents API
- Funds confirmation API
The Sandbox test data can be efficiently utilized by the following TPPs:
- Account Information Service Provider (AISP)
- Payment Initiation Services Provider (PISP)
- Payment Instrument Issuing Service Provider (PIIS)
To use the Sandbox, QWAC and QSeal certificates are not required. Certificates are required for the production environment.
Available Services
Sandbox provides the following services to TPPs:
- Payment Initiation Service - The Payment Initiation Service allows for initiation of a payment request.
- Account Information Service - The Account Information Service (AIS) offers the following services: list of payment accounts, provide information about account balances and transaction statements relative to a granted consent.
- Confirmation of Funds Service - The Confirmation of Funds Service makes it possible to verify if there is sufficient funds available in the account.
Sandbox test data
The Sandbox in the Developer portal contains test data that aids in API testing and simulates real-life scenarios. For instance, creating an account information consent is a prerequisite for accessing account details. Without the consent, TPP won't be able to access the necessary account information.
The Sandbox test data within the Developer portal includes simulated account information for two Payment Service Users (PSUs). This data encompasses crucial details such as usernames, passwords, and account information, including bank account numbers, account currency, and available funds.
During the Strong Customer Authentication (SCA) simulation, the utilization of usernames and passwords becomes essential. As part of this simulation, the PSU is directed to a dedicated bank SCA screen. Within this screen, the PSU's username and password must be entered, this way effectively simulating the user experience of the PSU.
The following information is available as Sandbox test data:
- Customer name: Snezhana Ristovska
- User name: stob001
- Password: stob001
| Account name | Account type | Account number | Balance | Currency |
|---|---|---|---|---|
| Current Account | BBAN | 200003928211126 | 500000.00 | MKD |
| Current Account | BBAN | 200003959101358 | 30037.00 | MKD |
| Current Account | IBAN | MK07200003854913076 | 736986.00 | EUR |
| Current Account | IBAN | MK07200003854918896 | 18424.00 | EUR |
- Customer name: Aleksandar Jovanovski
- User name: stob002
- Password: stob002
| Account name | Account type | Account number | Balance | Currency |
|---|---|---|---|---|
| Current Account | BBAN | 200003854933058 | 89915.00 | MKD |
| Current Account | BBAN | 200003854934513 | 61.00 | MKD |
| Current Account | IBAN | MK07200003854940818 | 15000.00 | EUR |
| Current Account | IBAN | MK07200003854946056 | 81531.00 | EUR |
Note: All APIs are implemented using RESTful architecture style. For all requests and responses only JSON format can be used.
Note: All account related data (i.e. PSU names, account numbers, account balances, etc.) is fictional and has no relation to real data.
Reset your Sandbox environment
In any situation TPP can always return their Sandbox environment configuration to default state. To do that you need to click on "Reset Sandbox" button.
Availability
Sandbox is available 24/7/365 to test bank services. If you have some problems, please contact our support team.
Test using Postman tool
Postman is the great tool to test and integrate APIs. Download Postman here. Use Postman's documentation and tutorials as help for any questions about using Postman.
eIDAS certificates
To access live environment, TPP must obtain eIDAS certificates from their national QTSP (Quality Trust Service Provider), upload them via Developer Portal's certificates management page and link them to one or more live applications.
eIDAS certificates are essential for establising a secure connection with XS2A. These certificates also contain PSD2 roles (PISP, AISP, PIISP) based on which the Platform restricts consumption of regulatory APIs for client applications. For example, if TPP has not been assigned a "PISP" role, then this TPP will not able to consume Payment Initiation Service APIs.
QWAC
Qualified Web Authentication Certificate is used to establish a secure TLS connection between TPP and the Platform. It sits in the transport layer and is validated by the Web browser. Also, QWAC contains organization id which is used by the Platform to verify TPP's legal status against the National TPP Registry.
QsealC
This Qualified Electronic Seal Certificate is used for signing HTTP requests to XS2A. It helps to ensure the immutability of the messages exchanged with the Platform. To properly sign a request, TPP has to calculate the hash of the HTTP Body and put it into “digest” header. It then has to form a base64 encoded string out of “digest”, “x-request-id”, “psu-id”, and “tpp-redirect-uri” headers, sign the string with the private key associated with their QSealC, and put it into “signature” header along with related metadata. The Platform verifies the signature with the QSealC certificate attached in “tpp-signature-certificate” header.
Test certificates
The Developer portal provides every TPP with test QWAC and QSealC certificates to facilitate more thorough API testing in Sandbox environment. Test certificates are equivalent to real eIDAS certificates. The only difference is that they are pre-generated by the Developer portal for testing purposes only.
Test QWAC certificate is required to establish a successful connection to Sandbox APIs. QSealC is optional.
If you would like to test with Postman, perform the following steps:
- Go to Sandbox -> Test Certificates;
- Download your test certificate(s) and private key(s);
- Open Postman;
- In Postman go to Settings -> Certificates -> Add Certificate;
- In Postman upload the certificate and key files and insert Sandbox URL into "Host" input field. Click 'Add'
After that you will be able to make successful Postman calls.
Production environment
Access to production environment is available only for certified TPPs. The TPP must make sure that it has an license from National Bank of the Republic of Macedonia (PISP, AISP, PIISP).
Access to production environment will be granted automatically after you upload a valid eIDAS certificate to the Developer portal. Once we have validated your TPP identity and legal permissions of PSD2, you can create and use the Applications for the production environment.
eIDAS certificate in Production Environment
After a license is granted by a National Bank of the Republic of Macedonia, the TPP must purchase an eIDAS QWAC certificate (mandatory) and QSeal certificate (optional) from a qualified trust service provider. This certificate will be used for onboarding to production environment. After successful onboarding, the TPPs must use the same certificate in each API call. All connections in production environment targeted towards PSD2 APIs without a valid eIDAS certificate will be rejected.
eIDas Certificate Validation and Revocation validation
When the client certificate is used, it will always be validated by us. The validation contains trust chain validations including expiration check and verification towards revocation on top of the actual signature validation. If any of the validations fail, the connection will be rejected. Please note that the owner of the certificate must renew the certificate before its expiration. If the certificate expires and a new certificate is used, then the certificate enrollment procedure must be initiated.
Note: We reserve the right to revoke TPP access to any of our endpoints in case of intentional misuse. The appropriate PSD2 framework must be adhered to.
Contact us
If you have an unique business case and you want to create a business with us, based on non PSD2 APIs, please contact us via e-mail. In the e-mail please add a description of your business requirements for the financial service you need.
Required License
For Account Information
| API | AISP License | PISP License | Banking License | Payment Instrument Issuing License |
|---|---|---|---|---|
| Account consents | YES | NO | YES | NO |
| Account transactions | YES | NO | YES | NO |
| Account balance | YES | NO | YES | NO |
| Account details | YES | NO | YES | NO |
| Confirmation of Funds | NO | NO | YES | YES |
For Payment Initiation
| API | AISP License | PISP License | Banking License | Payment Instrument Issuing License |
|---|---|---|---|---|
| Payment | NO | YES | YES | NO |
SCA (Strong Customer Authentication) methods
Redirect SCA appraoch
In Redirect SCA, when a PSU initiates a transaction or access to their account through TPP, they are redirected to the website or interface of the user's bank (the Account Servicing Payment Service Provider or ASPSP). The TPP calls authorization API endpoint to initiate this flow, from which the PSU is directed to authenticate themselves through our SCA page and give consent to the operation.
Embedded SCA appraoch
Embedded SCA flow is the process of performing Strong Customer Authentication (SCA) within the user interface of the TPP's application, rather than being redirected to the bank's authentication page.
In this case, after TPP makes initial request to us, and we will respond with an authentication challenge to the PSU, that is displayed directly in the TPPs interface. The PSU can then authenticate and give their consent right through the interface of the TPP.
Decoupled SCA approach
Decoupled SCA flow separates the authentication process from the transaction itself. In this flow, the PSU performs the authentication with us separately from the user interface of the TPP using a separate device or channel such as a mobile banking app.
The flow starts with TPP sending a request to us to initiate a transaction, and we respond with an Authorization URL. The TPP then redirects the user to Auhtorization URL, where the PSU authenticates themselves using their preferred method, such as a password or biometric identification. Once the user has successfully authenticated PSU can proceed with giving their consent. Afterwards we will return a result to the TPP through a callback URL. The TPP can then continue with the transaction.
About API
API
We aim to provide experiences that exceed expectations. We have built our open API around the Representational State Transfer Service architecture (REST), a standard HTTP and easy-to-read and write JavaScript Object Notation (JSON). We follow the Berlin Group API specifications and the Implementation guide and also extended the associated documentation to meet the regulatory requirements.
API HTTP Methods
All services are accessed through APIs using REST based HTTPS methods:
- GET: Reads a resource and returns it;
- POST: Creates a new resource;
- PUT: Requests that the entity provided is stored in the URI provided;
- DELETE: Deletes the resource identified by URI.
API availability status
The API availability status is used to inform TPP Developers regarding API (feature) lifecycle. The availability status is defined for API operations, parameters, models, and properties
| Status | Description |
|---|---|
| Beta | This status is used for the API (feature) that is implemented but is still subject to change. This API can be used by Developers in Sandbox and Production, but Stopanska Banka is not obliged to guarantee that significant changes to this API will not be introduced in future. The features the API in Beta status might also be completely removed in future releases. The Beta API's changes first appear in the Sandbox environment and later in the Production environment. This way TPP Developers will have time to adapt to the upcoming changes in the Production API. |
| Draft | The draft status is used for APIs which are still in design phase. |
| Production | The APIs in Production status are in use in Production environment and should be used in Production applications. No significant changes will be made to the stable APIs (features). |
| Sandbox only | The APIs with Sandbox only status are only available in the Sandbox environment and will not be available in the Production environment. |
| Deprecated | The APIs with Deprecated status will be removed in the future. Deprecated APIs will continue to be supported by the Stopanska Banka Developer's portal for six months. |
API in OpenAPI format
The Bank API specification is available in the OpenAPI format. More information about it can be found here.
API lifecycle
The API version number is always included in the API call
URL: https://api.ob.stb.kibs.mk/{sandbox|live}/xs2a/{version}/{service}
The API version number in the URL indicates the major version of the API. There can be minor updates to the APIs which do not change the major version number. The major version number only changes when the big number changes which might significantly impact API backwards compatibility is implemented. The new major versions of specification will depend on Berlin Group specification releases and National Bank of the Republic of Macedonia mandates, such changes will be published 3 months prior to the release date. The older versions of APIs will be deprecated but remain available for up to six months after release implementation, and removed after this period. API major version number will be incremented with every new major API release, e.g. next API version will typically have URL in following format:
HTTP Response codes
The HTTP response code is communicating the success or failure of a TPP request message. The 4XX HTTP response codes only be given if the current request cannot be fulfilled, in example if a payment initiation cannot be posted, or account transactions cannot be retrieved. A request to get the status of an existing payment or a consent returns HTTP response code 200 since the actual request to retrieve the status succeeded, regardless if that payment or consent state is set to failure or not.
| Code | Description |
|---|---|
| 200 OK | This return code is permitted if a request was repeated due to a time-out. The response in that might be either a 200 or 201 code. The POST for a Funds request will also return 200 since it does not create a new resource. DELETE Response Code where a payment resource has been cancelled successfully and no further cancellation authorisation is required. |
| 201 Created | POST response code where Payment Initiation or Consent Request was correctly performed. |
| 202 Accepted | DELETE response code, where a payment resource can be cancelled in general, but a cancellation authorisation is needed in addition. |
| 204 No Content | DELETE response code where a consent resource was successfully deleted. The code indicates that the request was performed, but no content was returned. |
| 400 Bad Request | Validation error occurred. This code will cover malformed syntax in request or incorrect data in payload. |
| 401 Unauthorized | The TPP or the PSU is not correctly authorized to perform the request. Retry the request with correct authentication information. |
| 403 Forbidden | Returned if the resource that was referenced in the path exists but cannot be accessed by the TPP or the PSU. |
| 404 Not found | Returned if the resource or endpoint that was referenced in the path does not exist or cannot be referenced by the TPP or the PSU. |
| 405 Method Not Allowed | This code is only sent when the HTTP method (PUT, POST, DELETE, GET etc.) is not supported on a specific endpoint. It has nothing to do with the consent, payment or account information data model. |
| 406 Not Acceptable | The ASPSP cannot generate the content that the TPP specified in the Accept header. |
| 408 Request Timeout | The server is still working correctly, but an individual request has timed out. |
| 415 Unsupported Media Type | The TPP has supplied a media type which the ASPSP does not support. |
| 429 Too Many Requests | The TPP has exceeded the number of requests allowed by the consent or by the RTS. |
| 500 Internal Server Error | Internal server error occurred. |
| 503 Service Unavailable | The ASPSP server is currently unavailable. Generally, this is a temporary state. |