OneLife API
API docs by Redocly

OneLife API (1.0)

Download OpenAPI specification:Download

OneLife: support@onelife.vn URL: https://onelife.vn Terms of Service

Tài liệu hướng dẫn tích hợp với OneLife API. OneLife sử dụng 2 server để giúp đối tác tích hợp và kiểm thử

Quản lý thẻ OneLife

Quản lý thông tin danh sách thẻ OneLife của thành viên.

Danh sách thẻ OneLife

Lấy danh sách thẻ OneLife có thể nạp tại 1 cửa hàng để hiển thị

query Parameters
partnerCode
required
string

Mã định danh của đối tác

storeId
required
string

Mã định danh 1 cửa hàng của đối tác. Trong trường hợp tích hợp trên web hoặc app của đối tác, vui lòng sử dụng {mã_đối_tác}_app hoặc {mã_đối_tác}_web, trường hợp gọi từ hệ thống, vui lòng sử dụng {mã_đối_tác}_system, trong đó mã đối tác viết liền không có khoảng trắng và kí tự đặc biệt

deviceId
required
string

Mã định danh 1 máy POS trong cửa hàng của đối tác. Trong trường hợp tích hợp trên web hoặc app của đối tác, vui lòng sử dụng mã thiết bị của người dùng

signature
required
string

Chữ ký để kiểm tra thông tin. Sử dụng thuật toán HMAC_SHA256 và secretKey được cung cấp riêng cho từng đối tác để mã hóa data theo dạng: accessKey=$accessKey&param1=$param1&param2=$param2...&paramN=$paramN trong đó:

  • accessKey là chuỗi ký tự bí mật được cung cấp riêng cho từng đối tác để truy cập vào hệ thống
  • Các param là tên các field trong payload của API, được sắp xếp theo thứ tự alphabet tăng dần từ a-z

Responses

Response samples

Content type
application/json
{
  • "results": [
    ]
}

Chi tiết thẻ OneLife

Lấy thông tin chi tiết thẻ OneLife thông qua cardId

path Parameters
cardId
required
integer

Mã định danh của thẻ OneLife

query Parameters
partnerCode
required
string

Mã định danh của đối tác

storeId
required
string

Mã định danh 1 cửa hàng của đối tác. Trong trường hợp tích hợp trên web hoặc app của đối tác, vui lòng sử dụng {mã_đối_tác}_app hoặc {mã_đối_tác}_web, trường hợp gọi từ hệ thống, vui lòng sử dụng {mã_đối_tác}_system, trong đó mã đối tác viết liền không có khoảng trắng và kí tự đặc biệt

deviceId
required
string

Mã định danh 1 máy POS trong cửa hàng của đối tác. Trong trường hợp tích hợp trên web hoặc app của đối tác, vui lòng sử dụng mã thiết bị của người dùng

signature
required
string

Chữ ký để kiểm tra thông tin. Sử dụng thuật toán HMAC_SHA256 và secretKey được cung cấp riêng cho từng đối tác để mã hóa data theo dạng: accessKey=$accessKey&param1=$param1&param2=$param2...&paramN=$paramN trong đó:

  • accessKey là chuỗi ký tự bí mật được cung cấp riêng cho từng đối tác để truy cập vào hệ thống
  • Các param là tên các field trong payload của API, được sắp xếp theo thứ tự alphabet tăng dần từ a-z

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "amount": 0,
  • "extra_value": 0,
  • "extend_expiry": 0,
  • "extend_expiry_unit": "DAY",
  • "currency": "VND",
  • "term": "string",
  • "condition": "string",
  • "image_url": "http://example.com",
  • "name": "string",
  • "description": "string",
  • "status": "pending"
}

Quản lý xác thực

Quản lý xác thực người dùng.

Đăng nhập với flow server to server

Đăng nhập người dùng với OneLife thông qua server to server flow, tức giữa các authentication servers S2SAuthorize

Request Body schema: application/json
data
required
string

Thông tin người dùng đã mã hóa (RSA-OAEP)

accessKey
required
string

Khóa truy cập của client

clientCode
required
string

Mã định danh của client (mỗi đối tác có thể có nhiều client)

clientName
required
string

Tên của client

redirectUrl
string

URL để chuyển hướng tới sau khi đăng nhập thành công

deepLink
string

URL để chuyển hướng tới sau khi đăng nhập thành công dành cho ứng dụng mobile

extraData
string

Các thông tin bổ sung

signature
required
string

Chữ ký để kiểm tra thông tin. Sử dụng thuật toán HMAC_SHA256 để mã hóa data theo dạng: accessKey=$accessKey&data=$data&clientCode=$clientCode&clientName=$clientName&redirectUrl=$redirectUrl&deepLink=$deepLink&extraData=$extraData trong đó:

  • accessKey là chuỗi ký tự bí mật được cung cấp riêng cho từng đối tác (theo auth client) để truy cập vào hệ thống
  • data là thông tin người dùng đã được mã hóa (RSA-OAEP) với cấu trúc JSON như sau:
    {
  "userId": "string",
  "phone": "string",
  "email": "string",
  "firstName": "string",
  "lastName": "string"
}
  • clientCode là mã định danh độc nhất được quy định riêng cho từng client
  • clientName là tên của client
  • redirectUrl là URL mà đối tác muốn OneLife chuyển hướng tới sau khi đăng nhập thành công
  • deepLink là URL mà đối tác muốn chuyển hướng user tới 1 nơi cụ thể nào đó trong ứng dụng mobile
  • extraData là các thông tin bổ sung mà đối tác muốn cung cấp cho OneLife

Responses

Request samples

Content type
application/json
{
  • "data": "string",
  • "accessKey": "string",
  • "clientCode": "string",
  • "clientName": "string",
  • "redirectUrl": "string",
  • "deepLink": "string",
  • "extraData": "string",
  • "signature": "string"
}

Response samples

Content type
application/json
{
  • "accessToken": "string",
  • "tokenType": "bearer",
  • "expiresIn": 0,
  • "refreshToken": "string"
}

Đăng xuất người dùng khỏi hệ thống OneLife

Đăng xuất người dùng khỏi hệ thống OneLife. Khi gọi API cần đính kèm Authorization header

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "code": 0,
  • "message": "string"
}

Lấy mã truy cập mới với mã gia hạn truy cập

query Parameters
grant_type
required
string
Value: "refresh_token"

OAuth2 grant type

Request Body schema: application/json
refreshToken
required
string

Token dùng để gia hạn mã truy cập

Responses

Request samples

Content type
application/json
{
  • "refreshToken": "string"
}

Response samples

Content type
application/json
{
  • "accessToken": "string",
  • "tokenType": "bearer",
  • "expiresIn": 0,
  • "refreshToken": "string"
}

Quản lý người dùng

Quản lý thông tin người dùng.

Thông tin số dư thẻ OneLife của khách hàng

Lấy thông tin số dư thẻ OneLife của khách hàng

query Parameters
userId
string

Mã định danh của người dùng OneLife, được lấy từ JWT Token trả về khi user login

phone
string

Số điện thoại của user. Mặc định sẽ lấy thông tin theo số điện thoại (trong trường hợp truyền cả userId và phone), số điện thoại sẽ có định dạng +84xxxxxxxxx

partnerCode
required
string

Mã định danh của đối tác

storeId
required
string

Mã định danh 1 cửa hàng của đối tác. Trong trường hợp tích hợp trên web hoặc app của đối tác, vui lòng sử dụng {mã_đối_tác}_app hoặc {mã_đối_tác}_web, trường hợp gọi từ hệ thống, vui lòng sử dụng {mã_đối_tác}_system, trong đó mã đối tác viết liền không có khoảng trắng và kí tự đặc biệt

deviceId
required
string

Mã định danh 1 máy POS trong cửa hàng của đối tác. Trong trường hợp tích hợp trên web hoặc app của đối tác, vui lòng sử dụng mã thiết bị của người dùng

signature
required
string

Chữ ký để kiểm tra thông tin. Sử dụng thuật toán HMAC_SHA256 và secretKey được cung cấp riêng cho từng đối tác để mã hóa data theo dạng: accessKey=$accessKey&param1=$param1&param2=$param2...&paramN=$paramN trong đó:

  • accessKey là chuỗi ký tự bí mật được cung cấp riêng cho từng đối tác để truy cập vào hệ thống
  • Các param là tên các field trong payload của API, được sắp xếp theo thứ tự alphabet tăng dần từ a-z

