{"_id":"@chargily/chargily-pay","_rev":"1-dafa56362aef8365bade2c1b0fbb806d","name":"@chargily/chargily-pay","dist-tags":{"latest":"2.1.0"},"versions":{"2.0.0":{"name":"@chargily/chargily-pay","version":"2.0.0","description":"JavaScript Library for Chargily Pay™ Gateway - V2. The easiest and free way to integrate e-payment API through EDAHABIA of Algerie Poste and CIB of SATIM into your JS project.","main":"lib/index.js","types":"lib/index.d.ts","scripts":{"dev":"nodemon --exec ts-node ./src/index.ts","build":"tsc","test":"echo \"Error: no test specified\" && exit 1"},"repository":{"type":"git","url":"git+https://github.com/chargily/chargily-pay-javascript.git"},"keywords":["chargily","payment","gateway","e-payment","algeria","edahabia","cib","javascript","typescript"],"author":{"name":"Abderraouf Zine","email":"rofazayn@gmail.com","url":"https://github.com/rofazayn"},"license":"MIT","bugs":{"url":"https://github.com/chargily/chargily-pay-javascript/issues"},"homepage":"https://github.com/chargily/chargily-pay-javascript#readme","devDependencies":{"@types/node":"^14.0.0","nodemon":"^3.1.0","ts-node":"^10.9.2","typescript":"^4.9.5"},"_id":"@chargily/chargily-pay@2.0.0","gitHead":"1967129a99975b5f4dfcc0184991737d479b8d20","_nodeVersion":"20.11.0","_npmVersion":"10.2.4","dist":{"integrity":"sha512-D+zRfue4kq+Xn/aF0mAbW4LB+PfLv5xcM6rWnraHPI/Ol1FxUksDREfWd0ynkBOIBtQp1hvY4BmwvRGjsPgZog==","shasum":"cb95acec3bb816356ddcd6d2307147c8a2499ce4","tarball":"https://registry.npmjs.org/@chargily/chargily-pay/-/chargily-pay-2.0.0.tgz","fileCount":15,"unpackedSize":67886,"signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEUCICEIyn18FetiMp/n9fBYXU3wzATyzsxO8xaROQ9G3v8bAiEAmgsW6D+xICnRemO8I9WIeMomdHPmGQt9A2grxsQi/j0="}]},"_npmUser":{"name":"rofazayn","email":"rofazayn@gmail.com"},"directories":{},"maintainers":[{"name":"rofazayn","email":"rofazayn@gmail.com"},{"name":"chargilydev","email":"chargily@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/chargily-pay_2.0.0_1710106026654_0.8036422525428506"},"_hasShrinkwrap":false},"2.1.0":{"name":"@chargily/chargily-pay","version":"2.1.0","description":"JavaScript Library for Chargily Pay™ Gateway - V2. The easiest and free way to integrate e-payment API through EDAHABIA of Algerie Poste and CIB of SATIM into your JS project.","main":"lib/index.js","types":"lib/index.d.ts","scripts":{"dev":"nodemon --exec ts-node ./src/index.ts","build":"tsc"},"repository":{"type":"git","url":"git+https://github.com/chargily/chargily-pay-javascript.git"},"keywords":["chargily","payment","gateway","e-payment","algeria","edahabia","cib","javascript","typescript"],"author":{"name":"Abderraouf Zine","email":"rofazayn@gmail.com","url":"https://github.com/rofazayn"},"license":"MIT","bugs":{"url":"https://github.com/chargily/chargily-pay-javascript/issues"},"homepage":"https://github.com/chargily/chargily-pay-javascript#readme","devDependencies":{"@types/node":"^14.0.0","nodemon":"^3.1.0","ts-node":"^10.9.2","typescript":"^4.9.5"},"_id":"@chargily/chargily-pay@2.1.0","gitHead":"4e41e5bdef517e121912621268c58741c38dccd3","_nodeVersion":"20.11.0","_npmVersion":"10.2.4","dist":{"integrity":"sha512-BMmvgowoZN2ETqNcSTle7VIVX4wHYvxTzk1Cu3o1TV+1Lj2P1hznIo6dgj7Die9ALUsBAnSR+SjuhYsrN1LlPw==","shasum":"2f8e0bd3f87758e55604a2c38498a7f8be9a10c2","tarball":"https://registry.npmjs.org/@chargily/chargily-pay/-/chargily-pay-2.1.0.tgz","fileCount":17,"unpackedSize":74436,"signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEYCIQCmef8DV76MU0ldeQfxXY2ZckgyQ1VG1ko7LzGx6ZaTlgIhAP8KpP3hUk7EQU9prJavVXECigxh/79QZMDioJCZXVsB"}]},"_npmUser":{"name":"rofazayn","email":"rofazayn@gmail.com"},"directories":{},"maintainers":[{"name":"rofazayn","email":"rofazayn@gmail.com"},{"name":"chargilydev","email":"chargily@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/chargily-pay_2.1.0_1716858773416_0.7950852683061851"},"_hasShrinkwrap":false}},"time":{"created":"2024-03-10T21:27:06.543Z","2.0.0":"2024-03-10T21:27:06.832Z","modified":"2024-05-28T01:12:53.860Z","2.1.0":"2024-05-28T01:12:53.597Z"},"maintainers":[{"name":"rofazayn","email":"rofazayn@gmail.com"},{"name":"chargilydev","email":"chargily@gmail.com"}],"description":"JavaScript Library for Chargily Pay™ Gateway - V2. The easiest and free way to integrate e-payment API through EDAHABIA of Algerie Poste and CIB of SATIM into your JS project.","homepage":"https://github.com/chargily/chargily-pay-javascript#readme","keywords":["chargily","payment","gateway","e-payment","algeria","edahabia","cib","javascript","typescript"],"repository":{"type":"git","url":"git+https://github.com/chargily/chargily-pay-javascript.git"},"author":{"name":"Abderraouf Zine","email":"rofazayn@gmail.com","url":"https://github.com/rofazayn"},"bugs":{"url":"https://github.com/chargily/chargily-pay-javascript/issues"},"license":"MIT","readme":"# Welcome to JavaScript Package Repository\n# for [Chargily Pay](https://chargily.com/business/pay \"Chargily Pay\")™ Gateway - V2.\n\nThank you for your interest in JS Package of Chargily Pay™, an open source project by Chargily, a leading fintech company in Algeria specializing in payment solutions and  e-commerce facilitating, this Package is providing the easiest and free way to integrate e-payment API through widespread payment methods in Algeria such as EDAHABIA (Algerie Post) and CIB (SATIM) into your JavaScript/Node.js projects.\n\nThis package is developed by **Abderraouf Zine ([rofazayn](https://github.com/rofazayn))** and is open to contributions from developers like you.\n\n\n## Key Features\n\n- Easy integration with Chargily Pay e-payment gateway\n- Support for both EDAHABIA of Algerie Poste and CIB of SATIM\n- Comprehensive management of customers, products, and prices\n- Efficient handling of checkouts and payment links\n- Compatible with Node.js and browser environments\n- Support for webhooks (server-side only)\n\n## Installation\n\nTo include this library in your project, you can use npm or yarn:\n\n```shell\nnpm install @chargily/chargily-pay\n```\n\nor\n\n```shell\nyarn add @chargily/chargily-pay\n\n```\n\n## Getting Started\n\nBefore utilizing the library, you must configure it with your [Chargily API key](https://dev.chargily.com/pay-v2/api-keys) and specify the mode (test or live). Here's an example to get started:\n\n```ts\nimport { ChargilyClient } from '@chargily/chargily-pay';\n\nconst client = new ChargilyClient({\n  api_key: 'YOUR_API_KEY_HERE',\n  mode: 'test', // Change to 'live' when deploying your application\n});\n```\n\nThis initializes the Chargily client, ready for communication with the Chargily Pay API.\n\n## Webhooks Notice\n\n**Important Notice:**\n\nUsing webhooks is only suitable for back-end environments.\n\nWebhooks allow your application to react to events from Chargily Pay by receiving HTTP requests with JSON payloads. To set up and handle webhooks securely, you must implement them on a server-side environment. This ensures the proper verification and processing of webhook events without exposing sensitive information or risking security issues.\n\nWhen implementing webhooks:\n\n1. **Verify the Signature:** Ensure the request is legitimate and untampered.\n2. **Identify the Event:** Use the event type to determine the action.\n3. **Handle the Event:** Execute the necessary actions based on the event type.\n4. **Respond with 200:** Confirm receipt of the webhook.\n\n### Example Webhook Endpoint\n\nWe will be using express for this example, so first let's install some dependencies.\n\n```shell\nnpm install express body-parser\n```\n\nThen install the needed types for express\n\n```shell\nnpm i @types/express --save-dev\n```\n\nNow, here's how you can set up a secure webhook endpoint using Express:\n\n```ts\nimport bodyParser from 'body-parser';\nimport express, { Request, Response } from 'express';\nimport { verifySignature } from '@chargily/chargily-pay';\n\nconst API_SECRET_KEY = 'test_secret_key_here';\n\nconst app = express();\nconst port = 4000;\n\n// Middleware to capture raw body as Buffer\napp.use(\n  bodyParser.json({\n    verify: (req: Request, res: Response, buf: Buffer) => {\n      (req as any).rawBody = buf;\n    },\n  })\n);\n\napp.post('/webhook', (req: Request, res: Response) => {\n  const signature = req.get('signature') || '';\n  const payload = (req as any).rawBody;\n\n  if (!signature) {\n    console.log('Signature header is missing');\n    res.sendStatus(400);\n    return;\n  }\n\n  try {\n    if (!verifySignature(payload, signature, API_SECRET_KEY)) {\n      console.log('Signature is invalid');\n      res.sendStatus(403);\n      return;\n    }\n  } catch (error) {\n    console.log(\n      'Something happened while trying to process the request to the webhook'\n    );\n    res.sendStatus(403);\n    return;\n  }\n\n  const event = req.body;\n  // You can use the event.type here to implement your own logic\n  console.log(event);\n\n  res.sendStatus(200);\n});\n\napp.listen(port, () => {\n  console.log(`Server is running at http://localhost:${port}`);\n});\n```\n\nOne more thing, if you wish to test your local webhook, we recommend using a tool like [NGROK](https://ngrok.com).\n\nYou can run ngrok to open a tunnel to your local machine using this command\n\n```shell\nngrok http 4000 # or the port you are using\n```\n\nNgrok will then return a public endpoint that you can add to Chargily's dashboard, by going [here](https://pay.chargily.com/test/dashboard/developers-corner) and pasting your endpoint in the webhook endpoint field. Also, make sure you don't forget to add `/webhook` or whatever url extension you used to the URL you paste there.\n\n## Creating a Customer\n\nTo create a customer, you can use the `createCustomer` method:\n\n```ts\nconst customerData = {\n  name: 'John Doe',\n  email: 'john.doe@example.com',\n  phone: '+213xxxxxxxx',\n  address: {\n    country: 'DZ',\n    state: 'Algiers',\n    address: '123 Main St',\n  },\n  metadata: {\n    notes: 'Important customer',\n  },\n};\n\nclient\n  .createCustomer(customerData)\n  .then((customer) => console.log(customer))\n  .catch((error) => console.error(error));\n```\n\nThis method returns a promise with the created customer object.\n\n## Updating a Customer\n\nTo update an existing customer, use the `updateCustomer` method with the customer's ID and the data you want to update:\n\n```ts\nconst updateData = {\n  email: 'new.email@example.com',\n  metadata: { notes: 'Updated customer info' },\n};\n\nclient\n  .updateCustomer('customer_id_here', updateData)\n  .then((customer) => console.log(customer))\n  .catch((error) => console.error(error));\n```\n\nThis will update the specified fields of the customer and return the updated customer object.\n\n## Creating a Product\n\nTo create a new product, you can use the `createProduct` method. Here's how to create a product named \"Super Product\":\n\n```ts\nconst productData = {\n  name: 'Super Product',\n  description: 'An amazing product that does everything!',\n  images: ['http://example.com/image1.jpg', 'http://example.com/image2.jpg'],\n  metadata: { category: 'electronics' },\n};\n\nclient\n  .createProduct(productData)\n  .then((product) => console.log(product))\n  .catch((error) => console.error(error));\n```\n\nThis method requires the `name` of the product and optionally accepts `description`, an array of `images`, and `metadata`.\n\n## Deleting a Customer\n\nTo delete a customer from the Chargily Pay system, you can use the `deleteCustomer` method with the customer's ID:\n\n```ts\nclient\n  .deleteCustomer('customer_id_here')\n  .then((response) => console.log(response))\n  .catch((error) => console.error(error));\n```\n\nThis method will return a response indicating whether the deletion was successful.\n\n## Listing Customers\n\nYou can list all customers with optional pagination using the `listCustomers` method. Specify the number of customers per page using the `per_page` parameter:\n\n```ts\nclient\n  .listCustomers(20) // List 20 customers per page\n  .then((customersList) => console.log(customersList))\n  .catch((error) => console.error(error));\n```\n\nThe response will include a paginated list of customers along with pagination details.\n\n## Updating a Customer\n\nTo update an existing customer, you'll need the customer's ID:\n\n```ts\nconst updatedCustomer = await client.updateCustomer('CUSTOMER_ID', {\n  name: 'Jane Doe',\n  email: 'jane.doe@example.com',\n  phone: '987654321',\n  address: {\n    country: 'DZ',\n    state: 'Oran',\n    address: '4321 Main St',\n  },\n  metadata: {\n    custom_field_updated: 'new value',\n  },\n});\n```\n\nThis call updates the specified customer and returns the updated customer object.\n\n## Deleting a Customer\n\nTo delete a customer, use their ID:\n\n```ts\nconst deleteResponse = await client.deleteCustomer('CUSTOMER_ID');\n```\n\nThis method returns a response indicating whether the deletion was successful.\n\n## Creating a Product\n\nTo add a new product to your catalog:\n\n```ts\nconst newProduct = await client.createProduct({\n  name: 'Awesome Product',\n  description: 'A description of your awesome product',\n  images: ['https://example.com/image.png'],\n  metadata: {\n    category: 'Electronics',\n  },\n});\n```\n\nThis creates a new product and returns the product object.\n\n## Updating a Product\n\nSimilar to customers, you can update products using their ID:\n\n```ts\nconst updatedProduct = await client.updateProduct('PRODUCT_ID', {\n  name: 'Even More Awesome Product',\n  description: 'An updated description',\n  images: ['https://example.com/newimage.png'],\n  metadata: {\n    category: 'Updated Category',\n  },\n});\n```\n\nThis updates the product details and returns the updated product object.\n\n## Creating a Price\n\nTo create a price for a product, you need the product's ID:\n\n```ts\nconst newPrice = await client.createPrice({\n  amount: 5000,\n  currency: 'dzd',\n  product_id: 'PRODUCT_ID',\n  metadata: {\n    size: 'M',\n  },\n});\n```\n\nThis creates a new price for the specified product and returns the price object.\n\n## Updating a Price\n\nYou can update the metadata of a price by its ID:\n\n```ts\nconst updatedPrice = await client.updatePrice('PRICE_ID', {\n  metadata: {\n    size: 'L',\n  },\n});\n```\n\nThis updates the price's metadata and returns the updated price object.\n\n## Creating a Checkout\n\nTo create a checkout session for a customer to make a payment:\n\n```ts\nconst checkout = await client.createCheckout({\n  items: [\n    {\n      price: 'PRICE_ID',\n      quantity: 1,\n    },\n  ],\n  success_url: 'https://your-website.com/success',\n  failure_url: 'https://your-website.com/failure',\n  payment_method: 'edahabia', // Optional, defaults to 'edahabia'\n  locale: 'en', // Optional, defaults to 'ar'\n  pass_fees_to_customer: true, // Optional, defaults to false\n  shipping_address: '123 Test St, Test City, DZ', // Optional\n  collect_shipping_address: true, // Optional, defaults to false\n  metadata: {\n    order_id: '123456',\n  },\n});\n```\n\nThis creates a new checkout session and returns the checkout object, including a `checkout_url` where you can redirect your customer to complete their payment.\n\n## Creating a Payment Link\n\nPayment links are URLs that you can share with your customers for payment:\n\n```ts\nconst paymentLink = await client.createPaymentLink({\n  name: 'Product Payment',\n  items: [\n    {\n      price: 'PRICE_ID',\n      quantity: 1,\n      adjustable_quantity: false,\n    },\n  ],\n  after_completion_message: 'Thank you for your purchase!',\n  locale: 'en',\n  pass_fees_to_customer: true,\n  collect_shipping_address: true,\n  metadata: {\n    campaign: 'Summer Sale',\n  },\n});\n```\n\nThis creates a new payment link and returns the payment link object, including the URL that you can share with your customers.\n\n## Handling Prices\n\n### Creating a Price\n\nTo set up a price for a product, you can use the product's ID:\n\n```ts\nconst newPrice = await client.createPrice({\n  amount: 5000,\n  currency: 'dzd',\n  product_id: 'PRODUCT_ID',\n  metadata: {\n    discount: '10%',\n  },\n});\n```\n\nThis call creates a new price for the specified product and returns the price object.\n\n### Updating a Price\n\nUpdate a price by its ID:\n\n```ts\nconst updatedPrice = await client.updatePrice('PRICE_ID', {\n  metadata: {\n    discount: '15%',\n  },\n});\n```\n\nThis updates the metadata for the price and returns the updated price object.\n\n### Fetching Prices\n\nTo retrieve all prices for a product:\n\n```ts\nconst prices = await client.listPrices();\n```\n\nThis returns a paginated list of all prices.\n\n## Working with Checkouts\n\n### Creating a Checkout\n\nCreating a checkout is a crucial step for initiating a payment process. A checkout can be created by specifying either a list of items (products and quantities) or a total amount directly. You also need to provide a success URL and optionally a failure URL where your customer will be redirected after the payment process.\n\nHere's how you can create a checkout:\n\n```ts\nconst newCheckout = await client.createCheckout({\n  items: [\n    { price: 'PRICE_ID', quantity: 2 },\n    { price: 'ANOTHER_PRICE_ID', quantity: 1 },\n  ],\n  success_url: 'https://yourdomain.com/success',\n  failure_url: 'https://yourdomain.com/failure',\n  payment_method: 'edahabia',\n  customer_id: 'CUSTOMER_ID',\n  metadata: { orderId: '123456' },\n  locale: 'en',\n  pass_fees_to_customer: false,\n});\n```\n\nThis request creates a new checkout session and returns the checkout object, including a `checkout_url` where you should redirect your customer to complete the payment.\n\n### Retrieving a Checkout\n\nTo fetch details of a specific checkout session:\n\n```ts\nconst checkoutDetails = await client.getCheckout('CHECKOUT_ID');\n```\n\nThis retrieves the details of the specified checkout session.\n\n## Managing Payment Links\n\n### Creating a Payment Link\n\nPayment Links provide a versatile way to request payments by generating a unique URL that you can share with your customers. Here's how to create one:\n\n```ts\nconst paymentLink = await client.createPaymentLink({\n  name: 'Subscription Service',\n  items: [{ price: 'PRICE_ID', quantity: 1, adjustable_quantity: false }],\n  after_completion_message: 'Thank you for your subscription!',\n  locale: 'en',\n  pass_fees_to_customer: true,\n  collect_shipping_address: true,\n  metadata: { subscriptionId: 'sub_12345' },\n});\n```\n\nThis creates a new payment link with specified details and returns the payment link object including the URL to be shared with your customers.\n\n### Updating a Payment Link\n\nTo update an existing payment link:\n\n```ts\nconst updatedLink = await client.updatePaymentLink('PAYMENT_LINK_ID', {\n  name: 'Updated Subscription Service',\n  after_completion_message: 'Thank you for updating your subscription!',\n  metadata: { subscriptionId: 'sub_67890' },\n});\n```\n\nThis updates the specified payment link and returns the updated object.\n\n### Fetching a Payment Link\n\nRetrieve the details of a specific payment link:\n\n```ts\nconst linkDetails = await client.getPaymentLink('PAYMENT_LINK_ID');\n```\n\nThis call retrieves the specified payment link's details.\n\n### Listing Payment Links\n\nTo list all your payment links:\n\n```ts\nconst allLinks = await client.listPaymentLinks();\n```\n\nThis returns a paginated list of all payment links you've created.\n\n\n## About Chargily Pay™ packages\n\nChargily Pay™ packages/plugins are a collection of open source projects published by Chargily to facilitate the integration of our payment gateway into different programming languages and frameworks. Our goal is to empower developers and businesses by providing easy-to-use tools to seamlessly accept payments.\n\n## API Documentation\n\nFor detailed instructions on how to integrate with our API and utilize Chargily Pay™ in your projects, please refer to our [API Documentation](https://dev.chargily.com/pay-v2/introduction). \n\n## Developers Community\n\nJoin our developer community on Telegram to connect with fellow developers, ask questions, and stay updated on the latest news and developments related to Chargily Pay™ : [Telegram Community](https://chargi.link/PayTelegramCommunity)\n\n## How to Contribute\n\nWe welcome contributions of all kinds, whether it's bug fixes, feature enhancements, documentation improvements, or new plugin/package developments. Here's how you can get started:\n\n1. **Fork the Repository:** Click the \"Fork\" button in the top-right corner of this page to create your own copy of the repository.\n\n2. **Clone the Repository:** Clone your forked repository to your local machine using the following command:\n\n```bash\ngit clone https://github.com/Chargily/chargily-pay-javascript.git\n```\n\n3. **Make Changes:** Make your desired changes or additions to the codebase. Be sure to follow our coding standards and guidelines.\n\n4. **Test Your Changes:** Test your changes thoroughly to ensure they work as expected.\n\n5. **Submit a Pull Request:** Once you're satisfied with your changes, submit a pull request back to the main repository. Our team will review your contributions and provide feedback if needed.\n\n## Get in Touch\n\nHave questions or need assistance? Join our developer community on [Telegram](https://chargi.link/PayTelegramCommunity) and connect with fellow developers and our team.\n\nWe appreciate your interest in contributing to Chargily Pay™! Together, we can build something amazing.\n\nHappy coding!\n\n","readmeFilename":"README.md"}