Trích nợ tự động

Quản lý liên kết trích nợ tự động: đăng ký, thanh toán, hủy liên kết, hoàn tiền.

---

Đăng ký liên kết

API: POST /v1/direct-debit/register

Node.js

const result = await client.directDebit.register({
  requestId: 'REQ_001',
  phone: '0935926988',
  returnUrl: 'https://example.com/callback',
  bankBin: '970418',
  accountName: 'NGUYEN VAN A',
});

Java

var req = new OpenApiRegisterDto();
req.setRequestId("REQ_001");
req.setPhone("0935926988");
req.setReturnUrl("https://example.com/callback");
req.setBankBin("970418");
req.setAccountName("NGUYEN VAN A");

var result = client.directDebit.register(req);

C#

var result = await client.DirectDebit.RegisterAsync(new OpenApiRegisterDto
{
    RequestId = "REQ_001",
    Phone = "0935926988",
    ReturnUrl = "https://example.com/callback",
    BankBin = "970418",
    AccountName = "NGUYEN VAN A",
});

PHP

$result = $client->directDebit->register(
    requestId: 'REQ_001',
    phone: '0935926988',
    returnUrl: 'https://example.com/callback',
    bankBin: '970418',
    accountName: 'NGUYEN VAN A',
);

Tham số đầu vào

Trường	Kiểu	Bắt buộc	Mô tả
requestId	string	✓	Mã yêu cầu duy nhất
phone	string	✓	Số điện thoại
returnUrl	string	✓	URL callback sau đăng ký
bankBin	string	✕	Mã BIN ngân hàng. Dùng BankBinEnum
accountName	string	✕	Tên chủ tài khoản

Response

Trả về URL đăng ký trong data (string).

---

Thanh toán hóa đơn

API: POST /v1/direct-debit/payment-bill

Node.js

const result = await client.directDebit.paymentBill({
  requestId: 'REQ_002',
  subscriptionId: 'SUB_001',
  amount: '500000',
  description: 'Thanh toán đơn hàng',
  partnerCode: 'one-pay',
  serviceProviderName: 'TINGEE',
});

Java

var req = new OpenApiPaymentBillDto();
req.setRequestId("REQ_002");
req.setSubscriptionId("SUB_001");
req.setAmount("500000");
req.setDescription("Thanh toán đơn hàng");
req.setPartnerCode("one-pay");
req.setServiceProviderName("TINGEE");

var result = client.directDebit.paymentBill(req);

C#

var result = await client.DirectDebit.PaymentBillAsync(new OpenApiPaymentBillDto
{
    RequestId = "REQ_002",
    SubscriptionId = "SUB_001",
    Amount = "500000",
    Description = "Thanh toán đơn hàng",
    PartnerCode = "one-pay",
    ServiceProviderName = "TINGEE",
});

PHP

$result = $client->directDebit->paymentBill(
    requestId: 'REQ_002',
    subscriptionId: 'SUB_001',
    amount: '500000',
    description: 'Thanh toán đơn hàng',
    partnerCode: 'one-pay',
    serviceProviderName: 'TINGEE',
);

Tham số đầu vào

Trường	Kiểu	Bắt buộc	Mô tả
requestId	string	✓	Mã yêu cầu duy nhất
subscriptionId	string	✓	Mã liên kết trích nợ
amount	string	✓	Số tiền (dạng string)
description	string	✓	Nội dung thanh toán
partnerCode	string	✓	Mã đối tác (one-pay)
serviceProviderName	string	✓	Tên nhà cung cấp dịch vụ
clientId	string	✕	Mã client
expirationTime	string	✕	Thời gian hết hạn
tokenRef	string	✕	Token tham chiếu
accountNumber	string	✕	Số tài khoản
returnUrl	string	✕	URL callback
additionalData	object	✕	Dữ liệu bổ sung

Response

{
  "code": "00",
  "message": "Success",
  "data": {
    "code": "00",
    "status": "success",
    "transactionCode": "TXN_001"
  }
}

Trường	Kiểu	Mô tả
data.code	string	Mã kết quả
data.status	string	Trạng thái: success, failure, pending, pending-confirm, ...
data.transactionCode	string	Mã giao dịch
data.isSentConfirmEmail	boolean	Đã gửi email xác nhận
data.isSentConfirmZalo	boolean	Đã gửi Zalo xác nhận
data.returnUrl	string	URL redirect

---

Hủy liên kết

API: DELETE /v1/direct-debit/delete-subscription

Node.js

const result = await client.directDebit.deleteSubscription({
  requestId: 'REQ_003',
  subscriptionId: 'SUB_001',
  tokenRef: 'TOKEN_REF',
  returnUrl: 'https://example.com/callback',
});

Java

var req = new OpenApiDeleteSubscriptionDto();
req.setRequestId("REQ_003");
req.setSubscriptionId("SUB_001");
req.setTokenRef("TOKEN_REF");
req.setReturnUrl("https://example.com/callback");

var result = client.directDebit.deleteSubscription(req);

