Awardit Voucher Adapter

Overview Document: Payment Adapters Overview

Overview and Unique Capabilities

The Awardit Adapter integrates Awardit gift cards and loyalty rewards with Norce Checkout. This page focuses on the unique technical details and configuration for Awardit.

Voucher Operations Supported

• Gift card validation and balance check
• PIN/secret digits verification (when required by card configuration)
• Multiple gift cards per order (split payment across cards)
• Automatic amount calculation based on remaining order total
• Real-time balance updates when cart or shipping changes
• Selling (issuing) new Awardit gift cards as cart items, see Selling Awardit Gift Cards

Limitations

• Partial Capture is not supported (gift cards are redeemed in full for the covered amount).
• Partial Refund is not supported.
• Authorization expires after 24 hours.
• Card currency must match order currency.
• Only redeemOnOrderCompleted capture mode is currently supported.
• The gift card amount is capped at the order total including shipping. With Qliro integrated shipping this requires Qliro to allow negative order totals on the merchant account, otherwise the gift card fails with NEGATIVE_ORDER_TOTAL_NOT_SUPPORTED. See Gift Cards with Qliro Integrated Shipping.

Configuration in Norce Admin

The adapter is configured using the following unique details obtained from Awardit:

Optional Configuration

Voucher Capture Mode

The Awardit Adapter uses a two-phase commit pattern for gift card redemption:

1. Authorization Phase: When the order moves to Processing state, the adapter authorizes (reserves) the gift card amount with Awardit. This reservation expires after 24 hours.

2. Commit Phase: When the order moves to Completed state, the adapter commits the reservation, permanently deducting the amount from the gift card balance.

If the order returns to Checkout state before completion, the authorization is automatically released, making the funds available on the gift card again.

Adding a Gift Card Payment

To add a gift card to an existing Norce Checkout order:

POST /api/checkout/v1/orders/{order_id}/payments
Host: {slug}.api-se.stage.norce.tech
x-merchant: {merchant}
x-channel: {channel}
Authorization: Bearer {token}
Content-Type: application/json

{
    "cardId": "3141592653589793",
    "code": "23846"
}

The code field contains the PIN/secret digits and is optional depending on the card configuration.

Using Multiple Gift Cards

Customers can add multiple gift cards to cover an order total. Each card covers a portion of the remaining balance. The adapter automatically calculates the optimal amount for each card based on the remaining uncovered order total.

Removing a Gift Card

To remove a gift card from an order:

POST /api/checkout/v1/orders/{order_id}/payments/{payment_id}/remove
Host: {slug}.api-se.stage.norce.tech
x-merchant: {merchant}
x-channel: {channel}
Authorization: Bearer {token}

This performs a soft delete, setting the payment state to removed. If the payment was already authorized (Reserved state), the adapter automatically releases the authorization with Awardit.

Selling Awardit Gift Cards (issueGiftCard)

In addition to redeeming gift cards as payment, the Awardit Adapter can sell gift cards: when a Norce Checkout order contains a gift card product and the order is completed, the adapter issues a new Awardit gift card for each unit through the Awardit mvalue v2 API and stores the issued card details on the cart item. The feature is optional and is off unless the issueGiftCard configuration section is present. Merchants that only redeem gift cards see no behaviour change.

Selling a gift card requires three things:

1. Configuration in Norce Admin: apiSettings.v2 credentials and an issueGiftCard section mapping cart items to Awardit templates.
2. A gift card product in the cart, identified either by sku (issueGiftCard.templates) or by product type GiftCard (issueGiftCard.fallback).
3. A call to enable-sell for each order that should issue gift cards. The configuration alone never affects an order; the frontend must opt the order in while it is still in Checkout state.

Prerequisites for selling Awardit gift cards

Before configuring gift card selling, ensure you have:

• An active Awardit Adapter configuration for the merchant/channel (apiSettings.baseUrl, username, password, shopId).
• Awardit mvalue v2 API access: a base URL (for example https://api-stage-giftcards.awardit.com for stage) and OAuth2 client credentials (clientId, clientSecret) obtained from Awardit.
• One or more Awardit gift card templates created by Awardit for your shop. You need the numeric template id for each. A template controls the card currency, allowed amount range, issuing period, distribution types (external, email, sms) and whether a PIN is required.
• Gift card products in Norce Commerce with a known sku, or with the product type GiftCard when using the fallback template.

Configuration in Norce Admin for selling gift cards

Add the v2 block under apiSettings and the issueGiftCard section to the Awardit Adapter configuration in Norce Admin (NCO Configuration API):

{
  "apiSettings": {
    "baseUrl": "https://api.awardit.com",
    "username": "username",
    "password": "password",
    "shopId": "shop-id",
    "v2": {
      "baseUrl": "https://api-stage-giftcards.awardit.com",
      "clientId": "client-id",
      "clientSecret": "client-secret"
    }
  },
  "issueGiftCard": {
    "templates": [
      { "sku": "GIFTCARD-500", "templateId": 1234 },
      { "sku": "GIFTCARD-1000", "templateId": 1235 }
    ],
    "fallback": { "productType": "GiftCard", "templateId": 1240 }
  }
}

The existing apiSettings (v1) credentials are still required and are used for redeeming gift cards as payment. The apiSettings.v2 credentials are only used for the mvalue v2 GetTemplate and IssueCard calls.

Gift card selling is enabled for a merchant/channel when the issueGiftCard section is present and has at least one templates entry or a fallback. A sku mapping always wins over the fallback. Cart items that match neither a sku mapping nor the fallback product type are ignored.

Enabling gift card selling per order (enable-sell)

Gift cards are only issued for orders where the frontend has explicitly called the enable-sell endpoint. Call it once the order contains gift card items and while the order is still in Checkout state, typically right before the customer proceeds to payment:

POST /api/checkout/v1/orders/{order_id}/gift-card/enable-sell
Host: {slug}.api-se.stage.norce.tech
x-merchant: {merchant}
x-channel: {channel}
Authorization: Bearer {token}

The endpoint returns 204 No Content on success. It does not issue any gift card itself. It registers an order-scoped /state hook on the Norce Checkout order (hook reference awardit-gift-card-issuing, target /cart/items) that calls the Awardit Adapter when the order state changes. The endpoint is idempotent: calling it again for an order that already has the hook succeeds without registering a duplicate.

Validation performed by enable-sell:

Gift card issuing flow on order state changes

Once enable-sell has registered the hook, the Awardit Adapter reacts to the following order state transitions:

1. Processing (the customer has paid): the adapter validates every gift card item against its Awardit template. If validation fails the transition is rejected with one of the error codes listed in Gift card selling error codes, and the order stays in its previous state.
2. Completed: the adapter issues one Awardit gift card for each unit of each gift card item and writes the card details to the cart item attributes. If Awardit fails, the Completed transition is rejected so it can be retried. Issuing is idempotent: retries use a deterministic idempotency key and skip units that already have card details on the item, so a retry never issues duplicate cards.

The amount of each issued card is the cart item unit price including VAT (total.includingVat / quantity). If the Awardit template has a fixed amount (template minimum equals maximum), the template amount is used instead.

Orders without gift card items, and orders where enable-sell was never called, are not affected.

Gift card distribution (email, SMS or external)

How the issued gift card reaches the recipient is decided per cart item, based on the distribution types supported by the Awardit template and optional cart item attributes:

Resolution rules:

• If neither giftCardChannel nor giftCardRecipient is set and the template supports external distribution, no distribution is requested from Awardit. The card details are only stored on the cart item, and the merchant is responsible for delivering the card (for example printing it or showing it on the order confirmation).
• Otherwise the channel is giftCardChannel when set, else email when the template supports it and a recipient email is available (or SMS is not supported), else sms.
• The recipient is giftCardRecipient when set, else the order shipping address email (for email) or phone (for sms). If no recipient can be resolved, the order fails with awardit-gift-card-recipient-missing.

The attributes are set on the cart item attributes object through the Norce Checkout Order API (or by the Norce adapter from Norce Commerce basket item info types, depending on your storefront integration) before the order moves to Processing. A gift card cart item on the Norce Checkout order that is sent by email to a specific recipient on a scheduled date looks like this:

{
  "id": "item-1",
  "sku": "GIFTCARD-500",
  "quantity": 1,
  "total": { "includingVat": 500.00, "excludingVat": 500.00 },
  "attributes": {
    "giftCardChannel": "email",
    "giftCardRecipient": "recipient@example.com",
    "giftCardSendAt": "2026-12-24T07:00:00+01:00",
    "giftCardMessage": "Merry Christmas!"
  }
}

All four attributes are optional. If none of these attributes are provided, the distribution method is selected automatically using the following priority:

1. external distribution is used if the Awardit template supports it. Awardit sends no email or SMS; the card details are only stored on the cart item.
2. Otherwise email to the shipping address email is used if the template supports email and at least one of the following is true: the shipping address has an email, or the template does not support sms.
3. Otherwise sms to the shipping address phone is used if the template supports sms.
4. If the template supports none of external, email or sms, the order fails with awardit-gift-card-template-not-available. If email or sms was selected but the shipping address has no email or phone respectively, the order fails with awardit-gift-card-recipient-missing.

Issued gift card details on the cart item

After the order is Completed, the issued card details are available in the cart item attributes. For a quantity of 1 the key is awardit; for higher quantities one key per unit is written as awardit_0, awardit_1, and so on.

"attributes": {
  "awardit": {
    "cardId": "3141592653589793",
    "cardCode": "ABCD-EFGH-IJKL",
    "transactionId": "9f1c2a...",
    "templateId": 1234,
    "distribution": "email",
    "validThru": "2027-09-14T00:00:00.0000000+00:00",
    "cardPin": "1234"
  }
}

Gift card selling error codes

Troubleshooting (Awardit Specific)

In addition to the generic troubleshooting steps:

• Verify the gift card status directly with Awardit if needed.
• Check the Norce order payment state and attributes for error details.
• Review the payment transactions on the order for an audit trail of all operations.

Error Codes

Links and References

• Awardit Adapter OpenAPI Specification
• Awardit Developer Documentation (contact Awardit for API documentation)