Thu tiền

Yêu cầu thanh toán VietQR, bill POS, việc cần xử lý của thu tiền và mẫu mã đơn riêng của công ty. Không giữ tiền: paid chỉ khi giao dịch đã xác thực.

Endpoint

Method	Path	Tóm tắt	Quyền	Nhóm tốc độ	Tương tác
GET	/v1/collect/bills	Danh sách bill	payment_request.read	read	Scalar
POST	/v1/collect/bills	Tạo bill và QR động cho POS	collect.bill.create	collect	Scalar
POST	/v1/collect/bills/{bill_ref}:cancel	Huỷ bill	collect.bill.create	write	Scalar
POST	/v1/collect/bills/{bill_ref}:mark-cash	Bill đã trả tiền mặt	collect.bill.create	write	Scalar
GET	/v1/payment-requests	Danh sách yêu cầu thanh toán	payment_request.read	read	Scalar
POST	/v1/payment-requests	Tạo yêu cầu thanh toán	payment_request.create	collect	Scalar
GET	/v1/payment-requests/{id}	Chi tiết yêu cầu thanh toán	payment_request.read	read	Scalar
PATCH	/v1/payment-requests/{id}	Sửa yêu cầu thanh toán	payment_request.update	write	Scalar
GET	/v1/payment-requests/{id}/timeline	Nhật ký yêu cầu thanh toán	payment_request.read	read	Scalar
GET	/v1/payment-requests/{id}/transactions	Giao dịch đã khớp với yêu cầu	payment_request.read	read	Scalar
POST	/v1/payment-requests/{id}:cancel	Huỷ yêu cầu thanh toán	payment_request.cancel	write	Scalar
POST	/v1/payment-requests/{id}:receipt	Gửi biên nhận	payment_request.remind	write	Scalar
POST	/v1/payment-requests/{id}:remind	Nhắc thanh toán	payment_request.remind	write	Scalar
POST	/v1/payment-requests/{id}:resend-remainder	Gửi phần còn lại	payment_request.update	write	Scalar
POST	/v1/payment-requests/{id}:resolve-overpay	Đánh dấu đã xử lý tiền thừa	payment_request.resolve_overpay	write	Scalar

Chi tiết endpoint

GET /v1/collect/bills

Danh sách bill

Mới nhất trước; lọc theo quầy hoặc ca.

Quyền: payment_request.read Scope: collect:read

• Nhóm tốc độ: read
• Phản hồi thành công 200: Danh sách bill. — BillList, application/json
• Mã lỗi riêng của endpoint: invalid_cursor

Tham số

Tên	Vị trí	Bắt buộc	Kiểu	Mô tả
limit	query	Không	integer	Số phần tử mỗi trang (1–100, mặc định 20).
cursor	query	Không	Cursor	Con trỏ phân trang mờ (cur_…) lấy từ next_cursor; không tự tạo hay sửa.
company_id	query	Không	OrgId	Mã công ty / tổ chức (org_…).
counter	query	Không	CounterId	Mã quầy thu ngân (ctr_…).
shift	query	Không	string	—
state	query	Không	string	—

curl

curl -sS -X GET "https://api.dongtien.pro/v1/collect/bills" \
  -H "Authorization: Bearer $DT_API_KEY"

TypeScript

import { createClient } from "@dongtien/sdk";

const dt = createClient({ apiKey: process.env.DT_API_KEY! });

const { data } = await dt.GET("/v1/collect/bills");

Python

import os

from dongtien import DongTien
from dongtien_api.api.thu_tien import list_collect_bills

with DongTien(api_key=os.environ["DT_API_KEY"]) as dt:
    result = list_collect_bills.sync(client=dt.client)

Mở trong tài liệu tương tác

POST /v1/collect/bills

Tạo bill và QR động cho POS

Tra cửa hàng/quầy theo slug; ca đang mở của quầy nhận bill. Gửi lại cùng bill_ref và cùng nội dung trả lại bill cũ (Idempotency-Replayed); cùng bill_ref khác nội dung trả 422. Cần Idempotency-Key (nên bằng bill_ref). Khi bill được trả đủ bằng tiền đã xác thực phát collect.bill.paid.

Quyền: collect.bill.create Scope: collect:write Idempotency-Key: bắt buộc

• Nhóm tốc độ: collect
• Nội dung yêu cầu: CreateBill (application/json, bắt buộc)
• Phản hồi thành công 201: Bill và yêu cầu thanh toán (QR). — Bill, application/json
• Mã lỗi riêng của endpoint: idempotency_key_required, conflict, idempotency_in_flight, idempotency_key_reused

Tham số

Tên	Vị trí	Bắt buộc	Kiểu	Mô tả
idempotency-key	header	Không	string	Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ. Bắt buộc ở máy chủ (thiếu → 400 idempotency_key_required); SDK tự sinh.

curl

curl -sS -X POST "https://api.dongtien.pro/v1/collect/bills" \
  -H "Authorization: Bearer $DT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "store": "q1-nguyen-hue",
  "counter": "quay-1",
  "bill_ref": "HD-000123",
  "amount": 185000
}'

TypeScript

import { createClient } from "@dongtien/sdk";

const dt = createClient({ apiKey: process.env.DT_API_KEY! });

const { data } = await dt.POST("/v1/collect/bills", {
  params: {
    header: { "idempotency-key": crypto.randomUUID() },
  },
  body: {
    "store": "q1-nguyen-hue",
    "counter": "quay-1",
    "bill_ref": "HD-000123",
    "amount": 185000
  },
});

Python

import os

from dongtien import DongTien
from dongtien_api.api.thu_tien import create_collect_bill
from dongtien_api.models import CreateBill

