Commerce Wrapped

Lets customers of a Drupal Commerce shop pay with Wrapped gift cards at checkout, and keeps every card's balance in step with Wrapped, so the same card works in your shop, on your POS and online.

Wrapped is a gift card service for retailers, restaurants and hospitality groups. It holds the balance of every gift card you sell, wherever the card is sold or spent: in your shop, through a point-of-sale (till) integration, or on another web store. Drupal Commerce is the online shop add-on for Drupal.

Without this module, a Wrapped gift card can't be used on a Drupal Commerce site. With it, the customer types the card's code at checkout. The module checks the code with Wrapped, takes the card's balance off the order total, and tells Wrapped how much was spent when the order is placed. Refunds and cancelled orders put the money back on the card. You can also sell Wrapped gift cards on your site.

Features

The basics:

• Pay with gift cards at checkout. A "Wrapped gift card" field for your checkout. The card pays the smaller of its balance and the order total, after discounts, shipping, fees and tax. The customer pays anything left by card as usual. Several gift cards can be used on one order.
• One balance everywhere. Wrapped keeps the balance, so a card topped up or spent in your shop has the right balance online straight away.
• Refunds and cancellations. A "Refund to gift card" tab on each order, and an optional setting to put the money back automatically when a placed order is cancelled.
• Sell Wrapped gift cards. Mark a product type as a gift card. Each card bought is created in Wrapped once the order is paid, and Wrapped can email it to the buyer or to a recipient they name.

What makes it safe to rely on:

• Balances are checked again just before payment. If a card was spent in your shop, voided or expired since the customer entered it, checkout stops and shows the updated total.
• A card is never charged twice. If Wrapped can't be reached, the change is queued and retried automatically. Wrapped recognises a repeat and doesn't apply it again.
• Protection against code guessing. After too many wrong codes from one visitor, further attempts are refused for a while.
• Codes are kept out of sight. Only the last four characters are stored on orders or shown in logs.
• Secrets stay out of exported configuration. The API key and webhook token are read from settings.php, an environment variable or the Key module.

Two ways to use it:

• On its own. Install Commerce Wrapped and use its own checkout field, refund tab and gift card products. Nothing else is needed.
• With Commerce Gift Card. Also enable the included Commerce Wrapped: Gift Card submodule if you use, or want, Commerce Gift Card. Its checkout field, refund form, bulk card generation and admin list of cards then all work with Wrapped cards. Changes made in Wrapped come back to Drupal through webhooks and a regular catch-up on cron.

When to use it:

• You already sell Wrapped gift cards in a shop, bar or restaurant, and want them accepted on your Drupal Commerce site.
• You want gift cards sold online to be usable in your shop, through Wrapped's POS integrations.
• You use Commerce Gift Card and want its cards shared with your other sales channels.

Post-Installation

1. Get an API key from Wrapped. In Wrapped, go to Settings › Integrations and API keys and create a key. Give it to Drupal in one of these ways (never in the settings form, so it doesn't end up in exported configuration):
   • add $settings['commerce_wrapped_api_key'] = '...'; to settings.php;
   • set the COMMERCE_WRAPPED_API_KEY environment variable on your server;
   • with the Key module, store it as a key and choose that key in the settings form.
2. Switch it on. Go to Commerce › Configuration › Wrapped gift cards (/admin/commerce/config/wrapped). Tick "Talk to Wrapped" and enter your Wrapped account's currency, such as GBP or USD. The page shows whether the connection works. You can also choose which of your stores accept Wrapped cards.
3. Add the gift card field to checkout. Go to Commerce › Configuration › Checkout flows, edit your flow and drag the Wrapped gift card pane into a step, for example "Order information".
   • With the Commerce Gift Card submodule, use Commerce Gift Card's Gift card redemption pane instead.
   • Then choose which gift card type holds Wrapped cards at /admin/commerce/config/wrapped/giftcard.

   Use one pane or the other in a checkout flow, not both.

4. Set up webhooks (needed with the submodule; optional otherwise). Webhooks are how Wrapped tells your site that a card changed. Choose a long random verification token, and give it to Drupal as $settings['commerce_wrapped_webhook_token'] or the COMMERCE_WRAPPED_WEBHOOK_TOKEN environment variable. Then run:
   
   drush --uri=https://www.example.com commerce-wrapped:webhook-register
5. Make sure cron runs. Cron sends again any change Wrapped couldn't receive the first time, and with the submodule catches up on changes made in Wrapped.
6. Optional: sell gift cards.
   • On a product variation type, tick the Sells Wrapped gift cards trait. Each variation gets a "Gift card value"; when it's empty, the price is used.
   • To let buyers send the card to someone else, tick Wrapped gift card recipient on the order item type and show its fields on the add-to-cart form.

Important: Wrapped has no test mode. Every API key works on your live account, so a test order spends a real card. Test with cards made for testing, then void them in Wrapped. If you run more than one copy of your site (live, staging, test), give each its own "Idempotency ID prefix" under Advanced in the settings. Otherwise Wrapped may refuse a test order's changes as repeats of live ones.

Check the setup from the command line with drush commerce-wrapped:status. Look a card up with drush commerce-wrapped:card CODE, which prints only the last four characters of the code.

Additional Requirements

• Drupal 10.3 or later, or Drupal 11
• Drupal Commerce 3.x, with its Checkout, Order, Price and Store modules
• A Wrapped account on a plan with API access (Pro and above)
• The Wrapped REST API, reached from your server over HTTPS
• For the Commerce Wrapped: Gift Card submodule only: Commerce Gift Card 2.x

Recommended modules/libraries

• Key: store the API key and webhook token in the key provider of your choice instead of settings.php or environment variables.
• Commerce Gift Card: through the included submodule, adds an admin list of cards, bulk code generation and its own refund form.

Similar projects

• Commerce Gift Card keeps gift cards entirely inside Drupal. On its own, its cards can only be used on your Drupal site. Commerce Wrapped connects to Wrapped, so the same cards also work in your shop and on your other channels. The two work together through the included submodule.
• Commerce's built-in coupons (Commerce Promotion) are discounts, not stored balances. A coupon takes money off. A gift card is a payment, with a balance that goes down as it's spent and back up when an order is refunded.

Supporting this Module

Bug reports, feature requests and patches are welcome in the issue queue. Testing against your own Wrapped account and reporting how it went is especially useful, because Wrapped has no sandbox to test against automatically.

Community Documentation

• The README.md in the module covers setup, how money moves between Drupal and Wrapped, and the Drush commands.
• Wrapped API guide
• Wrapped help center

Payment gateways

A gift card shows on the order as an adjustment (wrapped_gift_card, or commerce_giftcard with the submodule) that lowers the amount left to pay. Most payment gateways charge the amount left and need nothing extra. A gateway that rebuilds the order from its line items, such as a Stripe Checkout Session, has to take these adjustments off its lines. Otherwise it charges too much, or refuses the order.

For developers

• hook_commerce_wrapped_order_allowed_alter() decides which orders may be paid with Wrapped cards, beyond the store setting. For example, use it to keep gift cards off B2B orders.
• Events: WrappedEvents::CARD_CREATED, WrappedEvents::OPERATION_FAILED and WrappedEvents::WEBHOOK.
  • Subscribe to OPERATION_FAILED to alert staff when Wrapped refuses a change.
  • By then the rest of the order has been paid, so the card needs putting right by hand in Wrapped.
• WrappedClient wraps the parts of the Wrapped API the module uses.

This module is not made by, or affiliated with, Wrapped. "Wrapped" is a trademark of its owner.