I. Đặc tả kỹ thuật API:

1. Tổng quan

1.1. Mã hóa Checksum

1.1.1. Request structure

Request URL: https://{domain}/{path}
- Domain:
Environment Domain
Sandbox https://sbx-gapi.payme.vn
Production https://gapi.payme.vn
- Path: Path tương ứng với từng API
Method: POST
Header:
Key Type Required Value
x-api-client String YES ID của key kết nối
Content-Type String Content-Type: application/json; charset=UTF-8
x-api-validate String md5 ( path+ method+ payload + secretKey )
Body: payload là các JSON với các key được định nghĩa cụ thể theo từng API

Environment	Domain
Sandbox	https://sbx-gapi.payme.vn
Production	https://gapi.payme.vn

Key	Type	Required	Value
x-api-client	String	YES	ID của key kết nối
Content-Type	String		`Content-Type`: application/json; charset=UTF-8
x-api-validate	String		md5 ( path+ method+ payload + secretKey )

1.1.2. Response structure:

HTTP response status: 200 OK, request thành công.

Trường hợp mã lỗi khác 200 sẽ thực hiện gọi lại để ghi nhân request nên lưu ý khi IPN ghi nhân thành công merchant trả về mã 200

Response header: Tương tự như request
Body: Là nội dung phản hồi được qui định cụ thể từng API có struct chung
Key Type Mô tả
code Number Mã lỗi
message String Mô tả thông tin mã lỗi
data Object Dữ liệu trả về

1.2 Mã hóa RSA

1.2.1. Request structure

Request URL: https://{domain}/{path}
- Domain:
Environment Domain
Sandbox https://sbx-gapi.payme.vn
Production https://gapi.payme.vn
- Path: Path tương ứng với từng API
Method: POST
Header:

Environment	Domain
Sandbox	https://sbx-gapi.payme.vn
Production	https://gapi.payme.vn

Key	Type	Require	Value
x-api-client	String	YES	Một chuỗi định danh được cung cấp cho Merchant khi tiến hành kết nối.
x-api-key	String	YES	Chuỗi mã hóa chuẩn RSA (Merchant dùng PPG Public Key để tạo), giá trị trước khi mã hóa là chuỗi sinh ra ngẫu nhiên (nên tạo chuỗi từ 8 đến 20 ký tự), đây là SecretKey dùng để mã hóa dữ liệu x-api-message và x-api-action.
x-api-action	String	YES	Dữ liệu mã hóa được tạo ra từ chuỗi (API Path + SecretKey ) với phương thức mã hóa AES.
Authorization	String	NO	Dùng AccessToken để chứng thực tính hợp lệ của các yêu cầu gửi lên PPG.
x-api-validate	String	YES	Đoạn mã checksum Md5.

Đoạn checksum Md5 x-api-validate là kết quả hàm băm từ một chuỗi liên tục các giá trị theo thứ tự sau:

Key	Value
x-api-action	như trên
method	POST/PUT/DELETE/GET
Authorization	như trên
x-api-message	như trên
SecretKey	như trên

Body:

Một object chứa các param sau đây:

Key	Type	Require	Value
x-api-message	String	YES	Đoạn mã được Encrypt từ chuỗi ghép (payload + SecretKey) bằng thuật toán AES*

payload-Object: RequestParam của API
SecretKey-String: Key mà Merchant tự sinh ra khi request, key này dùng để mã hoá payload và được mã hoá bởi PayME Public Key.

1.2.2. Response structure:

HTTP response status: 200 OK, request thành công.

Trường hợp mã lỗi khác 200 sẽ thực hiện gọi lại để ghi nhân request nên lưu ý khi IPN ghi nhân thành công merchant trả về mã 200

Response header:

Key	Type	Require	Value
x-api-key	String	YES	Là 1 chuỗi mã hoá dùng publicKey của Merchant cung cấp để encrypt base64 đoạn SecretKey ở Body, merchant sẽ dùng PrivateKey để decrypt
x-api-client	String	YES	Là 1 chuỗi định danh được cung cấp cho merchant khi tiến hành kết nối
x-api-action	String	YES	Là api action đã request
x-api-validate	String	YES	Là đoạn mã checksum Md5

Đoạn checksum Md5 x-api-validate là kết quả hàm băm từ một chuỗi liên tục các giá trị theo thứ tự sau:

Key	Value
x-api-action	như trên
method	POST/PUT/DELETE/GET
Authorization	như trên
x-api-message	như trên
SecretKey	như trên

Body:

Key	Value	Type
x-api-message	String	Payload dữ liệu trả về đã được mã hóa. Dùng SecretKey lấy được từ x-api-key trong phần header để Decrypt payload

1.3. Mã lỗi:

Status Code	Short Description	Type	Meaning
500	`SYSTEM_ERROR`	System error	Lỗi dịch vụ, liên hệ bộ phận liên quan để xử lý
501	`SYSTEM_MAINTENANCE`	System error	Hệ thống đang bảo trì
502	`ILLEGAL_DATA_REQUEST`	Merchant error	Dữ liệu yêu cầu không hợp lệ
503	`KEYID_INVALID`	Merchant error	`KeyID` không hợp lệ
504	`LIMIT_REQUEST_REACH`	Merchant error	Merchant request liên tục quá số lần cho phép
505	`EXCEPTION`	System error	Có lỗi không xác định
506	`DUPLICATE_PARNERTRANSID`	Merchant error	Merchant gửi trùng partner transid
400	`INVALID_PARAMS`	Merchant error	Dữ liệu yêu cầu không hợp lệ
401	`INVALID_TOKEN`	Merchant error	`AccessToken` chứng thực yêu cầu không hợp lệ
1002	`REQUEST_REFUSED`	Merchant error	Yêu cầu bị từ chối vì 1 số lý do bảo mật

1.4. Phương thức thanh toán

payMethod	payCode	Method Name	Description
PAYME	PAYME	Ví PayME	Thanh toán bằng ví PayME
ATMCARD	ATM	Thẻ ATM	Thanh toán bằng thẻ ATM
CREDITCARD	CREDIT, CREDIT_INTERNATIONAL	Thẻ quốc tế	Thanh toán bằng thẻ Visa/Master/JCB
BANKTRANSFER	MANUAL_BANK, VIETQR	Chuyển khoản ngân hàng	Thanh toán bằng chuyển khoản
QRPAY	VN_PAY	QRCode ngân hàng	Thanh toán bằng QR của ngân hàng
ALIPAY	ALIPAY_DIRECT, ALIPAY_ECOMMERCE	Alipay	Thanh toán bằng Alipay (Trung Quốc)
XNAP	XNAP	XNAP	Thanh toán bằng QR của XNAP (Singapore)
PAYNOW	PAYNOW	PayNow	Thanh toán bằng QR của PayNow (Singapore)
THAIQR	THAIQR	ThaiQR	Thanh toán bằng ThaiQR (Thái Lan)

II. CLIENT TO SERVER - API Frontend:

---
Ở mục này sẽ là nhưng API được cấp cho client-side phía tối tác, được gọi từ client trực tiếp sang server API PayME
Authentication (mã xác thực) ở mục này sẽ được cấp khi user liên kết thành công và chỉ được quyền sủ dụng ở mục này
Cặp Key Mã hoá ở các API này sử dụng sẽ là key Tích Hợp SDK (đã khởi tạo ở Dashboard)
---

1. Thông tin tài khoản

1.1 API Lấy thông tin tài khoản ví PayME

Mô tả: API do PayME cung cấp dùng để cung cấp thông tin và hiển thị tài khoản
Flow Chart

API Path: /fe/ewallet/account
Method : GET

Request Parameters:

Authentication

Header	Type	Mô Tả
Authorization	String	accessToken của user được cấp sau khi login/linked thành công

Payload: NONE
Response:

Key	Type	Mô Tả
code	Number	Mã Lỗi: 300010 Lấy thông tin thành công 300011 Có lỗi xảy ra
message	String	Mô tả thông tin mã lỗi
data	Object	Dữ liệu trả về gồm có các field bên dưới:

Dữ liệu trả về

Key	Type	Mô tả
accountId	Number	ID account
phone	String	Số điện thoại
email	String	Thông Tin Email
kyc	Object	Thông tin kyc (chi tiết bên dưới)
avatar	String	avatar người dùng
gender	Enum	Giới tính người dùng (MALE, FEMALE, OTHER)
birthday	Date	Ngày sinh(DD/MM/YYYYY)
address	String	Địa chỉ liên lạc
isActive	Boolean	Mặc định Active
state	Enum	Trạng Thái Tài khoản (OPENED, LOCKED, TEMPORARY_LOCK)
linked	Boolean	Đã liên kết Ví PayME ?

KYC Object details

Key	Type	Mô tả
identifyNumber	Number	Mã định danh (số cmnd, cccd...)
identifyType	Enum	Hình thức định danh tài khoản (CMND, CCCD)
state	Enum	Trạng Thái KYC (xem chi tiết bên dưới)
reason	String	Lý do từ chối KYC (nếu có)
issuedAt	String	Ngày cấp
placeOfIssue	String	Nơi cấp

Các trạng thái KYC

KYC state	Mô Tả
APPROVED	đã xác nhận KYC
REJECTED	đã từ chối KYC
PENDING	đang chờ duyệt KYC

Ví dụ:

Payload mẫu trước khi encrypt: NONE
Response mẫu trước khi encrypt:

{
    code: 300010,
    message: "Lấy thông tin thành công",
    data: {
            accountId: 9,
            phone: "0998999999",
            email: "nvip99@gmail.com",
            kyc: {
                    identifyNumber: 10012123123,
                    identifyType: "CMND",
                    issuedAt: "01/08/1998",
                    state: "APPROVED",
                    reason: null,
                    placeOfIssue: "Công An TPHCM",
        },
            avatar: "http://static.payme.vn/luatnv/hinhanh.png",
            gender: "MALE",
            birthday: "01/08/1998",
            address: "53 Hai Bà Trưng, Phường 8, Thành Phó Đà Lạt, Tỉnh Lâm Đồng",
            isActive: true,
            state: "OPENED",
            linked: true,
    },
}

1.2 API Cập nhật thông tin tài khoản

Mô tả: API do PayME cung cấp dùng để cập nhật thông tin tài khoản
Flow Chart

API Path: /fe/ewallet/account
Method : PUT

Request Parameters:

Authentication

Header	Type	Mô Tả
Authorization	String	accessToken của user được cấp sau khi login/linked thành công

Payload:

Tham Số	Kiểu dữ liệu	Ý nghĩa
email	String	Thông Tin Email
avatar	String	avatar người dùng
address	String	Địa chỉ liên lạc

Response:

Tham Số	Kiểu dữ liệu	Ý nghĩa
code	Number	Mã Lỗi: 300012 Cập nhật thông tin thành công 300013 Cập nhật thông tin thất bại 300014 Email không đúng định dạng
message	String	Mô tả thông tin mã lỗi

Ví dụ:

Payload mẫu trước khi encrypt:

    {
        "email": "nluat999@gmail.com",
        "avatar": "hinhanh.png",
        "address": "615/218 Xo viet nghe Tinh, TPHCM"
    }

Response mẫu trước khi encrypt:

{
    code: 300012,
    message: "Cập nhật thông tin thành công "
}

1.3 API Lấy thông tin số dư

Mô tả: API do PayME cung cấp dùng để lấy thông tin số dư tài khoản
Flow Chart

API Path: /fe/ewallet/balance
Method : GET

Request Parameters:

Authentication

Header	Type	Mô Tả
Authorization	String	accessToken của user được cấp sau khi login/linked thành công

Payload: NONE
Response:

Tham Số	Kiểu dữ liệu	Ý nghĩa
code	Number	Mã Lỗi: 300020 Lấy Thông tin ví thành công
message	String	Mô tả thông tin mã lỗi
data	Object	Dữ liệu trả về gồm có các field bên dưới:

Dữ liệu trả về

Tham Số	Kiểu dữ liệu	Ý nghĩa
balance	Number	Thông tin số dư tổng
cash	Number	Số dư khả dụng
lockCash	Number	Số dư tạm khoá

Ví dụ:

Payload mẫu trước khi encrypt: NONE
Response mẫu trước khi encrypt:

{
    code: 300020,
    message: "Lấy Thông tin ví thành công",
    data: { balance: 250000, cash: 210000, lockCash: 40000
    },
}

2. Liên kết tài khoản

Bộ API ở mục này sẽ được dùng để liên kết 1 user của đối tác với một tài khoản Ví Payme

Khi liên kết thành công, 1 userid (mã định danh user của đối tác) sẽ được liên kết 1 - 1 và duy nhất với 1 sdt Ví PayME

2.1 Liên kết 1 user với Ví PayME

Mô tả: API do PayME cung cấp nhằm mục đích tạo liên kết giữa Ví PayME với đối tác khi có user mới muốn sử dụng Ví
Ở flow này có 3 trường hợp xảy ra : 1\ KH chưa liên kết từ app đối tác, có số điện thoại liên kết đã có trước đó => tiến hành liên kết và merge thông tin lại với nhau cho KH sử dụng, thông qua OTP và api 2.2 2\ KH chưa từng sủ dụng Ví => tiến hành liên kết đồng thời tạo Ví PayME cho Khách hàng, , thông qua OTP và api 2.2 3\ KH đã liên kết thành công trước đó, client sẽ gọi api này và được cấp accessToken để sử dụng ngay
API Path: /fe/ewallet/account/link
Method : POST

Request Parameters:

Payload:

Key	Type	Required	Description
connectToken	String	✔	là một đoạn mã chứa thông tin của Khách Hàng để liên kết, công thức ở bên dưới
deviceId	String		DeviceId ở máy của khách hàng
lang	String		Ngôn ngữ hiển thị : vi/en

**connectTokenđược sinh với công thức như sau : AES-256(JSON.stringify(data), secretKey);

Thông tin có trong object data của connectToken:

Key	Type	Required	Description
userId	String(32)	✔	AccountId khách hàng bên đối tác
phone	String(10)	✔	Số điện thoại của khách hàng
kycInfo	Object		Thông tin KYC mà đối tác gửi cho PayME `(1)`.(Chi tiết ở bên dưới)

Thông tin có trong object của kycInfo

Key Required Type Môtả

fullname ✔ String Tên của khách hàng

gender ✔ Enum Giới tính (MALE, FEMALE)

birthday ✔ String Ngày sinh (Dạng DD/MM/YYYY)

address ✔ String Thông tin về địa chỉ của khách hàng

identifyType ✔ Enum Loại thẻ chứng thực (CMND, CCCD)

identifyNumber ✔ String Số CMND, CCCD

issuedAt ✔ String Ngày phát hành thẻ (Dạng DD/MM/YYYY)

placeOfIssue ✔ String Nơi phát hành thẻ

video String URL video quay khuôn mặt của khách hàng

face String URL hình chụp khuôn mặt của khách hàng

image

✔

Object

Object chứa URL hình chụp CMND/CCCD của khách hàng (2):

Key	Type	Bắt Buộc	Mô tả
front	String	✔	URL hình chụp CMND/CCCD (mặt trước)
back	String	✔	URL hình chụp CMND/CCCD (mặt sau)

Response:

Key	Type	Mô Tả
code	Number	Mã lỗi: `311000`: Liên kết thành công `311001`: Tài khoản bị khoá `311002`: Thông tin KYC bị lỗi `311003`: Số điện thoại chưa liên kết với PayME `311004`: Không tìm thấy thông tin kết nối `311005`: Thông tin giải mã connectToken không đúng `311006`: Format của connectToken không đúng `311007`: Định dạng SDT không đúng `311008`: Số điện thoại đã liên kết với userId khác `311009`: UserId đã liên kết với SDT khác `311010`: Không tìm thấy thông tin tài khoản người dùng `311011`: Lỗi gửi OTP liên tiêp `311012`: Lỗi hệ thống
message	String	Mô tả thông tin mã lỗi
data	Object	Dữ liệu trả về gồm có thể có các field bên dưới:

Thông tin trong data

Key	Type	Mô tả
accessToken	String	AccessToken khi đăng nhập/linked thành công (mã code 311000)
verifyToken	String	Verify Token dùng cho các trường hợp kết nối với ví PayME mới (mã code 311003)

Ví dụ:

Payload mẫu trước khi encrypt:

{
  "connectToken": "U2FsdGVkX193ahc9vY2b/FeSVyg6FP8uoVl5aIMdfEeXXibbJtVkrVB/1VlDsh2WJkDdx8chu4LbvClRDn9kOrcIAvCu9P7i6JjPEtfFGnMNSulQUDUq49AGbytaVP6nRNg9clWWdbGqUJfGxNs4gvVKGSDbltOFZsDc1yLMI",
  "deviceId": "iphone"
}

Thông tin connectToken mẫu trước khi encrypt:

{
    "userId": "0944074831",
    "phone": "0944074831",
    "kycInfo":
        {
            "fullname": "Nguyen Le Khang",
            "gender": "MALE",
            "birthday": "08/11/1998",
            "address": "Luong Son - Bac Binh - Binh Thuan",
            "identifyType": "CMND",
            "identifyNumber": "String",
            "issuedAt": "19/01/2019",
            "placeOfIssue": "Binh Thuan",
            "video": "https://sbx-static.payme.vn//2020/10/28/Co-29vnK6.mp4",
            "face": "https://cdn.pixabay.com/photo/2015/04/23/22/00/tree-736885__480.jpg",
            "image":
                {
                    "front": "https://cdn.pixabay.com/photo/2015/04/23/22/00/tree-736885__480.jpg",
                    "back": "https://cdn.pixabay.com/photo/2015/04/23/22/00/tree-736885__480.jpg",
                }
        },
}

Note :

(1) PayME chỉ chấp nhận thông tin này khi có thoả thuận giữa 2 bên. (2) Hình ảnh bắt buộc có cả 2 mặt nếu gửi.

Response mẫu trước khi encrypt:

Trường hợp SDT đã liên kết với ví PayME

{
    "code": 311000,
    "message": "Đăng nhập Thành công",
    "data":
        {
           "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6MzU2NTgsImFjY291bnRJZCI6NTIyNjc3MzMzNiwic2NvcGUiOltdLCJjbGllbnRJZCI6IjA4NEY3REJFLTI3MzUtNEE1OC04NzFGLUFFNzZCMjVCMzVDOSIsImFwcElkIjpudWxsLCJpYXQiOjE2NDE1Mzg5MzR9.JAqsloNsAFy3Vjm3LlWjs_ECMX0EmXUVltZXqp7YvY4",
           "phone": "84944074831"
        },
}

Trường hợp SDT chưa liên kết với ví PayME

{
    "code": 311003,
    "message": "Số điện thoại chưa liên kết với PayME",
    "data":
        {
           "verifyToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6MzU2NTgsImFjY291bnRJZCI6NTIyNjc3MzMzNiwic2NvcGUiOltdLCJjbGllbnRJZCI6IjA4NEY3REJFLTI3MzUtNEE1OC04NzFGLUFFNzZCMjVCMzVDOSIsImFwcElkIjpudWxsLCJpYXQiOjE2NDE1Mzg5MzR9.JAqsloNsAFy3Vjm3LlWjs_ECMX0EmXUVltZXqp7YvY4",
           "phone": "84944074831"
        },
}

2.2 Xác nhận liên kết

Mô tả: Khi khách hàng kết nối ví payME lần đầu, lúc này cần xác nhận thông tin OTP từ khách hàng. Payme sẽ tiến hành gửi sms cho KH, sau đó phía đối tác cho KH nhập OTP và gửi kèm verifyToken cho PayME qua api này để hoàn tất liên kết.
API Path: /fe/ewallet/account/verifyLink
Method : POST

Request Parameters:

Payload:

Key	Type	Required	Description
verifyToken	String	✔	verifyToken nhận được từ API link
activeCode	String	✔	Active Code mà PayME đã gửi
lang	String		Ngôn ngữ hiển thị : vi/en

Response:

Key	Type	Mô Tả
code	Number	Mã lỗi: `312000`: Liên kết thành công `312001`: Sai mã xác nhận `312002`: Không tìm thấy thông tin kết nối `312003`: Thông tin giải mã verifyToken không đúng `312004`: Format của verifyToken không đúng `312005`: Định dạng SDT không đúng `312006`: Mã xác thực hết hạn `312007`: Tài khoản đã được liên kết trước đó `312008`: Lỗi khi KYC `312009`: Lỗi hệ thống
message	String	Mô tả thông tin mã lỗi
data	Object	Dữ liệu trả về gồm có thể có các field bên dưới:

Request mẫu trước khi encrypt:

{ 
    "activeCode": "233222", 
    "verifyToken": "U2FsdGVkX193ahc9vY2b/FeSVyg6FP8uoVl5aIMdfEeXXibbJtVkrVB/1VlDsh2WJkDdx8chu4LbvClRDn9kOrcIAvCu9P7i6JjPEtfFGnMNSulQUDUq49AGbytaVP6nRNg9clWWdbGqUJfGxNs4gvVKGSDbltOFZsDc1yLMI" 
}

Response mẫu trước khi encrypt:

{
    "code": 113000,
    "message": "Thành công",
    "data": { 
        "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6MzU2NTgsImFjY291bnRJZCI6NTIyNjc3MzMzNiwic2NvcGUiOltdLCJjbGllbnRJZCI6IjA4NEY3REJFLTI3MzUtNEE1OC04NzFGLUFFNzZCMjVCMzVDOSIsImFwcElkIjpudWxsLCJpYXQiOjE2NDE1Mzg5MzR9.JAqsloNsAFy3Vjm3LlWjs_ECMX0EmXUVltZXqp7YvY4" 
    }
}

3. Liên kết thẻ/tài khoản ngân hàng

Bộ API ở mục này sẽ được dùng để liên kết 1 thẻ/tài khoản Ngân hàng của đối tác với một tài khoản Ví Payme, sau khi liên kết thành công, thẻ đó sẽ có thể sử dụng thanh toán cho tài khoản đó trở về sau

3.1 API Lên kết thẻ

Mô tả: API do PayME cung cấp với mục đích thực hiện liên kết tài khoản ngân hàng vào ví payME
API Path: /fe/ewallet/banking/link
Method : POST
Header :

Key	Type	Required	Value
Authorization	String	YES	accessToken account được payME cấp sau khi đăng nhập thành công.

Request Parameters:

Payload :

Tham số	Kiểu dữ liệu	Bắt buộc	Mô tả
swiftCode	String	false	Mã swiftCode ngân hàng liên kết. Required nếu là ngân hàng nội địa thuộc NAPAS
amount	Number	false	Số tiền cần nạp vào Ví đề xác thực khi liên kết với các ngân hàng yêu cầu xác thực*
env	String	false	Môi trường để lấy Webview liên kết (thẻ Napas). Enum: [MobileApp WebApp]
linkedInfo	Object	true	Thông tin thẻ liên kết. (Chỉ chọn 1 trong 3 dạng liên kết)
redirectUrl	String	true	Link redirect khi thanh toán thành công
version	String	false	Version phiên bản app đang sử dụng
clientId	String	true	ID của client đang trong phiên đăng nhập

* Note : đối với các ngân hàng sau sẽ không cần số tiền nạp ban đầu :

PVCombank
OCB
BIDV
VIetinbank

Đối với liên kết thẻ Visa, số tiền luôn là 1000đ

