MacroBank openAPI

Last update: 29 Квітня, 2025

1. Glossary

Account Information Service (AIS) – as defined in Art. 66 of PSD2.

Account Information Service Provider (AISP) – TPPs using the XS2A interface to access information about the PSU’s payment account.

Account Service or Payment Service Provider (ASPSP) – common abbreviation of AIS or PIS.

Authentication – a process in result of which the ASPSP verifies the PSU’s identity.

Basic Scope of the AIS, PIS and CAF services – services required by PSD2.

Certificate Signing Request (CSR) – a key generated when requesting the issuance (signature) of an TLS/SSL certificate.

Confirmation of the Availability of Funds (CAF) – a service defined in Art. 65 of PSD2.

External Authorization Tool (EAT) – a system providing the SCA procedure, i.e. the strong authentication of PSU.

Extra Scope of the AIS, PIS and CAF services – services exceeding the requirements laid down in PSD2.

European Banking Authority (EBA) – the European Banking Authority.

ETSI – European Telecommunication Standardization Institute.

Granting Consent – a process in result of which the PSU grants TPP consent to access his/her account held by the ASPSP in order to effect a service, including the AIS, PIS and CAF services.

OAuth2 – OAuth2 is an open authorization standard. It allows users to share their private resources (e.g. pictures, films, contacts) stored at a given site with another party without a necessity to fathom the complexities of authorisation, usually providing the user name and a token (one-time passwords).

Payment Initiation Service Provider (PISP) – TPPs using the XS2A interface to initiate a payment transaction debited to the PSU’s account.

Payment Initiation Services (PIS) – as defined in Art. 67 of PSD2.

Payment Instrument Issuer Service Provider (PIISP) – TPPs using the XS2A interface to confirm the availability at the PSU’s payment account of an amount necessary to effect the payment transaction performed on the basis of an instrument issued by the PIISP.

Payment Services Directive (PSD) – Directive 2007/64/EC of the European Parliament and of the Council on payment services in the internal market.

Payment Services Directive 2 (PSD2) – Directive 2015/2366 of the European Parliament and of the Council on payment services in the internal market and repealing Directive 2007/64/EC.

Payment Services User (PSU) – natural or legal person making use of a payment service in the capacity of either payer or payee, or both.

Payment account – an account held in the name of one or more payment service users which is used for the execution of payment transactions.

Regulatory Technical Standard (RTS) – Commission Delegated Regulation (EU)
No. 2018/389 of 27 November 2017 supplementing Directive (EU) 2015/2366 of the European Parliament and of the Council with regard to regulatory technical standards for strong customer authentication and common and secure open standards of communication.

Revised Payment Services Directive (PSD2) – Directive (EU) 2015/2366 of the European Parliament and of the Council of 25 November 2015 on payment services in the internal market (revised payment services directive).

Strong Customer Authentication (SCA) – means an authentication based on the use of two or more elements (components) categorised as knowledge (something only the user knows), possession (something only the user possesses) and inherence (something the user is) that are independent, in that the breach of one does not compromise the reliability of the others, and is designed in such a way as to protect the confidentiality of the authentication data.

Swagger – is an open source software which helps design, build, document and consume the RESTful Web services.

TS 119 495 – a technical specification of the standard concerning the qualified certificate profile for the needs of the Payment Services Directive (Electronic Signatures and Infrastructures (ESI); Sector Specific Requirements; Qualified Certificate Profiles and TSP Policy Requirements under the Payment Services Directive 2015/2366/EU), updated as at the date of publication of this standard.

XS2A (Access to Account) – access to payment accounts used to perform AIS, PIS, CAF and other services affected as part of the OpenAPI.

2. General provisions

On the internal market, the Payment Service Directive makes an opportunity to create new products and services for payment solution. All players in the financial market such as banks, payment services, and systems and new type subjects TPP can take this opportunity.

Among new services listed following category of services:

