Tài liệu tích hợp API Nappay

Charging v2 · Recharge · Softcard · Card Partner

Tổng hợp 3 module API dành cho Merchant: gửi thẻ cào (Charging v2), nạp tiền dịch vụ (Recharge) và mua mã thẻ điện tử (Softcard). Mỗi module có công thức chữ ký, tham số, ví dụ request/response (JSON, cURL, PHP, Python, Node.js) và bảng mã trạng thái riêng.

Charging API v2

Gửi thẻ cào, kiểm tra trạng thái, lấy biểu phí.

Recharge API

Nạp tiền dịch vụ, số dư, danh sách sản phẩm.

Softcard API

Mua mã thẻ điện tử, tải lại đơn, kiểm tra tồn kho.

Charging API v2 API mới

Hướng dẫn kết nối gửi thẻ cào — dùng cho Merchant cần gửi thẻ, kiểm tra trạng thái giao dịch và lấy biểu phí theo tài khoản.

POST https://nappay.vn/chargingws/v2 /chargingws/v2

01Tổng quan tích hợp

Endpoint chính	`https://nappay.vn/chargingws/v2`
API biểu phí	`https://nappay.vn/chargingws/v2/getfee?partner_id=YOUR_PARTNER_ID`
Method khuyến nghị	POST
Kiểu dữ liệu khuyến nghị	`application/x-www-form-urlencoded` hoặc `JSON`
Lệnh hỗ trợ	`charging`, `check`

02Điều kiện trước khi gọi API

Bạn cần có partner_id và partner_key từ khu vực Merchant trước khi gọi API.
Nếu Merchant bật IP whitelist thì request phải gửi từ đúng IP đã cấu hình.
Với command charging, request_id phải là duy nhất theo từng partner_id.
Với command check, hãy dùng lại đúng request_id của giao dịch đã gửi trước đó.
Nên gửi telco, serial, code ở dạng sạch, đúng chuẩn để hệ thống xử lý nhanh và dễ đối soát.

03Công thức tạo sign

Công thức khuyến nghị cho CHARGING

md5(partner_key . code . command . partner_id . request_id . serial . telco)

Đây là công thức nên ưu tiên dùng khi gửi thẻ.

Công thức khuyến nghị cho CHECK

md5(partner_key . command . partner_id . request_id)

Phù hợp cho lệnh kiểm tra trạng thái giao dịch.

Công thức tương thích cũ (legacy)

md5(partner_key . code . serial)

API vẫn hỗ trợ để tương thích ngược với client legacy.

04Tham số cho lệnh `charging`

POST https://nappay.vn/chargingws/v2

Trường	Bắt buộc	Ví dụ	Mô tả
command	Bắt buộc	`charging`	Lệnh gửi thẻ lên hệ thống.
partner_id	Bắt buộc	`YOUR_PARTNER_ID`	Mã Merchant của bạn.
request_id	Bắt buộc	`NAPTHE_20260403_001`	Mã giao dịch phía bạn tự sinh và không được trùng.
telco	Bắt buộc	`VIETTEL`	Mã nhà mạng.
amount	Bắt buộc	`100000`	Mệnh giá bạn khai báo.
serial	Bắt buộc	`10006139342354`	Serial của thẻ.
code	Bắt buộc	`114384960423544`	Mã nạp hoặc PIN của thẻ.
sign	Bắt buộc	`md5(...)`	Chữ ký xác thực request.

05Tham số cho lệnh `check`

POST https://nappay.vn/chargingws/v2

Trường	Bắt buộc	Ví dụ	Mô tả
command	Bắt buộc	`check`	Lệnh kiểm tra trạng thái giao dịch.
partner_id	Bắt buộc	`YOUR_PARTNER_ID`	Mã Merchant của bạn.
request_id	Bắt buộc	`NAPTHE_20260403_001`	`request_id` đã dùng ở lệnh charging.
sign	Bắt buộc	`md5(...)`	Khuyến nghị dùng `md5(partner_key . command . partner_id . request_id)`.
telco / serial / code	Không bắt buộc	`VIETTEL / 10006139342354 / 114384960423544`	Có thể truyền thêm để tương thích ngược.

06Ví dụ & code mẫu

command = charging

JSON · Request

{
    "command": "charging",
    "partner_id": "YOUR_PARTNER_ID",
    "request_id": "NAPTHE_20260403_001",
    "telco": "VIETTEL",
    "amount": "100000",
    "serial": "10006139342354",
    "code": "114384960423544",
    "sign": "a1b2c3d4e5f6..."
}

cURL

# Tạo sign trước: md5(partner_key + code + command + partner_id + request_id + serial + telco)
curl -X POST 'https://nappay.vn/chargingws/v2' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d '{
    "command": "charging",
    "partner_id": "YOUR_PARTNER_ID",
    "request_id": "NAPTHE_20260403_001",
    "telco": "VIETTEL",
    "amount": "100000",
    "serial": "10006139342354",
    "code": "114384960423544",
    "sign": "a1b2c3d4e5f6..."
  }'