Thông tin linkedInfo object

Tham số	Kiểu dữ liệu	Bắt buộc	Mô tả
card	Object	false	Liên kết số thẻ ngân hàng
account	Object	false	Liên két bằng số tài khoản ngân hàng
credit	Object	false	Liên kết thẻ credit

Thông tin card object

Tham số	Kiểu dữ liệu	Bắt buộc	Mô tả
cardNumber	String	true	Số thẻ
cardHolder	String	true	Tên chủ thẻ
issuedAt	String	true	Ngày phát hành thẻ (MM/YY)
expiredAt	String	false	Ngày hết hạng thẻ (MM/YY)

Thông tin account object
Tham số Kiểu dữ liệu Bắt buộc Mô tả
accountNumber String true Số tài khoản ngân hàng muốn liên kết
Thông tin credit object
Tham số Kiểu dữ liệu Bắt buộc Mô tả
cardNumber String true Số thẻ
expiredAt String true Ngày hết hạn thẻ (MM/YY)
cvv String true Mã bảo mật thẻ
env:
Tên ENV Mô tả
MobileApp Khách hàng đang sử dụng mobile app để thao tác
WebApp Khách hàng đang sử dụng web để thao tác

Tham số	Kiểu dữ liệu	Bắt buộc	Mô tả
accountNumber	String	true	Số tài khoản ngân hàng muốn liên kết

Tên ENV	Mô tả
MobileApp	Khách hàng đang sử dụng mobile app để thao tác
WebApp	Khách hàng đang sử dụng web để thao tác

Response:

Tham số	Kiểu dữ liệu	Mô tả
code	Number	Mã lỗi: `157000`: Liên kết thành công `157010`: Liên kết cần xác thực bằng từ giao diện ngân hàng/napas (dùng html ở data) `157020`: Liên kết cần xác thực bằng mã OTP ngân hàng `157001`: Thất bại (sẽ trả từng message cụ thể khi nhận mã lỗi này) `157002`: Tạm khóa vì sai OTP quá nhiều lần
message	String	Mô tả thông tin mã lỗi
data	object	Data liên kêt (chi tiết bên dưới)

Thông tin data object

Tham số	Kiểu dữ liệu	Mô tả
linkedId	Number	Mã thẻ liên kết (nếu thành công ngay)
transaction	String	Mã giao dịch khi liên kết
html	String	form HTML sẽ cần client client đối tác hiện thị/nhung vào để xử lý với Ngân hàng/Napas xác thực thẻ, sau khi user thao tác thành công/thất bại, trang này sẽ redirect về redirectUrl đã gửi ở request

Request mẫu trước khi encrypt:

Liên kêt bằng thẻ

{
    "swiftCode": "SBITVNVXK",
    "env": "MobileApp",
    "amount": 20000,
    "linkInfo": {
        "card": {
            "cardNumber": "9704000000000018",
            "cardHolder": "Nguyễn Văn A",
            "issuedAt": "03/07"
        }
    },
    "redirectUrl": "https://google.com.vn",
    "clientId": "XXX-XXX-XXX-XXX"
}

Liên kết bằng account của bank

{
    "swiftCode": "BIDVVNVX",
    "env": "MobileApp",
    "linkInfo": {
        "account": {
            "accountNumber": "12010002100520"
        }
    },
    "redirectUrl": "https://google.com.vn",
    "clientId": "XXX-XXX-XXX-XXX"
}

Liên kết credit

{
    "amount": 1000,
    "linkInfo": {   
        "credit": {}
    },
    "redirectUrl": "https://payme.vn/web/",
    "clientId": "XXX-XXX-XXX-XXX"
}

Response mẫu trước khi encrypt:

Trường hợp liên kết thành công ngay

{
    "code": 157000,
    "message": "Liên kết thành công.",
    "data": {
        "linkedId": 123456969,
        "transaction": "59034859009",
        "html": null
    },
}

Trường hợp liên kết cần thao tác trên giao diện ngân hàng

{
    "code": 157010,
    "message": "Vui lòng xác thực giao dịch.",
    "data": {
        "linkedId": 123456969,
        "transaction": "59034859009",
        "html": "<html xmlns=\"http://www.w3.org/1999/xhtml\">\n  <head>  \n    <title>Liên kết ngân hàng BIDV</title>  \n    <meta     http-equiv=\"refresh\"  content=\"0;URL=https://www.bidv.net/EWALLET/SecureCodeServlet? secureCode=57566569314C48724E4B4B5A34322F6D716853556D513D3D\" />\n  </head>\n  <body></body>\n  </html>",
    },
}

Trường hợp liên kết cần nhập OTP từ ngân hàng,

{
    "code": 157020,
    "message": "Vui lòng xác thực OTP.",
    "data": {
        "linkedId": 123456969,
        "transaction": "59034859009",
        "html": null,
    },
}

3.2 API Xác thực OTP liên kết thẻ

Mô tả: Khi liên kết, nếu là loại thẻ cần xác thật OTP của Ngân hàng , đối tác cần hiện UI cho user nhập OTP này và gửi lại kèm transaction khởi tạo Sau khi payME nhận được OTP sẽ gửi Ngân hàng và xác thực kèm kèm quả trả về
API Path: /fe/ewallet/banking/link/verifyOTP
Method: POST
Header:
Key Type Required Value
Authorization String YES accessToken account được payME cấp sau khi đăng nhập thành công.

Request Parameters:

Payload :

Tham số	Kiểu dữ liệu	Bắt buộc	Mô tả
transaction	String	true	mã giao dịch khi thanh toán xác thực thẻ
otp	String	true	mã otp của ngân hàng
swiftCode	String	true	Mã swiftCode ngân hàng liên kết. Required nếu là ngân hàng nội địa thuộc NAPAS

Response:

Tham số	Kiểu dữ liệu	Mô tả
code	Number	Mã lỗi: `157200`: Xác thực thành công. PayME sẽ tiến hành liên kết thẻ cho user `157201`: Thất bại (sẽ trả từng message cụ thể khi nhận mã lỗi này) `157202`: Mã OTP không đúng. Tiến hành nhập lại. `157203`: Tạm khóa vì sai OTP quá nhiều lần
message	String	Mô tả thông tin mã lỗi

Request mẫu trước khi encrypt:

{
    "swiftCode": "BIDVVNVX",
    "transaction": "4901903683-KYOAQ9SI3",
    "otp": "123456"
}

Response mẫu trước khi encrypt:

{
    "code": 157200,
    "message": "Xác thực thành công."
}

3.3 API Hủy liên kết thẻ

Mô tả: API khi user muốn huỷ liên kết 1 thẻ ATM/CreditCard khỏi tài khoản
API Path: /fe/ewallet/banking/unlink
Method: POST
Header:
Key Type Required Value
Authorization String YES accessToken account được payME cấp sau khi đăng nhập thành công.

Request Parameters:

Payload :
Tham số Kiểu dữ liệu Bắt buộc Mô tả
linkedId Number true Id của thẻ liên kết trong danh sách liên kết
clientId String true id của client đang trong phiên đăng nhập

Tham số	Kiểu dữ liệu	Bắt buộc	Mô tả
linkedId	Number	true	Id của thẻ liên kết trong danh sách liên kết
clientId	String	true	id của client đang trong phiên đăng nhập

Response:

Tham số	Kiểu dữ liệu	Mô tả
code	Number	Mã lỗi: `157100`: Xác thực thành công. PayME sẽ tiến hành liên kết thẻ cho user `157100`: Thất bại (sẽ trả từng message cụ thể khi nhận mã lỗi này)
message	String	Mô tả thông tin mã lỗi

Request mẫu trước khi encrypt:

{
    "linkedId": 7589157344,
    "clientId": "clientId"
}

Response mẫu trước khi encrypt:

{
    "code": 157100,
    "message": "Hủy liên kết thành công.",
}

{
    "code": 157101,
    "message": "Hủy liên kết thất bại. Vui lòng thử lại sau.",
}

3.4 API Lấy danh sách thẻ đã liên kết

Mô tả: API để lấy data và hiển thị các thẻ khách hàng đã liên kết với ứng dụng và Ví PayME, dùng đển quản lý, huỷ hoặc thanh toán.
API Path: /fe/ewallet/banking/linked
Method: GET
Header:
Key Type Required Value
Authorization String YES accessToken account được payME cấp sau khi đăng nhập thành công.

Request Parameters:

Payload : NONE

Response:

Tham số	Kiểu dữ liệu	Mô tả
code	Number	Mã lỗi: `157400`: Liên kết thành công `157401`: Thất bại (sẽ trả từng message cụ thể khi nhận mã lỗi này)
message	String	Mô tả thông tin mã lỗi
data	object	Data liên kêt (chi tiết bên dưới)

Thông tin data object
Tham số Kiểu dữ liệu Mô tả
linkedList Array Chi tiết các thẻ đã liên kết để hiển thị, detail bên dưới
totaLinked Number Tổng số thẻ đã liên kết

Tham số	Kiểu dữ liệu	Mô tả
linkedList	Array	Chi tiết các thẻ đã liên kết để hiển thị, detail bên dưới
totaLinked	Number	Tổng số thẻ đã liên kết

Thông tin các phần tử có trong linkedList

Tham số	Kiểu dữ liệu	Mô tả
linkedId	Number	ID thẻ liên kết Ví PayME
linkedAt	DateTime	Thời gian liên kết thẻ
type	String	Loại thẻ liên két (ATM , CREDIT_CARD)
issuer	String	Tên ngân hàng/tổ chức phát hành thẻ
swiftCode	String	swiftCode ngân hàng liên kết
cardNumber	String	Số thẻ (đã che, chỉ hiển thị 4 số đầu và cuối)
accountNumber	String	Số tài khoản ngân hàng (đã che, chỉ hiển thị 4 số cuối)
issuedAt	String	Ngày phát hành
expiredAt	String	Ngày hết hạn thẻ

Response mẫu trước khi encrypt:

{
    "code": 157400,
    "message": "Lấy thông tin thẻ liên kết thành công.",
    "data": {
        "totalLinked": 3,
        "linkedList": [
            {
                "linkedId": 7643352700,
                "linkedAt": "08/02/2022",
                "type": "CREDIT_CARD",
                "issuer": "MASTERCARD",
                "swiftCode": null,
                "cardNumber": "5200********1096",
                "accountNumber": "",
                "issuedAt": "",
                "expiredAt": "10/2024"
            },
            {
                "linkedId": 9555032836,
                "linkedAt": "23/01/2022",
                "type": "ACCOUNT",
                "issuer": "OCB",
                "swiftCode": "ORCOVNVX",
                "cardNumber": "",
                "accountNumber": "************7009",
                "issuedAt": "",
                "expiredAt": ""
            },
            {
                "linkedId": 7630179079,
                "linkedAt": "22/01/2022",
                "type": "ATM",
                "issuer": "SaigonBank",
                "swiftCode": "SBITVNVX",
                "cardNumber": "9704********0018",
                "accountNumber": "",
                "issuedAt": "03/2007",
                "expiredAt": ""
            }
        ]
    }
}

4. Lịch sử ví PayME

4.1 Lịch sử giao dịch

Mô tả: API lấy danh sách lịch sử giao dịch của user
Path: /fe/ewallet/history
Method: GET

Request Parameters:

Header:

Tham so	Kiểu dữ liệu	Bắt buộc	Ý Nghĩa
accessToken	String	✔	accessToken account sau khi login

Payload:

Tham số	Kiểu dữ liệu	Ý Nghĩa	Enum
transaction	String	Mã dịch vụ
state	String(Enum)	Trạng thái lịch sử, trạng thái dịch vụ	[SUCCEEDED, PENDING]
changed	String(Enum)	Thu/Chi	[IN, OUT]
type	String(Enum)	Loại dịch vụ
startDate	Date	Thời gian bắt đầu
endDate	Date	Thời gian kết thúc
start	Number	Bắt đầu danh sách
limit	Number	giới hạn danh sách