Account Information Service (AIS) – service which provides information on payment accounts;
Payment Initiation Service (PIS) – service which initiates payments;
Confirmation of the Availability of Funds (CAF) – service which confirms the availability of funds.

For implementation new services ASPSP should provide to authorized third-party providers (TPP) the instrument via OpenAPI for access to customer’s accounts.

The present document provides the specification of implementation interface OpenAPI for platform Macrobank. This document was based on “Commission Delegated Regulation (EU) 2018/389 of 27 November 2017 supplementing Directive (EU) 2015/2366 of the European Parliament and of the Council with regard to regulatory technical standards for strong customer authentication and common and secure open standards of communication” (Source text).

Its main goal is to promote rules for communication between ASPSP and TPP for the AIP, PIS, and CAF functions.

In view of the fact that OpenAPI requirements allow to ASPSP and TPP provides services not only requirement of standard services but and extension services, then those services can split into two different groups:

Basic Scope – services mandatory by PSD2;
Extra Scope – extension services are provided specific ASPSP.

2.1. Stakeholders

The following three types of roles Standard defines 3 types of OpenAPI agent’s role:

PSU – user (holder) payment account;
ASPSP – service provider, which present integration payment services, provides XS2A interface for TPP;
TPP – third-party service provider, which used XS2A interface for access to PSU’s payment account and received permission from PSU for this access.

ASPSP also can serve as TPP and use interface, that over ASPSP provides.

2.2. Process interaction

The main case interaction is the request from TPP to services, which provide by APSPS for specific PSU. If you want to implement this interaction, you should do the following steps:

TPP makes the request to ASPSP for registration and generation Certificate Signing Request to OpenAPI’s connection.
ASPSP validates the possibility of connection TPP to OpenAPI, then ASPSP registers this TPP in trusted TPP list and gives Certificate for connection.
TPP uses received Certificate to connect to ASPSP by OpenAPI interface.
PSU chooses the option of account authorization on ASPSP in User Interface TPP. After that, PSU starts OATH2.0 authorization.
After success authorization, ASPSP gives JWT-token to TPP. This token defines specific PSU and access right list for this PSU’s account.
TPP uses receiving JWT to access to ASPSP services and PSU’s account operations.

TPP can have official register Certificate eIDAS. In this case, in section 1-3 this TPP should present this certificate in the registration step and uses it to connection OpenAPI interface.

2.3. Security

Security requirements of interaction defined in PSD2 and split into to group:

Strong authentication;
Encryption sending by public channel data.

The process of authentication TPP and ASPSP uses two way SSL protocol (muTLS). This protocol allowed to both participant validate certificates, trusted identify another side, and select cryptographic algorithms to exchange data.

Granting access rights to PSU’s account execute via OAUTH2.0 protocol. Result of procedure this protocol is JWT token receiving TPP. This token contains information about access level (role) to PSU’s account. For this reason, TPP is strong authorized commands on behalf of PSU.

ASPSP executes strong identification of PSU using two or more SCA methods.

After successfully finishing process of authentication, data exchange is using TLS1.2+ protocol. It prevents unauthorized access to data sent via the public channel.

2.4. Logging of operations

All communication operations are registered in the relevant journal (logfiles). It allows collect and handle receiving or initializing requests and result in realtime.

Recording request and processing result can provide process participants via email, SMS, or other channels on schedule or real time.

Process participants negotiate about reglament of journal exchange independently.

2.5. Monitoring of OpenAPI interface

In line with the requirements of directive PSD2, has been implemented automation (every minute) monitoring of accessible of the services OpenAPI interface. The process executes external (over OpenAPI system’s equipment) system. Information about accessibility of interface and services is collected.

ASPSP provides public statistics about automation monitoring on the special web page. Web-link for this page based on the next rule:

http://<hostname>/openapi/monitoring/statisic

3. Process of communication between participants

Step by step process required for communication between participants of information exchange via OpenAPI interface is provided in this section.

3.1. Registration TPP on ASPSP

Algorithm actions for registration TPP on ASPSP:

TPP goes to the section ‘Registration TPP’ at main web page ASPSP.
TPP fills the application with details about himself and required role (AISP, PISP, PIISP)
In addition to the application, TPP presents CSR is required for generation certificate. If TPP already has valid eIDAS certificate than TPP sends this certificate instead of CSR.
ASPSP handles application from TPP, validates presented information in different ways.
In case success validation ASPSP generates a new certificate based on presented CSR or joins presented eIDAS certificate. After that, ASPSP sends certificate (new or presented) to the email specified on TPP’s application. Along with this certificate, the CA certificate is sent by email.
ASPSP inject to table information about new TPP.
TPP sets up received core certificate to the System and configure connection with ASPSP using received TLS certificate.
TPP adds an opportunity PSU to choose an option to join his account from ASPSP at the private cabinet TPP.

The execution of this list allows to begin a safe and trusted connection between TPP and ASPSP

3.2. Providing to TPP access for PSU’s account

Algorithm actions for receiving an access TPP to PSU account:

TPP allows arbitrarily to PSU to choose at private cabinet TPP an option of joining his account at ASPSP.
After choosing an option of joining of account there is a next request from TPP to ASPSP for receiving an interface of authorisation according to protocol OAUTH2.0.
PSU is going through the procedure of authorisation at ASPSP according to principles of SCA, at side of ASPSP, which allows for reliable identification of rules of PSU to access to an account.
During authorisation PSU sets a level of access to his account for TPP choosing a role for TPP (chapter 2.1. of this document)
After successful authorisation and according to protocol OATH2.0 TPP gets JWT token with information about access rights and their expiration date.
Received token TPP saves in his database a connection to PSU which initiated a procedure. Also it is used for requests to OpenAPI ASPSP for identification of PSU.

This algorithm is possible after successful procedure of registration for TPP on the relevant ASPSP. After that TPP has all necessary keys and certificates for access to OpenAPI ASPSP and for commands of interface from chapter 4 and 5.

3.3. Interaction with interface OpenAPI

3.3.1. Structure of the request address

Any request from TPP to OpenAPI ASPSP has following structure:

https://mb5openapi.<hostname>/<version>/<type>/<command>

where

<hostname> – address of server ASPSP;

<version> – version of OpenAPI in format “vxxx”, for example, “v100”;

<type> – type of command: one of four types auth/accounts/payments/confirmation;

<command> – command of OpenAPI.

All request is HTTPS POST request with transmission parameter in header body in JSON format. The header of request must contain parameters

Content-Type: application/json

Authorization: Bearer {TOKEN}

where

{TOKEN} – token, which is received after execution of access procedure at paragraph 3.2. of this document

3.3.2. Mutual Authentication of the TPP and the ASPSP

The mutual authentication of the TPP and the ASPSP takes place on the basis of the X.509v3 certificates issued by ASPSP or a trusted third party. A trusted third party may by, in particular, an institution performing the role of the Identity Hub. It may also be any other party offering a trust-based relationship based on public key infrastructure mechanisms.

All operations consisting in the flows specified and described below in sections 4 and 5 are possible only in a situation of a correct authentication in a process that comprises a mutual authentication of the server and the client (mutual authentication). The TPP and the ASPSP may have the role of both a server and a client, but, in each case, it is required that the parties to the communication mutually authenticate each other.

3.3.3. Communication Protocol

HTTP /2 or HTTP 1.1, secured by TLS 1.2+ with a mutual authentication of the client and the server by means of the X.509v3 certificates will be used as the communication protocol. Due to the requirement to ensure non-repudiation (request and response signing), only the POST method will be used in the http communication.

3.3.4. Canonical Data Model

The detailed description of the data structure is available in the swagger, in section ‘Models’.

3.3.5. Message format

The data exchange format is JSON with the UTF-8 encoding. All messages have a defined JSON schema draft #4. The parameter names will be saved camelCase.

4. Basic Scope services

4.1. Services of Accounts category

4.1.1. getaccounts

Service for getting list of PSU payment accounts at ASPSP

