README
Xendit API Node.js Client
This library is the abstraction of Xendit API for access from applications written with server-side Javascript.
Note: This library is only meant for usage from server-side with Xendit secret API key. For PCI compliance to be maintained, tokenization of credit cards info should be done on client side with Xendit.js.
- API Documentation
- Installation
- Usage
- Card Services
- Virtual Account Services
- Disbursement Services
- Invoice Services
- Recurring Payments Services
- Payout Services
- EWallet Services
- Balance Services
- Retail Outlet Services
- QR Code Services
- Customer services
- Direct debit services
- Initialize linked account tokenization
- Validate OTP for Linked Account Token
- Retrieve accessible accounts by linked account token
- Create payment method (Direct Debit)
- Get payment methods by customer ID (Direct Debit)
- Create direct debit payment
- Validate OTP for direct debit payment
- Get direct debit payment status by ID
- Get direct debit payment status by reference ID
- Report Service
- Transaction Service
- XenPlatform Service
- Contributing
API Documentation
Please check Xendit API Reference.
Installation
npm install --save xendit-node
Usage
Configure package with your account's secret key obtained from your Xendit Dashboard.
const Xendit = require('xendit-node');
const x = new Xendit({
secretKey: 'xnd_...',
});
Usage examples:
Card Services
Instanitiate Card service using constructor that has been injected with Xendit keys
const { Card } = x;
const cardSpecificOptions = {};
const card = new Card(cardSpecificOptions);
Example: Capturing a charge
card
.captureCharge({
chargeID: 'charge-id-from-create-charge-endpoint',
externalID: 'your-system-tracking-id',
})
.then(({ id }) => {
console.log(`Charge created with ID: ${id}`);
})
.catch(e => {
console.error(`Charge creation failed with message: ${e.message}`);
});
Refer to Xendit API Reference for more info about methods' parameters
Create charge
card.createCharge(data: {
tokenID: string;
externalID: string;
amount?: number;
authID?: string;
cardCVN?: string;
capture?: boolean;
descriptor?: string;
currency?: string;
midLabel?: string;
billingDetails?: object;
promotion?: object;
installment?: object;
forUserID?: string;
metadata?: object;
})
Capture charge
card.captureCharge(data: {
chargeID: string;
amount: number;
forUserID?: string;
})
Get charge
card.getCharge(data: { chargeID: string; forUserID?: string })
Create authorization
card.createAuthorization(data: {
tokenID: string;
externalID: string;
amount?: number;
authID?: string;
cardCVN?: string;
descriptor?: string;
currency?: string;
midLabel?: string;
billingDetails?: object;
promotion?: object;
installment?: object;
forUserID?: string;
})
Reverse authorization
card.reverseAuthorization(data: {
chargeID: string;
externalID: string;
forUserID?: string;
})
Create refund
card.createRefund(data: {
chargeID: string;
amount: number;
externalID: string;
xIdempotencyKey?: string;
forUserID?: string;
})
Create promotion
card.createPromotion(data: {
referenceId: string;
description: string;
promoCode?: string;
binList?: string[];
channelCode?: string;
discountPercent?: number;
discountAmount?: number;
currency: string;
startTime: Date;
endTime: Date;
minOriginalAmount?: number;
maxDiscountAmount?: number;
})
Virtual Account Services
Instanitiate VA service using constructor that has been injected with Xendit keys
const { VirtualAcc } = x;
const vaSpecificOptions = {};
const va = new VirtualAcc(vaSpecificOptions);
Example: Create a fixed virtual account
va.createFixedVA({
externalID: 'your-external-id',
bankCode: 'BCA',
name: 'Stanley Nguyen',
})
.then(({ id }) => {
console.log(`Fixed VA created with ID: ${id}`);
})
.catch(e => {
console.error(`VA creation failed with message: ${e.message}`);
});
Refer to Xendit API Reference for more info about methods' parameters
Get banks with available virtual account service
va.getVABanks(data?: {
forUserID?: string;
});
Create a fixed virtual account
va.createFixedVA(data: {
externalID: string;
bankCode: string;
name: string;
virtualAccNumber?: string;
suggestedAmt?: number;
isClosed?: boolean;
expectedAmt?: number;
expirationDate?: Date;
isSingleUse?: boolean;
description?: string;
forUserID?: string;
})
Get details of your fixed virtual account
va.getFixedVA(data: {
id: string;
forUserID?: string;
})
Update details of your fixed virtual account
va.updateFixedVA(data: {
id: string;
suggestedAmt?: number;
expectedAmt?: number;
expirationDate?: Date;
isSingleUse?: boolean;
description?: string;
forUserID?: string;
})
Get details of a VA payment
va.getVAPayment(data: {
paymentID: string;
forUserID?: string;
})
paymentID
: ID of the payment that you obtained from your callback
Disbursement Services
Instanitiate Disbursement service using constructor that has been injected with Xendit keys
const { Disbursement } = x;
const disbursementSpecificOptions = {};
const d = new Disbursement(disbursementSpecificOptions);
Example: Create a disbursement
d.create({
externalID: 'your-external-tracking-ID',
bankCode: 'BCA',
accountHolderName: 'Stan',
accountNumber: '1234567890',
description: 'Payment for nasi padang',
amount: 10000,
})
.then(({ id }) => {
console.log(`Disbursement created with ID: ${id}`);
})
.catch(e => {
console.error(`Disbursement creation failed with message: ${e.message}`);
});
Refer to Xendit API Reference for more info about methods' parameters
Get banks with available disbursement service
d.getBanks();
Create a disbursement
d.create(data: {
externalID: string;
bankCode: string;
accountHolderName: string;
accountNumber: string;
description: string;
amount: number;
emailTo?: string[];
emailCC?: string[];
emailBCC?: string[];
xIdempotencyKey?: string;
forUserID?: string;
withFeeRule?: string;
})
Create a batch of disbursements
d.createBatch(data: {
reference: string;
disbursements: Array<{
externalID: string;
bankCode: string;
accountHolderName: string;
accountNumber: string;
description: string;
amount: number;
emailTo?: string[];
emailCC?: string[];
emailBCC?: string[];
forUserID?: string;
withFeeRule?: string;
}>;
xIdempotencyKey?: string;
})
Get a disbursement by ID
d.getByID(data: { disbursementID: string })
- Get a disbursement by external ID
d.getByExtID(data: { externalID: string })
Invoice Services
Instanitiate Invoice service using constructor that has been injected with Xendit keys
const { Invoice } = x;
const invoiceSpecificOptions = {};
const i = new Invoice(invoiceSpecificOptions);
Example: Create an invoice
i.createInvoice({
externalID: 'your-external-id',
payerEmail: 'stanley@xendit.co',
description: 'Invoice for Shoes Purchase',
amount: 100000,
}).then(({ id }) => {
console.log(`Invoice created with ID: ${id}`);
});
Refer to Xendit API Reference for more info about methods' parameters
Create an invoice
i.createInvoice(data: {
externalID: string;
payerEmail: string;
description: string;
amount: number;
shouldSendEmail?: boolean;
callbackVirtualAccountID?: string;
invoiceDuration?: number;
successRedirectURL?: string;
failureRedirectURL?: string;
paymentMethods?: string[];
currency?: string;
midLabel?: string;
forUserID?: string;
})
Get an invoice
i.getInvoice(data: { invoiceID: string; forUserID?: string })
Expire an invoice
i.expireInvoice(data: {
invoiceID: string;
forUserID?: string;
})
Get all invoices
i.getAllInvoices(data?: {
statuses?: string[];
limit?: number;
createdAfter?: Date;
createdBefore?: Date;
paidAfter?: Date;
paidBefore?: Date;
expiredAfter?: Date;
expiredBefore?: Date;
lastInvoiceID?: string;
clientTypes?: string[];
paymentChannels?: string[];
onDemandLink?: string;
recurringPaymentID?: string;
forUserID?: string;
})
Recurring Payments Services
Instanitiate Recurring Payments service using constructor that has been injected with Xendit keys
const { RecurringPayment } = x;
const rpSpecificOptions = {};
const rp = new RecurringPayment(rpSpecificOptions);
Example: Create a recurring payment
rp.createPayment({
externalID: '123',
payerEmail: 'stanley@xendit.co',
description: 'Payment for something',
amount: 10000,
interval: RecurringPayment.Interval.Month,
intervalCount: 1,
})
.then(({ id }) => {
console.log(`Recurring payment created with ID: ${id}`);
})
.catch(e => {
console.error(
`Recurring payment creation failed with message: ${e.message}`,
);
});
Refer to Xendit API Reference for more info about methods' parameters
Create recurring payment
rp.createPayment(data: {
externalID: string;
payerEmail?: string;
description?: string;
amount: number;
interval: Interval;
intervalCount: number;
totalRecurrence?: number;
invoiceDuration?: number;
shouldSendEmail?: boolean;
missedPaymentAction?: Action;
creditCardToken?: string;
startDate?: Date;
successRedirectURL?: string;
failureRedirectURL?: string;
recharge?: boolean;
chargeImmediately?: boolean;
currency?: string;
rescheduleAt?: Date;
customer?: object;
customerNotificationPreference?: object;
reminderTimeUnit?: string;
reminderTime?: number;
paymentMethodId?: string;
})
Get recurring payment
rp.getPayment(data: { id: string })
Edit recurring payment
rp.editPayment(data: {
id: string;
amount?: number;
creditCardToken?: string;
interval?: Interval;
intervalCount?: number;
shouldSendEmail?: boolean;
invoiceDuration?: number;
missedPaymentAction?: Action;
rescheduleAt?: Date;
customerId?: string;
reminderTimeUnit?: string;
reminderTime?: number;
paymentMethodId?: string;
})
Stop recurring payment
rp.stopPayment(data: { id: string })
Pause recurring payment
rp.pausePayment(data: { id: string })
Resume recurring payment
rp.resumePayment(data: { id: string })
Payout Services
Instanitiate Payout service using constructor that has been injected with Xendit keys
const { Payout } = x;
const payoutSpecificOptions = {};
const p = new Payout(payoutSpecificOptions);
Example: Create a payout
p.createPayout({
externalID: 'your-external-id',
amount: 100000,
email: 'stanley@xendit.co',
}).then(({ id }) => {
console.log(`Invoice created with ID: ${id}`);
});
Refer to Xendit API Reference for more info about methods' parameters
Create a payout
p.createPayout(data: {
externalID: string;
amount: string;
email: string;
})
Get a payout
p.getPayout(data: { id: string })
Void a payout
p.voidPayout(data: { id: string })
EWallet Services
Instanitiate EWallet service using constructor that has been injected with Xendit keys
const { EWallet } = x;
const ewalletSpecificOptions = {};
const ew = new EWallet(ewalletSpecificOptions);
Example: Create an ewallet charge
ew.createEWalletCharge({
referenceID: 'test-reference-id',
currency: 'IDR',
amount: 50000,
checkoutMethod: 'ONE_TIME_PAYMENT',
channelCode: 'ID_OVO',
channelProperties: {
mobileNumber: '+6281234567890',
},
}).then(r => {
console.log('created ewallet payment charge:', r);
return r;
});
Refer to Xendit API Reference for more info about methods' parameters
Create payment
ew.createPayment(data: {
externalID: string;
amount: number;
phone?: string;
expirationDate?: Date;
callbackURL?: string;
redirectURL?: string;
items?: PaymentItem[];
ewalletType: CreateSupportWalletTypes;
xApiVersion?: string;
})
Get payment
ew.getPayment(data: {
externalID: string;
ewalletType: GetSupportWalletTypes;
})
Create an ewallet charge
ew.createEWalletCharge(data: {
referenceID: string;
currency: Currency;
amount: number;
checkoutMethod: string;
channelCode?: ChannelCode;
channelProperties?: ChannelProps;
paymentMethodId?: string;
customerID?: string;
basket?: Basket[];
metadata?: object;
forUserID?: string;
withFeeRule?: string;
})
Get an ewallet charge status
ew.getEWalletChargeStatus(data: {
chargeID: string;
forUserID?: string;
})
Void an ewallet charge
ew.voidEWalletCharge(data: {
chargeID: string;
forUserID?: string;
})
Initialize tokenization
ew.initializeTokenization(data: {
customerID: string;
channelCode: ChannelCode;
properties?: OnlineBankingAccessProperties;
metadata?: object;
})
Unlink tokenization
ew.unlinkTokenization(data: {
linkedAccTokenID: string;
})
Create payment method (E-Wallet)
ew.createPaymentMethod(data: {
customerID: string;
type: PaymentMethodType;
properties: PaymentMethodProperties;
metadata?: object;
})
Get payment methods by customer ID (E-Wallet)
ew.getPaymentMethodsByCustomerID(data: {
customerID: string;
})
Balance Services
Instanitiate Balance service using constructor that has been injected with Xendit keys
const { Balance } = x;
const balanceSpecificOptions = {};
const i = new Balance(balanceSpecificOptions);
Example: Get balance of holding account
b.getBalance({
accountType: Balance.AccountType.Holding,
}).then(({ balance }) => {
console.log('Holding balance amount:', balance);
});
Refer to Xendit API Reference for more info about methods' parameters
Get balance
b.getBalance(data: {
accountType: AccountType;
forUserID?: string;
})
Retail Outlet Services
Instanitiate Retail outlet service using constructor that has been injected with Xendit keys
const { RetailOutlet } = x;
const retailOutletSpecificOptions = {};
const ro = new RetailOutlet(retailOutletSpecificOptions);
Example: Example: Create a fixed payment code
ro.createFixedPaymentCode({
externalID: '123',
retailOutletName: 'ALFAMART',
name: 'Ervan Adetya',
expectedAmt: 10000,
}).then(({ id }) => {
console.log(`Fixed Payment Code created with ID: ${id}`);
});
Refer to Xendit API Reference for more info about methods' parameters
Create fixed payment code
ro.createFixedPaymentCode(data: {
externalID: string;
retailOutletName: string;
name: string;
expectedAmt: number;
paymentCode?: string;
expirationDate?: Date;
isSingleUse?: boolean;
})
Get fixed payment code
ro.getFixedPaymentCode(data: { id: string })
Get payments by fixed payment code ID
ro.getPaymentsByFixedPaymentCodeId(data: { id: string })
Update fixed payment code
ro.updateFixedPaymentCode(data: {
id: string
name?: string;
expectedAmt?: number;
expirationDate?: Date;
})
Simulate payment for RO (only in dev mode)
ro.simulatePayment(data: {
retailOutletName: string;
paymentCode: string;
transferAmount: number;
})
QR Code Services
Instanitiate QR Code service using constructor that has been injected with Xendit keys
const { QrCode } = x;
const qrcodeSpecificOptions = {};
const q = new QrCode(qrcodeSpecificOptions);
Example: create a QR code
q.createCode({
externalID: 'your-system-tracking-id',
amount: 10000,
type: QrCode.Type.Dynamic,
callback_url: 'https://yourwebsite/callback',
})
.then(({ id }) => {
console.log(`QR code created with ID: ${id}`);
})
.catch(e => {
console.error(`QR code creation failed with message: ${e.message}`);
});
Refer to Xendit API Reference for more info about methods' parameters
Create code
q.createCode(data: {
externalID: string;
type: QrCodeTypes;
callbackURL: string;
amount?: number;
});
Get code
q.getCode(data: { externalID: string });
Simulate payment for QR (only in dev mode)
q.simulate(data: { externalID: string; amount?: number });
Get payments by external ID
q.getPayments(data: {
externalID: string;
from?: string;
to?: string;
limit?: number;
});
Customer services
Instanitiate customer service using constructor that has been injected with Xendit keys
const { Customer } = x;
const customerSpecificOptions = {};
const c = new Customer(customerSpecificOptions);
Example: create a customer
c.createCustomer({
referenceID: 'ref-id-example-1',
givenNames: 'customer 1',
email: 'customer@website.com',
mobileNumber: '+6281212345678',
description: 'dummy customer',
middleName: 'middle',
surname: 'surname',
addresses: [],
})
.then(({ id }) => {
console.log(`Customer created with ID: ${id}`);
})
.catch(e => {
console.error(`Customer creation failed with message: ${e.message}`);
});
Refer to Xendit API Reference for more info about methods' parameters
Create customer
c.createCustomer(data: {
referenceID: string;
mobileNumber?: string;
email?: string;
givenNames: string;
middleName?: string;
surname?: string;
description?: string;
phoneNumber?: string;
nationality?: string;
addresses?: Address[];
dateOfBirth?: string;
metadata?: object;
});
Get customer
c.getCustomer(data: { id: string });
Get customer by reference ID
c.getCustomerByReferenceID(data: { referenceID: string });
Update customer
c.updateCustomer(data: {
id: string;
referenceID?: string;
givenNames?: string;
mobileNumber?: string;
addresses?: Address[];
description?: string;
middleName?: string;
surname?: string;
phoneNumber?: string;
nationality?: string;
dateOfBirth?: string;
metadata?: object;
})
Direct debit services
Instanitiate direct debit service using constructor that has been injected with Xendit keys
const { DirectDebit } = x;
const directDebitSpecificOptions = {};
const dd = new DirectDebit(directDebitSpecificOptions);
Example: create a direct debit payment
dd.createDirectDebitPayment({
idempotencyKey: '7960e3fd-9a1d-469d-8b3e-2f88df139c50',
referenceID: 'merchant-ref-id-ex-1',
paymentMethodID: 'pm-8c09656d-09fe-4bdd-bd8d-87495a71d231',
currency: 'IDR',
amount: 15000,
callbackURL: 'https://payment-callback-listener/',
enableOTP: true,
})
.then(({ id }) => {
console.log(`Direct debit payment created with ID: ${id}`);
})
.catch(e => {
console.error(`Direct debit creation failed with message: ${e.message}`);
});
Refer to Xendit API Reference for more info about methods' parameters
Initialize linked account tokenization
dd.initializeTokenization(data: {
customerID: string;
channelCode: ChannelCode;
properties?: DebitCardProperties | OnlineBankingAccessProperties;
metadata?: object;
});
Validate OTP for Linked Account Token
dd.validateOTPforLinkedAccount(data: {
tokenID: string;
otpCode: string;
});
Retrieve accessible accounts by linked account token
dd.retrieveAccountsByTokenID(data: {
tokenID: string;
});
Create payment method (Direct Debit)
dd.createPaymentMethod(data: {
customerID: string;
type: PaymentMethodType;
properties: PaymentMethodProperties;
metadata?: object;
});
Get payment methods by customer ID (Direct Debit)
dd.getPaymentMethodsByCustomerID(data: {
customerID: string;
});
Create direct debit payment
dd.createDirectDebitPayment(data: {
idempotencyKey: string;
referenceID: string;
paymentMethodID: string;
currency: string;
amount: number;
callbackURL: string;
enableOTP?: boolean;
description?: string;
basket?: Basket[];
metadata?: object;
});
Validate OTP for direct debit payment
dd.validateOTPforPayment(data: {
directDebitID: string;
otpCode: string;
})
Get direct debit payment status by ID
dd.getDirectDebitPaymentStatusByID(data: {
directDebitID: string;
});
Get direct debit payment status by reference ID
dd.getDirectDebitPaymentStatusByReferenceID(data: {
referenceID: string;
Report Service
Instantiate the Report service using a constructor which has been injected with Xendit keys.
const { Report } = x;
const reportSpecificOptions = {};
const r = new Report(reportSpecificOptions);
Example: Generating a report
r.generateReport({
type: 'BALANCE_HISTORY',
filterDateFrom: new Date(new Date().getTime() - 24 * 60 * 60 * 1000), // Yesterday's Date
filterDateTo: new Date(),
format: 'CSV',
currency: 'IDR',
})
.then(res => {
console.log('Generated report:', res);
})
.catch(e => {
console.error(`Generate Report Failed with Error: ${e.message}`);
})
Generate Report
r.generateReport(data: {
type: reportTypes;
filterDateFrom?: Date;
filterDateTo?: Date;
format?: formatTypes;
currency?: currencyTypes;
})
Get Report
r.getReport(data: {
id: string
})
Transaction Service
Instantiate the Transaction service using a constructor which has been injected with Xendit keys.
const { Transaction } = x;
const transactionSpecificOptions = {};
const t = new Transaction(transactionSpecificOptions);
Example: Getting a transaction
t.getTransaction({
id: "txn_123"
})
.then(res => {
console.log('Get Transaction:', res);
})
.catch(e => {
console.error(`Get Transaction Failed with Error: ${e.message}`);
})
Get Transaction
t.getTransaction(data: {
id: string;
})
List Transactions
t.listTransactions(data: {
types?: Array<string>;
statuses?: Array<string>;
channelCategories?: Array<string>;
referenceId?: string;
productId?: string;
accountIdentifier?: string;
currency?: string;
amount?: number;
limit?: number;
afterId?: string;
beforeId?: string;
createdDateFrom?: Date;
createdDateTo?: Date;
updatedDateFrom?: Date;
updatedDateTo?: Date;
})
XenPlatform Service
Instanitiate Platform service using constructor that has been injected with Xendit keys
const { Platform } = x;
const platformSpecificOptions = {};
const p = new Platform(platformSpecificOptions);
Example: Creating a sub-account
p.createAccount({
accountEmail: 'example@gmail.com',
type: 'MANAGED',
})
.then(({ user_id }) => {
console.log(`Account created with ID: ${user_id}`);
})
.catch(e => {
console.error(`Account creation failed with message: ${e.message}`);
});
Refer to Xendit API Reference for more info about methods' parameters
Create sub-account
p.createAccount(data: {
accountEmail: string;
type: AccountTypes;
businessProfile?: {
businessName: string;
};
})
Create sub-account using V2
p.createV2Account(data: {
email: string;
type: string;
publicProfile?: {
businessName: string;
};
})
Get sub-account by ID
p.getAccountByID(data: {
id: string;
})
Update sub-account
p.updateAccount(data: {
id: string;
email: string;
publicProfile?: {
businessName: string;
};
})
Set Callback URL
p.setCallbackURL(data: {
type: string;
url: string;
forUserID?: string;
})
Create transfers
p.createTransfer(data: {
reference: string;
amount: number;
sourceUserID: string;
destinationUserID: string;
})
Create fee rules
p.createFeeRule(data: {
name: string;
description?: string;
routes: Array<{
unit: string;
amount: number;
currency: string;
}>;
})
Contributing
Running test suite
npm install
npm run test
Running examples
cp .env.sample .env # then fill in required environment variables
node examples/card.js # or whichever example you would like to run
There are a commit hook to run linting and formatting and push hook to run all tests. Please make sure they pass before making commits/pushes.
For any requests, bug or comments, please open an issue or submit a pull request.