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:
    EnvironmentDomain
    Sandboxhttps://sbx-gapi.payme.vn
    Productionhttps://gapi.payme.vn
    • Path: Path tương ứng với từng API
  • Method: POST

  • Header:

    KeyTypeRequiredValue
    x-api-clientStringYESID của key kết nối
    Content-TypeStringContent-Type: application/json; charset=UTF-8
    x-api-validateStringmd5 ( 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

    KeyTypeMô tả
    codeNumberMã lỗi
    messageStringMô tả thông tin mã lỗi
    dataObjectDữ liệu trả về

1.2 Mã hóa RSA

1.2.1. Request structure

KeyTypeRequireValue
x-api-clientStringYESMột chuỗi định danh được cung cấp cho Merchant khi tiến hành kết nối.
x-api-keyStringYESChuỗ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-actionStringYESDữ 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.
AuthorizationStringNODù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-validateStringYESĐ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:
KeyValue
x-api-actionnhư trên
methodPOST/PUT/DELETE/GET
Authorizationnhư trên
x-api-messagenhư trên
SecretKeynhư trên
  • Body:

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

KeyTypeRequireValue
x-api-messageStringYESĐ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:
KeyTypeRequireValue
x-api-keyStringYESLà 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-clientStringYESLà 1 chuỗi định danh được cung cấp cho merchant khi tiến hành kết nối
x-api-actionStringYESLà api action đã request
x-api-validateStringYESLà đ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:
KeyValue
x-api-actionnhư trên
methodPOST/PUT/DELETE/GET
Authorizationnhư trên
x-api-messagenhư trên
SecretKeynhư trên
  • Body:
KeyValueType
x-api-messageStringPayload 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 CodeShort DescriptionTypeMeaning
500SYSTEM_ERRORSystem errorLỗi dịch vụ, liên hệ bộ phận liên quan để xử lý
501SYSTEM_MAINTENANCESystem errorHệ thống đang bảo trì
502ILLEGAL_DATA_REQUESTMerchant errorDữ liệu yêu cầu không hợp lệ
503KEYID_INVALIDMerchant errorKeyID không hợp lệ
504LIMIT_REQUEST_REACHMerchant errorMerchant request liên tục quá số lần cho phép
505EXCEPTIONSystem errorCó lỗi không xác định
506DUPLICATE_PARNERTRANSIDMerchant errorMerchant gửi trùng partner transid
400INVALID_PARAMSMerchant errorDữ liệu yêu cầu không hợp lệ
401INVALID_TOKENMerchant errorAccessToken chứng thực yêu cầu không hợp lệ
1002REQUEST_REFUSEDMerchant errorYê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

payMethodpayCodeMethod NameDescription
PAYMEPAYMEVí PayMEThanh toán bằng ví PayME
ATMCARDATMThẻ ATMThanh toán bằng thẻ ATM
CREDITCARDCREDIT, CREDIT_INTERNATIONALThẻ quốc tếThanh toán bằng thẻ Visa/Master/JCB
BANKTRANSFERMANUAL_BANK, VIETQRChuyển khoản ngân hàngThanh toán bằng chuyển khoản
QRPAYVN_PAYQRCode ngân hàngThanh toán bằng QR của ngân hàng
ALIPAYALIPAY_DIRECT, ALIPAY_ECOMMERCEAlipayThanh toán bằng Alipay (Trung Quốc)
XNAPXNAPXNAPThanh toán bằng QR của XNAP (Singapore)
PAYNOWPAYNOWPayNowThanh toán bằng QR của PayNow (Singapore)
THAIQRTHAIQRThaiQRThanh 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
HeaderTypeMô Tả
AuthorizationStringaccessToken của user được cấp sau khi login/linked thành công
  • Payload: NONE
  • Response:
KeyTypeMô Tả
codeNumberMã Lỗi:
  • 300010 Lấy thông tin thành công
  • 300011 Có lỗi xảy ra
messageStringMô tả thông tin mã lỗi
dataObjectDữ liệu trả về gồm có các field bên dưới:

Dữ liệu trả về

KeyTypeMô tả
accountIdNumberID account
phoneStringSố điện thoại
emailStringThông Tin Email
kycObjectThông tin kyc (chi tiết bên dưới)
avatarStringavatar người dùng
genderEnumGiới tính người dùng (MALE, FEMALE, OTHER)
birthdayDateNgày sinh(DD/MM/YYYYY)
addressStringĐịa chỉ liên lạc
isActiveBooleanMặc định Active
stateEnumTrạng Thái Tài khoản (OPENED, LOCKED, TEMPORARY_LOCK)
linkedBooleanĐã liên kết Ví PayME ?

KYC Object details

KeyTypeMô tả
identifyNumberNumberMã định danh (số cmnd, cccd...)
identifyTypeEnumHình thức định danh tài khoản (CMND, CCCD)
stateEnumTrạng Thái KYC (xem chi tiết bên dưới)
reasonStringLý do từ chối KYC (nếu có)
issuedAtStringNgày cấp
placeOfIssueStringNơi cấp
  • Các trạng thái KYC
KYC stateMô 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
HeaderTypeMô Tả
AuthorizationStringaccessToken của user được cấp sau khi login/linked thành công
  • Payload:
Tham SốBắt buộcKiểu dữ liệuÝ nghĩa
emailStringThông Tin Email
avatarStringavatar người dùng
addressStringĐịa chỉ liên lạc
  • Response:
Tham SốKiểu dữ liệuÝ nghĩa
codeNumberMã 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
messageStringMô 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
HeaderTypeMô Tả
AuthorizationStringaccessToken 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
codeNumberMã Lỗi:
  • 300020 Lấy Thông tin ví thành công
messageStringMô tả thông tin mã lỗi
dataObjectDữ 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
balanceNumberThông tin số dư tổng
cashNumberSố dư khả dụng
lockCashNumberSố 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:
KeyTypeRequiredDescription
connectTokenStringlà 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
deviceIdStringDeviceId ở máy của khách hàng
langStringNgô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:
KeyTypeRequiredDescription
userIdString(32)AccountId khách hàng bên đối tác
phoneString(10)Số điện thoại của khách hàng
kycInfoObjectThô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
KeyRequiredTypeMôtả
fullnameStringTên của khách hàng
genderEnumGiới tính (MALE, FEMALE)
birthdayStringNgày sinh (Dạng DD/MM/YYYY)
addressStringThông tin về địa chỉ của khách hàng
identifyTypeEnumLoại thẻ chứng thực (CMND, CCCD)
identifyNumberStringSố CMND, CCCD
issuedAtStringNgày phát hành thẻ (Dạng DD/MM/YYYY)
placeOfIssueStringNơi phát hành thẻ
videoStringURL video quay khuôn mặt của khách hàng
faceStringURL hình chụp khuôn mặt của khách hàng
imageObjectObject 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:
KeyTypeMô Tả
codeNumberMã 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
messageStringMô tả thông tin mã lỗi
dataObjectDữ liệu trả về gồm có thể có các field bên dưới:
  • Thông tin trong data
KeyTypeMô tả
accessTokenStringAccessToken khi đăng nhập/linked thành công (mã code 311000)
verifyTokenStringVerify 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:
KeyTypeRequiredDescription
verifyTokenStringverifyToken nhận được từ API link
activeCodeStringActive Code mà PayME đã gửi
langStringNgôn ngữ hiển thị : vi/en
  • Response:
KeyTypeMô Tả
codeNumberMã 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
messageStringMô tả thông tin mã lỗi
dataObjectDữ 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 :

KeyTypeRequiredValue
AuthorizationStringYESaccessToken account được payME cấp sau khi đăng nhập thành công.

Request Parameters:

  • Payload :

    Tham sốKiểu dữ liệuBắt buộcMô tả
    swiftCodeStringfalseMã swiftCode ngân hàng liên kết. Required nếu là ngân hàng nội địa thuộc NAPAS
    amountNumberfalseSố 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*
    envStringfalseMôi trường để lấy Webview liên kết (thẻ Napas). Enum: [MobileApp WebApp]
    linkedInfoObjecttrueThông tin thẻ liên kết. (Chỉ chọn 1 trong 3 dạng liên kết)
    redirectUrlStringtrueLink redirect khi thanh toán thành công
    versionStringfalseVersion phiên bản app đang sử dụng
    clientIdStringtrueID 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ệuBắt buộcMô tả
      cardObjectfalseLiên kết số thẻ ngân hàng
      accountObjectfalseLiên két bằng số tài khoản ngân hàng
      creditObjectfalseLiên kết thẻ credit
    • Thông tin card object

      Tham sốKiểu dữ liệuBắt buộcMô tả
      cardNumberStringtrueSố thẻ
      cardHolderStringtrueTên chủ thẻ
      issuedAtStringtrueNgày phát hành thẻ (MM/YY)
      expiredAtStringfalseNgày hết hạng thẻ (MM/YY)
    • Thông tin account object

      Tham sốKiểu dữ liệuBắt buộcMô tả
      accountNumberStringtrueSố 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ệuBắt buộcMô tả
      cardNumberStringtrueSố thẻ
      expiredAtStringtrueNgày hết hạn thẻ (MM/YY)
      cvvStringtrueMã bảo mật thẻ
    • env:

      Tên ENVMô tả
      MobileAppKhách hàng đang sử dụng mobile app để thao tác
      WebAppKhách hàng đang sử dụng web để thao tác
  • Response:

    Tham sốKiểu dữ liệuMô tả
    codeNumberMã 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
    messageStringMô tả thông tin mã lỗi
    dataobjectData liên kêt (chi tiết bên dưới)
    • Thông tin data object

      Tham sốKiểu dữ liệuMô tả
      linkedIdNumberMã thẻ liên kết (nếu thành công ngay)
      transactionStringMã giao dịch khi liên kết
      htmlStringform 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:

    KeyTypeRequiredValue
    AuthorizationStringYESaccessToken account được payME cấp sau khi đăng nhập thành công.

Request Parameters:

  • Payload :

    Tham sốKiểu dữ liệuBắt buộcMô tả
    transactionStringtruemã giao dịch khi thanh toán xác thực thẻ
    otpStringtruemã otp của ngân hàng
    swiftCodeStringtrueMã 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ệuMô tả
    codeNumberMã 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
    messageStringMô 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:

    KeyTypeRequiredValue
    AuthorizationStringYESaccessToken account được payME cấp sau khi đăng nhập thành công.

Request Parameters:

  • Payload :

    Tham sốKiểu dữ liệuBắt buộcMô tả
    linkedIdNumbertrueId của thẻ liên kết trong danh sách liên kết
    clientIdStringtrueid của client đang trong phiên đăng nhập
  • Response:

    Tham sốKiểu dữ liệuMô tả
    codeNumberMã 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)
    messageStringMô 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:

    KeyTypeRequiredValue
    AuthorizationStringYESaccessToken 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ệuMô tả
    codeNumberMã 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)
    messageStringMô tả thông tin mã lỗi
    dataobjectData liên kêt (chi tiết bên dưới)
    • Thông tin data object

      Tham sốKiểu dữ liệuMô tả
      linkedListArrayChi tiết các thẻ đã liên kết để hiển thị, detail bên dưới
      totaLinkedNumberTổng số thẻ đã liên kết
    • Thông tin các phần tử có trong linkedList

      Tham sốKiểu dữ liệuMô tả
      linkedIdNumberID thẻ liên kết Ví PayME
      linkedAtDateTimeThời gian liên kết thẻ
      typeStringLoại thẻ liên két (ATM , CREDIT_CARD)
      issuerStringTên ngân hàng/tổ chức phát hành thẻ
      swiftCodeStringswiftCode ngân hàng liên kết
      cardNumberStringSố thẻ (đã che, chỉ hiển thị 4 số đầu và cuối)
      accountNumberStringSố tài khoản ngân hàng (đã che, chỉ hiển thị 4 số cuối)
      issuedAtStringNgày phát hành
      expiredAtStringNgà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 soKiểu dữ liệuBắt buộcÝ Nghĩa