Responses

Response samples

Content type
application/json
{
  • "walletId": 0,
  • "userId": 0,
  • "balance": 0,
  • "extraBalance": 0,
  • "expirationDate": "2019-08-24T14:15:22Z",
  • "partnerCode": "string",
  • "isNau": null
}

Cập nhật thông tin điểm thành viên thẻ OneLife của khách hàng

Cập nhật thông tin điểm thành viên thẻ OneLife của khách hàng

Request Body schema: application/json
partnerCode
required
string

Mã định danh của đối tác

partnerMembership
required
string

Hạng thành viên

partnerMemberPointUnit
required
string

Phân loại hạng thành viên

partnerMemberPointValue
required
int64

Điểm thành viên

phone
required
string

Số điện thoại đăng kí OneLife

signature
required
string

Chữ ký để kiểm tra thông tin. Sử dụng thuật toán HMAC_SHA256 để mã hóa data theo dạng: accessKey=$accessKey&partnerCode=$partnerCode&partnerMembership=$partnerMembership&partnerMemberPointUnit=$partnerMemberPointUnit&partnerMemberPointValue=$partnerMemberPointValue&phone=$phone trong đó:

  • accessKey là chuỗi ký tự bí mật được cung cấp riêng cho từng đối tác để truy cập vào hệ thống
  • Các params là tên các field trong payload của API, được sắp xếp theo thứ tự alphabet tăng dần từ a-z

Responses

Request samples

Content type
application/json
{
  • "partnerCode": "string",
  • "partnerMembership": "string",
  • "partnerMemberPointUnit": "string",
  • "partnerMemberPointValue": null,
  • "phone": "string",
  • "signature": "string"
}

Response samples

Content type
application/json
{
  • "walletId": 0,
  • "userId": 0,
  • "balance": 0,
  • "extraBalance": 0,
  • "expirationDate": "2019-08-24T14:15:22Z",
  • "partnerCode": "string",
  • "isNau": null
}

Quản lý giao dịch

Quản lý thông tin giao dịch

Thay đổi phương thức thanh toán giao dịch nạp thẻ

Thay đổi phương thức thanh toán giao dịch nạp thẻ
Yêu cầu xác thực sử dụng Basic Authentication (truyền username:password đã được encoded base64 trong header). Ví dụ: Basic cXVvY2RhdC5seUBraW5nZm9vZG1hcnQuY29tOjlrODkhVTl1RjBzcg==

Authorizations:
None
Request Body schema: application/json
partnerCode
required
string (partnerCode)

Mã định danh của đối tác

deviceId
required
string (deviceId)

Mã định danh 1 máy POS trong cửa hàng của đối tác. Trong trường hợp tích hợp trên web hoặc app của đối tác, vui lòng sử dụng mã thiết bị của người dùng

storeId
required
string (storeId)

Mã định danh 1 cửa hàng của đối tác. Trong trường hợp tích hợp trên web hoặc app của đối tác, vui lòng sử dụng {mã_đối_tác}_app hoặc {mã_đối_tác}_web, trường hợp gọi từ hệ thống, vui lòng sử dụng {mã_đối_tác}_system, trong đó mã đối tác viết liền không có khoảng trắng và kí tự đặc biệt

phone
required
string

Số điện thoại đăng kí OneLife của khách hàng, định dạng +84xxxxxxxxx (nếu đã có phone thì không truyền paymentCode. Nếu cả 2 cùng truyền thì mặc định lấy paymentCode), nếu cả 2 không truyền thì POS sẽ đi theo flow thanh toán dùng mã QR hoặc tích hợp phương thức thanh toán trong app đối tác

extraData
required
string (extraData)

Dữ liệu khác. Encode BASE64 data dưới định dạng JSON. Các key support hiện tại:

  • seller_code: thông tin mã nhân viên thực hiện giao dịch
  • pos_transaction_id: thông tin mã giao dịch máy POS (máy quét thẻ ngân hàng)
orderId
required
string <string> (orderId)

Mã định danh của yêu cầu thanh toán

newPaymentGatewayId
required
string

Mã cổng thanh toán mới

newPaymentMethod
required
string
Enum: "cash" "atm" "credit_debit_card" "brand_card" "wallet" "qr_code" "banking_card"

Phương thức thanh toán mới

signature
required
string (signature)

Chữ ký để kiểm tra thông tin. Sử dụng thuật toán HMAC_SHA256 và secretKey được cung cấp riêng cho từng đối tác để mã hóa data theo dạng: accessKey=$accessKey&param1=$param1&param2=$param2...&paramN=$paramN trong đó:

  • accessKey là chuỗi ký tự bí mật được cung cấp riêng cho từng đối tác để truy cập vào hệ thống
  • Các param là tên các field trong payload của API, được sắp xếp theo thứ tự alphabet tăng dần từ a-z

Responses

Request samples

Content type
application/json
{
  • "partnerCode": "string",
  • "deviceId": "string",
  • "storeId": "string",
  • "phone": "string",
  • "extraData": "string",
  • "orderId": "string",
  • "newPaymentGatewayId": "string",
  • "newPaymentMethod": "cash",
  • "signature": "string"
}

Response samples

