II. Đặ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

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:

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.
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
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
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ệ
505	EXCEPTION	System error	Có lỗi không xác định
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ệ
422	INVALID_PARAMS	Merchant error	Tham số truyền vào 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
VIETQR	VIETQR	VietQR	Thanh toán chuyển khoản bằng mã QR
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)
FACEID	FACE_ID	FaceId	Thanh toán bằng FaceId
MOMO	MOMO	Ví MoMo	Thanh toán qua ví MoMo

1.5. API Lấy chi nhánh ngân hàng:

• Mô tả: API do PayME cung cấp lấy thông tin chi nhánh ngân hàng

• API Path: /utility/bank/branch

• Method: POST

Request Parameters:

• Payload :

Tham số	Kiểu dữ liệu	Bắt buộc	Ý nghĩa
swiftCode	String (256)	✔	swiftCode của ngân hàng
lang	String		Ngôn ngữ hiển thị vi/en

• Response:

Key	Type	Mô Tả
code	Number	Mã lỗi: 113700: Lấy danh sách chi nhánh ngân hàng thành công 113701: Lấy danh sách chi nhánh ngân hàng thất bại
message	String	Mô tả thông tin mã lỗi
data	Array	Dữ liệu trả về gồm danh sách Object có các field bên dưới:

Cấu trúc mỗi phần tử trong data :

Key	Type	Mô Tả
branchCode	String	Mã code chi nhánh ngân hàng (mã dùng để chuyển tiền)
branchName	String	Tên chi nhánh ngân hàng

Ví dụ:

• Payload mẫu trước khi encrypt:

{
  "swiftCode": "BFTVVNVX" 
}

• Response mẫu trước khi encrypt:

{
  "code": 113700,
  "message": 'Lấy danh sách chi nhánh ngân hàng thành công',
  "data": [
    {
      branchCode: '01203001',
      branchName: 'NHTMCP NGOAI THUONG-VIET NAM (NHTMCP Ngoai Thuong)'
    },
    {
      branchCode: '01203002',
      branchName: 'NHTMCP NGOAI THUONG-SGD (NHTMCP Ngoai Thuong)'
    },
    {
      branchCode: '01203003',
      branchName: 'NHTMCP NGOAI THUONG-CN HA NOI (NHTMCP Ngoai Thuong)'
    },
    {
      branchCode: '01203004',
      branchName: 'NHTMCP NGOAI THUONG-CN THANG LONG (NHTMCP Ngoai Thuong)'
    }
  ]
}

1.6. Danh sách ngân hàng cần gửi chi nhánh

SwiftCode	Tên viết tắt	Tên đầy đủ
ABOCVNVX	ABC	NH NONG NGHIEP TRUNG QUOC (AGRI BANK OF CHINA)
ANZBVNVX	ANZ	NH ANZ Viet Nam
BKKBVNVX	BANGKOK BANK	Bangkok Bank
BKKBTHBK	BANGKOK BANK PUBLIC	NGAN HANG BANGKOK DAI CHUNG TRACH NHIEM HUU HAN
BKIDVNVX	BANK OF INDIA	Bank Of India HCM Branch
BNPAVNVN	BNP PARIBAS	NGAN HANG BNP PARIBAS
BKCHVNVX	BOC	Bank of China
COMMVNVX	BOComm	Bank of Communication
BFCEVNVX	BPCE IOM	BPCE International et Outre-Mer
BFCEVNVX	BPCEIOM	NH BPCEIOM
PUSBVNVX	BUSAN BANK	Busan Bank Co Ltd
UWCBVNVX	CATHAY BANK	Cathay Bank
PCBCVNVX	CCB	China Construction Bank
CITIVNVX	CITIBANK	CitiBank Viet Nam
CTCBVNVX	CTBC Bank	Chinatrust Commercial Bank
DAEBVNVX	DAEGU BANK	Ngan hang Daegu
DEUTVNVX	DEUTSCHE BANK	Deutsche Bank Viet Nam
ESUNVNVX	E.SUN BANK	E.SUN Commercial Bank Ltd
FCBKVNVX	FCB	First Commercial Bank
HNBKVNVX	HNCB	Hua Nan Commerecial Bank
ICBKVNVN	ICBC	NH Cong Thuong Trung Quoc
CHASVNVX	JP MORGAN CHASE	JP Morgan Chase Bank
KASIVNVX	KASIKORNBANK PUBLIC	NH DAI CHUNG TNHH KASIKORNBANK
KOEXVNVX	KEB Hana Bank	Korea Exchange Bank
KOEXVN2X	KEB Hana Bank HCM	Korean Exchange Bank HCM
CZNBVNVX	KOOKMIN BANK	Kookmin Bank
LAOVLALAXXX	LVB	NH lien doanh Viet Lao
MBBEVNVX	MALAYAN BANKING BERHAD	Malayan Banking Berhad
MBBEVNVX	MAY BANK	May Bank
ICBCVNVX	MEGA ICBC	Mega ICBC
MHCBVNVX	MIZUHO	Mizuho Bank LTD
BOTKVNVX	MUFG	Bank of Tokyo Mitsubishi
OCBCVNVX	OCBC	Oversea Chinese Banking Corp
SCSBVNVX	SCSB	Shanghai Commercial & Savings
SICOVNVX	SIAM COMMERCIAL BANK	NH The Siam Commercial Bank Public
SINOVNVX	SINOPAC	NGAN HANG SINOPAC
SMBCVNVX	SMBC	Sumitomo Mitsui Bank
TPBKVNVX	TAIPEI FUBON	Taipei Fubon Bank
SICOVNVX	THE SIAM	NH The Siam Commercial Bank Public
GTBAVNVX	VNCB	NH Xay Dung VN

1.7. API Tạo khách hàng

• Mô tả: API do PayME cung cấp để tạo khách hàng cho doanh nghiệp

• API Path: /customer

• Method: POST

Request Parameters:

• Payload :

Tham số	Kiểu dữ liệu	Bắt buộc	Ý nghĩa
fullName	String	✔	Tên của khách hàng
phoneNumber	String	✔	Số điện thoại của khách hàng
email	String	✔	Email của khách hàng
address	String		Địa chỉ của khách hàng
isQrCode	Boolean		Cấp số tài khoản ảo cho khách hàng
language	Boolean		Ngôn ngữ hiển thị vi/en

• Response:

Key	Type	Mô Tả
code	Number	Mã lỗi: 1011000: Tạo khách hàng thành công 1011001: Email không hợp lệ 1011002: Số điện thoại không hợp lệ 1011004: Địa chỉ không tồn tại 1011006: Tạo khách hàng thất bại
message	String	Mô tả thông tin mã lỗi
data	Object	Dữ liệu trả về là Object có các field bên dưới:

Cấu trúc của Object data :

Key	Type	Mô Tả
customerId	String	Mã định danh khách hàng
fullName	String	Tên của khách hàng
phoneNumber	String	Số điện thoại của khách hàng
email	String	Email của khách hàng
address	String	Địa chỉ của khách hàng
bankInfo	Object	Thông tin tài khoản ảo (nếu có truyền isQrCode = true)
createdAt	Date	Thời gian tạo

Cấu trúc object bankInfo

Key	Type	Mô tả
number	String	Số tài khoản ngân hàng
fullName	String	Tên người thụ hưởng
swiftCode	String	Mã định danh ngân hàng
bankName	String	Tên ngân hàng

Ví dụ:

• Payload mẫu trước khi encrypt:

{
  "fullName": "Khách hàng 1",
  "phoneNumber": "0987654321",
  "email": "khachhang1@email.com",
  "address": "30B Mai Chí Thọ, Khu Sala, Quận 2, TPHCM",
  "isQrCode": true
}

• Response mẫu trước khi encrypt:

{
  "code": 1011000,
  "message": 'Tạo khách hàng thành công',
  "data": {
    customerId: "176897325",
    fullName: "Khách hàng 1",
    phoneNumber: "0987654321",
    email: "khachhang1@email.com",
    address: "30B Mai Chí Thọ, Khu Sala, Quận 2, TPHCM",
    bankInfo: {
      number: "902000703024",
      fullName: "PAY KHACH HANG 1",
      swiftCode: "HVBKVNVX",
      bankName: "WOO"
    }
    createdAt: 2022-03-07T08:37:55.177Z,
  }
}

1.8. API Lấy thông tin khách hàng

• Mô tả: API do PayME cung cấp để lấy thông tin khách hàng của doanh nghiệp

• API Path: /customer/query

• Method: POST

Request Parameters:

• Payload :

Tham số	Kiểu dữ liệu	Bắt buộc	Ý nghĩa
customerId	String	✔	Mã định danh khách hàng
language	String	✔	Ngôn ngữ hiển thị vi/en. Mặc định: vi

• Response:

Key	Type	Mô Tả
code	Number	Mã lỗi: 1013000: Lấy thông tin khách hàng thành công 1013001: Lấy thông tin khách hàng thất bại 1013002: Không tìm thấy thông tin khách hàng
message	String	Mô tả thông tin mã lỗi
data	Object	Dữ liệu trả về là Object có các field bên dưới:

Cấu trúc của Object data :

Key	Type	Mô Tả
customerId	String	Mã định danh khách hàng
fullName	String	Tên của khách hàng
phoneNumber	String	Số điện thoại của khách hàng
email	String	Email của khách hàng
address	String	Địa chỉ của khách hàng
bankInfo	Object	Thông tin tài khoản ảo
createdAt	Date	Thời gian tạo

Cấu trúc object bankInfo

Key	Type	Mô tả
number	String	Số tài khoản ngân hàng
fullName	String	Tên người thụ hưởng
swiftCode	String	Mã định danh ngân hàng
bankName	String	Tên ngân hàng

Ví dụ:

• Payload mẫu trước khi encrypt:

{
  "customerId": "176897325",
  "language": "vi"
}

• Response mẫu trước khi encrypt:

{
  "code": 1013000,
  "message": 'Lấy thông tin khách hàng thành công',
  "data": {
    customerId: "176897325",
    fullName: "Khách hàng 1",
    phoneNumber: "0987654321",
    email: "khachhang1@email.com",
    address: "30B Mai Chí Thọ, Khu Sala, Quận 2, TPHCM",
    bankInfo: {
      number: "902000703024",
      fullName: "PAY KHACH HANG 1",
      swiftCode: "HVBKVNVX",
      bankName: "WOO"
    }
    createdAt: 2022-03-07T08:37:55.177Z,
  }
}

1.9. API Cấp tài khoản ảo cho khách hàng

• Mô tả: API do PayME cung cấp để cấp tài khoản ảo cho khách hàng của doanh nghiệp

• API Path: /customer/account/link

• Method: POST

Request Parameters:

• Payload :

Tham số	Kiểu dữ liệu	Bắt buộc	Ý nghĩa
customerId	String	✔	Mã định danh khách hàng
language	String		Ngôn ngữ hiển thị vi/en

• Response:

Key	Type	Mô Tả
code	Number	Mã lỗi: 1011010: Thêm liên kết tài khoản ảo của khách hàng thành công 1011013: Không tìm thấy thông tin khách hàng 1011012: Khách hàng đã có tài khoản liên kết 1011011: Thêm liên kết tài khoản ảo của khách hàng thất bại
message	String	Mô tả thông tin mã lỗi
data	Object	Dữ liệu trả về là Object có các field bên dưới:

Cấu trúc của Object data :

Key	Type	Mô Tả
customerId	String	Mã định danh khách hàng
fullName	String	Tên của khách hàng
phoneNumber	String	Số điện thoại của khách hàng
email	String	Email của khách hàng
address	String	Địa chỉ của khách hàng
bankInfo	Object	Thông tin tài khoản ảo
createdAt	Date	Thời gian tạo

Cấu trúc object bankInfo

Key	Type	Mô tả
number	String	Số tài khoản ngân hàng
fullName	String	Tên người thụ hưởng
swiftCode	String	Mã định danh ngân hàng
bankName	String	Tên ngân hàng

Ví dụ:

• Payload mẫu trước khi encrypt:

{
  "customerId": "176897325"
}

• Response mẫu trước khi encrypt:

{
  "code": 1011010,
  "message": 'Thêm liên kết tài khoản ảo của khách hàng thành công',
  "data": {
    customerId: "176897325",
    fullName: "Khách hàng 1",
    phoneNumber: "0987654321",
    email: "khachhang1@email.com",
    address: "30B Mai Chí Thọ, Khu Sala, Quận 2, TPHCM",
    bankInfo: {
      number: "902000703024",
      fullName: "PAY KHACH HANG 1",
      swiftCode: "HVBKVNVX",
      bankName: "WOO"
    }
    createdAt: 2022-03-07T08:37:55.177Z,
  }
}

1.9. API xóa tài khoản ảo của khách hàng

• Mô tả: API do PayME cung cấp để xóa tài khoản ảo của khách hàng của doanh nghiệp

• API Path: /customer/account/unlink

• Method: POST

Request Parameters:

• Payload :

Tham số	Kiểu dữ liệu	Bắt buộc	Ý nghĩa
customerId	String	✔	Mã định danh khách hàng
language	String		Ngôn ngữ hiển thị vi/en

• Response:

Key	Type	Mô Tả
code	Number	Mã lỗi: 1011020: Xóa liên kết tài khoản ảo của khách hàng thành công 1011009: Xóa liên kết tài khoản ảo của khách hàng thất bại 1011013: Không tìm thấy thông tin khách hàng 1011014: Khách hàng chưa liên kết tài khoản ảo
message	String	Mô tả thông tin mã lỗi
data	Object	Dữ liệu trả về là Object có các field bên dưới:

Cấu trúc của Object data :

Key	Type	Mô Tả
customerId	String	Mã định danh khách hàng
fullName	String	Tên của khách hàng
phoneNumber	String	Số điện thoại của khách hàng
email	String	Email của khách hàng
address	String	Địa chỉ của khách hàng

Ví dụ:

• Payload mẫu trước khi encrypt:

{
  "customerId": "176897325"
}

• Response mẫu trước khi encrypt:

{
  "code": 1011008,
  "message": "Xóa liên kết tài khoản ảo của khách hàng thành công",
  "data": {
    customerId: "176897325",
    fullName: "Khách hàng 1",
    phoneNumber: "0987654321",
    email: "khachhang1@email.com",
    address: "30B Mai Chí Thọ, Khu Sala, Quận 2, TPHCM"
  }
}

2. Thanh Toán

2.1. API Tạo Đơn Hàng:

• Mô tả: API do PayME cung cấp, MC server gọi sang PayME để tạo link thanh toán đơn hàng

• API Path: /payment/web

• Method: POST

Request Parameters:

• Payload :

Tham số	Kiểu dữ liệu	Bắt buộc	Ý nghĩa
partnerTransaction	String(32)	✔	Mã giao dịch của của đơn hàng do MC tạo ra là duy nhất và không cho phép gửi trùng, dùng để truy vẫn giao dịch
amount	Number	✔	Giá trị đơn hàng
desc	String (256)	✔	Mô tả đơn hàng để hiển thị cho khách hàng
ip	String	✔	Địa chỉ ip của khách hàng kết nối đến server của doanh nghiệp
payMethod	Enum		Phương thức thanh toán, bạn có thể xem PTTT tại đây
title	String (128)		Tiêu đề đơn hàng
ipnUrl	String		PayME sẽ thông báo trạng thái thanh toán của đơn hàng khi thanh toán hoàn tất; ipnUrl được gọi để thông báo kết quả thanh toán thành công. Nếu không được cung cấp, ipnUrl mặc định của ứng dụng sẽ được sử dụng.
extraData	String(1024)		Thông tin thêm cho thanh toán, dữ liệu sẽ được callback đến ipnUrl sau khi kết thúc giao dịch
customerInfo	Object		Thông tin của khách hàng khi muốn tạo thông tin chuyển khoản hoặc mã qr cố định Key Type Bắt buộc Mô Tả phone String ✔ Số điện thoại fullName String ✔ Tên đầy đủ address String Địa chỉ email String Địa chỉ email
payData	Object		Thông tin cần để thanh toán, tương ứng với mỗi phương thức (mặc định rỗng): VIETQR: Key Type Required Mô tả beneficiaryName String Tên người thụ hưởng (Vui lòng liên hệ Sale để sử dụng tính năng này)
currency	String		Đơn vị tiền tệ. Mặc định là VND
billingInfo	Object		Thông tin của khách hàng {"firstName":"", "lastName":"", "address":""," "district":"", "province":"", "postalCode:"", "country":"", "email":"", "phone":""}
redirectUrl	String		Link redirect khi thanh toán thành công
failedUrl	String		Link redirect khi thanh toán thất bại
expiryTime	Int		Số giây hết hạn của đơn hàng ( Mặc định là 1800 giây )
redirectTime	Int		Số giây redirect về lại site của Merchant, 0 nếu muốn redirect ngay link của MC
lang	String		Ngôn ngữ hiển thị vi/en
username	String		Tên đăng nhập tàii khoản ghi nhận giao dịch

• Response:

Key	Type	Mô Tả
code	Number	Mã lỗi: 105000: Tạo đơn thanh toán thành công 105011: Tạo đơn thanh toá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ó các field bên dưới: Key Type Mô Tả url String Link thanh toán của PayME sử dụng cho user thanh toán transaction String Mã giao dịch của của PayME GP unique trên toàn hệ thống

Ví dụ:

• Payload mẫu trước khi encrypt:

{
  "amount": 100000,
  "partnerTransaction ": 124556274354,
  "desc": "Thanh toán tiền NET – KH 0012545",
  "ipnUrl": "https://mc-server.com/ipn",
  "redirectUrl": "https://mcsite.com/success",
  "failedUrl": " https://mcsite.com/fail",
  "expiryTime": 1800 
}

• Response mẫu trước khi encrypt:

{
  "code": 105000,
  "data": {
    "url": "https://payment.payme.vn/payment/2599007600",
    "transaction": "5480589239"
  }
}

• Lưu ý: Khi khởi tạo đơn hàng thành công sau 5 phút nếu không nhận được IPN, Merchant kiểm tra trạng thái giao dịch qua API Truy vấn đơn hàng

2.2. API Thanh toán Direct:

• Description: API do PayME cung cấp nhằm mục đích tạo đơn thanh toán trực tiếp.
• Path: /payment/direct
• Method: POST

Request Parameters:

• Payload:

Key	Type	Required	Description
partnerTransaction	String(32)	✔	Mã giao dịch của của đơn hàng do MC tạo ra là duy nhất và không cho phép gửi trùng, dùng để truy vấn giao dịch
amount	Number	✔	Giá trị đơn hàng
desc	String (256)	✔	Mô tả đơn hàng để hiển thị cho khách hàng
payMethod	Enum	✔	Phương thức thanh toán (PAYME, ATMCARD, VIETQR, FACEID), chi tiết
ip	String	✔	Địa chỉ ip của khách hàng kết nối đến server của doanh nghiệp
payCode	Enum		Mã phương thức thanh toán (PAYME, ATM, VN_PAY, VIETQR), chi tiết
payData	Object		Thông tin cần để thanh toán, tương ứng với mỗi phương thức (mặc định rỗng): ATMCARD Đã liên kiết thẻ ATM Key Type Required Mô tả cardId String ✔ Mã định danh thẻ Chưa liên kết thẻ ATM Key Type Required Mô tả cardNumber String ✔ Số thẻ issueDate String ✔ Ngày phát hành MM/YY cardHolder String ✔ Tên chủ thẻ FACEID: Key Type Required Mô tả swiftCode String ✔ SwiftCode của ngân hàng thanh toán tokenFaceId String ✔ Token thanh toán của bên đối tác phoneNumber String ✔ Số điện thoại customerNumber String ✔ Số CIF khách hàng OCB CREDITCARD: Key Type Bắt Buộc Mô tả expiredAt String ✔ Ngày hết hạn thẻ (MM/YY) cardNumber String ✔ Số thẻ thanh toán cardHolder String ✔ Họ tên chủ thẻ cvv String ✔ Mã số bảo mật khi thanh toán ghi trên thẻ VIETQR: Key Type Required Mô tả beneficiaryName String Tên người thụ hưởng (Vui lòng liên hệ Sale để sử dụng tính năng này)
ipnUrl	String		PayME sẽ thông báo trạng thái thanh toán của đơn hàng khi thanh toán hoàn tất; ipnUrl được gọi để thông báo kết quả thanh toán thất bại hoặc thành công. Nếu không được cung cấp, ipnUrl mặc định của ứng dụng sẽ được sử dụng.
extraData	String(1024)		Thông tin thêm cho thanh toán, dữ liệu sẽ được callback đến ipnUrl sau khi kết thúc giao dịch
customerInfo	Object		Thông tin của khách hàng khi muốn tạo thông tin chuyển khoản hoặc mã qr cố định Key Type Bắt buộc Mô Tả phone String ✔ Số điện thoại fullName String ✔ Tên đầy đủ address String Địa chỉ email String Địa chỉ email
currency	String		Đơn vị tiền tệ. Mặc định là VND
billingInfo	Object		Thông tin khách hàng : {"firstName":"", "lastName":"", "address":""," "district":"", "province":"", "postalCode:"", "country":"", "email":"", "phone":""}
redirectUrl	String		Link redirect khi thanh toán thành công
failedUrl	String		Link redirect khi thanh toán thất bại
expiryTime	Int		Số giây hết hạn của đơn hàng ( Mặc định là 1800 giây )
lang	String		Ngôn ngữ hiển thị: vi/en
username	String		Tên đăng nhập tàii khoản ghi nhận giao dịch

• Response:

Key	Type	Description
code	Number	Mã lỗi: 105000: Tạo đơn thanh toán thành công 105011: Tạo đơn thanh toá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ó các field bên dưới: Key Type Mô tả payUrl String Liên kết thanh toán, Người bán sử dụng liên kết này để thanh toán (PayME) qrContent String Doanh nghiệp dùng content để tạo nên QRCode (VIETQR) form String Nội dung HTML, Người bán sử dụng nội dung này để tải màn hình thanh toán (ATMCARD) bankInfoList Array Nội dung ngân hàng chuyển khoản (VIETQR) transaction String Mã giao dịch của PayME là duy nhất trên toàn hệ thống partnerTransaction String Mã giao dịch được tạo bởi doanh nghiệp paymentId String Id thanh toán của PayME

Example:

• Payload mẫu trước khi encrypt:

Trường hợp FACE_ID

{
    "partnerTransaction": "VuLA_SuaOngTho_00025",
    "amount": 100000,
    "desc": "Payment bằng FaceID",
    "payMethod": "FACEID",
    "payData": {
        "faceId": {
            "swiftCode": "ORCOVNVX",
            "customerNumber": "7477646",
            "phoneNumber": "0962325464",
            "tokenFaceId": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
        }
    },
    "ipnUrl": "https://mc-server.com/ipn",
    "redirectUrl": "https://mcsite.com/success",
    "failedUrl": " https://mcsite.com/fail",
    "expiryTime": 1800
}

Trường hợp đã liên kết thẻ ATM

{
    "partnerTransaction": "754613167913",
    "amount": 100000,
    "desc": "Thanh toán bằng thẻ ATM đã liên kết",
    "ip": "127.1.0.8",
    "payMethod": "ATMCARD",
    "payData": {
        "cardId": "46542318781613"
    },
    "ipnUrl": "https://mc-server.com/ipn",
    "redirectUrl": "https://mcsite.com/success",
    "failedUrl": " https://mcsite.com/fail",
    "expiryTime": 1800
}

Trường hợp thanh toán bằng thẻ ATM (chưa liên kết)

{
    "partnerTransaction": "754613167913",
    "amount": 100000,
    "desc": "Thanh toán bằng thẻ ATM chưa liên kết",
    "ip": "127.1.0.8",
    "payMethod": "ATMCARD",
    "payData": {
        "cardNumber": "970413251647",
        "issueDate": "03/07",
        "cardHolder": "NGUYEN VAN A"
    },
    "ipnUrl": "https://mc-server.com/ipn",
    "redirectUrl": "https://mcsite.com/success",
    "failedUrl": " https://mcsite.com/fail",
    "expiryTime": 1800
}

• Response mẫu trước khi encrypt:

Trường hợp có form html:

{
  "code": 105000,
  "message": "Tạo đơn thanh toán thành công",
  "data": {
    "transaction": "5480589239",
    "paymentId":"123456"
    "partnerTransaction": "363254973",
    "payUrl": null,
    "qrContent": null,
    "form": "<html>HTML Content</html>"
  }
}

Trường hợp có bankInfoList:

{
    "code": 105000,
    "message": "Tạo đơn thanh toán thành công",
    "data": {
        "transaction": "b3AQjS58aQ",
        "partnerTransaction": "1231a",
        "payUrl": null,
        "qrContent": null,
        "paymentId": "Ssoj92MMSq",
        "form": null,
        "bankInfoList": [
            {
                "bankName": "Wooribank Việt Nam",
                "number": "902000702986",
                "fullName": "PAYME NGUOI BUOI",
                "branch": "Hà Nội",
                "content": "TT MMSq",
                "swiftCode": "HVBKVNVXXXX"
            }
        ]
    }
}

Trường hợp có qrContent:

{
    "code": 105000,
    "message": "Tạo đơn thanh toán thành công",
    "data": {
        "transaction": "TBIRsl8ccE",
        "partnerTransaction": "363254973aaa",
        "payUrl": null,
        "qrContent": "00020101021226200006970412010611131352044112530370454061000005802VN5904vvcv6007ANGIANG610422116252011209X3lL2xHQ750307vb vcbv070400010813TT TBIRsl8ccE63046D65",
        "paymentId": "X3lL2xHQ75",
        "form": null,
        "bankInfoList": null
    }
}

Trường hợp có payUrl:

{
    "code": 105000,
    "message": "Tạo đơn thanh toán thành công",
    "data": {
        "transaction": "fBhdA9AzUI",
        "partnerTransaction": "363254973aaaa",
        "payUrl": "https://sbx-social.payme.vn/mecorpctcpgtdd-/p3jghc6mm",
        "qrContent": null,
        "paymentId": "zWNlYpnnGP",
        "form": null,
        "bankInfoList": null
    }
}

• Lưu ý: Khi khởi tạo đơn hàng thành công sau 5 phút nếu không nhận được IPN, Merchant kiểm tra trạng thái giao dịch qua API Truy vấn đơn hàng

2.3. API 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	Description
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	Description
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":{}
}

2.4. API truy vấn đơn hàng:

• Mô tả: API do PayME cung cấp dùng để tra cứu trạng thái của một giao dịch thanh toán.

• Path: /payment/query

• Method: POST

Request Parameters:

• Payload:

Tham số	Kiểu dữ liệu	Bắt buộc	Ý nghĩa
partnerTransaction	String(32)	✔	Mã giao dịch của của đơn hàng của MC đã gửi sang tạo giao dịch thanh toán.

• Response:

Key	Type	Mô Tả
code	Number	Mã lỗi: 105002: Thành công, lưu ý là gọi api thành công không phải kết quả giao dịch thành công. 105105: Không tìm thấy thông tin giao dịch
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: Key Type Mô Tả transaction String Mã giao dịch của PayME partnerTransaction String Mã giao dịch của Merchant merchantId Number Mã merchant storeId Number Mã điểm giao dịch method String Mã phương thức thanh toán amount Number Giá trị giao dịch thanh toán fee Number Phí thu của Merchant total Number Số tiền Merchant thực nhận state String Trạng thái của giao dịch: SUCCEEDED: Thành công FAILED: Thất bại PENDING: Chờ thanh toán EXPIRED: Hết hạn CANCELED: Đã huỷ REFUNDED: Đã hoàn desc String Mô tả thanh toán extraData String Data Merchant đã gửi lúc tạo yêu cầu thanh toán createdAt Datetime Thời gian tạo yêu cầu thanh toán updatedAt Datetime Thời gian cập nhật

Ví dụ:

• Payload mẫu trước khi encrypt:

{
  "partnerTransaction": "7203946788",
}

• Response mẫu trước khi encrypt:

{
  "code": 105002,
  "data": {
  "transaction" : "5150496860",
  "partnerTransaction" : "7203946788",
  "amount" : 10000,
  "merchantId": 22,
  "storeId": 9,
  "method": "PAYME",
  "fee" : 0,
  "total" : 10000,
  "state" : "SUCCEEDED",
  "desc" : "Nội dung giao dịch thanh toán",
  "extraData" : {},
  "createdAt" : "2020-07-23T06:55:20.794Z",
  "updatedAt" : "2021-01-14T03:58:28.516Z"
  }
}

2.5. API Lấy danh sách đơn hàng:

• Mô tả: API do PayME cung cấp dùng để lấy danh sách thông tin của các đơn hàng.

• Path: /payment/query/list

• Method: POST

Request Parameters:

• Payload:

Tham số	Kiểu dữ liệu	Bắt buộc	Ý nghĩa
filter	Object		Chứa thông tin các tham số truy vấn chỉ định biểu thức lọc đơn hàng
paging	Object	✔	Chứa thông tin chỉ định số lượng đơn hàng
sort	Object		Chứa thông tin cách sắp xếp kết quả danh sách đơn hàng
language	String		Ngôn ngữ hiển thị vi/en. Mặc định: vi

• Cấu trúc của Object filter

Key	Kiểu dữ liệu	Bắt buộc	Ý nghĩa
createdAt	Object		Thời gian tạo đơn hàng
finishedAt	Object		Thời gian thanh toán đơn hàng
payMethod	String		Phương thức thanh toán, bạn có thể xem PTTT tại đây
stateList	Array		Danh sách trạng thái đơn hàng: SUCCEEDED: Thành công FAILED: Thất bại PENDING: Chờ thanh toán EXPIRED: Hết hạn CANCELED: Đã huỷ REFUNDED: Đã hoàn

• Cấu trúc của Object createdAt

Key	Kiểu dữ liệu	Bắt buộc	Ý nghĩa
from	Date		Thời điểm bắt đầu của khoảng thời gian muốn lấy danh sách đơn hàng theo ngày tạo
to	Date		Thời điểm kết thúc của khoảng thời gian muốn lấy danh sách đơn hàng theo ngày tạo

• Cấu trúc của Object finishedAt

Key	Kiểu dữ liệu	Bắt buộc	Ý nghĩa
from	Date		Thời điểm bắt đầu của khoảng thời gian muốn lấy danh sách đơn hàng theo ngày thanh toán
to	Date		Thời điểm kết thúc của khoảng thời gian muốn lấy danh sách đơn hàng theo ngày thanh toán

• Cấu trúc của Object paging

Key	Kiểu dữ liệu	Bắt buộc	Ý nghĩa
start	Number		Điểm bắt đầu lấy danh sách đơn hàng. Mặc định: 0.
limit	Number		Số đơn hàng cần lấy. Mặc định: 20. Nhỏ nhất: 10. Lớn nhất: 200

• Cấu trúc của Object sort

Key	Kiểu dữ liệu	Bắt buộc	Ý nghĩa
createdAt	Number		Sắp xếp kết quả danh sách đơn hàng theo ngày tạo. Mặc định: - 1 1: Theo thứ tự tăng dần ngày tạo -1: Theo thứ tự giảm dần ngày tạo

• Response:

Key	Kiểu dữ liệu	Mô Tả
code	Number	Mã lỗi: 107200: Lấy danh sách đơn hàng thành công. 107201: Lấy danh sách đơn hàng thất bại. 100101: Không tìm thấy thông tin tài khoản. 100100: Không tìm thấy thông tin doanh nghiệp.
message	String	Mô tả thông tin mã lỗi
data	Array	Dữ liệu trả về gồm có các item có field bên dưới:

• Cấu trúc các item của Array data

Key	Kiểu dữ liệu	Mô Tả
transaction	String	Mã giao dịch của PayME
partnerTransaction	String	Mã giao dịch của Merchant
payMethod	String	Phương thức thanh toán
amount	Number	Số tiền của đơn hàng
fee	Number	Phí thu của Merchant
total	Number	Tổng tiền của Merchant
state	String	Trạng thái của giao dịch: SUCCEEDED: Thành công FAILED: Thất bại PENDING: Chờ thanh toán EXPIRED: Hết hạn CANCELED: Đã huỷ REFUNDED: Đã hoàn
description	String	Mô tả đơn hàng
createdAt	String	Thời gian tạo đơn hàng
finishedAt	String	Thời gian thanh toán đơn hàng
remitterInfo	String	Thông tin người thanh toán

• Cấu trúc của Object remitterInfo

Key	Kiểu dữ liệu	Mô Tả
number	String	Số tài khoản/Số thẻ của người thanh toán
fullName	String	Họ và tên của người thanh toán
swiftCode	String	Mã định danh (swiftCode) của ngân hàng
bankName	String	Tên ngắn gọn của ngân hàng

Ví dụ:

• Payload mẫu trước khi encrypt:

{
  "filter": {
    "createdAt": {
      "from": "2023-04-23T06:55:20.794Z",
      "to": "2020-05-23T06:55:20.794Z"
    },
    "finishedAt": {
      "from": "2023-05-02T06:55:20.794Z",
      "to": "2023-05-30T06:55:20.794Z"
    },
    "payMethod": "VIETQR",
    "stateList": ["PENDING", "SUCCEEDED"],
  },
  "paging": {
    "start": 0,
    "limit": 20
  },
  "sort": {
    "createdAt": -1
  }
}

• Response mẫu trước khi encrypt:

{
  "code": 107200,
  "message": "Lấy danh sách đơn hàng thành công.",
  "data": [
    {
      "transaction" : "QEITK2R38T2",
      "partnerTransaction" : "7203946788156",
      "amount" : 10000,
      "payMethod": "VIETQR",
      "fee" : 0,
      "total" : 10000,
      "state" : "SUCCEEDED",
      "description" : "Nội dung giao dịch thanh toán",
      "createdAt" : "2023-04-27T06:55:20.794Z",
      "finishedAt" : "2023-05-10T01:12:20.794Z",
      "remitterInfo": {
        "number": "******7294",
        "fullName": "HA NAM NINH",
        "swiftCode": "EACBVNVX",
        "bankName": "DongABank"
      }
    },
    {
      "transaction" : "TQLK39FAN21T",
      "partnerTransaction" : "1618912319431",
      "amount" : 24000,
      "payMethod": "VIETQR",
      "fee" : 500,
      "total" : 23500,
      "state" : "PENDING",
      "description" : "Nội dung giao dịch thanh toán",
      "createdAt" : "2023-04-29T06:55:20.794Z",
      "finishedAt" : null
    }
  ]
}

2.6. API hủy đơn hàng:

• Mô tả: API do PayME cung cấp dùng để hủy đơn hàng đang chờ thanh toán.

• Path: /order/cancel

• Method: POST

Request Parameters:

• Payload:

Tham số	Kiểu dữ liệu	Bắt buộc	Ý nghĩa
transactionId	String(32)	✔	Mã giao dịch của của đơn hàng mà MC nhận được khi tạo đơn hàng thành công.
language	Enum		vi/en, ngôn ngữ hiển thị cho khách hàng ( mặc định là vi).

• Response:

Key	Type	Mô Tả
code	Number	Mã lỗi: 105170: Hủy đơn hàng thành công. 105171: Hủy đơn hàng thất bại 105163: Đơn hàng không trong trạng thái chờ thanh toán
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: Key Type Mô Tả transactionId String Mã giao dịch của PayME failedUrl String Link redirect khi thất bại

Ví dụ:

• Payload mẫu trước khi encrypt:

{
  "transactionId": "7203946788",
}

• Response mẫu trước khi encrypt:

{
  "code": 105170,
  "message": "Hủy đơn hàng thành công"
  "data": {
      "transactionId" : "7203946788",
      "failedUrl" : "https://mcsite.com/fail",
  }
}

2.7. API truy vấn thanh toán:

• Mô tả: API do PayME cung cấp dùng để tra cứu trạng thái thanh toán của một đơn hàng.

• Path: /payment/details/query

• Method: POST

Request Parameters:

• Payload:

Tham số	Kiểu dữ liệu	Bắt buộc	Ý nghĩa
paymentId	String		Mã thanh toán khi tạo đơn hàng thành công.
partnerTransaction	String(32)	✔	Mã giao dịch của của đơn hàng của MC đã gửi sang tạo giao dịch thanh toán.

• Response:

Key	Type	Mô Tả
code	Number	Mã lỗi: 105009: Thành công, lưu ý là gọi api thành công không phải kết quả giao dịch thành công. 105123: Không tìm thấy thông tin thanh toán
message	String	Mô tả thông tin mã lỗi
data	Array	Dữ liệu trả về gồm có các field bên dưới: Key Type Mô Tả paymentId String Mã thanh toán khi tạo đơn hàng thành công transaction String Mã giao dịch của PayME partnerTransaction String Mã giao dịch của Merchant merchantId Number Mã merchant storeId Number Mã điểm giao dịch method String Mã phương thức thanh toán amount Number Giá trị giao dịch thanh toán fee Number Phí thu của Merchant total Number Số tiền Merchant thực nhận state String Trạng thái của giao dịch: SUCCEEDED: Thành công FAILED: Thất bại PENDING: Chờ thanh toán EXPIRED: Hết hạn CANCELED: Đã huỷ REFUNDED: Đã hoàn desc String Mô tả thanh toán extraData String Data Merchant đã gửi lúc tạo yêu cầu thanh toán createdAt Datetime Thời gian tạo yêu cầu thanh toán updatedAt Datetime Thời gian cập nhật

Ví dụ:

• Payload mẫu trước khi encrypt:

{
    "paymentId": "NiGW5xTKx2",
    "lang": "vi"
}

• Response mẫu trước khi encrypt:

{
    "code": 105009,
    "message": "Lấy danh sách payment thành công",
    "data": [
        {
            "paymentId":"123131"
            "partnerTransaction": "3760388kcyao0i6",
            "merchantId": 22,
            "storeId": 24,
            "method": "ALIPAY_DIRECT",
            "amount": 35000,
            "fee": 0,
            "total": 35000,
            "state": "FAILED",
            "extraData": null,
            "createdAt": "2020-07-23T04:27:24.992Z",
            "updatedAt": "2021-02-05T06:20:34.267Z",
            "transaction": "1017641786",
            "desc": "Thanh toán tiền cơm - #1017641786"
        }   
    ]
}

2.8. API Thanh toán cho máy POS:

• Description: API do PayME cung cấp nhằm mục đích tạo đơn thanh toán trực tiếp trên máy POS.
• Path: /payment/transit/device
• Method: POST

Request Parameters:

• Payload:

Key	Type	Required	Description
partnerTransaction	String(32)	✔	Mã giao dịch của của đơn hàng do MC tạo ra là duy nhất và không cho phép gửi trùng, dùng để truy vấn giao dịch
amount	Number	✔	Giá trị đơn hàng
desc	String (256)	✔	Mô tả đơn hàng để hiển thị cho khách hàng
payCode	Enum	✔	Mã phương thức thanh toán (ATM_POS, CREDIT_POS, CREDIT_INTERNATIONAL_POS, VIETQR), chi tiết
username	String		Tên đăng nhập tài khoản ghi nhận giao dịch
ipnUrl	String		PayME sẽ thông báo trạng thái thanh toán của đơn hàng khi thanh toán hoàn tất; ipnUrl được gọi để thông báo kết quả thanh toán thành công. Nếu không được cung cấp, ipnUrl mặc định của ứng dụng sẽ được sử dụng.
lang	String		Ngôn ngữ hiển thị: vi/en

• Response:

Key	Type	Description
code	Number	Mã lỗi: 191000: Tạo đơn thanh toán thành công 191001: Tạo đơn thanh toán thất bại 191005: Thiết bị đang bận
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: Key Type Mô tả transaction String Mã giao dịch của PayME là duy nhất trên toàn hệ thống amount Number Giá trị đơn hàng payCode String Mã phương thức thanh toán partnerTransaction String Mã giao dịch được tạo bởi doanh nghiệp

Example:

• Payload mẫu trước khi encrypt:

{
  "partnerTransaction": "7203946788",
  "amount": 10000,
  "desc": "Mô tả đơn hàng",
  "payCode": "ATM_POS",
  "username": "paymeusername"
}

• Response mẫu trước khi encrypt:

{
  "code": 191000,
  "message": "Tạo đơn thanh toán thành công",
  "data": {
    "transaction": "MRTNJ3O4TD4S",
    "amount": 10000,
    "payCode": "ATM_POS",
    "partnerTransaction": "7203946788"
  }
}

2.9. API Hoàn Tiền:

• Mô tả:API do PayME cung cấp dùng để huỷ hoặc hoàn giao dịch đã thanh toán thành công.

  • Huỷ thanh toán: khi PayME chưa đối soát giao dịch cho Merchant
  • Hoàn tiền: khi PayME đã đối soát giao dich cho Merchant

• Quy tắc hoàn tiền:

Nguồn Tiền	Hoàn Về	Mô tả
Ví PayME	Ví PayME	Ngay lập tức
ATM	TK ngân hàng	1 - 45 ngày làm việc
Visa / Master / JCB	Thẻ	1 - 45 ngày làm việc
VietQR	TK ngân hàng	Ngay lập tức
AliPay	TK Alipay	Ngay lập tức

• Path: /payment/refund
• Method : POST

Request Parameters:

• Payload:

Tham số	Kiểu dữ liệu	Bắt buộc	Ý nghĩa
partnerTransaction	String(32)	✔	Mã giao dịch hoàn tiền do MC tạo tương ứng mỗi yêu cầu hoàn tiền.
transaction	String	✔	Mã giao dịch muốn hoàn, mã này do PayME trả về khi thanh toán thành công.
amount	Number	✔	Số tiền muốn hoàn lại cho khách hàng
reason	String	✔	Lý do hoàn tiền
language	String		Ngôn ngữ hiển thị: vi/en

• Response:

Key	Type	Mô Tả
code	Number	Mã lỗi: 105003: Hoàn tiền thành công 105107: Vượt quá số tiền có thể hoàn của giao dịch 105108: Quá thời hạn cho phép huỷ giao dịch 105109: Số tiền hoàn nhỏ hơn tối thiểu cho phép 105110: Giao dịch đã được hoàn hết tất cả số tiền 105112: Chưa hỗ trợ hoàn tiền cho phương thức thanh toán chỉ định 105166: Thông tin người thụ hưởng không hợp lệ 105116: Hoàn tiền giao dịch thất bại 105156: Giao dịch không được phép hoàn.Vui lòng thử lại sau. 129100: Không tìm thấy thông tin thanh toán đơn hàng 100101: Không tìm thấy thông tin tài khoản 100100: Không tìm thấy thông tin doanh nghiệp
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 Key Type Mô Tả transaction String Mã giao dịch của PayME partnerTransaction String Mã giao dịch của merchant msg String Nội dung thông báo kết quả hoàn

Ví dụ:

• Payload mẫu trước khi encrypt:

{
  "partnerTransaction": "7203946788",
  "transaction": "5150496860",
  "amount": 10000,
  "reason": "Lý do hoàn tiền"
}

• Response mẫu trước khi encrypt:

{
  "code": 105003,
  "message": "Hoàn tiền thành công",
  "data": {
    "partnerTransaction": "7203946788",
    "transaction": "5150496860",
    "amount": 10000,
    "msg": "Hoàn tiền thành công"
  }
}

2.9.1. IPN Thanh Toán:

• Mô tả:API do MC cung cấp, PayME gọi API để thông báo kết quả giao dịch.

• Path: Do MC cung cấp khi tạo kết nối hoặc gửi lúc tạo đơn hàng

• Method: POST

Request Parameters:

• Payload :

Key	Type	Mô Tả
transaction	String	Mã giao dịch của PayME
partnerTransaction	String	Mã giao dịch của Merchant
paymentId	String	Mã thanh toán của đơn hàng
merchantId	Number	Mã merchant
storeId	Number	Mã điểm giao dịch
payMethod	String	Phương thức thanh toán
payCode	String	Mã phương thức thanh toán
amount	Number	Giá trị giao dịch thanh toán
fee	Number	Phí thu của MC
total	Number	Số tiền MC thực nhận
state	String	Trạng thái của giao dịch: SUCCEEDED: Thành công FAILED: Thất bại PENDING: Chờ thanh toán EXPIRED: Hết hạn CANCELED: Trạng thái này sẽ trả về khi hủy 1 đơn hàng thanh toán chưa đối soát REFUNDED: Trạng thái trả về khi hoàn một phần tiền hoặc hủy đơn hàng giao dịch đã đối soát
reason	String	Lý do của trạng thái thanh toán
desc	String	Hiển thị mô tả thanh toán khi khách hàng mở yêu cầu thanh toán lên
customerInfo	Object	Thông tin tài khoản ảo của khách hàng ( chỉ có khi tạo đơn hàng cho khách hàng của doanh nghiệp). Dữ liệu gồm cái field bên dưới
extraData	String	Data Merchant đã gửi lúc tạo yêu cầu thanh toán
metaData	Object	Thông tin tài khoản đã thanh toán. Dữ liệu gồm cái field bên dưới
createdAt	Datetime	Thời điểm tạo yêu cầu thanh toán
updatedAt	Datetime	Thời điểm cập nhật yêu cầu thanh toán lần cuối

• Cấu trúc Object của customerInfo

Key	Kiểu dữ liệu	Ý nghĩa
customerId	String	Mã định danh khách hàng
swiftCode	String	Mã định danh (swiftCode) của ngân hàng
bankName	String	Tên ngắn gọn của ngân hàng
number	String	Số tài khoản ngân hàng
fullName	String	Tên người thụ hưởng

• Cấu trúc Object của metaData

Key	Kiểu dữ liệu	Ý nghĩa
fullName	String	Tên người thụ hưởng đã thanh toán
swiftCode	String	Mã định danh (swiftCode) của ngân hàng của tài khoản thanh toán
bankName	String	Tên ngắn gọn của ngân hàng của tài khoản thanh toán
number	String	Số tài khoản đã thanh toán
cardType	String	Loại thẻ đã thanh toán

   • Response:

Key	Type	Mô Tả
code	Number	Mã lỗi: 1000: Thành công, lưu ý là gọi api thành công không phải kết quả giao dịch thành công 1001: Thất bại
message	String	Mô tả thông tin mã lỗi

Ví dụ:

• Payload mẫu trước khi encrypt:

Trường hợp không có thông tin customerInfo :

{
  "transaction": "1440585414",
  "partnerTransaction": "OWP02S2047T126",
  "paymentId": "8447815937",
  "accountId": 310,
  "merchantId": 242932,
  "storeId": 65564016,
  "payMethod": "PAYME",
  "payCode": "PAYME",
  "amount": 50000,
  "fee": 385,
  "total": 49615,
  "state": "SUCCEEDED",
  "desc": "Top-up,
  "reason": "",
  "extraData": "",
  "createdAt": "2021-11-15T04:04:55.244Z",
  "updatedAt": "2021-11-15T04:05:16.115Z"
}

Trường hợp có thông tin customerInfo :

{
  "transaction": "1440585414",
  "partnerTransaction": "OWP02S2047T126",
  "paymentId": "8447815937",
  "accountId": 310,
  "merchantId": 242932,
  "storeId": 65564016,
  "payMethod": "PAYME",
  "payCode": "PAYME",
  "amount": 50000,
  "fee": 385,
  "total": 49615,
  "state": "SUCCEEDED",
  "desc": "Top-up,
  "customerInfo": {
    "customerId": "255334381",
    "swiftCode": "ORCOVNVX",
    "bankName": "OCB",
    "number": "NAR000038251290326",
    "fullName": "PAYME MERCHANT PAY"
  },
  "reason": "",
  "extraData": "",
  "createdAt": "2021-11-15T04:04:55.244Z",
  "updatedAt": "2021-11-15T04:05:16.115Z"
}

Trường hợp có thông tin metaData :

{
  "transaction": "1440585414",
  "partnerTransaction": "OWP02S2047T126",
  "paymentId": "8447815937",
  "accountId": 310,
  "merchantId": 242932,
  "storeId": 65564016,
  "payMethod": "PAYME",
  "payCode": "PAYME",
  "amount": 50000,
  "fee": 385,
  "total": 49615,
  "state": "SUCCEEDED",
  "desc": "Top-up,
  "customerInfo": {
    "customerId": "255334381",
    "swiftCode": "ORCOVNVX",
    "bankName": "OCB",
    "number": "NAR000038251290326",
    "fullName": "PAYME MERCHANT PAY"
  },
  "metaData": {
    "number": "****************2346",
    "fullName": "TRAN THANH CONG",
    "swiftCode": "",
    "cardType": "MASTERCARD"
  },
  "reason": "",
  "extraData": "",
  "createdAt": "2021-11-15T04:04:55.244Z",
  "updatedAt": "2021-11-15T04:05:16.115Z"
}

• Response mẫu trước khi encrypt:

{
  "code": 1000,
  "data": {
  "url": "https://payment.payme.vn/payment/2599007600",
  "transaction": "5480589239"
  }
}

3. Payout

3.1. API Chuyển tiền đơn

• Mô tả: API do PayME cung cấp dùng để tạo một giao dịch chuyển tiền.

• API Path: /payout

• Method: POST

Request Parameters:

• Payload:

Tham số	Kiểu dữ liệu	Bắt buộc	Ý nghĩa
partnerTransaction	String(32)	✔	Mã giao dịch của chi đơn do MC tạo ra là duy nhất và không được phép gửi trùng.
amount	Number	✔	Số tiền chi, tối thiểu 20,000 VNĐ
customer	Object		Thông tin người nhận customer.name: Tên gợi nhớ người nhận customer.group: Nhóm người nhận Enum: EMPLOYEE | CUSTOMER | PARTNER | FRIEND | FAMILY | OTHER
destination	Object	✔	Thông tin chuyển, xem cấu trúc bên dưới
type	Enum	✔	Loại chi: WITHDRAW: Rút tiền PAYMENT: Chuyển tiền SALARY: Chi lương
content	String(152)		Nội dung lệnh chi
ipnUrl	String		Link IPN thông báo trạng thái cho Merchant mỗi khi PayME thực hiện chi thành công.
extraData	String		Thông tin thêm do MC gửi sang sẽ được callback đến ipnUrl
language	Enum		vi/en, ngôn ngữ hiển thị cho khách hàng

• Cấu trúc của Object destination

• Trường hợp chuyển tiền đến ví

Tham số	Kiểu dữ liệu	Bắt buộc	Ý nghĩa
wallet	Object	✔	Thông tin ví PayME

Cấu trúc của Object wallet

Tham số	Kiểu dữ liệu	Bắt buộc	Ý nghĩa
phone	String	✔	SĐT của ví PayME
fullname	String	✔	Tên của ví PayME
beneficiaryPhone	String	✔	Số điện thoại liên hệ của khách hàng

• Trường hợp chuyển tiền đến tài khoản ngân hàng

Tham số	Kiểu dữ liệu	Bắt buộc	Ý nghĩa
bankAccount	Object	✔	Thông tin tài khoản ngân hàng

Cấu trúc của Object bankAccount

Tham số	Kiểu dữ liệu	Bắt buộc	Ý nghĩa
accountNumber	String	✔	Số tài khoản/Số thẻ ATM của ngân hàng
accountName	String	✔	Tên người thụ hưởng
swiftCode	String	✔	Mã định danh ngân hàng
branch	String		Chi nhánh ngân hàng. Yêu cầu nhập, nếu ngân hàng thụ hưởng thuộc danh sách tại đây hoặc số tiền chi lớn hơn 300,000,000 VNĐ. Api lấy danh sách chi nhánh của ngân hàng tại đây
beneficiaryPhone	String	✔	Số điện thoại liên hệ của khách hàng

• Response:

Key	Type	Mô tả
code	Number	Mã lỗi: 132000: Tạo giao dịch chuyển tiền thành công 132001: Doanh nghiệp không được phép chuyển tiền 132002: Thông tin tài khoản được chuyển tiền không chính xác 132003: Tài khoản ví chưa được KYC 132004: Không tìm thấy phương thức chuyển khoản 132005: Số tiền chuyển khoản không được nhỏ hơn 0 VNĐ 132009: Số tiền chuyển cần lớn hơn 10,000 VNĐ 132010: Số tiền chuyển chuyển cho tài khoản ngân hàng không nhỏ hơn 300,000 VNĐ 132012: Không tìm thấy mã giao dịch đối tác 132013: Mã giao dịch đã tồn tại 132017: Số tiền chuyển không được vượt quá 300,000,000 VNĐ 132605: Tên tài khoản ngân hàng không chính xác 132011: Số dư chuyển tiền không đủ 132016: Tạo giao dịch chuyển tiền thất bại 132108: Thiếu thông tin chi nhánh ngân hàng 133716: Tài khoản bị chặn 100101: Không tìm thấy thông tin tài khoản 100100: Không tìm thấy thông tin doanh nghiệp
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: Key Type Mô Tả transactionId String Mã giao dịch của của PayME GP unique trên toàn hệ thống

Ví dụ:

• Payload mẫu trước khi encrypt:

{
  "type": "PAYMENT",
  "content": "Test",
  "partnerTransaction": "12345689",
  "amount": 10000,
  "destination": {
    "bankAccount": {
      "accountNumber": "9704000000000018",
      "accountName": "NGUYEN VAN A",
      "swiftCode": "SBITVNVX",
      "beneficiaryPhone": "0987654321"
    },
  },
  "extraData": "{test:1231321}",
  "ipnUrl": "https://www.tiktok.com/",
  "language": "vi"
}

• Response mẫu trước khi encrypt:

{
  "code": 132000,
  "message": "Tạo giao dịch chuyển tiền thành công",
  "data": {
    "transactionId": "44759910038492093634"
  }
}

3.2. API Chuyển tiền danh sách

• Mô tả: API do PayME cung cấp dùng để tạo nhiều giao dịch chuyển tiền.
• URL POST: /payout/bulk

Request Parameters:

• Payload:

Tham số	Kiểu dữ liệu	Bắt buộc	Ý nghĩa
partnerBulkTransaction	String(32)	✔	Mã giao dịch của của đơn chi do MC tạo ra là duy nhất và không cho phép gửi trùng, dùng để truy vấn giao dịch
items	Array	✔	Danh sách tài khoản nhận
type	Enum	✔	Loại chi: WITHDRAW: Rút tiền PAYMENT: Chuyển tiền SALARY: Chi lương
description	String (256)	✔	Mô tả đơn hàng để hiển thị cho khách hàng
ipnUrl	String		Link IPN thông báo trạng thái cho Merchant mỗi khi PayME thực hiện chi thành công nào trong danh sách nhận tiền của lệnh chuyển tiền.
language	Enum		vi/en, ngôn ngữ hiển thị cho khách hàng

• Cấu trúc items

Key	Kiểu dữ liệu	Bắt buộc	Ý nghĩa
partnerTransaction	String(32)	✔	Mã định danh một phần tử trong danh sách chi
amount	Number	✔	Số tiền chi, tối thiểu 20,000 VNĐ
customer	Object		Thông tin người nhận customer.name: Tên gợi nhớ người nhận customer.group: Nhóm người nhận Enum: EMPLOYEE | CUSTOMER | PARTNER | FRIEND | FAMILY | OTHER
destination	Object	✔	Thông tin chuyển, xem cấu trúc bên dưới
content	String(152)		Nội dung lệnh chi
extraData	String		Thông tin thêm do MC gửi sang sẽ được callback đến ipnUrl

• Cấu trúc của Object destination

• Trường hợp chuyển tiền đến ví

Tham số	Kiểu dữ liệu	Bắt buộc	Ý nghĩa
wallet	Object	✔	Thông tin ví PayME

Cấu trúc của Object wallet

Tham số	Kiểu dữ liệu	Bắt buộc	Ý nghĩa
phone	String	✔	SĐT của ví PayME
fullname	String	✔	Tên của ví PayME
beneficiaryPhone	String	✔	Số điện thoại liên hệ của khách hàng

• Trường hợp chuyển tiền đến tài khoản ngân hàng

Tham số	Kiểu dữ liệu	Bắt buộc	Ý nghĩa
bankAccount	Object	✔	Thông tin tài khoản ngân hàng

Cấu trúc của Object bankAccount

Tham số	Kiểu dữ liệu	Bắt buộc	Ý nghĩa
accountNumber	String	✔	Số tài khoản/Số thẻ ATM của ngân hàng
accountName	String	✔	Tên người thụ hưởng
swiftCode	String	✔	Mã định danh ngân hàng
beneficiaryPhone	String	✔	Số điện thoại liên hệ của khách hàng

• Response:

Key	Type	Mô tả
code	Number	Mã lỗi: 132600: Tạo giao dịch chuyển tiền theo danh sách thành công 132011: Số dư chuyển tiền không đủ 132016: Tạo giao dịch 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ó các field bên dưới: Key Type Mô Tả bulkTransactionId String Mã giao dịch của của PayME GP unique trên toàn hệ thống

Ví dụ:

• Payload mẫu trước khi encrypt:

{
  "partnerBulkTransaction": "12345667877",
  "items": [
    {
      "partnerTransaction": "3444azaa",
      "amount": 100000,
      "destination": {
        "wallet": {
          "phone": "0909000200",
          "fullname": "NGUYEN VAN A",
          "beneficiaryPhone": "0987654321",
        }
      },
      "content": "Chi lương tháng 12",
      "extraData": "{}"
    },
    {
      "partnerTransaction": "11231azaaa",
      "amount": 100000,
      "destination": {
        "bankAccount": {
            "accountNumber": "9704000000000018",
            "accountName": "NGUYEN VAN A",
            "swiftCode": "SBITVNVX",
            "beneficiaryPhone": "0987654321",
        }
      },
      "content": "Chi lương tháng 12",
      "extraData": "{}"
    }
  ],
  "description": "Chi lương tháng 12",
  "type": "SALARY",
  "ipnUrl": "https://www.tiktok.com/"
}

• Response mẫu trước khi encrypt:

{
  "code": 132600,
  "message": "Tạo giao dịch chuyển tiền theo danh sách thành công",
  "data": {
    "bulkTransactionId": "6893852485"
  }
}

3.3. API Truy vấn chuyển tiền

• Mô tả: API do PayME cung cấp dùng để tra cứu trạng thái của giao dịch chuyển tiền.
• Path: /payout/query
• Method : POST

Request Parameters:

• Payload:

Tham số	Kiểu dữ liệu	Bắt buộc	Ý nghĩa
partnerTransaction	String(32)	✔	Mã giao dịch lệnh chi của MC
state			Trạng thái: SUCCEEDED: Chuyển tiền thành công APPROVED: Đã duyệt FAILED: Thất bại CANCELED: Đã hủy PENDING: Chờ xử lý REVIEW: Chờ chuyển

• Response:

Key	Type	Mô tả
code	Number	Mã lỗi 132500: Tìm kiếm lệnh chuyển tiền thành công 132501: Không tìm thấy lệnh chuyển tiền 100101: Không tìm thấy thông tin tài khoản 100100: Không tìm thấy thông tin doanh nghiệp
message	String	Mô tả thông tin mã lỗi
data	Object	Dữ liệu trả về là dữ liệu lệnh chuyển tiền

Cấu trúc data là array với mỗi item gồm các giá trị:

Key	Type	Mô tả
transactionId	String	Mã GD lệnh chuyển tiền của PayME
partnerTransaction	String	Mã giao dịch lệnh chuyển tiền của MC
partnerBulkTransaction	String	Mã giao dịch nhóm lệnh chuyển tiền của MC
amount	Number	Số tiền của lệnh chuyển tiền
fee	Number	Phí chi
total	Number	Số tiền nguồn chi bị trừ bao gồm số tiền chi và phí
source	Object	Nguồn tiền chuyển tiền
destination	Object	Thông tin tài khoản thụ hưởng
type	Enum	Loại chi
content	String	Nội dung chi
state	Enum	Trạng thái chuyển tiền SUCCEEDED: Chuyển tiền thành công APPROVED: Đã duyệt FAILED: Thất bại CANCELED: Đã hủy PENDING: Chờ xử lý REVIEW: Chờ chuyển
reason	String	Lý do hủy giao dịch, hoặc lý do GD bị từ chối
approvedAt	DateTime	Thời gian duyệt
canceledAt	DateTime	Thời gian hủy
createdAt	DateTime	Thời gian tạo

Ví dụ:

• Payload mẫu trước khi encrypt:

{
  "partnerTransaction": "432534523545",
  "state": ["APPROVED", "FAILED"]
}

• Response mẫu trước khi encrypt:

{
  "code": 132500,
  "message": "Tìm kiếm lệnh chuyển tiền thành công",
  "data": {
    "transactionId": "72425705880606658976",
    "partnerTransaction": "83343350",
    "amount": 20000,
    "fee": 4200,
    "total": 24200,
    "source": {
      "customize": {
        "amount": 20000
      }
    },
    "destination": {
      "bankAccount": {
        "accountNumber": "9704000000000018",
        "accountName": "NGUYEN VAN A",
        "swiftCode": "SBITVNVX"
      }
    },
    "type": "SALARY",
    "content": "chuyển tiền",
    "state": "APPROVED",
    "reason": null,
    "approvedAt": "2021-09-29T03:35:35.648Z",
    "canceledAt": null,
    "createdAt": "2021-09-29T03:35:27.415Z"
  }
}