# Hoặc dùng form-urlencoded:
curl -X POST 'https://nappay.vn/chargingws/v2' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'command=charging' \
  -d 'partner_id=YOUR_PARTNER_ID' \
  -d 'request_id=NAPTHE_20260403_001' \
  -d 'telco=VIETTEL' \
  -d 'amount=100000' \
  -d 'serial=10006139342354' \
  -d 'code=114384960423544' \
  -d 'sign=a1b2c3d4e5f6...'

PHP

<?php
$partner_id  = 'YOUR_PARTNER_ID';
$partner_key = 'YOUR_PARTNER_KEY';
$request_id  = 'NAPTHE_20260403_001';
$telco       = 'VIETTEL';
$amount      = '100000';
$serial      = '10006139342354';
$code        = '114384960423544';
$command     = 'charging';

// Công thức sign
$sign = md5($partner_key . $code . $command . $partner_id . $request_id . $serial . $telco);

$payload = [
    'command'    => $command,
    'partner_id' => $partner_id,
    'request_id' => $request_id,
    'telco'      => $telco,
    'amount'     => $amount,
    'serial'     => $serial,
    'code'       => $code,
    'sign'       => $sign,
];

$ch = curl_init('https://nappay.vn/chargingws/v2');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['Content-Type: application/json'],
    CURLOPT_POSTFIELDS     => json_encode($payload),
    CURLOPT_TIMEOUT        => 30,
]);
$response = curl_exec($ch);
curl_close($ch);
$result = json_decode($response, true);
print_r($result);

Python

import hashlib
import requests
import json

PARTNER_ID  = "YOUR_PARTNER_ID"
PARTNER_KEY = "YOUR_PARTNER_KEY"
REQUEST_ID  = "NAPTHE_20260403_001"
TELCO       = "VIETTEL"
AMOUNT      = "100000"
SERIAL      = "10006139342354"
CODE        = "114384960423544"
COMMAND     = "charging"

# Tạo sign
raw = PARTNER_KEY + CODE + COMMAND + PARTNER_ID + REQUEST_ID + SERIAL + TELCO
sign = hashlib.md5(raw.encode()).hexdigest()

payload = {
    "command": COMMAND,
    "partner_id": PARTNER_ID,
    "request_id": REQUEST_ID,
    "telco": TELCO,
    "amount": AMOUNT,
    "serial": SERIAL,
    "code": CODE,
    "sign": sign,
}

resp = requests.post(
    "https://nappay.vn/chargingws/v2",
    json=payload,
    headers={"Content-Type": "application/json"},
    timeout=30
)
print(resp.json())

Node.js

const crypto = require('crypto');
const axios  = require('axios');

const PARTNER_ID  = 'YOUR_PARTNER_ID';
const PARTNER_KEY = 'YOUR_PARTNER_KEY';
const REQUEST_ID  = 'NAPTHE_20260403_001';
const telco       = 'VIETTEL';
const amount      = '100000';
const serial      = '10006139342354';
const code        = '114384960423544';
const command     = 'charging';

const sign = crypto
  .createHash('md5')
  .update(`${PARTNER_KEY}${code}${command}${PARTNER_ID}${REQUEST_ID}${serial}${telco}`)
  .digest('hex');

const payload = { command, partner_id: PARTNER_ID, request_id: REQUEST_ID, telco, amount, serial, code, sign };

axios.post('https://nappay.vn/chargingws/v2', payload, {
  headers: { 'Content-Type': 'application/json' },
  timeout: 30000
}).then(res => console.log(res.data))
  .catch(err => console.error(err.response?.data || err.message));

command = check

JSON · Request

{
    "command": "check",
    "partner_id": "YOUR_PARTNER_ID",
    "request_id": "NAPTHE_20260403_001",
    "sign": "a1b2c3d4e5f6..."
}

cURL

# sign = md5(partner_key + command + partner_id + request_id)
curl -X POST 'https://nappay.vn/chargingws/v2' \
  -H 'Content-Type: application/json' \
  -d '{
    "command": "check",
    "partner_id": "YOUR_PARTNER_ID",
    "request_id": "NAPTHE_20260403_001",
    "sign": "a1b2c3d4e5f6..."
  }'

PHP

<?php
$partner_id  = 'YOUR_PARTNER_ID';
$partner_key = 'YOUR_PARTNER_KEY';
$request_id  = 'NAPTHE_20260403_001';
$command     = 'check';
$sign = md5($partner_key . $command . $partner_id . $request_id);
$payload = ['command'=>$command,'partner_id'=>$partner_id,'request_id'=>$request_id,'sign'=>$sign];
// ... gửi tương tự charging

Python

raw = PARTNER_KEY + "check" + PARTNER_ID + REQUEST_ID
sign = hashlib.md5(raw.encode()).hexdigest()
payload = {"command":"check","partner_id":PARTNER_ID,"request_id":REQUEST_ID,"sign":sign}
# requests.post(...) tương tự charging

