|
THE STATE BANK OF
VIETNAM
--------
|
THE SOCIALIST
REPUBLIC OF VIETNAM
Independence - Freedom - Happiness
---------------
|
|
No. 64/2024/TT-NHNN
|
Hanoi, December 31,
2024
|
CIRCULAR
ON
IMPLEMENTATION OF OPEN APPLICATION PROGRAMMING INTERFACE IN BANKING SECTOR
Pursuant to the Law on State Bank of Vietnam
dated June 16, 2010;
Pursuant to the Law on Credit Institutions
dated January 18, 2024;
Pursuant to the Law on Electronic Transactions
dated June 22, 2023;
Pursuant to the Law on Cybersecurity dated
November 19, 2015;
Pursuant to Decree No. 52/2024/ND-CP dated May
15, 2024 of the Government on cashless payments;
Pursuant to Decree No. 13/2023/ND-CP dated
April 17, 2023 of the Government on protection of personal data;
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
At the request of the Director General of the
Department of Information Technology;
The Governor of the State Bank of Vietnam
promulgates the Circular on implementation of Open Application Programming
Interface in banking sector.
Chapter I
GENERAL
REGULATIONS
Article 1. Scope
1. This Circular promulgates regulations on
implementation of Open Application Programming Interface in banking sector.
2. This Circular does not regulate the
connection and processing of state secret data. The processing of state secret
data shall be in accordance with the law.
3. This Circular does not regulate the direct
connection and resolution of data between:
a) The information system of banks and the
information system of organizations via Application Programming Interface to
serve internal affairs of those organizations;
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
Article 2. Regulated
entities
1. Commercial banks, cooperative banks, foreign
bank branches (hereinafter referred to as “banks”).
2. Relevant organizations and individuals in
implementation of services via Application Programming Interface in banking
sector
Article 3. Definitions
For the purposes of this Circular, the terms
below shall be construed as follows:
1. Application Programming Interface
(hereinafter referred to as “API”) is an interface that allows communication
between software applications within an organization or between organizations.
2. Open API in banking sector (Open API) is a
collection of APIs provided by banks to third parties for direct connection and
data processing to provide services to customers. Open API includes basic Open
API and other Open APIs
3. Open API testing system is the information
system of banks provided to third parties to test Open APIs before official
implementation.
4. Customers are
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
5. Third party is an organization or another
bank that has a contractual agreement with the bank to connect, process data
through Open APIs to provide services to customers.
6. Customer consent is the clear, voluntary
expression affirming a customer’s permission for the processing of the his/her
personal data.
Article 4. General
principles
Banks, customers, third parties (hereinafter
referred to as parties) shall comply with following principles during
implementation of Open API:
1. Comply with the law on protection, provision
of customer data and protection of personal data. The processing of personal
data of a customer serves only the respective customer, unless otherwise
prescribed by law.
2. Data during processing shall be managed,
stored, exploited, and used for the intended purpose as prescribed in the
contract between parties and in accordance with the law.
3. Data during processing shall be continuously
updated and accurate. In case of discrepancies, timely corrections and
adjustments shall be implemented according to the agreement between parties.
Chapter II
SPECIFIC
REGULATIONS ON IMPLEMENTATION OF OPEN API
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
Article 5.
Principles of implementation of Open API
1. When implementing basic Open APIs prescribed
in Article 6 of this Circular, banks shall comply with regulations in
Appendices 01 and 02 attached to this Circular.
2. When implementing Open APIs other than those
prescribed in Article 6 of this Circular according to practical needs and in
accordance with the law, banks shall comply with regulations in Appendix 02
attached to this Circular.
3. Banks shall only implement Open API
prescribed in point c clause 1 Article 6 for third parties which are banks and
payment intermediary service providers.
Article 6. List of Open
APIs
1. The list of basic Open APIs includes
following groups:
a) Open APIs for querying exchange rates and
interest rates of banks including API for retrieval of data on interest rates,
API for retrieval of exchange rates;
b) Open APIs for querying data of customers
including: API for authorization and consent, API for retrieval of access code,
API for refresh of access code, API for revocation of access code, API for
retrieval of account list, API for retrieval of account data, API for retrieval
of transaction history;
c) Open APIs for payment initiation, e-wallet
cash-in, and e-wallet cash-out including:
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
(ii) Open APIs for e-wallet cash-in
including: API for e-wallet deposit, API for OTP confirmation, API for update
of confirmation status of e-wallet deposit via Decoupled Flow, API for
retrieval of confirmation status of e-wallet deposit via Decoupled Flow, API
for e-wallet deposit confirmation, API for retrieval of transaction status;
(iii) Open API for e-wallet cash-out.
2. The detailed list of Open APIs in clause 1
of this Article is promulgated in Appendix 01 attached to this Circular.
Article 7. List of
technical standards
1. The technical standards for implementing
Open API include architecture standards, data standards, and security
standards.
2. The technical standards for implementing
Open API in banking sector is promulgated in Appendix 02 attached to this
Circular.
Article 8. Contracts
between banks and third parties
The bank and the third party shall enter into a
contract on implementing Open API including following content:
1. Commitment to data security including an
agreement to ensure safety and security of data during data processing via Open
API provided by the bank.
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
3. The third party’s responsibility to notify
the bank when they detect any personnel violating cybersecurity network during
implementation of Open API.
4. Information on Open API services
provided to customers.
5. Information on Open API service fees for
customers (if any).
6. Terms regarding the evaluation and
classification of the information system of third parties, which connects and
transmits data via Open API, in accordance with regulations on assurance of
information system security at different levels of the Government.
7. Access rights of third parties during
implementation of Open API.
8. Termination clause.
Article 9. Disclosure
of information on Open API
Before connecting and processing data with the
third parties, banks shall disclose information on Open AI on their official
websites including the following content:
1. Information on Open API testing system.
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
Section 2. RIGHTS AND
RESPONSIBILITIES OF BANKS AND THIRD PARTIES
Article 10. Rights of
banks
1. Request third parties to provide information
related to connection and processing data via Open API.
2. Other rights as prescribed in the contract
with the third parties.
Article 11.
Responsibilities of banks
1. Complete information technology
infrastructure for connection and processing data via Open API.
2. Formulate and complete guidelines on
connection and processing data.
3. Ensure the quality of data during the
implementation of Open API. Timely notify the third parties in case of data
discrepancies, and collaborate with the third parties to correct and adjust
them promptly.
4. Ensure cybersecurity of the information
system implementing Open API in accordance with level 3 of the Government on
levels of information system security and of the State Bank of Vietnam on the
information system in banking sector.
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
Search the data that customers have allowed the
third party to process.
b) Withdraw their consent in accordance with
the law.
6. Set a time limit of up to 180 days for
accessing customer data after obtaining customer consent, except in cases where
there is another agreement between customers and banks.
7. Provide information on the progress of
implementation of Open API to the State Bank of Vietnam (through the Department
of Information Technology) upon request.
8. Collaborate with the third parties based on
agreements and with competent authorities in resolving issues or disputes
during the implementation of Open API.
9. Implement a technological solution to limit
the number of automated queries for customer information from third parties.
10. Take responsibility in selecting,
appraising, supervising and managing the third parties.
11. Update or revoke the right to access to the
data of the third parties in accordance with contract changes.
12. Supervise access activities:
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
b) Record a comprehensive log of all Open
AI usage of the third-parties at least 03 months and store the data for at
least 01 year for inspection (if necessary).
Article 12. Rights and
responsibilities of third parties
1. The third parties have the following rights according
to contracts or agreements with banks and customers.
2. Responsibilities of third parties:
a) Provide tools and fuctions for customers to:
(i) Search the data that customers have allowed
the third party to process.
(ii) Withdraw their consent in accordance with
the law.
b) Notify the customers on clauses,
requirements for using the services and provide guidelines for customers to use
the services.
c) Issue procedures for risk management,
customer care, complaint resolution, dispute resolution, assurance of
continuous operation, and use of services when providing services to customer.
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
dd) Promptly notify the banks if there are
incidents related to information technology or information security when
implementing Open API. The method and time of notification shall be in
accordance with the agreement between banks and third parties.
e) Timely notify the banks in case of data
discrepancies, and collaborate with the banks to correct and adjust them
promptly. The method and time of notification shall be in accordance with the
agreement between banks and third parties
Chapter III
IMPLEMENTATION
CLAUSE
Article 13.
Responsibilities of the Department of Information Technology
1. Take charge, collaborate with relevant units
affiliated to the State Bank of Vietnam to resolve issues during the
implementation of this Circular.
2. Supervise, consolidate, report the Governor
of the State Bank of Vietnam the implementation status of banks in accordance
with this Circular.
3. Inspect banks implementing this Circular.
Article 14. Effect
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
Article 15.
Transitional provision
Banks that have already connected and directly
processed data with third parties via API or Open API to provide services to
individual customers before the effective date of this Circular must:
1. Formulate a list of APIs, Open APIs that
they are implementing and a detailed implementation plan in accordance with
this Circular, and report to the State Bank of Vietnam (through the Department
of Information Technology) by July 01, 2025.
2. Comply with regulations in this Circular by
March 01, 2027.
Article 16.
Implementation
Heads of units affiliated to the State Bank of
Vietnam, commercial banks, cooperative banks, foreign bank branches shall
implement this Circular./.
PP. THE GOVERNOR
DEPUTY GOVERNOR
Pham Tien Dung
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
APPENDIX 01
TECHNICAL SPECIFICATIONS FOR OPEN APIs IN THE BANKING SECTOR
(Attached with Circular No. 64/2024/TT-NHNN dated December 31, 2024 of the
Governor of the State Bank of Vietnam)
Glossary
No.
Terminology
Description
1
PSU
(Payment Service User)
Customer
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
TPP
(Third Party Provider)
Third
party provider
3
Bank
Auth Server
Bank
authorization server
4
Bank
Open API
Bank
Open API system
5
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
Access
token
6
refresh_token
Refresh
token
7
UUID
(Universally Unique Identifier)
Universally
unique identifier
8
INF
(INFormation)
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
9
AIS
(Account Information Service)
Open
APIs for querying customer information
10
PIS
(Payment Initiation Service)
Payment
initiation Open APIs
11
EWLTS
(Ewallet Service)
Open
APIs for e-wallet cash-in and cash-out
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
List of Open APIs by category under Article 6
No.
Open API list
I
Open
APIs for querying the Bank’s exchange rates and interest rates (point a,
clause 1)
1
API
for querying interest rates
2
API
for querying exchange rates
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
Open
APIs for querying customer information (point b, clause 1)
1
API
for authentication and obtaining consent of customers
2
API
for querying access token
3
API
for refreshing access token
4
API
for revoking access token
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
API
for querying account list
6
API
for querying account information
7
API
for querying transaction history
III
Open
APIs for payment initiation, e-wallet cash-in and cash-out (point c, clause
1)
A
Open
APIs for payment initiation
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
API
for payment initiation
2
API
for authenticating customer — Redirect flow
3
API for
querying access token — Redirect flow
4
API
for updating customer payment authorization status — Decoupled flow
5
API
for payment confirmation
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
API
for querying transaction status
7
API querying
customer payment authorization status — Decoupled flow
B
Open
APIs for e-wallet cash-in
1
API
for e-wallet cash-in
2
API
for OTP verification
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
API
for updating customer e-wallet cash-in authorization status — Decoupled flow
4
API
for querying customer e-wallet cash-in authorization status — Decoupled flow
5
API
for e-wallet cash-in confirmation
6
API
for querying transaction status
C
Open
API for e-wallet cash-out
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
1. General principles and technical requirements
- The Open API URLs specified in this Appendix shall follow
this uniform naming convention: “https://<domain>/api/v1/….”
- The parameters for Open APIs specified in this Appendix are
the minimum required set.
- A TPP shall use its valid and active Vietnamese tax
identification number as its identifier (TPP-ID).
- A bank shall use the bank code assigned by the State Bank
of Vietnam for banking operations as its identifier (Provider-ID).
- Once connectivity has been established and communications
between the Bank and the TPP have been secured in accordance with the standards
in Appendix 02, the TPP shall register its application identifier (client_id)
and client secret (client_secret) with the Bank.
- Banks shall manage TPP connections and access to Open APIs
in accordance with the OAuth 2.0 Authorization Framework in RFC 6749. Depending
on the API category, banks shall use the following access token flows as specified
in RFC 6749:
+
Client credentials grant flow (section 4.4 of RFC 6749).
+
Authorization code grant flow (section 4.1 of RFC 6749), combined with PKCE
under RFC 7636 for certain APIs for querying access token.
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
-
Token validity periods for these categories are as follows:
+
Authorization Code (GET/authorize): single use, valid for 180 seconds.
+
Access Token where grant_type is client_credentials (POST/token): valid
for a maximum of 3600 seconds.
+
Access Token where grant_type is authorization_code (POST/token): for
AIS, valid for a maximum of 3600 seconds; for PIS, single use and valid for a
maximum of 300 seconds.
+
Refresh token where grant_type is refresh_token (POST/token): applicable
only to AIS; its validity period shall comply with the customer data-sharing
consent as prescribed in clause 6 of Article 11. While the refresh_token
remains valid, the TPP may use it to obtain a new access_token from the Bank’s
authorization server without requiring the customer to repeat the access token
flow in section 3 of this Appendix.
- A consentId (generated after successful customer
authentication in the Decoupled flow for PIS and EWLTS, or the OTP flow for
EWLTS) is valid for 300 seconds.
- The values in the “Req.” column of the Open API
specification tables below have the following meanings:
+ M:
mandatory.
+ O:
optional.
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
- Open APIs with parameters in the body shall be signed using
Detached JWS in accordance with RFC 7515.
- The components shown in the flow diagrams in this Appendix
are represented at the logical level.
2. Open APIs for querying the Bank’s exchange rates and
interest rates (point a, clause 1, Article 6)
Figure 1: Bank exchange rate and interest rate querying flow
(INF)
- Flow description:
+ Step
1: The customer requests for querying exchange rates or interest rates of a
bank via the TPP application.
+ Step
2: The TPP requests an access_token under OAuth 2.0 with grant_type
set to client_credentials (details in section 4.4 of RFC 6749).
+ Step
2.1. The Bank’s authorization server validates the request and returns an access_token
to the TPP.
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
+ Step
3: The TPP requests for querying interest rates from the Bank’s system via the “API
for querying interest rates” in section 2.1.
+ Step
3.1. The Bank’s system returns the result to the TPP.
+ Step
3.2. The application of TPP displays the result to the customer.
If the
customer requests for querying exchange rates, proceed to step 4:
+ Step
4: The TPP requests for querying exchange rates from the Bank’s system via the “API
for querying exchange rates” in section 2.2.
+ Step
4.1. The Bank’s system returns the result to the TPP.
+ Step
4.2. The application of TPP displays the result to the customer.
2.1. API for querying interest rates
Endpoint
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
Method
GET
Scope
INF
- Request Header:
Parameter
Data type
Req.
Description
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
String
M
Default:
“application/json”
Authorization
String
M
-
Authorization format: “Bearer + {access_token}”, in accordance with RFC 6750.
-
The access_token is issued in accordance with section 4.4 of RFC 6749 (with
grant_type set to client_credentials).
Request-DateTime
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
M
-
Request date and time.
-
Format: yyyy-MM- ddTHH:mm:ssZ (UTC DateTime), in accordance with RFC 3339.
Request-ID
String [60]
M
Unique
request identifier, usually in UUID format.
PSU-IP-Address
String [50]
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
Customer’s
IP address.
This
value must be in IPv4 or IPv6 format.
PSU-User-Agent
String [200]
O
Browser
information if the customer uses the TPP’s website, or relevant information
if the customer uses another TPP application.
PSU-Device-OS
String [100]
O
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
Provider-ID
String [8]
M
Bank
identifier specified in section 1.
TPP-ID
String [15]
M
TPP
identifier specified in section 1.
Client-ID
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
O
Client_id
value specified in section 1.
- Query parameter:
Parameter
Data type
Req.
Description
currency
String [3]
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
Currency
expressed as a three-letter uppercase in accordance with ISO 4217.
- Response Header:
Parameter
Data type
Req.
Description
Content-Type
String
M
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
Request-ID
String
M
Value
taken from the request header in the TPP’s API request.
Request-DateTime
String
M
Value
taken from the request header in the TPP’s API request.
JWS-Signature
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
M
JWS
signature as specified in section 1.
- Response Body:
+ HTTP
STATUS CODE 200 OK:
Level 1
Level 2
Data type
Req.
Description
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
Array
M
List
of interest rates
currency
String [3]
M
Currency
expressed as a three-letter uppercase in accordance with ISO 4217.
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
productCode
String [100]
O
Cash-in
product code
productDesc
String [300]
M
Cash-in
product description
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
termCode
String [100]
M
Deposit
term
minAmount
Number
M
Minimum
cash-in amount
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
customerType
String [4]
M
Customer
type under ISO 20022.
Default
value: “PRVT” (individual customer)
interestRate
String [5]
M
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
effectiveDate
Datetime
M
-
Effective date.
-
Format: yyyy-MM- ddTHH:mm:ssZ (UTC DateTime), in accordance with RFC 3339.
additionalInfo
Object
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
Additional
information (if any)
+
Error Code: Refer to section 7.2.1 -
Error response format, and section 7.2.2 - Common error codes.
2.2. API for querying exchange rates
Endpoint
/v1/exchangerate?currency={currency}
Method
GET
Scope
INF
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
Parameter
Data type
Req.
Description
Content-Type
String
M
Default:
“application/json”
Authorization
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
M
-
Authorization format: “Bearer + {access_token}”, in accordance with RFC 6750.
-
The access_token is issued in accordance with section 4.4 of RFC 6749 (with
grant_type set to client_credentials).
Request-DateTime
DateTime
M
-
Request date and time.
-
Format: yyyy-MM-ddTHH:mm:ssZ (UTC DateTime), in accordance with RFC 3339.
Request-ID
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
M
Unique
request identifier, usually in UUID format.
PSU-IP-Address
String [50]
O
Customer’s
IP address. This value must be in IPv4 or IPv6 format.
PSU-User-Agent
String [200]
O
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
PSU-Device-OS
String [100]
O
Operating
system on the customer’s device (computer, mobile device, etc.).
Provider-ID
String [8]
M
Bank
identifier specified in section 1.
TPP-ID
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
M
TPP
identifier specified in section 1.
Client-ID
String [50]
O
Client_id
value specified in section 1.
- Query parameter:
Parameter
Data type
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
Description
currency
String [3]
O
Currency
expressed as a three-letter uppercase in accordance with ISO 4217.
- Response Header:
Parameter
Data type
Req.
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
Content-Type
String
M
Default:
“application/json”
Request-ID
String
M
Value
taken from the request header in the TPP’s API request.
Request-DateTime
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
M
Value
taken from the request header in the TPP’s API request.
JWS-Signature
String
M
JWS
signature as specified in section 1.
- Response Body:
+ HTTP
STATUS CODE 200 OK:
Level 1
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
Data type
Req.
Description
rates
Array
M
List
of exchange rates
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
String [3]
M
Currency
expressed as a three-letter uppercase in accordance with ISO 4217
buyCashRate
Number
M
Cash
buying rate
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
Number
M
Transfer
buying rate
sellCashRate
Number
M
Cash
selling rate
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
Number
M
Transfer
selling rate
additionalInfo
Object
O
Additional
information (if any)
applyDate
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
DateTime
M
-
Time at which the exchange rates take effect in the Bank’s system.
-
Format: yyyy-MM-ddTHH:mm:ssZ (UTC DateTime), in accordance with RFC 3339.
+
Error Code: Refer to section 7.2.1 - Error response format, and section 7.2.2 -
Common error codes.
3. Open APIs for querying customer information (point b,
clause 1, Article 6)
Applicable
only to queries initiated by the customer through the application of TPP.
- The customer token grant flow, triggered when the
process for obtaining the customer’s data-sharing consent is initiated through
the TPP application, is described below:
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
+ Step
1: The customer logs in to the TPP application and uses a TPP service that
involves the customer’s consent to data sharing.
● If the customer has not consented to data sharing, or the
consent period specified in clause 6 of Article 11 has expired, proceed with steps
1.1 to 2.4.
● If the consent remains valid but the access_token
has expired, proceed from step 3.
+ Step
1.1. The TPP’s system redirects the customer to the Bank’s authorization page.
+ Step
2: The customer is redirected to the Bank’s authorization page to provide
data-sharing consent through the “API for authentication and obtaining
consent of customers” in section 3.1. The customer then logs in to
the Bank’s authorization server.
+ Step
2.1. The Bank’s authorization server authenticates the customer. After
successful authentication, the customer consents to data sharing via the Bank’s
interface.
+ Step
2.2: The Bank’s authorization server redirects the customer to the TPP
application with an authorization code (details in section 3.1).
+ Step
2.3: The TPP requests an access_token and a refresh_token from the
Bank’s authorization server (Details prescribed in “API for querying access
token” in section 3.2).
+ Step
2.3.1: The Bank’s authorization server returns the result to the TPP. The TPP
uses the access_token to perform AIS queries and the refresh_token
to renew the access_token when it expires as described in step 3.
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
+ Step
3.1: The Bank’s authorization server returns the result to the TPP.
- The account information query flow using the access_token
obtained through the token grant flow (Figure 2) is described below:
Figure 3: Account information query flow
+ Step
4: The customer requests an account list via the TPP application.
+ Step
4.1: The TPP requests the account list from the Bank’s system through the “API
for querying account list” in section 3.5.
+ Step
4.2: The Bank’s system returns the result to the TPP.
+ Step
4.3: The TPP application displays the account list to the customer.
If the
customer requests information on a specific account, proceed to step 5:
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
+ Step
5.1: The TPP requests information on the account from the Bank’s system through
the “API for querying account information” in section 3.6.
+ Step
5.2: The Bank’s system returns the result to the TPP.
+ Step
5.3: The TPP application displays the account information to the customer.
If the
customer requests transaction history, proceed to step 6:
+ Step
6: The customer requests transaction history through the TPP application.
+ Step
6.1: The TPP requests transaction history from the Bank’s system via the “API
for querying transaction history” in section 3.7.
+ Step
6.2: The Bank’s system returns the result to the TPP.
+ Step
6.3: The TPP application displays the transaction history to the customer.
3.1. API for authentication and obtaining consent of
customers
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
/authorize
Method
GET
- Request Header:
Parameter
Data type
Req.
Description
Content-Type
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
M
application/x-www-form-urlencoded
Host
String
O
Identifies
the domain name of the server to which the request is sent.
- Query Parameter:
Parameter
Data type
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
Description
response_type
String
M
Default:
“code”
client_id
String
M
Client_id
value specified in section 1.
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
String
M
Access
scope: AIS
redirect_uri
String
M
URL
used to redirect the customer to the TPP application after the Bank’s
authorization server completes customer authentication.
state
String
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
Value
generated by the TPP to maintain the status between the request and response,
and prevent cross-site request forgery attacks.
code_challenge
String
M
code_challenge
= BASE64URL- ENCODE(SHA256(ASCII(code_verifier)))
Refer
to RFC 7636 for details.
code_challenge_method
String
O
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
Default:
“S256”
- Response:
+ The
Bank’s authorization server redirects the customer to the TPP application using
redirect_uri with the URL parameters described in the table below:
Parameter
Data type
Req.
Description
code
String
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
Authorization
code
state
String
M
State
value from the TPP’s request.
+
Error Code: Refer to section 7.1.2 - Error codes for the API for authentication
and obtaining consent of customers.
3.2. API for querying access token
Endpoint
/token
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
POST
-
Request Header:
Parameter
Data type
Req.
Description
Content-Type
String
M
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
Authorization
String
M
Basic
BASE64(client_id + “:” + client_secret)
Host
String
O
Identifies
the domain name of the server to which the request is sent.
- Request body:
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
Data type
Req.
Description
grant_type
String
M
Default:
“authorization_code”
code
String
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
Authorization
code issued by the Bank to the TPP via the token grant flow.
redirect_uri
String
M
URL
used to redirect the customer to the TPP application. This value must match
the redirect_uri supplied to the API for authentication and obtaining consent
of customers in section 3.1.
code_verifier
String
M
The
code_verifier used to generate the code_challenge supplied by the TPP to the API
for authentication and obtaining consent of customers in section 3.1 (Refer
to RFC 7636 for details).
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
Parameter
Data type
Req.
Description
Content-Type
String
M
Default:
“application/json”
- Response body:
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
Parameter
Data type
Req.
Description
access_token
String
M
Access
token.
refresh_token
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
M
Refresh
token.
token_type
String
M
Default:
“Bearer”
expires_in
Number
M
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
scope
String
M
Scope
of the access_token. This value matches the scope in the API for
authentication and obtaining consent of customers in section 3.1.
+
Error Code: Refer to section 7.1.2 - Error
codes for the API for querying access token.
3.3. API for refreshing access token
Endpoint
/token
Method
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
- Request Header:
Parameter
Data type
Req.
Description
Content-Type
String
M
application/x-www-form-urlencoded
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
String
M
Basic
BASE64(client_id + “:” + client_secret)
Host
String
O
Identifies
the domain name of the server to which the request is sent.
- Request body:
Parameter
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
Req.
Description
grant_type
String
M
Default:
“refresh_token”
refresh_token
String
M
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
scope
String
O
The
scope must not exceed the scope in the API for authentication and obtaining
consent of customers in section 3.1.
- Response Header:
Parameter
Data type
Req.
Description
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
String
M
Default:
“application/json”
- Response body:
+ HTTP
STATUS CODE 200 OK:
Parameter
Data type
Req.
Description
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
String
M
Access
token.
refresh_token
String
O
Refresh
token (this may differ from the refresh token generated through the token grant
flow with grant_type set to authorization_code).
token_type
String
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
Default:
“Bearer”
expires_in
Number
M
Validity
period of the access_token for AIS as specified in section 1.
+
Error code: Refer to section 7.1.2 - Error codes for the API for querying
access token.
3.4. API for revoking access token
The
TPP calls this API when the customer withdraws consent via the TPP application.
Endpoint
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
Method
POST
- Request Header:
Parameter
Data type
Req.
Description
Content-Type
String
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
application/x-www-form-urlencoded
Authorization
String
M
Basic
BASE64(client_id + “:” + client_secret)
Host
String
O
Identifies
the domain name of the server to which the request is sent.
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
Parameter
Data type
Req.
Description
token
String
M
The
access_token or refresh_token to be revoked.
token_type_hint
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
O
Type
of token to be revoked: “access_token” or “refresh_token”.
- Response:
+ HTTP
STATUS CODE 200 OK with no response data (refer to RFC 7009 for details).
+
Error code: Refer to section 7.1.2 - Error
codes for the API for querying access token.
3.5. API for querying account list
Endpoint
/v1/accounts
Method
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
Scope
AIS
- Request Header:
Parameter
Data type
Req.
Description
Content-Type
String
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
Default:
“application/json”
Authorization
String
M
-
Authorization format: “Bearer + {access_token}” in accordance with RFC 6750.
-
The access_token is issued in accordance with section 4.1 of RFC 6749
(Authorization Code Grant).
Request-DateTime
DateTime
M
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
- Format:
yyyy-MM- ddTHH:mm:ssZ (UTC DateTime) in accordance with RFC 3339.
Request-ID
String [60]
M
Unique
request identifier, usually in UUID format.
PSU-IP-Address
String [50]
O
Customer’s
IP address. This value must be in IPv4 or IPv6 format.
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
String [200]
O
Browser
information if the customer uses the TPP’s website, or relevant information
if the customer uses another TPP application.
PSU-Device-OS
String [100]
O
Operating
system on the customer’s device (computer, mobile device, etc.).
Provider-ID
String [8]
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
Bank
identifier specified in section 1.
TPP-ID
String [15]
M
TPP
identifier specified in section 1.
Client-ID
String [50]
O
Client_id
value specified in section 1.
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
- Response Header:
Parameter
Data type
Req.
Description
Content-Type
String
M
Default:
“application/json”
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
String
M
Value
taken from the request header in the TPP’s API request.
Request-DateTime
DateTime
M
Value
taken from the request header in the TPP’s API request.
JWS-Signature
String
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
JWS
signature as specified in section 1.
- Response body:
+ HTTP
STATUS CODE 200 OK:
Level 1
Level 2
Level 3
Data type
Req.
Description
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
Array
Account
list
identification
Object
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
Information
on the customer’s account opened at the Bank.
accountId
String [34]
M
Customer’s
account number
name
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
String [70]
M
Customer’s
account name.
type
String [4]
M
Account
type under ISO 20022.
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
currency
String [3]
M
Currency
expressed as a three-letter uppercase in accordance with ISO 4217.
bankCode
String [8]
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
Bank
identifier as specified in section 1.
additionalInfo
Object
O
Additional
information (if any)
+
Error Code: Refer to section 7.2.1 -
Error response format, and section 7.2.2 - Common error codes.
3.6. API for querying account information
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
/v1/accounts/information
Method
POST
Scope
AIS
- Request Header:
Parameter
Data type
Req.
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
Content-Type
String
M
Default:
“application/json”
Authorization
String
M
-
Authorization format: “Bearer + {access_token}” in accordance with RFC 6750.
-
The access_token is issued in accordance with section 4.1 of RFC 6749
(Authorization Code Grant).
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
DateTime
M
-
Request date and time.
-
Format: yyyy-MM- ddTHH:mm:ssZ (UTC DateTime), in accordance with RFC 3339.
Request-ID
String [60]
M
Unique
request identifier, usually in UUID format.
PSU-IP-Address
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
O
Customer’s
IP address. This value must be in IPv4 or IPv6 format.
PSU-User-Agent
String [200]
O
Browser
information if the customer uses the TPP’s website, or relevant information
if the customer uses another TPP application.
PSU-Device-OS
String [100]
O
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
Provider-ID
String [8]
M
Bank
identifier as specified in section 1.
TPP-ID
String [15]
M
TPP
identifier as specified in section 1.
Client-ID
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
O
Client_id
value as specified in section 1.
JWS-Signature
String
M
JWS
signature as specified in section 1.
- Request Body:
Level 1
Data type
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
Description
accountId
String [34]
M
Customer’s
account number.
- Response Header:
Parameter
Data type
Req.
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
Content-Type
String
M
Default:
“application/json”
Request-ID
String
M
Value
taken from the request header in the TPP’s API request.
Request-DateTime
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
M
Value
taken from the request header in the TPP’s API request.
JWS-Signature
String
M
JWS
signature as specified in section 1.
- Response Body:
+ HTTP
STATUS CODE 200 OK:
Level 1
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
Level 3
Data type
Req.
Description
identification
Object
M
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
accountId
String [34]
M
Customer’s
account number
name
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
M
Customer’s
account name.
type
String [4]
M
Account
type under ISO 20022.
currency
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
String [3]
M
Currency
expressed as a three-letter uppercase in accordance with ISO 4217.
bankCode
String [8]
M
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
creationDate
Datetime
M
-
Account creation date.
-
Format: yyyy-MM-ddTHH:mm:ssZ (UTC DateTime), in accordance with RFC 3339.
balances
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
Array
M
Detailed
balance information
amount
Object
M
Available
balance information
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
value
Number
M
Available
balance in the customer’s account
currency
String [3]
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
Currency
expressed as a three-letter uppercase in accordance with ISO 4217.
dateTime
DateTime
M
-
Date and time of processing by the system.
-
Format: yyyy-MM-ddTHH:mm:ssZ (UTC DateTime), in accordance with RFC 3339.
additionalInfo
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
Object
O
Additional
information (if any)
+
Error Code: Refer to section 7.2.1 -
Error response format, and section 7.2.2 - Common error codes.
3.7. API for querying transaction history
- The
period for which transaction history may be queried is subject to the Bank’s
rules.
Endpoint
/v1/accounts/transactions
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
POST
Scope
AIS
-
Request Header:
Parameter
Data type
Req.
Description
Content-Type
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
M
Default:
“application/json”
Authorization
String
M
-
Authorization format: “Bearer + {access_token}”, in accordance with RFC 6750.
-
The access_token is issued in accordance with section 4.1 of RFC 6749
(Authorization Code Grant).
Request-DateTime
DateTime
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
-
Request date and time.
-
Format: yyyy-MM-ddTHH:mm:ssZ (UTC DateTime), in accordance with RFC 3339.
Request-ID
String [60]
M
Unique
request identifier, usually in UUID format.
PSU-IP-Address
String [50]
O
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
PSU-User-Agent
String [200]
O
Browser
information if the customer uses the TPP’s website, or relevant information
if the customer uses another TPP application.
PSU-Device-OS
String [100]
O
Operating
system on the customer’s device (computer, mobile device, etc.).
Provider-ID
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
M
Bank
identifier as specified in section 1.
TPP-ID
String [15]
M
TPP
identifier as specified in section 1.
Client-ID
String [50]
O
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
JWS-Signature
String
M
JWS
signature as specified in section 1.
- Request Body:
Level 1
Data type
Req.
Description
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
String [34]
M
Customer’s
account number.
fromDate
DateTime
M
-
Transaction start date.
-
Format: yyyy-MM-ddTHH:mm:ssZ (UTC DateTime), in accordance with RFC 3339.
toDate
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
M
-
Transaction end date.
-
Format: yyyy-MM-ddTHH:mm:ssZ (UTC DateTime), in accordance with RFC 3339.
page
Number
O
Specifies
the requested page number. Pages are numbered from 1. If this parameter is
omitted, the API returns page 1.
size
Number
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
Specifies
the number of records per page. If this parameter is omitted, the API returns
all records matching the request.
- Response Header:
Parameter
Data type
Req.
Description
Content-Type
String
M
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
Request-ID
String
M
Value
taken from the request header in the TPP’s API request.
Request-
DateTime
DateTime
M
Value
taken from the request header in the TPP’s API request.
JWS-Signature
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
M
JWS
signature as specified in section 1.
- Response Body:
+ HTTP
STATUS CODE 200 OK:
Level 1
Level 2
Level 3
Level 4
Data type
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
Description
pageCount
Number
M
Total
number of pages
pageNumber
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
Number
M
Current
page
nextPage
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
O
Next
page
pageSize
Number
M
Number
of records per page.
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
Number
O
Total
number of records across all pages
transactions
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
Array
M
Transaction
history records
amount
Object
M
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
value
Number
M
Transaction
amount
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
String [3]
M
Currency
expressed as a three-letter uppercase in accordance with ISO 4217.
balances
Object
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
Balance
information
value
Number
M
Balance
at the time of the transaction
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
currency
String [3]
M
Currency
expressed as a three-letter uppercase in accordance with ISO 4217.
creditDebitIndicator
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
M
-
CRDT (Credit) for a credit balance
-
DBIT (Debit) for a debit balance
reversalIndicator
boolean
O
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
valueDate
DateTime
M
-
Transaction date and time.
-
Format: yyyy-MM-ddTHH:mm:ssZ (UTC DateTime), in accordance with RFC 3339.
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
Object
M
Transaction
identifier information
instructio
nIdentific ation
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
M
Unique
identifier for each transaction
relatedParties
Object
O
Sender
and recipient information
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
debtor
Object
O
Sender
information
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
String [140]
O
Sender’s
name
bankCode
String [8]
O
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
accountId
String [34]
O
Account
number.
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
Object
O
Recipient
information
name
String [140]
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
Recipient’s
name
bankCode
String [8]
O
Recipient’s
bank identifier as specified in section 1.
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
accountId
String [34]
O
Recipient’s
account number
additional TransactionInform ation
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
M
Transaction
details
additionalInfo
Object
O
Additional
information (if any)
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
4. Open APIs for payment initiation (point c, clause 1,
Article 6)
Applicable
only to payment orders initiated by the customer via the TPP application.
- API
for payment initiation flow:
Figure 4: API for payment initiation flow (PIS)
- Flow
description:
+ Step
1: The customer initiates a payment request via the TPP application.
+ Step
2: The TPP requests an access_token under OAuth 2.0 with grant_type
set to client_credentials (refer to section 4.4 of RFC 6749 for
details).
+ Step
2.1. The Bank’s authorization server validates the request and returns an access_token
to the TPP.
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
+ Step
3.1. The Bank’s system validates the information in the TPP’s request. If the
information is valid, it returns a unique transaction identifier (paymentId)
to the TPP, with consentStatus set to “AWAITTING_AUTH”.
For
the Redirect flow (steps 4 to 5.1):
+ Step
4: After receiving the paymentId, the TPP redirects the customer to the Bank’s
authorization page to authorize the payment.
+ Step
4.1: The customer logs in (refer to the “API for authenticating customer”
in section 4.2 for details).
+ Step
4.1.1. The customer confirms the payment details via the Bank’s interface.
+ Step
4.1.2. The customer authorizes the payment using the Bank’s authentication
methods in accordance with the laws.
+ Step
4.1.3: The Bank’s authorization server redirects the customer to the TPP
application with an authorization code.
+ Step
4.2: The TPP requests an access_token from the Bank’s authorization server
(refer to the “API for querying access toekn” in section 4.3 for
details).
+ Step
4.2.1: The Bank’s authorization server validates the authorization code in the
TPP’s request.
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
+ Step
5: The TPP sends a payment confirmation request to the Bank through the “API
for payment confirmation” in section 4.5.
+ Step
5.1. The Bank returns the payment result.
For
the Decoupled flow (steps 4’ to 5.1’):
+ Step
4’: Depending on the design of the TPP application and the Bank’s system, the
Bank’s authorization server may or may not notify the customer that a payment
requires authorization.
+ Step
4.1’: The customer opens the Bank’s application.
+ Step
4.1.1’: The customer confirms the payment details via the Bank’s interface.
+ Step
4.1.2’: The customer authorizes the payment using the authentication methods
prescribed by the Bank in accordance with the laws.
+ Step
4.2’: The Bank’s system sends the customer’s payment authorization status to
the TPP via the “API for updating customer payment authorization status —
Decoupled flow” in section 4.4.
+ Step
4.2.1’: The TPP receives the customer’s payment authorization status and
returns a response to the Bank’s system as prescribed in section 4.4.
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
+ Step
4.3.1’: The Bank’s system receives the request and returns the result to the
TPP.
+ Step
5’: The TPP sends a payment confirmation request, including the consentId, to
the Bank via the “API for payment confirmation” in section 4.5.
+ Step
5.1’: The Bank’s system receives the request and returns the result to the TPP
as prescribed in section 4.5.
+ Step
6: If the TPP does not receive the accounting result from the Bank, it requests
the transaction status from the Bank’s system via the “API for querying
transaction status” in section 4.6.
+ Step
6.1: The Bank’s system receives the request and returns the result to the TPP.
+ Step
7: The TPP displays the payment result to the customer.
4.1. API for payment initiation
Endpoint
/v1/payments
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
POST
Scope
PIS
- Request Header:
Parameter
Data type
Req.
Description
Content-Type
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
M
Default:
“application/json”
Authorization
String
M
-
Authorization format: “Bearer + {access_token}”, in accordance with RFC 6750.
-
The access_token is issued in accordance with section 4.4 of RFC 6749 (with
grant_type set to client_credentials).
Request-DateTime
DateTime
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
-
Request date and time.
-
Format: yyyy-MM- ddTHH:mm:ssZ (UTC DateTime), in accordance with RFC 3339.
Request-ID
String [60]
M
Unique
request identifier, usually in UUID format.
PSU-IP-Address
String [50]
O
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
PSU-User-Agent
String [200]
O
Browser
information if the customer uses the TPP’s website, or relevant information
if the customer uses another TPP application.
PSU-Device-OS
String [100]
O
Operating
system on the customer’s device (computer, mobile device, etc.).
Provider-ID
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
M
Bank
identifier as specified in section 1.
TPP-ID
String [15]
M
TPP
identifier as specified in section 1.
Client-ID
String [50]
O
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
JWS-Signature
String
M
JWS
signature as specified in section 1.
- Request Body:
Level 1
Level 2
Data type
Req.
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
instructionIdentification
String [50]
M
Transaction
identifier generated by the TPP
debtor
Object
C
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
name
String [70]
C
Payer’s
account name
accountId
String [34]
C
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
bankCode
String [8]
C
Payer’s
bank identifier as specified in section 1.
remittanceInformation
String [255]
M
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
instructedAmount
Object
M
Transaction
amount information
value
Number
M
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
currency
String [3]
M
Currency
expressed as a three-letter uppercase in accordance with ISO 4217.
requestedExecutionDate
DateTime
M
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
-
Format: yyyy-MM- ddTHH:mm:ssZ (UTC DateTime), in accordance with RFC 3339.
additionalInfo
Object
O
Additional
information (if any)
- Response Header:
Parameter
Data type
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
Description
Content-Type
String
M
Default:
“application/json”
Request-ID
String
M
Value
taken from the request header in the TPP’s API request.
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
String
M
Value
taken from the request header in the TPP’s API request.
JWS-Signature
String
M
JWS
signature as specified in section 1.
- Response Body:
+ HTTP
STATUS CODE 200 OK:
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
Data type
Req.
Description
paymentId
String [35]
M
Unique
transaction identifier assigned by the Bank.
status
String [4]
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
Transaction
status code under ISO 20022.
statusDateTime
DateTime
M
-
Status update time.
-
Format: yyyy-MM-ddTHH:mm:ssZ (UTC DateTime), in accordance with RFC 3339.
consentStatus
String [20]
M
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
+
Error Code: Refer to section 7.2.1 -
Error response format, and section 7.2.2 - Common error codes.
4.2. API for authenticating customer — Redirect flow
Endpoint
/authorize
Method
GET
- Request Header:
Parameter
Data type
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
Description
Content-Type
String
M
application/x-www-form-urlencoded
Host
String
O
Identifies
the domain name of the server to which the request is sent.
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
Parameter
Data type
Req.
Description
response_type
String
M
Default
value: “code id_token”
client_id
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
M
Client_id
value as specified in section 1.
scope
String
M
Access
scope: PIS
redirect_uri
String
M
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
state
String
M
Value
generated by the TPP to maintain the status between the request and response,
and prevent cross-site request forgery attacks.
code_challenge
String
M
code_challenge
= BASE64URL- ENCODE(SHA256(ASCII(code_verifier)))
Refer
to RFC 7636 for details.
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
String
O
Algorithm
used to generate code_challenge.
Default:
“S256”
request
String
M
Json
Web Token (JWT).
Include
the paymentId received from the API for payment initiation in section 4.1 as
a claim in the payload.
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
+
JOSE Header — in accordance with JWT under RFC 7519 and JWS under RFC 7515;
the algorithm under the “alg” header under section 3.1 of RFC 7518.
+
payload
+
signature — JWS under RFC 7515
- Response:
+ The
Bank’s authorization server redirects the customer to the TPP application using
redirect_uri together with the values in the table below:
Parameter
Data type
Req.
Description
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
String
M
Authorization
code
state
String
M
State
value from the TPP’s request.
id_token
String
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
Json
Web Token (JWT).
Include
the paymentId received from the Initiate Payment API in section 4.1 in the
payload.
-
The JWT consists of:
+
JOSE Header — in accordance with JWT under RFC 7519 and JWS under RFC 7515; the
algorithm under the “alg” header under section 3.1 of RFC 7518;
+
payload;
+
signature — in accordance with JWS under RFC7515.
+
Error Code: Refer to section 7.1.2 -
Error codes for the API for querying access token.
4.3. API for querying access token — Redirect flow
Endpoint
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
Method
POST
- Request Header:
Parameter
Data type
Req.
Description
Content-Type
String
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
application/x-www-form-urlencoded
Authorization
String
M
Basic
BASE64(client_id + “:” + client_secret)
Host
String
O
Identifies
the domain name of the server to which the request is sent.
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
Parameter
Data type
Req.
Description
grant_type
String
M
Default:
“authorization_code”
code
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
M
Authorization
code issued by the Bank to the TPP via the API for authenticating customer —
Redirect flow in section 4.2.
redirect_uri
String
M
URL
used to redirect the customer to the TPP application. This value must match
the redirect_uri supplied to the API for authenticating customer — Redirect flow
in section 4.2.
code_verifier
String
M
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
- Response Header:
Parameter
Data type
Req.
Description
Content-Type
String
M
Default:
“application/json”
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
+ HTTP
STATUS CODE 200 OK:
Parameter
Data type
Req.
Description
access_token
String
M
Access
token.
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
String
M
Default:
“Bearer”
expires_in
Number
M
Validity
period of the access_token for PIS as specified in section 1.
scope
String
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
Scope
of the access_token. This value matches the scope in the API for
authenticating customer — Redirect flow in section 4.2.
+
Error Code: Refer to section 7.1.2 -
Error codes for the API for querying access token.
4.4. API for updating customer payment authorization status —
Decoupled flow
- The
Bank’s system calls this API of TPP to return the customer’s payment
authorization status as specified below:
Endpoint
/v1/update-consent
Method
POST
-
Request Header:
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
Data type
Req.
Description
Content-Type
String
M
Default:
“application/json”
Authorization
String
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
-
Authorization format: “Bearer + {access_token}”, in accordance with RFC 6750.
-
The access_token is issued in accordance with section 4.4 of RFC 6749 (with
grant_type set to client_credentials).
Request-DateTime
DateTime
M
-
Request date and time.
-
Format: yyyy-MM-ddTHH:mm:ssZ (UTC DateTime), in accordance with RFC 3339.
Request-ID
String [60]
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
Unique
request identifier, usually in UUID format.
JWS-Signature
String
M
JWS
signature as specified in section 1.
-
Request Body:
Level 1
Data type
Req.
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
paymentId
String [35]
M
Unique
transaction identifier issued by the Bank to the TPP via the API for payment
initiation in section 4.1.
consentId
String [36]
M
Value
generated by the Bank after successful authorization via the Bank’s
application in the Decoupled flow.
consentStatus
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
M
Takes
one of the following values:
-
“AUTHORISED” when the customer successfully authorizes the transaction.
-
“REJECTED” when the customer’s authorization does not comply with the Bank’s
requirements.
-
“CANCEL” when the customer does not authorize the transaction via the Bank’s
application.
expireIn
Number
M
Validity
period of the consentId as specified in section 1.
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
Parameter
Data type
Req.
Description
Content-Type
String
M
Default:
“application/json”
Request-ID
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
M
Value
taken from the request header in the TPP’s API request.
Request-DateTime
String
M
Value
taken from the request header in the TPP’s API request.
JWS-Signature
String
M
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
- Response Body:
+ HTTP
STATUS CODE 200 OK:
Level 1
Data type
Req.
Description
message
String [20]
M
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
+
Error Code: As specified by the TPP.
4.5. API for payment confirmation
Endpoint
/v1/payments/submit
Method
POST
Scope
PIS
- Request Header:
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
Data type
Req.
Description
Content-Type
String
M
Default:
“application/json”
Authorization
String
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
-
Authorization format: “Bearer + {access_token}”, in accordance with RFC 6750.
-
For the Redirect flow: The access_token is issued in accordance with section
4.1 of RFC 6749 (Authorization Code Grant).
-
For the Decoupled flow: The access_token is issued in accordance with section
4.4 of RFC 6749 (with grant_type set to client_credentials).
Request-DateTime
DateTime
M
-
Request date and time.
-
Format: yyyy-MM- ddTHH:mm:ssZ (UTC DateTime), in accordance with RFC 3339.
Request-ID
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
M
Unique
request identifier, usually in UUID format.
PSU-IP-Address
String [50]
O
Customer’s
IP address. This value must be in IPv4 or IPv6 format.
PSU-User-Agent
String [200]
O
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
PSU-Device-OS
String [100]
O
Operating
system on the customer’s device (computer, mobile device, etc.).
Provider-ID
String [8]
M
Bank
identifier as specified in section 1.
TPP-ID
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
M
TPP
identifier as specified in section 1.
Client-ID
String [50]
O
Client_id
value as specified in section 1.
JWS-Signature
String
M
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
- Request Body:
Level 1
Data type
Req.
Description
paymentId
String [35]
M
Unique
transaction identifier issued by the Bank to the TPP via the API for payment
initiation in section 4.1.
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
String [36]
C
Value
generated by the Bank after successful authorization via the Bank’s
application in the Decoupled flow.
- Response Header:
Parameter
Data type
Req.
Description
Content-Type
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
M
Default:
“application/json”
Request-ID
String
M
Value
taken from the request header in the TPP’s API request.
Request-DateTime
String
M
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
JWS-Signature
String
M
JWS
signature as specified in section 1.
- Response Body:
+ HTTP
STATUS CODE 200 OK:
Level 1
Data type
Req.
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
paymentId
String [35]
M
Unique
transaction identifier issued by the Bank to the TPP via the API for payment
initiation in section 4.1.
status
String [4]
M
Transaction
status code under ISO 20022.
statusDateTime
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
M
-
Status update time.
-
Format: yyyy-MM-ddTHH:mm:ssZ (UTC DateTime), in accordance with RFC 3339.
+
Error Code: Refer to section 7.2.1 - Error
response format, and section 7.2.2 - Common error codes.
4.6. API for querying transaction status
Endpoint
/v1/payments/status
Method
POST
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
PIS
- Request Header:
Parameter
Data type
Req.
Description
Content-Type
String
M
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
Authorization
String
M
-
Authorization format: “Bearer + {access_token}”, in accordance with RFC 6750.
-
The access_token is issued in accordance with section 4.4 of RFC 6749 (with
grant_type set to client_credentials).
Request-DateTime
DateTime
M
-
Request date and time.
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
Request-ID
String [60]
M
Unique
request identifier, usually in UUID format.
PSU-IP-Address
String [50]
O
Customer’s
IP address. This value must be in IPv4 or IPv6 format.
PSU-User-Agent
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
O
Browser
information if the customer uses the TPP’s website, or relevant information
if the customer uses another TPP application.
PSU-Device-OS
String [100]
O
Operating
system on the customer’s device (computer, mobile device, etc.).
Provider-ID
String [8]
M
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
TPP-ID
String [15]
M
TPP
identifier as specified in section 1.
Client-ID
String [50]
O
Client_id
value as specified in section 1.
JWS-Signature
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
M
JWS
signature as specified in section 1.
- Request Body:
Level 1
Data type
Req.
Description
paymentId
String [35]
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
Unique
transaction identifier issued by the Bank to the TPP via the API for payment
initiation in section 4.1.
- Response Header:
Parameter
Type
Req.
Description
Content-Type
String
M
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
Request-ID
String
M
Value
taken from the request header in the TPP’s API request.
Request-DateTime
String
M
Value
taken from the request header in the TPP’s API request.
JWS-Signature
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
M
JWS
signature as specified in section 1.
- Response Body:
+ HTTP
STATUS CODE 200 OK:
Level 1
Data type
Req.
Description
paymentId
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
M
Unique
transaction identifier issued by the Bank to the TPP via the API payment
initiation in section 4.1.
status
String [4]
M
Transaction
status code under ISO 20022.
statusDateTime
DateTime
M
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
-
Format: yyyy-MM-ddTHH:mm:ssZ (UTC DateTime), in accordance with RFC 3339.
+
Error Code: Refer to section 7.2.1 -
Error response format, and section 7.2.2 - Error codes.
4.7. API retrieving customer payment authorization status —
Decoupled flow
The
TPP calls this API of the Bank to query the customer’s payment authorization
status as specified below:
Endpoint
/v1/get-consent
Method
POST
Scope
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
- Request Header:
Parameter
Data type
Req.
Description
Content-Type
String
M
Default:
“application/json”
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
String
M
-
Authorization format: “Bearer + {access_token}”, in accordance with RFC 6750.
-
The access_token is issued in accordance with section 4.4 of RFC 6749 (with
grant_type set to client_credentials).
Request-DateTime
DateTime
M
-
Request date and time.
-
Format: yyyy-MM- ddTHH:mm:ssZ (UTC DateTime), in accordance with RFC 3339.
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
String [60]
M
Unique
request identifier, usually in UUID format.
PSU-IP-Address
String [50]
O
Customer’s
IP address. This value must be in IPv4 or IPv6 format.
PSU-User-Agent
String [200]
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
Browser
information if the customer uses the TPP’s website, or relevant information
if the customer uses another TPP application.
PSU-Device-OS
String [100]
O
Operating
system on the customer’s device (computer, mobile device, etc.).
Provider-ID
String [8]
M
Bank
identifier as specified in section 1.
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
String [15]
M
TPP
identifier as specified in section 1.
Client-ID
String [50]
O
Client_id
value as specified in section 1.
JWS-Signature
String
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
JWS
signature as specified in section 1.
- Request Body:
Level 1
Data type
Req.
Description
paymentId
String [35]
M
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
- Response Header:
Parameter
Data type
Req.
Description
Content-Type
String
M
Default:
“application/json”
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
String
M
Value
taken from the request header in the TPP’s API request.
Request-DateTime
String
M
Value
taken from the request header in the TPP’s API request.
JWS-Signature
String
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
JWS
signature as specified in section 1.
- Response Body:
+ HTTP
STATUS CODE 200 OK:
Level 1
Data type
Req.
Description
paymentId
String [35]
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
Unique
transaction identifier issued by the Bank to the TPP via API for payment
initiation in section 4.1.
consentId
String [36]
M
Value
generated by the Bank after successful authorization via the Bank’s
application in the Decoupled flow.
consentStatus
String [20]
M
Takes
one of the following values:
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
-
“REJECTED” when the customer’s authorization does not comply with the Bank’s
requirements.
-
“CANCEL” when the customer does not authorize the transaction via the Bank’s
application.
expireIn
Number
M
Validity
period of the consentId as specified in section 1.
+
Error Code: Refer to section 7.2.1 -
Error response format, and section 7.2.2 - Error codes.
5. Open APIs for e-wallet cash-in (point c, clause 1, Article
6)
- The APIs for e-wallet cash-in flow are used after the
customer has linked the e-wallet in accordance with applicable requirements.
The customer may deposit money to the e-wallet from the linked account via the
TPP application.
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
Figure 5: E-wallet cash-in flow (EWLTS)
- Flow description:
+ Step
1: After logging in to the TPP application, the customer requests an e-wallet cash-in.
+ Step
2: The TPP requests an access_token from the Bank’s authorization server
under OAuth 2.0 with grant_type set to client_credentials
(refer to section 4.4 of RFC 6749 for details).
+ Step
2.1. The Bank’s authorization server validates the request and returns an access_token
to the TPP.
+ Step
3: The TPP sends an e-wallet cash-in initiation request to the Bank’s system via
the “API for e-wallet cash-in” in section 5.1.
+ Step
3.1. The Bank’s system validates the information in the TPP’s request. If the
information is valid, it returns a unique transaction identifier (paymentId)
to the TPP.
E-wallet
cash-in transactions shall be authenticated in accordance with regulations of
the Governor of the State Bank of Vietnam on safety and security in the
provision of online banking services. Where OTP or Decoupled authentication is
used for an e-wallet cash-in, the following procedures shall apply:
For
the OTP flow (steps 4 to 4.2.2):
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
+ Step
4.1: The customer enters the OTP in the TPP application.
+ Step
4.2: The TPP sends an OTP verification request to the Bank’s system via the “API
for OTP verification” in section 5.2.
+ Step
4.2.1: The Bank’s system validates the information in the TPP’s request.
+ Step
4.2.2: The Bank’s system returns the result to the TPP.
For
the Decoupled flow (steps 4’ to 4.3.1’):
+ Step
4’: Depending on the design of the TPP application and the Bank’s system, the
Bank’s authorization server may or may not notify the customer that an e-wallet
cash-in requires authorization.
+ Step
4.1’: The customer opens the Bank’s application.
+ Step
4.1.1’: The customer confirms the e-wallet cash-in information.
+ Step
4.1.2’: The customer authorizes the e-wallet cash-in using the Bank’s
authentication methods in accordance with the regulations on safety and
security in the provision of online banking services.
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
+ Step
4.2.1’: The TPP receives the status and returns a response to the Bank’s system
as prescribed in section 5.3.
+ Step
4.3’: If the TPP does not receive the customer’s e-wallet cash-in authorization
status from the Bank’s system via the “API for updating customer e-wallet
cash-in authorization status — Decoupled flow” in section 5.3, it
may request that status from the Bank’s system through the “API for querying
customer e-wallet cash-in authorization status — Decoupled flow” in section
5.4.
+ Step
4.3.1’: The Bank’s system receives the request and returns the result to the
TPP.
+ Step
5: The TPP sends an e-wallet cash-in confirmation request to the Bank via the “API
for e-wallet cash-in confirmation” in section 5.5.
+ Step
5.1. The Bank returns the transaction status to the TPP.
+ Step
6: If the TPP does not receive the posting result from the Bank, it requests
the transaction status from the Bank’s system via the “API for querying
transaction status” in section 5.6.
+ Step
6.1: The Bank’s system receives the request and returns the result to the TPP.
+ Step
7. The TPP displays the e-wallet cash-in result to the customer.
5.1. API for e-wallet cash-in
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
/v1/cash-in
Method
POST
Scope
EWLTS
- Request Header:
Parameter
Data type
Req.
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
Content-Type
String
M
Default:
“application/json”
Authorization
String
M
-
Authorization format: “Bearer + {access_token}”, in accordance with RFC 6750.
-
The access_token is issued in accordance with section 4.4 of RFC 6749 (with
grant_type set to client_credentials).
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
DateTime
M
-
Request date and time.
-
Format: yyyy-MM-ddTHH:mm:ssZ (UTC DateTime), in accordance with RFC 3339.
Request-ID
String [60]
M
Unique
request identifier, usually in UUID format.
PSU-IP-Address
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
O
Customer’s
IP address. This value must be in IPv4 or IPv6 format.
PSU-User-Agent
String [200]
O
Browser
information if the customer uses the TPP’s website, or relevant information if
the customer uses another TPP application.
PSU-Device-OS
String [100]
O
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
Provider-ID
String [8]
M
Bank
identifier as specified in section 1.
TPP-ID
String [15]
M
TPP
identifier as specified in section 1.
Client-ID
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
O
Client_id
value as specified in section 1.
JWS-Signature
String
M
JWS
signature as specified in section 1.
- Request Body:
Level 1
Level 2
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
Req.
Description
instructionIdentification
String [50]
M
Transaction
identifier generated by the TPP
remittanceInformation
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
M
Transaction
details
instructedAmount
Object
M
Transaction
amount information
value
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
M
Transaction
amount
currency
String [3]
M
Currency
expressed as a three-letter uppercase in accordance with ISO 4217.
requestedExecutionDate
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
M
-
Transaction execution date.
-
Format: yyyy-MM-ddTHH:mm:ssZ (UTC DateTime), in accordance with RFC 3339.
ewalletToken
String [30]
M
Token
generated when the e-wallet is linked between the TPP and the Bank.
additionalInfo
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
Object
O
Additional
information (if any).
- Response Header:
Parameter
Req.
Type
Description
Content-Type
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
String
Default:
“application/json”
Request-ID
M
String
Value
taken from the request header in the TPP’s API request.
Request-DateTime
M
String
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
JWS-Signature
M
String
JWS
signature as specified in section 1.
- Response Body:
+ HTTP
STATUS CODE 200 OK:
Level 1
Data type
Req.
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
paymentId
String [35]
M
Unique
transaction identifier assigned by the Bank.
status
String [4]
M
Transaction
status code under ISO 20022.
statusDateTime
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
M
-
Status update time.
-
Format: yyyy-MM-ddTHH:mm:ssZ (UTC DateTime), in accordance with RFC 3339.
authenType
String [10]
M
Takes
one of the following values:
-
“OTP”: use the OTP flow.
-
“DECOUPLED”: use the Decoupled flow.
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
additionalInfo
Object
O
Additional
information (if any)
+
Error Code: Refer to section 7.2.1 -
Error response format, and section 7.2.2 - Error codes.
5.2. API for OTP verification
Endpoint
/v1/verify-otp-cash-in
Method
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
Scope
EWLTS
- Request Header:
Parameter
Data type
Req.
Description
Content-Type
String
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
Default:
“application/json”
Authorization
String
M
-
Authorization format: “Bearer + {access_token}”, in accordance with RFC 6750.
-
The access_token is issued in accordance with section 4.4 of RFC 6749 (with
grant_type set to client_credentials).
Request-
DateTime
DateTime
M
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
-
Format: yyyy-MM-ddTHH:mm:ssZ (UTC DateTime), in accordance with RFC 3339.
Request-ID
String [60]
M
Unique
request identifier, usually in UUID format.
PSU-IP-Address
String [50]
O
Customer’s
IP address. This value must be in IPv4 or IPv6 format.
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
String [200]
O
Browser
information if the customer uses the TPP’s website, or relevant information
if the customer uses another TPP application.
PSU-Device-OS
String [100]
O
Operating
system on the customer’s device (computer, mobile device, etc.).
Provider-ID
String [8]
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
Bank
identifier as specified in section 1.
TPP-ID
String [15]
M
TPP
identifier specified in section 1.
Client-ID
String [50]
O
Client_id
value as specified in section 1.
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
String
M
JWS
signature as specified in section 1.
- Request Body:
Level 1
Data type
Req.
Description
paymentId
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
M
Unique
transaction identifier returned by the Bank via the API for e-wallet cash-in
in section 5.1.
otp
String [6]
M
OTP
sent by the Bank to the customer.
ewalletToken
String [30]
M
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
additionalInfo
Object
O
Additional
information (if any).
- Response Header:
Parameter
Data type
Req.
Description
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
String
M
Default:
“application/json”
Request-ID
String
M
Value
taken from the request header in the TPP’s API request.
Request-DateTime
String
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
Value
taken from the request header in the TPP’s API request.
JWS-Signature
String
M
JWS
signature as specified in section 1.
- Response Body:
+ HTTP
STATUS CODE 200 OK:
Level 1
Data type
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
Description
paymentId
String [35]
M
Unique
transaction identifier issued by the Bank to the TPP via the API for e-wallet
cash-in in section 5.1.
consentId
String [36]
M
Value
generated by the Bank after successful OTP verification in the OTP flow.
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
Number
M
Validity
period of the consentId as specified in section 1.
+
Error Code: Refer to section 7.2.1 - Error
response format, and section 7.2.2 - Error codes.
5.3. API for updating customer e-wallet cash-in authorization
status — Decoupled flow
The
Bank calls this API of the TPP to return the customer’s e-wallet cash-in
authorization status as specified below:
Endpoint
/v1/update-consent-cash-in
Method
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
-
Request Header:
Parameter
Data type
Req.
Description
Content-Type
String
M
Default:
“application/json”
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
String
M
-
Authorization format: “Bearer + {access_token}”, in accordance with RFC 6750.
-
The access_token is issued in accordance with section 4.4 of RFC 6749 (with
grant_type set to client_credentials).
Request-DateTime
DateTime
M
-
Request date and time.
-
Format: yyyy-MM- ddTHH:mm:ssZ (UTC DateTime), in accordance with RFC 3339.
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
String [60]
M
Unique
request identifier, usually in UUID format.
Provider-ID
String [8]
M
Bank
identifier as specified in section 1.
JWS-Signature
String
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
JWS
signature as specified in section 1.
- Request Body:
Level 1
Data type
Req.
Description
paymentId
String
[35]
M
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
consentId
String
[36]
M
Value
generated by the Bank after successful authorization via the Bank’s
application in the Decoupled flow.
consentStatus
String
[20]
M
Takes
one of the following values:
-
“AUTHORISED” when the customer is successfully authenticated.
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
-
“CANCEL” when the customer does not authorize the transaction via the Bank’s
application.
ewalletToken
String
[30]
M
Token
generated when the e-wallet is linked between the TPP and the Bank.
expireIn
Number
M
Validity
period of the consentId as specified in section 1.
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
Parameter
Data type
Req.
Description
Content-Type
String
M
Default:
“application/json”
Request-ID
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
M
Value
taken from the request header in the TPP’s API request.
Request-DateTime
String
M
Value
taken from the request header in the TPP’s API request.
JWS-Signature
String
M
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
-
Response Body:
+ HTTP
STATUS CODE 200 OK:
Level 1
Data type
Req.
Description
message
String [20]
M
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
+
Error Code: As specified by the
TPP.
5.4. API for querying customer e-wallet cash-in authorization
status — Decoupled flow
The
TPP calls this API of the Bank to query the customer’s e-wallet cash-in
authorization status as specified below:
Endpoint
/v1/get-consent-cash-in
Method
POST
Scope
EWLTS
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
Parameter
Data type
Req.
Description
Content-Type
String
M
Default:
“application/json”
Authorization
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
M
-
Authorization format: “Bearer + {access_token}”, in accordance with RFC 6750.
-
The access_token is issued in accordance with section 4.4 of RFC 6749 (with grant_type
set to client_credentials).
Request-DateTime
DateTime
M
-
Request date and time.
-
Format: yyyy-MM- ddTHH:mm:ssZ (UTC DateTime), in accordance with RFC 3339.
Request-ID
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
M
Unique
request identifier, usually in UUID format.
PSU-IP-Address
String [50]
O
Customer’s
IP address. This value must be in IPv4 or IPv6 format.
PSU-User-Agent
String [200]
O
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
PSU-Device-OS
String [100]
O
Operating
system on the customer’s device (computer, mobile device, etc.).
Provider-ID
String [8]
M
Bank
identifier as specified in section 1.
TPP-ID
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
M
TPP
identifier as specified in section 1.
Client-ID
String [50]
O
Client_id
value as specified in section 1.
JWS-Signature
String
M
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
- Request Body:
Level 1
Data type
Req.
Description
paymentId
String [35]
M
Unique
transaction identifier issued by the Bank to the TPP via the API for e-wallet
cash-in in section 5.1.
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
String [30]
M
Token
generated when the e-wallet is linked between the TPP and the Bank.
- Response Header:
Parameter
Data type
Req.
Description
Content-Type
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
M
Default:
“application/json”
Request-ID
String
M
Value
taken from the request header in the TPP’s API request.
Request-DateTime
String
M
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
JWS-Signature
String
M
JWS
signature as specified in section 1.
- Response Body:
+ HTTP
STATUS CODE 200 OK:
Level 1
Data type
Req.
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
paymentId
String [35]
M
Unique
transaction identifier issued by the Bank to the TPP via the API for e-wallet
cash-in in section 5.1.
consentId
String [36]
M
-
Value generated by the Bank after successful authorization via the Bank’s
application.
consentStatus
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
M
Takes
one of the following values:
-
“AUTHORISED” when the customer successfully authorizes the transaction.
-
“REJECTED” when the customer’s authorization does not comply with the Bank’s
requirements.
-
“CANCEL” when the customer does not authorize the transaction through the
Bank’s application.
expireIn
Number
M
Validity
period of the consentId as specified in section 1.
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
String [30]
M
Token
generated when the e-wallet is linked between the TPP and the Bank.
+
Error Code: Refer to section 7.2.1 -
Error response format, and section 7.2.2 - Error codes.
5.5. API for e-wallet cash-in confirmation
Endpoint
/v1/submit-cash-in
Method
POST
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
EWLTS
- Request Header:
Parameter
Data type
Req.
Description
Content-Type
String
M
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
Authorization
String
M
-
Authorization format: “Bearer + {access_token}”, in accordance with RFC 6750.
-
The access_token is issued in accordance with section 4.4 of RFC 6749 (with
grant_type set to client_credentials).
Request-DateTime
DateTime
M
-
Request date and time.
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
Request-ID
String [60]
M
Unique
request identifier, usually in UUID format.
PSU-IP-Address
String [50]
O
Customer’s
IP address. This value must be in IPv4 or IPv6 format.
PSU-User-Agent
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
O
Browser
information if the customer uses the TPP’s website, or relevant information
if the customer uses another TPP application.
PSU-Device-OS
String [100]
O
Operating
system on the customer’s device (computer, mobile device, etc.).
Provider-ID
String [8]
M
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
TPP-ID
String [15]
M
TPP
identifier as specified in section 1.
Client-ID
String [50]
O
Client_id
value as specified in section 1.
JWS-Signature
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
M
JWS
signature as specified in section 1.
- Request Body:
Level 1
Data type
Req.
Description
paymentId
String [35]
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
Unique
transaction identifier issued by the Bank to the TPP via the API for e-wallet
cash-in in section 5.1.
consentId
String [36]
C
Value
generated by the Bank after successful authorization via the Bank’s
application in the Decoupled flow, or successful OTP verification in the OTP
flow.
ewalletToken
String [30]
M
Token
generated when the e-wallet is linked between the TPP and the Bank.
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
Parameter
Data type
Req.
Description
Content-Type
String
M
Default:
“application/json”
Request-ID
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
M
Value
taken from the request header in the TPP’s API request.
Request-DateTime
String
M
Value
taken from the request header in the TPP’s API request.
JWS-Signature
String
M
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
- Response Body:
+ HTTP
STATUS CODE 200 OK:
Level 1
Data type
Req.
Description
paymentId
String [35]
M
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
status
String [4]
M
Transaction
status code under ISO 20022.
statusDateTime
DateTime
M
-
Status update time.
-
Format: yyyy-MM-ddTHH:mm:ssZ (UTC DateTime), in accordance with RFC 3339.
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
5.6. API for querying transaction status
Endpoint
/v1/get-status-cash-in
Method
POST
Scope
EWLTS
- Request Header:
Parameter
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
Req.
Description
Content-Type
String
M
Default:
“application/json”
Authorization
String
M
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
-
The access_token is issued in accordance with section 4.4 of RFC 6749 (with
grant_type set to client_credentials).
Request-DateTime
DateTime
M
-
Request date and time.
-
Format: yyyy-MM- ddTHH:mm:ssZ (UTC DateTime), in accordance with RFC 3339.
Request-ID
String [60]
M
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
PSU-IP-Address
String [50]
O
Customer’s
IP address. This value must be in IPv4 or IPv6 format.
PSU-User-Agent
String [200]
O
Browser
information if the customer uses the TPP’s website, or relevant information
if the customer uses another TPP application.
PSU-Device-OS
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
O
Operating
system on the customer’s device (computer, mobile device, etc.).
Provider-ID
String [8]
M
Bank
identifier as specified in section 1.
TPP-ID
String [15]
M
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
Client-ID
String [50]
O
Client_id
value as specified in section 1.
JWS-Signature
String
M
JWS
signature as specified in section 1.
- Request Body:
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
Data type
Req.
Description
paymentId
String
[35]
M
Unique
transaction identifier issued by the Bank to the TPP via the API for e-wallet
cash-in in section 5.1.
ewalletToken
String
[30]
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
Token
generated when the e-wallet is linked between the TPP and the Bank.
- Response Header:
Parameter
Type
Req.
Description
Content-Type
String
M
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
Request-ID
String
M
Value
taken from the request header in the TPP’s API request.
Request-DateTime
String
M
Value
taken from the request header in the TPP’s API request.
JWS-Signature
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
M
JWS
signature as specified in section 1.
- Response Body:
+ HTTP
STATUS CODE 200 OK:
Level 1
Data type
Req.
Description
paymentId
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
M
Unique
transaction identifier issued by the Bank to the TPP via the API for e-wallet
cash-in in section 5.1.
status
String [4]
M
Transaction
status code under ISO 20022.
statusDateTime
DateTime
M
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
-
Format: yyyy-MM-ddTHH:mm:ssZ (UTC DateTime), in accordance with RFC 3339.
+
Error Code: Refer to section 7.2.1 -
Error response format, and section 7.2.2 - Error codes.
6. Open API for e-wallet cash-out (point c, clause 1, Article
6)
- API
for e-wallet cash-out flow:
Figure 6: E-wallet cash-out flow (EWLTS)
- Flow
description:
+ Step
1: After logging in to the TPP application, the customer requests an e-wallet cash-out.
+ Step
2: The TPP requests an access_token from the Bank’s authorization server
under OAuth 2.0 with grant_type set to client_credentials
(refer to section 4.4 of RFC 6749 for details).
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
+ Step
3: The TPP sends an e-wallet cash-out request to the Bank via the API described
below.
+ Step
3.1. The Bank’s system returns the result to the TPP.
+ Step
3.2. The TPP application displays the result to the customer.
Endpoint
/v1/cash-out
Method
POST
Scope
EWLTS
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
Parameter
Data type
Req.
Description
Content-Type
String
M
Default:
“application/json”
Authorization
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
M
-
Authorization format: “Bearer + {access_token}”, in accordance with RFC 6750.
-
The access_token is issued in accordance with section 4.4 of RFC 6749 (with
grant_type set to client_credentials).
Request-DateTime
DateTime
M
-
Request date and time.
-
Format: yyyy-MM-ddTHH:mm:ssZ (UTC DateTime), in accordance with RFC 3339.
Request-ID
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
M
Unique
request identifier, usually in UUID format.
PSU-IP-Address
String [50]
O
Customer’s
IP address. This value must be in IPv4 or IPv6 format.
PSU-User-Agent
String [200]
O
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
PSU-Device-OS
String [100]
O
Operating
system on the customer’s device (computer, mobile device, etc.).
Provider-ID
String [8]
M
Bank
identifier as specified in section 1.
TPP-ID
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
M
TPP
identifier as specified in section 1.
Client-ID
String [50]
O
Client_id
value as specified in section 1.
JWS-Signature
String
M
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
-
Request Body:
Level 1
Level 2
Data type
Req.
Description
instructionIdentification
String [50]
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
Transaction
identifier generated by the TPP
remittanceInformation
String [255]
M
Transaction
details
instructedAmount
Object
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
Transaction
amount information
value
Number
M
Transaction
amount
currency
String [3]
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
Currency
expressed as a three-letter uppercase in accordance with ISO 4217.
requestedExecutionDate
DateTime
M
-
Transaction execution date.
-
Format: yyyy-MM-ddTHH:mm:ssZ (UTC DateTime), in accordance with RFC 3339.
ewalletToken
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
M
Token
generated when the e-wallet is linked between the TPP and the Bank.
additionalInfo
Object
O
Additional
information (if any)
- Response Header:
Parameter
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
Req.
Description
Content-Type
String
M
Default:
“application/json”
Request-ID
String
M
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
Request-DateTime
String
M
Value
taken from the request header in the TPP’s API request.
JWS-Signature
String
M
JWS
signature as specified in section 1.
- Response Body:
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
Level 1
Data type
Req.
Description
status
String [4]
M
Transaction
status code under ISO 20022.
statusDateTime
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
M
-
Status update time.
-
Format: yyyy-MM-ddTHH:mm:ssZ (UTC DateTime), in accordance with RFC 3339.
+
Error Code: Refer to section 7.2.1 -
Error response format, and section 7.2.2 - Common error codes.
7. Error codes
7.1. Error codes for the customer token grant flow
7.1.1. Error codes for the API for authentication and
obtaining consent of customers
If
“redirect_uri” is missing or does not match the URL registered by the TPP with
the Bank, the Bank shall redirect the customer to an error page that clearly
explains the error.
For
errors such as the customer’s refusal to grant consent, or other errors
unrelated to “redirect_uri”, the Bank shall notify the TPP by adding the values
and parameters in the table below to “redirect_uri”:
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
Data type
Req.
Description
error
String
M
Error
code returned by the system. The applicable OAuth 2.0 error codes are listed
in the error code table.
error_description
String
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
Additional
information to help the TPP understand the error.
state
String
M
Value
from the TPP’s request.
Error
code table:
No.
Parameter
Description
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
INVALID_REQUEST
The
request is missing a required parameter, or contains an invalid or malformed
parameter.
2
UNAUTHORIZED_CLIENT
The
TPP is not authorized to request an authorization code using this method.
3
ACCESS_DENIED
The
resource owner or authorization server denied the request.
4
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
The
authorization server does not support obtaining an authorization code using
this method.
5
INVALID_SCOPE
The
requested scope is invalid, unknown or malformed.
6
SERVER_ERROR
The
authorization server encountered an unexpected condition that prevented it
from fulfilling the request.
7
TEMPORARILY_UNAVAILABLE
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
7.1.2. Error codes for the API for querying access token
The
authorization server returns HTTP error code 400 (Bad Request) to the TPP,
together with the error details below based on section 5.2 - “Error
Response” of RFC 6749:
Error
code format:
Parameter
Req.
Explanation
error
M
Error
code returned by the system. The applicable OAuth 2.0 error codes are listed
in the error code table.
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
O
Additional
information to help the TPP understand the error.
error_uri
O
URI
identifying a human-readable web page containing information about the error,
used to provide further details.
Error
code table:
HTTP CODE
Error code (Error)
Description
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
INVALID_REQUEST
The
request is missing a required parameter, or contains an invalid or malformed
parameter.
400
INVALID_CLIENT
Client
authentication failed.
400
UNAUTHORIZED_CLIENT
The
TPP is not authorized to use this grant type.
400
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
The
requested scope is invalid, unknown or malformed.
400
UNSUPPORTED_GRANT_TYPE
The
grant type is not supported by the server.
7.2. Error codes for other APIs in this Appendix
7.2.1. Error response format
If an
error occurs, the Bank’s system shall return a response body containing the
information specified in the table below:
Parameter
Data type
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
Description
code
String
M
Error
code and HTTP status code as specified in section 7.2.2 - Common error codes.
description
String
M
Additional
details about the error
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
HTTP CODE
CODE
DESCRIPTION
400
ACCOUNT_ID_REQUIRED
The
accountId field must not be empty.
400
ACCOUNT_NOT_EXISTED
The
account does not exist.
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
CONSENTID_NOT_EXISTED
The
consentId does not exist.
400
CREDITOR_ACCOUNTID_
REQUIRED
The
creditor accountId field must not be empty.
400
CREDITOR_ACCOUNTID_
NOT_EXISTED
The
creditor accountId does not exist.
400
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
The
creditor bankCode field must not be empty.
400
CREDITOR_NAME_REQUIRED
The
creditor name field must not be empty.
400
DEBTOR_ACCOUNTID_NOT_
EXISTED
The
debtor accountId does not exist.
400
DEBTOR_ACCOUNTID_
REQUIRED
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
400
DEBTOR_NAME_REQUIRED
The
debtor name field must not be empty.
400
EWALLETTOKEN_
REQUIRED
The
ewalletToken field must not be empty.
400
EWALLETTOKEN_NOT_
EXISTED
The
ewalletToken does not exist.
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
EXPIRE_CONSENTID
The
consentId has expired.
400
FROMDATE_INVALID
The
fromDate field is invalid.
400
FROMDATE_REQUIRED
The
fromDate field must not be empty.
400
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
The
instructedAmount currency field is invalid.
400
INSTRUCTED_AMOUNT_
CURRENCY_REQUIRED
The
instructedAmount currency field must not be empty.
400
INSTRUCTED_AMOUNT_
VALUE_REQUIRED
The
instructedAmount value field must not be empty.
400
INSTRUCTION_IDENTIFICAT
ION_REQUIRED
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
400
JWS_SIGNATURE_REQUIRED
The
JWS-Signature field must not be empty.
400
PAGE_INVALID
The
page field is invalid.
400
PAYMENTID_REQUIRED
The
paymentId field must not be empty.
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
PAYMENTID_NOT_EXISTED
The
paymentId does not exist.
400
PROVIDER_ID_REQUIRED
The
Provider-ID field must not be empty.
400
PSU_IP_ADDRESS_INVALID
The
PSU-IP-Address field is invalid (if provided).
400
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
The
remittanceInformation field must not be empty.
400
REQUEST_DATETIME_
REQUIRED
The
Request-DateTime field must not be empty.
400
REQUEST_ID_REQUIRED
The
Request-ID field must not be empty.
400
REQUESTED_EXECUTIONDA
TE_REQUIRED
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
400
SIZE_INVALID
The
size field is invalid.
400
TODATE_INVALID
The
toDate field is invalid.
400
TODATE_REQUIRED
The
toDate field must not be empty.
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
TPP_ID_REQUIRED
The
TPP-ID field must not be empty.
400
TPP_UNVERIFIED
The
TPP has not been authenticated.
400
OTHER
Other
errors related to API requests from the TPP as described by the Bank.
401
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
The
OAuth 2 token has expired.
401
JWS_SIGNATURE_
UNVERIFIED
JWS-Signature
verification failed.
403
FORBIDDEN
A
valid OAuth token was received, but access was denied.
405
WRONG_METHOD
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
500
INTERNAL_ERROR
The
server encountered an unexpected condition that prevented it from fulfilling
the request.
502
BAD_GATEWAY
The
server received an invalid response from the upstream server.
504
GATEWAY_TIMEOUT
The
server did not receive a response from the upstream server to complete the
request.
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
OTHER
Other
errors related to the server processing the API request as described by the
Bank.
APPENDIX 02
TECHNICAL STANDARDS FOR DEPLOYMENT OF OPEN APIs IN THE
BANKING SECTOR
(Attached with Circular No. 64/2024/TT-NHNN dated December 31, 2024 of the
Governor of the State Bank of Vietnam)
No.
Standard category
Standard identifier
Full name of standard
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
1
Architecture
standards
1.1
Data
exchange
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
REpresentational
State Transfer
Mandatory
SOAP
Simple
Object Access Protocol
Recommended for the Bank’s other APIs.
1.2
Data
exchange format
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
JSON
JavaScript
Object Notation
Mandatory
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
eXtensible
Markup Language
Recommended for the Bank’s other APIs.
2
Data
standards
Data format
ISO 20022
International Organization for Standardization 20022
Use of one of these
standards is recommended for the Bank’s other APIs.
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
International Organization for Standardization 8583
OFX
Open Financial Exchange
ISO 4217
International Organization for Standardization 4217
Mandatory
RFC
3339
Date
and Time on the Internet: Timestamps
Mandatory
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
Information
security standards
3.1
Customer authentication and consent solution
RFC 6749
The OAuth 2.0 Authorization Framework
- Compliance with RFC 6749,
RFC 6750 and RFC 7636 is mandatory.
- RFC 6749 and RFC 6750 may
be combined with RFC 7636 and OIDC, depending on the use case.
RFC 6750
The OAuth 2.0 Authorization Framework: Bearer Token Usage
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
Proof Key for Code Exchange by OAuth Public Clients
RFC 7009
OAuth 2.0 Token Revocation
OIDC
OpenID Connect
SAML
v2.0
Security
Assertion Markup Language version 2.0
Recommended for the Bank’s other APIs.
3.2
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
HTTPS
HyperText Transfer Protocol Secure
Mandatory
TLS
v1.2 or later
Transport
Layer Security version 1.2+
Mandatory
3.3
Encryption algorithms
TCVN 7816:2007
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
Recommended
PKCS #1
RSA Cryptography Standard
Recommended
Use version 2.1 or later and
the RSAES-OAEP encryption scheme. Minimum key length: 2048 bits.
ECC
Elliptic Curve Cryptography
Recommended. Minimum key
length: 256 bits.
JWE
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
Compliance with RFC 7516 is
recommended.
TCVN
11367- 2:2016
Information
technology — Security techniques — Cryptographic algorithms — Part 2:
Asymmetric ciphers.
Recommended
3.4
Electronic signatures
JWS
JSON Web Signature
Mandatory requirements:
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
- Minimum key length: 2048
bits for RSA and 256 bits for ECDSA.
PKCS #1
RSA Cryptography Standard
Use of one of these
standards is recommended.
- For RSA:
+ Version 2.1 or later.
+ Minimum key length: 2048
bits.
- For ECDSA:
Minimum key length: 256
bits.
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
Elliptic Curve Digital Signature Algorithm
TCVN
7635:2007
Cryptographic
techniques — Digital signatures
3.5
Hash algorithms for digital signatures
FIPS PUB 180-4
Secure Hash Standard
Use of one of the following
hash functions is recommended: SHA2-56, SHA-384, SHA-512, SHA-512/256,
SHA3-256, SHA3-384, SHA3-512, SHAKE128, SHAKE256.
FIPS
PUB 202
...
...
...
Hãy đăng nhập hoặc đăng ký Thành viên
Pro tại đây để xem toàn bộ văn bản tiếng Anh.
3.6
Information system security
ISO27001:2022
International Organization for Standardization 27001:2022
Use of one of these two
standards is mandatory.
TCVN
11930:2017
Information
technology — Security techniques — Baseline information system security
requirements by security level