{"id":29943366,"url":"https://github.com/sourcefuse/loopback4-billing","last_synced_at":"2025-08-03T02:16:48.702Z","repository":{"id":259021766,"uuid":"860326629","full_name":"sourcefuse/loopback4-billing","owner":"sourcefuse","description":null,"archived":false,"fork":false,"pushed_at":"2024-12-17T11:31:25.000Z","size":305,"stargazers_count":1,"open_issues_count":7,"forks_count":0,"subscribers_count":8,"default_branch":"master","last_synced_at":"2025-07-26T09:35:48.748Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sourcefuse.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":".github/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":".github/CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-09-20T08:24:20.000Z","updated_at":"2024-12-12T13:50:10.000Z","dependencies_parsed_at":"2024-11-08T11:23:32.112Z","dependency_job_id":"dd82220c-2ebe-4755-8f97-23ea92395e35","html_url":"https://github.com/sourcefuse/loopback4-billing","commit_stats":null,"previous_names":["sourcefuse/loopback4-billing"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/sourcefuse/loopback4-billing","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sourcefuse%2Floopback4-billing","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sourcefuse%2Floopback4-billing/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sourcefuse%2Floopback4-billing/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sourcefuse%2Floopback4-billing/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sourcefuse","download_url":"https://codeload.github.com/sourcefuse/loopback4-billing/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sourcefuse%2Floopback4-billing/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":268484362,"owners_count":24257660,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-03T02:00:12.545Z","response_time":2577,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-08-03T02:15:10.286Z","updated_at":"2025-08-03T02:16:48.666Z","avatar_url":"https://github.com/sourcefuse.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ca href=\"https://sourcefuse.github.io/arc-docs/arc-api-docs\" target=\"_blank\"\u003e\u003cimg src=\"https://github.com/sourcefuse/loopback4-microservice-catalog/blob/master/docs/assets/logo-dark-bg.png?raw=true\" alt=\"ARC By SourceFuse logo\" title=\"ARC By SourceFuse\" align=\"right\" width=\"150\" /\u003e\u003c/a\u003e\n\n# [loopback4-billing](https://github.com/sourcefuse/loopback4-billing)\n\n\u003cp align=\"left\"\u003e\n\u003ca href=\"https://www.npmjs.com/package/loopback4-billing\"\u003e\n\u003cimg src=\"https://img.shields.io/npm/v/loopback4-billing.svg\" alt=\"npm version\" /\u003e\n\u003c/a\u003e\n\u003ca href=\"https://sonarcloud.io/summary/new_code?id=sourcefuse_loopback4-billing\" target=\"_blank\"\u003e\n\u003cimg alt=\"Sonar Quality Gate\" src=\"https://img.shields.io/sonar/quality_gate/sourcefuse_loopback4-billing?server=https%3A%2F%2Fsonarcloud.io\"\u003e\n\u003c/a\u003e\n\u003ca href=\"https://app.snyk.io/org/ashishkaushik/reporting?context[page]=issues-detail\u0026project_target=%255B%2522sourcefuse%252Floopback4-billing%2522%255D\u0026project_origin=%255B%2522github%2522%255D\u0026issue_status=%255B%2522Open%2522%255D\u0026issue_by=Severity\u0026table_issues_detail_cols=SCORE%257CCVE%257CCWE%257CPROJECT%257CEXPLOIT%2520MATURITY%257CINTRODUCED%257CSNYK%2520PRODUCT\u0026v=1\"\u003e\n\u003cimg alt=\"Synk Status\" src=\"https://img.shields.io/badge/SYNK_SECURITY-MONITORED-GREEN\"\u003e\n\u003c/a\u003e\n\u003ca href=\"https://github.com/sourcefuse/loopback4-billing/graphs/contributors\" target=\"_blank\"\u003e\n\u003cimg alt=\"GitHub contributors\" src=\"https://img.shields.io/github/contributors/sourcefuse/loopback4-billing?\"\u003e\n\u003c/a\u003e\n\u003ca href=\"https://www.npmjs.com/package/loopback4-billing\" target=\"_blank\"\u003e\n\u003cimg alt=\"downloads\" src=\"https://img.shields.io/npm/dw/loopback4-billing.svg\"\u003e\n\u003c/a\u003e\n\u003ca href=\"https://github.com/sourcefuse/loopback4-billing/blob/master/LICENSE\"\u003e\n\u003cimg src=\"https://img.shields.io/github/license/sourcefuse/loopback4-billing.svg\" alt=\"License\" /\u003e\n\u003c/a\u003e\n\u003ca href=\"https://loopback.io/\" target=\"_blank\"\u003e\n\u003cimg alt=\"Powered By LoopBack 4\" src=\"https://img.shields.io/badge/Powered%20by-LoopBack 4-brightgreen\" /\u003e\n\u003c/a\u003e\n\u003c/p\u003e\n\n## Overview\n\nThe loopback4-billing package is designed to integrate billing functionality into LoopBack 4 applications. It provides an abstraction layer to work with billing services such as Chargebee, Stripe etc, offering common billing operations like creating and managing customers, invoices, payment sources, and transactions.\n\nThe package uses a provider pattern to abstract different billing implementations, making it easy to switch between billing services like REST API or SDK-based providers.\n\n### Key Features\n**Customer Management**: Create, retrieve, update, and delete customers.\n\n**Invoice Management**: Create, retrieve, update, and delete invoices.\n\n**Payment Source Management**: Add, apply, retrieve, and delete payment sources for invoices.\n\n**Payment Status Tracking**: Check payment status of invoices.\n\n## Installation\n\nTo install loopback4-billing, use `npm`:\n\n```sh\nnpm install loopback4-billing\n```\n\n## Usage\n\n### Integration in Your LoopBack 4 Application\n\n1. Configure and load BillingComponent in the application constructor\n   as shown below.\n\n```ts\nimport {BillingComponent} from 'billing';\n// ...\nexport class MyApplication extends BootMixin(ServiceMixin(RepositoryMixin(RestApplication))) {\n  constructor(options: ApplicationConfig = {}) {\n\n    this.component(BillingComponent);\n    // ...\n  }\n  // ...\n}\n```\n2.  **Import Necessary Bindings and Interfaces**\nIn your controller or service, import BillingComponentBindings and IService from loopback4-billing.\n\n```ts\nimport { BillingComponentBindings, IService } from 'loopback4-billing';\nimport { inject } from '@loopback/core';\n```\n\n\n3. **Inject the BillingProvider into your controller.**\n Inject the BillingProvider into your controller or service where you need to perform billing operations.\n ```ts\n export class BillingController {\n  constructor(\n    @inject(BillingComponentBindings.BillingProvider)\n    private readonly billingProvider: IService,\n  ) {}\n}\n\n ```\n\n4. **Use BillingProvider Methods for Billing Operations**\nUse the methods provided by the BillingProvider to manage billing entities like customers, invoices, and payment sources like we have displayed an instance of using BillingProvider for creating a invoice.Similarly you can use all the other methods provided by billing provider.\n\n```ts\nimport { BillingComponentBindings, IService } from 'loopback4-billing';\nimport { inject } from '@loopback/core';\nimport { post, requestBody } from '@loopback/rest';\nimport { InvoiceDto } from '../models';\n\nexport class BillingController {\n  constructor(\n    @inject(BillingComponentBindings.BillingProvider)\n    private readonly billingProvider: IService,\n  ) {}\n\n  @post('/billing/invoice')\n  async createInvoice(\n    @requestBody() invoiceDto: InvoiceDto\n  ): Promise\u003cInvoiceDto\u003e {\n    return this.billingProvider.createInvoice(invoiceDto);\n  }\n}\n\n```\n\n## IService Interface and Available Methods\nThe IService interface defines a comprehensive list of methods to manage billing entities. Below is a summary of each method.\n\n### Customer Management\nTCustomer is defined as\n```ts\nexport interface TCustomer {\n  id?: string;\n  firstName: string;\n  lastName: string;\n  email: string;\n  company?: string;\n  billingAddress?: TAddress;\n  phone?: string;\n  options?: Options;\n}\n\nexport interface TAddress {\n  id?: string;\n  firstName?: string;\n  lastName?: string;\n  email?: string;\n  company?: string;\n  phone?: string;\n  city?: string;\n  state?: string;\n  zip?: string;\n  country?: string;\n  options?: Options;\n}\n```\n* **createCustomer(customerDto: TCustomer): Promise\u0026lt;TCustomer\u0026gt;** - Creates a new customer.\n\n* **getCustomers(customerId: string): Promise\u0026lt;TCustomer\u0026gt;** - Retrieves details of a specific customer by ID.\n\n* **updateCustomerById(customerId: string, customerDto: Partial\u0026lt;TCustomer\u0026gt;): Promise\u0026lt;void\u0026gt;** - Updates details of a specific customer by ID.\n\n* **deleteCustomer(customerId: string): Promise\u0026lt;void\u0026gt;** - Deletes a customer by ID.\n\n### Payment Source Management\nTpaymentSource is defined as\n```ts\nexport interface TPaymentSource {\n  id?: string;\n  customerId: string;\n  card?: ICardDto;\n  options?: Options;\n}\n\nexport interface ICardDto {\n  gatewayAccountId: string;\n  number: string;\n  expiryMonth: number;\n  expiryYear: number;\n  cvv: string;\n}\n```\n* **createPaymentSource(paymentDto: TPaymentSource): Promise\u0026lt;TPaymentSource\u0026gt;** - Creates a new payment source for the customer.\n\n* **applyPaymentSourceForInvoice(invoiceId: string, transaction: Transaction): Promise\u0026lt;TInvoice\u0026gt;** - Applies an existing payment source to an invoice. Transaction defines as\n```ts\nexport interface Transaction {\n  amount?: number; // Optional, in cents, min=0\n  paymentMethod:\n    | 'cash'\n    | 'check'\n    | 'bank_transfer'\n    | 'other'\n    | 'custom'\n    | 'payment_source'; // Required\n  paymentSourceId?: string;\n  referenceNumber?: string; // Optional, max 100 chars\n  customPaymentMethodId?: string; // Optional, max 50 chars\n  idAtGateway?: string; // Optional, max 100 chars\n  status?: 'success' | 'failure'; // Optional\n  date?: number; // Optional, timestamp in seconds (UTC)\n  errorCode?: string; // Optional, max 100 chars\n  errorText?: string; // Optional, max 65k chars\n  comment?: string;\n}\n```\n**Example of Transaction:**\nif invoice is not being paid by payment_source.\n```ts\ntransaction:Transaction={\n  paymentMethod:'cash',\n  comment:'cash 200 usd - dated 8 Nov 15:49 pm'\n}\n```\nif invoice is being paid by payment_source\n```ts\ntransaction:Transaction={\n  paymentMethod:'payment_source',\n  paymentSourceId:'id_XXXXXXX'    // id of payment source\n  comment:'cash 200 usd - dated 8 Nov 15:49 pm'\n}\n```\n* **retrievePaymentSource(paymentSourceId: string): Promise\u0026lt;TPaymentSource\u0026gt;** - Retrieves details of a specific payment source.\n\n* **deletePaymentSource(paymentSourceId: string): Promise\u0026lt;void\u0026gt;** - Deletes a payment source by ID.\n\n* **getPaymentStatus(invoiceId: string): Promise\u0026lt;boolean\u0026gt;** - Checks the payment status of a specific invoice. It returns whether the invoice is paid or not.\n\n### Invoice Management\nTInvoice is defined as :\n```ts\nexport interface TInvoice {\n  id?: string;\n  customerId: string;\n  shippingAddress?: TAddress;\n  status?: InvoiceStatus;\n  charges?: ICharge[];\n  options?: Options;\n  currencyCode: string;\n}\n```\n* **createInvoice(invoice: TInvoice): Promise\u0026lt;TInvoice\u0026gt;** - Creates a new invoice.\n\n* **retrieveInvoice(invoiceId: string): Promise\u0026lt;TInvoice\u0026gt;** - Retrieves details of a specific invoice.\n\n* **updateInvoice(invoiceId: string, invoice: Partia\u0026lt;TInvoice\u0026gt;): Promise\u003cTInvoice\u003e** -Updates an existing invoice by ID.\n\n* **deleteInvoice(invoiceId: string): Promise\u0026lt;void\u0026gt;** - Deletes an invoice by ID.\n\n\n\n\n## Configuration\n\nThe loopback4-billing package relies on the configuration of the chosen billing provider (e.g., Chargebee). To configure the package for your application, follow the steps below.\n\n### Step 1: Set Up Billing Provider\n\n#### For ChargeBee -\nTo use Chargebee as the billing provider, you need to configure the Chargebee API keys and site URL in your application. You can set these values in the environment variables of your LoopBack 4 project.\n\n```\nAPI_KEY=your_chargebee_api_key\nSITE=your_chargebee_site_url\n```\n\nafter that, bind these values with the ChargeBeeBindings.Config as shown below.\n```ts\nimport { BillingComponent } from 'loopback4-billing';\n\nexport class YourApplication extends BootMixin(\n  ServiceMixin(RepositoryMixin(RestApplication)),\n) {\n  constructor(options: ApplicationConfig = {}) {\n    super(options);\n\n    // Bind the config values\n    this.bind(ChargeBeeBindings.config).to({\n      site: process.env.SITE ?? '',\n      apiKey: process.env.API_KEY ?? '',\n    });\n\n    this.component(BillingComponent);\n    // Other configurations\n  }\n}\n```\n#### For Stripe -\nTo use Stripe as the billing provider, you need to configure the Stripe secret Key in your application. You can set these values in the environment variables of your LoopBack 4 project.\n\n```\nSTRIPE_SECRET=your_stripe_secret_key\n```\nafter that, bind these values with the ChargeBeeBindings.Config as shown below.\n```ts\nimport { BillingComponent } from 'loopback4-billing';\n\nexport class YourApplication extends BootMixin(\n  ServiceMixin(RepositoryMixin(RestApplication)),\n) {\n  constructor(options: ApplicationConfig = {}) {\n    super(options);\n\n    // Bind the config values\n    this.bind(StripeBindings.config).to({\n      secretKey: process.env.STRIPE_SECRET ?? '',\n    });\n\n    this.component(BillingComponent);\n    // Other configurations\n  }\n}\n```\n\n### Step 2: Register Billing Component\n\nTo use the billing component in your LoopBack 4 application. you need to register it in your application.ts file. And bind the Choosen billing Provider with their respective key. If provider is REST API based then bind it with `BillingComponentBindings.RestProvider`, else if the provider is SDK based bind it with `BillingComponentBindings.SDKProvider`.\n#### For ChargeBee -\nas Chargebee is a SDK based provider, so bind it with sdk provider binding.\n\n```ts\nimport { BillingComponent } from 'loopback4-billing';\n\nexport class YourApplication extends BootMixin(\n  ServiceMixin(RepositoryMixin(RestApplication)),\n) {\n  constructor(options: ApplicationConfig = {}) {\n    super(options);\n\n    this.bind(ChargeBeeBindings.config).to({\n      site: process.env.SITE ?? '',\n      apiKey: process.env.API_KEY ?? '',\n    });\n    // Register Billing component\n    this.bind(BillingComponentBindings.SDKProvider).toProvider(\n      ChargeBeeServiceProvider,\n    );\n\n    this.component(BillingComponent);\n\n\n    // Other configurations\n  }\n}\n```\n\n#### For Stripe -\nas Stripe is a SDK based provider, so bind it with sdk provider binding.\n\n```ts\nimport { BillingComponent } from 'loopback4-billing';\n\nexport class YourApplication extends BootMixin(\n  ServiceMixin(RepositoryMixin(RestApplication)),\n) {\n  constructor(options: ApplicationConfig = {}) {\n    super(options);\n\n    this.bind(StripeBindings.config).to({\n      secretKey: process.env.STRIPE_SECRET ?? '',\n    });\n    // Register Billing component\n    this.bind(BillingComponentBindings.SDKProvider).toProvider(\n      StripeServiceProvider,\n    );\n\n    this.component(BillingComponent);\n\n\n    // Other configurations\n  }\n}\n```\n\n### Step 3: Use the Billing Service in Controllers or Services\n\nYou can inject the BillingProvider or IService interface into your controller or service and use the billing operations as described below.\n\n```ts\nimport { BillingComponentBindings, IService } from 'loopback4-billing';\nimport { inject } from '@loopback/core';\nimport { post, requestBody } from '@loopback/rest';\nimport { InvoiceDto } from '../models';\n\nexport class BillingController {\n  constructor(\n    @inject(BillingComponentBindings.BillingProvider)\n    private readonly billingProvider: IService,\n  ) {}\n\n  @post('/billing/invoice')\n  async createInvoice(\n    @requestBody() invoiceDto: InvoiceDto\n  ): Promise\u003cInvoiceDto\u003e {\n    return this.billingProvider.createInvoice(invoiceDto);\n  }\n}\n\n```\n\nThe method of using providers with in controllers and services is going to be same for all type of billing provider integrations provided by Loopback4-billing.\n\n## Feedback\n\nIf you've noticed a bug or have a question or have a feature request, [search the issue tracker](https://github.com/sourcefuse/loopback4-billing/issues) to see if someone else in the community has already created a ticket.\nIf not, go ahead and [make one](https://github.com/sourcefuse/loopback4-billing/issues/new/choose)!\nAll feature requests are welcome. Implementation time may vary. Feel free to contribute the same, if you can.\nIf you think this extension is useful, please [star](https://help.github.com/en/articles/about-stars) it. Appreciation really helps in keeping this project alive.\n\n## Contributing\n\nPlease read [CONTRIBUTING.md](https://github.com/sourcefuse/loopback4-billing/blob/master/.github/CONTRIBUTING.md) for details on the process for submitting pull requests to us.\n\n## Code of conduct\n\nCode of conduct guidelines [here](https://github.com/sourcefuse/loopback4-billing/blob/master/.github/CODE_OF_CONDUCT.md).\n\n## License\n\n[MIT](https://github.com/sourcefuse/loopback4-billing/blob/master/LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsourcefuse%2Floopback4-billing","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsourcefuse%2Floopback4-billing","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsourcefuse%2Floopback4-billing/lists"}