Node.js

const sign = crypto.createHash('md5').update(`${PARTNER_KEY}check${PARTNER_ID}${REQUEST_ID}`).digest('hex');
const payload = { command: 'check', partner_id: PARTNER_ID, request_id: REQUEST_ID, sign };
// axios.post(...) tương tự charging

07Cấu trúc phản hồi

trans_id	ID giao dịch trong hệ thống.
request_id	Mã giao dịch phía Merchant gửi sang.
amount	Số tiền thực nhận về ví sau khi xử lý.
value	Mệnh giá thật được xác nhận.
declared_value	Mệnh giá Merchant khai báo lúc gửi thẻ.
telco	Nhà mạng của thẻ.
serial	Serial thẻ đã gửi.
code	Mã thẻ đã gửi.
status	Trạng thái thẻ hoặc mã lỗi API.
callback_sign	Chữ ký phản hồi: `md5(partner_key . code . serial)`.
message	Mô tả trạng thái hoặc lỗi.

08Ví dụ response

Pending

JSON · 200 OK

{
    "trans_id": 123456,
    "request_id": "NAPTHE_20260403_001",
    "amount": 0,
    "value": 0,
    "declared_value": "100000",
    "telco": "VIETTEL",
    "serial": "10006139342354",
    "code": "114384960423544",
    "status": 99,
    "callback_sign": "md5(partner_key . code . serial)",
    "message": "PENDING"
}

Success

JSON · 200 OK

{
    "trans_id": 123456,
    "request_id": "NAPTHE_20260403_001",
    "amount": 81000,
    "value": 100000,
    "declared_value": 100000,
    "telco": "VIETTEL",
    "serial": "10006139342354",
    "code": "114384960423544",
    "status": 1,
    "callback_sign": "1d55e0d5f8b4e8f815a3efbb9f5c7b21",
    "message": "VALID_CARD"
}

Error

JSON · Error

{
    "status": 102,
    "message": "Dữ liệu xác thực không hợp lệ hoặc chữ ký sign sai."
}

09Trạng thái thẻ

Status	Tên	Mô tả
99	PENDING	Thẻ đang chờ xử lý hoặc chờ nhà cung cấp trả kết quả.
1	VALID_CARD	Thẻ đúng, giao dịch thành công.
2	CARD_WRONG_VALUE	Thẻ đúng nhưng sai mệnh giá khai báo.
3	INVALID_CARD	Thẻ không hợp lệ hoặc dữ liệu thẻ sai.
4	MAINTENANCE	Nhà mạng hoặc cổng xử lý đang bảo trì.

10Mã lỗi ở mức request

Mã	Mô tả
100	Lỗi xử lý chung hoặc không thể tạo giao dịch.
101	Không tìm thấy giao dịch khi gọi command check.
102	Sai xác thực request, sai IP, sai sign hoặc dữ liệu đầu vào không hợp lệ.
103	Có ngoại lệ trong quá trình xử lý request.
104	Command không hợp lệ. Chỉ hỗ trợ charging và check.

11API biểu phí và mệnh giá hỗ trợ

Dùng endpoint sau để lấy biểu phí theo Merchant:

GET https://nappay.vn/chargingws/v2/getfee?partner_id=YOUR_PARTNER_ID

Response thường gồm các trường như telco, value, fees và penalty.

cURL · GET

curl -X GET 'https://nappay.vn/chargingws/v2/getfee?partner_id=YOUR_PARTNER_ID' \
  -H 'Accept: application/json'

Recharge API Card Partner

Hướng dẫn nạp tiền dịch vụ — dành cho Merchant cần topup, kiểm tra trạng thái, lấy số dư, danh sách sản phẩm và bảng phí.

POST https://nappay.vn/api/rechargews /api/rechargews

01Tổng quan tích hợp

Endpoint chính	`https://nappay.vn/api/rechargews`
Method khuyến nghị	POST
Kiểu dữ liệu khuyến nghị	`application/json`
Lệnh hỗ trợ	`topup`, `getstatus`, `getbalance`, `productlist`, `canceltopup`, `feetopup`

02Điều kiện trước khi gọi API

Bạn cần có partner_id và partner_key từ Merchant trước khi gọi API.
Merchant và ví thanh toán phải đang hoạt động.
IP gửi request phải nằm trong whitelist được phép.
Với lệnh topup, request_id phải là duy nhất để tránh tạo trùng giao dịch.
Nên gọi productlist trước để biết đúng service_code và cấu trúc account_info cần truyền.

03Công thức tạo sign

topup & getstatus

md5(partner_key . partner_id . command . request_id)

Dùng cho các lệnh có request_id bắt buộc.

getbalance, productlist, feetopup

md5(partner_key . partner_id . command)

Các lệnh này không dùng request_id trong bước xác thực sign.

canceltopup

md5(partner_key . partner_id . command)

Theo logic hiện tại, sign của lệnh hủy vẫn đang kiểm theo công thức này.

04Chi tiết từng lệnh

04.1Lệnh `topup`