enum:

type

Value	Mô tả dịch vụ
BASIC	Cơ bản
SOCIAL_PAYMENT	Social Payment
WALLET_PAY	WALLET_PAY
WALLET_QR	WALLET_QR
DEPOSIT	Nạp
WITHDRAW	Rút
TRANSFER_MONEY	Chuyển tiền
OPEN_EWALLET_PAYMENT	Thanh toán EWallet
BILL	Hóa đơn
LINKED	Liên kết thẻ
MOBILE_CARD	Mua thẻ cào
MOBILE_TOPUP	Nạp tiền điện thoại
REFUND_MONEY	Hoàn tiền
ISEC	ISEC
ADVANCE_MONEY	Ứng tiền
CREDIT_STATEMENT	Thanh toán tín dụng cho nhà cung cấp
CREDIT_SETTLEMENT	Tất toán tín dụng cho nhà cung cấp
GAME_CARD	Mua thẻ game
FAST_LOAN	Vay nhanh
PAYMENT_CODE	Thanh toán QR Code
PAY_QRCODE	Thanh toán VNPay
CREDIT_BALANCE	Ví tín dụng

Response:

Tham số	Kiểu dữ liệu	Ý Nghĩa
code	Number	Mã lỗi
message	String	Mô tả thông tin mã lỗi
data	Array	Mảng danh sách lịch sử

Data
data là 1 mảng gồm những object để hiện thị từng dòng lịch sử, với mỗi object có cấu trúc như sau :

Tham số	Kiểu dữ liệu	Ý Nghĩa
transaction	String	Mã dịch vụ
amount	String	Số tiền thanh toán
fee	String	Phí
total	String	Số tiền cuối cùng
serviceName	String	Tiêu đề lịch sử
createdAt	String	Thời gian giao dịch
state	String	Trạng thái
changed	String	Thu/Chi
description	String	Mô tả lịch sử
detailUrl	String	link webview mô tả chi tiết giao dịch

Ví dụ

Response mẫu trước khi encrypt:

{
    "code": 157000,
    "message": "Lấy thông tin lịch sử thành công",
    "data": [{
        transaction: "1111111190",
        amount: 10000,
        fee: 1000,
        total: 11000,
        serviceName: "Thanh toan dich vu",
        createdAt: "2022-01-11T06:54:53.701Z",
        state: "SUCCEEDED",
        changed: "OUT",
        description: "Thanh toan dich vu cho VNPay",
        detailUrl: "www.payme.vn/ewallet/history/1111111190"
    }]
}

{
    "code": 157001,
    "message": "Không tìm thấy thông tin lịch sử giao dịch",
    "data": []
}

5. Thanh toán

5.1 Thanh toán Đơn hàng cho Khách hàng

Description: Api dùng để thanh toán 1 đơn hàng của Merchant/Doanh nghiệp cho Khách hàng, sau khi gọi API này sẽ có 3 trường hợp xảy ra :
1\ Khách hàng đủ số dư Ví hoặc tiền trong tài khoản Ngân Hàng, và số tiền thanh toán dưới hạn mức cần xác thức => Đơn hàng sẽ được thanh toán ngay lập tức, và IPN về cho đối tác thông qua IPN URL đã khai báo ở key
2\ Số tiền thanh toán quá hạn mức cần xác thực của Ngân hàng phát hành Thẻ => Cần phải xác thực bằng OTP của Ngân hàng => Đối tác sẽ hiển thị UI nhập OTP cho Khách hàng và dùng api 5.2 để hoàn thành giao dịch
3\ Thanh toán thất bại, tuỳ vào mã lỗi thất bại đối tác sẽ báo lỗi cho Khách hàng
Path: /fe/ewallet/payment/pay
Method: POST

Request Parameters:

Payload:

Key

Type

Required

Description

amount

Number

✔

Giá trị tiền đơn hàng cần thanh toán

phone

String

✔

Số điện thoại Khách hàng cần thanh toán đơn hàng

partnerTransaction

String

✔

Transaction của đối tác

description

String

Mô tả ngắn gọi của đơn hàng, tối đa 200 ký tự

payment

Object

✔

Chứa thông loại hình thanh toán Khách hàng lựa chọn :

Key	Type	Bắt Buộc	Mô tả
type	Enum	✔	Loại hình thanh toán (WALLET, LINKED)
linkedId	Number		Linked Id của thẻ liên kết(Bắt buộc nếu loại hình thanh toán là LINKED)

Response:

Key	Type	Mô Tả
code	Number	Mã lỗi: `315000`: Thanh toán thành công `315001`: PartnerTransaction đã tồn tại `315002`: LinkedId không tồn tại (Thanh toán bằng LINKED) `315003`: Số dư ví PayME không đủ(Thanh toán bằng PAYME) `315004`: Tài khoản bị khoá. Không thể thanh toán `315005`: Thanh toán cần xác thực qua webview `315006`: Thanh toán cần xác thực qua OTP `315007`: Thanh toán thất bại (lý do ở message) `315008`: Các lỗi khác (lỗi hệ thống)
message	String	Mô tả thông tin mã lỗi
data	Object	Dữ liệu trả về gồm có thể có các field bên dưới:

Cấu trúc Data :

Key	Type	Mô Tả
transaction	String	mã giao dịch duy nhất dành cho giao dịch này, dùng để verify ở bước sau hoặc ghi nhận nếu thành công dùng cho hoàn/huỷ
form	String	form HTML sẽ cần client client đối tác hiện thị/nhung vào để xử lý với Ngân hàng/Napas xác thực thẻ, sau khi user thao tác thành công/thất bại, trang này sẽ redirect về redirectUrl đã gửi ở request

Example:

Payload mẫu trước khi encrypt:

Nếu thanh toán bằng Ví PayME

{
  "amount" :20000,
  "phone" :"0944074831",
  "description" :"Thanh toán đơn hàng",
  "partnerTransaction": "Pay00001",
  "payment": {
      "type" :"PAYME"
  }
}

Nếu thanh toán bằng thẻ liên kết

{
  "amount" :20000,
  "phone" :"0944074831",
  "description" :"Thanh toán đơn hàng",
  "partnerTransaction": "GenshinPay01",
  "payment": {
      "type" :"LINKED",
      "linkedId": 322344
  }
}

Response mẫu trước khi encrypt:

Trường hợp thanh toán thành công

{
    "code": 315000,
    "message": "Thanh toán thành công",
    "data":
        {
           "transaction" :"112212112"
        }
}

{
    "code": 315005,
    "message": "Thanh toán cần xác thực form",
    "data":
        {
           "transaction" :"112212112",
           "form": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6MzU2NTgsImFjY291bnRJZCI6NTIyNjc3MzMzNiwic2NvcGUiOltdLCJjbGllbnRJZCI6IjA4NEY3REJFLTI3MzUtNEE1OC04NzFGLUFFNzZCMjVCMzVDOSIsImFwcElkIjpudWxsLCJpYXQiOjE2NDE1Mzg5MzR9.JAqsloNsAFy3Vjm3LlWjs_ECMX0EmXUVltZXqp7YvY4"
        }
}

{
    "code": 315006,
    "message": "Thanh toán cần xác thực OTP",
    "data":
        {
           "transaction" :"112212112"
        }
}

5.2 Xác nhận giao dịch

Description: Với những trường hợp cần xác thực giao dịch qua OTP, bên bank sẽ gửi OTP cho khách hàng, sau đó phía đối tác cho KH nhập OTP và gửi cho PayME qua api này để hoàn tất việc thanh toán.
Path: /fe/ewallet/payment/verify
Method: POST

Request Parameters:

Payload:

Key	Type	Required	Description
otp	String	✔	OTP mà bên bank phát hành thẻ của Khách hàng đã gửi
transaction	String	✔	Transaction của giao dịch cần OTP mà PayME đã trả ở API thanh toán
clientId	String	✔	Mã client khách hàng thực hiện giao dịch

Response:

Key	Type	Mô Tả
code	Number	Mã lỗi: `316000`: Thanh toán thành công `316001`: Sai mã xác nhận `316002`: Nhập mã xác nhận sai nhiều lần liên tiếp `316003`: Lỗi hệ thống
message	String	Mô tả thông tin mã lỗi

Request mẫu trước khi encrypt:

{ 
    "activeCode": "233222",
    "transaction" :"223323232"
}

Response mẫu trước khi encrypt:

{
    "code": 316000,
    "message": "Thành công"
}

III. SERVER TO SERVER - API Backend:

Ở mục này sẽ là nhưng API được cấp cho server-side phía tối tác, được gọi từ backend đối tác trực tiếp sang server PayME.

Authentication (mã xác thực) và cặp Key Mã hoá ở các API này sử dụng sẽ là key Thu hộ/Chi Hộ đã khởi tạo ở Dashboard

6. Liên kết tài khoản

6.1 Liên kết 1 user với Ví PayME

Mô tả: API do PayME cung cấp nhằm mục đích tạo liên kết giữa Ví PayME với đối tác khi có user mới muốn sử dụng Ví
API Path: /be/ewallet/account/link
Method : POST

Request Parameters:

Payload:

Key	Type	Required	Description
userId	String(32)	✔	AccountId khách hàng bên đối tác
phone	String(10)	✔	Số điện thoại của khách hàng
kycInfo	Object		Thông tin KYC mà đối tác gửi cho PayME `(1)`.(Chi tiết ở bên dưới)

Thông tin có trong object của kycInfo

Key Required Type Môtả

fullname ✔ String Tên của khách hàng

gender ✔ Enum Giới tính (MALE, FEMALE)

birthday ✔ String Ngày sinh (Dạng DD/MM/YYYY)

address ✔ String Thông tin về địa chỉ của khách hàng

identifyType ✔ Enum Loại thẻ chứng thực (CMND, CCCD)

identifyNumber ✔ String Số CMND, CCCD

issuedAt ✔ String Ngày phát hành thẻ (Dạng DD/MM/YYYY)

placeOfIssue ✔ String Nơi phát hành thẻ

video String URL video quay khuôn mặt của khách hàng

face String URL hình chụp khuôn mặt của khách hàng

image

✔

Object

Object chứa URL hình chụp CMND/CCCD của khách hàng (2):

Key	Type	Bắt Buộc	Mô tả
front	String	✔	URL hình chụp CMND/CCCD (mặt trước)
back	String	✔	URL hình chụp CMND/CCCD (mặt sau)

Response:

Key	Type	Mô Tả
code	Number	Mã lỗi: `316000`: Liên kết thành công `316001`: Lỗi khi liên kết (chi tiết bên dưới) `316002`: Liên kết cần xác thực OTP
message	String	Mô tả thông tin mã lỗi

Ví dụ:

Payload mẫu trước khi encrypt:

{
    "userId": "0944074831",
    "phone": "0944074831",
    "kycInfo":
        {
            "fullname": "Nguyen Le Khang",
            "gender": "MALE",
            "birthday": "08/11/1998",
            "address": "Luong Son - Bac Binh - Binh Thuan",
            "identifyType": "CMND",
            "identifyNumber": "String",
            "issuedAt": "19/01/2019",
            "placeOfIssue": "Binh Thuan",
            "video": "https://sbx-static.payme.vn//2020/10/28/Co-29vnK6.mp4",
            "face": "https://cdn.pixabay.com/photo/2015/04/23/22/00/tree-736885__480.jpg",
            "image":
                {
                    "front": "https://cdn.pixabay.com/photo/2015/04/23/22/00/tree-736885__480.jpg",
                    "back": "https://cdn.pixabay.com/photo/2015/04/23/22/00/tree-736885__480.jpg",
                }
        },
}