3.4. API Truy vấn chuyển tiền danh sách

• Mô tả: API do PayME cung cấp dùng để tra cứu trạng thái của giao dịch chuyển tiền.
• Path: /payout/bulk/query
• Method : POST

Request Parameters:

• Payload:

Tham số	Kiểu dữ liệu	Bắt buộc	Ý nghĩa
partnerBulkTransaction	String(32)	✔	Mã giao dịch của nhóm lệnh chi của MC
partnerTransaction	String		Mã giao dịch lệnh chuyển tiền của MC
state			Trạng thái: SUCCEEDED: chuyển tiền thành công FAILED: Thất bại CANCELED: Đã hủy PENDING: Chờ xử lý

• Response:

Key	Type	Mô tả
code	Number	Mã lỗi 133400: Tìm kiếm lệnh chuyển tiền danh sách thành công 133401: Không tìm thấy lệnh chuyển tiền danh sách 100101: Không tìm thấy thông tin tài khoản 100100: Không tìm thấy thông tin doanh nghiệp
message	String	Mô tả thông tin mã lỗi
data	Array	Dữ liệu trả về là danh sách lệnh chi

Cấu trúc data là array với mỗi item gồm các giá trị:

Key	Type	Mô tả
transactionId	String	Mã GD lệnh chi của PayME
bulkTransactionId	String	Mã GD nhóm lệnh chi của PayME
partnerTransaction	String	Mã giao dịch lệnh chi của MC
partnerBulkTransaction	String	Mã giao dịch nhóm lệnh chi của MC
amount	Number	Số tiền của lệnh chuyển tiền
fee	Number	Phí chi
total	Number	Số tiền nguồn chi bị trừ bao gồm số tiền chi và phí
source	Object	Nguồn tiền chuyển tiền
destination	Object	Thông tin tài khoản thụ hưởng
type	Enum	Loại chi
content	String	Nội dung chi
state	Enum	Trạng thái chuyển tiền SUCCEEDED: chuyển tiền thành công FAILED: Thất bại CANCELED: Đã hủy PENDING: Chờ xử lý REVIEW: Chờ chuyển
reason	String	Lý do hủy giao dịch, hoặc lý do GD bị từ chối
approvedAt	DateTime	Thời gian duyệt
canceledAt	DateTime	Thời gian hủy
createdAt	DateTime	Thời gian tạo

Ví dụ:

• Payload mẫu trước khi encrypt:

{
  "partnerBulkTransaction": "z1zzzzcaavz",
  "partnerTransaction": "z1zzzzcaavz_2470722423",
  "state": ["PENDING"]
}

• Response mẫu trước khi encrypt:

{
  "code": 133400,
  "message": "Lấy thông tin lệnh chuyển tiền danh sách thành công",
  "data": [
    {
      "transactionId": "34009853678773583305",
      "bulkTransactionId    ": "1584621589641254875132",
      "partnerTransaction": "z1zzzzcaavz_2470722423",
      "partnerBulkTransaction": "addqftascaavz_2470489463",
      "amount": 100000,
      "fee": 5000,
      "total": 105000,
      "source": {
        "customize": {
          "amount": 100000
        }
      },
      "destination": {
        "bankAccount": {
          "accountNumber": "9704000000000018",
          "accountName": "NGUYEN VAN A",
          "swiftCode": "SBITVNVX"
        }
      },
      "type": "SALARY",
      "content": "Chi lương tháng 12",
      "state": "PENDING",
      "reason": null,
      "approvedAt": null,
      "canceledAt": null,
      "createdAt": "2021-09-28T18:24:33.958Z"
    }
  ]
}

3.5. API Hủy chuyển tiền:

• Mô tả: API do PayME cung cấp dùng để huỷ lệnh chuyển tiền.
• Path: /payout/cancel
• Method : POST

Request Parameters:

• Payload:

Tham số	Kiểu dữ liệu	Bắt buộc	Ý nghĩa
transactionId	String	✔	Mã đơn chi, mã này do PayME trả về khi tạo đơn chi thành công
reason	String		Lý do hủy
language	enum		vi/en, ngôn ngữ hiển thị cho khách hàng

• Response:

Key	Type	Mô tả
code	Number	Mã lỗi: 132300: Hủy lệnh chuyển tiền thành công 132301: Đơn hàng chuyển tiền không trong trạng thái có thể hủy 132302: Hủy đơn hàng chuyển tiền thất bại 132101: Không tìm thấy thông tin lệnh chuyển tiền 132301: Lệnh chuyển tiền chưa được duyệt trước đó 100101: Không tìm thấy thông tin tài khoản 100100: Không tìm thấy thông tin doanh nghiệp
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 Key Type Mô Tả transactionId String Mã giao dịch của PayME

Ví dụ:

• Payload mẫu trước khi encrypt:

{
  "transactionId": "7203946788"
}

• Response mẫu trước khi encrypt:

{
  "code": 132300,
  "message": "Hủy lệnh chuyển tiền thành công",
  "data": {
    "transactionId": "7203946788"
  }
}

3.6. IPN chuyển tiền

• Mô tả: API do MC cung cấp, PayME gọi API để thông báo kết quả giao dịch.
• Path: Do MC cung cấp khi tạo kết nối hoặc gửi lúc tạo đơn hàng
• Method : POST

Request Parameters:

• Payload:

Key	Type	Mô tả
transactionId	String	Mã giao dịch của PayME
partnerTransaction	String	Mã giao dịch của MC
bulkTransactionId	String	Mã giao dịch chuyển tiền danh sách của PayME
partnerBulkTransaction	String	Mã giao dịch chuyển tiền danh sách của MC
state	Enum	Trạng thái chi: SUCCEEDED: Chi thành công FAILED: Chi thất bại CANCELED: Đã hủy PENDING: chờ xử lý REVIEW: Chờ chuyển
transferedAt	Datetime	Thời gian chuyển
createdAt	Datetime	Thời gian khởi tạo lệnh chi

• Response:

Key	Type	Mô tả
code	Number	Mã lỗi 1000: Thành công, MC đã ghi nhân kết quả IPN 1001: Thất bại
message	String	Mô tả thông tin mã lỗi

Ví dụ:

• Payload mẫu trước khi encrypt:

{
    "transactionId": "123",
    "partnerTransaction": "456",
    "bulkTransactionId": "789",
    "partnerBulkTransaction": "101112",
    "state": "SUCCEEDED",
    "transferedAt": "2021-04-27 03:52:06.433Z"
    "createdAt": "2021-04-27 03:52:06.433Z"
}

• Response mẫu trước khi encrypt:

{
  "code": 1000,
  "message": "Ghi nhân IPN thành công"
}

4. Lệnh chờ xử lý

4.1 API truy vấn lệnh chờ xử lý:

• Mô tả: API do PayME cung cấp dùng để truy vấn các lệnh chờ xử lý.

• Path: /dispute/payment

• Method: POST

Request Parameters:

• Payload:

Tham số	Kiểu dữ liệu	Bắt buộc	Ý nghĩa
disputeId	String		Mã của lệnh chờ xử lý.
partnerTransaction	String		Mã giao dịch đơn hàng gốc do Merchant tạo ra.
transactionId	String		Mã giao dịch đơn hàng gốc.
language	String		vi/en, ngôn ngữ hiển thị

• Response:

Key	Type	Mô Tả
code	Number	Mã lỗi: 128226: Truy vấn thông tin lệnh chờ xử lý thành công. 128225: Không tìm thấy lệnh chờ xử lý. 100101: Không tìm thấy thông tin tài khoản. 100100: Không tìm thấy thông tin doanh nghiệp
message	String	Mô tả thông tin mã lỗi
data	Object	Dữ liệu trả về là Object có các field bên dưới:

Cấu trúc của Object data :

Key	Type	Mô Tả
disputeId	String	Mã lệnh chờ xử lý
referOrder	Object	Thông tin đơn hàng gốc (Trường hợp tìm thấy đơn hàng mà không đúng số tiền)
payMethod	String	Phương thức thanh toán
amount	Number	Số tiền thực nhận
type	String	Loại chờ xử lý: NOT_MATCH_AMOUNT: Tìm thấy đơn hàng nhưng không đúng số tiền NOT_MATCH_ORDER: Không tìm thấy đơn hàng
state	String	Trạng thái lệnh chờ xử lý OPEN: Chờ xử lý PROCESSING: Đang xử lý COMPLETED: Đã xử lý
attribute	Object	Thông tin xử lý lệnh chờ xử lý
conclusion	Object	Thông tin kết quả xử lý lệnh chờ xử lý
createdAt	Date	Thời gian tạo lệnh chờ xử lý
finishedAt	Date	Thời gian xử lý lệnh chờ xử lý

Cấu trúc của Object referOrder :

Key	Type	Mô Tả
transaction	String	Mã giao dịch đơn hàng gốc
partnerTransaction	String	Mã giao dịch đơn hàng gốc do Merchant tạo ra
amount	Number	Số tiền của đơn hàng gốc

Cấu trúc của Object attribute :

Key	Type	Mô Tả
qrCode	Object	Thông tin xử lý lệnh chờ xử lý nếu phương thức thanh toán là VIETQR

• Cấu trúc Object của qrCode

Key	Kiểu dữ liệu	Ý nghĩa
content	String	Nội dung chuyển khoản
remitter	Object	Thông tin người chuyển khoản
paidAt	Date	Thời gian thanh toán

• Cấu trúc Object của remitter

Key	Kiểu dữ liệu	Ý nghĩa
type	String	Loại tài khoản của người chuyển khoản BANK: Tài khoản ngân hàng EWALLET: Tài khoản ví điện tử
number	String	Số tài khoản
fullName	String	Tên người chuyển khoản
swiftCode	String	Mã định danh ngân hàng
bankName	String	Tên ngân hàng

• Cấu trúc Object của conclusion

Key	Kiểu dữ liệu	Ý nghĩa
actionType	String	Hành động xử lý lệnh chờ xử lý, đối với loại thanh toán Trường hợp loại chờ xử lý NOT_MATCH_AMOUNT: MATCH_ORDER: Khớp đơn hàng gốc ứng với số tiền đã thanh toán. TOPUP: Nạp tiền vào số dư ví của Merchant. CREATE_ORDER: Tạo mới một đơn hàng ứng với số tiền đã thanh toán. REFUND: Hoàn tiền về tài khoản của khách hàng đã thanh toán. Trường hợp loại chờ xử lý NOT_MATCH_ORDER: TOPUP: Nạp tiền vào số dư ví của Merchant. CREATE_ORDER: Tạo mới một đơn hàng mới ứng với số tiền đã thanh toán. REFUND: Hoàn tiền về tài khoản của khách hàng đã thanh toán.
transaction	String	Mã đơn hàng đã được xử lý cho loại hành động MATCH_ORDER, CREATE_ORDER
partnerTransaction	String	Mã giao dịch của Merchant đã được xử lý cho loại hành động MATCH_ORDER, CREATE_ORDER

Ví dụ:

• Payload mẫu trước khi encrypt:

{
    "disputeId": "TEAUTN13KS",
    "partnerTransaction": "1233494127812",
    "transactionId": "TKLAREI19Q92",
    "language": "vi"
}

• Response mẫu trước khi encrypt:

{
    "code": 128226,
    "message": "Truy vấn thông tin lệnh chờ xử lý thành công.",
    "data": {
        "disputeId":"TEAUTN13KS",
        "referOrder": {
            "transaction": "TKLAREI19Q92",
            "partnerTransaction": "1233494127812",
            "amount": 30000
        }
        "payMethod": "VIETQR",
        "amount": 32100,
        "type": "NOT_MATCH_AMOUNT",
        "state": "COMPLETED",
        "attribute": {
          "qrCode": {
            "content": "Thanh toán đơn hàng",
            "remitter": {
              "type": "BANK",
              "number": "9704000000000018",
              "fullName": "Nguyen Van A",
              "swiftCode": "SBITVNVX",
              "bankName": "SaigonBank"
            },
            "paidAt": "2023-05-20T04:03:55.244Z"
          }
        },
        "conclusion": {
          "actionType": "CREATE_ORDER",
          "transaction": "QEITL1358ZE8",
          "partnerTransaction": "84561328114953",
        },
        "createdBy": "nguyenvana",
        "createdAt": "2023-05-20T04:04:55.244Z",
        "finishedAt": "2023-05-20T04:08:01.214Z",
    }   
}

