API nạp cước

Tổng quan#

Một endpoint nhận mọi lệnh, phân biệt bằng tham số command. Gửi POST với thân JSON; phản hồi luôn là JSON gồm status, message và (khi thành công) data.

Endpoint

https://thepay1s.com/api/rechargews

Phương thức

POST

Kiểu dữ liệu

application/json

Lệnh

topup, getstatus, getbalance, productlist, canceltopup, feetopup

Điều kiện

• Kết nối API có loại Nạp cước/game và đang hoạt động; tài khoản sở hữu và ví không bị khoá.
• Nếu kết nối có danh sách Địa chỉ IP, yêu cầu phải gửi từ các IP đó, nếu không trả status=114.
• request_id của lệnh topup là duy nhất trong tài khoản; gửi trùng trả status=102 và không tạo đơn mới.
• Gọi productlist trước để biết service_code, mệnh giá và các khoá cần gửi trong account_info.
• API không gọi callback về hệ thống của bạn. Sau khi tạo đơn, dùng getstatus để theo dõi tới khi đơn có trạng thái cuối.

Ghi chú tương thích

• Lỗi trả status là mã số dạng chuỗi (101, 104…), không phải mã chữ như wrong_signature hay command_invalid.
• Chỉ đọc thân JSON (application/json); tham số dạng form hoặc query string không được đọc.
• Số lượng gửi ở tham số qty cùng cấp với amount, không đặt trong account_info.
• Mọi phản hồi thành công có message ở cấp ngoài cùng, kể cả topup và getbalance.

Chữ ký#

sign là MD5 của Partner Key ghép với Partner ID, tên lệnh và (với lệnh có request_id) mã đơn của bạn. Thứ tự ghép khác với API đổi thẻ: partner_id đứng trước command.

Ví dụ tính chữ ký

Với Partner Key giả định YOUR_PARTNER_KEY và Partner ID ở các ví dụ:

topup#

Tạo đơn nạp cho tài khoản đích. Tiền được trừ khỏi ví ngay khi tạo đơn; đơn mới ở trạng thái pending.

• commandchuỗiBắt buộcTên lệnh, đúng như tên mục.
• partner_idchuỗiBắt buộcPartner ID của kết nối.
• request_idchuỗiBắt buộcMã đơn phía bạn. Lệnh topup: mã mới, duy nhất trong tài khoản. Lệnh getstatus và canceltopup: request_id đã dùng khi topup.
• service_codechuỗiBắt buộcMã sản phẩm, lấy từ productlist.
• amountsố nguyênBắt buộcSố tiền nạp (VND), số nguyên.
• account_infoobjectBắt buộcObject thông tin nhận nạp, các khoá theo options của sản phẩm (ví dụ phone với nạp điện thoại, account với nạp game).
• qtysố nguyênSố lượng, mặc định 1, không vượt quá quantity_max của sản phẩm (nếu có).
• signchuỗiBắt buộcChữ ký md5(partner_key + partner_id + command + request_id), xem mục Chữ ký.

{
    "command": "topup",
    "partner_id": "YOUR_PARTNER_ID",
    "request_id": "TOPUP20261024001",
    "service_code": "VIETTEL",
    "amount": 100000,
    "account_info": {
        "phone": "0987654321"
    },
    "qty": 1,
    "sign": "bea6f2c44abfc7ad97dca6c4e7d9588c"
}

• Số tiền trừ ví: pay_amount = amount × (100 − discount) / 100 × qty, với discount là chiết khấu theo nhóm của tài khoản.
• Sản phẩm loại mobile: amount phải là một value trong items của sản phẩm.
• Sản phẩm loại game: amount nằm trong khoảng min_value tới max_value của option amount và là bội của multiple_value; sai trả status=102.
• Gửi lại cùng request_id trả lỗi REQUEST ID DA TON TAI; dùng getstatus để lấy đơn đã tạo.

getstatus#

Tra cứu trạng thái một đơn cước/game đã tạo.

• commandchuỗiBắt buộcTên lệnh, đúng như tên mục.
• partner_idchuỗiBắt buộcPartner ID của kết nối.
• request_idchuỗiBắt buộcMã đơn phía bạn. Lệnh topup: mã mới, duy nhất trong tài khoản. Lệnh getstatus và canceltopup: request_id đã dùng khi topup.
• order_codechuỗiBắt buộcMã đơn hệ thống trả về ở lệnh topup.
• signchuỗiBắt buộcChữ ký md5(partner_key + partner_id + command + request_id), xem mục Chữ ký.