with DongTien(api_key=os.environ["DT_API_KEY"]) as dt:
    result = create_collect_bill.sync(
        client=dt.client,
        body=CreateBill.from_dict({
            "store": "q1-nguyen-hue",
            "counter": "quay-1",
            "bill_ref": "HD-000123",
            "amount": 185000,
        }),
    )

Mở trong tài liệu tương tác

POST /v1/collect/bills/{bill_ref}:cancel

Huỷ bill

Bill đang waiting chuyển cancelled và yêu cầu thanh toán của nó cũng bị huỷ. Bill đã paid/cash_paid trả 409 conflict. POS sửa số tiền: huỷ rồi tạo bill_ref mới.

Quyền: collect.bill.create Scope: collect:write Idempotency-Key: tuỳ chọn

• Nhóm tốc độ: write
• Phản hồi thành công 200: Bill sau khi huỷ. — Bill, application/json
• Mã lỗi riêng của endpoint: resource_not_found, conflict, idempotency_in_flight, idempotency_key_reused

Tham số

Tên	Vị trí	Bắt buộc	Kiểu	Mô tả
bill_ref	path	Có	string	—
counter	query	Có	string	Quầy của bill (bill_ref chỉ duy nhất trong một quầy).
idempotency-key	header	Không	string	Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ.

curl

curl -sS -X POST "https://api.dongtien.pro/v1/collect/bills/$BILL_REF:cancel?counter=ctr_0f5k2m9q4h7t3n8r6v1w0x5yz0" \
  -H "Authorization: Bearer $DT_API_KEY"

TypeScript

import { createClient } from "@dongtien/sdk";

const dt = createClient({ apiKey: process.env.DT_API_KEY! });

const { data } = await dt.POST("/v1/collect/bills/{bill_ref}:cancel", {
  params: {
    path: { "bill_ref": "<bill_ref>" },
    query: { "counter": "ctr_0f5k2m9q4h7t3n8r6v1w0x5yz0" },
  },
});

Python

import os

from dongtien import DongTien
from dongtien_api.api.thu_tien import cancel_collect_bill

with DongTien(api_key=os.environ["DT_API_KEY"]) as dt:
    result = cancel_collect_bill.sync(
        bill_ref="<bill_ref>",
        client=dt.client,
        counter="ctr_0f5k2m9q4h7t3n8r6v1w0x5yz0",
    )

Mở trong tài liệu tương tác

POST /v1/collect/bills/{bill_ref}:mark-cash

Bill đã trả tiền mặt

Bill waiting chuyển cash_paid; yêu cầu thanh toán bị huỷ với lý do cash. Tiền chuyển khoản đến sau đó vào việc cần xử lý.

Quyền: collect.bill.create Scope: collect:write Idempotency-Key: tuỳ chọn

• Nhóm tốc độ: write
• Phản hồi thành công 200: Bill sau khi đánh dấu. — Bill, application/json
• Mã lỗi riêng của endpoint: resource_not_found, conflict, idempotency_in_flight, idempotency_key_reused

Tham số

Tên	Vị trí	Bắt buộc	Kiểu	Mô tả
bill_ref	path	Có	string	—
counter	query	Có	string	Quầy của bill (bill_ref chỉ duy nhất trong một quầy).
idempotency-key	header	Không	string	Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ.

curl

curl -sS -X POST "https://api.dongtien.pro/v1/collect/bills/$BILL_REF:mark-cash?counter=ctr_0f5k2m9q4h7t3n8r6v1w0x5yz0" \
  -H "Authorization: Bearer $DT_API_KEY"

TypeScript

import { createClient } from "@dongtien/sdk";

const dt = createClient({ apiKey: process.env.DT_API_KEY! });

const { data } = await dt.POST("/v1/collect/bills/{bill_ref}:mark-cash", {
  params: {
    path: { "bill_ref": "<bill_ref>" },
    query: { "counter": "ctr_0f5k2m9q4h7t3n8r6v1w0x5yz0" },
  },
});

Python

import os

from dongtien import DongTien
from dongtien_api.api.thu_tien import mark_collect_bill_cash

with DongTien(api_key=os.environ["DT_API_KEY"]) as dt:
    result = mark_collect_bill_cash.sync(
        bill_ref="<bill_ref>",
        client=dt.client,
        counter="ctr_0f5k2m9q4h7t3n8r6v1w0x5yz0",
    )

Mở trong tài liệu tương tác

GET /v1/payment-requests

Danh sách yêu cầu thanh toán

Mới nhất trước. view=attention gồm yêu cầu provisional, short, over chưa xử lý và expired có tiền về muộn.

Quyền: payment_request.read Scope: collect:read

• Nhóm tốc độ: read
• Phản hồi thành công 200: Danh sách yêu cầu. — PaymentRequestList, application/json
• Mã lỗi riêng của endpoint: invalid_cursor

Tham số

Tên	Vị trí	Bắt buộc	Kiểu	Mô tả
limit	query	Không	integer	Số phần tử mỗi trang (1–100, mặc định 20).
cursor	query	Không	Cursor	Con trỏ phân trang mờ (cur_…) lấy từ next_cursor; không tự tạo hay sửa.
company_id	query	Không	OrgId	Mã công ty / tổ chức (org_…).
state	query	Không	string	—
view	query	Không	string	—
store_id	query	Không	StoreId	Mã cửa hàng (sto_…).
counter_id	query	Không	CounterId	Mã quầy thu ngân (ctr_…).
account_id	query	Không	AccountId	Mã tài khoản ngân hàng (acc_…).
q	query	Không	string	Tìm theo mã DTP…, ref hoặc tên khách.
from	query	Không	Timestamp | Date	Tạo từ thời điểm này (giờ Việt Nam nếu là ngày).
to	query	Không	Timestamp | Date	—

