NAV Navbar
Logo
shell

PSD2 Aggregation API

Purpose

No examples are available on this section. Navigate to any service to show its associated examples.

Younify PSD2 Aggregation API (Younify PSD2 API) enables you to aggregate your user’s financial accounts from different banks, access transactional data and initiate payments into your application using one single HTTP API.

This API presents the technical implementation details of the operations exposed by Younify to any Third Party Provider (TPP) in order to implement Younify PSD2 product.

Audience

This API is designed for the engineering teams of TPP and Younify.

Getting started

If you would like to test or use Younify PSD2 API, please contact us at sales@younify.io.

We will sign a Service Aggrement that will grant you access to your private sandbox that includes:

Definitions and abbreviations

Term / Abbreviation Description
Debtor a person, country, or organization that owes money
Creditor a person or company to whom money is owing
Debtor Agent a payment service provider (bank or other financial institution) providing and maintaining a payment account for a payer (debtor);
Creditor Agent a payment service provider (bank or other financial institution) providing and maintaining a financial account for a beneficiary (creditor);
Third Party Provider / TPP a company providing account information services or payment initiation services
Account information service / AIS an online service to provide consolidated information on one or more payment accounts held by the user with either another payment service provider or with more than one payment service provider;
Payment initiation service / PIS a service to initiate a payment order at the request of the user with respect to a payment account held at another payment service provider

Architecture

Security and authorization

The authorization of the call from the client to the server should be made using Two-way SSL authentication in case of Web Services integration.

For each call to the server, the client should send a client certificate issued by the server’s certificate authority. If the client certificate is validated by the server, the call will be authorized.

Encryption of the connection

In order to secure the communication between the client and server, all data in transit on the internet will be transmitted on an encrypted channel.

IP Filtering

Each client of the Web Service should have its IP added in the server whitelist firewall.

REST API Overview

General information

A client references a resource by making a HTTP call to an URI that follows REST standard. The client application can use HTTP verbs to manipulate the data represented by the URI.

Method Action
GET Retrieve a specific item of the resource.
POST Create or initiate a resource
PUT Update the resource with the body of the enclosed request
DELETE Remove the resource

The URI has the following pattern:

<domain-name>/api/{version}/{resource}

In the rest of the document, the URI to access a resource will be provided with the following format:

GET /api/{version}/resource/:parameter

API Responses

HTTP Codes

The HTTP status code is embedded inside the header of the response.

20X Status codes indicate the success of the call:

HTTP Status code Description
200 OK The request is OK (this is the standard response for successful HTTP requests)
201 CREATED The resource has been created.


All other codes indicate that something went wrong:

HTTP Status code Description
400 Bad Request The request cannot be fulfilled due to bad syntax
403 Unauthorized Missing authentication information
404 Not Found Method/Data not found
500 Internal Server Error A generic error message, given when no more specific message is suitable

Response Format

The stream format should be JSON encoded in UTF-8. If the call is successful, the WS will return an object containing the API response.

Younify PSD2 API uses HATEOAS (Hypertext As The Engine Of Application State) media format, providing a standard way for expressing the resources and relationships of an API as hypermedia links. Hypermedia links provide an easy way to navigate the API.

In case where the return is different from 20X, the body response can provide an object with the details of the error message.

{
   "code": 1001,
   "description": "Missing mandatory fields."
}

Technical Errors

HTTP Status code Code Description
500 -1 Exception processing request.
403 -2 Missing authentication information.
403 -3 Invalid access token.


Application Errors

HTTP Status code Code Description
500 1000 Failed to parse request parameters/body.
400 1001 Missing mandatory fields.
400 1002 Field <parameter> does not have a valid format or has an unknown value.
400 1003 Field<parameter> exceeds limit.
400 1004 Field <parameter> has a duplicated value.

Besides the generic errors listed above, which may apply to all operations, each operation has its own specific error codes. Those error cases are listed for each operation separately.

Data types

Data exchanged between the client and server should have the following value ranges based on the type:

Data type Value range
string Is detailed at the level of each field. Ex. string(20)
int Minimum value: -2^31 (-2.147.483.648)
Maximum value: 2^31-1 (2.147.483.648)
long Minimum value: -2^63 (-9.223.372.036.854.775.808)
Maximum value: 2^63-1 (9.223.372.036.854.775.807)
double Minimum value: 1.7e–308
Maximum value: 1.7e+308
boolean true or false

API Reference

Bank list

GET /api/{version}/banks?country={country}

Returns the list of banks that Younify PSD2 platform is connected with for a given country.

GET /api/{version}/banks?country=es

Request

Parameter Required Type Details
country no string(2) The country must be specified in ISO 3166-1 alpha-2 format.

Response

