Thông tư 64/2024/TT-NHNN của Ngân hàng Nhà nước Việt Nam quy định về triển khai giao diện lập trình ứng dụng mở trong ngành Ngân hàng

NGÂN HÀNG NHÀ NƯỚC
VIỆT NAM
^_________

Số: 64/2024/TT-NHNN

CỘNG HÒA XÃ HỘI CHỦ NGHĨA VIỆT NAM
Độc lập - Tự do - Hạnh phúc
^{______________________}

Hà Nội, ngày 31 tháng 12 năm 2024

Nơi nhận:
- Như Điều 16;
- Ban Lãnh đạo NHNN;
- Văn phòng Chính phủ;
- Bộ Tư pháp (để kiểm tra);
- Công báo;
- Cổng TTĐT của NHNN;
- Lưu: VP, PC, CNTT (03 bản).

KT. THỐNG ĐỐC
PHÓ THỐNG ĐỐC




Phạm Tiến Dũng

Tham số

Loại dữ liệu

Bắt buộc

Mô tả

Content-Type

String

M

Mặc định “application/json”

Authorization

String

M

- Authorization định dạng: “Bearer + {access_token}”: theo tiêu chuẩn RFC 6750.

- Mã access_token được cấp theo quy định tại mục 4.4 trong RFC 6749 (với grant_type là client_credentials).

Request-DateTime

DateTime

M

- Ngày giờ thực hiện.
- Định dạng: yyyy-MM-ddTHH:mm:ssZ (UTC DateTime), theo tiêu chuẩn RFC 3339.

Request-ID

String [60]

M

Mã định danh duy nhất cho request, thường ở định dạng UUID.

PSU-IP-Address

String [50]

O

Địa chỉ IP của khách hàng.

Giá trị này phải ở dạng Ipv4 hoặc Ipv6.

PSU-User-Agent

String [200]

O

Thông tin trình duyệt trong trường hợp khách hàng sử dụng ứng dụng web của TPP hoặc các thông tin khác trong trường hợp khách hàng sử dụng ứng dụng khác của TPP.

PSU-Device-OS

String [100]

O

Hệ điều hành trên thiết bị (máy tính/di động,…) của khách hàng.

Provider-ID

String [8]

M

Mã định danh của Ngân hàng được quy định tại Mục 1.

TPP-ID

String [15]

M

Mã định danh của TPP được quy định tại Mục 1.

Client-ID

String [50]

O

Giá trị client_id được nêu tại Mục 1.

Tham số

Loại dữ liệu

Bắt buộc

Mô tả

currency

String [3]

M

Loại tiền tệ quy định theo mã của bộ ISO 4217 với 3 ký tự viết hoa.

Content-Type

String

M

Mặc định “application/json”

Request-ID

String

M

Giá trị được lấy từ request header trong API của TPP

Request-DateTime

String

M

Giá trị được lấy từ request header trong API của TPP

JWS-Signature

String

M

Chữ ký JWS theo quy định tại Mục 1

Mức 1

Mức 2

Loại dữ liệu

Bắt buộc

Mô tả

interests

Array

M

Danh sách lãi suất

currency

String [3]

M

Loại tiền tệ quy định theo mã của bộ ISO 4217 với 3 ký tự viết hoa.

productCode

String [100]

O

Mã loại sản phẩm tiền gửi

productDesc

String [300]

M

Mô tả loại sản phẩm tiền gửi

termCode

String [100]

M

Kỳ hạn gửi

minAmount

Number

M

Số tiền gửi tối thiểu

customerType

String [4]

M

Loại khách hàng theo ISO 20022.

Giá trị mặc định: “PRVT” (Khách hàng cá nhân)

interestRate

String [5]

M

Lãi suất

effectiveDate

Datetime

M

- Ngày hiệu lực.

- Định dạng: yyyy-MM-ddTHH:mm:ssZ (UTC DateTime), theo tiêu chuẩn RFC 3339.

additionalInfo

Object

O

Thông tin bổ sung (nếu có)

Content-Type

String

M

Mặc định “application/json”

Authorization

String

M

- Authorization định dạng: “Bearer + {access_token}”: theo tiêu chuẩn RFC 6750.

- Mã access_token được cấp theo quy định tại mục 4.4 trong RFC 6749 (với grant_type là client_credentials).

Request-DateTime

DateTime

M

- Ngày giờ thực hiện.
- Định dạng: yyyy-MM-ddTHH:mm:ssZ (UTC DateTime), theo tiêu chuẩn RFC 3339.

Request-ID

String [60]

M

Mã định danh duy nhất cho request, thường ở định dạng UUID

PSU-IP-Address

String [50]

O

Địa chỉ IP của khách hàng. Giá trị này phải ở dạng Ipv4 hoặc Ipv6.

PSU-User-Agent

String [200]

O