curl

curl -sS -X GET "https://api.dongtien.pro/v1/payment-requests" \
  -H "Authorization: Bearer $DT_API_KEY"

TypeScript

import { createClient } from "@dongtien/sdk";

const dt = createClient({ apiKey: process.env.DT_API_KEY! });

const { data } = await dt.GET("/v1/payment-requests");

Python

import os

from dongtien import DongTien
from dongtien_api.api.thu_tien import list_payment_requests

with DongTien(api_key=os.environ["DT_API_KEY"]) as dt:
    result = list_payment_requests.sync(client=dt.client)

MCP

Công cụ list_payment_requests, scope collect:read.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_payment_requests",
    "arguments": {}
  }
}

Mở trong tài liệu tương tác

POST /v1/payment-requests

Tạo yêu cầu thanh toán

Sinh mã DTP…, dựng VietQR (số tiền khoá khi có amount) và trang pay_url. Cần Idempotency-Key. Tài khoản chưa có kênh xác thực được trả warnings: ["ACCOUNT_PROVISIONAL_ONLY"]: tiền về sẽ ở trạng thái tạm tính và yêu cầu không tự chuyển paid (D36). Không giữ tiền.

Quyền: payment_request.create Scope: collect:write Idempotency-Key: bắt buộc

• Nhóm tốc độ: collect
• Nội dung yêu cầu: CreatePaymentRequest (application/json, bắt buộc)
• Phản hồi thành công 201: Yêu cầu đã tạo. — PaymentRequest, application/json
• Mã lỗi riêng của endpoint: idempotency_key_required, conflict, idempotency_in_flight, idempotency_key_reused

Tham số

Tên	Vị trí	Bắt buộc	Kiểu	Mô tả
idempotency-key	header	Không	string	Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ. Bắt buộc ở máy chủ (thiếu → 400 idempotency_key_required); SDK tự sinh.

curl

curl -sS -X POST "https://api.dongtien.pro/v1/payment-requests" \
  -H "Authorization: Bearer $DT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "account": "acb_4521",
  "amount": 250000,
  "ref": "DH-10492"
}'

TypeScript

import { createClient } from "@dongtien/sdk";

const dt = createClient({ apiKey: process.env.DT_API_KEY! });

const { data } = await dt.POST("/v1/payment-requests", {
  params: {
    header: { "idempotency-key": crypto.randomUUID() },
  },
  body: {
    "account": "acb_4521",
    "amount": 250000,
    "ref": "DH-10492"
  },
});

Python

import os

from dongtien import DongTien
from dongtien_api.api.thu_tien import create_payment_request
from dongtien_api.models import CreatePaymentRequest

with DongTien(api_key=os.environ["DT_API_KEY"]) as dt:
    result = create_payment_request.sync(
        client=dt.client,
        body=CreatePaymentRequest.from_dict({
            "account": "acb_4521",
            "amount": 250000,
            "ref": "DH-10492",
        }),
    )

MCP

Công cụ create_payment_request, scope collect:write.

Mở trong tài liệu tương tác

GET /v1/payment-requests/{id}

Chi tiết yêu cầu thanh toán

Tra theo pr_… hoặc mã nội dung DTP….

Quyền: payment_request.read Scope: collect:read

• Nhóm tốc độ: read
• Phản hồi thành công 200: Yêu cầu. — PaymentRequest, application/json
• Mã lỗi riêng của endpoint: resource_not_found

Tham số

Tên	Vị trí	Bắt buộc	Kiểu	Mô tả
id	path	Có	PaymentRequestRef	Mã yêu cầu pr_… hoặc mã nội dung DTP….

curl

curl -sS -X GET "https://api.dongtien.pro/v1/payment-requests/$ID" \
  -H "Authorization: Bearer $DT_API_KEY"

TypeScript

import { createClient } from "@dongtien/sdk";

const dt = createClient({ apiKey: process.env.DT_API_KEY! });

const { data } = await dt.GET("/v1/payment-requests/{id}", {
  params: {
    path: { "id": "pr_0f5k2m9q4h7t3n8r6v1w0x5yzd" },
  },
});

Python

import os

from dongtien import DongTien
from dongtien_api.api.thu_tien import get_payment_request

with DongTien(api_key=os.environ["DT_API_KEY"]) as dt:
    result = get_payment_request.sync(id="pr_0f5k2m9q4h7t3n8r6v1w0x5yzd", client=dt.client)

Mở trong tài liệu tương tác

PATCH /v1/payment-requests/{id}

Sửa yêu cầu thanh toán

Chỉ khi yêu cầu còn waiting và chưa có giao dịch nào gắn; mã DTP… và tài khoản không bao giờ đổi. Đổi số tiền sinh lại QR. Trái điều kiện trả 409 conflict.

Quyền: payment_request.update Scope: collect:write Idempotency-Key: tuỳ chọn

• Nhóm tốc độ: write
• Nội dung yêu cầu: UpdatePaymentRequest (application/json, bắt buộc)
• Phản hồi thành công 200: Yêu cầu sau khi sửa. — PaymentRequest, application/json
• Mã lỗi riêng của endpoint: resource_not_found, conflict, idempotency_in_flight, idempotency_key_reused

Tham số

Tên	Vị trí	Bắt buộc	Kiểu	Mô tả
id	path	Có	PaymentRequestRef	Mã yêu cầu pr_… hoặc mã nội dung DTP….
idempotency-key	header	Không	string	Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ.