{
    "_links": {
        "self": {
            "href": "https://psd2.younify.ro/api/v1/banks?country=RO"
        }
    },
    "_embedded": {
        "banks": [{
                "id": "1034",
                "shortName": "ABC",
                "fullName": "ABC BANK",
                "logo": "https://psd2.younify.ro/ext/media/logos/abc.png",
                "url": "https://www.abc.ro",
                "_links": {
                    "details": {
                        "href": "https://psd2.younify.ro/api/v1/banks/1034",
                        "title": "Bank details",
                        "method": "GET"
                    }
                }
            },
            {
                "id": "1028",
                "shortName": "EFG",
                "fullName": "EFG BANK",
                "logo": "https://psd2.younify.ro/ext/media/logos/efg.png",
                "url": "https://www.efg.ro",
                "_links": {
                    "details": {
                        "href": "https://psd2.younify.ro/api/v1/banks/1028",
                        "title": "Bank details",
                        "method": "GET"
                    }
                }
            }
        ]
    }
}

Response

Parameter Required Type Details
banks yes array of BankSummary List of banks based on request query.

Details on “BankSummary” object:

Parameter Required Type Details
id yes string(100) Represents Younify internal identifier of the bank. This id will be used any time you refering to this specific bank entity.
Please note that a bank in different country has a different identifier.
shortName yes string(255) Abbreviation of the name of the bank. In case the bank doesn’t have an abbreviation, the full name will be returned in this field.
fullName yes string(255) Full name of the bank.
logo yes string(255) Link to the logo of the bank.
url yes string(255) Link to the bank’s website.

Bank details

GET /api/{version}/banks/{bankId}

Returns the details for a bank on a given identifier.

GET /api/{version}/banks/1034

Request

Parameter Required Type Details
bankId yes string(100) Bank identifier.

Response

{
    "id": "1034",
    "shortName": "ABC",
    "fullName": "ABC BANK",
    "logo": "https://psd2.younify.ro/ext/media/logos/abc.png",
    "url": "https://www.abc.ro",
    "country": "RO",
    "_links": {
        "self": {
            "href": "https://psd2.younify.ro/api/v1/banks/1034"
        },
        "all": {
            "href": "https://psd2.younify.ro/api/v1/banks?country=RO",
            "title": "View all banks",
            "method": "GET"
        }
    }
}

Response

Parameter Required Type Details
id yes string(100) Represents Younify internal identifier of the bank. This id will be used any time you refering to this specific bank entity.
Please note that a bank in different country has a different identifier.
shortName yes string(255) Abbreviation of the name of the bank. In case the bank doesn’t have an abbreviation, the full name will be returned in this field.
fullName yes string(255) Full name of the bank.
logo yes string(255) Link to the logo of the bank.
url yes string(255) Link to the bank’s website.
country yes string(2) Country code of the bank specified in ISO 3166-1 alpha-2 format.

Specific errors

HTTP Status Code Code Description
404 10001 Bank not found for the provided bankId: {bankId}.

Add bank

User adding a new bank on TPP platform must enter his bank credentials on the bank platform. Once his credentials are validated by the bank platform he will be propmted to allow the TPP platform to access his data. Once this step is done, the TPP platform will be able to retrieve his data from the bank.

Younify PSD2 platform aggregates the PSD2 APIs exposed by different banks and provides one single interface to access all banks platforms. Each bank will provide their own authentication and authorization mechanism, which can be OAuth or OAuth 2.0. This means that each bank will have it’s own: URLs, authorization codes, specific details, which will be handled by Younify PSD2 platform.

Adding a new bank by a user of the TPP platform will be handled by Younify PSD2 platform using a flavor of OAuth 2.0 Authorization framework.

End user perspective

From the end user’s perspective the process works as follows:

After the steps above, the user can retrieve his data from the added bank.

TPP platform perspective

From the TPP platform’s perspective the process works as follows:

The bearer token will be used by the TPP platform to authenticate the user on Younify PSD2 platform when making calls to the API.

The steps above are detailed in the following sections:

User redirect

GET /auth/authorize?redirect_uri=<your_callback_uri>&client_id=<your_client_id>&state=UseTheForce&response_type=code&user_id=72513&bank_id=1023

In order to retrieve the bearer token to access user’s bank account, the user must select a bank and will be redirected to the request authorization endpoint.

GET /auth/authorize?redirect_uri=<callback_uri>&client_id=<client_id>&state=<state>&response_type=code&user_id=<user_id>&bank_id=<bank_id>

The values of the parameters are detailed below:

Parameter Details
redirect_uri the URL on TPP platform where the user will be redirected to after the authorization has been completed successfully or failed
client_id represents the client_id that has been assigned to the TPP platform
state a random state value that will be returned to TPP platform. This parameter is used to prevent cross-site request forgery (CSRF)
user_id a unique identifier of the end user of TPP platform. This will help associating the added banks of the user.
bank_id the id of the bank to which the end user wants to connect with. The bank_id will be retrieved from the bank list method.

Extract Authorization Code

Once the user authenticates and gives access to Younify PSD2 on the bank platform, it will be redirected to the redirect_uri that was previously provided by the TPP platform, along with the following parameters:

Parameter Details
state the random state value that was sent by TPP platform in the initial request. The state parameter must be checked to ensure it contains the same value with the one sent when making the initial request. If the value doesn’t match, the process should be interrupted.
code this parameter represents the Authorization Code and will be used to retrieve the OAuth token.