Thông tin trình duyệt trong trường hợp khách hàng sử dụng ứng dụng web của TPP hoặc các thông tin khác trong trường hợp khách hàng sử dụng ứng dụng khác của TPP.

PSU-Device-OS

String [100]

O

Hệ điều hành trên thiết bị (máy tính/di động,…) của khách hàng.

Provider-ID

String [8]

M

Mã định danh của Ngân hàng được quy định tại Mục 1.

TPP-ID

String [15]

M

Mã định danh của TPP được quy định tại Mục 1.

Client-ID

String [50]

O

Giá trị client_id được nêu tại Mục 1.

Tham số

Loại dữ liệu

Bắt buộc

Mô tả

currency

String [3]

O

Loại tiền tệ quy định theo mã của bộ ISO 4217 với 3 ký tự viết hoa.

Tham số

Loại dữ liệu

Bắt buộc

Mô tả

Content-Type

String

M

Mặc định “application/json”

Request-ID

String

M

Giá trị được lấy từ request header trong API của TPP

Request-DateTime

String

M

Giá trị được lấy từ request header trong API của TPP

JWS-Signature

String

M

Chữ ký JWS theo quy định tại Mục 1

Mức 1

Mức 2

Loại dữ liệu

Bắt buộc

Mô tả

rates

Array

M

Danh sách tỷ giá

currency

String [3]

M

Loại tiền tệ quy định theo mã của bộ ISO 4217 với 3 ký tự viết hoa

buyCashRate

Number

M

Tỉ giá mua vào bằng tiền mặt

buyTransferRate

Number

M

Tỉ giá mua vào bằng chuyển khoản

sellCashRate

Number

M

Tỉ giá bán ra bằng tiền mặt

sellTransferRate

Number

M

Tỉ giá bán ra bằng chuyển khoản

additionalInfo

Object

O

Thông tin bổ sung (nếu có)

applyDate

DateTime

M

- Thời điểm áp dụng tỉ giá trên hệ thống của Ngân hàng.

- Định dạng: yyyy-MM-ddTHH:mm:ssZ (UTC DateTime), theo tiêu chuẩn RFC 3339.

Tham số

Loại dữ liệu

Bắt buộc

Mô tả

Content-Type

String

M

application/x-www-form-urlencoded

Host

String

O

Xác định tên miền của máy chủ mà request đang gửi đến

Tham số

Loại dữ liệu

Bắt buộc

Mô tả

response_type

String

M

Mặc định “code”

client_id

String

M

Giá trị client_id được nêu tại Mục 1.

scope

String

M

Phạm vi truy cập: AIS

redirect_uri

String

M

Đường dẫn dùng để điều hướng khách hàng về ứng dụng của TPP sau khi hệ thống xác nhận của Ngân hàng hoàn thành xác nhận khách hàng.

state

String

M

Giá trị này được TPP tạo ra để duy trì trạng thái giữa request và respone, được sử dụng để ngăn chặn các cuộc tấn công trong lĩnh vực bảo mật web (Cross-site request forgery)

code_challenge

String

M

code_challenge = BASE64URL-ENCODE(SHA256(ASCII(code_verifier)))

Chi tiết tham khảo thêm tại RFC 7636

code_challenge

_method

String

O

Thuật toán được sử dụng để tạo ra code_challenge.

Mặc định “S256”

Tham số

Loại dữ liệu

Bắt buộc

Mô tả

code

String

M

Mã đồng ý

state

String

M

Giá trị state từ request của TPP.

Tham số

Loại dữ liệu

Bắt buộc

Mô tả

Content-Type

String

M

application/x-www-form-urlencoded

Authorization

String

M

Basic BASE64(client_id + “:” + client_secret)

Host

String

O

Xác định tên miền của máy chủ mà request đang gửi đến

Tham số

Loại dữ liệu

Bắt buộc

Mô tả

grant_type

String

M

Mặc định “authorization_code”

code

String

M

Mã đồng ý mà Ngân hàng đã cấp cho TPP thông qua luồng lấy mã truy cập.

redirect_uri

String

M

Đường dẫn dùng để điều hướng khách hàng trở lại ứng dụng của TPP. Giá trị này phải khớp với giá trị redirect_uri đã truyền tại API Xác nhận và lấy sự đồng ý của khách hàng mục 3.1.

code_verifier

String

M

Giá trị code_verifier được sử dụng để tạo ra code_challenge mà TPP đã truyền tại API Xác nhận và lấy sự đồng ý của khách hàng mục 3.1. Chi tiết tham khảo thêm RFC 7636.

Tham số

Loại dữ liệu

Bắt buộc

Mô tả

Content-Type

String

M

Mặc định “application/json”

Tham số

Loại dữ liệu

Bắt buộc

Mô tả

Content-Type

String

M

application/x-www-form-urlencoded

Authorization

String

M

Basic BASE64(client_id + “:” + client_secret)

Host

String

O