Content type
application/json
{
  • "orderId": "string",
  • "phone": "string",
  • "paymentGatewayName": "string",
  • "paymentGatewayId": "string",
  • "paymentMethod": "string",
  • "brandCardId": "string",
  • "brandCardName": "string",
  • "totalAmount": null,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

Hủy bỏ giao dịch nạp thẻ

Hủy bỏ giao dịch nạp thẻ
Yêu cầu xác thực sử dụng Basic Authentication (truyền username:password đã được encoded base64 trong header). Ví dụ: Basic cXVvY2RhdC5seUBraW5nZm9vZG1hcnQuY29tOjlrODkhVTl1RjBzcg==

Authorizations:
None
Request Body schema: application/json
partnerCode
required
string (partnerCode)

Mã định danh của đối tác

deviceId
required
string (deviceId)

Mã định danh 1 máy POS trong cửa hàng của đối tác. Trong trường hợp tích hợp trên web hoặc app của đối tác, vui lòng sử dụng mã thiết bị của người dùng

storeId
required
string (storeId)

Mã định danh 1 cửa hàng của đối tác. Trong trường hợp tích hợp trên web hoặc app của đối tác, vui lòng sử dụng {mã_đối_tác}_app hoặc {mã_đối_tác}_web, trường hợp gọi từ hệ thống, vui lòng sử dụng {mã_đối_tác}_system, trong đó mã đối tác viết liền không có khoảng trắng và kí tự đặc biệt

phone
required
string

Số điện thoại đăng kí OneLife của khách hàng, định dạng +84xxxxxxxxx

extraData
string (extraData)

Dữ liệu khác. Encode BASE64 data dưới định dạng JSON. Các key support hiện tại:

  • seller_code: thông tin mã nhân viên thực hiện giao dịch
  • pos_transaction_id: thông tin mã giao dịch máy POS (máy quét thẻ ngân hàng)
orderId
required
string <string> (orderId)

Mã định danh của yêu cầu thanh toán

signature
required
string (signature)

Chữ ký để kiểm tra thông tin. Sử dụng thuật toán HMAC_SHA256 và secretKey được cung cấp riêng cho từng đối tác để mã hóa data theo dạng: accessKey=$accessKey&param1=$param1&param2=$param2...&paramN=$paramN trong đó:

  • accessKey là chuỗi ký tự bí mật được cung cấp riêng cho từng đối tác để truy cập vào hệ thống
  • Các param là tên các field trong payload của API, được sắp xếp theo thứ tự alphabet tăng dần từ a-z

Responses

Request samples

Content type
application/json
{
  • "partnerCode": "string",
  • "deviceId": "string",
  • "storeId": "string",
  • "phone": "string",
  • "extraData": "string",
  • "orderId": "string",
  • "signature": "string"
}

Response samples

Content type
application/json
{
  • "orderId": "string",
  • "voidOrderId": "string",
  • "phone": "string",
  • "beforeBalance": null,
  • "beforeExtraBalance": null,
  • "afterBalance": null,
  • "afterExtraBalance": null,
  • "status": "success",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

Hủy bỏ giao dịch thanh toán

Hủy bỏ giao dịch thanh toán
Yêu cầu xác thực sử dụng Basic Authentication (truyền username:password đã được encoded base64 trong header). Ví dụ: Basic cXVvY2RhdC5seUBraW5nZm9vZG1hcnQuY29tOjlrODkhVTl1RjBzcg==

Authorizations:
None
Request Body schema: application/json
partnerCode
required
string (partnerCode)

Mã định danh của đối tác

partnerRefOrderId
required
string (partnerRefOrderId)

Mã định danh của đơn hàng của đối tác

deviceId
required
string (deviceId)

Mã định danh 1 máy POS trong cửa hàng của đối tác. Trong trường hợp tích hợp trên web hoặc app của đối tác, vui lòng sử dụng mã thiết bị của người dùng

storeId
required
string (storeId)

Mã định danh 1 cửa hàng của đối tác. Trong trường hợp tích hợp trên web hoặc app của đối tác, vui lòng sử dụng {mã_đối_tác}_app hoặc {mã_đối_tác}_web, trường hợp gọi từ hệ thống, vui lòng sử dụng {mã_đối_tác}_system, trong đó mã đối tác viết liền không có khoảng trắng và kí tự đặc biệt

phone
required
string

Số điện thoại đăng kí OneLife của khách hàng, định dạng +84xxxxxxxxx

extraData
string (extraData)

Dữ liệu khác. Encode BASE64 data dưới định dạng JSON. Các key support hiện tại:

  • seller_code: thông tin mã nhân viên thực hiện giao dịch
  • pos_transaction_id: thông tin mã giao dịch máy POS (máy quét thẻ ngân hàng)
signature
required
string (signature)

Chữ ký để kiểm tra thông tin. Sử dụng thuật toán HMAC_SHA256 và secretKey được cung cấp riêng cho từng đối tác để mã hóa data theo dạng: accessKey=$accessKey&param1=$param1&param2=$param2...&paramN=$paramN trong đó:

  • accessKey là chuỗi ký tự bí mật được cung cấp riêng cho từng đối tác để truy cập vào hệ thống
  • Các param là tên các field trong payload của API, được sắp xếp theo thứ tự alphabet tăng dần từ a-z

Responses

Request samples

Content type
application/json
{
  • "partnerCode": "string",
  • "partnerRefOrderId": "string",
  • "deviceId": "string",
  • "storeId": "string",
  • "phone": "string",
  • "extraData": "string",
  • "signature": "string"
}

Response samples

Content type
application/json
{
  • "orderId": "string",
  • "voidOrderId": "string",
  • "phone": "string",
  • "beforeBalance": null,
  • "beforeExtraBalance": null,
  • "afterBalance": null,
  • "afterExtraBalance": null,
  • "status": "success",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

Bổ sung giao dịch thanh toán

Bổ sung giao dịch thanh toán
Lưu ý: giao dịch sẽ chỉ có thể bổ sung khi tài khoản của khách hàng chưa phát sinh giao dịch mới kể từ thời điểm orderDate truyền vô. Nếu nhận thông báo từ chổi, vui lòng liên hệ team OneLife để được hỗ trợ

Request Body schema: application/json
partnerCode
required
string (partnerCode)

Mã định danh của đối tác

deviceId
required
string (deviceId)

Mã định danh 1 máy POS trong cửa hàng của đối tác. Trong trường hợp tích hợp trên web hoặc app của đối tác, vui lòng sử dụng mã thiết bị của người dùng

storeId
required
string (storeId)

Mã định danh 1 cửa hàng của đối tác. Trong trường hợp tích hợp trên web hoặc app của đối tác, vui lòng sử dụng {mã_đối_tác}_app hoặc {mã_đối_tác}_web, trường hợp gọi từ hệ thống, vui lòng sử dụng {mã_đối_tác}_system, trong đó mã đối tác viết liền không có khoảng trắng và kí tự đặc biệt

partnerRefOrderId
required
string (partnerRefOrderId)

Mã định danh của đơn hàng của đối tác

orderInfo
required
string

Thông tin chi tiết hóa đơn

paymentAmount
required
integer <int64>

Số tiền cần thanh toán

phone
required
string

Số điện thoại đăng kí OneLife của khách hàng, định dạng +84xxxxxxxxx

orderDate
required
string

Thời điểm phát sinh giao dịch. Định dạng ngày tháng là RFC 3339, giờ UTC. Ví dụ "2019-10-12T07:20:50.52Z" hoặc "2019-10-12T07:20:50Z"

ipnUrl
string <url>

webhook phía đối tác cung cấp để OneLife trả kết quả về server đối tác. Webhook cần xây dựng với các thuộc tính như sau:

Nội dung Yêu cầu
Method POST
URL Không chứa các kí tự đặc biệt ngoại trừ _ hoặc -
Headers Content-type: application/json
Payload JSON object phía server OneLife truyền vô
Response Status code 204

Payload từ phía server OneLife truyền sang khi thông báo trạng thái giao dịch sẽ có cấu trúc như summary:

{
  "balanceCharged": float,
  "deviceId": "string",
  "extraBalanceOLCharged": float,
  "extraBalancePartnerCharged": float,
  "orderId": "string",
  "partnerCode": "string",
  "partnerRefOrderId": "string",
  "paymentAmount": float,
  "paymentCode": "string",
  "phone": "string",
  "signature": "string"
  "status": "string",
  "storeId": "string",
  "transactionId": string,
}
extraData
required
string (extraData)

Dữ liệu khác. Encode BASE64 data dưới định dạng JSON. Các key support hiện tại:

  • seller_code: thông tin mã nhân viên thực hiện giao dịch
  • pos_transaction_id: thông tin mã giao dịch máy POS (máy quét thẻ ngân hàng)
signature
required
string (signature)

Chữ ký để kiểm tra thông tin. Sử dụng thuật toán HMAC_SHA256 và secretKey được cung cấp riêng cho từng đối tác để mã hóa data theo dạng: accessKey=$accessKey&param1=$param1&param2=$param2...&paramN=$paramN trong đó:

  • accessKey là chuỗi ký tự bí mật được cung cấp riêng cho từng đối tác để truy cập vào hệ thống
  • Các param là tên các field trong payload của API, được sắp xếp theo thứ tự alphabet tăng dần từ a-z

Responses

Request samples

Content type
application/json
{
  • "partnerCode": "string",
  • "deviceId": "string",
  • "storeId": "string",
  • "partnerRefOrderId": "string",
  • "orderInfo": "string",
  • "paymentAmount": 0,
  • "phone": "string",
  • "orderDate": "string",
  • "ipnUrl": "string",
  • "extraData": "string",
  • "signature": "string"
}

Response samples

Content type
application/json
{
  • "orderId": "string",
  • "transactionId": "string",
  • "paymentStatus": "pending",
  • "partnerCode": "string",
  • "extraData": "string",
  • "balanceCharged": null,
  • "extraBalanceOLCharged": null,
  • "extraBalancePartnerCharged": null,
  • "beforeBalance": null,
  • "beforeExtraBalance": null,
  • "afterBalance": null,
  • "afterExtraBalance": null,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

Lấy danh sách cổng thanh toán

Lấy danh sách cổng thanh toán

Responses

Response samples

Content type
application/json
{
  • "paymentGateways": [
    ]
}

Tra cứu thông tin giao dịch

Tra cứu thông tin giao dịch thông qua orderId

query Parameters
orderId
required
string

Mã định danh của yêu cầu thanh toán

partnerRefOrderId
required
string

Mã định danh của đơn hàng của đối tác

partnerCode
required
string

Mã định danh của đối tác

storeId
required
string

Mã định danh 1 cửa hàng của đối tác. Trong trường hợp tích hợp trên web hoặc app của đối tác, vui lòng sử dụng {mã_đối_tác}_app hoặc {mã_đối_tác}_web, trường hợp gọi từ hệ thống, vui lòng sử dụng {mã_đối_tác}_system, trong đó mã đối tác viết liền không có khoảng trắng và kí tự đặc biệt

deviceId
required
string

Mã định danh 1 máy POS trong cửa hàng của đối tác. Trong trường hợp tích hợp trên web hoặc app của đối tác, vui lòng sử dụng mã thiết bị của người dùng

signature
required
string

Chữ ký để kiểm tra thông tin. Sử dụng thuật toán HMAC_SHA256 và secretKey được cung cấp riêng cho từng đối tác để mã hóa data theo dạng: accessKey=$accessKey&param1=$param1&param2=$param2...&paramN=$paramN trong đó:

  • accessKey là chuỗi ký tự bí mật được cung cấp riêng cho từng đối tác để truy cập vào hệ thống
  • Các param là tên các field trong payload của API, được sắp xếp theo thứ tự alphabet tăng dần từ a-z

Responses

Response samples

Content type
application/json
{
  • "orderId": "string",
  • "userId": "string",
  • "userPhone": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "orderDate": "2019-08-24T14:15:22Z",
  • "totalAmount": null,
  • "undiscountTotalAmount": null,
  • "totalPaid": null,
  • "status": "draft",
  • "note": "string",
  • "partnerRefOrderId": "string",
  • "description": "string",
  • "balanceCharged": null,
  • "extraBalanceOLCharged": null,
  • "extraBalancePartnerCharged": null,
  • "type": "string",
  • "storeId": "string",
  • "deviceId": "string",
  • "ipnUrl": "string",
  • "transactionFee": null,
  • "transactionId": "string",
  • "paymentStatus": "pending"
}

Lấy dữ liệu đối soát giao dịch

Lấy dữ liệu đối soát giao dịch theo ngày

query Parameters
from
required
string <date-time>

Thời điểm bắt đầu truy xuất dữ liệu giao dịch

to
required
string <date-time>

Thời điểm kết thúc truy xuất dữ liệu giao dịch

page
integer

Số thứ tự trang kết quả cần truy xuất. Mặc định page = 1

perpage
integer

Số lượng giao dịch trả về trong 1 trang kết quả. Mặc định perpage = 100. Nếu perpage = -1 thì sẽ trả về tất cả kết quả trong 1 lần gọi mà không có phân trang

type
required
string
Enum: "TOPUP" "PAYMENT"

Loại dữ liệu giao dịch cần lấy: TOPUP = Giao dịch nạp thẻ, PAYMENT = Giao dịch thanh toán bằng OneLife

partnerCode
required
string

Mã định danh của đối tác

signature
required
string

Chữ ký để kiểm tra thông tin. Sử dụng thuật toán HMAC_SHA256 và secretKey được cung cấp riêng cho từng đối tác để mã hóa data theo dạng: accessKey=$accessKey&param1=$param1&param2=$param2...&paramN=$paramN trong đó:

  • accessKey là chuỗi ký tự bí mật được cung cấp riêng cho từng đối tác để truy cập vào hệ thống
  • Các param là tên các field trong payload của API, được sắp xếp theo thứ tự alphabet tăng dần từ a-z

Responses

Response samples

Content type
application/json
{
  • "total": 0,
  • "from": null,
  • "to": null,
  • "type": "TOPUP",
  • "page": { },
  • "results(1)": [
    ],
  • "results(2)": [
    ],
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

Lấy danh sách giao dịch 2 ngày gần nhất (dùng cho Business Portal)

Lấy danh sách giao dịch 2 ngày gần nhất (dùng cho Business Portal)

query Parameters
partnerCode
required
string

Mã định danh của đối tác

storeId
required
string

Mã định danh 1 cửa hàng của đối tác. Trong trường hợp tích hợp trên web hoặc app của đối tác, vui lòng sử dụng {mã_đối_tác}_app hoặc {mã_đối_tác}_web, trường hợp gọi từ hệ thống, vui lòng sử dụng {mã_đối_tác}_system, trong đó mã đối tác viết liền không có khoảng trắng và kí tự đặc biệt

deviceId
required
string

Mã định danh 1 máy POS trong cửa hàng của đối tác. Trong trường hợp tích hợp trên web hoặc app của đối tác, vui lòng sử dụng mã thiết bị của người dùng

signature
required
string

Chữ ký để kiểm tra thông tin. Sử dụng thuật toán HMAC_SHA256 và secretKey được cung cấp riêng cho từng đối tác để mã hóa data theo dạng: accessKey=$accessKey&password=$password&username=$username&param1=$param1&param2=$param2...&paramN=$paramN trong đó:

  • accessKey là chuỗi ký tự bí mật được cung cấp riêng cho từng đối tác để truy cập vào hệ thống
  • username là user được cung cấp riêng cho từng đối tác để truy cập vào Business Portal
  • password là mật khẩu được cung cấp riêng cho từng đối tác để truy cập vào Business Portal
  • Các param là tên các field trong payload của API, được sắp xếp theo thứ tự alphabet tăng dần từ a-z

Responses

Response samples

Content type
application/json
{
  • "orders": [
    ]
}

Lấy dữ liệu phân tích của khách hàng trong tháng

Lấy dữ liệu phân tích của khách hàng trong tháng

query Parameters
partnerCode
required
string

Mã định danh của đối tác

storeId
required
string

Mã định danh 1 cửa hàng của đối tác. Trong trường hợp tích hợp trên web hoặc app của đối tác, vui lòng sử dụng {mã_đối_tác}_app hoặc {mã_đối_tác}_web, trường hợp gọi từ hệ thống, vui lòng sử dụng {mã_đối_tác}_system, trong đó mã đối tác viết liền không có khoảng trắng và kí tự đặc biệt

deviceId
required
string

Mã định danh 1 máy POS trong cửa hàng của đối tác. Trong trường hợp tích hợp trên web hoặc app của đối tác, vui lòng sử dụng mã thiết bị của người dùng

phone
required
string

Số điện thoại đăng kí OneLife của khách hàng, định dạng +84xxxxxxxxx

signature
required
string

Chữ ký để kiểm tra thông tin. Sử dụng thuật toán HMAC_SHA256 và secretKey được cung cấp riêng cho từng đối tác để mã hóa data theo dạng: accessKey=$accessKey&password=$password&username=$username&param1=$param1&param2=$param2...&paramN=$paramN trong đó:

  • accessKey là chuỗi ký tự bí mật được cung cấp riêng cho từng đối tác để truy cập vào hệ thống
  • username là user được cung cấp riêng cho từng đối tác để truy cập vào Business Portal
  • password là mật khẩu được cung cấp riêng cho từng đối tác để truy cập vào Business Portal
  • Các param là tên các field trong payload của API, được sắp xếp theo thứ tự alphabet tăng dần từ a-z

Responses

Response samples

Content type
application/json
{
  • "totalOrdersPerMonth": 0,
  • "totalOrderValuePerMonth": null,
  • "avgOrderValuePerMonth": null
}

Lấy danh sách cửa hàng

Lấy danh sách cửa hàng

query Parameters
partnerCode
required
string

Mã định danh của đối tác

storeId
required
string

Mã định danh 1 cửa hàng của đối tác. Trong trường hợp tích hợp trên web hoặc app của đối tác, vui lòng sử dụng {mã_đối_tác}_app hoặc {mã_đối_tác}_web, trường hợp gọi từ hệ thống, vui lòng sử dụng {mã_đối_tác}_system, trong đó mã đối tác viết liền không có khoảng trắng và kí tự đặc biệt

deviceId
required
string

Mã định danh 1 máy POS trong cửa hàng của đối tác. Trong trường hợp tích hợp trên web hoặc app của đối tác, vui lòng sử dụng mã thiết bị của người dùng

signature
required
string

Chữ ký để kiểm tra thông tin. Sử dụng thuật toán HMAC_SHA256 và secretKey được cung cấp riêng cho từng đối tác để mã hóa data theo dạng: accessKey=$accessKey&password=$password&username=$username&param1=$param1&param2=$param2...&paramN=$paramN trong đó:

  • accessKey là chuỗi ký tự bí mật được cung cấp riêng cho từng đối tác để truy cập vào hệ thống
  • username là user được cung cấp riêng cho từng đối tác để truy cập vào Business Portal
  • password là mật khẩu được cung cấp riêng cho từng đối tác để truy cập vào Business Portal
  • Các param là tên các field trong payload của API, được sắp xếp theo thứ tự alphabet tăng dần từ a-z

Responses

Response samples

Content type
application/json
{
  • "stores": [
    ]
}

Quy trình thanh toán với OneLife

Quy trình thanh toán tại POS bằng app OneLife

PaymentWithApp

Quy trình thanh toán tại POS bằng số điện thoại đăng kí OneLife

PaymentWithPhoneNo

Quy trình thanh toán tại POS bằng cách quét mã QR trên máy POS

PaymentWithQRCode

Quy trình thanh toán trên app đối tác sử dụng phương thức thanh toán là thẻ OneLife

PaymentInPartnerApp

Yêu cầu thanh toán

Thanh toán bằng thẻ OneLife

Tạo yêu cầu thanh toán bằng thẻ OneLife

Có các trường hợp sau:

  • Khách hàng thanh toán dùng số điện thoại: cần truyền dữ liệu là số điện thoại vào field phone, field paymentCode để trống. Định dạng của số điện thoại là +84xxxxxxxxx
  • Khách hàng thanh toán sử dụng mã thanh toán cá nhân: dự liệu nhận từ máy scan truyền vào field paymentCode, field phone để trống. Định dạng của payment code là OLPMCxxxxxx (43 ký tự)
  • Khách hàng thanh toán bằng cách chủ động quét mã: field paymentCode và phone để trống, response trả về dùng để render thành mã QR hiển thị lên màn hình POS cho khách hàng quét Lưu ý: nếu cả 2 field phone và paymentCode đều được truyền giá trị, thì mặc định sẽ lấy paymentCode để xử lý theo luồng khách hàng sử dụng mã thanh toán cá nhân
Request Body schema: application/json
partnerCode
required
string (partnerCode)

Mã định danh của đối tác

deviceId
required
string (deviceId)

Mã định danh 1 máy POS trong cửa hàng của đối tác. Trong trường hợp tích hợp trên web hoặc app của đối tác, vui lòng sử dụng mã thiết bị của người dùng

storeId
required
string (storeId)

Mã định danh 1 cửa hàng của đối tác. Trong trường hợp tích hợp trên web hoặc app của đối tác, vui lòng sử dụng {mã_đối_tác}_app hoặc {mã_đối_tác}_web, trường hợp gọi từ hệ thống, vui lòng sử dụng {mã_đối_tác}_system, trong đó mã đối tác viết liền không có khoảng trắng và kí tự đặc biệt

partnerRefOrderId
required
string (partnerRefOrderId)

Mã định danh của đơn hàng của đối tác

orderInfo
required
string

Thông tin chi tiết hóa đơn

paymentAmount
required
integer <int64>

Số tiền cần thanh toán

phone
required
string

Số điện thoại đăng kí OneLife của khách hàng, định dạng +84xxxxxxxxx (nếu đã có phone thì không truyền paymentCode. Nếu cả 2 cùng truyền thì mặc định lấy paymentCode), nếu cả 2 không truyền thì POS sẽ đi theo flow thanh toán dùng mã QR hoặc tích hợp phương thức thanh toán trong app đối tác

paymentCode
required
string

Mã thanh toán do thu ngân quét từ app OneLife của khách hàng (nếu đã có paymentCode thì không truyền phone. Nếu cả 2 cùng truyền thì mặc định lấy paymentCode), nếu cả 2 không truyền thì POS sẽ lấy thông tin generate mã QR hoặc tích hợp phương thức thanh toán trong app đối tác

ipnUrl
string <url>

webhook phía đối tác cung cấp để OneLife trả kết quả về server đối tác. Webhook cần xây dựng với các thuộc tính như sau:

Nội dung Yêu cầu
Method POST
URL Không chứa các kí tự đặc biệt ngoại trừ _ hoặc -
Headers Content-type: application/json
Payload JSON object phía server OneLife truyền vô
Response Status code 204

Payload từ phía server OneLife truyền sang khi thông báo trạng thái giao dịch sẽ có cấu trúc như summary:

{
  "balanceCharged": float,
  "deviceId": "string",
  "extraBalanceOLCharged": float,
  "extraBalancePartnerCharged": float,
  "orderId": "string",
  "partnerCode": "string",
  "partnerRefOrderId": "string",
  "paymentAmount": float,
  "paymentCode": "string",
  "phone": "string",
  "signature": "string"
  "status": "string",
  "storeId": "string",
  "transactionId": string,
}
extraData
required
string (extraData)

Dữ liệu khác. Encode BASE64 data dưới định dạng JSON. Các key support hiện tại:

  • seller_code: thông tin mã nhân viên thực hiện giao dịch
  • pos_transaction_id: thông tin mã giao dịch máy POS (máy quét thẻ ngân hàng)
signature
required
string (signature)

Chữ ký để kiểm tra thông tin. Sử dụng thuật toán HMAC_SHA256 và secretKey được cung cấp riêng cho từng đối tác để mã hóa data theo dạng: accessKey=$accessKey&param1=$param1&param2=$param2...&paramN=$paramN trong đó:

  • accessKey là chuỗi ký tự bí mật được cung cấp riêng cho từng đối tác để truy cập vào hệ thống
  • Các param là tên các field trong payload của API, được sắp xếp theo thứ tự alphabet tăng dần từ a-z

Responses

Request samples

Content type
application/json
{
  • "partnerCode": "string",
  • "deviceId": "string",
  • "storeId": "string",
  • "partnerRefOrderId": "string",
  • "orderInfo": "string",
  • "paymentAmount": 0,
  • "phone": "string",
  • "paymentCode": "string",
  • "ipnUrl": "string",
  • "extraData": "string",
  • "signature": "string"
}

Response samples

Content type
application/json
{
  • "orderId": "string",
  • "transactionId": "string",
  • "paymentStatus": "pending",
  • "partnerCode": "string",
  • "extraData": "string",
  • "expireIn": 0,
  • "frequencyLimit": 0,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

Xác nhận thanh toán

Xác nhận thanh toán bằng thẻ OneLife

Request Body schema: application/json
partnerCode
required
string (partnerCode)

Mã định danh của đối tác

deviceId
required
string (deviceId)

Mã định danh 1 máy POS trong cửa hàng của đối tác. Trong trường hợp tích hợp trên web hoặc app của đối tác, vui lòng sử dụng mã thiết bị của người dùng

storeId
required
string (storeId)

Mã định danh 1 cửa hàng của đối tác. Trong trường hợp tích hợp trên web hoặc app của đối tác, vui lòng sử dụng {mã_đối_tác}_app hoặc {mã_đối_tác}_web, trường hợp gọi từ hệ thống, vui lòng sử dụng {mã_đối_tác}_system, trong đó mã đối tác viết liền không có khoảng trắng và kí tự đặc biệt

partnerRefOrderId
required
string (partnerRefOrderId)

Mã định danh của đơn hàng của đối tác

orderInfo
string

Thông tin chi tiết hóa đơn

paymentAmount
required
integer <int64>

Số tiền cần thanh toán

phone
string (phone)

Số điện thoại đăng kí OneLife của khách hàng, định dạng +84xxxxxxxxx (nếu đã có phone thì không truyền paymentCode. Nếu cả 2 cùng truyền thì mặc định lấy paymentCode)

paymentCode
string (paymentCode)

Mã thanh toán do thu ngân quét từ app OneLife của khách hàng (nếu đã có paymentCode thì không truyền phone. Nếu cả 2 cùng truyền thì mặc định lấy paymentCode)

orderId
required
string <string> (orderId)

Mã định danh của yêu cầu thanh toán

transactionId
required
string <string> (transactionId)

Mã định danh của giao dịch thanh toán

otp
string

Mã xác thực 1 lần (OTP) do user cung cấp được gửi bởi OneLife server qua SMS tới khách hàng. Nếu khách hàng dùng mã thanh toán cá nhân hoặc quét mã QR thì trường này không bắt buộc

extraData
string (extraData)

Dữ liệu khác. Encode BASE64 data dưới định dạng JSON. Các key support hiện tại:

  • seller_code: thông tin mã nhân viên thực hiện giao dịch
  • pos_transaction_id: thông tin mã giao dịch máy POS (máy quét thẻ ngân hàng)
signature
required
string (signature)

Chữ ký để kiểm tra thông tin. Sử dụng thuật toán HMAC_SHA256 và secretKey được cung cấp riêng cho từng đối tác để mã hóa data theo dạng: accessKey=$accessKey&param1=$param1&param2=$param2...&paramN=$paramN trong đó:

  • accessKey là chuỗi ký tự bí mật được cung cấp riêng cho từng đối tác để truy cập vào hệ thống
  • Các param là tên các field trong payload của API, được sắp xếp theo thứ tự alphabet tăng dần từ a-z

Responses

Request samples

Content type
application/json
{
  • "partnerCode": "string",
  • "deviceId": "string",
  • "storeId": "string",
  • "partnerRefOrderId": "string",
  • "orderInfo": "string",
  • "paymentAmount": 0,
  • "phone": "string",
  • "paymentCode": "string",
  • "orderId": "string",
  • "transactionId": "string",
  • "otp": "string",
  • "extraData": "string",
  • "signature": "string"
}

Response samples

Content type
application/json
{
  • "orderId": "string",
  • "transactionId": "string",
  • "paymentStatus": "pending",
  • "partnerCode": "string",
  • "extraData": "string",
  • "otpFailedCounter": 0,
  • "balanceCharged": null,
  • "extraBalanceOLCharged": null,
  • "extraBalancePartnerCharged": null,
  • "beforeBalance": null,
  • "beforeExtraBalance": null,
  • "afterBalance": null,
  • "afterExtraBalance": null,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

Hủy yêu cầu thanh toán bằng thẻ OneLife

Hủy yêu cần thanh toán bằng thẻ OneLife

Request Body schema: application/json
partnerCode
required
string (partnerCode)

Mã định danh của đối tác

deviceId
required
string (deviceId)

Mã định danh 1 máy POS trong cửa hàng của đối tác. Trong trường hợp tích hợp trên web hoặc app của đối tác, vui lòng sử dụng mã thiết bị của người dùng

storeId
required
string (storeId)

Mã định danh 1 cửa hàng của đối tác. Trong trường hợp tích hợp trên web hoặc app của đối tác, vui lòng sử dụng {mã_đối_tác}_app hoặc {mã_đối_tác}_web, trường hợp gọi từ hệ thống, vui lòng sử dụng {mã_đối_tác}_system, trong đó mã đối tác viết liền không có khoảng trắng và kí tự đặc biệt

partnerRefOrderId
required
string (partnerRefOrderId)

Mã định danh của đơn hàng của đối tác

orderId
required
string <string> (orderId)

Mã định danh của yêu cầu thanh toán

signature
required
string (signature)

Chữ ký để kiểm tra thông tin. Sử dụng thuật toán HMAC_SHA256 và secretKey được cung cấp riêng cho từng đối tác để mã hóa data theo dạng: accessKey=$accessKey&param1=$param1&param2=$param2...&paramN=$paramN trong đó:

  • accessKey là chuỗi ký tự bí mật được cung cấp riêng cho từng đối tác để truy cập vào hệ thống
  • Các param là tên các field trong payload của API, được sắp xếp theo thứ tự alphabet tăng dần từ a-z

Responses

Request samples

Content type
application/json
{
  • "partnerCode": "string",
  • "deviceId": "string",
  • "storeId": "string",
  • "partnerRefOrderId": "string",
  • "orderId": "string",
  • "signature": "string"
}

Response samples

Content type
application/json
{
  • "orderId": "string",
  • "status": "CANCELED"
}

Yêu cầu gửi Voice OTP tại POS

Yêu cầu gửi Voice OTP tại POS. Mặc định, giao dịch thanh toán dùng thẻ OneLife tại POS sẽ gửi OTP qua channel SMS. Trong trường hợp user không nhận được SMS, thì cashier có thể nhấn nút request VoiceOTP, thời gian giữa mỗi lần call API success là 60s

Request Body schema: application/json
partnerCode
required
string (partnerCode)

Mã định danh của đối tác

deviceId
required
string (deviceId)

Mã định danh 1 máy POS trong cửa hàng của đối tác. Trong trường hợp tích hợp trên web hoặc app của đối tác, vui lòng sử dụng mã thiết bị của người dùng

storeId
required
string (storeId)

Mã định danh 1 cửa hàng của đối tác. Trong trường hợp tích hợp trên web hoặc app của đối tác, vui lòng sử dụng {mã_đối_tác}_app hoặc {mã_đối_tác}_web, trường hợp gọi từ hệ thống, vui lòng sử dụng {mã_đối_tác}_system, trong đó mã đối tác viết liền không có khoảng trắng và kí tự đặc biệt

orderId
required
string <string> (orderId)

Mã định danh của yêu cầu thanh toán

extraData
required
string (extraData)

Dữ liệu khác. Encode BASE64 data dưới định dạng JSON. Các key support hiện tại:

  • seller_code: thông tin mã nhân viên thực hiện giao dịch
  • pos_transaction_id: thông tin mã giao dịch máy POS (máy quét thẻ ngân hàng)
signature
required
string (signature)

Chữ ký để kiểm tra thông tin. Sử dụng thuật toán HMAC_SHA256 và secretKey được cung cấp riêng cho từng đối tác để mã hóa data theo dạng: accessKey=$accessKey&param1=$param1&param2=$param2...&paramN=$paramN trong đó:

  • accessKey là chuỗi ký tự bí mật được cung cấp riêng cho từng đối tác để truy cập vào hệ thống
  • Các param là tên các field trong payload của API, được sắp xếp theo thứ tự alphabet tăng dần từ a-z

Responses

Request samples

Content type
application/json
{
  • "partnerCode": "string",
  • "deviceId": "string",
  • "storeId": "string",
  • "orderId": "string",
  • "extraData": "string",
  • "signature": "string"
}

Response samples

Content type
application/json
{
  • "orderId": "string",
  • "phone": "string",
  • "expireIn": 0,
  • "status": "success"
}

Quy trình nạp thẻ OneLife tại POS

Quy trình thanh toán nạp thẻ OneLife tại POS BuyOneLifeCardOffline

Yêu cầu nạp thẻ

Nạp thẻ OneLife tại POS

Lưu ý: phần tài liệu dưới đây mô tả về việc đối tác tích hợp qua API, Nếu đối tác lựa chọn giải pháp embed web view, vui lòng theo dõi tại đây

Tạo Yêu cầu nạp thẻ

Tạo yêu cầu nạp thẻ OneLife

Request Body schema: application/json
partnerCode
required
string (partnerCode)

Mã định danh của đối tác

deviceId
required
string (deviceId)

Mã định danh 1 máy POS trong cửa hàng của đối tác. Trong trường hợp tích hợp trên web hoặc app của đối tác, vui lòng sử dụng mã thiết bị của người dùng

storeId
required
string (storeId)

Mã định danh 1 cửa hàng của đối tác. Trong trường hợp tích hợp trên web hoặc app của đối tác, vui lòng sử dụng {mã_đối_tác}_app hoặc {mã_đối_tác}_web, trường hợp gọi từ hệ thống, vui lòng sử dụng {mã_đối_tác}_system, trong đó mã đối tác viết liền không có khoảng trắng và kí tự đặc biệt

partnerRefOrderId
required
string (partnerRefOrderId)

Mã định danh của đơn hàng của đối tác

brandCardId
required
string

Mã định danh của thẻ OneLife cần nạp. Mã định danh được trả về từ API Lấy danh sách thẻ OneLife

phone
required
string (phone)

Số điện thoại đăng kí OneLife của khách hàng, định dạng +84xxxxxxxxx (nếu đã có phone thì không truyền paymentCode. Nếu cả 2 cùng truyền thì mặc định lấy paymentCode)

paymentCode
required
string (paymentCode)

Mã thanh toán do thu ngân quét từ app OneLife của khách hàng (nếu đã có paymentCode thì không truyền phone. Nếu cả 2 cùng truyền thì mặc định lấy paymentCode)

paymentMethod
required
any (paymentMethod)
Enum: "cash" "banking_card"

Phương thức thanh toán

extraData
required
string (extraData)

Dữ liệu khác. Encode BASE64 data dưới định dạng JSON. Các key support hiện tại:

  • seller_code: thông tin mã nhân viên thực hiện giao dịch
  • pos_transaction_id: thông tin mã giao dịch máy POS (máy quét thẻ ngân hàng)
signature
required
string (signature)

Chữ ký để kiểm tra thông tin. Sử dụng thuật toán HMAC_SHA256 và secretKey được cung cấp riêng cho từng đối tác để mã hóa data theo dạng: accessKey=$accessKey&param1=$param1&param2=$param2...&paramN=$paramN trong đó:

  • accessKey là chuỗi ký tự bí mật được cung cấp riêng cho từng đối tác để truy cập vào hệ thống
  • Các param là tên các field trong payload của API, được sắp xếp theo thứ tự alphabet tăng dần từ a-z

Responses

Request samples

Content type
application/json
{
  • "partnerCode": "string",
  • "deviceId": "string",
  • "storeId": "string",
  • "partnerRefOrderId": "string",
  • "brandCardId": "string",
  • "phone": "string",
  • "paymentCode": "string",
  • "paymentMethod": "cash",
  • "extraData": "string",
  • "signature": "string"
}

Response samples

Content type
application/json
{
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "orderId": "string",
  • "transactionId": "string",
  • "paymentStatus": "pending",
  • "partnerCode": "string",
  • "extraData": "string",
  • "expireIn": 0,
  • "partnerRefOrderId": "string"
}

Xác nhận nạp thẻ

Xác nhận nạp thẻ OneLife

Request Body schema: application/json
brandCardId
required
int64

Mã thẻ nạp

partnerCode
required
string (partnerCode)

Mã định danh của đối tác

deviceId
required
string (deviceId)

Mã định danh 1 máy POS trong cửa hàng của đối tác. Trong trường hợp tích hợp trên web hoặc app của đối tác, vui lòng sử dụng mã thiết bị của người dùng

storeId
required
string (storeId)

Mã định danh 1 cửa hàng của đối tác. Trong trường hợp tích hợp trên web hoặc app của đối tác, vui lòng sử dụng {mã_đối_tác}_app hoặc {mã_đối_tác}_web, trường hợp gọi từ hệ thống, vui lòng sử dụng {mã_đối_tác}_system, trong đó mã đối tác viết liền không có khoảng trắng và kí tự đặc biệt

partnerRefOrderId
required
string (partnerRefOrderId)

Mã định danh của đơn hàng của đối tác

orderId
required
string <string> (orderId)

Mã định danh của yêu cầu thanh toán

transactionId
required
string <string> (transactionId)

Mã định danh của giao dịch thanh toán

phone
required
string (phone)

Số điện thoại đăng kí OneLife của khách hàng, định dạng +84xxxxxxxxx (nếu đã có phone thì không truyền paymentCode. Nếu cả 2 cùng truyền thì mặc định lấy paymentCode)

paymentCode
required
string (paymentCode)

Mã thanh toán do thu ngân quét từ app OneLife của khách hàng (nếu đã có paymentCode thì không truyền phone. Nếu cả 2 cùng truyền thì mặc định lấy paymentCode)

paymentMethod
required
any (paymentMethod)
Enum: "cash" "banking_card"

Phương thức thanh toán

otp
required
string

Mã xác thực 1 lần (OTP) do user cung cấp được gửi bởi OneLife server qua SMS tới khách hàng. Nếu khách hàng dùng mã thanh toán cá nhân hoặc quét mã thì trường này không bắt buộc

extraData
required
string (extraData)

Dữ liệu khác. Encode BASE64 data dưới định dạng JSON. Các key support hiện tại:

  • seller_code: thông tin mã nhân viên thực hiện giao dịch
  • pos_transaction_id: thông tin mã giao dịch máy POS (máy quét thẻ ngân hàng)
signature
required
string (signature)

Chữ ký để kiểm tra thông tin. Sử dụng thuật toán HMAC_SHA256 và secretKey được cung cấp riêng cho từng đối tác để mã hóa data theo dạng: accessKey=$accessKey&param1=$param1&param2=$param2...&paramN=$paramN trong đó:

  • accessKey là chuỗi ký tự bí mật được cung cấp riêng cho từng đối tác để truy cập vào hệ thống
  • Các param là tên các field trong payload của API, được sắp xếp theo thứ tự alphabet tăng dần từ a-z

Responses

Request samples

Content type
application/json
{
  • "brandCardId": null,
  • "partnerCode": "string",
  • "deviceId": "string",
  • "storeId": "string",
  • "partnerRefOrderId": "string",
  • "orderId": "string",
  • "transactionId": "string",
  • "phone": "string",
  • "paymentCode": "string",
  • "paymentMethod": "cash",
  • "otp": "string",
  • "extraData": "string",
  • "signature": "string"
}

Response samples

Content type
application/json
{
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "orderId": "string",
  • "transactionId": "string",
  • "paymentStatus": "pending",
  • "partnerCode": "string",
  • "extraData": "string",
  • "otpFailedCounter": 0,
  • "beforeBalance": null,
  • "beforeExtraBalance": null,
  • "afterBalance": null,
  • "afterExtraBalance": null,
  • "customerFullname": "string",
  • "customerPhone": "string",
  • "expireIn": 0,
  • "frequencyLimit": 0
}

Cập nhật extraData của giao dich

Cập nhật extraData của giao dịch

Request Body schema: application/json
partnerCode
required
string (partnerCode)

Mã định danh của đối tác

deviceId
required
string (deviceId)

Mã định danh 1 máy POS trong cửa hàng của đối tác. Trong trường hợp tích hợp trên web hoặc app của đối tác, vui lòng sử dụng mã thiết bị của người dùng

storeId
required
string (storeId)

Mã định danh 1 cửa hàng của đối tác. Trong trường hợp tích hợp trên web hoặc app của đối tác, vui lòng sử dụng {mã_đối_tác}_app hoặc {mã_đối_tác}_web, trường hợp gọi từ hệ thống, vui lòng sử dụng {mã_đối_tác}_system, trong đó mã đối tác viết liền không có khoảng trắng và kí tự đặc biệt

orderId
required
string <string> (orderId)

Mã định danh của yêu cầu thanh toán

paymentMethod
required
any (paymentMethod)
Enum: "cash" "banking_card"

Phương thức thanh toán

extraData
required
string (extraData)

Dữ liệu khác. Encode BASE64 data dưới định dạng JSON. Các key support hiện tại:

  • seller_code: thông tin mã nhân viên thực hiện giao dịch
  • pos_transaction_id: thông tin mã giao dịch máy POS (máy quét thẻ ngân hàng)
signature
required
string (signature)

Chữ ký để kiểm tra thông tin. Sử dụng thuật toán HMAC_SHA256 và secretKey được cung cấp riêng cho từng đối tác để mã hóa data theo dạng: accessKey=$accessKey&param1=$param1&param2=$param2...&paramN=$paramN trong đó:

  • accessKey là chuỗi ký tự bí mật được cung cấp riêng cho từng đối tác để truy cập vào hệ thống
  • Các param là tên các field trong payload của API, được sắp xếp theo thứ tự alphabet tăng dần từ a-z

Responses

Request samples

Content type
application/json
{
  • "partnerCode": "string",
  • "deviceId": "string",
  • "storeId": "string",
  • "orderId": "string",
  • "paymentMethod": "cash",
  • "extraData": "string",
  • "signature": "string"
}

Response samples

Content type
application/json
{
  • "extraData": "string"
}

OneLife Club - Chương trình thành viên

Chương trình thành viên OneLife

Lấy danh sách hạng thành viên của nhà bán hàng

Lấy danh sách hạng thành viên của nhà bán hàng

query Parameters
merchant_id
required
uint64

Mã định danh của nhà bán hàng

Responses

Response samples

Content type
application/json
{
  • "code": null,
  • "success": true,
  • "message": "string",
  • "data": [
    ]
}

Lấy thông tin hạng thành viên của người dùng đối với nhà bán hàng

Lấy thông tin hạng thành viên của người dùng đối với nhà bán hàng

query Parameters
customer_id
required
string

Mã định danh của người dùng OneLife, được lấy từ JWT Token trả về khi user login

merchant_id
required
string

Mã định danh của nhà bán hàng

Responses

Response samples

Content type
application/json
{
  • "code": null,
  • "success": true,
  • "message": "string",
  • "data": {
    }
}

Cấu hình danh sách hạng thành viên cho nhà bán hàng

Cấu hình danh sách hạng thành viên cho nhà bán hàng

Request Body schema: application/json
Array of objects

Danh sách cấu hình hạng thành viên

Responses

Request samples

Content type
application/json
{
  • "merchant_memberships": [
    ]
}

Response samples

Content type
application/json
{
  • "code": null,
  • "success": true,
  • "message": "string",
  • "data": [
    ]
}

Tích luỹ điểm thưởng của nhà bán hàng

Tích luỹ điểm thưởng của nhà bán hàng

Request Body schema: application/json
customer_id
required
uint64

Mã định danh của người dùng

merchant_id
required
uint64

Mã định danh của nhà bán hàng

order_id
required
string

Mã định danh của đơn hàng

total_amount
required
float

Tổng giá trị đơn hàng

Responses

Request samples

Content type
application/json
{
  • "customer_id": null,
  • "merchant_id": null,
  • "order_id": "string",
  • "total_amount": null
}

Response samples

Content type
application/json
{
  • "code": null,
  • "message": "string",
  • "success": true
}

Đổi thưởng

Đổi thưởng

Request Body schema: application/json
customer_id
required
uint64

Mã định danh của người dùng

reward_id
required
uint64

Mã định danh của phần thưởng

Responses

Request samples

Content type
application/json
{
  • "customer_id": null,
  • "reward_id": null
}

Response samples

Content type
application/json
{
  • "action": "string",
  • "payload": {
    }
}

Lấy danh sách thưởng của nhà bán hàng

Lấy danh sách thưởng của nhà bán hàng

query Parameters
merchant_id
required
string

Mã định danh của nhà bán hàng

from
int

Thời điểm phần thưởng bắt đầu có hiệu lực,\nđơn vị thời gian được tính theo giây (unix timestamp in seconds)

to
int

Thời điểm phần thưởng hết hiệu lực,\nđơn vị thời gian được tính theo giây (unix timestamp in seconds)

Responses

Response samples

Content type
application/json
{
  • "code": null,
  • "success": true,
  • "message": "string",
  • "data": [
    ]
}

Hook đồng bộ thay đổi điểm, chi tiêu, hạng thành viên từ KingFood

Hook đồng bộ thay đổi điểm, chi tiêu, hạng thành viên từ KingFood

Request Body schema: application/json
action
required
string

Mô tả hook

required
object

Payload chứa thông tin của yêu cầu

Responses

Request samples

Content type
application/json
{
  • "action": "string",
  • "payload": {
    }
}

Response samples

Content type
application/json
{
  • "code": null,
  • "success": true,
  • "message": "string"
}

Sản phẩm trên OneLife

Quản lý thông tin sản phẩm

Sản phẩm gợi ý - Kingfoodmart

Sản phẩm gợi ý cho đơn hàng Kingfoodmart

query Parameters
username
required
string

Tài khoản để xác minh người dùng

password
required
string

Mật khẩu

customerCode
required
string

Mã khách hàng trên hệ thống Kingfoodmart. Ví dụ KH00112233

barcodesInOrder
required
string

Mã sản phẩm của các mặt hàng hiện có trong đơn hàng của khách hàng (Dùng để gợi ý và để loại trừ sản phẩm nào đã có trong đơn hàng). Các mã được ghép lại thành một chuỗi, ngăn cách bởi dấu phẩy. Ví dụ "8935006539273,8934673601825"

recomZone
required
string
Enum: "reorder" "may_like" "popular_product" "cobuy" "recent_view"

Phân biệt vùng giới thiệu sản phẩm trên trang web. Giá trị của trường này gồm có:

  • reorder: sản phẩm đã đặt
  • may_like: sản phẩm có thể khách hàng sẽ thích
  • popular_product: sản phẩm nổi bật
  • cobuy: sản phẩm hay được mua cùng
  • recent_view: sản phẩm đã xem gần đây

Responses

Response samples

Content type
application/json
{
  • "total": 0,
  • "variants": [
    ]
}

Sản phẩm gợi ý - OneLife

Sản phẩm gợi ý cho đơn hàng OneLife

query Parameters
username
required
string

Tài khoản để xác minh người dùng

password
required
string

Mật khẩu

userId
required
string

Mã khách hàng của customer trên hệ thống OneLife dạng uint64. Ví dụ 188233172716412231

barcodesInOrder
required
string

Mã sản phẩm của các mặt hàng hiện có trong đơn hàng của khách hàng (Dùng để gợi ý và để loại trừ sản phẩm nào đã có trong đơn hàng). Các mã được ghép lại thành một chuỗi, ngăn cách bởi dấu phẩy. Ví dụ "8935006539273,8934673601825"

recomZone
required
string
Enum: "reorder" "may_like" "popular_product" "cobuy" "recent_view"

Phân biệt vùng giới thiệu sản phẩm trên trang web. Giá trị của trường này gồm có:

  • reorder: sản phẩm đã đặt
  • may_like: sản phẩm có thể khách hàng sẽ thích
  • popular_product: sản phẩm nổi bật
  • cobuy: sản phẩm hay được mua cùng
  • recent_view: sản phẩm đã xem gần đây

Responses

Response samples

Content type
application/json
{
  • "total": 0,
  • "variants": [
    ]
}

Sản phẩm Flash-sale

Sản phẩm flash-sale cho đơn hàng OneLife

query Parameters
userId
required
string

Mã khách hàng của customer trên hệ thống OneLife dạng uint64. Ví dụ 188233172716412231

barcodesInOrder
required
string

Mã sản phẩm của các mặt hàng hiện có trong đơn hàng của khách hàng (Dùng để gợi ý và để loại trừ sản phẩm nào đã có trong đơn hàng). Các mã được ghép lại thành một chuỗi, ngăn cách bởi dấu phẩy. Ví dụ "8935006539273,8934673601825"

Responses

Response samples

Content type
application/json
{
  • "total": 0,
  • "remainTime": 0,
  • "variants": [
    ]
}

Sản phẩm khuyến mãi

Sản phẩm khuyến mãi cho đơn hàng OneLife

query Parameters
userId
required
string

Mã khách hàng của customer trên hệ thống OneLife dạng uint64. Ví dụ 188233172716412231

barcodesInOrder
required
string

Mã sản phẩm của các mặt hàng hiện có trong đơn hàng của khách hàng (Dùng để gợi ý và để loại trừ sản phẩm nào đã có trong đơn hàng). Các mã được ghép lại thành một chuỗi, ngăn cách bởi dấu phẩy. Ví dụ "8935006539273,8934673601825"

Responses

Response samples

Content type
application/json
{
  • "total": 0,
  • "remainTime": 0,
  • "variants": [
    ]
}

Danh sách mã lỗi

Danh sách mã lỗi trả về từ hệ thống của OneLife

Code Mô tả
0 Lỗi không xác định. Vui lòng liên hệ support@onelife.vn để được hỗ trợ
2000 Payload thiếu các trường yêu cầu
2001 Payload không chính xác
2002 Chữ ký không chính xác
2003 Thông tin không chính xác
2004 Số điện thoại không chính xác
3000 Quyền truy cập bị từ chối
3001 Tài khoản chưa xác thực
3002 Tài khoản không hoạt động
3003 Mã OTP không chính xác
3004 Quá giới hạn số lần gửi OTP. Vui lòng thử lại sau
3005 OTP nhập sai quá số lần cho phép
3006 Quá giới hạn số lần gửi OTP
4000 Hệ thống đang bảo trì. Vui lòng thử lại sau
4001 Lỗi hệ thống. Vui lòng liên hệ support@onelife.vn để được hỗ trợ
4002 Deadline exceeded
4003 Canceled
4004 Aborted
5001 Tài khoản không tồn tại
5002 Tài khoản thanh toán không tồn tại
6001 Mã thanh toán không chính xác hoặc đã hết hạn
6002 Mã thanh toán đã hết hạn
6003 Số dư tài khoản không đủ
6004 Giao dịch đã hết hạn
6005 Tài khoản vượt quá hạn mức
6006 Giao dịch đã thanh toán
6007 Trạng thái giao dịch không hỗ trợ thao tác này
6008 Loại giao dịch không hỗ trợ thao tác này
6009 Từ chối bổ sung giao dịch thanh toán vì tài khoản đã có giao dịch phát sinh. Vui lòng liên hệ team OneLife để được hỗ trợ
6010 Từ chối hủy giao dịch vì tài khoản đã có giao dịch phát sinh. Vui lòng liên hệ team OneLife để được hỗ trợ
6011 Số điện thoại không chính xác với thông tin trong giao dịch
6012 Giao dịch đã bị hủy