Request parameters:

without parameters

Response parameters:

Array of objects with parameters structure as shown in the table below:

Name of parameter	Type	Description
id	int	Account id
designation	string	Payment account number or IBAN
description	string	Name of account owner by default
currency	string	Three letters of currency, for example “USD”, “EUR”
currency_code	int	Сurrency code by internal accounting
active	bool	Account activity flag
blockdebit	bool	Debit operations lock flag
blockcredit	bool	Credit operations lock flag
closed	bool	Closed account flag

Example of response for successful execution of request:


        [
         {
          "id":6993,
          "designation":"GB45NNNN00123421000001",
          "description":"Vasiliy Sidorov",
          "currency":”EUR”,
          "currency_code":2,
          "active":1,
          "blockdebit":0,
          "blockcredit":1,
          "closed":0
         },
         {
           ...      <next account data if present>
         },
         ...
        ]

4.1.2. getaccount

Service for getting details for PSU payment account at ASPSP

Request parameters:

Name of parameter	Type	Description
account	string	Account Number or IBAN
currency	string	Three letters of currency, for example “USD”, “EUR”

Response parameters:

Name of parameter	Type	Description
accountid	int	Account id
designation	string	Payment account number or IBAN
currency	string	Three letters of currency, for example “USD”, “EUR”
currency_code	int	Сurrency code by internal accounting
balance	number #.##	Account balance in account currency
plan_balance	number #.##	Reserved for future use
balancebc	number #.##	Account balance in base currency
thedate	string	Date with format “YYYYMMDD”
available_amount	number #.##	Current available amount of funds
overdraft_amount	number #.##	Current overdraft amount
overdraft_limit	number #.##	Limit for overdraft
balance_ib	number #.##	Reserved for future use
favorite	bool	Is account favorit flag
customdescription	string	Additional description of account

Example of response for successful execution of request:


        {
         "accountid":6994,
         "designation":"GB18NNNN00123421000002",
         "currency":2,
         "currency_code":"EUR",
         "balance":-75,
         "plan_balance":-75,
         "balancebc":-75,
         "thedate":"20190411",
         "available_amount":-75,
         "overdraft_amount":0,
         "overdraft_limit":0,
         "balance_ib":-75,
         "favorite":0,
         "customdescription":null
        }

4.1.3. getstatement

Service for getting statement for the period for PSU payment account at ASPSP

Request parameters:

Name of parameter	Type	Description
account	string	Account Number or IBAN
beginDate	string	Date with format “YYYYMMDD”
endDate	string	Date with format “YYYYMMDD”

Response parameters:

Array of objects with parameters structure as shown in the table below:

Name of parameter	Type	Description
#idnty	int	Sequence number in response
#transactionid	int	Transaction ID
thedate	string	Date with format “YYYYMMDD”
designation	string	Payment account number or IBAN
description	string	Name of account owner by default
currcodechr	string	Three letters of currency, for example “USD”, “EUR”
amtdebit	number #.##	Transaction amount for debit
amtcredit	number #.##	Transaction amount for credit
#amtdebitbc	number #.##	Transaction amount for debit in base currency
#amtcreditbc	number #.##	Transaction amount for credit in base currency
amount	number #.##	Total transaction amount
#amountbc	number #.##	Total transaction amount in base currency
balance	number #.##	Current Account balance
#balancebc	number #.##	Current Account balance in base currency
docnumber	int	System number of transaction
src	string	Short name of the document
info	string	Payment description
reference	string	Reserved for future use
#completed	bool	0 - virtual transaction, 1 - real transaction
#revaluation	bool	Revaluation transaction flag
documentid	int	Intуrnal id of the transaction
#auser	string	username of author of the transaction
#key	int	Reserved for future use

