Skip to main content

Integrating a gift card provider

Integrate gift card providers with NewStore Omnichannel Cloud, to accept payments via physical and virtual gift cards from your customers on NewStore Associate App and issue refunds as gift cards.

To integrate with a gift card provider, develop an adapter that uses the Gift Card webhooks. An adapter serves as an intermediary or integration layer that communicates with NewStore Omnichannel Cloud on one side, and with the gift card provider you integrate with on the other side. Additionally, ensure that the gift card provider is added as a payment provider in NewStore. See Configuring gift cards as products and Configuring gift cards as a payment strategy for more information.

Selling gift cards​

Gift cards exist as products in NewStore. However, all gift card denominations are identified by the same SKU. For example, if you sell gift cards for 300USD and 500USD, displaying these values as products in NewStore Associate App requires extra configuration.

To sell gift cards:

  1. Import gift cards as products into NewStore Omnichannel Cloud. See Creating product data .

  2. To display different gift card denominations in NewStore Associate App, define an extended attribute pricebooks in the product data for the gift card. In the value for pricebooks add the price books for the gift card as a comma separated string. NewStore uses the prices for the gift card in the price books included here, to display the gift card values as a list in NewStore Associate App.

~~~ json
{
  "extended_attributes": [
    {
      "name": "pricebooks",
      "value": "gift-card-300,gift-card-500"
    }
  ]
}
~~~
  1. Import a price book for each gift card denomination you want to sell. See Creating price book data . For example, to sell gift cards for 300USD and 500USD, import two price books gift-card-300 and gift-card-500, and add the gift card product ID to both price books with different prices.
~~~ json
{
  "head": {
  "pricebook": "gift-card-300",
  "shop": "storefront-catalog-en",
  "currency": "USD"
  },
    "items": [
      {
        "product_id": "GC-NEWSTORE",
        "value": 300.00
      }
    ]
}
~~~

  1. In NewStore, ensure that your app is configured to identify the products that match gift cards in your catalog. To enable this feature, contact the support team.

    Important

    The regular expression matching is NOT case-sensitive, which means ^([a-z]*)$ will be matched with both abc and ABC. Associates might type in lower or upper case letters when manually entering a gift card number. The integration must handle situations where the gift card provider requires the gift card number typed in a specific case.

    To correctly extract the gift card's serial from the scanned barcode, you need to provide a (capture group)[https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Regular_expressions/Capturing_group]. You can capture the whole number or just part of it depending on your integration. An expression like ^SVS_GC-(\\d{15})$ will match all scanned codes that start with SVS_GC- but only extract the number following this pattern as the actual gift card number.

    See Configuring gift cards as products .

  2. To enable associates to sell gift cards, implement the Activate gift card webhook. NewStore Omnichannel Cloud calls this method on your adapter when the gift card is scanned as a product on NewStore Associate App, during a sale. Since the gift card number is already available during checkout, the gift card is already issued and only needs activation by the gift card provider.

Here's how the integration works:

sequenceDiagram participant NewStore participant Adapter participant GC as Gift Card Provider Note left of NewStore: Sell gift card as a product activate NewStore NewStore->>Adapter: /gift_card/activate (POST) Adapter->>GC: Requests activation activate Adapter GC->>Adapter: Gift card activated deactivate Adapter Adapter->>NewStore: Sends activated gift card data deactivate NewStore

To add the gift card number into the sales receipt or gift card receipt templates for your business, note that the gift card number is stored as serial_number in the external_identifier property for the item.

Issuing gift cards as a refund​

If your business issues refunds via gift cards, NewStore Omnichannel Cloud triggers a request to issue either a physical gift card or an e-gift card, when the corresponding refund payment method is chosen on NewStore Associate App.

sequenceDiagram participant NewStore participant Adapter participant GC as Gift Card Provider Note left of NewStore: Refund via gift card NewStore->>Adapter: /gift_card/issue (POST) activate NewStore Adapter->>GC: Requests gift card issue activate Adapter GC->>Adapter: Gift card issued deactivate Adapter Adapter->>NewStore: Sends gift card data activate NewStore Note left of NewStore: Activate issued card NewStore->>Adapter: /gift_card/activate (POST) Adapter->>GC: Requests gift card activation activate Adapter GC->>Adapter: Gift card activated deactivate Adapter Adapter->>NewStore: Sends activated gift card data deactivate NewStore
  1. Implement the Issue gift card webhook. NewStore Omnichannel Cloud calls this method when a gift card is selected as the refund method when requesting refunds on NewStore Associate App, or when refunding via gift cards is set as the default refund strategy in NewStore Omnichannel Cloud. The gift card number is not available in NewStore Omnichannel Cloud at this point, and must be requested from the gift card provider and returned to NewStore Omnichannel Cloud in the response to this request.
  2. Based on your gift card provider, when the gift card is issued it may already be activated. If it is not, implement the Activate gift card webhook.

Enabling virtual gift card sales and refunds​

The steps to enable sales and refunds are the same for both virtual and physical gift cards. However, note that when virtual gift cards are issued or activated, details of the gift card are sent to the email address included in the Issue gift card webhook and Activate gift card webhook requests from NewStore Omnichannel Cloud.

Ensure that the email templates for these notifications are customized for your business. Use the following templates to send email notifications to a customer when a gift card is issued and activated:

  • gift_card_issued_email_body
  • gift_card_issued_email_subject
  • gift_card_issued_email_pn

Accepting payments via gift cards​

To accept payment via a gift card during checkout, implement the Return balance webhook. At checkout, when a gift card is chosen as the payment method, NewStore Omnichannel Cloud calls this method in your implementation.

Gift card payments are processed in the same way as payments made using other payment methods. Based on the balance returned, NewStore Omnichannel Cloud calls your PSP (payment service provider) integration to create a financial instrument for the amount and capture the payment. For more information on payment, capture and refund, also see Integrating a payment service provider .

sequenceDiagram participant NewStore participant Adapter participant GC as Gift Card Provider Note left of NewStore: Accept gift card during checkout NewStore->>Adapter: /gift_card/balance (POST) activate NewStore Adapter->>GC: Requests gift card balance activate Adapter GC->>Adapter: Balance returned deactivate Adapter Adapter->>NewStore: Sends balance Note left of NewStore: Customer is assigned to cart in Associate App and the sale is processed. deactivate NewStore

Idempotency guidelines​

The issue and activation requests contain idempotency keys to identify the request and enable automatic retries in case of processing failures or network errors. Ensure that you send the same response to each request you receive with a specific idempotency key. For example, if you receive 3 requests containing the idempotence_key property set to abc, whether the body has changed or not, send the same response to all 3 requests.

Related topics