Version	Change Description	Date
v.1.0	Initial version	30.04.26
v.1.1	Updated the link to the page with the detailed specification version descriptions	08.05.26

 

This document provides a general overview of the technical specifications of the dedicated APIs. Detailed documentation for the specification version used by the ASPSP is available at: https://docs.api.upc.ua/ua/api-servisi/regulyatorni-api

 

1. General Technical Specifications

1.1. Architecture and Standard

The dedicated APIs are designed as REST APIs and are based on the XS2A (Access to Account) specification implemented through the Open Banking Platform (OBP). XS2A is the standard interface that enables Third Party Providers (TPPs) to access payment accounts in accordance with PSD2 requirements.

 

1.2. Transport Protocol

Protocol: HTTPS (HTTP over TLS/SSL).

All requests are transmitted exclusively over secure HTTPS connections. The use of unencrypted HTTP is not supported.

 

1.3. Data Format

Request and response bodies use the JSON (JavaScript Object Notation) format. The Content-Type: application/json header is mandatory for all POST requests that contain a request body.

 

1.4. Versioning

The current version of both APIs is v2. The version is specified in the base URL path: /pis/v2/ and /ais/v2/.

 

1.5. Required HTTP Headers (Common to Both APIs)

• X-Request-Id – Unique request identifier (UUID format), for example: dc7b16a5-4ac8-4fdc-9c4e-9f9d0387dc07. Used for request identification and tracing.
• Content-Type – Request body content type: application/json (for POST requests).
• PSU-ID – Identifier of the Payment Service User (PSU) in the bank's system.
• PSU-IP-Address – IP address of the PSU's device.
• Consent-ID – Identifier of an authorized AIS consent (used for AIS requests after authorization).
• Client-Redirect-URI – URL to which the PSU is redirected after successful authorization (Redirect SCA).
• Client-Redirect-Nok-URI – URL to which the PSU is redirected if authorization fails (Redirect SCA).

 

2. PIS (Payment Initiation Service) Technical Specifications

 

2.1. Base URL

/pis/v2/

 

2.2. Endpoints

 

2.2.1. Payment Initiation

• Method and path: POST /pis/v2/payments/{payment-product}
• Path parameter: payment-product – Payment product type (currently supported: instant-credit-transfers).

 

Request body (JSON):

• paymentIdentification.endToEndId – End-to-end payment identifier (string).
• debtorAccount.iban – Payer's account IBAN.
• debtorAccount.currency – Payer's account currency (for example, "UAH").
• instructedAmount.currency – Transfer currency.
• instructedAmount.amount – Transfer amount (decimal string, for example "12.21").
• creditor.name – Beneficiary name.
• creditor.creditorId – Beneficiary identifier.
• creditor.creditorIdType – Beneficiary identifier type (for example, "PSPT").
• creditorAccount.iban – Beneficiary's account IBAN.
• creditorAccount.currency – Beneficiary's account currency.
• remittanceInformationUnstructured – Array of strings containing the payment purpose.

 

Response (JSON): paymentId (UUID), transactionStatus (RCVD), _links.startAuthorisation.href.

 

2.2.2. Payment Authorization (SCA)

• Method and path: POST /pis/v2/payments/{payment-product}/{payment-id}/authorisations
• Path parameters: payment-product, payment-id (obtained from the previous step).
• Headers: Client-Redirect-URI, Client-Redirect-Nok-URI (required for Redirect SCA).

 

Decoupled SCA response (JSON): scaStatus (received), authorisationId (UUID), psuMessage.

Redirect SCA response (JSON): scaStatus (received), authorisationId, _links.scaRedirect.href.

 

2.2.3. Payment Status

• Method and path: GET /pis/v2/payments/{payment-product}/{payment-id}/status
• Path parameters: payment-product, payment-id.

 

Response (JSON): transactionStatus – Transaction status (for example, ACCC – Accepted Settlement Completed).

 

2.3. Interaction Flow (PIS Flow)

1. The TPP initiates a payment (POST /payments/{payment-product}) and receives a paymentId.
2. The TPP starts the authorization process (POST /payments/{payment-product}/{payment-id}/authorisations) and receives an authorisationId together with either a psuMessage (Decoupled SCA) or an scaRedirect URL (Redirect SCA).
3. The PSU authorizes the payment using the bank's mobile application or the bank's web page, depending on the selected SCA method.
4. The TPP checks the payment status (GET /payments/{payment-product}/{payment-id}/status) and receives the current transactionStatus.
5. The TPP informs the PSU of the payment result.

 

2.4. PIS-Specific Error Codes

• 404 – PRODUCT_UNKNOWN – The specified payment product is not supported by the bank.
• 400 – PAYMENT_FAILED – The payment initiation request could not be processed.
• 403 – SERVICE_BLOCKED – The service is unavailable for the PSU due to a restriction imposed by the bank.

 

3. AIS (Account Information Service) Technical Specifications

 

3.1. Base URL

/ais/v2/

 

3.2. Endpoints

 

3.2.1. Creating an AIS Consent

Method and path: POST /ais/v2/consents/account-access

 

Request body (JSON):