C#

var result = await client.DirectDebit.DeleteSubscriptionAsync(new OpenApiDeleteSubscriptionDto
{
    RequestId = "REQ_003",
    SubscriptionId = "SUB_001",
    TokenRef = "TOKEN_REF",
    ReturnUrl = "https://example.com/callback",
});

PHP

$result = $client->directDebit->deleteSubscription(
    requestId: 'REQ_003',
    subscriptionId: 'SUB_001',
    tokenRef: 'TOKEN_REF',
    returnUrl: 'https://example.com/callback',
);

Tham số đầu vào

Trường	Kiểu	Bắt buộc	Mô tả
requestId	string	✓	Mã yêu cầu duy nhất
subscriptionId	string	✓	Mã liên kết trích nợ
tokenRef	string	✓	Token tham chiếu
returnUrl	string	✓	URL callback

Response

{
  "code": "00",
  "message": "Success",
  "data": {
    "code": "00",
    "confirmUrl": "https://..."
  }
}

Trường	Kiểu	Mô tả
data.code	string	Mã kết quả
data.confirmUrl	string	URL xác nhận hủy liên kết

---

Hoàn tiền

API: POST /v1/direct-debit/refund

Node.js

const result = await client.directDebit.refund({
  subscriptionId: 'SUB_001',
  tokenRef: 'TOKEN_REF',
  transactionId: 'TXN_001',
  amount: 100000,
});

Java

var req = new OpenApiRefundInputDto();
req.setSubscriptionId("SUB_001");
req.setTokenRef("TOKEN_REF");
req.setTransactionId("TXN_001");
req.setAmount(100000);

var result = client.directDebit.refund(req);

C#

var result = await client.DirectDebit.RefundAsync(new OpenApiRefundInputDto
{
    SubscriptionId = "SUB_001",
    TokenRef = "TOKEN_REF",
    TransactionId = "TXN_001",
    Amount = 100000,
});

PHP

$result = $client->directDebit->refund(
    subscriptionId: 'SUB_001',
    tokenRef: 'TOKEN_REF',
    transactionId: 'TXN_001',
    amount: 100000,
);

Tham số đầu vào

Trường	Kiểu	Bắt buộc	Mô tả
subscriptionId	string	✓	Mã liên kết trích nợ
tokenRef	string	✓	Token tham chiếu
transactionId	string	✓	Mã giao dịch cần hoàn
amount	number	✓	Số tiền hoàn

Response

{
  "code": "00",
  "message": "Success",
  "data": {
    "refundAmount": 100000,
    "transactionId": "TXN_REFUND_001",
    "status": "success"
  }
}

Trường	Kiểu	Mô tả
data.refundAmount	number	Số tiền đã hoàn
data.transactionId	string	Mã giao dịch hoàn
data.status	string	Trạng thái: success, failure, Pending

---

Sửa phương thức thanh toán

API: PUT /v1/direct-debit/edit-confirm-payment-method

Node.js

const result = await client.directDebit.editConfirmPaymentMethod({
  requestId: 'REQ_004',
  returnUrl: 'https://example.com/callback',
  subscriptionId: 'SUB_001',
});

Java

var req = new OpenApiEditConfirmBeforePaymentMethodDto();
req.setRequestId("REQ_004");
req.setReturnUrl("https://example.com/callback");
req.setSubscriptionId("SUB_001");

var result = client.directDebit.editConfirmPaymentMethod(req);

C#

var result = await client.DirectDebit.EditConfirmPaymentMethodAsync(
    new OpenApiEditConfirmBeforePaymentMethodDto
    {
        RequestId = "REQ_004",
        ReturnUrl = "https://example.com/callback",
        SubscriptionId = "SUB_001",
    });

PHP

$result = $client->directDebit->editConfirmPaymentMethod(
    requestId: 'REQ_004',
    returnUrl: 'https://example.com/callback',
    subscriptionId: 'SUB_001',
);

Tham số đầu vào

Trường	Kiểu	Bắt buộc	Mô tả
requestId	string	✓	Mã yêu cầu duy nhất
returnUrl	string	✓	URL callback
subscriptionId	string	✓	Mã liên kết trích nợ

Response

Trả về URL xác nhận trong data (string).

---

Trạng thái liên kết

API: GET /v1/direct-debit/get-subscription-status

Node.js

const result = await client.directDebit.getSubscriptionStatus({
  subscriptionId: 'SUB_001',
  tokenRef: 'TOKEN_REF',
});

Java

var result = client.directDebit.getSubscriptionStatus(
    null, "SUB_001", "TOKEN_REF"
);

C#

var result = await client.DirectDebit.GetSubscriptionStatusAsync(
    subscriptionId: "SUB_001",
    tokenRef: "TOKEN_REF"
);

PHP

$result = $client->directDebit->getSubscriptionStatus(
    subscriptionId: 'SUB_001',
    tokenRef: 'TOKEN_REF',
);

Tham số đầu vào (query)

