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

1. Tổng quan

1.1. Mã hóa Checksum

1.1.1. Request structure

  • Request URL: https://{domain}/{path}

    • Domain:
    Environment Domain
    Sandbox https://sbx-gapi.payme.vn
    Production https://gapi.payme.vn
    • Path: Path tương ứng với từng API

  • Method: POST

  • Header:

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

  • Body: payload là các JSON với các key được định nghĩa cụ thể theo từng API

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.
Authorization String NO Dùng AccessToken để chứng thực tính hợp lệ của các yêu cầu gửi lên PPG.
x-api-validate String YES Đoạn mã checksum Md5.
  • Đoạn checksum Md5 x-api-validate là kết quả hàm băm từ một chuỗi liên tục các giá trị theo thứ tự sau:
Key Value
x-api-action như trên
method POST/PUT/DELETE/GET
Authorization như trên
x-api-message như trên
SecretKey như trên
  • Body:

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

Key Type Require Value
x-api-message String YES Đoạn mã được Encrypt từ chuỗi ghép (payload + SecretKey) bằng thuật toán AES*
  • payload-Object: RequestParam của API
  • SecretKey-String: Key mà Merchant tự sinh ra khi request, key này dùng để mã hoá payload và được mã hoá bởi PayME Public Key.

1.2.2. Response structure:

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

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

  • Response header:
Key Type Require Value
x-api-key String YES Là 1 chuỗi mã hoá dùng publicKey của Merchant cung cấp để encrypt base64 đoạn SecretKey ở Body, merchant sẽ dùng PrivateKey để decrypt
x-api-client String YES Là 1 chuỗi định danh được cung cấp cho merchant khi tiến hành kết nối
x-api-action String YES Là api action đã request
x-api-validate String YES Là đoạn mã checksum Md5
  • Đoạn checksum Md5 x-api-validate là kết quả hàm băm từ một chuỗi liên tục các giá trị theo thứ tự sau:
Key Value
x-api-action như trên
method POST/PUT/DELETE/GET
Authorization như trên
x-api-message như trên
SecretKey như trên
  • Body:
Key Value Type
x-api-message String Payload dữ liệu trả về đã được mã hóa. Dùng SecretKey lấy được từ x-api-key trong phần header để Decrypt payload

1.3. Mã lỗi:

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

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

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

II. CLIENT TO SERVER - API Frontend:

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

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

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

  • Mô tả: API do PayME cung cấp dùng để cung cấp thông tin và hiển thị tài khoản

  • Flow Chart

  • API Path: /fe/ewallet/account

  • Method : GET

Request Parameters:

  • Authentication
Header Type Mô Tả
Authorization String accessToken của user được cấp sau khi login/linked thành công
  • Payload: NONE
  • Response:
Key Type Mô Tả
code Number Mã Lỗi:
  • 300010

    Lấy thông tin thành công

  • 300011

    Có lỗi xảy ra

message String Mô tả thông tin mã lỗi
data Object Dữ liệu trả về gồm có các field bên dưới:

Dữ liệu trả về

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

KYC Object details

Key Type Mô tả
identifyNumber Number Mã định danh (số cmnd, cccd...)
identifyType Enum Hình thức định danh tài khoản (CMND, CCCD)
state Enum Trạng Thái KYC (xem chi tiết bên dưới)
reason String Lý do từ chối KYC (nếu có)
issuedAt String Ngày cấp
placeOfIssue String Nơi cấp
  • Các trạng thái KYC
KYC state Mô Tả
APPROVED đã xác nhận KYC
REJECTED đã từ chối KYC
PENDING đang chờ duyệt KYC
Ví dụ:
  • Payload mẫu trước khi encrypt: NONE
  • Response mẫu trước khi encrypt:
{
    code: 300010,
    message: "Lấy thông tin thành công",
    data: {
            accountId: 9,
            phone: "0998999999",
            email: "nvip99@gmail.com",
            kyc: {
                    identifyNumber: 10012123123,
                    identifyType: "CMND",
                    issuedAt: "01/08/1998",
                    state: "APPROVED",
                    reason: null,
                    placeOfIssue: "Công An TPHCM",
        },
            avatar: "http://static.payme.vn/luatnv/hinhanh.png",
            gender: "MALE",
            birthday: "01/08/1998",
            address: "53 Hai Bà Trưng, Phường 8, Thành Phó Đà Lạt, Tỉnh Lâm Đồng",
            isActive: true,
            state: "OPENED",
            linked: true,
    },
}

