Payme Payment Gateway - Cổng thanh toán Payme - PPG

Cổng thanh toán Payme – Payme Payment Gateway (PPG) cung cấp các API tạo và nhận thanh toán thông qua các nhà cung cấp của PAYME như Ví Payme, Alilay, Hệ thống Ngân Hàng, Visa, Master…

Mỗi đối tác của Payme sẽ được cấp một tài khoản PGG kèm theo 1 merchant (đi kèm theo là merchantId) đại diện pháp lý để thực hiện các giao dịch, cũng là khái niệm dùng để đối soát doanh số.

Mỗi Merchant có thể khai báo nhiều Cửa hàng, điểm giao dịch cho mình để thực hiện thanh toán và phân chia doanh số theo cửa hàng, điểm giao dịch.

Payme Transaction (viết tắt transaction) là một mã giao dịch PPG tạo ra để định danh cho một giao dịch. Mã giao dịch này là duy nhất trên toàn hệ thống PPG

Partner Transaction ID (viết tắt partnerTransaction) là mã giao dịch đối tác gửi qua Payme để tiến hành thanh toán, mã giao dịch này cần là duy nhất trên mỗi merchantId và cũng là đối ứng 1 – 1 với transaction

Là chuỗi xác thực có được khi login thành công vào cổng thanh toán và tiến hành tạo Key thanh toán, dùng để chứng thực tính hợp lệ của các yêu cầu gửi lên từ đối tác.

Thông tin bổ sung (extraData) là một nội dung được định nghĩa theo dạng chuỗi, chứa thông tin bổ sung của một giao dịch mà đối tác muốn nhận về khi hoàn tất một giao dịch với PAYME.

Các bước cơ bản để tích hợp với Payme

• Gửi thông tin đăng ký tài khoản doanh nghiệp
• Lựa chọn phương thức thanh toán áp dụng cho đơn vị kinh doanh
• PAYME cung cấp thông tin môi trường Sandbox để đối tác tích hợp
• Đối tác tiến hành kết nối API theo tài liệu bằng thông tin PAYME cung cấp
• Tiến hành kiểm thử trước khi nghiệm thu kết nối
• Sau khi nghiệm thu, PAYME sễ cung cấp thông tin kết nối môi trường Production
• Đối tác tiến hành chuyển đổi môi trường và cập nhật theo các thông tin Production mà PAYME đã cung cấp
• Triển khai dịch vụ thanh toán cho khách hàng

Payme cung cấp cho đối tác kinh doanh ba môi trường để tích hợp với PPG api:

• Sandbox: Sự dụng trong quá trình bắt đầu tích hợp, có các data test cung cấp để tiện kết nối, kiểm thử
  Domain : https://sbx-pg.payme.vn/

• Production: Sự dụng trong quá trình triển khai production, môi trường và dữ liệu tương đương với môi trường production nhưng chỉ cung cấp cho đối tác dùng để tích hợp kiểm thử (UAT)
  Domain : Sẽ cung cấp sau khi nghiệm thu kết thúc

• Production: Sử dụng để triển khai cho khách hàng thanh toán dịch vụ, sẽ cung cấp khi tiến hành khi release cho Merchant

====================================================

• Merchant ID: Sau khi đăng ký tài khoản doanh nghiệp, đối tác sẽ được cung cấp thông tin id này.
• AccessToken: Mã xác thực quyền truy cập các API PPG sẽ được tạo sau khi hoàn tất quá trình Lựa chọn Phương Thức Thanh Toán

- Mã Hoá dữ liệu :

Mọi dữ liệu từ phía Merchant cần được mã hoá (encrypt) tất cả trước khi gửi yêu cầu (request) lên PPG API, bao gồm body chứa payload đã mã hóa) và headers (chứa dữ liệu mã hóa tương ứng)
Tương tự kết quả phản hồi (response) khi trả về cũng sẽ được mã hoá và Merchant sẽ dùng key để giải mã (decrypt) ra dữ liệu

• Chuẩn mã hoá : AES và RSA-SHA256.
• Payme Public key: Payme sẽ cung cấp 1 publicKey cho mỗi merchant, dùng để các mã hoá (encrypt) dữ liệu Merchant gửi yêu cầu lên
  Payme sẽ dùng Private Key cùng cặp để giải mã (decrypt) các dữ liệu này
• Partner Public key: Partner sẽ cung cấp 1 publicKey cho Payme khi tiến hành đăng ký, Payme sẽ dùng key này mã hoá (encrypt) các dữ liệu trả về cho Merchant Merchant sẽ dùng Private Key cùng cặp để giải mã (decrypt) các dữ liệu này

Thư viện thuật toán mã hóa RSA thảm khảo tại :