curl

curl -sS -X PATCH "https://api.dongtien.pro/v1/payment-requests/$ID" \
  -H "Authorization: Bearer $DT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "amount": 300000,
  "expires_in_minutes": 60
}'

TypeScript

import { createClient } from "@dongtien/sdk";

const dt = createClient({ apiKey: process.env.DT_API_KEY! });

const { data } = await dt.PATCH("/v1/payment-requests/{id}", {
  params: {
    path: { "id": "pr_0f5k2m9q4h7t3n8r6v1w0x5yzd" },
  },
  body: {
    "amount": 300000,
    "expires_in_minutes": 60
  },
});

Python

import os

from dongtien import DongTien
from dongtien_api.api.thu_tien import update_payment_request
from dongtien_api.models import UpdatePaymentRequest

with DongTien(api_key=os.environ["DT_API_KEY"]) as dt:
    result = update_payment_request.sync(
        id="pr_0f5k2m9q4h7t3n8r6v1w0x5yzd",
        client=dt.client,
        body=UpdatePaymentRequest.from_dict({
            "amount": 300000,
            "expires_in_minutes": 60,
        }),
    )

Mở trong tài liệu tương tác

GET /v1/payment-requests/{id}/timeline

Nhật ký yêu cầu thanh toán

Chỉ thêm, theo thời gian tăng dần.

Quyền: payment_request.read Scope: collect:read

• Nhóm tốc độ: read
• Phản hồi thành công 200: Các dòng nhật ký. — PaymentRequestEventList, application/json
• Mã lỗi riêng của endpoint: resource_not_found

Tham số

Tên	Vị trí	Bắt buộc	Kiểu	Mô tả
id	path	Có	PaymentRequestRef	Mã yêu cầu pr_… hoặc mã nội dung DTP….

curl

curl -sS -X GET "https://api.dongtien.pro/v1/payment-requests/$ID/timeline" \
  -H "Authorization: Bearer $DT_API_KEY"

TypeScript

import { createClient } from "@dongtien/sdk";

const dt = createClient({ apiKey: process.env.DT_API_KEY! });

const { data } = await dt.GET("/v1/payment-requests/{id}/timeline", {
  params: {
    path: { "id": "pr_0f5k2m9q4h7t3n8r6v1w0x5yzd" },
  },
});

Python

import os

from dongtien import DongTien
from dongtien_api.api.thu_tien import list_payment_request_timeline

with DongTien(api_key=os.environ["DT_API_KEY"]) as dt:
    result = list_payment_request_timeline.sync(id="pr_0f5k2m9q4h7t3n8r6v1w0x5yzd", client=dt.client)

Mở trong tài liệu tương tác

GET /v1/payment-requests/{id}/transactions

Giao dịch đã khớp với yêu cầu

Gồm cả giao dịch tạm tính (chưa tính vào received_verified).

Quyền: payment_request.read Scope: collect:read

• Nhóm tốc độ: read
• Phản hồi thành công 200: Giao dịch khớp. — PaymentRequestTransactionList, application/json
• Mã lỗi riêng của endpoint: resource_not_found

Tham số

Tên	Vị trí	Bắt buộc	Kiểu	Mô tả
id	path	Có	PaymentRequestRef	Mã yêu cầu pr_… hoặc mã nội dung DTP….

curl

curl -sS -X GET "https://api.dongtien.pro/v1/payment-requests/$ID/transactions" \
  -H "Authorization: Bearer $DT_API_KEY"

TypeScript

import { createClient } from "@dongtien/sdk";

const dt = createClient({ apiKey: process.env.DT_API_KEY! });

const { data } = await dt.GET("/v1/payment-requests/{id}/transactions", {
  params: {
    path: { "id": "pr_0f5k2m9q4h7t3n8r6v1w0x5yzd" },
  },
});

Python

import os

from dongtien import DongTien
from dongtien_api.api.thu_tien import list_payment_request_transactions

with DongTien(api_key=os.environ["DT_API_KEY"]) as dt:
    result = list_payment_request_transactions.sync(id="pr_0f5k2m9q4h7t3n8r6v1w0x5yzd", client=dt.client)

Mở trong tài liệu tương tác

POST /v1/payment-requests/{id}:cancel

Huỷ yêu cầu thanh toán

Chỉ khi còn waiting. Tiền chuyển sau khi huỷ không gắn vào yêu cầu: vào việc cần xử lý (late_payment). Phát payment_request.cancelled.

Quyền: payment_request.cancel Scope: collect:write Idempotency-Key: tuỳ chọn

• Nhóm tốc độ: write
• Nội dung yêu cầu: CancelPaymentRequest (application/json)
• Phản hồi thành công 200: Yêu cầu đã huỷ. — PaymentRequest, application/json
• Mã lỗi riêng của endpoint: resource_not_found, conflict, idempotency_in_flight, idempotency_key_reused

Tham số

Tên	Vị trí	Bắt buộc	Kiểu	Mô tả
id	path	Có	PaymentRequestRef	Mã yêu cầu pr_… hoặc mã nội dung DTP….
idempotency-key	header	Không	string	Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ.

curl

curl -sS -X POST "https://api.dongtien.pro/v1/payment-requests/$ID:cancel" \
  -H "Authorization: Bearer $DT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "reason": "Khách đổi ý, không mua nữa"
}'

TypeScript

import { createClient } from "@dongtien/sdk";

const dt = createClient({ apiKey: process.env.DT_API_KEY! });