1.2 API Cập nhật thông tin tài khoản

  • Mô tả: API do PayME cung cấp dùng để cập nhật thông tin tài khoản

  • Flow Chart

  • API Path: /fe/ewallet/account

  • Method : PUT

Request Parameters:

  • Authentication
Header Type Mô Tả
Authorization String accessToken của user được cấp sau khi login/linked thành công
  • Payload:
Tham Số Bắt buộc Kiểu dữ liệu Ý nghĩa
email String Thông Tin Email
avatar String avatar người dùng
address String Địa chỉ liên lạc
  • Response:
Tham Số Kiểu dữ liệu Ý nghĩa
code Number Mã Lỗi:
  • 300012

    Cập nhật thông tin thành công

  • 300013

    Cập nhật thông tin thất bại

  • 300014

    Email không đúng định dạng

message String Mô tả thông tin mã lỗi
Ví dụ:
  • Payload mẫu trước khi encrypt:
    {
        "email": "nluat999@gmail.com",
        "avatar": "hinhanh.png",
        "address": "615/218 Xo viet nghe Tinh, TPHCM"
    }
  • Response mẫu trước khi encrypt:
{
    code: 300012,
    message: "Cập nhật thông tin thành công "
}

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

  • Mô tả: API do PayME cung cấp dùng để lấy thông tin số dư tài khoản

  • Flow Chart

  • API Path: /fe/ewallet/balance

  • Method : GET

Request Parameters:

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

  • Payload: NONE

  • Response:

Tham Số Kiểu dữ liệu Ý nghĩa
code Number Mã Lỗi:
  • 300020

    Lấy Thông tin ví thành công

message String Mô tả thông tin mã lỗi
data Object Dữ liệu trả về gồm có các field bên dưới:

Dữ liệu trả về

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

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

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

{
    code: 300020,
    message: "Lấy Thông tin ví thành công",
    data: { balance: 250000, cash: 210000, lockCash: 40000
    },
}

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


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


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



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

  • Ở flow này có 3 trường hợp xảy ra : 1\ KH chưa liên kết từ app đối tác, có số điện thoại liên kết đã có trước đó => tiến hành liên kết và merge thông tin lại với nhau cho KH sử dụng, thông qua OTP và api 2.2 2\ KH chưa từng sủ dụng Ví => tiến hành liên kết đồng thời tạo Ví PayME cho Khách hàng, , thông qua OTP và api 2.2 3\ KH đã liên kết thành công trước đó, client sẽ gọi api này và được cấp accessToken để sử dụng ngay

  • API Path: /fe/ewallet/account/link

  • Method : POST

Request Parameters:

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

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

  • Thông tin có trong object data của connectToken:
Key Type Required Description
userId String(32) ✔ AccountId khách hàng bên đối tác
phone String(10) ✔ Số điện thoại của khách hàng
kycInfo Object Thông tin KYC mà đối tác gửi cho PayME (1).(Chi tiết ở bên dưới)
  • Thông tin có trong object của kycInfo
Key Required Type Môtả
fullname ✔ String Tên của khách hàng
gender ✔ Enum Giới tính (MALE, FEMALE)
birthday ✔ String Ngày sinh (Dạng DD/MM/YYYY)
address ✔ String Thông tin về địa chỉ của khách hàng
identifyType ✔ Enum Loại thẻ chứng thực (CMND, CCCD)
identifyNumber ✔ String Số CMND, CCCD
issuedAt ✔ String Ngày phát hành thẻ (Dạng DD/MM/YYYY)
placeOfIssue ✔ String Nơi phát hành thẻ
video String URL video quay khuôn mặt của khách hàng
face String URL hình chụp khuôn mặt của khách hàng
image ✔ Object Object chứa URL hình chụp CMND/CCCD của khách hàng (2):
KeyTypeBắt BuộcMô tả
frontString✔ URL hình chụp CMND/CCCD (mặt trước)
backString✔ URL hình chụp CMND/CCCD (mặt sau)
  • Response:
Key Type Mô Tả
code Number Mã lỗi:
  • 311000: Liên kết thành công
  • 311001: Tài khoản bị khoá
  • 311002: Thông tin KYC bị lỗi
  • 311003: Số điện thoại chưa liên kết với PayME
  • 311004: Không tìm thấy thông tin kết nối
  • 311005: Thông tin giải mã connectToken không đúng
  • 311006: Format của connectToken không đúng
  • 311007: Định dạng SDT không đúng
  • 311008: Số điện thoại đã liên kết với userId khác
  • 311009: UserId đã liên kết với SDT khác
  • 311010: Không tìm thấy thông tin tài khoản người dùng
  • 311011: Lỗi gửi OTP liên tiêp
  • 311012: Lỗi hệ thống