Xác định tên miền của máy chủ mà request đang gửi đến

Tham số

Loại dữ liệu

Bắt buộc

Mô tả

grant_type

String

M

Mặc định “refresh_token”

refresh_token

String

M

Giá trị refresh_token được trả về tại mục API Lấy mã truy cập

scope

String

O

Phạm vi (scope) không được vượt quá phạm vi (scope) tại API Xác nhận và lấy sự đồng ý của khách hàng mục 3.1.

Tham số

Loại dữ liệu

Bắt buộc

Mô tả

Content-Type

String

M

Mặc định “application/json”

Tham số

Loại dữ liệu

Bắt buộc

Mô tả

access_token

String

M

Mã truy cập.

refresh_token

String

O

Mã làm mới (Mã này có thể khác giá trị mã làm mới được sinh ra từ luồng lấy mã truy cập với grant_type authorization_code)

token_type

String

M

Mặc định “Bearer”

expires_in

Number

M

Giá trị hiệu lực của access_token đã được mô tả tại Mục 1 đối với nhóm AIS

Tham số

Loại dữ liệu

Bắt buộc

Mô tả

Content-Type

String

M

application/x-www-form-urlencoded

Authorization

String

M

Basic BASE64(client_id + “:” + client_secret)

Host

String

O

Xác định tên miền của máy chủ mà request đang gửi đến

Tham số

Loại dữ liệu

Bắt buộc

Mô tả

token

String

M

Giá trị của access_token hoặc refresh_token cần thu hồi

token_type_hint

String

O

Loại token cần thu hồi “access_token” hoặc “refresh_token”

Tham số

Loại dữ liệu

Bắt buộc

Mô tả

Content-Type

String

M

Mặc định “application/json”

Authorization

String

M

- Authorization định dạng: “Bearer + {access_token}”: theo tiêu chuẩn RFC 6750.

-          Mã access_token được cấp theo quy định tại mục 4.1 trong RFC 6749 (Authorization Code Grant).

Request-DateTime

DateTime

M

- Ngày giờ thực hiện.
- Định dạng: yyyy-MM-ddTHH:mm:ssZ (UTC DateTime), theo tiêu chuẩn RFC 3339

Request-ID

String [60]

M

Mã định danh duy nhất cho request, thường ở định dạng UUID

PSU-IP-Address

String [50]

O

Địa chỉ IP của khách hàng. Giá trị này phải ở dạng IPv4 hoặc IPv6.

PSU-User-Agent

String [200]

O

Thông tin trình duyệt trong trường hợp khách hàng sử dụng ứng dụng web của TPP hoặc các thông tin khác trong trường hợp khách hàng sử dụng ứng dụng khác của TPP.

PSU-Device-OS

String [100]

O

Hệ điều hành trên thiết bị (máy tính/di động,…) của khách hàng.

Provider-ID

String [8]

M

Mã định danh của Ngân hàng được quy định tại Mục 1.

TPP-ID

String [15]

M

Mã định danh của TPP được quy định tại Mục 1.

Client-ID

String [50]

O

Giá trị client_id được nêu tại Mục 1

Tham số

Loại Dữ liệu

Bắt buộc

Mô tả

Content-Type

String

M

Mặc định “application/json”

Request-ID

String

M

Giá trị được lấy từ request header trong API của TPP

Request-DateTime

DateTime

M

Giá trị được lấy từ request header trong API của TPP

JWS-Signature

String

M

Chữ ký JWS theo quy định tại Mục 1

Mức 1

Mức 2

Mức 3

Loại dữ liệu

Bắt buộc

Mô tả

accounts

Array

Danh sách tài khoản

identification

Object

M

Thông tin tài khoản của khách hàng mở tại Ngân hàng.

accountId

String [34]

M

Số tài khoản của khách hàng

name

String [70]

M

Tên tài khoản của khách hàng.

type

String [4]

M

Loại tài khoản quy định trong ISO 20022.

currency

String [3]

M

Loại tiền tệ quy định theo mã của bộ ISO 4217 với 3 ký tự viết hoa.

bankCode

String [8]

M

Mã định danh của Ngân hàng được quy định tại Mục 1

additionalInfo

Object

O

Thông tin bổ sung (nếu có)

Tham số

Loại dữ liệu

Bắt buộc

Mô tả

Content-Type

String

M

Mặc định “application/json”

Authorization

String

M

- Authorization định dạng: “Bearer + {access_token}”: theo tiêu chuẩn RFC 6750.

- Mã access_token được cấp theo quy định tại mục 4.1 trong RFC 6749 (Authorization Code Grant).

Request-DateTime

DateTime

M

- Ngày giờ thực hiện.
- Định dạng: yyyy-MM-ddTHH:mm:ssZ (UTC DateTime), theo tiêu chuẩn RFC 3339.

Request-ID

String [60]

M

Mã định danh duy nhất cho request, thường ở định dạng UUID