Note :

(1) PayME chỉ chấp nhận thông tin này khi có thoả thuận giữa 2 bên. (2) Hình ảnh bắt buộc có cả 2 mặt nếu gửi.

Response mẫu trước khi encrypt:

Trường hợp thành công

{
    "code": 316000,
    "message": "Liên kết Thành công",
    "data": {
        "accessToken": "U2FsdGVkX193ahc9vY2b"
    }
}

Trường hợp cần xác thực OTP

{
    "code": 316002,
    "message": "Liên kết cần xác thực OTP",
    "data": {
        "verifyToken": "U2FsdGVkX193ahc9vY2b"
    }
}

6.2 Xác thực liên kết 1 user với Ví PayME

Mô tả: Khi khách hàng kết nối ví payME lần đầu, lúc này cần xác nhận thông tin OTP từ khách hàng. Payme sẽ tiến hành gửi sms cho KH, sau đó phía đối tác cho KH nhập OTP và gửi kèm verifyToken cho PayME qua api này để hoàn tất liên kết.

API Path: /be/ewallet/account/verifyLink
Method : POST

Request Parameters:

Payload:

Key	Type	Required	Description
activeCode	String(10)	✔	OTP cho số điện thoại mà merchant đã gửi PayME ở API 6.1 (OTP do PayME gửi)
verifyToken	String	✔	verifyToken mà PayME đã trả ở API 6.1

Response:

Key	Type	Mô Tả
code	Number	Mã lỗi: `316100`: Liên kết thành công `316101`: OTP không đúng `316102`: Lỗi khi liên kết (chi tiết ở message)
message	String	Mô tả thông tin mã lỗi

Ví dụ:

Payload mẫu trước khi encrypt:

{
    "verifyToken": "U2FsdGVkX193ahc9vY2b",
    "activeCode": "233232"
}

Response mẫu trước khi encrypt:

Trường hợp thành công

{
    "code": 316100,
    "message": "Liên kết Thành công",
    "data" :{
        "verifyToken": "U2FsdGVkX193ahc9vY2b"
    }
}

Trường hợp thất bại

{
    "code": 316102,
    "message": "Liên kết thất bại. Vui lòng thử lại sau."
}

6.3 Cập nhật thông tin KYC của User

Mô tả: Với User đã liên kết với PayME. Merchant có thể dùng API này để cập nhật lại thông tin KYC của khách hàng .

API Path: /be/ewallet/account/kyc/update
Method : POST

Request Parameters:

Payload:

Key	Type	Required	Description
phone	String(10)	✔	Số điện thoại của khách hàng
kycInfo	Object	✔	Thông tin KYC mà đối tác gửi cho PayME `(1)`.(Chi tiết ở bên dưới)

Thông tin có trong object của kycInfo

Key Required Type Môtả

fullname String Tên của khách hàng

gender Enum Giới tính (MALE, FEMALE)

birthday String Ngày sinh (Dạng DD/MM/YYYY)

address String Thông tin về địa chỉ của khách hàng

identifyType Enum Loại thẻ chứng thực (CMND, CCCD)

identifyNumber String Số CMND, CCCD

issuedAt String Ngày phát hành thẻ (Dạng DD/MM/YYYY)

placeOfIssue String Nơi phát hành thẻ

video String URL video quay khuôn mặt của khách hàng

face String URL hình chụp khuôn mặt của khách hàng

image

Object

Object chứa URL hình chụp CMND/CCCD của khách hàng (2):

Key	Type	Bắt Buộc	Mô tả
front	String		URL hình chụp CMND/CCCD (mặt trước)
back	String		URL hình chụp CMND/CCCD (mặt sau)

Response:

Key	Type	Mô Tả
code	Number	Mã lỗi: `316200`: Cập nhật thành công `316201`: Cập nhật thất bại (chi tiết bên dưới)
message	String	Mô tả thông tin mã lỗi

Ví dụ:

Payload mẫu trước khi encrypt:

Response mẫu trước khi encrypt:

Trường hợp thành công

{
    "code": 316200,
    "message": "Cập nhật thành công"
}

Trường hợp thất bại

{
    "code": 316201,
    "message": "Cập nhật thất bại. Vui lòng thử lại sau."
}

7. Thông tin tài khoản

7.1 API Lấy thông tin tài khoản ví PayME

Mô tả: API do PayME cung cấp dùng để cung cấp thông tin và hiển thị tài khoản
Flow Chart

API Path: /be/ewallet/account
Method : GET

Request Parameters:

Payload:

Key	Type	Required	Description
phone	String	✔	Số điện thoại Khách hàng muốn lấy thông tin

Response:

Key	Type	Mô Tả
code	Number	Mã Lỗi: 300010 Lấy thông tin thành công 300011 Có lỗi xảy ra
message	String	Mô tả thông tin mã lỗi
data	Object	Dữ liệu trả về gồm có các field bên dưới:

Dữ liệu trả về

Key	Type	Mô tả
accountId	Number	ID account
phone	String	Số điện thoại
email	String	Thông Tin Email
kyc	Object	Thông tin kyc (chi tiết bên dưới)
avatar	String	avatar người dùng
gender	Enum	Giới tính người dùng (MALE, FEMALE, OTHER)
birthday	Date	Ngày sinh(DD/MM/YYYYY)
address	String	Địa chỉ liên lạc
isActive	Boolean	Mặc định Active
state	Enum	Trạng Thái Tài khoản (OPENED, LOCKED, TEMPORARY_LOCK)
linked	Boolean	Đã liên kết Ví PayME ?

KYC Object details

Key	Type	Mô tả
identifyNumber	Number	Mã định danh (số cmnd, cccd...)
identifyType	Enum	Hình thức định danh tài khoản (CMND, CCCD)
state	Enum	Trạng Thái KYC (xem chi tiết bên dưới)
reason	String	Lý do từ chối KYC (nếu có)
issuedAt	String	Ngày cấp
placeOfIssue	String	Nơi cấp

Các trạng thái KYC

KYC state	Mô Tả
APPROVED	đã xác nhận KYC
REJECTED	đã từ chối KYC
PENDING	đang chờ duyệt KYC

Ví dụ:

Payload mẫu trước khi encrypt:
```
{
    "phone": "0909000100"
}
```
Response mẫu trước khi encrypt:

{
    code: 300010,
    message: "Lấy thông tin thành công",
    data: {
            accountId: 9,
            phone: "0998999999",
            email: "nvip99@gmail.com",
            kyc: {
                    identifyNumber: 10012123123,
                    identifyType: "CMND",
                    issuedAt: "01/08/1998",
                    state: "APPROVED",
                    reason: null,
                    placeOfIssue: "Công An TPHCM",
        },
            avatar: "http://static.payme.vn/luatnv/hinhanh.png",
            gender: "MALE",
            birthday: "01/08/1998",
            address: "53 Hai Bà Trưng, Phường 8, Thành Phó Đà Lạt, Tỉnh Lâm Đồng",
            isActive: true,
            state: "OPENED",
            linked: true,
    },
}

7.2 API Cập nhật thông tin tài khoản

Mô tả: API do PayME cung cấp dùng để cập nhật thông tin tài khoản
Flow Chart

API Path: /be/ewallet/account
Method : PUT

Request Parameters:

Payload:

Tham Số	Bắt buộc	Kiểu dữ liệu	Ý nghĩa
phone	String	✔	Số điện thoại Khách hàng muốn thay đổi thông tin
email		String	Thông Tin Email
avatar		String	avatar người dùng
address		String	Địa chỉ liên lạc

Response:

Tham Số	Kiểu dữ liệu	Ý nghĩa
code	Number	Mã Lỗi: 300012 Cập nhật thông tin thành công 300013 Cập nhật thông tin thất bại 300014 Email không đúng định dạng
message	String	Mô tả thông tin mã lỗi

Ví dụ:

Payload mẫu trước khi encrypt:

    {
        "phone": "0909000100",
        "email": "nluat999@gmail.com",
        "avatar": "hinhanh.png",
        "address": "615/218 Xo viet nghe Tinh, TPHCM"
    }

Response mẫu trước khi encrypt:

{
    code: 300012,
    message: "Cập nhật thông tin thành công "
}

7.3 API Lấy thông tin số dư

Mô tả: API do PayME cung cấp dùng để lấy thông tin số dư tài khoản
Flow Chart

API Path: /be/ewallet/balance
Method : GET

Request Parameters:

Payload:

Key	Type	Required	Description
phone	String	✔	Số điện thoại Khách hàng muốn lấy thông tin số dư Ví

Response:

Tham Số	Kiểu dữ liệu	Ý nghĩa
code	Number	Mã Lỗi: 300020 Lấy Thông tin ví thành công
message	String	Mô tả thông tin mã lỗi
data	Object	Dữ liệu trả về gồm có các field bên dưới:

Dữ liệu trả về

Tham Số	Kiểu dữ liệu	Ý nghĩa
balance	Number	Thông tin số dư tổng
cash	Number	Số dư khả dụng
lockCash	Number	Số dư tạm khoá

Ví dụ:

Payload mẫu trước khi encrypt: { "phone": "0909000100" }
Response mẫu trước khi encrypt:

{
    code: 300020,
    message: "Lấy Thông tin ví thành công",
    data: { balance: 250000, cash: 210000, lockCash: 40000
    },
}

8. Liên kết thẻ/tài khoản ngân hàng

8.1 API Lên kết thẻ

Mô tả: API do PayME cung cấp với mục đích thực hiện liên kết tài khoản ngân hàng vào ví payME
API Path: /be/ewallet/banking/link
Method : POST

Request Parameters:

Payload :

Tham số	Kiểu dữ liệu	Bắt buộc	Mô tả
phone	String	true	Số điện thoại Khách hàng muốn liên kết
swiftCode	String	false	Mã swiftCode ngân hàng liên kết. Required nếu là ngân hàng nội địa thuộc NAPAS
amount	Number	false	Số tiền cần nạp vào Ví đề xác thực khi liên kết với các ngân hàng yêu cầu xác thực*
env	String	false	Môi trường để lấy Webview liên kết (thẻ Napas). Enum: [MobileApp WebApp]
linkInfo	Object	true	Thông tin thẻ liên kết. (Chỉ chọn 1 trong 3 dạng liên kết)
redirectUrl	String	true	Link redirect khi thanh toán thành công
version	String	false	Version phiên bản app đang sử dụng
clientId	String	true	ID của client đang trong phiên đăng nhập

* Note : đối với các ngân hàng sau sẽ không cần số tiền nạp ban đầu :

PVCombank
OCB
BIDV
VIetinbank

Đối với liên kết thẻ Visa, số tiền luôn là 1000đ

Thông tin linkedInfo object

Tham số	Kiểu dữ liệu	Bắt buộc	Mô tả
card	Object	false	Liên kết số thẻ ngân hàng
account	Object	false	Liên két bằng số tài khoản ngân hàng
credit	Object	false	Liên kết thẻ credit

Thông tin card object

Tham số	Kiểu dữ liệu	Bắt buộc	Mô tả
cardNumber	String	true	Số thẻ
cardHolder	String	true	Tên chủ thẻ
issuedAt	String	true	Ngày phát hành thẻ (MM/YY)
expiredAt	String	false	Ngày hết hạng thẻ (MM/YY)

Thông tin account object
Tham số Kiểu dữ liệu Bắt buộc Mô tả
accountNumber String true Số tài khoản ngân hàng muốn liên kết
Thông tin credit object
Tham số Kiểu dữ liệu Bắt buộc Mô tả
cardNumber String true Số thẻ
expiredAt String true Ngày hết hạn thẻ (MM/YY)
cvv String true Mã bảo mật thẻ
env:
Tên ENV Mô tả
MobileApp Khách hàng đang sử dụng mobile app để thao tác
WebApp Khách hàng đang sử dụng web để thao tác