{
    "command": "getstatus",
    "partner_id": "YOUR_PARTNER_ID",
    "request_id": "TOPUP20261024001",
    "order_code": "RE7K2M9Q4XZ1A",
    "sign": "96fbff46acf8dff0ea4d591f96d74f01"
}

• Hỏi cách nhau ít nhất 30 giây và dừng khi đơn ở trạng thái completed, failed hoặc canceled.

getbalance#

Lấy số dư ví của tài khoản sở hữu kết nối, ví dùng để thanh toán đơn cước/game.

• commandchuỗiBắt buộcTên lệnh, đúng như tên mục.
• partner_idchuỗiBắt buộcPartner ID của kết nối.
• signchuỗiBắt buộcChữ ký md5(partner_key + partner_id + command), xem mục Chữ ký.

{
    "command": "getbalance",
    "partner_id": "YOUR_PARTNER_ID",
    "sign": "1a4651ad1fc33b21b9a5dabf410c7f79"
}

• Lệnh không dùng request_id, không tạo giao dịch.

productlist#

Lấy danh sách sản phẩm đang bán: mệnh giá, giá theo nhóm của tài khoản và các trường cần nhập.

• commandchuỗiBắt buộcTên lệnh, đúng như tên mục.
• partner_idchuỗiBắt buộcPartner ID của kết nối.
• signchuỗiBắt buộcChữ ký md5(partner_key + partner_id + command), xem mục Chữ ký.

{
    "command": "productlist",
    "partner_id": "YOUR_PARTNER_ID",
    "sign": "e23aa765d9cc5696811207b0125172c5"
}

• Danh sách và giá có thể thay đổi, nên lấy lại định kỳ thay vì lưu cố định. Ý nghĩa từng trường ở mục Phản hồi và trạng thái đơn.

canceltopup#

Huỷ một đơn chưa hoàn tất và hoàn tiền về ví.

• commandchuỗiBắt buộcTên lệnh, đúng như tên mục.
• partner_idchuỗiBắt buộcPartner ID của kết nối.
• request_idchuỗiBắt buộcMã đơn phía bạn. Lệnh topup: mã mới, duy nhất trong tài khoản. Lệnh getstatus và canceltopup: request_id đã dùng khi topup.
• order_codechuỗiBắt buộcMã đơn hệ thống trả về ở lệnh topup.
• signchuỗiBắt buộcChữ ký md5(partner_key + partner_id + command), xem mục Chữ ký.

{
    "command": "canceltopup",
    "partner_id": "YOUR_PARTNER_ID",
    "request_id": "TOPUP20261024001",
    "order_code": "RE7K2M9Q4XZ1A",
    "sign": "a1ae1cf89832e8f58f72060617029fb6"
}

• Chỉ huỷ được đơn ở trạng thái pending hoặc processing; số tiền đã trừ (pay_amount) được hoàn về ví và đơn chuyển sang canceled.
• Chữ ký của canceltopup không ghép request_id, dù lệnh có gửi request_id.

feetopup#

Lấy bảng giá và chiết khấu theo nhóm của tài khoản cho từng mệnh giá.

• commandchuỗiBắt buộcTên lệnh, đúng như tên mục.
• partner_idchuỗiBắt buộcPartner ID của kết nối.
• signchuỗiBắt buộcChữ ký md5(partner_key + partner_id + command), xem mục Chữ ký.

{
    "command": "feetopup",
    "partner_id": "YOUR_PARTNER_ID",
    "sign": "5fea7c50b47e206c353b79caebafbee3"
}

• Mỗi dòng là một mệnh giá của một sản phẩm, key là service_code.

Phản hồi và trạng thái đơn#

Thành công: status là chuỗi success, kèm message và data. Lỗi: status là mã số dạng chuỗi và message, không có data. Luôn trả HTTP 200.

Các trường trong data

• time
  Kiểu

  chuỗi
  Lệnh

  topup
  Mô tả

  Thời điểm tạo đơn, dạng YYYY-MM-DD HH:mm:ss giờ Việt Nam.
• request_id
  Kiểu

  chuỗi
  Lệnh

  topup, getstatus, canceltopup
  Mô tả

  request_id bạn đã gửi.
• order_code
  Kiểu

  chuỗi
  Lệnh

  topup, getstatus, canceltopup
  Mô tả

  Mã đơn của hệ thống, dùng cho getstatus và canceltopup.
• service_code
  Kiểu

  chuỗi
  Lệnh

  topup
  Mô tả

  Mã sản phẩm.