PSU-IP-Address

String [50]

O

Địa chỉ IP của khách hàng. Giá trị này phải ở dạng IPv4 hoặc IPv6.

PSU-User-Agent

String [200]

O

Thông tin trình duyệt trong trường hợp khách hàng sử dụng ứng dụng web của TPP hoặc các thông tin khác trong trường hợp khách hàng sử dụng ứng dụng khác của TPP.

PSU-Device-OS

String [100]

O

Hệ điều hành trên thiết bị (máy tính/di động,…) của khách hàng.

Provider-ID

String [8]

M

Mã định danh của Ngân hàng được quy định tại Mục 1.

TPP-ID

String [15]

M

Mã định danh của TPP được quy định tại Mục 1.

Client-ID

String [50]

O

Giá trị client_id được nêu tại Mục 1

JWS-Signature

String

M

Chữ ký JWS theo quy định tại Mục 1

Mức 1

Loại dữ liệu

Bắt buộc

Mô tả

accountId

String [34]

M

Số tài khoản của khách hàng.

Tham số

Loại dữ liệu

Bắt buộc

Mô tả

Content-Type

String

M

Mặc định “application/json”

Request-ID

String

M

Giá trị được lấy từ request header trong API của TPP

Request-DateTime

DateTime

M

Giá trị được lấy từ request header trong API của TPP

JWS-Signature

String

M

Chữ ký JWS theo quy định tại Mục 1

Mức 1

Mức 2

Mức 3

Loại dữ liệu

Bắt buộc

Mô tả

identification

Object

M

Thông tin số tài khoản của khách hàng

accountId

String [34]

M

Số tài khoản của khách hàng

name

String [70]

M

Tên tài khoản của khách hàng.

type

String [4]

M

Loại tài khoản quy định trong ISO 20022.

currency

String [3]

M

Loại tiền tệ quy định theo mã của bộ ISO 4217 với 3 ký tự viết hoa.

bankCode

String [8]

M

Mã định danh của Ngân hàng được quy định tại Mục 1 của Phụ lục.

creationDate

Datetime

M

- Ngày tạo tài khoản.

- Định dạng: yyyy-MM-ddTHH:mm:ssZ (UTC DateTime), theo tiêu chuẩn RFC 3339.

balances

Array

M

Thông tin về chi tiết số dư

amount

Object

M

Thông tin về số dư khả dụng

value

Number

M

Số dư khả dụng trên tài khoản của khách hàng

currency

String [3]

O

Loại tiền tệ quy định theo mã của bộ ISO 4217 với 3 ký tự viết hoa.

dateTime

DateTime

M

- Ngày giờ hệ thống thực hiện.
- Định dạng: yyyy-MM-ddTHH:mm:ssZ (UTC DateTime), theo tiêu chuẩn RFC 3339.

additionalInfo

Object

O

Thông tin bổ sung (nếu có)

Tham số

Loại dữ liệu

Bắt buộc

Mô tả

Content-Type

String

M

Mặc định “application/json”

Authorization

String

M

- Authorization định dạng: “Bearer + {access_token}”: theo tiêu chuẩn RFC 6750.

- Mã access_token được cấp theo quy định tại mục 4.1 trong RFC 6749 (Authorization Code Grant).

Request-DateTime

DateTime

M

- Ngày giờ thực hiện.
- Định dạng: yyyy-MM-ddTHH:mm:ssZ (UTC DateTime), theo tiêu chuẩn RFC 3339.

Request-ID

String [60]

M

Mã định danh duy nhất cho request, thường ở định dạng UUID.

PSU-IP-Address

String [50]

O

Địa chỉ IP của khách hàng. Giá trị này phải ở dạng Ipv4 hoặc Ipv6.

PSU-User-Agent

String [200]

O

Thông tin trình duyệt trong trường hợp khách hàng sử dụng ứng dụng web của TPP hoặc các thông tin khác trong trường hợp khách hàng sử dụng ứng dụng khác của TPP.

PSU-Device-OS

String [100]

O

Hệ điều hành trên thiết bị (máy tính/di động,…) của khách hàng.

Provider-ID

String [8]

M

Mã định danh của Ngân hàng được quy định tại Mục 1.

TPP-ID

String [15]

M

Mã định danh của TPP được quy định tại Mục 1.

Client-ID

String [50]

O

Giá trị client_id được nêu tại Mục 1.

JWS-Signature

String

M

Chữ ký JWS theo quy định tại Mục 1.

accountId

String [34]

M

Số tài khoản của khách hàng.

fromDate

DateTime

M

- Thời gian giao dịch từ ngày.

- Định dạng: yyyy-MM-ddTHH:mm:ssZ (UTC DateTime), theo tiêu chuẩn RFC 3339.

toDate

DateTime

M

- Thời gian giao dịch đến ngày.