accessTokenStringaccessToken account sau khi login
  • Payload:
Tham sốKiểu dữ liệuBắt buộcÝ NghĩaEnum
transactionStringMã dịch vụ
stateString(Enum)Trạng thái lịch sử, trạng thái dịch vụ[SUCCEEDED, PENDING]
changedString(Enum)Thu/Chi[IN, OUT]
typeString(Enum)Loại dịch vụ
startDateDateThời gian bắt đầu
endDateDateThời gian kết thúc
startNumberBắt đầu danh sách
limitNumbergiới hạn danh sách
  • enum:

type

ValueMô tả dịch vụ
BASICCơ bản
SOCIAL_PAYMENTSocial Payment
WALLET_PAYWALLET_PAY
WALLET_QRWALLET_QR
DEPOSITNạp
WITHDRAWRút
TRANSFER_MONEYChuyển tiền
OPEN_EWALLET_PAYMENTThanh toán EWallet
BILLHóa đơn
LINKEDLiên kết thẻ
MOBILE_CARDMua thẻ cào
MOBILE_TOPUPNạp tiền điện thoại
REFUND_MONEYHoàn tiền
ISECISEC
ADVANCE_MONEYỨng tiền
CREDIT_STATEMENTThanh toán tín dụng cho nhà cung cấp
CREDIT_SETTLEMENTTất toán tín dụng cho nhà cung cấp
GAME_CARDMua thẻ game
FAST_LOANVay nhanh
PAYMENT_CODEThanh toán QR Code
PAY_QRCODEThanh toán VNPay
CREDIT_BALANCEVí tín dụng