4.2. API Lấy danh sách lệnh chờ xử lý:

• Mô tả: API do PayME cung cấp dùng để lấy danh sách các lệnh chờ xử lý.

• Path: /dispute/payment/list

• Method: POST

Request Parameters:

• Payload:

Tham số	Kiểu dữ liệu	Bắt buộc	Ý nghĩa
filter	Object		Chứa thông tin các tham số truy vấn chỉ định biểu thức lọc lệnh chờ xử lý
paging	Object	✔	Chứa thông tin chỉ định số lượng lệnh chờ xử lý
sort	Object		Chứa thông tin cách sắp xếp kết quả danh sách lệnh chờ xử lý
language	String		Ngôn ngữ hiển thị vi/en. Mặc định: vi

• Cấu trúc của Object filter

Key	Kiểu dữ liệu	Bắt buộc	Ý nghĩa
createdAt	Object		Thời gian tạo lệnh chờ xử lý
finishedAt	Object		Thời gian hoàn thành lệnh chờ xử lý
paymentAt	Object		Thời gian thanh toán lệnh chờ xử lý
statusList	Array		Danh sách trạng thái lệnh chờ xử lý: OPEN: Chờ xử lý PROCESSING: Đang xử lý COMPLETED: Đã xử lý
type	String		Loại chờ xử lý: NOT_MATCH_AMOUNT: Tìm thấy đơn hàng nhưng không đúng số tiền NOT_MATCH_ORDER: Không tìm thấy đơn hàng

• Cấu trúc của Object createdAt

Key	Kiểu dữ liệu	Bắt buộc	Ý nghĩa
from	Date		Thời điểm bắt đầu của khoảng thời gian muốn lấy danh sách lệnh chờ xử lý theo ngày tạo
to	Date		Thời điểm kết thúc của khoảng thời gian muốn lấy danh sách lệnh chờ xử lý theo ngày tạo

• Cấu trúc của Object finishedAt

Key	Kiểu dữ liệu	Bắt buộc	Ý nghĩa
from	Date		Thời điểm bắt đầu của khoảng thời gian muốn lấy danh sách lệnh chờ xử lý theo ngày hoàn thành
to	Date		Thời điểm kết thúc của khoảng thời gian muốn lấy danh sách lệnh chờ xử lý theo ngày hoàn thành

• Cấu trúc của Object paymentAt

Key	Kiểu dữ liệu	Bắt buộc	Ý nghĩa
from	Date		Thời điểm bắt đầu của khoảng thời gian muốn lấy danh sách lệnh chờ xử lý theo ngày thanh toán
to	Date		Thời điểm kết thúc của khoảng thời gian muốn lấy danh sách lệnh chờ xử lý theo ngày thanh toán

• Cấu trúc của Object paging

Key	Kiểu dữ liệu	Bắt buộc	Ý nghĩa
start	Number		Điểm bắt đầu lấy danh sách lệnh chờ xử lý. Mặc định: 0
limit	Number		Số lệnh chờ xử lý cần lấy. Mặc định: 20

• Cấu trúc của Object sort

Key	Kiểu dữ liệu	Bắt buộc	Ý nghĩa
createdAt	Number		Sắp xếp kết quả danh sách lệnh chờ xử lý theo ngày tạo. Mặc định: - 1 1: Theo thứ tự tăng dần ngày tạo -1: Theo thứ tự giảm dần ngày tạo

• Response:

Key	Kiểu dữ liệu	Mô Tả
code	Number	Mã lỗi: 128218: Lấy danh sách lệnh thanh toán không khớp thành công. 100101: Không tìm thấy thông tin tài khoản. 100100: Không tìm thấy thông tin doanh nghiệp.
message	String	Mô tả thông tin mã lỗi
data	Array	Dữ liệu trả về gồm có các item có field bên dưới:

• Cấu trúc các item của Array data

Key	Kiểu dữ liệu	Mô Tả
disputeId	String	Mã lệnh chờ xử lý
referOrder	Object	Thông tin đơn hàng gốc (Trường hợp tìm thấy đơn hàng mà không đúng số tiền)
method	String	Phương thức thanh toán
amount	Number	Số tiền thực nhận
type	String	Loại chờ xử lý: NOT_MATCH_AMOUNT: Tìm thấy đơn hàng nhưng không đúng số tiền NOT_MATCH_ORDER: Không tìm thấy đơn hàng
state	String	Trạng thái lệnh chờ xử lý OPEN: Chờ xử lý PROCESSING: Đang xử lý COMPLETED: Đã xử lý
createdAt	Date	Thời gian tạo lệnh chờ xử lý
finishedAt	Date	Thời gian xử lý lệnh chờ xử lý
paymentAt	Date	Thời gian thanh toán

Cấu trúc của Object referOrder :

Key	Type	Mô Tả
transaction	String	Mã giao dịch đơn hàng gốc
partnerTransaction	String	Mã giao dịch đơn hàng gốc do Merchant tạo ra
amount	Number	Số tiền của đơn hàng gốc

Ví dụ:

• Payload mẫu trước khi encrypt:

{
  "filter": {
    "createdAt": {
      "from": "2023-06-20T07:50:11.820Z",
      "to": "2023-07-30T07:50:11.820Z"
    },
    "finishedAt": {
      "from": "2023-06-20T07:50:11.820Z",
      "to": "2023-07-30T07:50:11.820Z"
    },
    "statusList": ["OPEN"],
  },
  "paging": {
    "start": 0,
    "limit": 20
  },
  "sort": {
    "createdAt": -1
  }
}

• Response mẫu trước khi encrypt:

{
  "code": 128218,
  "message": "Lấy danh sách lệnh thanh toán không khớp thành công.",
  "data": [
    {
        "disputeId": "3391I33CEIFE",
        "referOrder": {
            "orderId": "261EDQDKZXAR",
            "paymentId": "HFZ9HZ55W8ED",
            "partnerTransaction": "143160270691",
            "amount": 20000
        },
        "method": "VIETQR",
        "amount": 19000,
        "type": "NOT_MATCH_AMOUNT",
        "state": "OPENT",
        "createdAt": "2023-06-30T07:50:11.820Z",
        "finishedAt": "2023-06-30T07:50:11.820Z",
        "paymentAt": "2023-06-30T07:29:01.543Z"
    },
    {
        "disputeId": "A5LCMK831951",
        "referOrder": {
            "orderId": "PDBNQGQ4SF71",
            "paymentId": "72A9PIH070SP",
            "partnerTransaction": "866325282448",
            "amount": 10000
        },
        "method": "VIETQR",
        "amount": 9000,
        "type": "NOT_MATCH_AMOUNT",
        "state": "COMPLETED",
        "createdAt": "2023-07-10T04:35:20.945Z",
        "finishedAt": "2023-07-10T04:35:20.945Z",
        "paymentAt": "2023-06-30T01:41:28.251Z"
    }
  ]
}

4.3. API xử lý lệnh chờ xử lý:

• Mô tả: API do PayME cung cấp dùng để xử lý lệnh chờ xử lý cho MC. Khi xử lý thành công PayME sẽ IPN về cho MC.

• Path: /dispute/payment/process

• Method: POST

Request Parameters:

• Payload:

Tham số	Kiểu dữ liệu	Bắt buộc	Ý nghĩa
disputeId	String	✔	Mã của lệnh chờ xử lý.
actionType	String	✔	Hành động xử lý lệnh chờ xử lý, đối với loại thanh toán Trường hợp loại chờ xử lý NOT_MATCH_AMOUNT: MATCH_ORDER: Khớp đơn hàng gốc ứng với số tiền đã thanh toán. TOPUP: Nạp tiền vào số dư ví của Merchant. CREATE_ORDER: Tạo mới một đơn hàng ứng với số tiền đã thanh toán. REFUND: Hoàn tiền về tài khoản của khách hàng đã thanh toán. Trường hợp loại chờ xử lý NOT_MATCH_ORDER: TOPUP: Nạp tiền vào số dư ví của Merchant. CREATE_ORDER: Tạo mới một đơn hàng mới ứng với số tiền đã thanh toán. REFUND: Hoàn tiền về tài khoản của khách hàng đã thanh toán.
partnerTransaction	String		Đối với hành động xử lý lệnh chờ xử lý: actionType=CREATE_ORDER , MC cần gửi thêm thông tin mã giao dịch của MC (bắt buộc gửi)
beneficiary	Object		Thông tin tài khoản người thụ hưởng. Đối với hành động xử lý lệnh chờ xử lý: actionType = REFUND , trường hợp không thể hoàn tiền về tài khoản của khách hàng đã thanh toán, PayME sẽ hoàn tiền về số tài khoản này
language	String		vi/en, ngôn ngữ hiển thị

• Cấu trúc của Object beneficiary

Key	Kiểu dữ liệu	Bắt buộc	Ý nghĩa
number	String	✔	Số tài khoản
fullName	String	✔	Tên tài khoản
swiftCode	String	✔	Swift Code ngân hàng

• Response:

Key	Type	Mô Tả
code	Number	Mã lỗi: 128230: Xử lý lệnh chờ xử lý thành công 128231: Xử lý lệnh chờ xử lý thất bại. 100101: Không tìm thấy thông tin tài khoản. 100100: Không tìm thấy thông tin doanh nghiệp
message	String	Mô tả thông tin mã lỗi
data	Object	Dữ liệu trả về là Object có các field bên dưới:

Cấu trúc của Object data :

Key	Type	Mô Tả
disputeId	String	Mã lệnh chờ xử lý
state	String	Trạng thái lệnh chờ xử lý OPEN: Chờ xử lý PROCESSING: Đang xử lý COMPLETED: Đã xử lý

Ví dụ:

• Payload mẫu trước khi encrypt:

{
    "disputeId": "TEAUTN13KS",
    "actionType": "CREATE_ORDER",
    "partnerTransaction": "84561328114953",
    "language": "vi"
}

Trường hợp có thông tin người thụ hưởng (beneficiary):

{
    "disputeId": "TEAUTN13KS",
    "actionType": "REFUND",
    "beneficiary": {
        "account": "9704000000000018",
        "fullname": "NGUYEN VAN A",
        "swiftCode": "SBITVNVX"
    },
    "language": "vi"
}

• Response mẫu trước khi encrypt:

{
    "code": 128230,
    "message": "Tiếp nhận xử lý lệnh chờ xử lý thành công",
    "data": {
        "disputeId":"TEAUTN13KS",
        "state": "PROCESSING"
    }   
}

4.4. IPN khi có lệnh chờ xử lý:

• Mô tả: API do MC cung cấp, PayME gọi API để thông báo có lệnh chờ xử lý mới hoặc khi xử lý thành công.

• Path: Do MC cung cấp khi tạo kết nối

• Method: POST

Request Parameters:

• Payload :

Key	Type	Mô Tả
disputeId	String	Mã lệnh chờ xử lý
referOrder	Object	Thông tin đơn hàng gốc (Trường hợp tìm thấy đơn hàng mà không đúng số tiền)
payMethod	String	Phương thức thanh toán
amount	String	Số tiền thực nhận
type	String	Loại chờ xử lý: NOT_MATCH_AMOUNT: Tìm thấy đơn hàng nhưng không đúng số tiền NOT_MATCH_ORDER: Không tìm thấy đơn hàng
state	String	Trạng thái lệnh chờ xử lý: OPEN: Chờ xử lý PROCESSING: Đang xử lý COMPLETED: Đã xử lý
conclusion	Object	Thông tin kết quả xử lý lệnh chờ xử lý
createdBy	String	Tài khoản tạo lệnh chờ xử lý
createdAt	Date	Thời gian tạo lệnh chờ xử lý
finishedAt	Date	Thời gian xử lý lệnh chờ xử lý

Cấu trúc của Object referOrder :

Key	Type	Mô Tả
transaction	String	Mã giao dịch đơn hàng gốc
partnerTransaction	String	Mã giao dịch đơn hàng gốc do Merchant tạo ra
amount	Number	Số tiền của đơn hàng gốc

• Cấu trúc Object của conclusion