In case the authorization failed, TPP platform will receive an error message on the redirect_uri. Details on the error message is described in OAuth 2.0 section 4.1.2.1.

Retrieve the OAuth token

POST /auth/token?grant_type=authorization_code&code=<code>&client_id=<client_id>&redirect_uri=<redirect_uri>

Once the code is extracted from the response, the TPP platform can request the OAuth Access Token from Younify PSD2 platform.

The OAuth Access Token can be retrieved by accesing the access token endpoint as follows (using application/x-www-form-urlencoded encoding):

POST /auth/token?grant_type=authorization_code&code=<code>&client_id=<client_id>&redirect_uri=<redirect_uri>

the values of the parameters are detailed below:

Parameter Details
grant_type “authorization_code”
code the code received in the hTPP redirect after the authentication
client_id represents the client_id that has been assigned to the TPP platform
redirect_uri the same redirect_uri used in authorization request

The request to retrieve the OAuth Access Token is authenticated using the standard means of authentication used by the Younify PSD2 platform (Two-way SSL authentication or signature based authentication).

Response

{
    "access_token": "ESFgeQtnWn06nv9H3WPjiwHbWgIcoafJ",
    "token_type": "Bearer",
    "expires_in": 3600,
    "refresh_token": "a04xi9952L6wIq4ZRYP4okPUV70X923W"
}

The response is detailed below:

Parameter Details
access_token the access token to be used by the TPP platform to access the user’s data
token_type Bearer token
expires_in the timeline in seconds of the access token.
refresh_token when the access token is expired, the refresh token will be used to retrieve the new access_token

Access and Refresh token

Authorization: Bearer ESFgeQtnWn06nv9H3WPjiwHbWgIcoafJ

The access token will be included in the hTPP Authorization header of each request to Younify PSD2 platform as type Bearer. This will help authorize the user of TPP platform on Younify PSD2 platform.

The authentication credentials (Two-way SSL or signature based authentication) from TPP platform to Younify PSD2 platform will still have to be present on each request.

Once the access_token has expired, the refresh_token should be used in order to optain the new valid access_token. In order to refresh the access_token the same endpoint should be used as for retrieving the initial access token:

POST /auth/token?grant_type=authorization_code&refresh_token=a04xi9952L6wIq4ZRYP4okPUV70X923W

POST /auth/token?grant_type=authorization_code&refresh_token=<refresh_token>

the values of the parameters are detailed below:

Parameter Details
grant_type “refresh_token”
refresh_token The refresh token received with the current expired access_token

The response of the refresh_token request is the same as for retrieving the initial access token.

Access token revocation

POST /auth/revoce?token=a04xi9952L6wIq4ZRYP4okPUV70X923W

If the access_token is no longer needed, it is recommended to be revoked. The revocation of a token can be done by calling the revocation endpoint. The access_token and refresh_token should be revoked separately.

POST /auth/revoce?token=<token>

Remove bank

DELETE /api/{version}/banks/{bankId}/accounts

Removes a bank for the authorized user.

Request

DELETE /api/{version}/banks/1023/accounts

Accept        : application/json
Authorization : Bearer ESFgeQtnWn06nv9H3WPjiwHbWgIcoafJ

Headers

Parameter Required Type Details
Accept yes string(16) Specifies acceptable content-types. The only accepted value is application/json.
Authorization yes string(255) Access token received for the user after successfully authenticated with a bank.

Parameters (URL)

Parameter Required Type Details
bankId yes string(100) Bank identifier.

Response: HTTP Status Code 200

Response

No response parameters with HTTP 200 status code.

Specific errors

HTTP Status Code Code Description
404 10001 Bank not found for the provided bankId: {bankId}.
404 10002 Bank: {bankId} not found for authorized user.

Basic user info

GET /api/{version}/banks/{bankId}/users

Returns basic information of the user in the selected bank.

Request

GET /api/{version}/banks/1034/users

Accept        : application/json
Authorization : Bearer ESFgeQtnWn06nv9H3WPjiwHbWgIcoafJ

Headers

Parameter Required Type Details
Accept yes string(16) Specifies acceptable content-types. The only accepted value is application/json.
Authorization yes string(255) Access token received for the user after successfully authenticated with a bank.

Parameters (URL)

Parameter Required Type Details
bankId yes string(100) Bank identifier.

Response

{
    "id": "801",
    "firstName": "POPESCU",
    "lastName": "Adelina",
    "gender": "FEMALE",
    "birthDate": "1994-10-23",
    "identityDocumentType": "NATIONALID",
    "identityDocumentId": "ZB 801817",  
    "address": "Vacarescu elena 22, Bl U8, Sc 4, Et 9, Ap 100",
    "postalCode": "511927",
    "city": "Brasov"
    "country": "RO",
    "email": "adelina.popescu@email.com",
    "phone": "0700000000",
    "_links": {
        "self": {
            "href": "https://psd2.younify.ro/api/v1/banks/1034/users"
        }
    }
}