Tạo giao dịch nạp tiền dịch vụ cho tài khoản đích.

POST https://nappay.vn/api/rechargews

Trường	Bắt buộc	Ví dụ	Mô tả
command	Bắt buộc	`topup`	Tên lệnh gọi API.
partner_id	Bắt buộc	`YOUR_PARTNER_ID`	Mã Merchant của bạn.
request_id	Bắt buộc	`TOPUP_20260403_001`	Mã giao dịch do phía bạn tự sinh.
service_code	Bắt buộc	`VINA-DATA`	Mã dịch vụ lấy từ productlist.
amount	Bắt buộc	`100000`	Giá trị cần nạp.
account_info	Bắt buộc	`{"phone":"0987654321"}`	Thông tin tài khoản nhận nạp, tùy theo sản phẩm.
sign	Bắt buộc	`md5(...)`	Chữ ký xác thực request.

JSON · Request

{
    "command": "topup",
    "partner_id": "YOUR_PARTNER_ID",
    "request_id": "TOPUP_20260403_001",
    "service_code": "VINA-DATA",
    "amount": 100000,
    "account_info": { "phone": "0987654321" },
    "sign": "a1b2c3d4e5f6..."
}

cURL

# sign = md5(partner_key + partner_id + command + request_id)
curl -X POST 'https://nappay.vn/api/rechargews' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d '{
    "command": "topup",
    "partner_id": "YOUR_PARTNER_ID",
    "request_id": "TOPUP_20260403_001",
    "service_code": "VINA-DATA",
    "amount": 100000,
    "account_info": {"phone": "0987654321"},
    "sign": "a1b2c3d4e5f6..."
  }'

PHP

<?php
$partner_id  = 'YOUR_PARTNER_ID';
$partner_key = 'YOUR_PARTNER_KEY';
$request_id  = 'TOPUP_20260403_001';
$command     = 'topup';
$sign = md5($partner_key . $partner_id . $command . $request_id);
$payload = [
    'command'      => $command,
    'partner_id'   => $partner_id,
    'request_id'   => $request_id,
    'service_code' => 'VINA-DATA',
    'amount'       => 100000,
    'account_info' => ['phone' => '0987654321'],
    'sign'         => $sign,
];
$ch = curl_init('https://nappay.vn/api/rechargews');
curl_setopt_array($ch, [
    CURLOPT_POST => true, CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
    CURLOPT_POSTFIELDS => json_encode($payload),
]);
$result = json_decode(curl_exec($ch), true);

Python

import hashlib, requests
PARTNER_ID, PARTNER_KEY = "YOUR_PARTNER_ID", "YOUR_PARTNER_KEY"
REQUEST_ID, COMMAND = "TOPUP_20260403_001", "topup"
sign = hashlib.md5((PARTNER_KEY+PARTNER_ID+COMMAND+REQUEST_ID).encode()).hexdigest()
payload = {"command":COMMAND,"partner_id":PARTNER_ID,"request_id":REQUEST_ID,
           "service_code":"VINA-DATA","amount":100000,
           "account_info":{"phone":"0987654321"},"sign":sign}
r = requests.post("https://nappay.vn/api/rechargews", json=payload)

Node.js

const sign = crypto.createHash('md5').update(`${PARTNER_KEY}${PARTNER_ID}topup${REQUEST_ID}`).digest('hex');
axios.post('https://nappay.vn/api/rechargews', {
  command: 'topup', partner_id: PARTNER_ID, request_id: REQUEST_ID,
  service_code: 'VINA-DATA', amount: 100000,
  account_info: { phone: '0987654321' }, sign
});

JSON · 200 OK

{
    "status": "success",
    "message": "Thành công",
    "data": {
        "time": "2026-04-03 14:30:00",
        "request_id": "TOPUP_20260403_001",
        "account": { "phone": "0987654321" },
        "order_code": "RE240403001",
        "pay_amount": 95000,
        "discount": 5,
        "service_code": "VINA-DATA",
        "amount": 100000,
        "status": "pending"
    }
}

04.2Lệnh `getstatus`

Tra cứu trạng thái giao dịch recharge đã tạo trước đó.

POST https://nappay.vn/api/rechargews

Trường	Bắt buộc	Ví dụ	Mô tả
command	Bắt buộc	`getstatus`	Tên lệnh gọi API.
partner_id	Bắt buộc	`YOUR_PARTNER_ID`	Mã Merchant của bạn.
request_id	Bắt buộc	`TOPUP_20260403_001`	request_id của giao dịch đã gửi.
order_code	Bắt buộc	`RE240403001`	Mã đơn hàng hệ thống trả về sau khi tạo giao dịch.
sign	Bắt buộc	`md5(...)`	Chữ ký xác thực request.

JSON · Request

{
    "command": "getstatus",
    "partner_id": "YOUR_PARTNER_ID",
    "request_id": "TOPUP_20260403_001",
    "order_code": "RE240403001",
    "sign": "md5(partner_key . partner_id . command . request_id)"
}

