> Portal Navigation: > > - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version. > - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages). > - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`). > - Top-level index of all portals: https://dev.wix.com/docs/llms.txt > - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt ## Resource: Introduction ## Article: Introduction ## Article Link: https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/payments/gift-cards/gift-cards-service-plugin/introduction.md ## Article Content: # About the Wix eCommerce Gift Cards/Vouchers Service Plugin
__Important:__ - The Wix eCommerce Gift Cards service plugin is available for both REST and SDK integrations. Due to npm package naming limitations, the SDK version is named "Gift Vouchers service plugin". Both names refer to the same extension and provide identical functionality, and may be used interchangeably throughout this introduction. - When developing websites or building apps with Blocks, use [Velo service plugins](https://dev.wix.com/docs/velo/events-service-plugins/about-events-service-plugins-and-the-sdk.md).
The Wix eCommerce Gift Cards Provider Service Plugin allows you to integrate with Wix as a gift card service provider, enabling Wix merchants to utilize your gift card functionalities directly on their sites, providing a seamless experience for their customers. By integrating your service with Wix, you can facilitate key gift card operations such as balance retrieval, redemption, and voiding transactions. These operations are seamlessly integrated into the site's checkout page, enhancing the overall customer experience. The integration process involves creating an app in the Wix App Market via the Wix Studio workspace, and configuring the Gift Cards Provider [service plugin](https://dev.wix.com/docs/build-apps/develop-your-app/extensions/backend-extensions/service-plugins/about-service-plugin-extensions.md). ## Use cases - [Provide gift card data in response to a Get Balance request](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/payments/gift-cards/gift-cards-service-plugin/sample-flows.md#retrieve-a-gift-card) - [Redeem a gift card in response to a Redeem request](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/payments/gift-cards/gift-cards-service-plugin/sample-flows.md#redeem-a-gift-card) - [Void a transaction in response to a Void request](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/payments/gift-cards/gift-cards-service-plugin/sample-flows.md#void-a-transaction) ::::tabs :::REST_TAB ## Get started To enable Wix to communicate with your app: 1. Go to [Extensions](https://dev.wix.com/docs/build-apps/develop-your-app/extensions/about-extensions.md) in your app's dashboard. 1. Click **+ Create Extension** in the top right. 1. Find **Gift Cards Provider** and click **+ Create**. 1. Use the JSON editor to create the extension's configuration file. Configure the parameters by referencing the table below or the **Documentation** section to the right of the editor. For each parameter, add the parameter name and value in the JSON editor. | Name | Type | Description | | ---------------- | ------ | -------------------------------------------------------------------------------------------------------------------- | | `deploymentUri` | string | Required. Base URI where the endpoints are called. Wix eCommerce appends the endpoint path to the base URI. For example, to call the Balance Retrieval endpoint at `https://my-gift-cards.com/v1/getBalance`, the base URI you provide here is `https://my-gift-cards.com/`. | | `componentName` | string | Unique name for this component, that appears only in the app dashboard. | When a site owner installs and authorizes your app to provide gift card operations, Wix will send a JSON Web Token (JWT) with an instance ID to your deployment URI + endpoint path. The app should collect the JWT, decode it, and store the resulting instance ID. For example, the token in this request: ```curl $ curl -X POST https://ext-server.com/wix-spi/account-ids -H 'Content-Type: plain/text' -d 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpbnN0YW5jZUlkIjoiMDQ0NjY3ZjQtYzEzZi00NmMyLTg1MDYtZGU5ZTQyMjkzODk2In0.fxedHrnHUFi6V- S5OH8gL-pY4STxFWZHjj-xo9QUwQY' ``` Decodes into: ```json { "instanceId": "044667f4-c13f-46c2-8506-de9e42293896" } ``` ::: :::SDK_TAB ## Get started Follow these steps to begin implementing your service plugin: ### Step 1 | Choose a framework You can implement this service plugin with the following [frameworks](https://dev.wix.com/docs/build-apps/get-started/overview/wix-s-development-frameworks.md): + **Wix CLI:** Learn how to [implement a service plugin with the CLI and the SDK](https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/wix-cli/supported-extensions/backend-extensions/service-plugins/add-service-plugin-extensions-with-the-cli.md). + **Self-hosted:** Learn how to [implement a self-hosted service plugin with the SDK and the Wix Dev Center](https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/self-hosting/supported-extensions/backend-extensions/add-self-hosted-service-plugin-extensions-with-the-sdk.md). ### Step 2 | Configure your service plugin To configure and customize your plugin, you need to provide important information in the service plugin configuration file. You can [configure your plugin in the Wix Dev Center](https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/self-hosting/supported-extensions/backend-extensions/add-self-hosted-service-plugin-extensions-with-the-sdk.md#step-1--add-a-service-plugin-extension-to-your-app). For details, see [Gift Vouchers Provider Extension Configuration](https://dev.wix.com/docs/rest/business-solutions/e-commerce/payments/gift-cards/gift-cards-service-plugin/extension-config.md). ### Step 3 | Define handler functions Use [`giftVouchersProvider.provideHandlers()`](https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/self-hosting/supported-extensions/backend-extensions/add-self-hosted-service-plugin-extensions-with-the-sdk.md#step-4--define-handler-functions) to define the following handler functions that implement your custom business logic. Make sure you define all required functions. | Function | Required | |-----------------------------|----------------| | [`getBalance()`](https://dev.wix.com/docs/rest/business-solutions/e-commerce/payments/gift-cards/gift-cards-service-plugin/get-balance.md) | Yes | | [`redeem()`](https://dev.wix.com/docs/rest/business-solutions/e-commerce/payments/gift-cards/gift-cards-service-plugin/redeem.md) | Yes | | [`_void()`](https://dev.wix.com/docs/rest/business-solutions/e-commerce/payments/gift-cards/gift-cards-service-plugin/void.md) | Yes | ## Code examples Below is an example for implementing the Gift Vouchers Provider service plugin in your code. ### CLI: Basic code structure This is the basic code structure for implementing the Gift Vouchers Provider service plugin with the Wix CLI: ```js import { giftVouchersProvider } from '@wix/ecom/service-plugins' giftVouchersProvider.provideHandlers({ getBalance: async (payload) => { const {request, metadata} = payload; // Add your logic here }, redeem: async (payload) => { const {request, metadata} = payload; // Add your logic here }, void: async (payload) => { const {request, metadata} = payload; // Add your logic here } }); ``` ### Self-hosted: Basic code structure This is the basic code structure for implementing a self-hosted Gift Vouchers Provider service plugin: ```js import { createClient } from '@wix/sdk'; import { giftVouchersProvider } from '@wix/ecom/service-plugins' const wixClient = createClient({ auth: { appId: , publicKey: }, modules: { giftVouchersProvider } }); wixClient.giftVouchersProvider.provideHandlers({ getBalance: async (payload) => { const { request, metadata } = payload; // Add your logic here }, redeem: async (payload) => { const { request, metadata } = payload; // Add your logic here }, void: async (payload) => { const { request, metadata } = payload; // Add your logic here } }); // Implement a router to process all requests express.post('/plugins-and-webhooks/*', (req, res) => { wixClient.process(req); }); ``` ::: :::: ## Terminology - **Redeem**: Applying a gift card balance to a purchase, including subtracting the applied value from the gift card balance. - **Void**: Reversing a redeem action and returning the applied value to the gift card balance. ## See also + [About Service Plugin Extensions](https://dev.wix.com/docs/build-apps/develop-your-app/extensions/backend-extensions/service-plugins/about-service-plugin-extensions.md) + [Add a Service Plugin Extension With the CLI](https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/wix-cli/supported-extensions/backend-extensions/service-plugins/add-service-plugin-extensions-with-the-cli.md) + [Add a Self-hosted Service Plugin With the SDK](https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/self-hosting/supported-extensions/backend-extensions/add-self-hosted-service-plugin-extensions-with-the-sdk.md) + [Add Self-hosted Service Plugin Extensions with REST](https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/self-hosting/supported-extensions/backend-extensions/add-self-hosted-service-plugin-extensions-with-rest.md)