Dịch vụ Topup VinID Point

Giới thiệu dịch vụ

Dịch vụ Topup VinID Point cho phép các đối tác tích hợp thực hiện nạp điểm VinID trực tiếp tới số điện thoại của người dùng. Chỉ cần số điện thoại đã đăng ký tài khoản VinID là người dùng sẽ nhận được điểm Vinpoint ngay vào tài khoản VinID mà không cần thực hiện bất cứ thao tác gì.

Lưu ý:

Điểm VinID đã được topup cho người dùng thì không thể thu hồi. Để tránh rủi ro cho đối tác, mặc định số điểm được Topup chỉ có thể sử dụng sau 24 giờ kể từ thời điểm nhận. Trường hợp Merchant mong muốn số điểm có thể sử dụng ngay, vui lòng liên hệ với Bộ phận kinh doanh hoặc tham khảo Dịch vụ VinID Giftcode

Luồng người dùng sử dụng dịch vụ

Đối tác có thể sử dụng Dịch vụ Topup VinID Point cho nhiều mục đích khác nhau tùy thuộc vào nghiệp vụ của mình như: mua bán điểm, trao đổi/tặng thưởng, … từ hệ thống của mình. Sơ đồ dưới đây minh họa cho nghiệp vụ Đổi điểm VinID của đối tác có hệ thống điểm loyalty riêng.

Sơ đồ xử lý kỹ thuật

APIs

Get user info by phone number

POST {API-HOST}/merchant-integration/v1/gateway

API cho merchant để kiểm tra thông tin của số điện thoại người dùng.

Headers

Name	Type	Description
X-API-Code*	string	mi_v1_loyalty_member_info
X-Merchant-ID*	string	Mã cửa hàng của merchant tại VinID
X-Terminal-ID*	string	Mã máy POS của merchant tại VinID

Request Body

Name	Type	Description
phone_no*	string	Số điện thoại của người dùng theo định dạng 0xxxxxxx. Tối thiểu 10 ký tự. Tối đa 11 ký tự
card_no	string

200

{
  "meta": {
    "code": int,
    "message": "string"
  },
  "data": {
    "full_name":        string,
    "phone_number":     string,
    "dob":              string,
    "gender":           string,
    "identify":         string,  // Số điện thoại cá nhân
    "status":           string,  // A: Active | I: Inactive | B: Block
    "card_status":      string   // A: Active | I: Inactive
  }
}

Top-up points to phone number

POST {API-HOST}/merchant-integration/v1/gateway

API để nạp điểm cho số điện thoại người dùng

Headers

Name	Type	Description
X-API-Code*	string	mi_v1_loyalty_transaction_topup
X-Merchant-ID*	String	Mã cửa hàng của merchant tại VinID
X-Terminal-ID*	String	Mã máy POS của merchant tại VinID

Request Body

Name	Type	Description
phone_no*	string	Số điện thoại nhận điểm theo định dạng 0xxxxxxx Tối thiểu 10 ký tự. Tối đa 11 ký tự.
point_amount*	integer	Số điểm cần nạp. Tối thiểu 50 .Tối đa 20000000 Nhỏ hơn 20000 nếu xuất hóa đơn
invoice_no*	string	Mã hóa đơn của merchant
send_receipt*	boolean	Yêu cầu xuất hóa đơn true: có. false : không
receipt_info	object	Thông tin để xuất hóa đơn Tất cả các trường thông tin bên dưới sẽ required nếu xuất hóa đơn
name	string	Tên ghi hóa đơn Tối đa 50 ký tự
address	string	Địa chỉ ghi hóa đơn Tối đa 100 ký tự
email	string	Email ghi hóa đơn (Yêu cầu truyền đúng định dạng) Tối đa 50 ký tự
tax_code	string	Mã số thuế ghi hóa đơn. Tối đa 32 ký tự
send_sms	boolean
id_type	string	Valid value: MOBILE, CARD, USER_ID
id	string

200

{
  "meta": {
    "code": 200,
    "message": "OK"
  }
}

REQUEST TEMPLATE

{
  "phone_no": "01118281123", 				// 	optional,numeric,min=10,max=11
  "point_amount": 2, 						//	required,numeric,min=0,should be < 20000 when send_reciept is true
  "invoice_no": "string", 				//	required,max length=23
  "send_receipt": true | false,			//	required
  "receipt_info": {						//	All receipt info fields is required if send_receipt is true
    "name": "string",            		//	max length=50
    "address":"string",					//	max length=100
    "email":"string",					//  Email format,max length=50
    "tax_code":"string"         		// 	max=32
  },
  "send_sms": true | false,				// optional, default value: true
  "id_type": "string",					// optional, valid value:  MOBILE, CARD, USER_ID
  "id": "string"                      // optional, 
}

Query order status

POST {API-HOST}/merchant-integration/v1/gateway

API để kiểm tra trạng thái đơn hàng

Headers

Name	Type	Description
X-Merchant-ID*	string	Mã cửa hàng của merchant tại VinID
X-Terminal-ID*	string	Mã máy POS của merchant tại VinID
X-API-Code*	string	mi_v1_loyalty_transaction_detail

Request Body

Name	Type	Description
invoice_no*	string	Mã hóa đơn của merchant

200

{
    "meta": {
        "code": 200,
        "message": "Success"
    },
     "data": {
        "type":                     string,     //  TXN_EARN
        "status":                   string,     //  "S": success |  "E" : error
    }
}

Mã lỗi

HTTP Status Code	Code	API	Message	Note
400	4000	All	Bad request
403	403100	All	MerchantId/TerminalId invalid
500	5000	All	(Varies)	Mã lỗi chung của hệ thống
200	200300	Get member info	Member card is not activated or blocked
200	4000306	Top-up points	Member card is not activated or blocked
200	200301	Get member info	Account is not activated or blocked	Tài khoản chưa được kích hoạt hoặc tạm thời bị khóa
200	4000326	Top-up points	Account is not activated or blocked	Tài khoản chưa được kích hoạt hoặc tạm thời bị khóa
200	200400	Get member info	Member does not exist	Tài khoản của thành viên không tồn tại
200	4000315	Top-up points	Member does not exist	Tài khoản của thành viên không tồn tại
200	4000307	Top-up points	Invoice no already exists
200	4000001	Top-up points	MerchantId/TerminalId/RequestId invalid
200	4030302	Top-up points	MerchantId/TerminalId not found/not active
200	500400	Top-up points	Insufficient point balance	Số điểm của thành viên không đủ để thanh toán
200	4000318	Top-up points	Member is potential risk
200	4000328	Top-up points	Exceeded max point amount for receipting	Giá trị giao dịch vượt giới hạn
200	600400	Top-up points	Campaign is unavailable or Allowed point has exceeded
200	600500	Top-up points	Transaction value exceeds limitation
200	600600	Top-up points	Transaction is invalid	Giao dịch không hợp lệ (điểm vượt hạn mức tối đa trên giao dịch, trạng thái khách hàng không hoạt động,…)

Tham khảo bảng Mã lỗi chung

Xem thêm:

• API Host

• Quy tắc kết nối