PAYME PAYMENT GATEWAY

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

I. Giới thiệu

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…

Thuật ngữ

Merchant - Doanh nghiệp

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ố.

Store - Cửa hàng, điểm giao dịch

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 - Mã giao dịch PAYME

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 - Mã giao dịch đối tác

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

AccessToken - Thông Tin xác thực

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.

ExtraData - Thông tin bổ sung

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.

Quy trình tích hợp

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

Thông tin tích hợp

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

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

II. Bảo mật

- Thông tin cơ bản :

  • 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 :

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

- Hướng dẫn mã hóa

Mã hoá dữ liệu yêu cầu (Encrypt Request)

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

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

Header

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
Ví dụ
  • 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' }

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

Giải mã thông tin phản hồi (Decrypt response)

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

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
Body

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
Ví dụ
  • 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' }

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

III. API

Thanh toán Trực Tiếp

- Sơ đồ xử lý

• Mô tả

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

logo

- Mô tả luồng xử lý

• 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

Thanh toán scan QR bằng máy POS

• Mô tả

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

- Sơ đồ xử lý

logo

- Mô tả luồng xử lý

• 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

1) Tạo yêu cầu thanh toán

1.1) Tạo yêu cầu thanh toán qua WAP

• Mô tả

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

• API Path

/v1/Payment/Generate

• Method

POST

• Request Parameters

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
Ví dụ

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 } }

• Response
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
Ví dụ

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

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

• IPN

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

1.2) Thanh toán trực tiếp qua thẻ ATM

• Mô tả

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

• API Path

/v1/Payment/ATM

• Method

POST

• Request Parameters

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
Ví dụ

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 } } }

• Response
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
Ví dụ

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:" "<........>" } }

• IPN

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

1.3) Thanh toán qua chuyển khoản

• Mô tả

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

• API Path

/v1/Payment/Manual

• Method

POST

• Request Parameters

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
Ví dụ

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 } } }

• Response
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
Ví dụ

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" } }

• IPN

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

1.4) Thanh toán qua thẻ Quốc Tế

• Mô tả

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

• API Path

/v1/Payment/CreditCard

• Method

POST

• Request Parameters

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
Ví dụ

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 } } }

• Response
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
Ví dụ

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:" "<........>" } }

• IPN

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

1.5) Thanh toán trực tiếp qua Ví PayME

• Mô tả

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

• API Path

/v1/Payment/PayME/Direct

• Method

POST

• Request Parameters

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
Ví dụ

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": {} }

• Response
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
Ví dụ

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" } }

• IPN

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

2) Tra cứu yêu cầu thanh toán

• Mô tả

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

• API Path

/v1/Payment/Information/{transaction}

• Method

GET

• Request Parameters

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
Ví dụ

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

• Response
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
Ví dụ

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" } }

3) Huỷ Thanh toán

• Mô tả

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ỷ

• API Path

/v1/Payment/{transaction}

• Method

DELETE

• Request Parameters

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
Ví dụ

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

• Response
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
Ví dụ

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ỷ" }

Liên Kết Ví

1) Tạo liên kết ví

• Mô tả

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

• API Path

/v1/Link/PayME

• Method

POST

• Request Parameters

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í
Ví dụ

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

• Response
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
Ví dụ

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í" } }

2) Xác nhận liên kết ví

• Mô tả

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

• API Path

/v1/Link/PayME/Verify

• Method

POST

• Request Parameters

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
Ví dụ

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

• Response
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
Ví dụ

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

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

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

Tạo yêu cầu chuyển tiền

Tạo yêu cầu chuyển tiền qua liên kết thanh toán

• Mô tả

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ợ

- Mô tả luồng xử lý

• 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)

• API Path

/v1/Service/TransferMoney/Generate

• Method

POST

• Request Parameters

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
Ví dụ

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 }

• Response
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
Ví dụ

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

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

• IPN

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

Tạo yêu cầu chuyển tiền qua ATM

• Mô 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

- Mô tả luồng xử lý

• 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: PP 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)

• API Path

/v1/Service/TransferMoney/ATM

• Method

POST

• Request Parameters

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
Ví dụ

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 } }

• Response
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
Ví dụ

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" } }

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

IV. Phụ Lục

I. Ghi chú mã lỗi

• Mô tả :

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