• NodeRSA: (https://www.npmjs.com/package/node-rsa)
• CryptoJS: (https://www.npmjs.com/package/cryptojs)
• MD5: (https://www.npmjs.com/package/md5)

Thuật toán RSA được PAYME sử dụng theo chuẩn: PKCS1 - SHA256, encoding base64

• Cấu trúc 1 request gồm có những dữ liệu sau:

là 1 Json Object chứa

Key	Value	Type
x-api-message	String	là 1 đoạn mã được Encrypt từ chuỗi ghép {payload + encryptKey*} bằng thuật toán AES*

• Payload : là Json RequestParam của API • encryptKey* (string) : là 1 request key tạo ra khi gửi yêu cầu để phân biệt các yêu cầu với nhau, và sẽ được trả về khi response

là 1 Json Object bao gồm

Key	Type	Value
x-api-client	String	Là 1 chuỗi định danh được cung cấp cho merchant khi tiến hành kết nối
x-api-key	String	Là 1 chuỗi mã hoá dùng publicKey do Payme cung cấp để encrypt base64 đoạn encryptKey* ở Body
x-api-action	String	Dữ liệu mã hóa được tạo ra từ chuỗi (API Path + encryptKey*) với phương thức mã hóa AES
Authorization	String	Là accessToken key user được cấp khi login hoặc server sẽ cung cấp khi kết nối
x-api-validate	String	Là đoạn mã checksum Md5 từ 1 mảng bao gồm những data gửi lên theo thứ tự

Thứ tự mảng dữ liệu sinh x-api-validate

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

• Request API : /v2/Partner/Search

• Method: Post

• Payload: { filter: {}, paging: { start: 0, limit: 100 }, sort: {} }

• AccessToken: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ODE1LCJhY2NvdW50SWQiOSAAAS'

• Request:
  body: { 'x-api-message': 'U2FsdGVkX1+yCZ3g9E4FZC9hqqZFSqz9vnwFNmmsy2sw0CoBHilM6ewqcaS5mU2GWYiZ4rck/2QAjCs3Ygy0yYBsUUMyoZN1bZOUKlwAoTs=' } ,

• Headers:
  { 'x-api-client': 'app', 'x-api-key': 'R9YXgudwaR2Y1mQmCxbV5x8Ue8FKzIeM4rvEpabyEPb2eBaIKj9wexp72xNF13CYA/2780xrSY/6MIH/aWYe0g==', 'x-api-action': 'U2FsdGVkX1+TMinBr+1CKh2In0/GVCygOON4FeuxTuiHCqMlu1m98y3emDBI2IXM4mhxgAIPlPioaKuvITrQPQ==', 'x-api-validate': '82e9efa80d41953cc8d5e9030cb1644b', Authorization: 'eyJhbGciOiJIUzI1NiIsInR5cCI6ICJ9.eyJpZCI6ODE1LCJhY2NvdW50SWQiOjE1LCJpYXQiOjE1Njk4Mjk3MTV9.8KAQbG7ue-jHlgwAAHYEMUhA48LIBX6o3Vggv_mcE' }

=====================

• Cấu trúc 1 response gồm có những dữ liệu sau:

là 1 Json Object bao gồm

Key	Type	Value
x-api-key	String	Là 1 chuỗi mã hoá dùng publicKey của Merchant cung cấp để encrypt base64 đoạn encryptKey* ở Body, merchant sẽ dùng PrivateKey để decrypt
x-api-client	String	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	Là api action đã request
x-api-validate	String	Là đoạn mã checksum Md5 từ 1 mảng bao gồm những data gửi lên theo thứ tự

Thứ tự mảng dữ liệu sinh x-api-validate

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

là 1 Json Object chứa

Key	Value	Type
x-api-message	String	Payload dữ liệu trả về đã được mã hóa sử dụng encryptKey* đã lấy từ x-api-key trong phần header để decrypt

• Response:
  { 'x-api-key': 'eErPFr4DaZIIPGdNH1rCBgqL0KmsvGqU05gR7M2CS8emP8+BBP06VSGC3GVZMf6n3MSTXMM8E+1pp/+ZeBYE8Q==', 'x-api-client': 'app', 'x-api-action': 'U2FsdGVkX184NnKzc7X/shtZdF+aFax1XkTlE4DyYQLcPAYBOHdL1Xp7eyflzrd5uqZZY1SgpQ4bivi0o/ML1A==', 'x-api-validate': 'abb587105723e4705eceeb38dbea3f85', 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-cache', 'content-length': '108', date: 'Tue, 09 Jun 2020 10:29:31 GMT', connection: 'close' }

====================================================

Là flow thanh toán trực tiếp khi khách hàng quét Qr/mở link thanh toán do PPG cung cấp cho merchant và tiến hành thanh toán trực tiếp

• Bước 1: Khách hàng kiểm tra đơn hàng và tiến hành thanh toán
• Bước 2: Backend của Merchant kiểm tra đơn hàng và gọi API của PPG tạo yêu cầu thanh toán
• Bước 3: PPG kiểm tra yêu cầu thanh toán và trả về link thanh toán cho Merchant
• Bước 4: Frontend của Merchant [chuyển sang/mở] link thanh toán do Payme cung cấp cho Khách Hàng
• Bước 5: Khách hàng chọn các phương thức thanh toán và nhập các thông tin thanh toán bên trong trang thanh toán
• Bước 6: Sau khi khách hàng Submit trang thanh toán, PPG sẽ xử lý và báo kết quả về trang này, đồng thời IPN về callback URL của Merchant (được cung cấp khi tạo kết nối)
• Bước 7: Server của Merchant xác thực giao dịch và cập nhật dịch vụ cho khách hàng

Là flow thanh toán chỉ dùng cho 1 số nhà cung cấp đặc biết có cung cấp QR cá nhân cho khách hàng. Khi khách hàng muốn thanh toán sẽ tạo QR cá nhân và máy POS sẽ scan QR của khách để tiến hành thanh toán

• Bước 1: Khách hàng kiểm tra đơn hàng và tiến hành thanh toán
• Bước 2: Backend của Merchant kiểm tra đơn hàng và gọi API của PPG tạo yêu cầu thanh toán
• Bước 3: PPG kiểm tra yêu cầu thanh toán và xác nhận tạo thanh toán
• Bước 4: Máy POS scan QR của khách và gửi QR content của khách lên api thanh toán tương ứng
• Bước 5: Server PPG nhận QR và tiến hành thanh toán dự vào QR content do POS gửi lên
• Bước 6: Trả phản hồi về cho máy POS, đồng thời IPN kết quả giao dịch về callback URL của Merchant (được cung cấp khi tạo kết nối)
• Bước 7: Server của Merchant xác thực giao dịch và cập nhật dịch vụ cho khách hàng

**Lưu ý : trong 1 số trường hợp vì lý do kỹ thuật hoặc kết nối mạng, PPG ko thể IPN về cho Merchant và vượt quá số lần thử lại, Merchant có thể dùng API Tra cứu Yêu cầu thanh toán để lấy thông tin kết quả thanh toán (nếu đã có) và xử lý mà không đợi IPN

Là api dùng để tạo ra 1 link yêu cầu thanh toán thông qua PPG, khi 1 khách hàng sử dụng link sẽ có thể thanh toán qua các phương thức PPG cung cấp (vd : ví Payme, thẻ ATM, Visa…), sau khi thanh toán thành công, PPG sẽ callback về cho merchant thông tin thanh toán để xử lý Các thông tin thành toán này sẽ được tiến hành đối sát ở các kỳ thanh toán

/v1/Payment/Generate

Payload :

Key	Type	Required	Mô Tả	Ghi chú
amount	Number	YES	Số tiền yêu cầu khách hàng thanh toán	Tối thiểu 2.000 vnd và tối đa 10.000.000 VND
desc	String	YES	Hiển thị mô tả thanh toán khi khách hàng mở link yên cầu thanh toán lên	Có thể sử dụng tiếng Việt có dấu theo chuẩn Unicode, tối đa 256 ký tự
partnerTransaction	String	YES	Mã giao dịch của đôi tác	Là unique đối với mỗi Merchant
extraData	Json Object	NO	Data bổ sung của thanh toán, sau khi user thanh toán thành công, trong data IPN của PPG về cho Merchant

Yêu cầu mẫu trước khi encrypt :
{ "amount": 100.000, "partnerTransaction ": 124556274354, "desc": "Thanh toán tiền NET – KH 0012545", "extraData": { "partnerTransaction": 124556274354, "fullname" : "Nguyễn Văn A", "billId": 0012545 } }

Key	Type	Mô Tả
code	Number	Mã báo thành công hoặc lỗi dịch vụ, xem ở phần ghi chú mã lỗi
data	Json Object	Dữ liệu trả về gồm có các field bên dưới

• Cấu trúc Data :

Key	Type	Mô Tả
url	String	Link thanh toán của Payme đối tác sử dụng cho user thanh toán
transaction	String	Là mã giao dịch của Payme, là unique trên toàn hệ thống, có thể dùng để tra cứu giao dịch ở API mô tả bên dưới

Phản hồi mẫu trước khi encrypt :

{ "code": 1000, "data": { "url": "https://sbx-social.payme.vn/0933454934/2eb53d2c0a3tghma", "transaction": "5480589239" } }

Data sẽ gửi về đối tác ngay khi giao dịch hoàn tất, thông qua IPN URl đã khai báo lúc tạo Key kết nối

• Cấu trúc Data :

Key	Type	Mô Tả
transaction	String	Mã giao dịch của Payme
partnerTransaction	String	Mã giao dịch của đối tác
amount	Number	Số tiền yêu cầu khách hàng thanh toán
fee	Number	Phí khi sử dụng các cổng thanh toán đặc biệt (nếu có)
total	Number	Số tiền thu về thực của Merchant sau khi trừ phí và khuyến mãi (nếu có)
state	String	Mô tả trạng thái của yêu cầu 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
extraData	JSON	Data đối tác đã gửi lúc tạo yêu cầu thanh toán
createdAt	Date	Thời điểm tạo yêu cầu thanh toán
updatedAt	Date	Thời điểm cập nhật yêu cầu thanh toán lần cuối

Các trạng thái của yêu cầu thanh toán :

Key	Value
SUCCEEDED	Thanh toán đã thành công
FAILED	Thanh toán thất bại link đã vô hiệu lực
PENDING	Thanh toán đang chờ khách hàng thanh toán
EXPIRED	Thanh toán đã hết hạn không còn hiệu lực
CANCELED	Thanh toán đã bị huỷ từ Merchant
REFUNDED	Thanh toán đã được hoàn lại cho user trong 1 số trường hợp đặc biêt

---

Là api dùng để thanh toán qua thẻ ATM của khách hàng

/v1/Payment/ATM

Payload :

Key	Type	Required	Mô Tả	Ghi chú
card_number	Number	YES	Số thẻ ATM của khách	Viết liền
card_holder	String	YES	Tên in trên thẻ	Viết Hoa không dấu, tối đa 100 ký tự
issue_date	String	YES	Ngày phát hành thẻ	Format chuẩn MM/YY
paymentInfo	JsonObject	YES	Nội dung thanh toán	Xem info object bên dưới
returnUrl	String	NO	URL redirect sau khi user thanh toán thành công

Cấu trúc paymentInfo :

Key	Type	Required	Mô Tả	Ghi chú
amount	Number	YES	Số tiền yêu cầu khách hàng thanh toán	Tối thiểu 2.000 vnd và tối đa 10.000.000 VND
desc	String	YES	Hiển thị mô tả thanh toán	Có thể sử dụng tiếng Việt có dấu theo chuẩn Unicode, tối đa 256 ký tự
partnerTransaction	String	YES	Mã giao dịch của đôi tác	Là unique đối với mỗi Merchant
extraData	Json Object	NO	Data bổ sung của thanh toán, sau khi user thanh toán thành công, trong data IPN của PPG về cho Merchant

Yêu cầu mẫu trước khi encrypt :
{ "card_number" : "9704000000000001", "card_holder" : "NGUYEN VAN A", "issue_date" : "07/10", "returnUrl" : "http://payme.vn/SUCCESS" "paymentInfo" : { "amount": 100.000, "partnerTransaction ": 124556274354, "desc": "Thanh toán tiền NET – KH 0012545", "extraData": { "partnerTransaction": 124556274354, "fullname" : "Nguyễn Văn A", "billId": 0012545 } } }

Key	Type	Mô Tả
code	Number	Mã báo thành công hoặc lỗi dịch vụ, xem ở phần ghi chú mã lỗi
data	Json Object	Dữ liệu trả về gồm có các field bên dưới

• Cấu trúc Data :

Key	Type	Mô Tả
message	String	Thông báo kết quả thanh toán ngắn gọn
transaction	String	Là mã giao dịch của Payme, là unique trên toàn hệ thống, có thể dùng để tra cứu giao dịch ở API mô tả bên dưới
amount	Number	Số tiền GD
fee	Number	Phí thanh toán (nếu có)
total	Number	Link thanh toán của Payme đối tác sử dụng cho user thanh toán
description	String	Hiển thị mô tả thanh toán
state	String	Mô tả trạng thái của yêu cầu thanh toán**
form	String	Form giao dịch của mà client/web của merchant sẽ load lên để user xác nhận hoặc nhập OTP thanh toán

Phản hồi mẫu trước khi encrypt :

{ "code": 1000, "data": { "message": "Thành công" , "transaction": "00564161216", "amount": 100000, "fee": 1100, "total": 101100, "description": "Thanhg toán Hoá Đơn HD001", "state": "PENDING", "form:" "<........>" } }

Data sẽ gửi về đối tác ngay khi giao dịch hoàn tất, thông qua IPN URl đã khai báo lúc tạo Key kết nối

• Cấu trúc Data : tương tự data IPN Thanh toán qua WAP

---

Là api dùng để lấy thông tin thanh toán, sau đó khác hàng sẽ tiến thành thanh toán thủ công dựa vào thông tin thanh toán PPG trả về. Khi khách hàng thanh toán thành công, PPG sẽ IPN về cho Merchant để hoàn tất giao dịch

/v1/Payment/Manual

Payload :

Key	Type	Required	Mô Tả	Ghi chú
type	String	YES	Loại hình chuyển khoảng	Hiện tại chỉ hỗ trợ 2 loại hình là BANK và EWALLET
paymentInfo	JsonObject	YES	Nội dung thanh toán	Xem info object bên dưới

Cấu trúc paymentInfo :

Key	Type	Required	Mô Tả	Ghi chú
amount	Number	YES	Số tiền yêu cầu khách hàng thanh toán	Tối thiểu 2.000 vnd và tối đa 10.000.000 VND
desc	String	YES	Hiển thị mô tả thanh toán	Có thể sử dụng tiếng Việt có dấu theo chuẩn Unicode, tối đa 256 ký tự
partnerTransaction	String	YES	Mã giao dịch của đôi tác	Là unique đối với mỗi Merchant
extraData	Json Object	NO	Data bổ sung của thanh toán, sau khi user thanh toán thành công, trong data IPN của PPG về cho Merchant

Yêu cầu mẫu trước khi encrypt :
{ "type": "BANK", "paymentInfo" : { "amount": 100.000, "partnerTransaction ": 124556274354, "desc": "Thanh toán tiền NET – KH 0012545", "extraData": { "partnerTransaction": 124556274354, "fullname" : "Nguyễn Văn A", "billId": 0012545 } } }

Key	Type	Mô Tả
code	Number	Mã báo thành công hoặc lỗi dịch vụ, xem ở phần ghi chú mã lỗi
data	Json Object	Dữ liệu trả về gồm có các field bên dưới

• Cấu trúc Data :

Key	Type	Mô Tả
message	String	Thông báo kết quả thanh toán ngắn gọn
transaction	String	Là mã giao dịch của Payme, là unique trên toàn hệ thống, có thể dùng để tra cứu giao dịch ở API mô tả bên dưới
amount	Number	Số tiền GD
fee	Number	Phí thanh toán (nếu có)
total	Number	Link thanh toán của Payme đối tác sử dụng cho user thanh toán
description	String	Hiển thị mô tả thanh toán
state	String	Mô tả trạng thái của yêu cầu thanh toán**
expiredTime	Date	Thời điểm hết hạn thanh toán, yêu cầu sẽ bị vô hiệu
paymentContent	String	là đoạn QR Code số tk ngân hàng/Ví điện tử mà khách hàng sẽ quét để thanh toán

Phản hồi mẫu trước khi encrypt :

{ "code": 1000, "data": { "message": "Thành công" , "transaction": "00564161216", "amount": 100000, "fee": 1100, "total": 101100, "description": "Thanhg toán Hoá Đơn HD001", "state": "PENDING", "expiredTime": "2020-07-09 03:16:43.866" "paymentContent:" "13156445164610650431656316" } }

Data sẽ gửi về đối tác ngay khi giao dịch hoàn tất, thông qua IPN URl đã khai báo lúc tạo Key kết nối

• Cấu trúc Data : tương tự data IPN Thanh toán qua WAP

---

Là api dùng để thanh toán qua thẻ ATM của khách hàng

/v1/Payment/CreditCard

Payload :

Key	Type	Required	Mô Tả	Ghi chú
cardType	String	YES	Loại Thẻ Quốc Tế, hiện tại chỉ hỗ trợi VISA, MASTER
paymentInfo	JsonObject	YES	Nội dung thanh toán	Xem info object bên dưới
returnUrl	String	NO	URL redirect sau khi user thanh toán thành công

Cấu trúc paymentInfo :

Key	Type	Required	Mô Tả	Ghi chú
amount	Number	YES	Số tiền yêu cầu khách hàng thanh toán	Tối thiểu 2.000 vnd và tối đa 10.000.000 VND
desc	String	YES	Hiển thị mô tả thanh toán	Có thể sử dụng tiếng Việt có dấu theo chuẩn Unicode, tối đa 256 ký tự
partnerTransaction	String	YES	Mã giao dịch của đôi tác	Là unique đối với mỗi Merchant
extraData	Json Object	NO	Data bổ sung của thanh toán, sau khi user thanh toán thành công, trong data IPN của PPG về cho Merchant

Yêu cầu mẫu trước khi encrypt :
{ "cardType" : "VISA", "returnUrl" : "https://payme.vn/CCS_SUCCESS", "paymentInfo" : { "amount": 100.000, "partnerTransaction ": 124556274354, "desc": "Thanh toán tiền NET – KH 0012545", "extraData": { "partnerTransaction": 124556274354, "fullname" : "Nguyễn Văn A", "billId": 0012545 } } }

Key	Type	Mô Tả
code	Number	Mã báo thành công hoặc lỗi dịch vụ, xem ở phần ghi chú mã lỗi
data	Json Object	Dữ liệu trả về gồm có các field bên dưới

• Cấu trúc Data :

Key	Type	Mô Tả
message	String	Thông báo kết quả thanh toán ngắn gọn
transaction	String	Là mã giao dịch của Payme, là unique trên toàn hệ thống, có thể dùng để tra cứu giao dịch ở API mô tả bên dưới
amount	Number	Số tiền GD
fee	Number	Phí thanh toán (nếu có)
total	Number	Link thanh toán của Payme đối tác sử dụng cho user thanh toán
description	String	Hiển thị mô tả thanh toán
state	String	Mô tả trạng thái của yêu cầu thanh toán**
form	String	Form giao dịch của mà client/web của merchant sẽ load lên để user xác nhận hoặc nhập OTP thanh toán

Phản hồi mẫu trước khi encrypt :

{ "code": 1000, "data": { "message": "Thành công" , "transaction": "00564161216", "amount": 100000, "fee": 1100, "total": 101100, "description": "Thanhg toán Hoá Đơn HD001", "state": "PENDING", "form:" "<........>" } }

Data sẽ gửi về đối tác ngay khi giao dịch hoàn tất, thông qua IPN URl đã khai báo lúc tạo Key kết nối

• Cấu trúc Data : tương tự data IPN Thanh toán qua WAP

---

Là api dùng để tạo ra QR Code PayME mà khách hàng có thể dùng app Ví PayME hoặc các app chấp nhận Ví PayME để thanh toán

/v1/Payment/PayME/Direct

Payload :

Key	Type	Required	Mô Tả	Ghi chú
amount	Number	YES	Số tiền cần thanh toán	Min 10K, max 100M
currency	String	YES	Loại tiền tệ	Hiện tại chỉ chấp nhận VND
partnerTransaction	String	YES	Mã giao dịch của đối tác	cần unique trên mỗi giao dịch
title	String	YES	Tiêu đề	Có thể sử dụng tiếng Việt có dấu theo chuẩn Unicode, tối đa 256 ký tự
desc	String	YES	Hiển thị mô tả thanh toán	Có thể sử dụng tiếng Việt có dấu theo chuẩn Unicode, tối đa 256 ký tự
expiryAt	DateTime	NO	Thời điểm hết hạn thanh toán, yêu cầu sẽ bị vô hiệu	default 24h kể từ lúc tạo, theo chuẩn ISODate
extraData	Json Object	NO	Data bổ sung của thanh toán, sau khi user thanh toán thành công, trong data IPN của PPG về cho Merchant

Yêu cầu mẫu trước khi encrypt :
{ "amount": 10000, "currency": "VND", "partnerTransaction": "1800347240", "title": "Công Ty Song Long", "desc": "Thanh toán tiền NET", "expiryAt": "2021-01-16T10:26:22.980Z", "extraData": {} }

Key	Type	Mô Tả
code	Number	Mã báo thành công hoặc lỗi dịch vụ, xem ở phần ghi chú mã lỗi
data	Json Object	Dữ liệu trả về gồm có các field bên dưới

• Cấu trúc Data :

Key	Type	Mô Tả
message	String	Thông báo kết quả thanh toán ngắn gọn
transaction	String	Là mã giao dịch của PayME, là unique trên toàn hệ thống, có thể dùng để tra cứu giao dịch ở API mô tả bên dưới
qrContent	String	Nội dung QR, dùng nội dung này để tạo hình QR code cho user quét
url	String	Link thanh toán payme dùng build QRCode client

Phản hồi mẫu trước khi encrypt :

{ "code": 1000, "data": { "transaction": "6968015843", "url": "https://sbx-social.payme.vn/mecorpctcpgtdd-/21586848a2etrgn2", "qrContent": "https://sbx-social.payme.vn/mecorpctcpgtdd-/21586848a2etrgn2" } }

Data sẽ gửi về đối tác ngay khi giao dịch hoàn tất, thông qua IPN URl đã khai báo lúc tạo Key kết nối

• Cấu trúc Data : tương tự data IPN Thanh toán qua WAP

Là api dùng để tra cứu tình trạng hiện tại của 1 yêu cầu thanh toán thông qua Payme transaction

/v1/Payment/Information/{transaction}

Payload :

Key	Type	Required	Mô Tả	Ghi chú
transaction	String	YES	Mã giao dịch của Payme	Là unique đối với mỗi Merchant

Yêu cầu mẫu trước khi encrypt :
https://sbx-pg.payme.vn/v1/Payment/Information/{5480589239}

Key	Type	Mô Tả
code	Number	Mã báo thành công hoặc lỗi dịch vụ, xem ở phần ghi chú mã lỗi
data	Json Object	Dữ liệu trả về gồm có các field bên dưới

• Cấu trúc Data :

Key	Type	Mô Tả
amount	Number	Số tiền yêu cầu khách hàng thanh toán
fee	Number	Phí khi sử dụng các cổng thanh toán đặc biệt (nếu có)
total	Number	Số tiền thu về thực của Merchant sau khi trừ phí và khuyến mãi (nếu có)
state	String	Mô tả trạng thái của yêu cầu thanh toán**
url	String	Link yêu cầu 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
transaction	String	Mã giao dịch tra cứu
expiryAt	Date	Thời điểm yêu cầu thanh toán hết hạn
createdAt	Date	Thới điểm tạo yêu cầu thanh toán
updatedAt	Date	Thời điểm cập nhật yêu cầu thanh toán lần cuối

Các trạng thái của yêu cầu thanh toán :

Key	Value
SUCCEEDED	Thanh toán đã thành công
FAILED	Thanh toán thất bại link đã vô hiệu lực
PENDING	Thanh toán đang chờ khách hàng thanh toán
EXPIRED	Thanh toán đã hết hạn không còn hiệu lực
CANCELED	Thanh toán đã bị huỷ từ Merchant
REFUNDED	Thanh toán đã được hoàn lại cho user trong 1 số trường hợp đặc biêt

Phản hồi mẫu trước khi encrypt :

{ "code": 1000, "data": { "paidInfo": { "paidAt": null, "description": null }, "amount": 100000, "fee": 0, "total": 100000, "state": "PENDING", "url": "https://sbx-social.payme.vn/0933454934/2eb53d2c0a3tghma", "description": "Thanh toán tiền NET", "expiryAt": "2020-06-16T11:30:41.906Z", "transaction": "5480589239", "createdAt": "2020-06-09T11:29:49.995Z", "updatedAt": "2020-06-09T11:29:49.995Z" } }

Là api dùng để huỷ 1 yêu cầu thanh toán thông qua Payme transaction, yêu cầu này phải ở trạng thái chưa thành công mới được huỷ

/v1/Payment/{transaction}

Parameters :

Key	Type	Required	Mô Tả	Ghi chú
transaction	String	YES	Mã giao dịch của Payme muốn Huỷ	Là unique đối với mỗi Merchant

Yêu cầu mẫu trước khi encrypt :
DELETE https://sbx-pg.payme.vn/v1/Payment/{5480589239}

Key	Type	Mô Tả
code	Number	Mã báo thành công hoặc lỗi Huỷ giao dịch, xem ở phần ghi chú mã lỗi
transaction	String	Mã giao dịch tiến hành huỷ
message	String	Mô tả lỗi Huỳ không thành công nếu thất bại

Phản hồi mẫu trước khi encrypt :

Thành công :

{ "code": 1000, "transaction": "5480589239" }

Thất bại :

{ "code": 1000, "message": "Giao dịch đã hoàn tất, không thể Huỷ" }

Là api dùng để liên kết ví điện tử PayME

/v1/Link/PayME

Payload :

Key	Type	Required	Mô Tả	Ghi chú
phone	String	YES	Số điện thoại của Merchant dùng để liên kết ví

Yêu cầu mẫu trước khi encrypt :
{ "phone": "0933454933" }

Key	Type	Mô Tả
code	Number	Mã báo thành công hoặc lỗi dịch vụ, xem ở phần ghi chú mã lỗi
data	Json Object	Dữ liệu trả về gồm có các field bên dưới

• Cấu trúc Data :

Key	Type	Mô Tả
message	String	Thông báo tình trạng thành công hoặc thất bại

Phản hồi mẫu trước khi encrypt :

{ "code": 1000, "data": { "message": "Vui lòng nhập active code để xác thực thông tin ví" } }

Là api dùng để xác thực thông tin liên kết ví điện tử PayME

/v1/Link/PayME/Verify

Payload :

Key	Type	Required	Mô Tả	Ghi chú
phone	String	YES	Số điện thoại của Merchant dùng để liên kết ví
activeCode	String	YES	Mã kích hoạt dùng để xác thực

Yêu cầu mẫu trước khi encrypt :
{ "phone": "0933454933", "activeCode": "222313" }

Key	Type	Mô Tả
code	Number	Mã báo thành công hoặc lỗi dịch vụ, xem ở phần ghi chú mã lỗi
data	Json Object	Dữ liệu trả về gồm có các field bên dưới

• Cấu trúc Data :

Key	Type	Mô Tả
accessToken	String	Token OpenAPI dùng để gọi các API hổ trợ của ví điên tử PayME

Phản hồi mẫu trước khi encrypt :

{ "code": 1000, "data": { "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhY2NvdW50SWQiOiIzIiwicGFydG5lcklkIjoxLCJwaG9uZSI6Ijg0OTMzNDU0OTM0Iiwic291cmNlIjoiT3BlbkFQSSIsImlhdCI6MTU5NDI4MTcwN30.POfphM9iMlRLnRdct4tAW6W-QIwxd6eb3L5sc8S5jS4" } }

=======================================================

Là flow Merchant có thể dùng số dư Ví Payme đề tạo lệnh chuyển tiền cho user hoặc chính mình Sau khi tạo lệnh thành công, Merchant hoặc khách hàng sẽ có một link thanh toán và có thể chuyển tiền về các nguồn được Payme hỗ trợ

• Bước 1: Merchant gọi API của PPG tạo yêu cầu chuyển tiền
• Bước 2: PPG kiểm tra yêu cầu, số dư của Merchant và trả về link thanh toán cho Merchant nếu hợp lệ.
Link thanh toán này chứa số tiền yêu cầu và đã được trừ vào ví của Merchant
• Bước 3: Merchant nhận được link thanh có thể gửi cho khách hàng hoặc trực tiếp sử dụng
• Bước 4: Người sử dụng mở link thanh toán và chọn nguồn nhận tiền, sau đó submit các thông tin cần thiết
• Bước 6: Sau khi khách hàng submit, PPG sẽ xử lý và chuyền tiền cho khách hàng về đúng nơi đã chọn
Đồng thời báo kết quả về callback URL của Merchant (được cung cấp khi tạo kết nối)

/v1/Service/TransferMoney/Generate

Payload :

Key	Type	Required	Mô Tả	Ghi chú
amount	Number	YES	Số tiền yêu cầu khách hàng thanh toán	Tối thiểu 2.000 vnd và tối đa 10.000.000 VND
desc	String	YES	Hiển thị mô tả thanh toán khi khách hàng mở link yên cầu thanh toán lên	Có thể sử dụng tiếng Việt có dấu theo chuẩn Unicode, tối đa 256 ký tự
partnerTransaction	String	YES	Mã giao dịch của đôi tác	Là unique đối với mỗi Merchant
extraData	Json Object	NO	Data bổ sung của thanh toán, sau khi chuyển tiền thành công, trong data IPN của PPG về cho Merchant
passwordEnable	Boolean	NO	Option có cần bảo mật link thanh toán hay không	Nếu có thì link thanh toán sẽ được cấp 1 mật khẩu và người dùng cần nhập mới có thể nhận tiền

Yêu cầu mẫu trước khi encrypt :
{ "amount": 100.000, "partnerTransaction ": 124556274354, "desc": "Chuyển tiền cho KH 0012545", "extraData": { "partnerTransaction": 124556274354, "fullname" : "Nguyễn Văn A", "billId": 0012545 }, "passwordEnable": true }

Key	Type	Mô Tả
code	Number	Mã báo thành công hoặc lỗi dịch vụ, xem ở phần ghi chú mã lỗi
data	Json Object	Dữ liệu trả về gồm có các field bên dưới

• Cấu trúc Data :

Key	Type	Mô Tả
url	String	Link thanh toán cho khách hàng
password	String	Pass của Link thanh toán nếu có
transaction	String	Là mã giao dịch của Payme, là unique trên toàn hệ thống, có thể dùng để tra cứu giao dịch ở API mô tả bên dưới

Phản hồi mẫu trước khi encrypt :

{ "code": 1000, "data": { "url": "https://sbx-social.payme.vn/2ebad758e3msnm2m", "url": "201489", "transaction": "5480589239" } }

Data sẽ gửi về đối tác ngay khi giao dịch hoàn tất, thông qua IPN URl đã khai báo lúc tạo Key kết nối

• Cấu trúc Data :

Key	Type	Mô Tả
transaction	String	Mã giao dịch của Payme
partnerTransaction	String	Mã giao dịch của đối tác
amount	Number	Số tiền đã chuyển
fee	Number	Phí khi sử dụng các cổng thanh toán đặc biệt (nếu có)
total	Number	Số tiền người nhận
state	String	Mô tả trạng thái của yêu cầu thanh toán**
extraData	JSON	Data đối tác đã gửi lúc tạo yêu cầu chuyển tiền
createdAt	Date	Thời điểm tạo yêu cầu thanh toán
updatedAt	Date	Thời điểm cập nhật yêu cầu thanh toán lần cuối

Các trạng thái của yêu cầu thanh toán :

Key	Value
SUCCEEDED	Thanh toán đã thành công
FAILED	Thanh toán thất bại link đã vô hiệu lực
PENDING	Thanh toán đang chờ khách hàng thanh toán
EXPIRED	Thanh toán đã hết hạn không còn hiệu lực
CANCELED	Thanh toán đã bị huỷ từ Merchant
REFUNDED	Thanh toán đã được hoàn lại cho user trong 1 số trường hợp đặc biêt

Là flow Merchant có thể dùng số dư Ví Payme đề tạo lệnh chuyển tiền về tài khoản ngân hàng cho user hoặc chính mình Sau khi tạo lệnh thành công, Merchant sẽ bị trừ số dư ví, và số tiền sẽ được chuyển khoản thằng về tài khoản ngân hàng chỉ định

• Bước 1: Merchant gọi API của PPG tạo yêu cầu chuyển tiền
• Bước 2: PPG kiểm tra yêu cầu, số dư của Merchant và trừ tiền của Merchant nếu hợp lệ.
• Bước 3: PPG chuyển khoản số tiền đã trừ về cho số tài khoản ngân hàng chỉ định
Đồng thời báo kết quả về callback URL của Merchant (được cung cấp khi tạo kết nối)

/v1/Service/TransferMoney/ATM

Payload :

Key	Type	Required	Mô Tả	Ghi chú
amount	Number	YES	Số tiền yêu cầu khách hàng thanh toán	Tối thiểu 2.000 vnd và tối đa 10.000.000 VND
bank_number	String	YES	Số tài khoản Ngân hàng nhận tiền
bank_holder	String	YES	Tên tài khoản Ngân hàng nhận tiền	Tên TK và số TK cần phải trùng khớp
desc	String	YES	Hiển thị mô tả thanh toán	Có thể sử dụng tiếng Việt có dấu theo chuẩn Unicode, tối đa 256 ký tự
partnerTransaction	String	YES	Mã giao dịch của đôi tác	Là unique đối với mỗi Merchant
extraData	Json Object	NO	Data bổ sung của thanh toán, sẽ được trả về khi chuyền tiền thành công

Yêu cầu mẫu trước khi encrypt :
{ "amount": 100.000, "bank_number": "970421324561646", "bank_holder" : "NGUYEN VAN A" , "partnerTransaction ": "124556274354", "desc": "Chuyển tiền cho KH 0012545", "extraData": { "partnerTransaction": 124556274354, "fullname" : "Nguyễn Văn A", "billId": 0012545 } }

Key	Type	Mô Tả
code	Number	Mã báo thành công hoặc lỗi dịch vụ, xem ở phần ghi chú mã lỗi
data	Json Object	Dữ liệu trả về gồm 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
partnerTransaction	String	Mã giao dịch của đối tác
amount	Number	Số tiền đã chuyển
fee	Number	Phí khi sử dụng các cổng thanh toán đặc biệt (nếu có)
total	Number	Số tiền người nhận thực nhận
state	String	Mô tả trạng thái của yêu cầu thanh toán**
extraData	JSON	Data đối tác đã gửi lúc tạo yêu cầu thanh toán
createdAt	Date	Thời điểm tạo yêu cầu thanh toán
updatedAt	Date	Thời điểm cập nhật yêu cầu thanh toán lần cuối

Phản hồi mẫu trước khi encrypt :

{ "code": 1000, "data": { "amount": 100000, "fee": 0, "total": 100000, "state": "SUCCEEDED", "transaction": "5480589239", "partnerTransaction": "124556274354", "extraData": { "partnerTransaction": 124556274354, "fullname" : "Nguyễn Văn A", "billId": 0012545 } "createdAt": "2020-06-09T11:29:49.995Z", "updatedAt": "2020-06-09T11:29:49.995Z" } }

Là flow Merchant có thể dùng số dư Ví Payme đề tạo lệnh chuyển tiền về tài khoản Payme khác của khách
Sau khi tạo lệnh thành công, Merchant sẽ bị trừ số dư ví, và số tiền sẽ được chuyển khoản thằng về tài khoản PayME chỉ định

• Bước 1: Merchant gọi API của PPG tạo yêu cầu chuyển tiền
• Bước 2: PPG kiểm tra yêu cầu, số dư của Merchant và trừ tiền của Merchant nếu hợp lệ.
• Bước 3: PPG chuyển khoản số tiền đã trừ về cho số tài khoản PayME chỉ định
Đồng thời báo kết quả về callback URL của Merchant (được cung cấp khi tạo kết nối)

/v1/Service/TransferMoney/PayME

Payload :

Key	Type	Required	Mô Tả	Ghi chú
amount	Number	YES	Số tiền cần chuyển cho khách hàng	Tối thiểu 10.000 vnd và tối đa 10.000.000 VND
phone	String	YES	Số điện thoại Ví Payme nhận tiền
desc	String	YES	Hiển thị mô tả thanh toán	Có thể sử dụng tiếng Việt có dấu theo chuẩn Unicode, tối đa 256 ký tự
partnerTransaction	String	YES	Mã giao dịch của đôi tác	Là unique đối với mỗi Merchant
extraData	Json Object	NO	Data bổ sung của thanh toán, sẽ được trả về khi chuyền tiền thành công

Yêu cầu mẫu trước khi encrypt :
{ "amount": 100.000, "phone" : "0909000100" , "partnerTransaction ": "124556274354", "desc": "Chuyển tiền cho KH 0012545", "extraData": { "partnerTransaction": 124556274354, "fullname" : "Nguyễn Văn A", "billId": 0012545 } }

Key	Type	Mô Tả
code	Number	Mã báo thành công hoặc lỗi dịch vụ, xem ở phần ghi chú mã lỗi
data	Json Object	Dữ liệu trả về gồm 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
partnerTransaction	String	Mã giao dịch của đối tác
amount	Number	Số tiền đã chuyển
fee	Number	Phí khi sử dụng các cổng thanh toán đặc biệt (nếu có)
total	Number	Số tiền người nhận thực nhận
state	String	Mô tả trạng thái của yêu cầu thanh toán**
extraData	JSON	Data đối tác đã gửi lúc tạo yêu cầu thanh toán
createdAt	Date	Thời điểm tạo yêu cầu thanh toán
updatedAt	Date	Thời điểm cập nhật yêu cầu thanh toán lần cuối

Phản hồi mẫu trước khi encrypt :

{ "code": 1000, "data": { "amount": 100000, "fee": 0, "total": 100000, "state": "SUCCEEDED", "transaction": "5480589239", "partnerTransaction": "124556274354", "extraData": { "partnerTransaction": 124556274354, "fullname" : "Nguyễn Văn A", "billId": 0012545 } "createdAt": "2020-06-09T11:29:49.995Z", "updatedAt": "2020-06-09T11:29:49.995Z" } }

====================================================

Các mã lỗi phổ thông sẽ trả về ở các api của PGG

ERROR CODE	Code	Mô tả
SYSTEM_ERROR	500	Lỗi dịch vụ, liên hệ bộ phận liên quan để xử lý
SERVER_MAINTENANCE	501	Server đang bảo trì
INVALID_PARAMS	400	Dữ liệu yêu cầu không hợp lệ
INVALID_TOKEN	401	AccessToken chứng thực yêu cầu không hợp lệ
REQUEST_SUCCESS	1000	Yêu cầu thành công
REQUEST_FAIL	1001	Yêu cầu thất bại, kèm theo message trong data để thông báo lý do lỗi thất bại
REQUEST_REFUSED	1002	Yêu cầu bị từ chối vì 1 số lý do bảo mật