JSON · 200 OK

{
    "status": "success",
    "message": "Thành công",
    "data": {
        "account": { "phone": "0987654321" },
        "request_value": 100000,
        "amount": 100000,
        "request_id": "TOPUP_20260403_001",
        "order_code": "RE240403001",
        "status": "completed"
    }
}

04.3Lệnh `getbalance`

Lấy số dư ví Merchant đang dùng để thanh toán recharge.

POST https://nappay.vn/api/rechargews

Trường	Bắt buộc	Ví dụ	Mô tả
command	Bắt buộc	`getbalance`	Tên lệnh gọi API.
partner_id	Bắt buộc	`YOUR_PARTNER_ID`	Mã Merchant của bạn.
sign	Bắt buộc	`md5(...)`	Chữ ký không dùng request_id.

JSON · Request

{
    "command": "getbalance",
    "partner_id": "YOUR_PARTNER_ID",
    "sign": "md5(partner_key . partner_id . command)"
}

JSON · 200 OK

{
    "status": "success",
    "message": "Thành công",
    "data": {
        "balance": 1200000,
        "currency": "VND"
    }
}

04.4Lệnh `productlist`

Lấy danh sách dịch vụ, mệnh giá, giá bán và các option nhập liệu.

POST https://nappay.vn/api/rechargews

Trường	Bắt buộc	Ví dụ	Mô tả
command	Bắt buộc	`productlist`	Tên lệnh gọi API.
partner_id	Bắt buộc	`YOUR_PARTNER_ID`	Mã Merchant của bạn.
sign	Bắt buộc	`md5(...)`	Chữ ký không dùng request_id.

JSON · Request

{
    "command": "productlist",
    "partner_id": "YOUR_PARTNER_ID",
    "sign": "md5(partner_key . partner_id . command)"
}

JSON · 200 OK

{
    "status": "success",
    "message": "Thành công",
    "data": [
        {
            "name": "Nạp data VinaPhone",
            "service_code": "VINA-DATA",
            "items": [
                {
                    "name": "Gói 100.000đ",
                    "value": 100000,
                    "price": 95000,
                    "discount": 5
                }
            ],
            "options": [
                { "key": "phone", "name": "Số điện thoại", "type": "text" }
            ]
        }
    ]
}

Nên gọi productlist trước mỗi lần triển khai mới — danh sách dịch vụ thực tế có thể nhiều hơn ví dụ minh họa ở trên (data, ví game, nạp điện thoại trả trước/trả sau theo từng nhà mạng…).

04.5Lệnh `canceltopup`

Yêu cầu hủy giao dịch recharge khi nghiệp vụ cho phép.

POST https://nappay.vn/api/rechargews

Trường	Bắt buộc	Ví dụ	Mô tả
command	Bắt buộc	`canceltopup`	Tên lệnh gọi API.
partner_id	Bắt buộc	`YOUR_PARTNER_ID`	Mã Merchant của bạn.
request_id	Bắt buộc	`TOPUP_20260403_001`	request_id của giao dịch cần hủy.
order_code	Bắt buộc	`RE240403001`	Mã đơn hàng cần hủy.
sign	Bắt buộc	`md5(...)`	Theo logic hiện tại, sign kiểm theo `md5(partner_key . partner_id . command)`.

JSON · Request

{
    "command": "canceltopup",
    "partner_id": "YOUR_PARTNER_ID",
    "request_id": "TOPUP_20260403_001",
    "order_code": "RE240403001",
    "sign": "md5(partner_key . partner_id . command)"
}

JSON · 200 OK

{
    "status": "success",
    "message": "Thành công",
    "data": {
        "request_id": "TOPUP_20260403_001",
        "order_code": "RE240403001",
        "status": "canceled"
    }
}

04.6Lệnh `feetopup`

Lấy bảng giá và chiết khấu theo Merchant.

POST https://nappay.vn/api/rechargews

Trường	Bắt buộc	Ví dụ	Mô tả
command	Bắt buộc	`feetopup`	Tên lệnh gọi API.
partner_id	Bắt buộc	`YOUR_PARTNER_ID`	Mã Merchant của bạn.
sign	Bắt buộc	`md5(...)`	Chữ ký không dùng request_id.

JSON · Request

{
    "command": "feetopup",
    "partner_id": "YOUR_PARTNER_ID",
    "sign": "md5(partner_key . partner_id . command)"
}

JSON · 200 OK

{
    "status": "success",
    "message": "Thành công",
    "data": [
        {
            "key": "VINA-DATA",
            "value": 100000,
            "price": 95000,
            "discount": 5
        }
    ]
}

05Ghi chú về phản hồi

Recharge API trả về khung JSON gồm status, message và data.
Trường status có thể là chuỗi hoặc số nguyên tùy nhánh xử lý.
Nên xử lý luồng nghiệp vụ theo status, không chỉ dựa vào message.

06Trạng thái thường gặp