const { data } = await dt.POST("/v1/payment-requests/{id}:cancel", {
  params: {
    path: { "id": "pr_0f5k2m9q4h7t3n8r6v1w0x5yzd" },
  },
  body: {
    "reason": "Khách đổi ý, không mua nữa"
  },
});

Python

import os

from dongtien import DongTien
from dongtien_api.api.thu_tien import cancel_payment_request
from dongtien_api.models import CancelPaymentRequest

with DongTien(api_key=os.environ["DT_API_KEY"]) as dt:
    result = cancel_payment_request.sync(
        id="pr_0f5k2m9q4h7t3n8r6v1w0x5yzd",
        client=dt.client,
        body=CancelPaymentRequest.from_dict({
            "reason": "Khách đổi ý, không mua nữa",
        }),
    )

Mở trong tài liệu tương tác

POST /v1/payment-requests/{id}:receipt

Gửi biên nhận

Chỉ khi paid hoặc over. Ghi dòng receipt vào nhật ký và đưa biên nhận gửi tới recipient vào hàng đợi thông báo (gửi lại cùng người nhận không tạo thêm tin).

Quyền: payment_request.remind Scope: collect:write Idempotency-Key: tuỳ chọn

• Nhóm tốc độ: write
• Nội dung yêu cầu: PaymentRequestNotify (application/json, bắt buộc)
• Phản hồi thành công 200: Yêu cầu. — PaymentRequest, application/json
• Mã lỗi riêng của endpoint: resource_not_found, conflict, idempotency_in_flight, idempotency_key_reused

Tham số

Tên	Vị trí	Bắt buộc	Kiểu	Mô tả
id	path	Có	PaymentRequestRef	Mã yêu cầu pr_… hoặc mã nội dung DTP….
idempotency-key	header	Không	string	Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ.

curl

curl -sS -X POST "https://api.dongtien.pro/v1/payment-requests/$ID:receipt" \
  -H "Authorization: Bearer $DT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "recipient": {
    "channel": "email",
    "address": "ketoan@cuahangminhanh.vn"
  }
}'

TypeScript

import { createClient } from "@dongtien/sdk";

const dt = createClient({ apiKey: process.env.DT_API_KEY! });

const { data } = await dt.POST("/v1/payment-requests/{id}:receipt", {
  params: {
    path: { "id": "pr_0f5k2m9q4h7t3n8r6v1w0x5yzd" },
  },
  body: {
    "recipient": {
      "channel": "email",
      "address": "ketoan@cuahangminhanh.vn"
    }
  },
});

Python

import os

from dongtien import DongTien
from dongtien_api.api.thu_tien import receipt_payment_request
from dongtien_api.models import PaymentRequestNotify

with DongTien(api_key=os.environ["DT_API_KEY"]) as dt:
    result = receipt_payment_request.sync(
        id="pr_0f5k2m9q4h7t3n8r6v1w0x5yzd",
        client=dt.client,
        body=PaymentRequestNotify.from_dict({
            "recipient": {
                "channel": "email",
                "address": "ketoan@cuahangminhanh.vn",
            },
        }),
    )

Mở trong tài liệu tương tác

POST /v1/payment-requests/{id}:remind

Nhắc thanh toán

Ghi dòng reminded vào nhật ký và đưa lời nhắc gửi tới recipient vào hàng đợi thông báo. Chỉ với yêu cầu waiting, provisional hoặc short.

Quyền: payment_request.remind Scope: collect:write Idempotency-Key: tuỳ chọn

• Nhóm tốc độ: write
• Nội dung yêu cầu: PaymentRequestNotify (application/json, bắt buộc)
• Phản hồi thành công 200: Yêu cầu. — PaymentRequest, application/json
• Mã lỗi riêng của endpoint: resource_not_found, conflict, idempotency_in_flight, idempotency_key_reused

Tham số

Tên	Vị trí	Bắt buộc	Kiểu	Mô tả
id	path	Có	PaymentRequestRef	Mã yêu cầu pr_… hoặc mã nội dung DTP….
idempotency-key	header	Không	string	Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ.

curl

curl -sS -X POST "https://api.dongtien.pro/v1/payment-requests/$ID:remind" \
  -H "Authorization: Bearer $DT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "recipient": {
    "channel": "email",
    "address": "ketoan@cuahangminhanh.vn"
  }
}'

TypeScript

import { createClient } from "@dongtien/sdk";

const dt = createClient({ apiKey: process.env.DT_API_KEY! });

const { data } = await dt.POST("/v1/payment-requests/{id}:remind", {
  params: {
    path: { "id": "pr_0f5k2m9q4h7t3n8r6v1w0x5yzd" },
  },
  body: {
    "recipient": {
      "channel": "email",
      "address": "ketoan@cuahangminhanh.vn"
    }
  },
});

Python

import os

from dongtien import DongTien
from dongtien_api.api.thu_tien import remind_payment_request
from dongtien_api.models import PaymentRequestNotify

with DongTien(api_key=os.environ["DT_API_KEY"]) as dt:
    result = remind_payment_request.sync(
        id="pr_0f5k2m9q4h7t3n8r6v1w0x5yzd",
        client=dt.client,
        body=PaymentRequestNotify.from_dict({
            "recipient": {
                "channel": "email",
                "address": "ketoan@cuahangminhanh.vn",
            },
        }),
    )

Mở trong tài liệu tương tác

POST /v1/payment-requests/{id}:resend-remainder

Gửi phần còn lại

Chỉ khi short. Giữ nguyên mã DTP…, đặt locked_amount = amount − đã nhận (xác thực) và sinh lại QR.

Quyền: payment_request.update Scope: collect:write Idempotency-Key: tuỳ chọn