- Định dạng: yyyy-MM-ddTHH:mm:ssZ (UTC DateTime), theo tiêu chuẩn RFC 3339.

page

Number

O

Xác định số trang được yêu cầu. Các trang được đánh số từ 1. Nếu tham số không được chỉ định, API sẽ trả về trang số 1.

size

Number

O

Xác định số lượng bản ghi trên một trang. Nếu tham số không được chỉ định, API sẽ trả về toàn bộ các bản ghi thoả mãn yêu cầu.

Tham số

Loại dữ liệu

Bắt buộc

Mô tả

Content-Type

String

M

Mặc định “application/json”

Request-ID

String

M

Giá trị được lấy từ request header trong API của TPP

Request-DateTime

DateTime

M

Giá trị được lấy từ request header trong API của TPP

JWS-Signature

String

M

Chữ ký JWS theo quy định tại Mục 1

Mức 1

Mức 2

Mức 3

Mức 4

Loại dữ liệu

Bắt buộc

Mô tả

pageCount

Number

M

Tổng số trang

pageNumber

Number

M

Trang hiện tại

nextPage

Number

O

Trang tiếp theo

pageSize

Number

M

Số bản ghi trên một trang.

totalCount

Number

O

Tống số bản ghi trên tất cả các trang

transactions

Array

M

Danh sách dữ liệu về lịch sử giao dịch

amount

Object

M

Thông tin số tiền giao dịch

value

Number

M

Số tiền giao dịch

currency

String [3]

M

Loại tiền tệ quy định theo mã của bộ ISO 4217 với 3 ký tự viết hoa

balances

Object

M

Thông tin số dư

value

Number

M

Số dư ở thời điểm giao dịch

currency

String [3]

M

Loại tiền tệ quy định theo mã của bộ ISO 4217 với 3 ký tự viết hoa

creditDebitIndicator

String [4]

M

- CRDT (Credit) nếu là số dư ghi có

- DBIT (Debit) nếu là số dư ghi nợ

reversalIndicator

boolean

O

Chỉ ra một giao dịch đã bị đảo ngược hoặc huỷ bỏ. Có thể bao gồm các giao dịch bị hoàn tiền, bị huỷ bỏ.

valueDate

DateTime

M

- Thời gian giao dịch.

- Định dạng: yyyy-MM-ddTHH:mm:ssZ (UTC DateTime), theo tiêu chuẩn RFC 3339.

references

Object

M

Thông tin mã định danh giao dịch

instructionIdentification

String [70]

M

Mã định danh duy nhất cho mỗi giao dịch

relatedParties

Object

O

Thông tin gửi nhận

debtor

Object

O

Thông tin bên chuyển tiền

name

String [140]

O

Tên của bên chuyển tiền

bankCode

String [8]

O

Mã định danh của Ngân hàng của bên chuyển được quy định tại Mục 1

accountId

String [34]

O

Số tài khoản.

creditor

Object

O

Thông tin bên nhận

name

String [140]

O

Tên của bên nhận

bankCode

String [8]

O

Mã định danh của Ngân hàng của bên nhận được quy định tại Mục 1

accountId

String [34]

O

Số tài khoản của bên nhận

additionalTransactionInformation

String [255]

M

Nội dung giao dịch

additionalInfo

Object

O

Thông tin bổ sung (nếu có)

Tham số

Loại dữ liệu

Bắt buộc

Mô tả

Content-Type

String

M

Mặc định “application/json”

Authorization

String

M

- Authorization định dạng: “Bearer + {access_token}”: theo tiêu chuẩn RFC 6750.

- Mã access_token được cấp theo quy định tại mục 4.4 trong RFC 6749 (với grant_type là client_credentials).

Request-DateTime

DateTime

M

- Ngày giờ thực hiện.
- Định dạng: yyyy-MM-ddTHH:mm:ssZ (UTC DateTime), theo tiêu chuẩn RFC 3339.

Request-ID

String [60]

M

Mã định danh duy nhất cho request, thường ở định dạng UUID

PSU-IP-Address

String [50]

O

Địa chỉ IP của khách hàng. Giá trị này phải ở dạng IPv4 hoặc IPv6.

PSU-User-Agent

String [200]

O

Thông tin trình duyệt trong trường hợp khách hàng sử dụng ứng dụng web của TPP hoặc các thông tin khác trong trường hợp khách hàng sử dụng ứng dụng khác của TPP.

PSU-Device-OS

String [100]

O

Hệ điều hành trên thiết bị (máy tính/di động,…) của khách hàng.

Provider-ID

String [8]

M

Mã định danh của Ngân hàng được quy định tại Mục 1.

TPP-ID

String [15]

M

Mã định danh của TPP được quy định tại Mục 1.

Client-ID

String [50]

O

Giá trị client_id được nêu tại Mục 1.

JWS-Signature

String

M

Chữ ký JWS theo quy định tại Mục 1