message String Mô tả thông tin mã lỗi
data Object Dữ liệu trả về gồm có thể có các field bên dưới:
  • Thông tin trong data
Key Type Mô tả
accessToken String AccessToken khi đăng nhập/linked thành công (mã code 311000)
verifyToken String Verify Token dùng cho các trường hợp kết nối với ví PayME mới (mã code 311003)

Ví dụ:

  • Payload mẫu trước khi encrypt:
{
  "connectToken": "U2FsdGVkX193ahc9vY2b/FeSVyg6FP8uoVl5aIMdfEeXXibbJtVkrVB/1VlDsh2WJkDdx8chu4LbvClRDn9kOrcIAvCu9P7i6JjPEtfFGnMNSulQUDUq49AGbytaVP6nRNg9clWWdbGqUJfGxNs4gvVKGSDbltOFZsDc1yLMI",
  "deviceId": "iphone"
}
  • Thông tin connectToken mẫu trước khi encrypt:
{
    "userId": "0944074831",
    "phone": "0944074831",
    "kycInfo":
        {
            "fullname": "Nguyen Le Khang",
            "gender": "MALE",
            "birthday": "08/11/1998",
            "address": "Luong Son - Bac Binh - Binh Thuan",
            "identifyType": "CMND",
            "identifyNumber": "String",
            "issuedAt": "19/01/2019",
            "placeOfIssue": "Binh Thuan",
            "video": "https://sbx-static.payme.vn//2020/10/28/Co-29vnK6.mp4",
            "face": "https://cdn.pixabay.com/photo/2015/04/23/22/00/tree-736885__480.jpg",
            "image":
                {
                    "front": "https://cdn.pixabay.com/photo/2015/04/23/22/00/tree-736885__480.jpg",
                    "back": "https://cdn.pixabay.com/photo/2015/04/23/22/00/tree-736885__480.jpg",
                }
        },
}

Note :

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

Response mẫu trước khi encrypt:

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

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

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

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

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

  • API Path: /fe/ewallet/account/verifyLink

  • Method : POST

Request Parameters:

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

Request mẫu trước khi encrypt:

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

Response mẫu trước khi encrypt:

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

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


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



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

  • API Path: /fe/ewallet/banking/link

  • Method : POST

  • Header :

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

Request Parameters:

  • Payload :

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

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

    • PVCombank
    • OCB
    • BIDV
    • VIetinbank

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


    • Thông tin linkedInfo object

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

    • Thông tin card object

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

    • Thông tin account object

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

    • Thông tin credit object

      Tham số Kiểu dữ liệu Bắt buộc Mô tả
      cardNumber String true Số thẻ
      expiredAt String true Ngày hết hạn thẻ (MM/YY)
      cvv String true Mã bảo mật thẻ

    • env:

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

  • Response:

    | Tham số | Kiểu dữ liệu | Mô tả | |:-----------|:----------------:|--------------------| | code | Number |Mã lỗi:

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

    • Thông tin data object

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

Request mẫu trước khi encrypt:

Liên kêt bằng thẻ

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

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

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

Liên kết credit

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

Response mẫu trước khi encrypt:

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

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

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

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

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

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

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

  • Header:

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

Request Parameters:

  • Payload :

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

  • Response:

    | Tham số | Kiểu dữ liệu | Mô tả | |:-----------|:----------------:|--------------------| | code | Number |Mã lỗi:

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

Request mẫu trước khi encrypt:

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

Response mẫu trước khi encrypt:

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

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

  • Header:

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

Request Parameters:

  • Payload :

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

  • Response:

    | Tham số | Kiểu dữ liệu | Mô tả | |:-----------|:----------------:|--------------------| | code | Number |Mã lỗi:

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

Request mẫu trước khi encrypt:

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

Response mẫu trước khi encrypt:

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

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

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

  • API Path: /fe/ewallet/banking/linked

  • Method: GET

  • Header:

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

Request Parameters:

  • Payload : NONE

  • Response:

    | Tham số | Kiểu dữ liệu | Mô tả | |:-----------|:----------------:|--------------------| | code | Number |Mã lỗi:

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

    • Thông tin data object

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

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

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

