Direct Debit

Manage automatic debit (Direct Debit) links: register, pay, cancel the link, and refund.

---

Register a link

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',
);

Parameters

Field	Type	Required	Description
requestId	string	✓	Unique request ID
phone	string	✓	Phone number
returnUrl	string	✓	Callback URL after registration
bankBin	string	✕	Bank BIN. Use BankBinEnum
accountName	string	✕	Account holder name

Response

Returns the registration URL in data (string).

---

Pay a bill

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',
);

Parameters

Field	Type	Required	Description
requestId	string	✓	Unique request ID
subscriptionId	string	✓	Direct Debit link ID
amount	string	✓	Amount (as a string)
description	string	✓	Payment description
partnerCode	string	✓	Partner code (one-pay)
serviceProviderName	string	✓	Service provider name
clientId	string	✕	Client ID
expirationTime	string	✕	Expiration time
tokenRef	string	✕	Reference token
accountNumber	string	✕	Account number
returnUrl	string	✕	Callback URL
additionalData	object	✕	Additional data

Response

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

Field	Type	Description
data.code	string	Result code
data.status	string	Status: success, failure, pending, pending-confirm, ...
data.transactionCode	string	Transaction code
data.isSentConfirmEmail	boolean	Whether a confirmation email was sent
data.isSentConfirmZalo	boolean	Whether a Zalo confirmation was sent
data.returnUrl	string	Redirect URL

---

Cancel a link

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',
);

Parameters

Field	Type	Required	Description
requestId	string	✓	Unique request ID
subscriptionId	string	✓	Direct Debit link ID
tokenRef	string	✓	Reference token
returnUrl	string	✓	Callback URL

Response

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

Field	Type	Description
data.code	string	Result code
data.confirmUrl	string	URL to confirm the link cancellation

---

Refund

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,
);

Parameters

Field	Type	Required	Description
subscriptionId	string	✓	Direct Debit link ID
tokenRef	string	✓	Reference token
transactionId	string	✓	ID of the transaction to refund
amount	number	✓	Refund amount

Response

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

Field	Type	Description
data.refundAmount	number	Refunded amount
data.transactionId	string	Refund transaction ID
data.status	string	Status: success, failure, Pending

---

Edit payment method

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',
);

Parameters

Field	Type	Required	Description
requestId	string	✓	Unique request ID
returnUrl	string	✓	Callback URL
subscriptionId	string	✓	Direct Debit link ID

Response

Returns the confirmation URL in data (string).

---

Link status

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',
);

Parameters (query)

Field	Type	Required	Description
subscriptionId	string	✓	Direct Debit link ID
tokenRef	string	✓	Reference token
requestId	string	✕	Request ID

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"
  }
}

Field	Type	Description
data.subscriptionId	string	Link ID
data.tokenRef	string	Reference token
data.bankBin	string	Bank BIN. Use BankBinEnum
data.bankName	string	Bank name. Use BankNameEnum
data.accountNumber	string	Account number
data.phone	string	Phone number
data.status	string	active or inactive
data.confirmPaymentByEmail	boolean	Confirm via email
data.confirmPaymentByZalo	boolean	Confirm via Zalo

---

Transaction status

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',
);

Parameters (query)

Field	Type	Required	Description
transactionId	string	✓	Transaction ID
tokenRef	string	✓	Reference token
subscriptionId	string	✓	Direct Debit link ID

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"
  }
}

Field	Type	Description
data.transactionId	string	Transaction ID
data.subscriptionId	string	Link ID
data.bankBin	string	Bank BIN. Use BankBinEnum
data.amount	number	Amount
data.status	string	success, failed, pending, insufficient-balance, ...
data.transactionDate	string	Transaction time
data.customer	object	Customer information (onepayAccountId, name, phone, email)

---

Transaction history

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,
);

Parameters (query)

Field	Type	Required	Description
subscriptionId	string	✓	Direct Debit link ID
tokenRef	string	✓	Reference token
startTime	string	✕	Filter start time
endTime	string	✕	Filter end time
skipCount	number	✕	Number of records to skip
maxResultCount	number	✕	Maximum number of records

Response

Returns PagedResultDto with totalCount and an items array:

Field	Type	Description
items[].transactionId	string	Transaction ID
items[].code	string	Result code
items[].bankName	string	Bank name. Use BankNameEnum
items[].amount	string	Amount
items[].content	string	Transaction description
items[].accountNumber	string	Account number
items[].transactionDate	string	Transaction time
items[].status	string	success, failure, pending, refunded, ...