0.0.2 • Published 10 months ago
@killbillsdev/node-sdk v0.0.2
KillBills - SDK (NodeJS-TS)
The main purpose of this Software Development Kit (SDK) is to facilitates the integration of KillBills' services into Node.js applications. The SDK will act as an intermediary layer, allowing developers to communicate with the KillBills API and access its features in a straightforward manner. By providing a consistent and easy-to-use interface, the SDK aims to simplify & speed up the process of integrating KillBills' services into Node.js applications.
Dependencies
Features
- getStores : The method getStores returns a list of killbills integrated stores as an array of objects with relevant properties.
- sendBankingTransaction : The method sendBanking transaction validates and send transaction to the killbills gate transaction.
- sendReceipt : The method sendReceipt validates and send a receipt to the killbills gate receipt.
Installation
with npm :
npm i @killbillsdev/killbills-sdk
with yarn :
yarn add @killbillsdev/killbills-sdk
Usage/Examples
Method getStores :
import { getStores } from '@killbills-dev/killbills-sdk';
const main = async () => {
const partnerStores = await getStores('prod','your-access-key');
return partnerStores;
};
Output:
[
{
"id": "id",
"billing_descriptor": "store billing descriptor",
"store_name": "store name",
"merchant_name": "merchant name",
"full_address": "00 street, 00000, city",
"siret": 00000000000000
},
{
"id": "id",
"billing_descriptor": "store billing descriptor",
"store_name": "store name",
"merchant_name": "merchant name",
"full_address": "00 street, 00000, city",
"siret": 00000000000000
},
//...other results
]
Method sendBankingTransaction :
note that the transactionData object only contains minimal required values see (insert link to all possibilities)
import { sendBankingTransaction } from '@killbills-dev/killbills-sdk';
const main = async () => {
const hmacKey = 'your-hmac-key';
const transactionData = {...};
const sendTransaction = await sendBankingTransaction('prod',transactionData,hmacKey);
return sendTransaction;
};
Output:
{
"status": "success",
"message": "published to gate transaction",
"messageId": "xxxxxxxxxxxxxxxxx",
"previewLink": "https://banks.killbills.co/payloads/xxxxxxxxxxxxxxxxx"
}
Method sendReceipt :
note that the receiptData object only contains minimal required values see (insert link to all possibilities)
import { sendReceipt } from '@killbills-dev/killbills-sdk';
const main = async () => {
const hmacKey = 'your-hmac-key';
const receiptData = {...};
const sendReceiptToKillbills = await sendReceipt('prod',receiptData,hmacKey);
return sendReceiptToKillbills;
};
Output:
{
"status": "success",
"message": "published to gate receipt",
"messageId": "xxxxxxxxxxxxxxxxx",
"previewLink": "https://merchants.killbills.co/payloads/xxxxxxxxxxxxxxxxx"
}
Transaction & Receipt Format
TRANSACTION :
transactionData = {
bank_id: '', // string (36 caractères)
callback_url: '', // string
partner_name: '', // string
kb_features: [], // tableau de chaînes de caractères ou nombres vides
receipt_format: '', // string ('JSON', 'PDF', 'SVG', 'PNG')
transaction: {
reference_id: '', // string
amount: '', // number (positif)
customer_id: '', // string
transaction_date: '', // date (au format chaîne de caractères)
store_name: '', // string ou vide
billing_descriptor: '', // string
siret: '', // string ou vide
payment: '', // objet vide
currency: '', // string ou vide
pos_name: '', // string ou vide
merchant_name: '' // string ou vide
}
};
RECEIPT :
receiptData = {
reference_id: '', // string (alphanumérique)
amount: 0, // number
total_tax_amount: '', // number ou vide
currency: '', // string ('EUR' ou 'USD')
date: '', // string (au format 'YYYY-MM-DDTHH:mm:ss')
covers: 0, // number ou vide
table: '', // string ou vide
invoice: 0, // number ou vide
total_discount: 0, // number ou vide
mode: 0, // number ou vide
partner_name: '', // string
merchant: {
merchant_name: '', // string ou vide
reference_id: '', // string
merchant_id: 0 // number ou vide
},
store: {
store_name: '', // string
reference_id: '', // string
billing_descriptor: '', // string
siret: '', // string (14 caractères)
code_ape: '', // string ou vide
tva_intra: '', // string ou vide
address: {
postal_code: 0, // number
street_address: '', // string ou vide
country: '', // string ou vide
city: '', // string ou vide
full_address: '', // string ou vide
number: 0 // number ou vide
}
},
taxes: [{
description: '', // string ou vide
amount: 0, // number
rate: 550 // number (550, 1000 ou 2000) ou vide
}],
items: [{
reference_id: '', // string ou vide
name: '', // string
description: '', // string ou vide
type: '', // string ou vide
quantity: 0, // number
price: 0, // number
discount: 0, // number ou vide
total_amount: 0, // number ou vide
tax: {
description: '', // string ou vide
amount: 0, // number
rate: 550 // number (550, 1000 ou 2000) ou vide
},
subitems: [{
reference_id: '', // string ou vide
name: '', // string
description: '', // string ou vide
quantity: 0, // number ou vide
price: 0, // number ou vide
discount: 0, // number ou vide
total_amount: 0, // number ou vide
tax: {
description: '', // string ou vide
amount: 0, // number
rate: 550 // number (550, 1000 ou 2000) ou vide
}
}]
}],
payments: [{
bin: '', // string ou vide
last_four: '', // string ou vide
auth_code: '', // string ou vide
scheme: '', // string ou vide
amount: 0, // number
transaction_date: '', // string (au format 'YYYY-MM-DDTHH:mm:ss')
transaction_id: '', // string ou vide
payment_type: '' // string ou vide
}]
};
Run Locally
Clone the project
git clone https://github.com/killbillsdev/killbills-sdk
Go to the project directory
cd killbills-sdk
Set node version & Install dependencies
nvm use 18 && npm install
Build the package
npm run build
Running Tests
To run tests, run the following command
npm run test
Feedback
If you have any feedback, please reach out to us at :
https://freeonlinesurveys.com/s/8biYAZPa