instructionIdentification

String [50]

M

Mã giao dịch do TPP khởi tạo

debtor

Object

C

Thông tin người thực hiện thanh toán, không bắt buộc trong trường hợp thanh toán với dịch vụ Cổng thanh toán

name

String [70]

C

Tên tài khoản của người thực hiện thanh toán

accountId

String [34]

C

Số tài khoản của người thực hiện thanh toán

bankCode

String [8]

C

Mã định danh của Ngân hàng của người thực hiện thanh toán được quy định tại Mục 1.

remittanceInformation

String [255]

M

Nội dung giao dịch

instructedAmount

Object

M

Thông tin số tiền giao dịch

value

Number

M

Số tiền giao dịch

currency

String [3]

M

Loại tiền tệ quy định theo mã của bộ ISO 4217 với 3 ký tự viết hoa.

requestedExecutionDate

DateTime

M

- Ngày thực hiện giao dịch.

- Định dạng: yyyy-MM-ddTHH:mm:ssZ (UTC DateTime), theo tiêu chuẩn RFC 3339.

additionalInfo

Object

O

Thông tin bổ sung (nếu có)

Tham số

Loại dữ liệu

Bắt buộc

Mô tả

Content-Type

String

M

Mặc định “application/json”

Request-ID

String

M

Giá trị được lấy từ request header trong API của TPP

Request-DateTime

String

M

Giá trị được lấy từ request header trong API của TPP

JWS-Signature

String

M

Chữ ký JWS theo quy định tại Mục 1

paymentId

String [35]

M

Mã giao dịch duy nhất do Ngân hàng cung cấp.

status

String [4]

M

Mã trạng thái của giao dịch. Theo tiêu chuẩn của ISO 20022.

statusDateTime

DateTime

M

- Thời điểm cập nhật trạng thái.

- Định dạng: yyyy-MM-ddTHH:mm:ssZ (UTC DateTime), theo tiêu chuẩn RFC 3339.

consentStatus

String [20]

M

Mặc định: “AWAITTING_AUTH”

Tham số

Loại dữ liệu

Bắt buộc

Mô tả

Content-Type

String

M

application/x-www-form-urlencoded

Host

String

O

Xác định tên miền của máy chủ mà request đang gửi đến

response_type

String

M

Giá trị mặc định “code id_token”

client_id

String

M

Giá trị client_id được nêu tại Mục 1.

scope

String

M

Phạm vi truy cập: PIS

redirect_uri

String

M

Đường dẫn dùng để điều hướng khách hàng về ứng dụng của TPP sau khi hệ thống xác nhận của Ngân hàng hoàn thành xác nhận khách hàng.

state

String

M

Giá trị này được TPP tạo ra để duy trì trạng thái giữa request và respone, được sử dụng để ngăn chặn các cuộc tấn công trong lĩnh vực bảo mật web (Cross-site request forgery)

code_challenge

String

M

code_challenge = BASE64URL-ENCODE(SHA256(ASCII(code_verifier)))

Chi tiết tham khảo thêm tại RFC 7636

code_challenge

_method

String

O

Thuật toán được sử dụng để tạo ra code_challenge.

Mặc định “S256”

request

String

M

Json Web Token (JWT).

Sử dụng giá trị paymentId nhận được từ API khởi tạo thanh toán mục 4.1 đưa vào claim trong payload.

Chuỗi thông tin JWT bao gồm:

+ JOSE Header – theo JWT trong RFC 7519, JWS trong RFC 7515. Thuật toán trong header “alg” theo mục 3.1 trong RFC 7518.

+ payload

+ signature – JWS trong RFC 7515

Tham số

Loại dữ liệu

Bắt buộc

Mô tả

code

String

M

Mã đồng ý

state

String

M

Giá trị state từ request của TPP.

id_token

String

O

Json Web Token (JWT).

Sử dụng giá trị paymentId nhận được từ API khởi tạo thanh toán mục 4.1 đưa vào trong payload.

- Chuỗi thông tin JWT bao gồm:

+ JOSE Header – theo JWT trong RFC 7519, JWS trong RFC 7515. Thuật toán trong header “alg” theo mục 3.1 trong RFC 7518;

+ payload;

+ signature – theo JWS trong RFC7515.

Tham số

Loại dữ liệu

Bắt buộc

Mô tả

Content-Type

String

M

application/x-www-form-urlencoded

Authorization

String

M

Basic BASE64(client_id + “:” + client_secret)

Host

String

O

Xác định tên miền của máy chủ mà request đang gửi đến

Tham số

Loại dữ liệu

Bắt buộc

Mô tả

grant_type

String

M

Mặc định “authorization_code”

code

String

M

Mã đồng ý mà Ngân hàng đã cấp cho TPP thông qua API xác nhận khách hàng luồng Redirect mục 4.2.

redirect_uri

String

M