Response

Parameter Required Type Details
id yes string(100) Represents the user identifier in the bank.
firstName yes string(255) Represents the first name.
lastName yes string(255) Represents the last name.
gender no string(10) Represents the user gender. The possible values are:
  • MALE
  • FEMALE
birthDate no string(10) The date is represented in ISO 8601 format ( YYYY-MM-DD )
identityDocumentType yes string(20) Identity document type. The possible values are:
  • NATIONALID: national identity number
  • FOREIGNERID: foreigner identity number
  • PASSPORT: passport number
identityDocumentId yes string(50) Identity document number.
address no string(255) Information that locates and identifies a specific address, as defined by postal services, presented in free format text.
postalCode no string(16) Identifier consisting of a group of letters and/or numbers that is added to a postal address to assist the sorting of mail.
city no string(35) City of client’s address.
country no string(2) Country should be represented in ISO 3166-1 alpha-2 format (ex. RO)
email no string(100) Email address.
phone no string(20) Phone number of the client.

Specific errors

HTTP Status Code Code Description
404 10001 Bank not found for the provided bankId: {bankId}.
404 10002 Bank: {bankId} not found for authorized user.

List bank accounts

GET /api/{version}/accounts

Returns the list of all enrolled bank accounts for the authorized user.

Request

GET /api/{version}/accounts

Accept        : application/json
Authorization : Bearer ESFgeQtnWn06nv9H3WPjiwHbWgIcoafJ

Headers

Parameter Required Type Details
Accept yes string(16) Specifies acceptable content-types. The only accepted value is application/json
Authorization yes string(255) Access token received for the user after successfully authenticated with a bank.

Parameters (URL & body)

No request parameters.

Response

{
    "_links": {
        "self": {
            "href": "https://psd2.younify.ro/api/v1/accounts"
        }
    },
    "_embedded": {
        "accounts": [{
                "id": "3427277",
                "bankId": "1034",
                "name": "",
                "type": "CURRENT",
                "iban": "RO30MPRL9466170979781821",
                "currency": "RON",
                "creationDate": "2017-10-12T12:29:02+03:00",
                "_links": {
                    "details": {
                        "href": "https://psd2.younify.ro/api/v1/accounts/3427277",
                        "title": "Account info",
                        "method": "GET"
                    }
                }
            },
            {
                "id": "8652101",
                "bankId": "1034",
                "name": "",
                "type": "SAVINGS",
                "iban": "RO91YEAX4769466049925482",
                "currency": "RON",
                "creationDate": "2017-10-12T12:29:02+03:00",
                "_links": {
                    "details": {
                        "href": "https://psd2.younify.ro/api/v1/accounts/8652101",
                        "title": "Account info",
                        "method": "GET"
                    }
                }
            }
        ]
    }
}

Response

Parameter Required Type Details
accounts yes array of AccountSummary List of user’s accounts.

Details on AccountSummary object:

Parameter Required Type Details
id yes string(36) Account identifier.
bankId yes string(100) Represents the Younify internal identifier of the bank.
name no string(255) Alias name assigned to the account.
type yes string(255) Account type. The possible values are:
  • CURRENT: Current account.
  • SAVINGS: Saving account.
  • OTHER: Any other type of account.
iban yes string(34) IBAN. The format of the IBAN is transmitted using ISO 13616-1:2007.
currency yes string(3) Represents the currency and it should be transmitted using ISO4217:2008 currency code format.
creationDate no string(25) Creation date of the account. The date is represented in ISO 8601 format (YYYY-MM-DDThh:mm:ssTZ)

Bank account details

GET /api/{version}/accounts/{accountId}

Returns the details of a bank account of the authorized user.

Request

GET /api/{version}/accounts/3427277

Accept        : application/json
Authorization : Bearer ESFgeQtnWn06nv9H3WPjiwHbWgIcoafJ

Headers

Parameter Required Type Details
Accept yes string(16) Specifies acceptable content-types. The only accepted value is application/json.
Authorization yes string(255) Access token received for the user after successfully authenticated with a bank.

Parameters (URL & body)

Parameter Required Type Details
accountId yes string(36) Represents the account identifier.

Response

{
    "id": "3427277",
    "bankId": "3",
    "name": "",
    "type": "CURRENT",
    "iban": "RO30MPRL9466170979781821",
    "balance": "1294.30",
    "currency": "RON",
    "creationDate": "2017-10-12T12:29:02+03:00",    
    "_links": {
        "self": {
            "href": "https://psd2.younify.ro/api/v1/accounts/3427277"
        },
        "all": {
            "href": "https://psd2.younify.ro/api/v1/accounts",
            "title": "View accounts",
            "method": "GET"
        }
    }
}

Response

Parameter Required Type Details
id yes string(36) Account identifier.
bankId yes string(100) Represents the Younify internal identifier of the bank.
name no string(255) Alias name assigned to the account.
type yes string(255) Account type. The possible values are:
  • CURRENT: Current account.
  • SAVINGS: Saving account.
  • OTHER: Any other type of account.