Mã / Status	Tên	Mô tả
success	—	Request hợp lệ và xử lý thành công.
command_invalid	command_invalid	Lệnh command không nằm trong danh sách hỗ trợ.
wrong_post_data	wrong_post_data	Thiếu hoặc sai dữ liệu đầu vào bắt buộc.
product_not_found	product_not_found	Không tìm thấy service_code tương ứng.
account_info_not_correct	account_info_not_correct	account_info không đúng định dạng mong muốn.
payment_fail	payment_fail	Thanh toán ví thất bại.
order_not_found	order_not_found	Không tìm thấy đơn hàng cần tra cứu hoặc hủy.
wrong_signature	wrong_signature	Sai chữ ký sign.
114	—	IP gọi API không nằm trong whitelist cho phép.

07Card Partner API — Ví dụ thực tế (legacy)

Các ví dụ dưới đây lấy từ tài liệu Card Partner API cũ, endpoint vẫn dùng https://nappay.vn/api/rechargews.

Lấy trạng thái giao dịch (getstatus)

Tra cứu trạng thái đơn hàng đã tạo. Chữ ký: md5(partner_key + partner_id + command + request_id)

Request

{
    "partner_id": "3681148751",
    "command": "getstatus",
    "request_id": "116",
    "order_code": "R625931CC50F71",
    "sign": "43567456546dfs32465asdkg123"
}

cURL

curl --location 'https://nappay.vn/api/rechargews' \
  --header 'Content-Type: application/json' \
  --data '{
    "partner_id": "3681148751",
    "command": "getstatus",
    "request_id": "116",
    "order_code": "R625931CC50F71",
    "sign": "43567456546dfs32465asdkg123"
  }'

JSON · 200 OK

{
    "status": "success",
    "data": {
        "account": { "phone": "0943793984" },
        "request_value": 10000,
        "amount": 10000,
        "request_id": "116",
        "order_code": "R625931CC50F71",
        "status": "pending"
    }
}

Lấy danh sách sản phẩm (productlist)

Lấy toàn bộ sản phẩm đang bán. Chữ ký: md5(partner_key + partner_id + command)

Request

{
    "partner_id": "45974491332",
    "command": "productlist",
    "sign": "43567456546dfs32465asdkg123"
}

cURL

curl --location 'https://nappay.vn/api/rechargews' \
  --header 'Content-Type: application/json' \
  --data '{
    "partner_id": "3681148751",
    "command": "productlist",
    "sign": "43567456546dfs32465asdkg123"
  }'

Response productlist trả về mảng sản phẩm gồm nạp Viettel/Vina/Mobi trả trước-trả sau, game (Avatar, Ninja, Ngọc Rồng…) với service_code, items (mệnh giá, giá, chiết khấu).

Lấy số dư (getbalance)

Chữ ký: md5(partner_key + partner_id + command)

Request

{
    "partner_id": "3681148751",
    "command": "getbalance",
    "sign": "43567456546dfs32465asdkg123"
}

cURL

curl --location 'https://nappay.vn/api/rechargews' \
  --header 'Content-Type: application/json' \
  --data '{
    "partner_id": "3681148751",
    "command": "getbalance",
    "sign": "43567456546dfs32465asdkg123"
  }'

JSON · 200 OK

{
    "status": "success",
    "data": {
        "balance": 85465019,
        "currency": "VND"
    }
}

Softcard API

Hướng dẫn mua mã thẻ điện tử — mua card, tải lại đơn, kiểm tra tồn kho, lấy số dư ví và danh sách sản phẩm.

POST https://nappay.vn/api/cardws /api/cardws

01Tổng quan tích hợp

Endpoint chính	`https://nappay.vn/api/cardws`
API danh sách sản phẩm	`https://nappay.vn/api/cardws/products?partner_id=YOUR_PARTNER_ID`
Method	POST cho `/api/cardws`, GET cho `/api/cardws/products`
Kiểu dữ liệu khuyến nghị	`application/json`
Lệnh hỗ trợ	`buycard`, `redownload`, `checkavailable`, `getbalance`

02Điều kiện trước khi gọi API

Merchant phải được cấp quyền dùng module Softcard và đang hoạt động.
Nếu bật checksign thì sign phải khớp công thức của từng lệnh.
IP gọi API phải nằm trong whitelist Merchant hoặc whitelist hệ thống.
Với buycard và redownload, request_id phải là mã riêng để tránh trùng đơn.
wallet_number phải là ví đúng Merchant và còn hoạt động.

03Công thức tạo sign

buycard & redownload

md5(partner_key . partner_id . command . request_id)

Áp dụng cho các lệnh có request_id bắt buộc.

checkavailable & getbalance

md5(partner_key . partner_id . command)

Dùng cho các lệnh không cần request_id.

04Lệnh `buycard`

Mua mã thẻ điện tử và nhận card ngay nếu hệ thống xử lý thành công.

POST https://nappay.vn/api/cardws