• Nhóm tốc độ: write
• Phản hồi thành công 200: Yêu cầu với QR phần còn lại. — PaymentRequest, application/json
• Mã lỗi riêng của endpoint: resource_not_found, conflict, idempotency_in_flight, idempotency_key_reused

Tham số

Tên	Vị trí	Bắt buộc	Kiểu	Mô tả
id	path	Có	PaymentRequestRef	Mã yêu cầu pr_… hoặc mã nội dung DTP….
idempotency-key	header	Không	string	Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ.

curl

curl -sS -X POST "https://api.dongtien.pro/v1/payment-requests/$ID:resend-remainder" \
  -H "Authorization: Bearer $DT_API_KEY"

TypeScript

import { createClient } from "@dongtien/sdk";

const dt = createClient({ apiKey: process.env.DT_API_KEY! });

const { data } = await dt.POST("/v1/payment-requests/{id}:resend-remainder", {
  params: {
    path: { "id": "pr_0f5k2m9q4h7t3n8r6v1w0x5yzd" },
  },
});

Python

import os

from dongtien import DongTien
from dongtien_api.api.thu_tien import resend_payment_request_remainder

with DongTien(api_key=os.environ["DT_API_KEY"]) as dt:
    result = resend_payment_request_remainder.sync(id="pr_0f5k2m9q4h7t3n8r6v1w0x5yzd", client=dt.client)

Mở trong tài liệu tương tác

POST /v1/payment-requests/{id}:resolve-overpay

Đánh dấu đã xử lý tiền thừa

Chỉ khi over. Chỉ đánh dấu overpay_resolved_at: hệ thống không hoàn tiền (D2).

Quyền: payment_request.resolve_overpay Scope: collect:write Idempotency-Key: tuỳ chọn

• Nhóm tốc độ: write
• Nội dung yêu cầu: ResolveOverpay (application/json)
• Phản hồi thành công 200: Yêu cầu. — PaymentRequest, application/json
• Mã lỗi riêng của endpoint: resource_not_found, conflict, idempotency_in_flight, idempotency_key_reused

Tham số

Tên	Vị trí	Bắt buộc	Kiểu	Mô tả
id	path	Có	PaymentRequestRef	Mã yêu cầu pr_… hoặc mã nội dung DTP….
idempotency-key	header	Không	string	Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ.

curl

curl -sS -X POST "https://api.dongtien.pro/v1/payment-requests/$ID:resolve-overpay" \
  -H "Authorization: Bearer $DT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "note": "Đã báo khách, đối trừ vào đơn hàng sau"
}'

TypeScript

import { createClient } from "@dongtien/sdk";

const dt = createClient({ apiKey: process.env.DT_API_KEY! });

const { data } = await dt.POST("/v1/payment-requests/{id}:resolve-overpay", {
  params: {
    path: { "id": "pr_0f5k2m9q4h7t3n8r6v1w0x5yzd" },
  },
  body: {
    "note": "Đã báo khách, đối trừ vào đơn hàng sau"
  },
});

Python

import os

from dongtien import DongTien
from dongtien_api.api.thu_tien import resolve_payment_request_overpay
from dongtien_api.models import ResolveOverpay

with DongTien(api_key=os.environ["DT_API_KEY"]) as dt:
    result = resolve_payment_request_overpay.sync(
        id="pr_0f5k2m9q4h7t3n8r6v1w0x5yzd",
        client=dt.client,
        body=ResolveOverpay.from_dict({
            "note": "Đã báo khách, đối trừ vào đơn hàng sau",
        }),
    )

Mở trong tài liệu tương tác

Đối tượng

BillList

Trường	Kiểu	Bắt buộc	Mô tả
data	Bill[]	Có	—
data[].amount	PositiveVnd	Có	—
data[].bill_ref	string	Có	—
data[].counter	CounterRef	Có	—
data[].created_at	Timestamp	Có	—
data[].id	BillId	Có	—
data[].object	string	Có	Giá trị: bill.
data[].paid_at	Timestamp | null	Có	—
data[].payment_method	string	Có	Giá trị: transfer, cash.
data[].payment_request	object | null	Có	Yêu cầu thanh toán của bill (QR). null với bill tiền mặt.
data[].shift_id	ShiftId | null	Có	—
data[].source	string	Có	Giá trị: pos_api, manual.
data[].state	BillState	Có	Giá trị: waiting, paid, expired, cash_paid, cancelled.
data[].store	StoreRef	Có	—
has_more	boolean	Có	—
next_cursor	string | null	Có	Con trỏ trang kế; null khi hết dữ liệu.
object	string	Có	Giá trị: list.

CreateBill

Trường	Kiểu	Bắt buộc	Mô tả
account	string	Không	Bỏ trống: dùng tài khoản của quầy.
amount	integer	Có	—
bill_ref	string	Có	Mã bill của POS; duy nhất trong quầy. Dùng làm Idempotency-Key.
counter	string	Có	slug của quầy.
customer_name	string	Không	—
expires_in_minutes	integer	Không	Mặc định theo qr_ttl_min của quầy.
note	string	Không	—
store	string	Có	slug của cửa hàng.

Bill