Response mẫu trước khi encrypt:

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

4. Lịch sử ví PayME

4.1 Lịch sử giao dịch

  • Mô tả: API lấy danh sách lịch sử giao dịch của user

  • Path: /fe/ewallet/history

  • Method: GET

Request Parameters:

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

type

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

Response:

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

  • Data

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

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

Ví dụ

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

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

5. Thanh toán

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

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

  • Path: /fe/ewallet/payment/pay
  • Method: POST

Request Parameters:

  • Payload:
Key Type Required Description
amount Number ✔ Giá trị tiền đơn hàng cần thanh toán
phone String ✔ Số điện thoại Khách hàng cần thanh toán đơn hàng
partnerTransaction String ✔ Transaction của đối tác
description String Mô tả ngắn gọi của đơn hàng, tối đa 200 ký tự
payment Object ✔ Chứa thông loại hình thanh toán Khách hàng lựa chọn :
KeyTypeBắt BuộcMô tả
typeEnum✔ Loại hình thanh toán (WALLET, LINKED)
linkedIdNumberLinked Id của thẻ liên kết(Bắt buộc nếu loại hình thanh toán là LINKED)
  • Response:
Key Type Mô Tả
code Number Mã lỗi:
  • 315000: Thanh toán thành công
  • 315001: PartnerTransaction đã tồn tại
  • 315002: LinkedId không tồn tại (Thanh toán bằng LINKED)
  • 315003: Số dư ví PayME không đủ(Thanh toán bằng PAYME)
  • 315004: Tài khoản bị khoá. Không thể thanh toán
  • 315005: Thanh toán cần xác thực qua webview
  • 315006: Thanh toán cần xác thực qua OTP
  • 315007: Thanh toán thất bại (lý do ở message)
  • 315008: Các lỗi khác (lỗi hệ thống)
message String Mô tả thông tin mã lỗi
data Object Dữ liệu trả về gồm có thể có các field bên dưới:

Cấu trúc Data :

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

Example:

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

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

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

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

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

Response mẫu trước khi encrypt:

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

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

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

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


5.2 Xác nhận giao dịch

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

Request Parameters:

  • Payload:
Key Type Required Description
otp String ✔ OTP mà bên bank phát hành thẻ của Khách hàng đã gửi
transaction String ✔ Transaction của giao dịch cần OTP mà PayME đã trả ở API thanh toán
clientId String ✔ Mã client khách hàng thực hiện giao dịch
  • Response:
Key Type Mô Tả
code Number Mã lỗi:
  • 316000: Thanh toán thành công
  • 316001: Sai mã xác nhận
  • 316002: Nhập mã xác nhận sai nhiều lần liên tiếp
  • 316003: Lỗi hệ thống
message String Mô tả thông tin mã lỗi

Request mẫu trước khi encrypt:

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

Response mẫu trước khi encrypt:

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


III. SERVER TO SERVER - API Backend:

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

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

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

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

  • API Path: /be/ewallet/account/link

  • Method : POST

Request Parameters:

  • Payload:
Key Type Required Description
userId String(32) ✔ AccountId khách hàng bên đối tác
phone String(10) ✔ Số điện thoại của khách hàng
kycInfo Object Thông tin KYC mà đối tác gửi cho PayME (1).(Chi tiết ở bên dưới)
  • Thông tin có trong object của kycInfo
Key Required Type Môtả
fullname ✔ String Tên của khách hàng
gender ✔ Enum Giới tính (MALE, FEMALE)
birthday ✔ String Ngày sinh (Dạng DD/MM/YYYY)
address ✔ String Thông tin về địa chỉ của khách hàng
identifyType ✔ Enum Loại thẻ chứng thực (CMND, CCCD)
identifyNumber ✔ String Số CMND, CCCD
issuedAt ✔ String Ngày phát hành thẻ (Dạng DD/MM/YYYY)
placeOfIssue ✔ String Nơi phát hành thẻ
video String URL video quay khuôn mặt của khách hàng
face String URL hình chụp khuôn mặt của khách hàng
image ✔ Object Object chứa URL hình chụp CMND/CCCD của khách hàng (2):
KeyTypeBắt BuộcMô tả
frontString✔ URL hình chụp CMND/CCCD (mặt trước)
backString✔ URL hình chụp CMND/CCCD (mặt sau)
  • Response:
Key Type Mô Tả
code Number Mã lỗi:
  • 316000: Liên kết thành công
  • 316001: Lỗi khi liên kết (chi tiết bên dưới)
  • 316002: Liên kết cần xác thực OTP
message String Mô tả thông tin mã lỗi

Ví dụ:

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

Note :

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

Response mẫu trước khi encrypt:

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

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

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

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

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

  • API Path: /be/ewallet/account/verifyLink

  • Method : POST

Request Parameters:

  • Payload:
Key Type Required Description
activeCode String(10) ✔ OTP cho số điện thoại mà merchant đã gửi PayME ở API 6.1 (OTP do PayME gửi)
verifyToken String ✔ verifyToken mà PayME đã trả ở API 6.1
  • Response:
Key Type Mô Tả
code Number Mã lỗi:
  • 316100: Liên kết thành công
  • 316101: OTP không đúng
  • 316102: Lỗi khi liên kết (chi tiết ở message)
message String Mô tả thông tin mã lỗi

Ví dụ:

  • Payload mẫu trước khi encrypt:
{
    "verifyToken": "U2FsdGVkX193ahc9vY2b",
    "activeCode": "233232"
}

Response mẫu trước khi encrypt:

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

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

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

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

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

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

  • API Path: /be/ewallet/account/kyc/update

  • Method : POST

Request Parameters:

  • Payload:
Key Type Required Description
phone String(10) ✔ Số điện thoại của khách hàng
kycInfo Object ✔ Thông tin KYC mà đối tác gửi cho PayME (1).(Chi tiết ở bên dưới)
  • Thông tin có trong object của kycInfo
Key Required Type Môtả
fullname String Tên của khách hàng
gender Enum Giới tính (MALE, FEMALE)
birthday String Ngày sinh (Dạng DD/MM/YYYY)
address String Thông tin về địa chỉ của khách hàng
identifyType Enum Loại thẻ chứng thực (CMND, CCCD)
identifyNumber String Số CMND, CCCD
issuedAt String Ngày phát hành thẻ (Dạng DD/MM/YYYY)
placeOfIssue String Nơi phát hành thẻ
video String URL video quay khuôn mặt của khách hàng
face String URL hình chụp khuôn mặt của khách hàng
image Object Object chứa URL hình chụp CMND/CCCD của khách hàng (2):
KeyTypeBắt BuộcMô tả
frontStringURL hình chụp CMND/CCCD (mặt trước)
backStringURL hình chụp CMND/CCCD (mặt sau)
  • Response:
Key Type Mô Tả
code Number Mã lỗi:
  • 316200: Cập nhật thành công
  • 316201: Cập nhật thất bại (chi tiết bên dưới)
message String Mô tả thông tin mã lỗi

Ví dụ:

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

Response mẫu trước khi encrypt:

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

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

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

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

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

  • API Path: /be/ewallet/user/unlink

  • Method : POST

Request Parameters:

  • Payload:
Key Type Required Description
phone String(10) ✔ Số điện thoại của khách hàng
  • Response:
Key Type Mô Tả
code Number Mã lỗi:
  • 316220: Hủy liên kết thành công
  • 316221: Hủy liên kết thất bại
message String Mô tả thông tin mã lỗi

Ví dụ:

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

Response mẫu trước khi encrypt:

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

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

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

{
    "code": 316221,
    "message": " Hủy liên kết thất bại."
}


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

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

  • Mô tả: API do PayME cung cấp dùng để cung cấp thông tin và hiển thị tài khoản

  • Flow Chart

  • API Path: /be/ewallet/account

  • Method : GET

Request Parameters:


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

  • Response:
Key Type Mô Tả
code Number Mã Lỗi:
  • 300010

    Lấy thông tin thành công

  • 300011

    Có lỗi xảy ra

message String Mô tả thông tin mã lỗi
data Object Dữ liệu trả về gồm có các field bên dưới:

Dữ liệu trả về

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

KYC Object details

Key Type Mô tả
identifyNumber Number Mã định danh (số cmnd, cccd...)
identifyType Enum Hình thức định danh tài khoản (CMND, CCCD)
state Enum Trạng Thái KYC (xem chi tiết bên dưới)
reason String Lý do từ chối KYC (nếu có)
issuedAt String Ngày cấp
placeOfIssue String Nơi cấp
  • Các trạng thái KYC
