Post on 25-Apr-2023
Canopus Innovative Technologies epaysuite.com, canopus.ru
Canopus FS
Macrobank 5 OpenAPI Specification
Version 1 2019-09-12
CanopusInnovativeTechnologies2019
Canopus Innovative Technologies epaysuite.com, canopus.ru
ChronologyDate Versi
onDescription Author
03/09/2019 0.12 New Document (draft) Ilya Muraviev Yury Tsapkov Alexander Adrianov
12/09/2019 1.0. Minor edits Yury Tsapkov Alexander Adrianov
Canopus Innovative Technologies epaysuite.com, canopus.ru
Index 1. GLOSSARY ............................................................................................................................................. 4 2. GENERAL PROVISIONS .............................................................................................................................. 6 2.1. Stakeholders ................................................................................................................................ 6
2.2. Process interaction ...................................................................................................................... 7
2.3. Security ....................................................................................................................................... 7
2.4. Logging of operations .................................................................................................................. 8
2.5. Monitoring of OpenAPI interface ................................................................................................. 8
3. PROCESS OF COMMUNICATION BETWEEN PARTICIPANTS .................................................................................. 9 3.1. Registration TPP on ASPSP ........................................................................................................... 9
3.2. Providing to TPP access for PSU’s account .................................................................................... 9
3.3. Interaction with interface OpenAPI ............................................................................................ 10
4. BASIC SCOPE SERVICES ........................................................................................................................... 12 4.1. Services of Accounts category .................................................................................................... 12
4.2. Services of Payment category .................................................................................................... 19
4.3. Services of Confirmation category.............................................................................................. 25
5. EXTRA SCOPE SERVICES .......................................................................................................................... 27 6. RESPONSE STATUSES ............................................................................................................................. 28
Canopus Innovative Technologies epaysuite.com, canopus.ru
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.
Canopus Innovative Technologies epaysuite.com, canopus.ru
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.
Canopus Innovative Technologies epaysuite.com, canopus.ru
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.
Canopus Innovative Technologies epaysuite.com, canopus.ru
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:
1. TPP makes the request to ASPSP for registration and generation Certificate Signing Request to OpenAPI’s connection.
2. ASPSP validates the possibility of connection TPP to OpenAPI, then ASPSP registers this TPP in trusted TPP list and gives Certificate for connection.
3. TPP uses received Certificate to connect to ASPSP by OpenAPI interface. 4. PSU chooses the option of account authorization on ASPSP in User Interface TPP. After
that, PSU starts OATH2.0 authorization. 5. After success authorization, ASPSP gives JWT-token to TPP. This token defines specific
PSU and access right list for this PSU’s account. 6. 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.
Canopus Innovative Technologies epaysuite.com, canopus.ru
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
Canopus Innovative Technologies epaysuite.com, canopus.ru
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:
1. TPP goes to the section ‘Registration TPP’ at main web page ASPSP. 2. TPP fills the application with details about himself and required role (AISP, PISP, PIISP) 3. 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. 4. ASPSP handles application from TPP, validates presented information in different ways. 5. 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.
6. ASPSP inject to table information about new TPP. 7. TPP sets up received core certificate to the System and configure connection with ASPSP
using received TLS certificate. 8. 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:
1. TPP allows arbitrarily to PSU to choose at private cabinet TPP an option of joining his account at ASPSP.
2. 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.
3. 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.
4. During authorisation PSU sets a level of access to his account for TPP choosing a role for TPP (chapter 2.1. of this document)
Canopus Innovative Technologies epaysuite.com, canopus.ru
5. After successful authorisation and according to protocol OATH2.0 TPP gets JWT token with information about access rights and their expiration date.
6. 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.
Canopus Innovative Technologies epaysuite.com, canopus.ru
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.
Canopus Innovative Technologies epaysuite.com, canopus.ru
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 }, {
Canopus Innovative Technologies epaysuite.com, canopus.ru
... <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
Canopus Innovative Technologies epaysuite.com, canopus.ru
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
Canopus Innovative Technologies epaysuite.com, canopus.ru
#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
Canopus Innovative Technologies epaysuite.com, canopus.ru
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
Canopus Innovative Technologies epaysuite.com, canopus.ru
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
Canopus Innovative Technologies epaysuite.com, canopus.ru
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 }
Canopus Innovative Technologies epaysuite.com, canopus.ru
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
Canopus Innovative Technologies epaysuite.com, canopus.ru
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",
Canopus Innovative Technologies epaysuite.com, canopus.ru
"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",
Canopus Innovative Technologies epaysuite.com, canopus.ru
"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”
Canopus Innovative Technologies epaysuite.com, canopus.ru
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> }, ... ]
Canopus Innovative Technologies epaysuite.com, canopus.ru
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" } }
Canopus Innovative Technologies epaysuite.com, canopus.ru
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:
Canopus Innovative Technologies epaysuite.com, canopus.ru
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 }
Canopus Innovative Technologies epaysuite.com, canopus.ru
5. Extra Scope services
Additional services provided by ASPSP for Macrobank 5 are developing and will be presented at next versions of current document.
Canopus Innovative Technologies epaysuite.com, canopus.ru
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