• amount
  Kiểu

  số nguyên
  Lệnh

  topup, getstatus
  Mô tả

  topup: số tiền nạp bạn gửi. getstatus: số tiền đã trừ ví.
• request_value
  Kiểu

  số nguyên
  Lệnh

  getstatus
  Mô tả

  Số tiền nạp của đơn.
• pay_amount
  Kiểu

  số nguyên
  Lệnh

  topup
  Mô tả

  Số tiền đã trừ ví.
• discount
  Kiểu

  số
  Lệnh

  topup, feetopup
  Mô tả

  Chiết khấu theo phần trăm.
• account
  Kiểu

  object
  Lệnh

  getstatus
  Mô tả

  account_info của đơn.
• status
  Kiểu

  chuỗi
  Lệnh

  topup, getstatus, canceltopup
  Mô tả

  Trạng thái đơn, xem bảng bên dưới.
• balance
  Kiểu

  số nguyên
  Lệnh

  getbalance
  Mô tả

  Số dư ví (VND).
• currency
  Kiểu

  chuỗi
  Lệnh

  getbalance
  Mô tả

  Luôn là VND.
• key, value, price
  Kiểu

  mảng
  Lệnh

  feetopup
  Mô tả

  Mảng các dòng gồm key (service_code), value (mệnh giá), price (giá sau chiết khấu) và discount.

Sản phẩm trong productlist

• name
  Kiểu

  chuỗi
  Mô tả

  Tên sản phẩm.
• service_code
  Kiểu

  chuỗi
  Mô tả

  Mã sản phẩm, gửi trong service_code của topup.
• type
  Kiểu

  chuỗi
  Mô tả

  mobile: chọn một mệnh giá trong items. game: nhập số tiền theo option amount.
• quantity_max
  Kiểu

  số nguyên
  Mô tả

  Số lượng tối đa mỗi đơn, 0 hoặc 1 nghĩa là chỉ nạp một lần.
• items
  Kiểu

  mảng
  Mô tả

  Mệnh giá: name, value, price (giá sau chiết khấu) và discount theo nhóm của tài khoản.
• options
  Kiểu

  mảng
  Mô tả

  Các trường cần nhập: key (khoá trong account_info), name, type; option amount có thêm min_value, max_value, multiple_value.

Trạng thái đơn (data.status)

• pending
  Ý nghĩa

  Đã nhận đơn, tiền đã trừ, đang chờ gửi sang nhà cung cấp. Có thể huỷ.
• processing
  Ý nghĩa

  Nhà cung cấp đang xử lý. Có thể huỷ nếu nhà cung cấp chưa nạp.
• completed
  Ý nghĩa

  Nạp thành công.
• failed
  Ý nghĩa

  Nhà cung cấp báo thất bại. Đơn được quản trị viên đối soát; nếu hoàn tiền, đơn chuyển sang canceled.
• canceled
  Ý nghĩa

  Đơn đã huỷ và tiền đã hoàn về ví.

Mã lỗi#

Thông báo được giữ nguyên văn để bạn so khớp, nhưng nên xử lý theo status.

• 100
  message

  API KEY KHONG DUNG
  Nguyên nhân và cách xử lý

  partner_id không tồn tại hoặc kết nối không có loại Nạp cước/game.
• 100
  message

  Api key chưa được bật
  Nguyên nhân và cách xử lý

  Kết nối đang tắt.
• 100
  message

  Tài khoản bị khóa
  Nguyên nhân và cách xử lý

  Tài khoản sở hữu kết nối đang bị khoá.
• 100
  message

  Địa chỉ ví bị khóa
  Nguyên nhân và cách xử lý

  Ví của tài khoản đang bị khoá.
• 101
  message

  CHU KY KHONG HOP LE
  Nguyên nhân và cách xử lý

  Chữ ký không khớp. Kiểm tra Partner Key, thứ tự ghép và lệnh có ghép request_id hay không.
• 102
  message

  REQUEST ID DA TON TAI
  Nguyên nhân và cách xử lý

  request_id đã được dùng cho một đơn khác trong tài khoản.
• 102
  message

  LOI MENH GIA TIEN
  Nguyên nhân và cách xử lý

  amount không phải mệnh giá của sản phẩm, hoặc ngoài khoảng cho phép với sản phẩm loại game.
• 102
  message

  Thông tin tài khoản nạp không hợp lệ
  Nguyên nhân và cách xử lý

  account_info thiếu khoá bắt buộc theo options, hoặc qty vượt quantity_max.
