Dintero

Omnium issues gift cards on the Dintero Wallets API. A gift card is created when an order containing a gift card product is processed, and Dintero returns a card code and a PIN that Omnium delivers to the customer by email.

The card is redeemed inside Dintero Checkout: the payer enters the code and the PIN in the Dintero payment step. Omnium does not reserve, capture or refund against the card.

Supported features

• Issue a gift card from an order line, for any amount (open amount or fixed denominations)
• Code and PIN delivered through an Omnium notification, with a designed email template
• Look up the remaining balance of a card by its code
• Redemption handled by Dintero Checkout

Not supported by this plugin:

Prerequisites

• Dintero Checkout must already be configured for the tenant - see Dintero (payments). Gift cards reuse the same account and API client.
• Wallets must be enabled on the Dintero account, and the API client must have the write:wallets scope. That single scope covers creating cards and reading card information.
• The gift card module must be active for the tenant - see Gift Cards.

Setup

1. Add the gift card connector

Go to Configuration → Settings → Advanced → Connectors and add:

{
  "name": "Dintero",
  "implementations": [
    "IGiftCardProvider"
  ]
}

2. Credentials

No separate payment type is needed. Gift cards read the credentials from the Dintero entry under Configuration → Settings → Payment → Payment Types, matched on either the payment method name or the provider name for the market. The fields used are:

3. Gift card product and order settings

Create a virtual gift card product (IsVirtual set to true), then go to Settings → Orders → Gift Cards:

The amount on the card is the price of the order line, so an open-amount gift card is simply a gift card product whose price the sales channel sets per order line. See Buying gift cards.

4. Workflow step

On the first order status (typically New), add the workflow step Create and send gift cards (v2) (CreateAndSendGiftCardsV2).

{
  "name": "CreateAndSendGiftCardsV2",
  "active": true,
  "properties": [
    { "key": "ChangeToStatus", "value": "VirtualShip" }
  ]
}

• ChangeToStatus moves the order to that status once every gift card line has a card. For a gift-card-only order the whole order moves; for a mixed order only the gift card shipment moves, and the physical items continue through normal fulfilment.
• Leave ChangeToStatus empty to create the cards without changing status.

The step also needs the VirtualShip order status and the VirtualShipment shipping method described on the Gift Cards page.

5. Notification

The code and PIN reach the customer through the Gift card bought message notification, under Configuration → Settings → Notifications.

• Set the To field to {GIFT_CARD_RECEIVER_EMAIL}. It falls back to the buyer's email when the order line carries no separate receiver.
• Fill in the From address. A notification whose sender is not a valid email address is discarded before it is sent or queued, while the order still records the notification as sent - an empty From therefore looks like a delivered email that never arrives. Use a literal address, or {STORE_EMAIL} to send from the order's store, which falls back to the market's default email address.
• Build the body in the email designer, which offers the gift card merge tags listed below.

Available merge tags:

The issued card

Omnium sends the following along to Dintero so the card can be traced from the Dintero backoffice:

• The Omnium order id as card metadata
• The buyer's email as the customer reference
• The receiver name as the card name

Each card gets its own unique card id, so an order containing several gift cards produces several distinct cards. A gift card line with a quantity above 1 is split into one line per card before the cards are created, so every card carries its own code, PIN and receiver properties.

Buying gift cards

Add the gift card product to a cart the same way as any other product. To let the customer choose the amount, add the order line with the gift card SKU and the selected price:

API endpoint: POST /api/Cart/{cartId}/OrderLines → Documentation

Optional order line properties controlling delivery of the card:

If the order contains only gift cards, the shipment added to the cart should be of type VirtualShipment. For mixed orders the workflow splits the gift card lines into their own virtual shipment automatically.

Checking a balance

API endpoint: GET /api/GiftCard/{code} → Documentation

The response reports the spendable balance - what remains after earlier redemptions.

An unknown code returns not found. A rejected credential or a Dintero outage returns the underlying status instead, so a configuration problem is never reported as a missing card.

Redeeming a gift card

Redemption happens entirely in Dintero Checkout. The payer selects the gift card option and enters the code and PIN from the email, and Dintero deducts the amount and settles the remainder with the ordinary payment method. Omnium sees only the resulting Dintero payment on the order.

Because of this, the Omnium gift card payment method, the cart gift card endpoints and the Reserve gift cards workflow step are not used with Dintero.