Example of response for successful execution of request:


        [
         {
          "#idnty":4,
          "#transactionid":12,
          "thedate":"20181121",
          "designation":"60600.0001",
          "description":"Currency exchange transit account",
          "currcodechr":"EUR                 ",
          "amtdebit":1000,
          "amtcredit":null,
          "#amtdebitbc":1000,
          "#amtcreditbc":null,
          "amount":-1000,
          "#amountbc":-1000,
          "balance":6400,
          "#balancebc":6400,
          "docnumber":2317,
          "src":"EXCHANGE",
          "info":"Exchange 1000.00 EUR -> 1000.00 GBP rate: 1",
          "reference":"",
          "#completed":1,
          "#revaluation":0,
          "documentid":1458,
          "#auser":"dbo",
          "#key":-1000
         },
         {
           ...      <next transaction data if present>
         },
         ...
        ]

4.1.4. gettransaction

Service for getting a specific transaction details.

Request parameters:

Name of parameter	Type	Description
account	string	Account Number or IBAN
transactionid	int	Transaction ID

Response parameters:

Name of parameter	Type	Description
thedate	string	Date with format “YYYYMMDD”
designation	string	Payment account number or IBAN
description	string	Name of account owner by default
currcodechr	string	Three letters of currency, for example “USD”, “EUR”
amtdebit	number #.##	Transaction amount for debit
amtcredit	number #.##	Transaction amount for credit
#amtdebitbc	number #.##	Transaction amount for debit in base currency
#amtcreditbc	number #.##	Transaction amount for credit in base currency
amount	number #.##	Total transaction amount
#amountbc	number #.##	Total transaction amount in base currency
balance	number #.##	Current Account balance
#balancebc	number #.##	Current Account balance in base currency
docnumber	int	System number of transaction
src	string	Short name of the document
info	string	Payment description
#completed	bool	0 - virtual transaction, 1 - real transaction
#revaluation	bool	Revaluation transaction flag
documentid	int	Internal id of the transaction
#auser	string	Username of author of the transaction

Example of response for successful execution of request:


        {
         "thedate":"20181121",
         "designation":"60600.0001",
         "description":"Currency exchange transit account",
         "currcodechr":"EUR",
         "amtdebit":1000,
         "amtcredit":null,
         "#amtdebitbc":1000,
         "#amtcreditbc":null,
         "amount":-1000,
         "#amountbc":-1000,
         "balance":6400,
         "#balancebc":6400,
         "docnumber":2317,
         "src":"EXCHANGE",
         "info":"Exchange 1000.00 EUR -> 1000.00 GBP rate: 1",
         "#completed":1,
         "#revaluation":0,
         "documentid":1458,
         "#auser":"dbo"
        }

4.1.5. checkconsent

This service allows TPP to сheck availability of consent. PSU may cancel consent directly at ASPSP interface and TPP must check it, using checkconsent service.

Request parameters:

without parameters

Response parameters:

Name of parameter	Type	Description
status	bool	Status of given consent “0” - no consent,“1” - consent presented

Example of response for successful execution of request:


        {
          "status":1
        }

4.1.6. deleteconsent

This service allows TPP to remove consent independently or on request by PSU from TPP interface.

Request parameters:

without parameters

Response parameters:

Name of parameter	Type	Description
result	bool	“0” - not removed, “1” - consent removed

Example of response for successful execution of request:


        {
          "result":1
        }

4.2. Services of Payment category

4.2.1. createpayment

Service allows to create payments from payment account PSU.

Request parameters:

Name of parameter	Type	Description
documenttype	string	Type of transaction. One of the following: “Outgoing_Payment_FReq” - for SWIFT; “Outgoing_SEPAPAY_FReq” - for SEPA.
data	object	transaction data for SWIFT or SEPA payment

Parameters structure for object data for SWIFT payment:

Name of parameter	Type	Description
debitaccountid	int	Debit account ID
amount	number #.##	Amount of funds for payment
currencyid	int	Сurrency code by internal accounting
info	string	Text message for payment
extaccountnumber	string	Account Number or IBAN
benefname	string	Beneficiary name
registrationnumber	string	Beneficiary registration number
benefcountry	int	Beneficiary country according to ISO 3166-1 alpha-2
benefaddress	string	Beneficiary address
tariffamount	number #.##	Amount of commission
totalamount	number #.##	Total amount of payment with commission
chargestype	int	Type of commission
prioritet	int	Priority of payment
extbankswift	string	Intermediary bank SWIFT code
extbankname	string	Intermediary bank name
extbenefbankcountry	int	Intermediary country according to ISO 3166-1 alpha-2
extbankaddress	string	Intermediary bank address

Example of request:


        {
          "documenttype":"Outgoing_Payment_FReq",
          "data":
          {
            "debitaccountid":"6993",
            "amount":200,
            "currencyid":"2",
            "info":"Test SWIFT",
            "extaccountnumber":"GB29NWBK60161331926819",
            "benefname":"Test Testov",
            "registrationnumber":"",
            "benefcountry":"232",
            "benefaddress":"London",
            "tariffamount":0,
            "totalamount":0,
            "chargestype":"3",
            "prioritet":"1",
            "extbankswift":"BARKGB21XXX",
            "extbankname":"BARCLAYS STOCKBROKERS LTD.",
            "extbenefbankcountry":"232",
            "extbankaddress":"TAY HOUSE 300 BATH STREET LANARKSHIRE"
          }
        }

Parameters structure for object data for SEPA payment:

Name of parameter	Type	Description
debitaccountid	int	Debit account ID
amount	number #.##	Amount of funds for payment
currencyid	int	Сurrency code by internal accounting
info	string	Text message for payment
extaccountnumber	string	Account Number or IBAN
benefname	string	Beneficiary name
registrationnumber	string	Beneficiary registration number
benefcountry	int	Beneficiary country according to ISO 3166-1 alpha-2
external_account	string	Reserved for future use
benefaddress	string	Beneficiary address
extbankswift	string	Intermediary bank SWIFT code
extbankname	string	Intermediary bank name
extbenefbankcountry	int	Intermediary country according to ISO 3166-1 alpha-2
extbankaddress	string	Intermediary bank address

Example of request:


        {
          "documenttype":"Outgoing_SEPAPAY_FReq",
          "data":
          {
            "debitaccountid":"6993",
            "amount":200,
            "currencyid":"2",
            "info":"Test SEPA",
            "extaccountnumber":"GB29NWBK60161331926819",
            "benefname":"Roman Peps",
            "registrationnumber":"1234",
            "benefcountry":"232",
            "external_account":"0",
            "benefaddress":"London",
            "extbankswift":"BARKGB21XXX",
            "extbankname":"BARCLAYS STOCKBROKERS LTD.",
            "extbenefbankcountry":"232",
            "extbankaddress":"TAY HOUSE 300 BATH STREET LANARKSHIRE"
          }
        }

Response parameters:

Name of parameter	Type	Description
result	bool	Result of payment creation process “0” - not created,“1” - payment successfully created
fieldErrors	array	Array with detected error codes and descriptions. If result is 1 - empty object.
message	string	Text description of result of operation
objectid	int	ID of created payment, if result is 1

Example of response for successful execution of request:


        {
         "result":1,
         "fieldErrors":[],
         "message":"Use your payment or OTP password to sign the document",
         "objectid":5672
        }

4.2.2. getpayments

Service for getting list of payment transactions for the period for PSU payment account at ASPSP

Request parameters:

Name of parameter	Type	Description
account	string	Account Number or IBAN
beginDate	string	Date with format “YYYYMMDD”
endDate	string	Date with format “YYYYMMDD”

Response parameters:

Array of objects with parameters structure as shown in the table below:

Name of parameter	Type	Description
paymentID	int	Payment ID
documenttype	string	Type of transaction. One of the following: “Outgoing_Payment_FReq” - for SWIFT; “Outgoing_SEPAPAY_FReq” - for SEPA.
data	object	transaction data for SWIFT or SEPA payment (for object details see paragraph 4.2.1)
thedate	string	Date with format “YYYYMMDD”
statusdescription	string	Text description of the status of payment