• 102
  message

  Số tiền trong tài khoản không đủ
  Nguyên nhân và cách xử lý

  Số dư ví không đủ cho pay_amount.
• 102
  message

  Số dư nguồn thẻ không đủ, vui lòng báo admin nạp thêm
  Nguyên nhân và cách xử lý

  Nguồn nạp tạm hết số dư; thử lại sau hoặc liên hệ hỗ trợ.
• 102
  message

  Giao dich khong the huy
  Nguyên nhân và cách xử lý

  Đơn đã hoàn tất, thất bại hoặc đã huỷ nên không huỷ được.
• 102
  message

  LOI HE THONG, VUI LONG THU LAI SAU
  Nguyên nhân và cách xử lý

  Lỗi phía hệ thống khi tạo đơn; tiền không bị trừ. Thử lại sau với cùng request_id.
• 103
  message

  Khong Tin Thay GD
  Nguyên nhân và cách xử lý

  Không có đơn nào của tài khoản với request_id và order_code này.
• 104
  message

  merchant_not_existed_or_off
  Nguyên nhân và cách xử lý

  Thiếu tham số bắt buộc của lệnh, hoặc thân yêu cầu không phải JSON hợp lệ.
• 104
  message

  COMMAND KHÔNG HỢP LỆ
  Nguyên nhân và cách xử lý

  command không thuộc danh sách lệnh hỗ trợ.
• 105
  message

  ITEM KHONG TON TAI
  Nguyên nhân và cách xử lý

  service_code không tồn tại hoặc sản phẩm đang tắt.
• 114
  message

  Địa chỉ IP không được phép, vui lòng gửi IP này cho admin
  Nguyên nhân và cách xử lý

  IP gọi API không nằm trong danh sách Địa chỉ IP của kết nối. Thông báo kèm IP hệ thống nhận được.

Thử bằng key sandbox

Dùng key sandbox (Partner ID bắt đầu bằng sandbox_) với đúng URL này. Sản phẩm, mệnh giá, tài khoản và giá vẫn kiểm tra trên danh mục thật; kết quả chọn bằng đuôi request_id, đọc từ dấu _ cuối cùng, không phân biệt hoa thường.

• (không có)
  Kết quả

  Thành công ngay (status success, đơn completed), trừ tiền thử
• _pending
  Kết quả

  Đơn pending, vài giây sau thành completed, trừ tiền thử
• _processing
  Kết quả

  Đơn processing (đã gửi nhà cung cấp, không huỷ được), sau đó completed
• _failed
  Kết quả

  Đơn pending, vài giây sau thành failed và hoàn tiền thử
• _canceled
  Kết quả

  Đơn pending, vài giây sau thành canceled và hoàn tiền thử
• _stuck
  Kết quả

  Đơn pending mãi, chỉ đổi khi huỷ bằng canceltopup hoặc đặt kết quả tay
• _rejected
  Kết quả

  Trả lỗi 102 (LOI HE THONG), tiền thử trừ rồi hoàn ngay
• _providerbalance
  Kết quả

  Trả lỗi 102 nguồn thẻ không đủ, không trừ tiền
• _maintenance
  Kết quả

  Trả lỗi 107 dịch vụ bảo trì, không trừ tiền
• _locked
  Kết quả

  Trả lỗi 100 tài khoản bị khoá, không trừ tiền
• _walletlocked
  Kết quả

  Trả lỗi 100 ví bị khoá, không trừ tiền

Code mẫu#

Hàm mẫu tự tính chữ ký theo từng lệnh rồi gửi yêu cầu; ví dụ tạo đơn cước/game rồi tra trạng thái. Tab cURL gửi lệnh topup.

PARTNER_ID='YOUR_PARTNER_ID'
PARTNER_KEY='YOUR_PARTNER_KEY'
REQUEST_ID='TOPUP20261024001'
SIGN=$(printf '%s' "${PARTNER_KEY}${PARTNER_ID}topup${REQUEST_ID}" | md5sum | cut -d ' ' -f 1)

curl -X POST 'https://thepay1s.com/api/rechargews' \
  -H 'Content-Type: application/json' \
  --data-binary @- <<JSON
{
  "command": "topup",
  "partner_id": "$PARTNER_ID",
  "request_id": "$REQUEST_ID",
  "service_code": "VIETTEL",
  "amount": 100000,
  "account_info": {
    "phone": "0987654321"
  },
  "qty": 1,
  "sign": "$SIGN"
}
JSON