Đường dẫn dùng để điều hướng khách hàng trở lại ứng dụng của TPP. Giá trị này phải khớp với giá trị redirect_uri đã truyền ở API xác nhận khách hàng luồng Redirect mục 4.2

code_verifier

String

M

Giá trị code verifier được sử dụng để tạo ra code_challenge mà TPP đã truyền tại API xác nhận khách hàng luồng Redirect mục 4.2. Chi tiết tham khảo thêm RFC 7636.

Tham số

Loại dữ liệu

Bắt buộc

Mô tả

Content-Type

String

M

Mặc định “application/json”

Tham số

Loại dữ liệu

Bắt buộc

Mô tả

access_token

String

M

Mã truy cập.

token_type

String

M

Mặc định “Bearer”

expires_in

Number

M

Giá trị hiệu lực của access_token đã được mô tả tại Mục 1 đối với nhóm PIS.

scope

String

M

Phạm vi của access_token. Giá trị này khớp với scope tại API Xác nhận khách hàng luồng Redirect mục 4.2.

Content-Type

String

M

Mặc định “application/json”

Authorization

String

M

- Authorization định dạng: “Bearer + {access_token}”: theo tiêu chuẩn RFC 6750.

- Mã access_token được cấp theo quy định tại mục 4.4 trong RFC 6749(với grant_type là client_credentials).

Request-DateTime

DateTime

M

- Ngày giờ thực hiện.
- Định dạng: yyyy-MM-ddTHH:mm:ssZ (UTC DateTime), theo tiêu chuẩn RFC 3339.

Request-ID

String [60]

M

Mã định danh duy nhất cho request, thường ở định dạng UUID

JWS-Signature

String

M

Chữ ký JWS theo quy định tại Mục 1

Mức 1

Loại dữ liệu

Bắt buộc

Mô tả

paymentId

String [35]

M

Mã giao dịch duy nhất do Ngân hàng cung cấp cho TPP trong API khởi tạo thanh toán mục 4.1

consentId

String [36]

M

Giá trị do Ngân hàng sinh ra sau khi xác nhận thành công trên Ứng dụng của Ngân hàng trong luồng Decoupled.

consentStatus

String [20]

M

Nhận một trong các giá trị sau:

- “AUTHORISED” khi khách hàng xác nhận thành công.

- “REJECTED” khi khách hàng xác nhận sai quy định của Ngân hàng.

- “CANCEL” khi khách hàng không xác nhận trên Ứng dụng của Ngân hàng.

expireIn

Number

M

Thời gian hiệu lực của consentId quy định tại Mục 1

Tham số

Loại dữ liệu

Bắt buộc

Mô tả

Content-Type

String

M

Mặc định “application/json”

Request-ID

String

M

Giá trị được lấy từ request header trong API của TPP

Request-DateTime

String

M

Giá trị được lấy từ request header trong API của TPP

JWS-Signature

String

M

Chữ ký JWS theo quy định tại Mục 1

message

String [20]

M

Mặc định “Success”

Content-Type

String

M

Mặc định “application/json”

Authorization

String

M

- Authorization định dạng: “Bearer + {access_token}”: theo tiêu chuẩn RFC 6750.

- Đối với Redirect Flow: Mã access_token được cấp theo quy định tại mục 4.1 trong RFC 6749 (Authorization Code Grant).

- Đối với Decoupled flow: Mã access_token được cấp theo quy định tại mục 4.4 trong RFC 6749 (với grant_type là client_credentials).

Request-DateTime

DateTime

M

- Ngày giờ thực hiện.
- Định dạng: yyyy-MM-ddTHH:mm:ssZ (UTC DateTime), theo tiêu chuẩn RFC 3339.

Request-ID

String [60]

M

Mã định danh duy nhất cho request, thường ở định dạng UUID

PSU-IP-Address

String [50]

O

Địa chỉ IP của khách hàng. Giá trị này phải ở dạng IPv4 hoặc IPv6.

PSU-User-Agent

String [200]

O

Thông tin trình duyệt trong trường hợp khách hàng sử dụng ứng dụng web của TPP hoặc các thông tin khác trong trường hợp khách hàng sử dụng ứng dụng khác của TPP.

PSU-Device-OS

String [100]

O

Hệ điều hành trên thiết bị (máy tính/di động,…) của khách hàng.

Provider-ID

String [8]

M

Mã định danh của Ngân hàng được quy định tại Mục 1.

TPP-ID

String [15]

M

Mã định danh của TPP được quy định tại Mục 1.

Client-ID

String [50]

O

Giá trị client_id được nêu tại Mục 1.

JWS-Signature

String

M

Chữ ký JWS theo quy định tại Mục 1

Mức 1

Loại dữ liệu

Bắt buộc

Mô tả

paymentId

String [35]

M

Mã giao dịch duy nhất do Ngân hàng cung cấp cho TPP trong API khởi tạo thanh toán mục 4.1