Response:

Tham sốKiểu dữ liệuÝ Nghĩa
codeNumberMã lỗi
messageStringMô tả thông tin mã lỗi
dataArrayMả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
transactionStringMã dịch vụ
amountStringSố tiền thanh toán
feeStringPhí
totalStringSố tiền cuối cùng
serviceNameStringTiêu đề lịch sử
createdAtStringThời gian giao dịch
stateStringTrạng thái
changedStringThu/Chi
descriptionStringMô tả lịch sử
detailUrlStringlink 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:
KeyTypeRequiredDescription
amountNumberGiá trị tiền đơn hàng cần thanh toán
phoneStringSố điện thoại Khách hàng cần thanh toán đơn hàng
partnerTransactionStringTransaction của đối tác
descriptionStringMô tả ngắn gọi của đơn hàng, tối đa 200 ký tự
paymentObjectChứa thông loại hình thanh toán Khách hàng lựa chọn :
KeyTypeBắt BuộcMô tả
typeEnumLoạ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:
KeyTypeMô Tả
codeNumberMã 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)
messageStringMô tả thông tin mã lỗi
dataObjectDữ liệu trả về gồm có thể có các field bên dưới:

Cấu trúc Data :

KeyTypeMô Tả
transactionStringmã 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ỷ
formStringform 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:
KeyTypeRequiredDescription
otpStringOTP mà bên bank phát hành thẻ của Khách hàng đã gửi
transactionStringTransaction của giao dịch cần OTP mà PayME đã trả ở API thanh toán
clientIdStringMã client khách hàng thực hiện giao dịch
  • Response:
KeyTypeMô Tả
codeNumberMã 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
messageStringMô 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:
KeyTypeRequiredDescription
userIdString(32)AccountId khách hàng bên đối tác
phoneString(10)Số điện thoại của khách hàng
kycInfoObjectThô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
KeyRequiredTypeMôtả
fullnameStringTên của khách hàng
genderEnumGiới tính (MALE, FEMALE)
birthdayStringNgày sinh (Dạng DD/MM/YYYY)
addressStringThông tin về địa chỉ của khách hàng
identifyTypeEnumLoại thẻ chứng thực (CMND, CCCD)
identifyNumberStringSố CMND, CCCD
issuedAtStringNgày phát hành thẻ (Dạng DD/MM/YYYY)
placeOfIssueStringNơi phát hành thẻ
videoStringURL video quay khuôn mặt của khách hàng
faceStringURL hình chụp khuôn mặt của khách hàng
imageObjectObject 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:
KeyTypeMô Tả
codeNumberMã 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
messageStringMô 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:
KeyTypeRequiredDescription
activeCodeString(10)OTP cho số điện thoại mà merchant đã gửi PayME ở API 6.1 (OTP do PayME gửi)
verifyTokenStringverifyToken mà PayME đã trả ở API 6.1
  • Response:
KeyTypeMô Tả
codeNumberMã 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)
messageStringMô 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:
KeyTypeRequiredDescription
phoneString(10)Số điện thoại của khách hàng
kycInfoObjectThô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
KeyRequiredTypeMôtả
fullnameStringTên của khách hàng
genderEnumGiới tính (MALE, FEMALE)
birthdayStringNgày sinh (Dạng DD/MM/YYYY)
addressStringThông tin về địa chỉ của khách hàng
identifyTypeEnumLoại thẻ chứng thực (CMND, CCCD)
identifyNumberStringSố CMND, CCCD
issuedAtStringNgày phát hành thẻ (Dạng DD/MM/YYYY)
placeOfIssueStringNơi phát hành thẻ
videoStringURL video quay khuôn mặt của khách hàng
faceStringURL hình chụp khuôn mặt của khách hàng
imageObjectObject 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:
KeyTypeMô Tả
codeNumberMã 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)
messageStringMô 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:
KeyTypeRequiredDescription
phoneString(10)Số điện thoại của khách hàng
  • Response:
KeyTypeMô Tả
codeNumberMã lỗi:
  • 316220: Hủy liên kết thành công
  • 316221: Hủy liên kết thất bại
messageStringMô 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:
KeyTypeRequiredDescription
phoneStringSố điện thoại Khách hàng muốn lấy thông tin

  • Response:
KeyTypeMô Tả
codeNumberMã Lỗi:
  • 300010 Lấy thông tin thành công
  • 300011 Có lỗi xảy ra
messageStringMô tả thông tin mã lỗi
dataObjectDữ liệu trả về gồm có các field bên dưới:

Dữ liệu trả về

KeyTypeMô tả
accountIdNumberID account
phoneStringSố điện thoại
emailStringThông Tin Email
kycObjectThông tin kyc (chi tiết bên dưới)
avatarStringavatar người dùng
genderEnumGiới tính người dùng (MALE, FEMALE, OTHER)
birthdayDateNgày sinh(DD/MM/YYYYY)
addressStringĐịa chỉ liên lạc
isActiveBooleanMặc định Active
stateEnumTrạng Thái Tài khoản (OPENED, LOCKED, TEMPORARY_LOCK)
linkedBooleanĐã liên kết Ví PayME ?

KYC Object details

KeyTypeMô tả
identifyNumberNumberMã định danh (số cmnd, cccd...)
identifyTypeEnumHình thức định danh tài khoản (CMND, CCCD)
stateEnumTrạng Thái KYC (xem chi tiết bên dưới)
reasonStringLý do từ chối KYC (nếu có)
issuedAtStringNgày cấp
placeOfIssueStringNơi cấp
  • Các trạng thái KYC
KYC stateMô 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ộcKiểu dữ liệuÝ nghĩa
phoneStringSố điện thoại Khách hàng muốn thay đổi thông tin
emailStringThông Tin Email
avatarStringavatar người dùng
addressStringĐịa chỉ liên lạc
  • Response:
Tham SốKiểu dữ liệuÝ nghĩa
codeNumberMã 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
messageStringMô 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:
KeyTypeRequiredDescription
phoneStringSố đ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
codeNumberMã Lỗi:
  • 300020 Lấy Thông tin ví thành công
messageStringMô tả thông tin mã lỗi
dataObjectDữ 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
balanceNumberThông tin số dư tổng
cashNumberSố dư khả dụng
lockCashNumberSố 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ệuBắt buộcMô tả
    phoneStringtrueSố điện thoại Khách hàng muốn liên kết
    swiftCodeStringfalseMã swiftCode ngân hàng liên kết. Required nếu là ngân hàng nội địa thuộc NAPAS
    amountNumberfalseSố 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*
    envStringfalseMôi trường để lấy Webview liên kết (thẻ Napas). Enum: [MobileApp WebApp]
    linkInfoObjecttrueThông tin thẻ liên kết. (Chỉ chọn 1 trong 3 dạng liên kết)
    redirectUrlStringtrueLink redirect khi thanh toán thành công
    versionStringfalseVersion phiên bản app đang sử dụng
    clientIdStringtrueID 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ệuBắt buộcMô tả
      cardObjectfalseLiên kết số thẻ ngân hàng
      accountObjectfalseLiên két bằng số tài khoản ngân hàng
      creditObjectfalseLiên kết thẻ credit
    • Thông tin card object

      Tham sốKiểu dữ liệuBắt buộcMô tả
      cardNumberStringtrueSố thẻ
      cardHolderStringtrueTên chủ thẻ
      issuedAtStringtrueNgày phát hành thẻ (MM/YY)
      expiredAtStringfalseNgày hết hạng thẻ (MM/YY)
    • Thông tin account object

      Tham sốKiểu dữ liệuBắt buộcMô tả
      accountNumberStringtrueSố 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ệuBắt buộcMô tả
      cardNumberStringtrueSố thẻ
      expiredAtStringtrueNgày hết hạn thẻ (MM/YY)
      cvvStringtrueMã bảo mật thẻ
    • env:

      Tên ENVMô tả
      MobileAppKhách hàng đang sử dụng mobile app để thao tác
      WebAppKhách hàng đang sử dụng web để thao tác
  • Response:

    Tham sốKiểu dữ liệuMô tả
    codeNumberMã 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
    messageStringMô tả thông tin mã lỗi
    dataobjectData liên kêt (chi tiết bên dưới)
    remainingLockedTimenumberThờ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ệuMô tả
      linkedIdNumberMã thẻ liên kết (nếu thành công ngay)
      transactionStringMã giao dịch khi liên kết
      htmlStringform 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ệuBắt buộcMô tả
    transactionStringtruemã giao dịch khi thanh toán xác thực thẻ
    otpStringtruemã otp của ngân hàng
  • Response:

    Tham sốKiểu dữ liệuMô tả
    codeNumberMã 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
    messageStringMô tả thông tin mã lỗi
    remainingLockedTimenumberThờ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ệuBắt buộcMô tả
    phoneStringtrueSố điện thoại Khách hàng muốn huỷ liên kết
    linkedIdNumbertrueId của thẻ liên kết trong danh sách liên kết
    clientIdStringtrueid của client đang trong phiên đăng nhập
  • Response:

    Tham sốKiểu dữ liệuMô tả
    codeNumberMã 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)
    messageStringMô 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 :
KeyTypeRequiredDescription
phoneStringSố đ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ệuMô tả
    codeNumberMã 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)
    messageStringMô tả thông tin mã lỗi
    dataobjectData liên kêt (chi tiết bên dưới)
    • Thông tin data object

      Tham sốKiểu dữ liệuMô tả
      linkedListArrayChi tiết các thẻ đã liên kết để hiển thị, detail bên dưới
      totaLinkedNumberTổng số thẻ đã liên kết
    • Thông tin các phần tử có trong linkedList

      Tham sốKiểu dữ liệuMô tả
      linkedIdNumberID thẻ liên kết Ví PayME
      linkedAtDateTimeThời gian liên kết thẻ
      typeStringLoại thẻ liên két (ATM , CREDIT_CARD)
      issuerStringTên ngân hàng/tổ chức phát hành thẻ
      swiftCodeStringswiftCode ngân hàng liên kết
      cardNumberStringSố thẻ (đã che, chỉ hiển thị 4 số đầu và cuối)
      accountNumberStringSố tài khoản ngân hàng (đã che, chỉ hiển thị 4 số cuối)
      issuedAtStringNgày phát hành
      expiredAtStringNgà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:
KeyTypeRequiredDescription
amountNumberGiá trị tiền đơn hàng cần thanh toán
phoneStringSố điện thoại Khách hàng cần thanh toán đơn hàng
partnerTransactionStringTransaction của đối tác
descriptionStringMô tả ngắn gọi của đơn hàng, tối đa 200 ký tự
paymentObjectChứa thông loại hình thanh toán Khách hàng lựa chọn :
KeyTypeBắt BuộcMô tả
typeEnumLoạ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:
KeyTypeMô Tả
codeNumberMã 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)
messageStringMô tả thông tin mã lỗi
dataObjectDữ liệu trả về gồm có thể có các field bên dưới:

Cấu trúc Data :

KeyTypeMô Tả
transactionStringmã 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ỷ
formStringform 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:
KeyTypeRequiredDescription
otpStringOTP mà bên bank phát hành thẻ của Khách hàng đã gửi
transactionStringTransaction của giao dịch cần OTP mà PayME đã trả ở API thanh toán
clientIdStringMã client khách hàng thực hiện giao dịch
  • Response:
KeyTypeMô Tả
codeNumberMã 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
messageStringMô 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"
}


  • 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:
KeyTypeRequiredDescription
amountNumberSố tiền cần thanh toán
descriptionStringNội dung thanh toán, tối đa 200 ký tự
orderRequiredFieldObjectThu thập thông tin khách hàng khi thanh toán
expiredAtEnumThờ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.
attachedFilesArrayHình ảnh đính kèm của link thanh toán. Thông tin từng item là một Object
  • Response:
KeyTypeMô Tả
codeNumberMã 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)
messageStringMô tả thông tin mã lỗi
dataObjectDữ liệu trả về gồm có thể có các field bên dưới:

Cấu trúc Data :

KeyTypeMô Tả
linkIdStringId của link thanh toán PayME Link
paymentLinkStringUrl PayME Link
descriptionStringNội dung thanh toán
amountNumberSố tiền thanh toán
currencyStringĐơn vị tiền tệ của link thanh toán
createdByObjectThông tin người tạo link thanh toán
createdAtDateTimeThời gian khởi tạo link thanh toán
attachedFilesArrayThô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:
KeyTypeRequiredDescription
phoneNumberSố điện thoại của người dùng
amountStringSố tiền cần nạp
linkedIdNumberLinkedId của thẻ đã liên kết (Lấy được từ API lấy danh sách thẻ liên kết (8.4))
ipnUrlStringThông báo kết quả giao dịch nạp cho đối tác
  • Response:
KeyTypeMô Tả
codeNumberMã 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
messageStringMô tả thông tin mã lỗi
dataObjectDữ liệu trả về gồm có thể có các field bên dưới:

Cấu trúc Data :

KeyTypeMô Tả
transactionStringMã 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:
KeyTypeRequiredDescription
phoneStringSố điện thoại của người dùng
transactionStringMã giao dịch của PayME ở API nạp tiền vào ví (10.1)
otpStringOTP của ngân hàng đã trả về SDT của khách hàng
  • Response:
KeyTypeMô Tả
codeNumberMã 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
messageStringMô tả thông tin mã lỗi
dataObjectDữ liệu trả về gồm có thể có các field bên dưới:

Cấu trúc Data :