Trường	Bắt buộc	Ví dụ	Mô tả
command	Bắt buộc	`buycard`	Tên lệnh gọi API.
partner_id	Bắt buộc	`YOUR_PARTNER_ID`	Mã Merchant của bạn.
request_id	Bắt buộc	`CARD_20260403_001`	Mã giao dịch do phía bạn tự sinh.
service_code	Bắt buộc	`VIETTEL`	Mã sản phẩm cần mua.
value	Bắt buộc	`100000`	Mệnh giá thẻ.
qty	Bắt buộc	`2`	Số lượng thẻ cần mua, phải là số nguyên dương.
wallet_number	Bắt buộc	`VND123456789`	Ví thanh toán của Merchant.
sign	Bắt buộc	`md5(...)`	Chữ ký xác thực request.

JSON · Request

{
    "command": "buycard",
    "partner_id": "YOUR_PARTNER_ID",
    "request_id": "CARD_20260403_001",
    "service_code": "VIETTEL",
    "value": 100000,
    "qty": 2,
    "wallet_number": "VND123456789",
    "sign": "a1b2c3d4e5f6..."
}

cURL

# sign = md5(partner_key + partner_id + command + request_id)
curl -X POST 'https://nappay.vn/api/cardws' \
  -H 'Content-Type: application/json' \
  -d '{
    "command": "buycard",
    "partner_id": "YOUR_PARTNER_ID",
    "request_id": "CARD_20260403_001",
    "service_code": "VIETTEL",
    "value": 100000,
    "qty": 2,
    "wallet_number": "VND123456789",
    "sign": "a1b2c3d4e5f6..."
  }'

PHP

<?php
$partner_id  = 'YOUR_PARTNER_ID';
$partner_key = 'YOUR_PARTNER_KEY';
$request_id  = 'CARD_20260403_001';
$command     = 'buycard';
$sign = md5($partner_key . $partner_id . $command . $request_id);
$payload = [
    'command'       => $command,
    'partner_id'    => $partner_id,
    'request_id'    => $request_id,
    'service_code'  => 'VIETTEL',
    'value'         => 100000,
    'qty'           => 2,
    'wallet_number' => 'VND123456789',
    'sign'          => $sign,
];
// curl POST https://nappay.vn/api/cardws

Python

sign = hashlib.md5((PARTNER_KEY+PARTNER_ID+"buycard"+REQUEST_ID).encode()).hexdigest()
payload = {"command":"buycard","partner_id":PARTNER_ID,"request_id":REQUEST_ID,
           "service_code":"VIETTEL","value":100000,"qty":2,
           "wallet_number":"VND123456789","sign":sign}
requests.post("https://nappay.vn/api/cardws", json=payload)

Node.js

const sign = crypto.createHash('md5').update(`${PARTNER_KEY}${PARTNER_ID}buycard${REQUEST_ID}`).digest('hex');
axios.post('https://nappay.vn/api/cardws', {
  command: 'buycard', partner_id: PARTNER_ID, request_id: REQUEST_ID,
  service_code: 'VIETTEL', value: 100000, qty: 2,
  wallet_number: 'VND123456789', sign
});

JSON · 200 OK

{
    "status": 1,
    "message": "Mua thẻ thành công",
    "data": {
        "cards": [
            {
                "name": "Thẻ Viettel 100.000",
                "serial": "10006139342354",
                "code": "114384960423544",
                "expired": "2027-12-31"
            }
        ],
        "request_id": "CARD_20260403_001",
        "order_code": "SC240403001"
    }
}

05Lệnh `redownload`

Tải lại thông tin card của đơn hàng đã mua trước đó.

POST https://nappay.vn/api/cardws

Trường	Bắt buộc	Ví dụ	Mô tả
command	Bắt buộc	`redownload`	Tên lệnh gọi API.
partner_id	Bắt buộc	`YOUR_PARTNER_ID`	Mã Merchant của bạn.
request_id	Bắt buộc	`CARD_20260403_001`	request_id đã dùng khi mua thẻ.
sign	Bắt buộc	`md5(...)`	Chữ ký xác thực request.

JSON · Request

{
    "command": "redownload",
    "partner_id": "YOUR_PARTNER_ID",
    "request_id": "CARD_20260403_001",
    "sign": "md5(partner_key . partner_id . command . request_id)"
}

JSON · 200 OK

{
    "status": 1,
    "message": "Mua thẻ thành công",
    "data": {
        "cards": [
            {
                "name": "Thẻ Viettel 100.000",
                "serial": "10006139342354",
                "code": "114384960423544",
                "expired": "2027-12-31"
            }
        ],
        "request_id": "CARD_20260403_001",
        "order_code": "SC240403001"
    }
}

06Lệnh `checkavailable`

Kiểm tra tồn kho sản phẩm trước khi mua.

POST https://nappay.vn/api/cardws