consentId

String [36]

C

Giá trị do Ngân hàng sinh ra sau khi xác nhận thành công trên Ứng dụng của Ngân hàng trong luồng Decoupled.

Tham số

Loại dữ liệu

Bắt buộc

Mô tả

Content-Type

String

M

Mặc định “application/json”

Request-ID

String

M

Giá trị được lấy từ request header trong API của TPP

Request-DateTime

String

M

Giá trị được lấy từ request header trong API của TPP

JWS-Signature

String

M

Chữ ký JWS theo quy định tại Mục 1

paymentId

String [35]

M

Mã giao dịch duy nhất do Ngân hàng cung cấp cho TPP trong API khởi tạo thanh toán mục 4.1.

status

String [4]

M

Mã trạng thái của giao dịch. Theo tiêu chuẩn của ISO 20022.

statusDateTime

DateTime

M

- Thời điểm cập nhật trạng thái.

- Định dạng: yyyy-MM-ddTHH:mm:ssZ (UTC DateTime), theo tiêu chuẩn RFC 3339.

Content-Type

String

M

Mặc định “application/json”.

Authorization

String

M

- Authorization định dạng: “Bearer + {access_token}”: theo tiêu chuẩn RFC 6750.

- Mã access_token được cấp theo quy định tại mục 4.4 trong RFC 6749(với grant_type là client_credentials)

Request-DateTime

DateTime

M

- Ngày giờ thực hiện.
- Định dạng: yyyy-MM-ddTHH:mm:ssZ (UTC DateTime), theo tiêu chuẩn RFC 3339.

Request-ID

String [60]

M

Mã định danh duy nhất cho request, thường ở định dạng UUID.

PSU-IP-Address

String [50]

O

Địa chỉ IP của khách hàng. Giá trị này phải ở dạng IPv4 hoặc IPv6.

PSU-User-Agent

String [200]

O

Thông tin trình duyệt trong trường hợp khách hàng sử dụng ứng dụng web của TPP hoặc các thông tin khác trong trường hợp khách hàng sử dụng ứng dụng khác của TPP.

PSU-Device-OS

String [100]

O

Hệ điều hành trên thiết bị (máy tính/di động,…) của khách hàng.

Provider-ID

String [8]

M

Mã định danh của Ngân hàng được quy định tại Mục 1.

TPP-ID

String [15]

M

Mã định danh của TPP được quy định tại Mục 1.

Client-ID

String [50]

O

Giá trị client_id được nêu tại Mục 1.

JWS-Signature

String

M

Chữ ký JWS theo quy định tại Mục 1.

Mức 1

Loại dữ liệu

Bắt buộc

Mô tả

paymentId

String [35]

M

Mã giao dịch duy nhất do Ngân hàng cung cấp cho TPP trong API khởi tạo thanh toán mục 4.1.

Content-Type

String

M

Mặc định “application/json”

Request-ID

String

M

Giá trị được lấy từ request header trong API của TPP

Request-DateTime

String

M

Giá trị được lấy từ request header trong API của TPP

JWS-Signature

String

M

Chữ ký JWS theo quy định tại Mục 1

paymentId

String [35]

M

Mã giao dịch duy nhất do Ngân hàng cung cấp cho TPP trong API khởi tạo thanh toán mục 4.1.

status

String [4]

M

Mã trạng thái của giao dịch. Theo tiêu chuẩn của ISO 20022.

statusDateTime

DateTime

M

- Thời điểm cập nhật trạng thái.

- Định dạng: yyyy-MM-ddTHH:mm:ssZ (UTC DateTime), theo tiêu chuẩn RFC 3339.

Content-Type

String

M

Mặc định “application/json”

Authorization

String

M

- Authorization định dạng: “Bearer + {access_token}”: theo tiêu chuẩn RFC 6750.

- Mã access_token được cấp theo quy định tại mục 4.4 trong RFC 6749(với grant_type là client_credentials).

Request-DateTime

DateTime

M

- Ngày giờ thực hiện.
- Định dạng: yyyy-MM-ddTHH:mm:ssZ (UTC DateTime), theo tiêu chuẩn RFC 3339.

Request-ID

String [60]

M

Mã định danh duy nhất cho request, thường ở định dạng UUID

PSU-IP-Address

String [50]

O

Địa chỉ IP của khách hàng. Giá trị này phải ở dạng IPv4 hoặc IPv6.

PSU-User-Agent

String [200]

O

Thông tin trình duyệt trong trường hợp khách hàng sử dụng ứng dụng web của TPP hoặc các thông tin khác trong trường hợp khách hàng sử dụng ứng dụng khác của TPP.

PSU-Device-OS

String [100]

O

Hệ điều hành trên thiết bị (máy tính/di động,…) của khách hàng.

Provider-ID

String [8]

M

Mã định danh của Ngân hàng được quy định tại Mục 1.