KeyTypeMô Tả
transactionStringMã 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:
KeyTypeRequiredDescription
phoneNumberSố điện thoại của người dùng
amountStringSố tiền cần rút
linkedIdNumberLinkedId 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:
KeyTypeMô Tả
codeNumberMã 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)
messageStringMô tả thông tin mã lỗi
dataObjectDữ liệu trả về gồm có thể có các field bên dưới:

Cấu trúc Data :

KeyTypeMô Tả
transactionStringMã 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:
KeyTypeRequiredDescription
phoneStringSố điện thoại của người dùng
transactionStringMã giao dịch của PayME ở API rút tiền vào ví (11.1)
otpStringOTP của PayME đã trả về SDT của khách hàng
  • Response:
KeyTypeMô Tả
codeNumberMã 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)
messageStringMô tả thông tin mã lỗi
dataObjectDữ liệu trả về gồm có thể có các field bên dưới:

Cấu trúc Data :

KeyTypeMô Tả
transactionStringMã 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:
KeyTypeRequiredDescription
amountNumberGiá trị tiền đơn hàng cần thanh toán
phoneStringSố điện thoại Khách hàng cần thanh toán đơn hàng
descriptionStringMô tả ngắn gọi ủa đơn hàng, tối đa 200 ký tự
transportObjectChứ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

KeyTypeRequiredDescription
walletObjectChuyển tiền đến ví
bankCardObjectChuyển tiền đến thẻ ngân hàng
bankAccountObjectChuyển tiền đến tài khoản ngân hàng

wallet Object

KeyTypeRequiredDescription
phoneStringSố điện thoại người nhận

bankCard Object

KeyTypeRequiredDescription
cardNumberStringSố thẻ người nhận
cardHolderStringTên người nhận trên thẻ
swiftCodeStringMã ngân hàng

bankAccount Object

KeyTypeRequiredDescription
accountNumberStringSố tài khoản người nhận
accountHolderStringTên người nhận trên tài khoản
swiftCodeStringMã ngân hàng
KeyTypeDescription
codeNumberMã 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
messageStringMô tả thông tin mã lỗi
dataObjectDữ liệu trả về gồm có thể có các field bên dưới

Cấu trúc Data :

KeyTypeMô Tả
transactionStringTransaction đượ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:
KeyTypeRequiredDescription
phoneStringSố tiền thoại của khách hàng
otpStringOTP mà bên bank phát hành thẻ của Khách hàng đã gửi
transactionStringTransaction của giao dịch cần OTP mà PayME đã trả ở API thanh toán
  • Response:
KeyTypeDescription
codeNumberMã 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
messageStringMô tả thông tin mã lỗi
dataObjectDữ liệu trả về gồm có thể có các field bên dưới

Cấu trúc Data :

KeyTypeMô Tả
transactionStringTransaction đượ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

KeyRequiredTypeMô tả
amountYesNumberSố tiền thanh toán
partnerTransactionYesStringMã đối tác, nếu truyền trạng thái REFUNDED thì cần truyền đúng mã partnerTransaction cần REFUNDED
stateYesEnumTrạng thái đơn hàng : SUCCEEDED, FAILED,REFUNDED
descYesStringMô tả nội dung thanh toán của khách hàng
payMethodYesStringLoại hình thanh toán nếu Merchant chỉ định nếu có, nếu không sẽ cho user chọn
currencyNoStringĐơn vị tiền tệ. Mặc định là VND
extraDataNoStringThông tin bổ sung
usernameNoStringUsername của user
payDataNoObjectThông tin cần bổ xung với các phương thức thanh toán có yêu cầu thêm
langNoStringNgôn ngữ hiển thị. Mặc định là vi

Cấu trúc object payData:

KeyTypeMô tả
swiftcodeStringSwiftcode ngân hàng, Required khi payMethod: ATMCARD/FACEID
card_numberStringSố thẻ ngân hàng
card_holderStringTên chủ thẻ
issue_dateStringThờ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

KeyTypeMô tả
codeNumberMã lỗi
messageStringMô tả thông tin mã lỗi
dataObjectNế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:

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