• access.payments[].account.iban – IBAN of the account to which access is requested.
• access.payments[].rights – Array of access rights: accountDetails, balances, transactions. If balances or transactions is specified, the accountDetails permission is granted implicitly.
• consentType – Consent type: detailed.
• recurringIndicator – Indicates recurring (true) or one-time (false) access.
• validTo – Consent expiry date (format: YYYY-MM-DD).
• frequencyPerDay – Maximum number of requests per day without the PSU's presence (maximum: 4).

 

Response (JSON): consentId (UUID), consentStatus (received), _links.startAuthorisation.href.

 

3.2.2. Consent Authorization (SCA)

• Method and path: POST /ais/v2/consents/account-access/{consent-id}/authorisations
• Path parameter: consent-id.
• Headers: Client-Redirect-URI, Client-Redirect-Nok-URI.

 

Decoupled SCA response (JSON): scaStatus, authorisationId, psuMessage.

Redirect SCA response (JSON): scaStatus, authorisationId, _links.scaRedirect.href.

 

3.2.3. Consent Status

• Method and path: GET /ais/v2/consents/account-access/{consent-id}/status

 

Response (JSON): consentStatus – Consent status (received, valid, rejected, etc.).

 

3.2.4. Retrieving the List of Accounts

• Method and path: GET /ais/v2/accounts
• Query parameter: withBalance=true
• Header: Consent-ID – Identifier of the authorized AIS consent.

 

Response (JSON): An array of accounts objects containing: iban, currency, resourceId, name, balances[].balanceAmount, balances[].balanceType, balances[].referenceDate

 

3.2.5. Retrieving Transaction History

Method and path: GET /ais/v2/accounts/{account-id}/transactions

 

Query parameters:

• dateFrom – Start date of the requested period (transaction history older than 90 days requires a one-time AIS consent with recurringIndicator: false and the transactions access right).
• limit – Maximum number of transactions to return (pagination).
• offset – Number of records to skip (pagination).

Pagination: The TPP increases the offset value by the number of records already received. Pagination ends when the number of returned records is less than limit or when an empty list is returned. If pagination parameters are not provided, the number of returned transactions is determined by the bank.

 

3.3. Interaction Flow (AIS Flow)

1. The TPP creates an AIS consent (POST /consents/account-access) and receives a consentId.
2. The TPP starts the consent authorization process (POST /consents/account-access/{consent-id}/authorisations) and receives an authorisationId together with either a psuMessage (Decoupled SCA) or an scaRedirect URL (Redirect SCA).
3. The PSU authorizes the consent using the bank's mobile application or web page.
4. The TPP checks the consent status (GET /consents/account-access/{consent-id}/status) until it becomes valid.
5. The TPP retrieves account and transaction information by including the Consent-ID header in the request.

 

3.4. Limitations

• The maximum request frequency without the PSU's presence is 4 requests per day (frequencyPerDay ≤ 4).
• Transaction history available without additional SCA covers the previous 90 calendar days.

 

3.5. AIS-Specific Error Codes

• 401 – CONSENT_INVALID – The consent is invalid or does not grant the required access rights.
• 403 – CONSENT_UNKNOWN – The specified consent does not exist.
• 429 – ACCESS_EXCEEDED – The daily limit of four GET requests without the PSU's presence has been exceeded.
• 400 – FORMAT_ERROR (transaction pagination) – The dateFrom parameter specifies a date more than 90 days in the past for a recurring AIS consent.

 

4. Strong Customer Authentication (SCA)

Both APIs (PIS and AIS) support two SCA methods.

 

4.1. Decoupled SCA

The PSU receives a message or push notification from the bank and authorizes the operation directly in the bank's application without leaving the TPP interface. The TPP receives the psuMessage field containing the message intended for the PSU. The bank notifies the PSU that authorization is required.

 

4.2. Redirect SCA

The TPP redirects the PSU to the bank's SCA page (scaRedirect.href), where the PSU authenticates and authorizes the operation. After the authorization process is completed, the bank redirects the PSU to the Client-Redirect-URI (success) or the Client-Redirect-Nok-URI (failure).

 

5. Requirements for Third Party Providers (TPPs)

 

5.1. Registration and Certificates

To connect to the dedicated APIs, the TPP must:

• Register on the Developer Portal (portal.api.upc.ua).
• Obtain and configure digital certificates for mutual TLS (mTLS) authentication, as described in the Certificates section of the portal.
• Configure electronic request signatures, as described in the Electronic Signatures section.
• Register an application in the Applications section and subscribe to the required API service.

 

5.2. Technical Requirements

The TPP must have:

• an HTTP client supporting HTTPS/TLS and mutual TLS (mTLS);
• support for JSON serialization and deserialization;
• the ability to generate unique UUID values for the X-Request-Id header;
• polling logic to check payment and consent statuses;
• pagination support using the limit and offset parameters;
• publicly accessible Client-Redirect-URI and Client-Redirect-Nok-URI endpoints for Redirect SCA.

 

5.3. Environments

• Sandbox – Available for development and integration testing.
• Production – Used for live interaction with PSU payment accounts.