E-commerce & Gift Card

Use Case Description

This use case describes the process of a customer purchasing a digital gift card from an external system, gifting it to a friend, and the friend subsequently using the gift card to make purchases on an e-commerce site.

Actors

Customer: Purchases and gifts the digital gift card.

E-commerce System: Handles the sale and validation of the gift card.

External System: Generates and manages the gift card details.

Preconditions

The external system must have the necessary permissions and access to the document creation service, please refer to Authentication.

APIs Used

Generate Giftcards: Generates digital gift cards.

Get Giftcard: Validates and retrieves gift card details.

Update Giftcard: Updates the gift card balance after a purchase.

Main Success Scenario

Purchase and Gift Generation:

The customer sends a request to the external system to generate a digital gift card using the Generate Giftcards API.

The external system processes the request and sends the generated gift card details back to the customer via a callback URL.

Gift Card Usage:

The recipient visits the e-commerce site and adds items to their cart.

At checkout, the recipient enters the barcode of the gift card.

The e-commerce site uses the Get Giftcard API to validate the gift card and check the available balance.

If the gift card is valid and has sufficient balance, the e-commerce site completes the order and uses the Update Giftcard API to deduct the purchase amount from the gift card balance.

Alternate Flows

Gift Card Generation Failure:

If the Generate Giftcards API fails (e.g., invalid itemCode), an error message is sent to the callback URL.

Invalid or Expired Gift Card:

If the Get Giftcard API indicates the gift card is invalid or expired, the e-commerce site informs the recipient, and the transaction cannot proceed.

Insufficient Balance:

If the gift card balance is insufficient to cover the purchase, the e-commerce site prompts the recipient to use an alternative payment method.

Example JSON Structure Generate Giftcards

Request

{
    "itemCode": "GIFTCARD_IVA_TAGLIO_100",
    "giftcards": 5,
    "callback": "https://webhook.site/..."
}

Successful Response

{
    "success": true,
    "giftcards":
    [
        {
            "barcode": "4443334961511",
            "startValidity": "2022-06-10 00:00:00",
            "endValidity": "2023-06-10 00:00:00"
        },
        {
            "barcode": "4448332511072",
            "startValidity": "2022-06-10 00:00:00",
            "endValidity": "2023-06-10 00:00:00"
        }
    ]
}

Error Response

{
    "success": false,
    "message": "itemCode not found"
}

Example JSON Structure Get Giftcard

Request

Successful Response

{
    "success": true,
    "giftcard":
    {
        "id": "SVILU_500_440_2000000001814",
        "companyId": "XXXX",
        "siteId": 500,
        "branchCode": 1,
        "entityCode": 440,
        "cardBarcode": "2000000001814",
        "issueDate": "2021-10-04 00:00:00",
        "activationDate": "2021-10-04 00:00:00",
        "expirationDate": "2021-11-04 00:00:00",
        "flgActive": "Y",
        "priceList": "1",
        "priceListType": "V",
        "decimalNumber": 2,
        "currencySymbol": "€",
        "currency": "EUR",
        "originalAmount": 390,
        "amount": 390,
        "itemType": "FINANCIAL",
        "itemSubtype": "GIFTCARD",
        "itemCode": "GF440VP15_400_3",
        "taxRate": 21,
        "vatCode": 3,
        "printerDepartmentCode": 1,
        "flgNetworkUsage": "Y",
        "flgPartiallyUsage": "Y",
        "paymentTermCode": 201,
        "flgAllowOfflineUsage": "N",
        "taxation": ""
    }
}

Error Response

{
    "success": false,
    "message": "barcode not found"
}

Example JSON Structure Update Giftcard

Request

{
    "entityCode": 440,
    "barcode": "0098260111383",
    "amount": -50.0
}

Successful callback Response

{
    "success": true,
    "id": "7571b744-8e2d-4dde-99d8-b60c0dff1aca"
}

Error callback Response

{
    "success": false,
    "message": "barcode not found"
}

Sequence Diagram

INFO

Please refer to Best Practices for Error Handling in External System for best practices on implementation.

E-commerce & Gift Card