iban yes string(34) IBAN. The format of the IBAN is transmitted using ISO 13616-1:2007.
balance yes string(18) Account balance.
Format:
  • minInclusive: 0
  • totalDigits: 18
  • factionDigits: 2
The decimal separator is a dot.
currency yes string(3) Represents the currency and it should be transmitted using ISO4217:2008 currency code format.
creationDate no string(25) Creation date of the account. The date is represented in ISO 8601 format (YYYY-MM-DDThh:mm:ssTZ)

Specific errors

HTTP Status Code Code Description
404 10003 Account not found for the provided accountId: {accountId}.

Account transactions

GET /api/{version}/accounts/{accountId}/transactions?pageNumber={pageNumber}&pageSize={pageSize}&amountFrom={amountFrom}&amountTo={amountTo}&dateFrom={dateFfrom}&dateTo={dateTo}&operationType={operationType}

Returns the transaction list associated to a bank account of the authorized user.

Request

GET /api/{version}/accounts/3015154/transactions?pageNumber=0&pageSize=10&amountFrom=0&amountTo=200&dateFrom=2017-08-08&dateTo=2017-10-10&operationType=BOTH

Accept        : application/json
Authorization : Bearer ESFgeQtnWn06nv9H3WPjiwHbWgIcoafJ

Headers

Parameter Required Type Details
Accept yes string(16) Specifies acceptable content-types. The only accepted value is application/json.
Authorization yes string(255) Access token received for the user after successfully authenticated with a bank.

Parameters (URL)

Parameter Required Type Details
accountId yes string(36) Represents the account identifier.
pageNumber no int Represents page number.
Default value is 0
pageSize no int Represent number of transactions to be returned on a page.
Default value is 10
amountFrom no string(18) Represent the minimum amount to search for.
Default value is -Double.MAX_VALUE
Format:
  • minInclusive: 0
  • totalDigits: 18
  • factionDigits: 2
The decimal separator is a dot.
amountTo no string(18) Represent the maximum amount to search for.
Default value is: Double.MAX_VALUE
Format:
  • minInclusive: 0
  • totalDigits: 18
  • factionDigits: 2
The decimal separator is a dot.
dateFrom no string(10) Represent the minimum date to filter.
The date should be represented in ISO 8601 format ( YYYY-MM-DD )
Default value is creationDate of the account.
dateTo no string(10) Represent the maximum date to filter.
The date should be represented in ISO 8601 format ( YYYY-MM-DD )
Default value is current date.
operationType no string(10) Represent the type of operation to filter.
Available values are:
  • IN
  • OUT
  • BOTH (default)

Response

{
    "currentPage": 0,
    "totalPages": 1,
    "transactions": [{
            "id": "3667",
            "accountId": "3015154",
            "transactionType": "DEBIT",
            "description": "Utilizare POS alte BC retr. num.",
            "amount": "1724.00",
            "currency": "RON",
            "creationDate": "2017-08-12T00:00:00+03:00",
            "processedDate": "2017-08-12T00:00:00+03:00"
        },
        {
            "id": "3668",
            "accountId": "3015154",
            "transactionType": "DEBIT",
            "description": "Retragere numerar",
            "amount": "365.00",
            "currency": "RON",
            "creationDate": "2017-07-21T00:00:00+03:00",
            "processedDate": "2017-07-21T00:00:00+03:00"
        }
    ],
    "_links": {
        "self": {
            "href": "https://psd2.younify.ro/api/v1/accounts/3015154/transactions?pageNumber=0&pageSize=10&amountFrom=0&amountTo=200&dateFrom=2017-08-08&dateTo=2017-10-10&operationType=BOTH"
        },
        "next": {
            "href": "https://psd2.younify.ro/api/v1/accounts/3015154/transactions?pageNumber=0&pageSize=10&amountFrom=0&amountTo=200&dateFrom=2017-08-08&dateTo=2017-10-10&operationType=BOTH",
            "title": "View transactions",
            "method": "GET"
        }
    }
}

Response

Parameter Required Type Details
currentPage yes int Current page of the search result.
totalPages yes int Total number of pages.
transactions yes array of Transaction List of Transaction objects.

Details on “Transaction” object:

Parameter Required Type Details
id yes string(255) Represents transaction identifier.
accountId yes string(36) Represents the account identifier.
transactionType yes string(10) Represents the type of transaction. The possible values are:
  • CREDIT
  • DEBIT
  • FEE
description yes string(2000) Represents the description associated with the transaction.
amount yes string(18) Represents the amount involved in the transaction.
Format:
  • minInclusive: 0
  • totalDigits: 18
  • factionDigits: 2
The decimal separator is a dot.
currency yes string(3) Represents the currency and it should be transmitted using ISO4217:2008 currency code format.
creationDate yes string(25) Represents the creation date of the transation. The date is represented in ISO 8601 format (YYYY-MM-DDThh:mm:ssTZ)
processedDate yes string(25) Represents the processed date of the transation(date the amount was credited/debited). The date is represented in ISO 8601 format (YYYY-MM-DDThh:mm:ssTZ)