Example of response for successful execution of request:


        [
         {
          "paymentid":8619,
          "documenttype":“Outgoing_SEPAPAY_FReq”,
          "data":
          "debitaccountid":"6993",
          "amount":200,
          "currencyid":"2",
          "info":"Test SEPA",
          "extaccountnumber":"GB29NWBK60161331926819",
          "benefname":"Roman Peps",
          "registrationnumber":"1234",
          "benefcountry":"232",
          "external_account":"0",
          "benefaddress":"London",
          "extbankswift":"BARKGB21XXX",
          "extbankname":"BARCLAYS STOCKBROKERS LTD.",
          "extbenefbankcountry":"232",
          "extbankaddress":"TAY HOUSE 300 BATH STREET LANARKSHIRE"
         },
         {
           ...      <next transaction data if present>
         },
         ...
        ]

4.2.3. getpayment

Service for getting details for specific payment.

Request parameters:

Name of parameter	Type	Description
paymentID	int	Payment ID

Response parameters:

Name of parameter	Type	Description
data	object	transaction data for SWIFT or SEPA payment (for object details see paragraph 4.2.1)

Example of response for successful execution of request for SEPA payment:


        {
          data:
          {
           "paymentid":8619,
           "documenttype":“Outgoing_SEPAPAY_FReq”,
           "data":
           "debitaccountid":"6993",
           "amount":200,
           "currencyid":"2",
           "info":"Test SEPA",
           "extaccountnumber":"GB29NWBK60161331926819",
           "benefname":"Roman Peps",
           "registrationnumber":"1234",
           "benefcountry":"232",
           "external_account":"0",
           "benefaddress":"London",
           "extbankswift":"BARKGB21XXX",
           "extbankname":"BARCLAYS STOCKBROKERS LTD.",
           "extbenefbankcountry":"232",
           "extbankaddress":"TAY HOUSE 300 BATH STREET LANARKSHIRE"
          }
        }

4.2.4. cancelpayment

Service for canceling not processed payment.

Request parameters:

Name of parameter	Type	Description
account	string	Account Number or IBAN
paymentID	int	Payment ID

Response parameters:

Name of parameter	Type	Description
result	bool	“0” - not canceled, “1” - payment canceled

Example of response for successful execution of request:


        {
          "result":1
        }

4.3. Services of Confirmation category

4.3.1. checkfunds

Service for getting simple response-confirmation of availability of funds for given amount.

Request parameters:

Name of parameter	Type	Description
account	string	Account Number or IBAN
amount	string	Amount of funds to be checked
currency	string	Three letters of currency, for example “USD”, “EUR”

Response parameters:

Array of objects with parameters structure as shown in the table below:

Name of parameter	Type	Description
result	bool	Result of checking availability of funds: “0” - not enough, “1” - enough

Example of response for successful execution of request:


        {
         "result":1
        }

5. Extra Scope services

Additional services provided by ASPSP for Macrobank 5 are developing and will be presented at next versions of current document.

6. Response statuses

The technical statuses will be returned by the following http codes:

STATUS	DESCRIPTION
200 OK	The operation was successful
204 No Content	The operation was successful. The response does not contain additional information.
400 Bad Request	The request is syntactically incorrect
401 Unauthorized	Incorrectly authenticated user
403 Forbidden	Authorization error (no rights to access the resource)
405 Method Not Allowed	Use of an inappropriate method – the method used in the request is not allowed for the resource indicated (Only POST is used)
406 Not Acceptable	Incorrect Accept heading in the request (the server does not support it)
415 Unsupported Media Type	If an incorrect content type was set in the request
422 Unprocessable Entity	Validation error
429 Too Many Requests	Request rejected due to the fact that the maximum number of requests to access the resource has been exceeded
500 Internal Server Error	There was an unknown internal error of the API server
501 Not Implemented	XS2A interface doesn’t support given functionality requested by TPP
503 Service Unavailable	The API server is temporarily unavailable