Trường	Kiểu	Bắt buộc	Mô tả
subscriptionId	string	✓	Mã liên kết trích nợ
tokenRef	string	✓	Token tham chiếu
requestId	string	✕	Mã yêu cầu

Response

{
  "code": "00",
  "message": "Success",
  "data": {
    "subscriptionId": "SUB_001",
    "tokenRef": "TOKEN_REF",
    "bankBin": "970418",
    "bankName": "BIDV",
    "accountNumber": "0935926988",
    "accountName": "NGUYEN VAN A",
    "phone": "0935926988",
    "status": "active",
    "confirmPaymentByEmail": false,
    "confirmPaymentByZalo": true,
    "confirmPhoneNumber": "0935926988"
  }
}

Trường	Kiểu	Mô tả
data.subscriptionId	string	Mã liên kết
data.tokenRef	string	Token tham chiếu
data.bankBin	string	Mã BIN ngân hàng. Dùng BankBinEnum
data.bankName	string	Tên ngân hàng. Dùng BankNameEnum
data.accountNumber	string	Số tài khoản
data.phone	string	Số điện thoại
data.status	string	active hoặc inactive
data.confirmPaymentByEmail	boolean	Xác nhận qua email
data.confirmPaymentByZalo	boolean	Xác nhận qua Zalo

---

Trạng thái giao dịch

API: GET /v1/direct-debit/get-transaction-status

Node.js

const result = await client.directDebit.getTransactionStatus({
  transactionId: 'TXN_001',
  tokenRef: 'TOKEN_REF',
  subscriptionId: 'SUB_001',
});

Java

var result = client.directDebit.getTransactionStatus(
    "TXN_001", "TOKEN_REF", "SUB_001"
);

C#

var result = await client.DirectDebit.GetTransactionStatusAsync(
    transactionId: "TXN_001",
    tokenRef: "TOKEN_REF",
    subscriptionId: "SUB_001"
);

PHP

$result = $client->directDebit->getTransactionStatus(
    transactionId: 'TXN_001',
    tokenRef: 'TOKEN_REF',
    subscriptionId: 'SUB_001',
);

Tham số đầu vào (query)

Trường	Kiểu	Bắt buộc	Mô tả
transactionId	string	✓	Mã giao dịch
tokenRef	string	✓	Token tham chiếu
subscriptionId	string	✓	Mã liên kết trích nợ

Response

{
  "code": "00",
  "message": "Success",
  "data": {
    "transactionId": "TXN_001",
    "subscriptionId": "SUB_001",
    "tokenRef": "TOKEN_REF",
    "bankBin": "970418",
    "accountNumber": "0935926988",
    "amount": 500000,
    "status": "success",
    "transactionDate": "2025-01-15T10:30:00Z"
  }
}

Trường	Kiểu	Mô tả
data.transactionId	string	Mã giao dịch
data.subscriptionId	string	Mã liên kết
data.bankBin	string	Mã BIN ngân hàng. Dùng BankBinEnum
data.amount	number	Số tiền
data.status	string	success, failed, pending, insufficient-balance, ...
data.transactionDate	string	Thời gian giao dịch
data.customer	object	Thông tin khách hàng (onepayAccountId, name, phone, email)

---

Lịch sử giao dịch

API: GET /v1/direct-debit/get-paging-transactions

Node.js

const result = await client.directDebit.getPagingTransactions({
  subscriptionId: 'SUB_001',
  tokenRef: 'TOKEN_REF',
  skipCount: 0,
  maxResultCount: 10,
});

Java

var result = client.directDebit.getPagingTransactions(
    "SUB_001", "TOKEN_REF", null, null, 0, 10
);

C#

var result = await client.DirectDebit.GetPagingTransactionsAsync(
    subscriptionId: "SUB_001",
    tokenRef: "TOKEN_REF",
    skipCount: 0,
    maxResultCount: 10
);

PHP

$result = $client->directDebit->getPagingTransactions(
    subscriptionId: 'SUB_001',
    tokenRef: 'TOKEN_REF',
    skipCount: 0,
    maxResultCount: 10,
);

Tham số đầu vào (query)

Trường	Kiểu	Bắt buộc	Mô tả
subscriptionId	string	✓	Mã liên kết trích nợ
tokenRef	string	✓	Token tham chiếu
startTime	string	✕	Thời gian bắt đầu lọc
endTime	string	✕	Thời gian kết thúc lọc
skipCount	number	✕	Số bản ghi bỏ qua
maxResultCount	number	✕	Số bản ghi tối đa

Response

Trả về PagedResultDto với totalCount và mảng items:

Trường	Kiểu	Mô tả
items[].transactionId	string	Mã giao dịch
items[].code	string	Mã kết quả
items[].bankName	string	Tên ngân hàng. Dùng BankNameEnum
items[].amount	string	Số tiền
items[].content	string	Nội dung giao dịch
items[].accountNumber	string	Số tài khoản
items[].transactionDate	string	Thời gian giao dịch
items[].status	string	success, failure, pending, refunded, ...