Key	Kiểu dữ liệu	Ý nghĩa
actionType	String	Hành động xử lý lệnh chờ xử lý, đối với loại thanh toán Trường hợp loại chờ xử lý NOT_MATCH_AMOUNT: MATCH_ORDER: Khớp đơn hàng gốc ứng với số tiền đã thanh toán. TOPUP: Nạp tiền vào số dư ví của Merchant. CREATE_ORDER: Tạo mới một đơn hàng ứng với số tiền đã thanh toán. REFUND: Hoàn tiền về tài khoản của khách hàng đã thanh toán. Trường hợp loại chờ xử lý NOT_MATCH_ORDER: TOPUP: Nạp tiền vào số dư ví của Merchant. CREATE_ORDER: Tạo mới một đơn hàng mới ứng với số tiền đã thanh toán. REFUND: Hoàn tiền về tài khoản của khách hàng đã thanh toán.
transaction	String	Mã đơn hàng đã được xử lý cho loại hành động MATCH_ORDER, CREATE_ORDER
partnerTransaction	String	Mã giao dịch của Merchant đã được xử lý cho loại hành động MATCH_ORDER, CREATE_ORDER

   • Response:

Key	Type	Mô Tả
code	Number	Mã lỗi: 1000: Thành công 1001: Thất bại
message	String	Mô tả thông tin mã lỗi

Ví dụ:

• Payload mẫu trước khi encrypt:

{
  "disputeId": "TEAUTN13KS",
  "referOrder": {
    "transaction": "TKLAREI19Q92",
    "partnerTransaction": "1233494127812",
    "amount": 30000
  },
  "payMethod": "VIETQR",
  "amount": 32100,
  "type": "NOT_MATCH_AMOUNT",
  "state": "OPEN",
  "conclusion": null,
  "createdBy": "nguyenvana",
  "createdAt": "2023-05-20T04:04:55.244Z",
  "finishedAt": null,
}

• Response mẫu trước khi encrypt:

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

5. Ứng Lương

5.1 API Tạo ứng lương

• Mô tả: API do PayME cung cấp dùng để tạo yêu cầu ứng lương.
• Path: /salaryAdvance
• Method : POST

Request Parameters:

• Payload:

Key	Required	Type	Mô tả
fullname	Yes	String	tên người ứng lương
amount	Yes	Number	Số tiền muốn ứng
content	Yes	String	Nội dung ứng lương
salary	Yes	Number	Tiền lương một tháng
kycInfo	Yes	Object	Thông tin kyc (chi tiết bên dưới)
company	Yes	String	Tên công ty
partnerTransaction	Yes	String	Mã giao dịch của của đơn chi do MC tạo ra là duy nhất và không cho phép gửi trùng, dùng để truy vấn giao dịch
supplier	No	String	Nhà cung cấp
destination	Yes	Object	Thông tin tài khoản người nhận
ipnUrl	No	Object	PayME sẽ thông báo trạng thái ứng lương; ipnUrl được gọi để thông báo kết quả ứng lương thất bại hoặc thành công.
workDay	Yes	Number	Tổng ngày công từ trước đến giờ
workDayInMonth	Yes	Number	Ngày công trong tháng hiện tại
language	No	String	Ngôn ngữ hiển thị. Mặc định là vi

Cấu trúc object destination

Key	Type	Mô tả
wallet	Object	Thông tin tài khoản ví
bankAccount	Object	Thông tin tài khoản ngân hàng

Cấu trúc object wallet

Key	Type	Mô tả
phone	String	Số điện thoại
fullname	String	Họ tên

Cấu trúc object bankAccount

Key	Type	Mô tả
accountNumber	String	Số tài khoản
accountName	String	Tên tài khoản
swiftCode	String	Swift Code ngân hàng

Cấu trúc object kycInfo

Key	Required	Type	Môtả
fullname	Yes	String	Tên của khách hàng
gender	Yes	Enum(MALE, FEMALE)	Giới tính
birthday	Yes	String	Ngày sinh (DD/MM/YYYY)
address	Yes	String	Thông tin về địa chỉ của khách hàng
identifyType	Yes	Enum (CMND, CCCD)	Loại thẻ chứng thực của khách hàng
identifyNumber	Yes	String	Số CMND, CCCD
issuedAt	Yes	String	Ngày phát hành thẻ (DD/MM/YYYY)
placeOfIssue	Yes	String	Nơi phát hành thẻ
video	No	String	URL video quay khuôn mặt của khách hàng
face	No	String	URL hình chụp khuôn mặt của khách hàng
image	No	Object	Object chứa URL hình chụp CMND/CCCD của khách hàng (2)

Thông tin của Object Image

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

• Response:

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ề gồm có các field bên dưới: Key Type Mô Tả transactionId String Mã giao dịch của của PayME GP unique trên toàn hệ thống amount Number Số tiền muốn ứng fee Number Phí tiền ứng lương total Number Tổng tiền nhận state String Trạng thái ứng lương

Mã lỗi	Mô tả
100101	Không tìm thấy thông tin tài khoản
100100	Không tìm thấy thông tin merchant
101003	Lấy thông tin chuyển tiền thất bại
101005	Tên không trùng với tài khoản ví
101204	Tài khoản ví chưa KYC
101006	Tên không trùng với tài khoản ngân hàng
101001	Gửi yêu cầu ứng lương thất bại
101000	Gửi yêu cầu ứng lương thành công

Ví dụ:

• Payload mẫu trước khi encrypt:

{
    "fullname": "Nguyen Van A",
    "amount": 5000000,
    "salary": 5000000,
    "company": "ABC",
    "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",
                },
        },
    "destination":
        {
            "bankAccount":
                {
                    "accountNumber": "0129837294",
                    "accountName": "HA NAM NINH",
                    "swiftCode": "HLBBVNVX",
                },
        },
    "workDay": 120,
    "workDayInMonth": 15,
}

• Response mẫu trước khi encrypt:

{
    "code": 129001,
    "message": "Gửi yêu cầu ứng lương thành công",
    "data":
        { "transactionId": "921535982", "partnerTransaction": "456", "state": "PENDING", "amount": 50000, "fee": 0, "total": 50000 },
}

5.2 API Truy Vấn Ứng Lương

• Mô tả: API do PayME cung cấp dùng để tra cứu trạng thái của yêu cầu ứng lương.
• Path: /salaryAdvance/query
• Method : POST

Request Parameters:

• Payload:

Key	Required	Type	Mô tả
transactionId	Yes	Number	Mã ứng lương
language	No	String	Ngôn ngữ hiển thị. Mặc định là 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à object data các thông tin cần thiết

Cấu trúc object data:

Key	Type	Mô tả
transactionId	String	Mã ứng lương
fullname	String	Tên người ứng lương
content	String	Nội dung ứng lương
state	String	Trạng thái ứng lương [PENDING, FAILED, REJECT, APPROVED, SUCCEEDED]
amount	Number	Số tiền muốn ứng
total	Number	Tổng tiền lương sẽ ứng sau khi tính phí
fee	Number	Phí ứng lương
salary	Number	Tiền lương một tháng

Mã lỗi	Mô tả
101101	Không tìm thấy yêu cầu ứng lương
101100	Lấy trạng thái ứng lương thành công
101102	Lấy trạng thái ứng lương bại

Ví dụ:

• Payload mẫu trước khi encrypt:

{ "transactionId": "921535982" }

• Response mẫu trước khi encrypt:

{
  "code":101100,
  "message":"Lấy trạng thái ứng lương thành công",
  "data":
      { "transactionId": "921535982", "state": "PENDING", "fullname": "Nguyen Van A" ,"amount":5000000,"fee":0,"total":0 ,"salary":7000000, "content" : "Ứng lương" } 
   
}

5.3 IPN Ứng Lương

• Mô tả: API do MC cung cấp, PayME gọi API để thông báo kết quả chuyển tiền ứng lương.
• Path: Do MC cung cấp khi gửi yêu cầu ứng lương
• Method : POST

Request Parameters:

• Payload:

Key	Type	Mô tả
transactionId	String	Mã giao dịch của PayME
partnerTransaction	String	Mã giao dịch của MC
state	Enum	Trạng thái ứng lương: SUCCEEDED: Chuyển tiền ứng lương thành công FAILED: Ứng lương thất bại CANCELED: Đã hủy PENDING: chờ xử lý
transferedAt	Datetime	Thời gian chuyển
createdAt	Datetime	Thời gian khởi tạo lệnh chi

• Response:

Key	Type	Mô tả
code	Number	Mã lỗi 1000: Thành công, MC đã ghi nhân kết quả IPN 1001: Thất bại
message	String	Mô tả thông tin mã lỗi

Mã lỗi	Mô tả
131010	Thanh toán ứng lương thành công
131011	Thanh toán ứng lương thất bại

Ví dụ:

• Payload mẫu trước khi encrypt:

{
    "transactionId": "123",
    "partnerTransaction": "456",
    "state": "SUCCEEDED",
    "transferedAt": "2021-04-27 03:52:06.433Z"
}

• Response mẫu trước khi encrypt:

{
  "code": 1000,
  "message": "Ghi nhân IPN thành công"
}

6. Thanh toán SDK

6.1. API Kiểm tra số dư Ví

• Mô tả: API do PayME cung cấp dùng để kiểm tra số dư Ví PayME từ SDT của khách hàng. (số Phone này phải được Khách hàng liên kết ví payME trước đó)
• URL POST: /ewallet/sdk/balance

Request Parameters:

• Payload:

Tham số	Kiểu dữ liệu	Bắt buộc	Ý nghĩa
phone	String	✔	Số điện thoại khách hàng tiến hành thanh toán
lang	String		Ngôn ngữ (vi/en). Mặc định vi

• Response:

Key	Type	Mô tả
code	Number	Mã lỗi giao dịch, bao gồm 140000: Lấy số dư thành công 140001: Lấy thông tin thất bại
message	String	Mô tả thông tin mã lỗi
data	Object	Dữ liệu trả về gồm có: Key Type Mô Tả balance Number Số dư Ví PayME

Ví dụ:

• Payload mẫu trước khi encrypt:

{
  "phone": "0944074831",
  "lang": "vi"
}

• Response mẫu trước khi encrypt:

{
  "code": 140000,
  "message": "Lấy thông tin thành công",
  "data": { "balance": 75999859 }
}

6.2. API thanh toán đơn hàng SDK

• Mô tả: API dùng để thanh toán đơn hàng SDK bằng tài khoản Ví PayME khách hàng đã liên kết.
• URL POST: /ewallet/sdk/pay

Request Parameters:

• Payload:

Tham số	Kiểu dữ liệu	Bắt buộc	Ý nghĩa
partnerTransaction	String	✔	Mã giao dịch của của đơn chi do MC tạo ra là duy nhất và không cho phép gửi trùng, dùng để truy vấn giao dịch
amount	Number	✔	Số tiền cần thanh toán
phone	String	✔	Số điện thoại thanh toán đơn hàng (số Phone này phải được Khách hàng liên kết ví payME trước đó)
description	String (256)	✔	Mô tả đơn hàng để hiển thị cho khách hàng
language	Enum		vi/en, ngôn ngữ hiển thị cho khách hàng

• Response:

Key	Type	Mô tả
code	Number	Mã lỗi giao dịch, bao gồm 130000: Thanh toán thành công 130001: Không tìm thấy thông tin doanh nghiệp 130002: Doanh nghiệp chưa được sử dụng tính năng này 130003: Không tìm thấy liên kết Ví PayME 130004: Không tìm thấy thông tin kết nối 130005: Có lỗi xảy ra khi tạo đơn hàng 130006: Lỗi hệ thống, vui lòng thử lại sau
message	String	Mô tả thông tin mã lỗi
data	Object	Dữ liệu trả về gồm có : Key Type Mô Tả transaction String Mã giao dịch của PayME partnerTransaction String Mã giao dịch của MC

Ví dụ:

• Payload mẫu trước khi encrypt:

{
  "amount ": 20000,
  "partnerTransaction": "5849542.881047385GaRyhwWxy",
  "phone": "0944074831",
  "description": "Mota"
}

• Response mẫu trước khi encrypt:

{
  "code": 130000,
  "message": "Tạo đơn hàng thành công",
  "data": {
    "transaction": "9180449484",
    "partnerTransaction": "5849542.881047385GaRyhwWxy"
  }
}