Trường	Kiểu	Bắt buộc	Mô tả
amount	PositiveVnd	Có	—
bill_ref	string	Có	—
counter	CounterRef	Có	—
counter.id	CounterId	Có	—
counter.name	string	Có	—
counter.slug	string	Có	—
created_at	Timestamp	Có	—
id	BillId	Có	—
object	string	Có	Giá trị: bill.
paid_at	Timestamp | null	Có	—
payment_method	string	Có	Giá trị: transfer, cash.
payment_request	object | null	Có	Yêu cầu thanh toán của bill (QR). null với bill tiền mặt.
payment_request.account	PaymentAccountRef	Có	—
payment_request.allow_partial	boolean	Có	—
payment_request.amount	integer | null	Có	null: khách tự nhập số tiền.
payment_request.cancelled_reason	string | null	Có	—
payment_request.company_id	OrgId	Có	—
payment_request.counter	CounterRef | null	Có	—
payment_request.created_at	Timestamp	Có	—
payment_request.created_by	UserId | null	Có	—
payment_request.customer_name	string | null	Có	—
payment_request.expires_at	Timestamp	Có	—
payment_request.id	PaymentRequestId	Có	—
payment_request.late_verified	boolean	Có	true: được xác thực muộn sau khi hết hạn (A2) nhưng vẫn gắn vào yêu cầu.
payment_request.locked_amount	integer | null	Có	Số tiền khoá trong QR hiện hành (khác amount sau :resend-remainder).
payment_request.memo_code	string	Có	—
payment_request.note_internal	string | null	Có	—
payment_request.object	string	Có	Giá trị: payment_request.
payment_request.opened_at	string | null	Có	Lần đầu khách mở trang thanh toán.
payment_request.over_by	integer	Có	Thừa so với amount (chỉ khi over).
payment_request.overpay_resolved_at	Timestamp | null	Có	—
payment_request.paid_at	Timestamp | null	Có	—
payment_request.pay_url	string (uri)	Có	Trang thanh toán công khai pay.dongtien.pro/r/{mã}.
payment_request.qr	object	Có	—
payment_request.received_provisional	integer	Có	Tổng tiền tạm tính (chưa tính là đã nhận).
payment_request.received_verified	integer	Có	Tổng tiền đã xác thực đã gắn vào yêu cầu.
payment_request.ref	string | null	Có	—
payment_request.short_by	integer	Có	Còn thiếu (chỉ khi short/provisional).
payment_request.source	string	Có	—
payment_request.state	PaymentRequestState	Có	Giá trị: waiting, provisional, short, paid, over, expired, cancelled.
payment_request.store	StoreRef | null	Có	—
payment_request.version	integer	Có	Tăng mỗi lần đổi trạng thái; dùng để phát hiện cập nhật cũ.
payment_request.warnings	string[]	Có	Giá trị: ACCOUNT_PROVISIONAL_ONLY.
shift_id	ShiftId | null	Có	—
source	string	Có	Giá trị: pos_api, manual.
state	BillState	Có	Giá trị: waiting, paid, expired, cash_paid, cancelled.
store	StoreRef	Có	—
store.id	StoreId	Có	—
store.name	string	Có	—
store.slug	string	Có	—

PaymentRequestList

Trường	Kiểu	Bắt buộc	Mô tả
data	PaymentRequest[]	Có	—
data[].account	PaymentAccountRef	Có	—
data[].allow_partial	boolean	Có	—
data[].amount	integer | null	Có	null: khách tự nhập số tiền.
data[].cancelled_reason	string | null	Có	—
data[].company_id	OrgId	Có	—
data[].counter	CounterRef | null	Có	—
data[].created_at	Timestamp	Có	—
data[].created_by	UserId | null	Có	—
data[].customer_name	string | null	Có	—
data[].expires_at	Timestamp	Có	—
data[].id	PaymentRequestId	Có	—
data[].late_verified	boolean	Có	true: được xác thực muộn sau khi hết hạn (A2) nhưng vẫn gắn vào yêu cầu.
data[].locked_amount	integer | null	Có	Số tiền khoá trong QR hiện hành (khác amount sau :resend-remainder).
data[].memo_code	string	Có	—
data[].note_internal	string | null	Có	—
data[].object	string	Có	Giá trị: payment_request.
data[].opened_at	string | null	Có	Lần đầu khách mở trang thanh toán.
data[].over_by	integer	Có	Thừa so với amount (chỉ khi over).
data[].overpay_resolved_at	Timestamp | null	Có	—
data[].paid_at	Timestamp | null	Có	—
data[].pay_url	string (uri)	Có	Trang thanh toán công khai pay.dongtien.pro/r/{mã}.
data[].qr	object	Có	—
data[].received_provisional	integer	Có	Tổng tiền tạm tính (chưa tính là đã nhận).
data[].received_verified	integer	Có	Tổng tiền đã xác thực đã gắn vào yêu cầu.
data[].ref	string | null	Có	—
data[].short_by	integer	Có	Còn thiếu (chỉ khi short/provisional).
data[].source	string	Có	—
data[].state	PaymentRequestState	Có	Giá trị: waiting, provisional, short, paid, over, expired, cancelled.
data[].store	StoreRef | null	Có	—
data[].version	integer	Có	Tăng mỗi lần đổi trạng thái; dùng để phát hiện cập nhật cũ.
data[].warnings	string[]	Có	Giá trị: ACCOUNT_PROVISIONAL_ONLY.
has_more	boolean	Có	—
next_cursor	string | null	Có	Con trỏ trang kế; null khi hết dữ liệu.
object	string	Có	Giá trị: list.

CreatePaymentRequest

Trường	Kiểu	Bắt buộc	Mô tả
account	string	Có	Tài khoản nhận: acc_… hoặc bí danh <ngân hàng>_<4 số cuối>. Bí danh trùng nhiều tài khoản trả 409 account_alias_ambiguous.
allow_partial	boolean	Không	—
amount	integer | null	Không	Số tiền; null/bỏ trống để khách tự nhập.
counter_id	CounterId	Không	—
customer_name	string	Không	—
expires_in_minutes	integer	Không	Hạn thanh toán, mặc định 24 giờ, tối đa 30 ngày.
note	string	Không	Ghi chú nội bộ, không hiện cho khách.
ref	string	Không	Mã tham chiếu của bạn (đơn hàng…).