Response:

Tham số	Kiểu dữ liệu	Mô tả
code	Number	Mã lỗi: `157000`: Liên kết thành công `157010`: Liên kết cần xác thực bằng từ giao diện ngân hàng/napas (dùng html ở data) `157020`: Liên kết cần xác thực bằng mã OTP ngân hàng `157001`: Thất bại (sẽ trả từng message cụ thể khi nhận mã lỗi này) `157002`: Tạm khóa vì sai OTP quá nhiều lần
message	String	Mô tả thông tin mã lỗi
data	object	Data liên kêt (chi tiết bên dưới)
remainingLockedTime	number	Thời gian tạm khóa liên kết thẻ khi liên kết kết thất bại hoặc xác nhận OTP sai nhiều lần.

Thông tin data object

Tham số	Kiểu dữ liệu	Mô tả
linkedId	Number	Mã thẻ liên kết (nếu thành công ngay)
transaction	String	Mã giao dịch khi liên kết
html	String	form HTML sẽ cần client client đối tác hiện thị/nhung vào để xử lý với Ngân hàng/Napas xác thực thẻ, sau khi user thao tác thành công/thất bại, trang này sẽ redirect về redirectUrl đã gửi ở request

Request mẫu trước khi encrypt:

Liên kêt bằng thẻ

{
    "swiftCode": "SBITVNVXK",
    "env": "MobileApp",
    "amount": 20000,
    "linkInfo": {
        "card": {
            "cardNumber": "9704000000000018",
            "cardHolder": "Nguyễn Văn A",
            "issuedAt": "03/07"
        }
    },
    "redirectUrl": "https://google.com.vn",
    "clientId": "XXX-XXX-XXX-XXX"
}

Liên kết bằng account của bank

{
    "swiftCode": "BIDVVNVX",
    "env": "MobileApp",
    "linkInfo": {
        "account": {
            "accountNumber": "12010002100520"
        }
    },
    "redirectUrl": "https://google.com.vn",
    "clientId": "XXX-XXX-XXX-XXX"
}

Liên kết credit

{
    "amount": 1000,
    "linkInfo": {   
        "credit": {}
    },
    "redirectUrl": "https://payme.vn/web/",
    "clientId": "XXX-XXX-XXX-XXX"
}

Response mẫu trước khi encrypt:

Trường hợp liên kết thành công ngay

{
    "code": 157000,
    "message": "Liên kết thành công.",
    "data": {
        "linkedId": 123456969,
        "transaction": "59034859009",
        "html": null
    },
}

Trường hợp liên kết cần thao tác trên giao diện ngân hàng

{
    "code": 157010,
    "message": "Vui lòng xác thực giao dịch.",
    "data": {
        "linkedId": 123456969,
        "transaction": "59034859009",
        "html": "<html xmlns=\"http://www.w3.org/1999/xhtml\">\n  <head>  \n    <title>Liên kết ngân hàng BIDV</title>  \n    <meta     http-equiv=\"refresh\"  content=\"0;URL=https://www.bidv.net/EWALLET/SecureCodeServlet? secureCode=57566569314C48724E4B4B5A34322F6D716853556D513D3D\" />\n  </head>\n  <body></body>\n  </html>",
    },
}

Trường hợp liên kết cần nhập OTP từ ngân hàng,

{
    "code": 157020,
    "message": "Vui lòng xác thực OTP.",
    "data": {
        "linkedId": 123456969,
        "transaction": "59034859009",
        "html": null,
    },
}

8.2 API Xác thực OTP liên kết thẻ

Mô tả: Khi liên kết, nếu là loại thẻ cần xác thật OTP của Ngân hàng , đối tác cần hiện UI cho user nhập OTP này và gửi lại kèm transaction khởi tạo Sau khi payME nhận được OTP sẽ gửi Ngân hàng và xác thực kèm kèm quả trả về
API Path: /be/ewallet/banking/link/verifyOTP
Method: POST

Request Parameters:

Payload :
Tham số Kiểu dữ liệu Bắt buộc Mô tả
transaction String true mã giao dịch khi thanh toán xác thực thẻ
otp String true mã otp của ngân hàng

Response:

Tham số	Kiểu dữ liệu	Mô tả
code	Number	Mã lỗi: `157200`: Xác thực thành công. PayME sẽ tiến hành liên kết thẻ cho user `157201`: Thất bại (sẽ trả từng message cụ thể khi nhận mã lỗi này) `157202`: Mã OTP không đúng. Tiến hành nhập lại. `157203`: Tạm khóa vì sai OTP quá nhiều lần
message	String	Mô tả thông tin mã lỗi
remainingLockedTime	number	Thời gian tạm khóa liên kết thẻ khi liên kết kết thất bại hoặc xác nhận OTP sai nhiều lần.

Request mẫu trước khi encrypt:

{
    "transaction": "4901903683-KYOAQ9SI3",
    "otp": "123456"
}

Response mẫu trước khi encrypt:

{
    "code": 157200,
    "message": "Xác thực thành công."
}

8.3 API Hủy liên kết thẻ

Mô tả: API khi user muốn huỷ liên kết 1 thẻ ATM/CreditCard khỏi tài khoản
API Path: /be/ewallet/banking/unlink
Method: POST

Request Parameters:

Payload :

Tham số	Kiểu dữ liệu	Bắt buộc	Mô tả
phone	String	true	Số điện thoại Khách hàng muốn huỷ liên kết
linkedId	Number	true	Id của thẻ liên kết trong danh sách liên kết
clientId	String	true	id của client đang trong phiên đăng nhập

Response:

Tham số	Kiểu dữ liệu	Mô tả
code	Number	Mã lỗi: `157100`: Xác thực thành công. PayME sẽ tiến hành liên kết thẻ cho user `157100`: Thất bại (sẽ trả từng message cụ thể khi nhận mã lỗi này)
message	String	Mô tả thông tin mã lỗi

Request mẫu trước khi encrypt:

{
    "linkedId": 7589157344,
    "clientId": "clientId"
}

Response mẫu trước khi encrypt:

{
    "code": 157100,
    "message": "Hủy liên kết thành công.",
}

{
    "code": 157101,
    "message": "Hủy liên kết thất bại. Vui lòng thử lại sau.",
}

8.4 API Lấy danh sách thẻ đã liên kết

Mô tả: API để lấy data và hiển thị các thẻ khách hàng đã liên kết với ứng dụng và Ví PayME, dùng đển quản lý, huỷ hoặc thanh toán.
API Path: /be/ewallet/banking/linked
Method: GET

Request Parameters:

Payload :

Key	Type	Required	Description
phone	String	✔	Số điện thoại Khách hàng muốn lấy danh sách thẻ đã liên kết

Response:

Tham số	Kiểu dữ liệu	Mô tả
code	Number	Mã lỗi: `157400`: Liên kết thành công `157401`: Thất bại (sẽ trả từng message cụ thể khi nhận mã lỗi này)
message	String	Mô tả thông tin mã lỗi
data	object	Data liên kêt (chi tiết bên dưới)

Thông tin data object
Tham số Kiểu dữ liệu Mô tả
linkedList Array Chi tiết các thẻ đã liên kết để hiển thị, detail bên dưới
totaLinked Number Tổng số thẻ đã liên kết

Thông tin các phần tử có trong linkedList

Tham số	Kiểu dữ liệu	Mô tả
linkedId	Number	ID thẻ liên kết Ví PayME
linkedAt	DateTime	Thời gian liên kết thẻ
type	String	Loại thẻ liên két (ATM , CREDIT_CARD)
issuer	String	Tên ngân hàng/tổ chức phát hành thẻ
swiftCode	String	swiftCode ngân hàng liên kết
cardNumber	String	Số thẻ (đã che, chỉ hiển thị 4 số đầu và cuối)
accountNumber	String	Số tài khoản ngân hàng (đã che, chỉ hiển thị 4 số cuối)
issuedAt	String	Ngày phát hành
expiredAt	String	Ngày hết hạn thẻ

Response mẫu trước khi encrypt:

{
    "code": 157400,
    "message": "Lấy thông tin thẻ liên kết thành công.",
    "data": {
        "totalLinked": 3,
        "linkedList": [
            {
                "linkedId": 7643352700,
                "linkedAt": "08/02/2022",
                "type": "CREDIT_CARD",
                "issuer": "MASTERCARD",
                "swiftCode": null,
                "cardNumber": "5200********1096",
                "accountNumber": "",
                "issuedAt": "",
                "expiredAt": "10/2024"
            },
            {
                "linkedId": 9555032836,
                "linkedAt": "23/01/2022",
                "type": "ACCOUNT",
                "issuer": "OCB",
                "swiftCode": "ORCOVNVX",
                "cardNumber": "",
                "accountNumber": "************7009",
                "issuedAt": "",
                "expiredAt": ""
            },
            {
                "linkedId": 7630179079,
                "linkedAt": "22/01/2022",
                "type": "ATM",
                "issuer": "SaigonBank",
                "swiftCode": "SBITVNVX",
                "cardNumber": "9704********0018",
                "accountNumber": "",
                "issuedAt": "03/2007",
                "expiredAt": ""
            }
        ]
    }
}

9. Thanh toán

9.1 Thanh toán Đơn hàng cho Khách hàng

Description: Api dùng để thanh toán 1 đơn hàng của Merchant/Doanh nghiệp cho Khách hàng, sau khi gọi API này sẽ có 3 trường hợp xảy ra :
1\ Khách hàng đủ số dư Ví hoặc tiền trong tài khoản Ngân Hàng, và số tiền thanh toán dưới hạn mức cần xác thức => Đơn hàng sẽ được thanh toán ngay lập tức, và IPN về cho đối tác thông qua IPN URL đã khai báo ở key
2\ Số tiền thanh toán quá hạn mức cần xác thực của Ngân hàng phát hành Thẻ => Cần phải xác thực bằng OTP của Ngân hàng => Đối tác sẽ hiển thị UI nhập OTP cho Khách hàng và dùng api 5.2 để hoàn thành giao dịch
3\ Thanh toán thất bại, tuỳ vào mã lỗi thất bại đối tác sẽ báo lỗi cho Khách hàng
Path: /be/ewallet/payment/pay
Method: POST

Request Parameters:

Payload:

Key

Type

Required

Description

amount

Number

✔

Giá trị tiền đơn hàng cần thanh toán

phone

String

✔

Số điện thoại Khách hàng cần thanh toán đơn hàng

partnerTransaction

String

✔

Transaction của đối tác

description

String

Mô tả ngắn gọi của đơn hàng, tối đa 200 ký tự

payment

Object

✔

Chứa thông loại hình thanh toán Khách hàng lựa chọn :

Key	Type	Bắt Buộc	Mô tả
type	Enum	✔	Loại hình thanh toán (WALLET, LINKED)
linkedId	Number		Linked Id của thẻ liên kết(Bắt buộc nếu loại hình thanh toán là LINKED)

Response:

Key	Type	Mô Tả
code	Number	Mã lỗi: `315000`: Thanh toán thành công `315001`: PartnerTransaction đã tồn tại `315002`: LinkedId không tồn tại (Thanh toán bằng LINKED) `315003`: Số dư ví PayME không đủ(Thanh toán bằng PAYME) `315004`: Tài khoản bị khoá. Không thể thanh toán `315005`: Thanh toán cần xác thực qua webview `315006`: Thanh toán cần xác thực qua OTP `315007`: Thanh toán thất bại (lý do ở message) `315008`: Các lỗi khác (lỗi hệ thống)
message	String	Mô tả thông tin mã lỗi
data	Object	Dữ liệu trả về gồm có thể có các field bên dưới:

Cấu trúc Data :

