Dịch vụ E-Voucher

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

Khách hàng lấy voucher phía VinID để sử dụng dịch vụ phía đối tác.

Verify voucher

POST {API-Host}/merchant-integration/v1/e-voucher/verify

API cho Merchant xác thực thông tin voucher mà khách hàng sử dụng

Headers

Name	Type	Description
X-Key-Code*	string	mã xác thực merchant được khởi tạo trên Merchant Site
X-Timestamp*	string	thời gian merchant tạo request đến hệ thống của VinID
X-Nonce*	number	sử dụng với mỗi request từ merchant, có giá trị sử dụng trong 2h từ thời điểm hệ thống VinID nhận được request
X-Signature*	string	chữ ký điện tử xác thực của request

Request Body

Name	Type	Description
store_code*	string	Mã cửa hàng của merchant được VinID cấp, nơi khách hàng sử dụng voucher
pos_code*	string	Mã máy pos cửa hàng của merchant được VinID cấp, nơi khách hàng sử dụng voucher
serial_number*	string	Mã sử dụng (ticket/code/serial) của voucher mà khách hàng sử dụng
order_info*	object	Thông tin đơn hàng phía đối tác
merchant_staff_id*	string	Mã định danh nhân viên merchant tại cửa hàng
extra_data	object	Thông tin bổ sung

200 Voucher serial hợp lệ

{
   "meta":{
      "code":200,
      "message":"success"
   },
   "data": {
      "available_to": "long",
      "available_from": "long",
      "min_order_value": "double",
      "discount_value": "double",
      "discount_type": "string (percent, amount)",
      "apply_in_holiday": "boolean",
      "merchant_voucher_code": "string"
   }
}

400 Không có merchant hoạt động

{
	"meta":{
		"code":4040901,
		"message":"Không tìm thấy dữ liệu thiết lập của merchant"
	}
}

401 Yêu cầu không hợp lệ

{
	"meta":{
		"code":4000001,
		"message":"Dữ liệu không hợp lệ"
	}
}

404 Voucher không hợp lệ

{
	"meta":{
		"code":4000902,
		"message":"Voucher serial không tồn tại, đã hết hạn hoặc đã được sử dụng"
	}
}

500 Internal Server Error

{
	"meta":{
		"code":5000001,
		"message":"Hệ thống xảy ra lỗi khi xử lý yêu cầu"
	}
}

{ 
  "store_code": "string",
  "pos_code": "string",
  "serial_number": "string",
  "order_info": {},
  "merchant_staff_id": "string",
  "extra_data": {}   
}

Mark used voucher

POST {API-Host}/merchant-integration/v1/e-voucher/mark-used

API cho Merchant đánh dấu voucher đã sử dụng

Headers

Name	Type	Description
X-Key-Code*	string	mã xác thực merchant được khởi tạo trên Merchant Site
X-Timestamp*	string	thời gian merchant tạo request đến hệ thống của VinID
X-Nonce*	number	sử dụng với mỗi request từ merchant, có giá trị sử dụng trong 2h từ thời điểm hệ thống VinID nhận được request
X-Signature*	string	chữ ký điện tử xác thực của request

Request Body

Name	Type	Description
store_code*	string	Mã cửa hàng của merchant được VinID cấp, nơi khách hàng sử dụng voucher
pos_code*	string	Mã máy pos cửa hàng của merchant được VinID cấp, nơi khách hàng sử dụng voucher
serial_number*	string	Mã sử dụng (ticket/code/serial) của voucher mà khách hàng sử dụng
redeem_ref_id*	string	Mã tham chiếu của giao dịch sử dụng sử dụng voucher của merchant
merchant_staff_id*	number	Mã định danh nhân viên merchant tại cửa hàng
extra_data	object	Thông tin bổ sung
merchant_code*	string	Mã merchant được VinID cấp
merchant_voucher_code*	string	Merchant voucher code
merchant_reference_id*	string	Merchant reference id

200 Voucher serial hợp lệ

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

400 Không có merchant hoạt động

{
	"meta":{
		"code":4040901,
		"message":"Không tìm thấy dữ liệu thiết lập của merchant"
	}
}

401 Yêu cầu không hợp lệ

{
	"meta":{
		"code":4000001,
		"message":"Dữ liệu không hợp lệ"
	}
}

404 Voucher không hợp lệ

{
	"meta":{
		"code":4000902,
		"message":"Voucher serial không tồn tại, đã hết hạn hoặc đã được sử dụng"
	}
}

500 Internal Server Error

{
	"meta":{
		"code":5000001,
		"message":"Hệ thống xảy ra lỗi khi xử lý yêu cầu"
	}
}

{ 
  "store_code": "string",
  "pos_code": "string",
  "merchant_code": "string",
  "merchant_voucher_code": "string",
  "merchant_reference_id": "string",
  "serial_number": "string",
  "redeem_ref_id": "string",
  "merchant_staff_id": int,
  "extra_data": {}   
}

Mã lỗi

Code	Message
4000001	Dữ liệu không hợp lệ
4040901	Không tìm thấy dữ liệu thiết lập của merchant
4000902	Voucher serial không tồn tại, đã hết hạn hoặc đã được sử dụng
5000001	Hệ thống xảy ra lỗi khi xử lý yêu cầu

Refund Voucher

POST {API-Host}/merchant-integration/v1/e-voucher/refund

API Thu hồi e-voucher

Headers

Name	Type	Description
X-Key-Code*	string	mã xác thực merchant được khởi tạo trên Merchant Site
X-Timestamp*	string	thời gian merchant tạo request đến hệ thống của VinID
X-Nonce*	number	sử dụng với mỗi request từ merchant, có giá trị sử dụng trong 2h từ thời điểm hệ thống VinID nhận được request
X-Signature*	string	chữ ký điện tử xác thực của request

Request Body

Name	Type	Description
serials*	[]string	Serial numbers of the voucher codes

200: OK Voucher được thu hồi thành công

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

500: Internal Server Error Hệ thống xảy ra lỗi khi xử lý yêu cầu

{
	"meta":{
		"code":5000001,
		"message":"Hệ thống xảy ra lỗi khi xử lý yêu cầu"
	}
}

401: Unauthorized Yêu cầu không hợp lệ

{
    "meta": {
        "code": 4010001,
        "message": "Lỗi trong quá trình chứng thực yêu cầu"
    }
}

400 Không có merchant hoạt động

{
	"meta":{
		"code":4040901,
		"message":"Không tìm thấy dữ liệu thiết lập của merchant"
	}
}

{ 
  "serials": []"string"
}

Mã lỗi

Code	Mesage
4000001	Dữ liệu không hợp lệ
4040901	Không tìm thấy dữ liệu thiết lập của merchant
5000001	Hệ thống xảy ra lỗi khi xử lý yêu cầu