KYC state Mô Tả
APPROVED đã xác nhận KYC
REJECTED đã từ chối KYC
PENDING đang chờ duyệt KYC
Ví dụ:

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

    {
    "phone": "0909000100"
}

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

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

7.2 API Cập nhật thông tin tài khoản

  • Mô tả: API do PayME cung cấp dùng để cập nhật thông tin tài khoản

  • Flow Chart

  • API Path: /be/ewallet/account

  • Method : PUT

Request Parameters:

  • Payload:
Tham Số Bắt buộc Kiểu dữ liệu Ý nghĩa
phone String ✔ Số điện thoại Khách hàng muốn thay đổi thông tin
email String Thông Tin Email
avatar String avatar người dùng
address String Địa chỉ liên lạc
  • Response:
Tham Số Kiểu dữ liệu Ý nghĩa
code Number Mã Lỗi:
  • 300012

    Cập nhật thông tin thành công

  • 300013

    Cập nhật thông tin thất bại

  • 300014

    Email không đúng định dạng

message String Mô tả thông tin mã lỗi
Ví dụ:
  • Payload mẫu trước khi encrypt:
    {
        "phone": "0909000100",
        "email": "nluat999@gmail.com",
        "avatar": "hinhanh.png",
        "address": "615/218 Xo viet nghe Tinh, TPHCM"
    }
  • Response mẫu trước khi encrypt:
{
    code: 300012,
    message: "Cập nhật thông tin thành công "
}

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

  • Mô tả: API do PayME cung cấp dùng để lấy thông tin số dư tài khoản

  • Flow Chart

  • API Path: /be/ewallet/balance

  • Method : GET

Request Parameters:

  • Payload:
Key Type Required Description
phone String ✔ Số điện thoại Khách hàng muốn lấy thông tin số dư Ví
  • Response:
Tham Số Kiểu dữ liệu Ý nghĩa
code Number Mã Lỗi:
  • 300020

    Lấy Thông tin ví thành công

message String Mô tả thông tin mã lỗi
data Object Dữ liệu trả về gồm có các field bên dưới:

Dữ liệu trả về

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

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

    {
    "phone": "0909000100"
}

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

{
    code: 300020,
    message: "Lấy Thông tin ví thành công",
    data: { balance: 250000, cash: 210000, lockCash: 40000
    },
}

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


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



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

  • API Path: /be/ewallet/banking/link

  • Method : POST

Request Parameters:

  • Payload :

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

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

    • PVCombank
    • OCB
    • BIDV
    • VIetinbank

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


    • Thông tin linkedInfo object

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

    • Thông tin card object

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

    • Thông tin account object

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

    • Thông tin credit object

      Tham số Kiểu dữ liệu Bắt buộc Mô tả
      cardNumber String true Số thẻ
      expiredAt String true Ngày hết hạn thẻ (MM/YY)
      cvv String true Mã bảo mật thẻ

    • env:

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

  • Response:

    | Tham số | Kiểu dữ liệu | Mô tả | |:-----------|:----------------:|--------------------| | code | Number |Mã lỗi:

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

    • Thông tin data object

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

Request mẫu trước khi encrypt:

Liên kêt bằng thẻ

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

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

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

Liên kết credit

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

Response mẫu trước khi encrypt:

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

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

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

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

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

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

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

Request Parameters:

  • Payload :

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

  • Response:

    | Tham số | Kiểu dữ liệu | Mô tả | |:-----------|:----------------:|--------------------| | code | Number |Mã lỗi:

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

Request mẫu trước khi encrypt:

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

Response mẫu trước khi encrypt:

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

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

Request Parameters:

  • Payload :

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

  • Response:

    | Tham số | Kiểu dữ liệu | Mô tả | |:-----------|:----------------:|--------------------| | code | Number |Mã lỗi:

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

Request mẫu trước khi encrypt:

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

Response mẫu trước khi encrypt:

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

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

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

  • API Path: /be/ewallet/banking/linked

  • Method: GET

Request Parameters:

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

  • Response:

    | Tham số | Kiểu dữ liệu | Mô tả | |:-----------|:----------------:|--------------------| | code | Number |Mã lỗi:

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

    • Thông tin data object

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

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

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

Response mẫu trước khi encrypt:

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

9. Thanh toán

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

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

  • Path: /be/ewallet/payment/pay
  • Method: POST

Request Parameters:

  • Payload:
Key Type Required Description
amount Number ✔ Giá trị tiền đơn hàng cần thanh toán
phone String ✔ Số điện thoại Khách hàng cần thanh toán đơn hàng
partnerTransaction String ✔ Transaction của đối tác
description String Mô tả ngắn gọi của đơn hàng, tối đa 200 ký tự
payment Object ✔ Chứa thông loại hình thanh toán Khách hàng lựa chọn :
KeyTypeBắt BuộcMô tả
typeEnum✔ Loại hình thanh toán (WALLET, LINKED)
linkedIdNumberLinked Id của thẻ liên kết(Bắt buộc nếu loại hình thanh toán là LINKED)
  • Response:
Key Type Mô Tả
code Number Mã lỗi:
  • 315000: Thanh toán thành công
  • 315001: PartnerTransaction đã tồn tại
  • 315002: LinkedId không tồn tại (Thanh toán bằng LINKED)
  • 315003: Số dư ví PayME không đủ(Thanh toán bằng PAYME)
  • 315004: Tài khoản bị khoá. Không thể thanh toán
  • 315005: Thanh toán cần xác thực qua webview
  • 315006: Thanh toán cần xác thực qua OTP
  • 315007: Thanh toán thất bại (lý do ở message)
  • 315008: Các lỗi khác (lỗi hệ thống)
message String Mô tả thông tin mã lỗi
data Object Dữ liệu trả về gồm có thể có các field bên dưới:

Cấu trúc Data :

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

Example:

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

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

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

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

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

Response mẫu trước khi encrypt:

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

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

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

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


9.2 Xác nhận giao dịch

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

Request Parameters:

  • Payload:
Key Type Required Description
otp String ✔ OTP mà bên bank phát hành thẻ của Khách hàng đã gửi
transaction String ✔ Transaction của giao dịch cần OTP mà PayME đã trả ở API thanh toán
clientId String ✔ Mã client khách hàng thực hiện giao dịch
  • Response:
Key Type Mô Tả
code Number Mã lỗi:
  • 316000: Thanh toán thành công
  • 316001: Sai mã xác nhận
  • 316002: Nhập mã xác nhận sai nhiều lần liên tiếp
  • 316003: Lỗi hệ thống
message String Mô tả thông tin mã lỗi

Request mẫu trước khi encrypt:

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

Response mẫu trước khi encrypt:

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


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

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

Request Parameters:

  • Payload:
Key Type Required Description
amount Number ✔ Số tiền cần thanh toán
description String ✔ Nội dung thanh toán, tối đa 200 ký tự
orderRequiredField Object Thu thập thông tin khách hàng khi thanh toán
expiredAt Enum Thời gian hết hạn link thanh toán Enum: [ TENMINUTES, ONEHOUR, HALFOFDAY, ONEDAY, SEVENDAYS, ONEMONTH] P/S: Mặc định không hết hạn.
attachedFiles Array Hình ảnh đính kèm của link thanh toán. Thông tin từng item là một Object
  • Response:
Key Type Mô Tả
code Number Mã lỗi:
  • 121000: Tạo link thanh toán thành công.
  • 121002: Tạo link thanh toán thất bại (lý do ở message)
message String Mô tả thông tin mã lỗi
data Object Dữ liệu trả về gồm có thể có các field bên dưới:

Cấu trúc Data :

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

Example:

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

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

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

Response mẫu trước khi encrypt:

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

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

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

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


10. Nạp tiền Ví

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

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

Request Parameters:

  • Payload:
Key Type Required Description
phone Number ✔ Số điện thoại của người dùng
amount String ✔ Số tiền cần nạp
linkedId Number ✔ LinkedId của thẻ đã liên kết (Lấy được từ API lấy danh sách thẻ liên kết (8.4))
ipnUrl String Thông báo kết quả giao dịch nạp cho đối tác
  • Response:
Key Type Mô Tả
code Number Mã lỗi:
  • 317000: Nạp tiền thành công.
  • 317001: Nạp tiền thất bại (lý do ở message)
  • 317002: Nạp tiền cần xác thực OTP
  • 317003: Nạp tiền cần xác thực từ ngân hàng
message String Mô tả thông tin mã lỗi
data Object Dữ liệu trả về gồm có thể có các field bên dưới:

Cấu trúc Data :

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

Example:

  • Payload mẫu trước khi encrypt:
{
    "phone": "0944074831",
    "amount": 20000,
    "linkedId": 466737373
}

Response mẫu trước khi encrypt:

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

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

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

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

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

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

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

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


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

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

Request Parameters:

  • Payload:
Key Type Required Description
phone String ✔ Số điện thoại của người dùng
transaction String ✔ Mã giao dịch của PayME ở API nạp tiền vào ví (10.1)
otp String ✔ OTP của ngân hàng đã trả về SDT của khách hàng
  • Response:
Key Type Mô Tả
code Number Mã lỗi:
  • 317100: Nạp tiền thành công.
  • 317101: Nạp tiền thất bại (lý do ở message)
  • 317102: OTP không chính xác
message String Mô tả thông tin mã lỗi
data Object Dữ liệu trả về gồm có thể có các field bên dưới:

Cấu trúc Data :

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

Example:

  • Payload mẫu trước khi encrypt:
{
    "phone": "0944074831",
    "otp": "453344",
    "transaction": "37373773"
}

Response mẫu trước khi encrypt:

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

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

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

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

Trường hợp sai OTP

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


11. Rút tiền

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

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

Request Parameters:

  • Payload:
Key Type Required Description
phone Number ✔ Số điện thoại của người dùng
amount String ✔ Số tiền cần rút
linkedId Number ✔ LinkedId của thẻ đã liên kết (Lấy được từ API lấy danh sách thẻ liên kết (8.4))
  • Response:
Key Type Mô Tả
code Number Mã lỗi:
  • 318000: Rút tiền thành công.
  • 318001: Rút tiền cần xác thực OTP
  • 318002: Rút tiền thất bại (lý do ở message)
message String Mô tả thông tin mã lỗi
data Object Dữ liệu trả về gồm có thể có các field bên dưới:

Cấu trúc Data :

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

Example:

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

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

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

Response mẫu trước khi encrypt:

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

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

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

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

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

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

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

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

Request Parameters:

  • Payload:
Key Type Required Description
phone String ✔ Số điện thoại của người dùng
transaction String ✔ Mã giao dịch của PayME ở API rút tiền vào ví (11.1)
otp String ✔ OTP của PayME đã trả về SDT của khách hàng
  • Response:
Key Type Mô Tả
code Number Mã lỗi:
  • 318100: Rút tiền thành công.
  • 318101: Sai OTP
  • 318102: Rút tiền thất bại(lý do ở message)
message String Mô tả thông tin mã lỗi
data Object Dữ liệu trả về gồm có thể có các field bên dưới:

Cấu trúc Data :

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

Example:

  • Payload mẫu trước khi encrypt:
{
    "phone": "0944074831",
    "otp": "453344",
    "transaction": "37373773"
}

Response mẫu trước khi encrypt:

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

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

Trường hợp sai OTP

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

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

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


12. Chuyển tiền

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

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

Request Parameters:

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

transport Object

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

wallet Object

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

bankCard Object

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

bankAccount Object

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

Cấu trúc Data :

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

Example:

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

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

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

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

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

Response mẫu trước khi encrypt:

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

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

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

12.2 Xác nhận giao dịch

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

Request Parameters:

  • Payload:
Key Type Required Description
phone String ✔ Số tiền thoại của khách hàng
otp String ✔ OTP mà bên bank phát hành thẻ của Khách hàng đã gửi
transaction String ✔ Transaction của giao dịch cần OTP mà PayME đã trả ở API thanh toán
  • Response:
Key Type Description
code Number Mã lỗi:
  • 319902: Tài khoản chưa được KYC
  • 319904: Không thể chuyển tiền cho chính mình
  • 319905: Số điện thoại này chưa liên kết với Ví PayME
  • 319906: Tài khoản không được cấp quyền chuyển
  • 319907: Phương thức chuyển tiền không được hỗ trợ
  • 319000: Chuyển tiền thành công
  • 319101: Mã xác thực không đúng
  • 319102: SDT đã sai mã xác nhận nhiều lần
  • 319103: Hệ thống đang bảo trì
  • 319105: Mã xác nhận đã hết hạn
  • 319106: Chuyển tiền thất bại
message String Mô tả thông tin mã lỗi
data Object Dữ liệu trả về gồm có thể có các field bên dưới

Cấu trúc Data :

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

Request mẫu trước khi encrypt:

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

Response mẫu trước khi encrypt:

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


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

Request

POST /be/payment/direct/ipn

Authenication

DEFAULT


Payload

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

Cấu trúc object payData:

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

Request mẫu trước khi encrypt:

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

Response

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

Cấu trúc object data:

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

Response mẫu trước khi encrypt:


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

Mã lỗi

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