Specific errors

HTTP Status Code Code Description
404 10003 Account not found for the provided accountId: {accountId}.

Customer credit transfer initiation

POST /api/{version}/accounts/transactions

Initiate a request for funds movement from a debtor account to a creditor.

The payment request is done using an ISO20022 “pain.001.001.08” message-based structure (CustomerCreditTransferInitiationV08). The structure applies only to one payment instruction.

POST /api/{version}/accounts/transactions

Accept        : application/json
Authorization : Bearer ESFgeQtnWn06nv9H3WPjiwHbWgIcoafJ

Body

{
    "GrpHdr": {
        "MsgId": "ac7ee88f-2825-401a-9a3f-74749991cab",
        "CreDtTm": "2017-07-21T00:00:00+03:00",
        "NbOfTxs": 1,
        "InitgPty": {
            "Id": "9H3WPjiwHbWgIcoafJ"
        }
    },
    "PmtInf": {
        "PmtInfId": "7251300056823478347",
        "PmtMtd": "TRF",
        "ReqdExctnDt": {
            "Dt": "2017-07-21"
        },
        "Dbtr": {
            "Id": "-"
        },
        "DbtrAcct": {
            "Id": "3427277"
        },
        "DbtrAgt": {
            "FinInstnId": {
                "BICFI": "ABCEROBU",
                "Nm": "ABC Bank",
                "PstlAdr": {
                    "TwnNm": "Bucuresti",
                    "Ctry": "RO"
                }
            }
        },
        "ChrgBr": "SHAR",
        "CdtTrfTxInf": {
            "PmtId": {
                "EndToEndId": "7251300056823478347"
            },
            "Amount": {
                "InstdAmt": "780.23",
                "Ccy": "RON"
            },
            "CdtrAgt": {
                "FinInstnId": {
                    "BICFI": "YEAXROBU",
                    "Nm": "EFG Bank",
                    "PstlAdr": {
                        "TwnNm": "Bucharest",
                        "Ctry": "RO"
                    }
                }
            },
            "Cdtr": {
                "Nm": "Popescu Valentin",
                "PstlAdr": {
                    "AdrLine": "Vacarescu Elena 22, Bl U8, Sc 4, Et 9, Ap 100",
                    "AdrTp": "ADDR",
                    "PstCd": "511927",
                    "TwnNm": "Brasov",
                    "CtrySubDvsn": "BV",
                    "Ctry": "RO"
                }
            },
            "CdtrAcct": {
                "Id": {
                    "IBAN": "RO91YEAX4769466049925482"
                }
            },
            "Purp": {
                "Prtry": "Transfer"
            }
        }
    }
}

Headers

Parameter Required Type Details
Accept yes string(16) Specifies acceptable content-types. The only accepted value is application/json.
Authorization yes string(255) Access token received for the user after successfully authenticated with a bank.

Request (body)

Parameter Required Type Details
GrpHdr yes GroupHeader object GroupHeader
Header of the payment request message.
Pmtlnf yes PaymentInformation object PaymentInformation
Set of characteristics that applies to the debit side of the payment transactions included in the credit transfer initiation.

Details on “GroupHeader (GrpHdr)” object:

Parameter Required Type Details
MsgId yes string(35) MessageIdentification
Message identifier that should be unique for every request.
Due to ISO20022, this field is present but has no API usage.
CreDtTm yes string(25) CreationDateTime
Represents the creation date of the transation. The date is represented in ISO 8601 format (YYYY-MM-DDThh:mm:ssTZ)
NbOfTxs yes int NumberOfTransactions
Number of individual transactions contained in the message.
Should have the value 1.
InitgPty.Id yes string(35) InitiatingParty.Identification
Party that initiates the payment.
The value should be the client_id that has been assigned to the TPP platform.

Details on “PaymentInformation (Pmtlnf)” object:

Parameter Required Type Details
PmtInfId yes string(35) PaymentInformationIdentification
Unique identification, as assigned by a sending party, to unambiguously identify the payment information group within the message.
The value of this field should have it’s most significant chars the client_id of the TPP platform.
PmtMtd yes string(3) PaymentMethod
Specifies the means of payment that will be used to move the amount of money.
The possible values are:
  • TRF: (CreditTransfer) Transfer of an amount of money in the books of the account servicer.