Key	Type	Mô Tả
transaction	String	mã giao dịch duy nhất dành cho giao dịch này, dùng để verify ở bước sau hoặc ghi nhận nếu thành công dùng cho hoàn/huỷ
form	String	form HTML sẽ cần client client đối tác hiện thị/nhung vào để xử lý với Ngân hàng/Napas xác thực thẻ, sau khi user thao tác thành công/thất bại, trang này sẽ redirect về redirectUrl đã gửi ở request

Example:

Payload mẫu trước khi encrypt:

Nếu thanh toán bằng Ví PayME

{
  "amount" :20000,
  "phone" :"0944074831",
  "description" :"Thanh toán đơn hàng",
  "partnerTransaction": "Pay00001",
  "payment": {
      "type" :"PAYME"
  }
}

Nếu thanh toán bằng thẻ liên kết

{
  "amount" :20000,
  "phone" :"0944074831",
  "description" :"Thanh toán đơn hàng",
  "partnerTransaction": "GenshinPay01",
  "payment": {
      "type" :"LINKED",
      "linkedId": 322344
  }
}

Response mẫu trước khi encrypt:

Trường hợp thanh toán thành công

{
    "code": 315000,
    "message": "Thanh toán thành công",
    "data":
        {
           "transaction" :"112212112"
        }
}

{
    "code": 315005,
    "message": "Thanh toán cần xác thực form",
    "data":
        {
           "transaction" :"112212112",
           "form": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6MzU2NTgsImFjY291bnRJZCI6NTIyNjc3MzMzNiwic2NvcGUiOltdLCJjbGllbnRJZCI6IjA4NEY3REJFLTI3MzUtNEE1OC04NzFGLUFFNzZCMjVCMzVDOSIsImFwcElkIjpudWxsLCJpYXQiOjE2NDE1Mzg5MzR9.JAqsloNsAFy3Vjm3LlWjs_ECMX0EmXUVltZXqp7YvY4"
        }
}

{
    "code": 315006,
    "message": "Thanh toán cần xác thực OTP",
    "data":
        {
           "transaction" :"112212112"
        }
}

9.2 Xác nhận giao dịch

Description: Với những trường hợp cần xác thực giao dịch qua OTP, bên bank sẽ gửi OTP cho khách hàng, sau đó phía đối tác cho KH nhập OTP và gửi cho PayME qua api này để hoàn tất việc thanh toán.
Path: /be/ewallet/payment/verify
Method: POST

Request Parameters:

Payload:

Key	Type	Required	Description
otp	String	✔	OTP mà bên bank phát hành thẻ của Khách hàng đã gửi
transaction	String	✔	Transaction của giao dịch cần OTP mà PayME đã trả ở API thanh toán
clientId	String	✔	Mã client khách hàng thực hiện giao dịch

Response:

Key	Type	Mô Tả
code	Number	Mã lỗi: `316000`: Thanh toán thành công `316001`: Sai mã xác nhận `316002`: Nhập mã xác nhận sai nhiều lần liên tiếp `316003`: Lỗi hệ thống
message	String	Mô tả thông tin mã lỗi

Request mẫu trước khi encrypt:

{ 
    "activeCode": "233222",
    "transaction" :"223323232"
}

Response mẫu trước khi encrypt:

{
    "code": 316000,
    "message": "Thành công"
}

9.3 Khởi tạo thanh toán PayME Link

Description: Api dùng để khởi tạo link thanh toán cho Merchant với nhiều phương thức thanh toán được tích hợp sẵn.
Path: /be/widgets/link/create
Method: POST

Request Parameters:

Payload:

Key	Type	Required	Description
amount	Number	✔	Số tiền cần thanh toán
description	String	✔	Nội dung thanh toán, tối đa 200 ký tự
orderRequiredField	Object		Thu thập thông tin khách hàng khi thanh toán
expiredAt	Enum		Thời gian hết hạn link thanh toán Enum: [ TENMINUTES, ONEHOUR, HALFOFDAY, ONEDAY, SEVENDAYS, ONEMONTH] P/S: Mặc định không hết hạn.
attachedFiles	Array		Hình ảnh đính kèm của link thanh toán. Thông tin từng item là một Object

Response:

Key	Type	Mô Tả
code	Number	Mã lỗi: `121000`: Tạo link thanh toán thành công. `121002`: Tạo link thanh toán thất bại (lý do ở message)
message	String	Mô tả thông tin mã lỗi
data	Object	Dữ liệu trả về gồm có thể có các field bên dưới:

Cấu trúc Data :

Key	Type	Mô Tả
linkId	String	Id của link thanh toán PayME Link
paymentLink	String	Url PayME Link
description	String	Nội dung thanh toán
amount	Number	Số tiền thanh toán
currency	String	Đơn vị tiền tệ của link thanh toán
createdBy	Object	Thông tin người tạo link thanh toán
createdAt	DateTime	Thời gian khởi tạo link thanh toán
attachedFiles	Array	Thông tin hình ảnh đính kèm link thanh toán

Example:

Payload mẫu trước khi encrypt:

Nếu thanh toán bằng Ví PayME

{
    "amount": 100000,
    "description": "Anh thợ điện thanh toán tiền nước mía",
    "expiredAt": "ONEDAY",
    "orderRequiredField": {
        "email": true,
        "fullname": true,
        "phone": true,
        "shippingAddress": true
    },
    "attachedFiles": [
        {
            "fileName": "0b16f1e0440cdb133f9cc52bc75d06ad.jpg",
            "url": "/2022/03/07/hExvL6XYg.jpg"
        },
        {
            "fileName": "0b16f1e0440cdb133f9cc52bc75d05ad.jpg",
            "url": "/2022/03/07/hExvL6XYg.jpg"
        }
    ]
}

Response mẫu trước khi encrypt:

Trường hợp tạo PayME Link thành công

{
    "code": 121000,
    "message": "Tạo link thành công",
    "data": {
        "linkId": "jyll8r",
        "paymentLink": "https://sbx.payme.vn/l/jyll8r",
        "description": "Anh thợ điện thanh toán tiền nước mía",
        "amount": 100000,
        "currency": "VND",
        "createdBy": {
            "email": "vula@payme.com",
            "phone": "84917922010",
            "merchantId": 986933,
            "accountId": 9012784179
        },
        "createdAt": "2022-03-07T08:37:55.177Z",
        "attachedFiles": [
            {
                "fileName": "0b16f1e0440cdb133f9cc52bc75d06ad.jpg",
                "url": "https://static.com.vn/2022/03/07/hExvL6XYg.jpg"
            },
            {
                "fileName": "0b16f1e0440cdb133f9cc52bc75d05ad.jpg",
                "url": "https://static.com.vn/2022/03/07/hExvL6XYg.jpg"
            }
        ]
    }
}

Trường hợp tạo PayME Link thất bại

{
    "code": 121002,
    "message": "Không tìm thấy thông tin merchant",
    "data":{}
}

10. Nạp tiền Ví

10.1 Nạp tiền từ thẻ liên kết vào ví

Description: Api dùng để nạp tiền vào ví dành cho số điện thoại đã liên kết với PayME
Path: /be/ewallet/deposit/linked
Method: POST

Request Parameters:

Payload:

Key	Type	Required	Description
phone	Number	✔	Số điện thoại của người dùng
amount	String	✔	Số tiền cần nạp
linkedId	Number	✔	LinkedId của thẻ đã liên kết (Lấy được từ API lấy danh sách thẻ liên kết (8.4))
ipnUrl	String		Thông báo kết quả giao dịch nạp cho đối tác

Response:

Key	Type	Mô Tả
code	Number	Mã lỗi: `317000`: Nạp tiền thành công. `317001`: Nạp tiền thất bại (lý do ở message) `317002`: Nạp tiền cần xác thực OTP `317003`: Nạp tiền cần xác thực từ ngân hàng
message	String	Mô tả thông tin mã lỗi
data	Object	Dữ liệu trả về gồm có thể có các field bên dưới:

Cấu trúc Data :

Key	Type	Mô Tả
transaction	String	Mã giao dịch của PayME

Example:

Payload mẫu trước khi encrypt:

{
    "phone": "0944074831",
    "amount": 20000,
    "linkedId": 466737373
}

Response mẫu trước khi encrypt:

Trường hợp nạp tiền thành công

{
    "code": 317000,
    "message": "Nạp tiền thành công",
    "data": {
        "transaction": "7484857874"
    }
}

Trường hợp nạp tiền thất bại

{
    "code": 317001,
    "message": "Nạp tiền thất bại",
    "data":{
        "transaction": "7484857874"
    }
}

Trường hợp nạp tiền cần xác thực OTP

{
    "code": 317002,
    "message": "Nạp tiền cần xác thực OTP",
    "data":{
        "transaction": "7484857874"
    }
}

Trường hợp nạp tiền cần xác thực từ ngân hàng

{
    "code": 317003,
    "message": "Nạp tiền cần xác thực từ ngân hàng",
    "data":{
        "transaction": "7484857874",
        "html": "<html xmlns=\"http://www.w3.org/1999/xhtml\">\n  <head>  \n    <title>Liên kết ngân hàng BIDV</title>  \n    <meta     http-equiv=\"refresh\"  content=\"0;URL=https://www.bidv.net/EWALLET/SecureCodeServlet? secureCode=57566569314C48724E4B4B5A34322F6D716853556D513D3D\" />\n  </head>\n  <body></body>\n  </html>",
    }
}

10.2 Xác thực nạp tiền từ thẻ liên kết

Description: Api dùng để xác thực việc nạp tiền vào ví dành cho số điện thoại đã liên kết với PayME trong trường hợp yêu cầu xác thực Ngân hàng
Path: /be/ewallet/deposit/verifyLinked
Method: POST

Request Parameters:

Payload:

Key	Type	Required	Description
phone	String	✔	Số điện thoại của người dùng
transaction	String	✔	Mã giao dịch của PayME ở API nạp tiền vào ví (10.1)
otp	String	✔	OTP của ngân hàng đã trả về SDT của khách hàng

Response:

Key	Type	Mô Tả
code	Number	Mã lỗi: `317100`: Nạp tiền thành công. `317101`: Nạp tiền thất bại (lý do ở message) `317102`: OTP không chính xác
message	String	Mô tả thông tin mã lỗi
data	Object	Dữ liệu trả về gồm có thể có các field bên dưới:

Cấu trúc Data :

Key	Type	Mô Tả
transaction	String	Mã giao dịch của PayME

Example:

Payload mẫu trước khi encrypt:

{
    "phone": "0944074831",
    "otp": "453344",
    "transaction": "37373773"
}

Response mẫu trước khi encrypt:

Trường hợp nạp tiền thành công

{
    "code": 317100,
    "message": "Nạp tiền thành công",
    "data": {
        "transaction": "7484857874"
    }
}

Trường hợp nạp tiền thất bại

{
    "code": 317101,
    "message": "Nạp tiền thất bại",
    "data":{
        "transaction": "7484857874"
    }
}

Trường hợp sai OTP

{
    "code": 317102,
    "message": "OTP không chính xác"
}

11. Rút tiền

11.1 Rút tiền về thẻ ngân hàng đã liên kết

Description: Api dùng để rút tiền về thẻ ngân hàng đã liên kết dành cho số điện thoại đã liên kết với PayME
Path: /be/ewallet/withdraw/linked
Method: POST

Request Parameters:

Payload:

Key	Type	Required	Description
phone	Number	✔	Số điện thoại của người dùng
amount	String	✔	Số tiền cần rút
linkedId	Number	✔	LinkedId của thẻ đã liên kết (Lấy được từ API lấy danh sách thẻ liên kết (8.4))

Response:

Key	Type	Mô Tả
code	Number	Mã lỗi: `318000`: Rút tiền thành công. `318001`: Rút tiền cần xác thực OTP `318002`: Rút tiền thất bại (lý do ở message)
message	String	Mô tả thông tin mã lỗi
data	Object	Dữ liệu trả về gồm có thể có các field bên dưới:

Cấu trúc Data :

Key	Type	Mô Tả
transaction	String	Mã giao dịch của PayME

Example:

Payload mẫu trước khi encrypt:

Nếu thanh toán bằng Ví PayME

{
    "phone": "0944074831",
    "amount": 20000,
    "linkedId": 466737373
}

Response mẫu trước khi encrypt:

Trường hợp rút tiền thành công

{
    "code": 318000,
    "message": "Rút tiền thành công",
    "data": {
        "transaction": "7484857874"
    }
}

Trường hợp rút tiền cần xác thực OTP

{
    "code": 318001,
    "message": "Rút tiền cần xác thực OTP",
    "data":{
        "transaction": "7484857874"
    }
}

Trường hợp rút tiền thất bại

{
    "code": 318002,
    "message": "Rút tiền thất bại",
    "data":{
        "transaction": "7484857874"
    }
}

11.2 Xác thực việc rút tiền về thẻ ngân hàng đã liên kết

Description: Api dùng để xác thực việc rút tiền về thẻ ngân hàng liên kết dành cho số điện thoại đã liên kết với PayME trong trường hợp yêu cầu xác thực Ngân hàng
Path: /be/ewallet/withdraw/linked/verify
Method: POST

Request Parameters:

Payload:

Key	Type	Required	Description
phone	String	✔	Số điện thoại của người dùng
transaction	String	✔	Mã giao dịch của PayME ở API rút tiền vào ví (11.1)
otp	String	✔	OTP của PayME đã trả về SDT của khách hàng

Response:

Key	Type	Mô Tả
code	Number	Mã lỗi: `318100`: Rút tiền thành công. `318101`: Sai OTP `318102`: Rút tiền thất bại(lý do ở message)
message	String	Mô tả thông tin mã lỗi
data	Object	Dữ liệu trả về gồm có thể có các field bên dưới:

Cấu trúc Data :

Key	Type	Mô Tả
transaction	String	Mã giao dịch của PayME

Example:

Payload mẫu trước khi encrypt:

{
    "phone": "0944074831",
    "otp": "453344",
    "transaction": "37373773"
}

Response mẫu trước khi encrypt:

Trường hợp nạp tiền thành công

{
    "code": 318100,
    "message": "Rút tiền thành công",
    "data": {
        "transaction": "7484857874"
    }
}

Trường hợp sai OTP

{
    "code": 318101,
    "message": "OTP không chính xác"
}

Trường hợp nạp tiền thất bại

{
    "code": 318102,
    "message": "Rút tiền thất bại",
    "data":{
        "transaction": "7484857874"
    }
}

12. Chuyển tiền

12.1 Chuyển tiền đến ví hoặc bank

Description: Api dùng để chuyển tiền đến ví PayME khác hoặc ngân hàng
Path: be/ewallet/transfer
Method: POST

Request Parameters:

Payload:

Key	Type	Required	Description
amount	Number	✔	Giá trị tiền đơn hàng cần thanh toán
phone	String	✔	Số điện thoại Khách hàng cần thanh toán đơn hàng
description	String		Mô tả ngắn gọi ủa đơn hàng, tối đa 200 ký tự
transport	Object	✔	Chứa thông tin phương thức chuyển tiền cho khách hàng lựa chọn, chỉ cho chọn 1 trong 3 phương thức

transport Object

Key	Type	Description
wallet	Object	Chuyển tiền đến ví
bankCard	Object	Chuyển tiền đến thẻ ngân hàng
bankAccount	Object	Chuyển tiền đến tài khoản ngân hàng

wallet Object

Key	Type	Required	Description
phone	String	✔	Số điện thoại người nhận

bankCard Object

Key	Type	Required	Description
cardNumber	String	✔	Số thẻ người nhận
cardHolder	String	✔	Tên người nhận trên thẻ
swiftCode	String	✔	Mã ngân hàng

bankAccount Object

Key	Type	Required	Description
accountNumber	String	✔	Số tài khoản người nhận
accountHolder	String	✔	Tên người nhận trên tài khoản
swiftCode	String	✔	Mã ngân hàng

Key	Type	Description
code	Number	Mã lỗi: `319000`: Chuyển tiền thành công `319001`: Chuyển tiền cần xác nhận OTP `319002`: Số dư ví không đủ để thực hiện chuyển tiền `319003`: Thông tin người nhận không tồn tại `319005`: Hệ thống đang bảo trì `319902`: Tài khoản chưa được KYC `319904`: Không thể chuyển tiền cho chính mình `319905`: Số điện thoại này chưa liên kết với Ví PayME `319906`: Tài khoản không được cấp quyền chuyển `319907`: Phương thức chuyển tiền không được hỗ trợ `319100`: Chuyển tiền thành công `319101`: Mã xác thực không đúng `319102`: SDT đã sai mã xác nhận nhiều lần `319103`: Hệ thống đang bảo trì `319105`: Mã xác nhận đã hết hạn `319106`: Chuyển tiền thất bại
message	String	Mô tả thông tin mã lỗi
data	Object	Dữ liệu trả về gồm có thể có các field bên dưới

Cấu trúc Data :

Key	Type	Mô Tả
transaction	String	Transaction được tạo ra ở hệ thống PayME

Example:

Payload mẫu trước khi encrypt:

Nếu chuyển tiền đến Ví PayME

{
    "amount": 20000,
    "phone": "0704464413",
    "description": "Chuyen tien ne",
    "transport": {
        "wallet": {
            "phone": "0704464414"
        }
    }
}

Nếu chuyển tiền đến thẻ ngân hàng

{
    "amount": 20000,
    "phone": "0944074831",
    "description": "Chuyen tien ne",
    "transport": {
        "bankCard": {
            "cardNumber": "9704000000000018",
            "cardHolder": "Nguyen Van A",
            "swiftCode": "SBITVNVX"
        }
    }
}

Response mẫu trước khi encrypt:

Trường hợp thanh toán thành công

{
    "code": 319000,
    "message": "Chuyen tien thanh cong",
    "data": {
        "transaction": "112212112"
    }
}

{
    "code": 319001,
    "message": "Chuyển tiền cần xác nhận OTP",
    "data": {
        "transaction": "5613807813"
    }
}

12.2 Xác nhận giao dịch

Description: Với những trường hợp cần xác thực giao dịch qua OTP, bên PayME sẽ gửi OTP cho khách hàng, sau đó phía đối tác cho KH nhập OTP và gửi cho PayME qua api này để hoàn tất việc chuyen tien.
Path: be/ewallet/verifyTransfer
Method: POST

Request Parameters:

Payload:

Key	Type	Required	Description
phone	String	✔	Số tiền thoại của khách hàng
otp	String	✔	OTP mà bên bank phát hành thẻ của Khách hàng đã gửi
transaction	String	✔	Transaction của giao dịch cần OTP mà PayME đã trả ở API thanh toán

Response:

Key	Type	Description
code	Number	Mã lỗi: `319902`: Tài khoản chưa được KYC `319904`: Không thể chuyển tiền cho chính mình `319905`: Số điện thoại này chưa liên kết với Ví PayME `319906`: Tài khoản không được cấp quyền chuyển `319907`: Phương thức chuyển tiền không được hỗ trợ `319000`: Chuyển tiền thành công `319101`: Mã xác thực không đúng `319102`: SDT đã sai mã xác nhận nhiều lần `319103`: Hệ thống đang bảo trì `319105`: Mã xác nhận đã hết hạn `319106`: Chuyển tiền thất bại
message	String	Mô tả thông tin mã lỗi
data	Object	Dữ liệu trả về gồm có thể có các field bên dưới

Cấu trúc Data :

Key	Type	Mô Tả
transaction	String	Transaction được tạo ra ở hệ thống PayME

Request mẫu trước khi encrypt:

{
    "otp": "233222",
    "transaction": "223323232"
}

Response mẫu trước khi encrypt:

{
    "code": 319000,
    "message": "Thành công",
   "data": {
       "transaction": "223323232"
   }
}

13. Tạo yêu cầu ghi nhận thanh toán

Request

POST /be/payment/direct/ipn

Authenication

DEFAULT

Payload

Key	Required	Type	Mô tả
amount	Yes	Number	Số tiền thanh toán
partnerTransaction	Yes	String	Mã đối tác, nếu truyền trạng thái REFUNDED thì cần truyền đúng mã partnerTransaction cần REFUNDED
state	Yes	Enum	Trạng thái đơn hàng : SUCCEEDED, FAILED,REFUNDED
desc	Yes	String	Mô tả nội dung thanh toán của khách hàng
payMethod	Yes	String	Loại hình thanh toán nếu Merchant chỉ định nếu có, nếu không sẽ cho user chọn
currency	No	String	Đơn vị tiền tệ. Mặc định là VND
extraData	No	String	Thông tin bổ sung
username	No	String	Username của user
payData	No	Object	Thông tin cần bổ xung với các phương thức thanh toán có yêu cầu thêm
lang	No	String	Ngôn ngữ hiển thị. Mặc định là vi

Cấu trúc object payData:

Key	Type	Mô tả
swiftcode	String	Swiftcode ngân hàng, Required khi payMethod: ATMCARD/FACEID
card_number	String	Số thẻ ngân hàng
card_holder	String	Tên chủ thẻ
issue_date	String	Thời gian hết hạn

Request mẫu trước khi encrypt:

{
  "amount": 100000,
  "currency": "VND",
  "storeId": 9,
  "desc": "test run dev ATM",
  "partnerTransaction": "994474795288356",
  "payMethod": "ATMCARD",
  "payData": {
    "card_number": "9704000000000018",
    "card_holder": "NGUYEN VAN A",
    "issue_date": "03/07",
    "swiftcode": "TPBVVNVX"
  },
  "state":"SUCCEEDED"
  "lang": "vi"
}

Response

Key	Type	Mô tả
code	Number	Mã lỗi
message	String	Mô tả thông tin mã lỗi
data	Object	Nếu thành công sẽ là 1 object data các thông tin cần thiết

Cấu trúc object data:

Key	Type	Mô tả
state	String	Trạng thái thanh toán
transaction	String	Mã giao dịch của Lệnh thanh toán
partnerTransaction	String	Mã giao dịch của MC
paymentId	String	Mã thanh toán

Response mẫu trước khi encrypt:

{
    "code": 105000,
    "message": "Tạo đơn thanh toán thành công",
    "data": {
        "transaction": "TM158IV850QZ",
        "partnerTransaction": "225253335266",
        "paymentId": "MKIXBQTSHCPB",
        "state": "REFUNDED"
    }
}

Mã lỗi

Mã lỗi	Mô tả
105000	Tạo đơn thanh toán thành công
100100	Không tìm thấy thông tin doanh nghiệp
100101	Không tìm thấy thông tin tài khoản
100102	Không tìm thấy thông tin điểm giao dịch
100106	Điểm giao dịch này không hoạt động
100108	Doanh nghiệp chưa đăng ký phương thức này
105101	Mã giao dịch đối tác đã tồn tại
105102	Phương thức thanh toán này đang tạm đóng
105103	Doanh nghiệp chưa đăng ký phương thức thanh toán này
105104	Cập nhật dữ liệu giao dịch thất bại
128102	Không tìm thấy phương thức thanh toán
128104	Đơn hàng không tồn tại
128105	Yêu cầu thanh toán này đã được hoàn tất trước đó
128106	Yêu cầu thanh toán thất bại
129104	Chưa cấu hình thanh toán
129010	Cập nhật thông tin thanh toán thất bại
129011	Yêu cầu thanh toán đã tạo trước đó
105119	Thông tin payData không hợp lệ