Trường	Bắt buộc	Ví dụ	Mô tả
command	Bắt buộc	`checkavailable`	Tên lệnh gọi API.
partner_id	Bắt buộc	`YOUR_PARTNER_ID`	Mã Merchant của bạn.
service_code	Bắt buộc	`VIETTEL`	Mã sản phẩm cần kiểm tra.
value	Bắt buộc	`100000`	Mệnh giá thẻ cần kiểm tra.
qty	Bắt buộc	`5`	Số lượng muốn kiểm tra tồn kho.
sign	Bắt buộc	`md5(...)`	Chữ ký xác thực request.

JSON · Request

{
    "command": "checkavailable",
    "partner_id": "YOUR_PARTNER_ID",
    "service_code": "VIETTEL",
    "value": 100000,
    "qty": 5,
    "sign": "md5(partner_key . partner_id . command)"
}

JSON · 200 OK

{
    "stock_available": true,
    "VIETTEL-100000": "Còn hàng"
}

07Lệnh `getbalance`

Lấy số dư của ví Merchant đang dùng để mua card.

POST https://nappay.vn/api/cardws

Trường	Bắt buộc	Ví dụ	Mô tả
command	Bắt buộc	`getbalance`	Tên lệnh gọi API.
partner_id	Bắt buộc	`YOUR_PARTNER_ID`	Mã Merchant của bạn.
wallet_number	Bắt buộc	`VND123456789`	Ví cần lấy số dư.
sign	Bắt buộc	`md5(...)`	Chữ ký xác thực request.

JSON · Request

{
    "command": "getbalance",
    "partner_id": "YOUR_PARTNER_ID",
    "wallet_number": "VND123456789",
    "sign": "md5(partner_key . partner_id . command)"
}

JSON · 200 OK

{
    "balance": 2500000,
    "currency_code": "VND"
}

08API danh sách sản phẩm

Dùng endpoint sau để lấy danh sách sản phẩm và mệnh giá hỗ trợ:

GET https://nappay.vn/api/cardws/products?partner_id=YOUR_PARTNER_ID

cURL · GET

curl -X GET 'https://nappay.vn/api/cardws/products?partner_id=YOUR_PARTNER_ID' \
  -H 'Accept: application/json'

JSON · 200 OK

[
    {
        "name": "Viettel",
        "slug": "viettel",
        "service_code": "VIETTEL",
        "image": "/uploads/softcard/viettel.png",
        "cardvalue": [
            { "service_code": "VIETTEL", "value": 100000, "id": 10 }
        ]
    }
]

06Ghi chú về phản hồi

buycard và redownload trả về JSON theo khung status, message, data.
checkavailable trả về JSON trực tiếp gồm stock_available và thông tin tồn kho.
getbalance trả về JSON trực tiếp gồm balance và currency_code.
API /api/cardws/products trả về mảng sản phẩm JSON trực tiếp.

07Bảng mã trạng thái

Mã	Mô tả
1	Mua thẻ thành công hoặc tải lại card thành công.
2	Đơn hàng đang chờ xử lý.
3	Đơn hàng đã hủy và hoàn tiền.
102	Số dư ví không đủ.
109	request_id đã tồn tại.
114	Merchant gọi sai IP đăng ký.
116	Sai chữ ký sign.
118	Sản phẩm đã hết.
129	Đơn hàng không tồn tại.
130	Lỗi lấy thẻ từ nguồn cung cấp.

Tài liệu tích hợp API Nappay

Charging API v2 API mới

01Tổng quan tích hợp

02Điều kiện trước khi gọi API

03Công thức tạo sign

04Tham số cho lệnh charging

05Tham số cho lệnh check

06Ví dụ & code mẫu

command = charging

command = check

07Cấu trúc phản hồi

08Ví dụ response

Pending

Success

Error

09Trạng thái thẻ

10Mã lỗi ở mức request

11API biểu phí và mệnh giá hỗ trợ

Recharge API Card Partner

01Tổng quan tích hợp

02Điều kiện trước khi gọi API

03Công thức tạo sign

04Chi tiết từng lệnh

04.1Lệnh topup

04.2Lệnh getstatus

04.3Lệnh getbalance

04.4Lệnh productlist

04.5Lệnh canceltopup

04.6Lệnh feetopup

05Ghi chú về phản hồi

06Trạng thái thường gặp

07Card Partner API — Ví dụ thực tế (legacy)

Lấy trạng thái giao dịch (getstatus)

Lấy danh sách sản phẩm (productlist)

Lấy số dư (getbalance)

Softcard API

01Tổng quan tích hợp

02Điều kiện trước khi gọi API

03Công thức tạo sign

04Lệnh buycard

05Lệnh redownload

06Lệnh checkavailable

07Lệnh getbalance

08API danh sách sản phẩm

06Ghi chú về phản hồi

07Bảng mã trạng thái

04Tham số cho lệnh `charging`

05Tham số cho lệnh `check`

04.1Lệnh `topup`

04.2Lệnh `getstatus`

04.3Lệnh `getbalance`

04.4Lệnh `productlist`

04.5Lệnh `canceltopup`

04.6Lệnh `feetopup`

04Lệnh `buycard`

05Lệnh `redownload`

06Lệnh `checkavailable`

07Lệnh `getbalance`