ReqdExctnDt.Dt yes string(10) RequestedExecutionDate
Date at which the initiating party requests the clearing agent to process the payment. The date is represented in ISO 8601 format (YYYY-MM-DD).
Default value is current date.
Dbtr.Id yes string(36) Debtor.Identification
Debtor identifier for the account between the account owner and the account servicer.
Due to ISO20022, this field is present but has no API usage as the identifier of the customer is extracted based on Bearer token.
DbtrAcct.Id yes string(36) DebtorAccount.Identification
Identification of the account of the debtor to which a debit entry will be made as a result of the transaction.
DbtrAgt. FinInstnId.BICFI yes string(11) DebtorAgent. FinancialInstitutionIdentification. BICFI
Code allocated to the financial institution of the debtor by the ISO 9362: Business identifier code (BIC).
Due to ISO20022, this field is present but has no API usage as the identifier of the financial institution is extracted based on the DbtrAcct.Id field.
ChrgBr yes string(4) ChargeBearer
Specifies which party/parties will bear the charges associated with the processing of the payment transaction.
The possible values are:
  • DEBT: (BorneByDebtor) All transaction charges are to be borne by the debtor.
  • CRED: (BorneByCreditor) All transaction charges are to be borne by the creditor.
  • SHAR: (Shared) In a credit transfer context, means that transaction charges on the sender side are to be borne by the debtor, transaction charges on the receiver side are to be borne by the creditor.

For domestic transactions the value of ChrgBr should be set to SHAR.
CdtTrfTxInf yes CreditTransfer Transaction Information object CreditTransferTransactionInformation
Provides information on the transaction included in the message.

Details on “CreditTransferTransactionInformation (CdtTrfTxInf)” object:

Parameter Required Type Details
Pmtld.EndToEndId yes string(35) PaymentIdentification. EndToEndIdentification
Unique identification assigtned by the initiating party to identify the transaction. This identification is passed on, unchanged, throughout the entire end-to-end chain.

The value of this field should be the same as for PaymentInformationIdentification (PmtInfId).
Amount.InstdAmt yes string(18) Amount.InstructedAmount
Amount of money to be moved between the debtor and creditor, before deduction of charges, expressed in the currency of the debtor account as ordered by the initiating party.
This amount will be transported unchanged through the transaction chain.

Format:
  • minInclusive: 0
  • totalDigits: 18
  • factionDigits: 2
The decimal separator is a dot.
Amount.Ccy yes string(3) Amount.InstructedAmount. Currency
Format of the currency should be transmitted using ISO 4217:2008 currency code format.
CdtrAgt. FinInstnId.BICFI no string(11) CreditorAgent. FinancialInstitutionIdentification. BICFI
Code allocated to the financial institution of the creditor by the ISO 9362: Business identifier code (BIC).
This value is mandatory for cross-border transfers.
CdtrAgt. FinInstnId.Nm no string(140) CreditorAgent. FinancialInstitutionIdentification. Name
Name by which an agent is known and which is usually used to identify that agent.
This value is mandatory for cross-border transfers.
CdtrAgt.FinInstnId. PstlAdr.TwnNm no string(35) CreditorAgent. FinancialInstitutionIdentification. PostalAddress.TownName
Name of a built-up area, with defined boundaries, and a local government.
This value is mandatory for cross-border transfers.
CdtrAgt.FinInstnId. PstlAdr.Ctry no string(2) CreditorAgent. FinancialInstitutionIdentification. PostalAddress.Country
The country must be specified in ISO 3166-1 alpha-2 format.
This value is mandatory for cross-border transfers.
Cdtr.Nm yes string(140) Creditor.Name
Name by which a party is known and which is usually used to identify that party.
Cdtr.PstlAdr no PostalAddress object Creditor.PostalAddress
Information that locates and identifies a specific address, as defined by postal services.
This value is mandatory for cross-border transfers.
CdtrAcct.Id.IBAN yes string(34) CreditorAccount. Identification.IBAN
IBAN of the creditor account to which the money will be moved. The format of the IBAN is transmitted using ISO 13616-1:2007.
Purp.Prtry no string(35) Purpose.Proprietary
Underlying reason for the payment transaction.

Details on “PostalAddress (PstlAdr)” object:

Parameter Required Type Details
AdrTp no string(4) AddressType
Identifies the nature of the postal address.
The possible values are:
  • ADDR: (Postal) Address is the complete postal address.
  • PBOX: (POBox) Address is a postal office (PO) box.
  • HOME: (Residential) Address is the home address.
  • BIZZ: (Business) Address is the business address.
  • MLTO: (MailTo) Address is the address to which mail is sent.
  • DLVY: (DeliveryTo) Address is the address to which delivery is to take place.
Dept no string(70) Department
Identification of a division of a large organisation or building.
SubDept no string(70) SubDepartment
Identification of a sub-division of a large organisation or building.
StrtNm no string(70) StreetName
Name of a street or thoroughfare.
BldgNb no string(16) BuildingNumber
Number that identifies the position of a building on a street.
PstCd no string(16) PostCode
Identifier consisting of a group of letters and/or numbers that is added to a postal address to assist the sorting of mail.
TwnNm no string(35) TownName
Name of a built-up area, with defined boundaries, and a local government.
CtrySubDvsn no string(35) CountrySubDivision
Identifies a subdivision of a country such as state, region, county.
Ctry no string(2) Country
Country must be specified in ISO 3166-1 alpha-2 format.
AdrLine no string(70) AddressLine
Information that locates and identifies a specific address, as defined by postal services, presented in free format text.

Response: HTTP Status Code 200

Response

No response parameters with HTTP 200 status code.

Specific errors