PaymentRequest

Trường	Kiểu	Bắt buộc	Mô tả
account	PaymentAccountRef	Có	—
account.bank	string	Có	—
account.id	AccountId	Có	—
account.label	string	Có	—
account.last4	string	Có	—
account.trust	string	Có	provisional_only: tài khoản chưa có kênh xác thực được (Open API, sao kê, email có chữ ký, SMS có người gửi do hệ điều hành cấp) — tiền về sẽ ở trạng thái tạm tính (D36). Giá trị: verifiable, provisional_only.
allow_partial	boolean	Có	—
amount	integer | null	Có	null: khách tự nhập số tiền.
cancelled_reason	string | null	Có	—
company_id	OrgId	Có	—
counter	CounterRef | null	Có	—
counter.id	CounterId	Có	—
counter.name	string	Có	—
counter.slug	string	Có	—
created_at	Timestamp	Có	—
created_by	UserId | null	Có	—
customer_name	string | null	Có	—
expires_at	Timestamp	Có	—
id	PaymentRequestId	Có	—
late_verified	boolean	Có	true: được xác thực muộn sau khi hết hạn (A2) nhưng vẫn gắn vào yêu cầu.
locked_amount	integer | null	Có	Số tiền khoá trong QR hiện hành (khác amount sau :resend-remainder).
memo_code	string	Có	—
note_internal	string | null	Có	—
object	string	Có	Giá trị: payment_request.
opened_at	string | null	Có	Lần đầu khách mở trang thanh toán.
over_by	integer	Có	Thừa so với amount (chỉ khi over).
overpay_resolved_at	Timestamp | null	Có	—
paid_at	Timestamp | null	Có	—
pay_url	string (uri)	Có	Trang thanh toán công khai pay.dongtien.pro/r/{mã}.
qr	object	Có	—
qr.emv	string	Có	Chuỗi VietQR (EMVCo) để vẽ mã QR; số tiền khoá khi locked_amount có giá trị.
received_provisional	integer	Có	Tổng tiền tạm tính (chưa tính là đã nhận).
received_verified	integer	Có	Tổng tiền đã xác thực đã gắn vào yêu cầu.
ref	string | null	Có	—
short_by	integer	Có	Còn thiếu (chỉ khi short/provisional).
source	string	Có	—
state	PaymentRequestState	Có	Giá trị: waiting, provisional, short, paid, over, expired, cancelled.
store	StoreRef | null	Có	—
store.id	StoreId	Có	—
store.name	string	Có	—
store.slug	string	Có	—
version	integer	Có	Tăng mỗi lần đổi trạng thái; dùng để phát hiện cập nhật cũ.
warnings	string[]	Có	Giá trị: ACCOUNT_PROVISIONAL_ONLY.

UpdatePaymentRequest

Trường	Kiểu	Bắt buộc	Mô tả
allow_partial	boolean	Không	—
amount	integer | null	Không	—
customer_name	string | null	Không	—
expires_in_minutes	integer	Không	—
note	string | null	Không	—
ref	string | null	Không	—

PaymentRequestEventList

Trường	Kiểu	Bắt buộc	Mô tả
data	PaymentRequestEvent[]	Có	—
data[].actor	string | null	Có	user:usr_…, key:apk_… hoặc system:recon.
data[].at	Timestamp	Có	—
data[].detail	map<string, any>	Có	—
data[].from_state	PaymentRequestState | null	Có	Giá trị: waiting, provisional, short, paid, over, expired, cancelled.
data[].id	string	Có	—
data[].kind	string	Có	Giá trị: created, opened, provisional, verified, short, over, reminded, receipt, expired, cancelled, overpay_resolved, reconciled, remainder_sent, updated, tx_attached, tx_detached.
data[].to_state	PaymentRequestState | null	Có	Giá trị: waiting, provisional, short, paid, over, expired, cancelled.
object	string	Có	Giá trị: list.

PaymentRequestTransactionList

Trường	Kiểu	Bắt buộc	Mô tả
data	PaymentRequestTransaction[]	Có	—
data[].amount	PositiveVnd	Có	—
data[].amount_applied	PositiveVnd	Có	—
data[].channel	string	Có	Giá trị: android, ios, email, openapi, statement, import.
data[].last4	string	Có	4 số cuối tài khoản nhận.
data[].linked_at	Timestamp	Có	—
data[].occurred_at	Timestamp	Có	—
data[].payer_masked	string | null	Có	Tên người chuyển đã rút gọn (NGUYEN T*** NHUNG).
data[].transaction_id	TxId	Có	—
data[].trust_basis	string	Có	Giá trị: trusted_sender, sender_verified_ios, email_dkim_direct, email_dkim_forwarded, none.
data[].verification_level	string	Có	Giá trị: provisional, verified.
data[].verified_by	string | null	Có	Giá trị: openapi, statement, trusted_sender, email_dkim, manual, import.
object	string	Có	Giá trị: list.

CancelPaymentRequest

Trường	Kiểu	Bắt buộc	Mô tả
reason	string	Không	—

PaymentRequestNotify

Trường	Kiểu	Bắt buộc	Mô tả
recipient	object | object	Có	—

ResolveOverpay

Trường	Kiểu	Bắt buộc	Mô tả
note	string	Không	—

Lưu ý về từ "đã xác thực": đây là xác thực nguồn, không phải ngân hàng xác nhận quyết toán.