HTTP Status Code Code Description
400 10005 InitiatingParty.Identification (InitgPty.id): {InitgPty.id} does not match with authorization credentials.
400 10006 RequestedExecutionDate (ReqdExctnDt): {ReqdExctnDt} should not be in the past.
404 10007 DebtorAccount.Identification (DbtrAcct.Id): {DbtrAcct.Id} not found.
400 10008 Insufficient funds in debtor account.
400 10009 Exceeded limit on debtor account.
400 10010 Debtor account is blocked.
403 10011 Access denied to Debtor account.
400 10012 Debtor account closed.
400 10013 Payment type not allowed.
400 10014 CreditorAccount. Identification.IBAN (CdtrAcct.Id.IBAN): {CdtrAcct.Id.IBAN} does not belong to Creditor Agent (CdtrAgt. FinInstnId.BICFI).

Creditor agent details

GET /api/{version}/ibans/{iban}/banks

Returns basic information of a creditor agent based on the IBAN of a creditor.

Request

GET /api/{version}/ibans/RO30MPRL9466170979781821/banks

Accept        : application/json
Authorization : Bearer ESFgeQtnWn06nv9H3WPjiwHbWgIcoafJ

Headers

Parameter Required Type Details
Accept yes string(16) Specifies acceptable content-types. The only accepted value is application/json.
Authorization yes string(255) Access token received for the user after successfully authenticated with a bank.

Parameters (URL)

Parameter Required Type Details
iban yes string(34) IBAN. The format of the IBAN is transmitted using ISO 13616-1:2007.

Response

{
    "CdtrAgt": {
        "FinInstnId": {
            "BICFI": "MPRLROBU",
            "Nm": "ABC BANK",
            "PstlAdr": {
                "TwnNm": "BUCHAREST",
                "Ctry": "RO"
            }
        }

    },
    "_links": {
        "self": {
            "href": "https://psd2.younify.ro/api/v1/banks?iban=RO30MPRL9466170979781821"
        }
    }
}

Response

Parameter Required Type Details
CdtrAgt. FinInstnId.BICFI no string(11) CreditorAgent. FinancialInstitutionIdentification.BICFI
Code allocated to the financial institution of the creditor agent by the ISO 9362: Business identifier code (BIC).
CdtrAgt. FinInstnId.Nm no string(140) CreditorAgent. FinancialInstitutionIdentification.Name
Name by which an agent is known and which is usually used to identify that agent.
CdtrAgt.FinInstnId. PstlAdr.TwnNm no string(35) CreditorAgent. FinancialInstitutionIdentification. PostalAddress.TownName
Name of a built-up area, with defined boundaries, and a local government.
CdtrAgt.FinInstnId. PstlAdr.Ctry no string(2) CreditorAgent. FinancialInstitutionIdentification. PostalAddress.Country
The country must be specified in ISO 3166-1 alpha-2 format.

Specific errors

HTTP Status Code Code Description
404 10004 Bank not found for the provided IBAN: {IBAN}.

Fee for customer credit transfer

POST /api/{version}/accounts/transactions/fees

Returns the fee associated for funds movement from a debtor account to a creditor.

The payment fee request is done using an ISO20022 “pain.001.001.08” message-based structure (CustomerCreditTransferInitiationV08). The structure applies only to one payment instruction.

POST /api/{version}/accounts/transactions/fees

Accept        : application/json
Authorization : Bearer ESFgeQtnWn06nv9H3WPjiwHbWgIcoafJ

Headers

Parameter Required Type Details
Accept yes string(16) Specifies acceptable content-types. The only accepted value is application/json.
Authorization yes string(255) Access token received for the user after successfully authenticated with a bank.

Request (URL)

Request parameters are the same as per Customer credit transfer initiation method.

Response

{
    "Amount": {
        "InstdAmt": "3.5",
        "Ccy": "RON"
    },
    "_links": {
        "self": {
            "href": "https://psd2.younify.ro/api/v1/accounts/transactions/fees"
        }
    }
}

Response

Parameter Required Type Details
Amount.InstdAmt yes string(18) Amount.InstructedAmount
Charges applied to the debtor expressed in the currency of the debtor account as ordered by the initiating party.
Format:
  • minInclusive: 0
  • totalDigits: 18
  • factionDigits: 2
The decimal separator is a dot.
Amount.Ccy yes string(3) Amount.InstructedAmount. Currency
Format of the currency should be transmitted using ISO 4217:2008 currency code format.

Specific errors

HTTP Status Code Code Description
400 10005 InitiatingParty.Identification (InitgPty.id): {InitgPty.id} does not match with authorization credentials.
400 10006 RequestedExecutionDate (ReqdExctnDt): {ReqdExctnDt} should not be in the past.
404 10007 DebtorAccount.Identification (DbtrAcct.Id): {DbtrAcct.Id} not found.
400 10013 Payment type not allowed.
400 10014 CreditorAccount. Identification.IBAN (CdtrAcct.Id.IBAN): {CdtrAcct.Id.IBAN} does not belong to Creditor Agent (CdtrAgt. FinInstnId.BICFI).