CP Extender: API Gift Cards

To complete authorized transactions, please refer to CP Extender: Authorize

Controller: Giftcard

ReserveIds

Method: Giftcard/ReserveIds

Security: Bearer

Type: POST

URL: https://{{BaseUrl}}:{{Port}}/Giftcard/ReserveIds

Request Body:

{ "RequestName":"Web001", "RequestType":"pool", "PoolCount":10, "Agency":"Website" }

Gift Card reservations are used to represent a block of Gift Cards that were physically printed (or reserved for the website) so that newly generated gift card numbers do not overlap with the reserved block.

Request Name is an optional batch reference. Although in most cases, you would want this batch id to be unique, uniqueness is not enforced as there may be circumstances where multiple batches may be requested as part of the same RequestName. If no RequestName is entered, the batch will be grouped by DateTime.

Optional RequestType can be: single or pool. Default: single

All reservations for RequestType:single will be set as a Temporary Reservation and will expire if the card is not created within 1 hour.

PoolCount is ignored for RequestType:single

Agency is required and represents the Company or Campaign which the GC pool was requested for.

* Max GiftCard Count per batch is limited to a setting. Typically 500. If the PoolCount is greater than this setting value, the PoolCount will be reduced to the Max.

Response: HTTP Status 200

Response Body:

{
    "GiftCards": [
        "99-53235753896117470",
        "99-36031997041479042",
        "99-81763963807794691",
        "99-58504335524900568",
        "99-93039730381900456",
        "99-41923731872470201",
        "99-53986110152642044",
        "99-63765562191658989",
        "99-40678072221435293",
        "99-48349826419356375"
    ]
}

Errors:

400 Bad Request

500 Internal Server Error

Create

Method: Giftcard/Create

Security: Bearer

Type: POST

URL: https://{{BaseUrl}}:{{Port}}/Giftcard/Create

Request Body:

{
	"CustomerNumber":"2059378440",
	"GiftCardId":"99-53235753896117470",
	"GiftCardCode":"GC",
	"GiftCardValue":100,
	"SaleId":"123456789"
}

{
	"CustomerNumber":"2059378440",
	"GiftCardId":"99-53235753896117470",
	"GiftCardCode":"GC",
	"GiftCardValue":50,
	"PointsToRedeem":"5000"
}

Giftcards can be created on the fly by letting the system auto-assign a gift-card, or you may specify a Gift Card number from one that it was pre-generated using Giftcard/ReserveIds.

If auto-assigning a Gift Card number, do not include GiftCardId in your request.
If specifying a Gift Card number, a Gift Card Id must be present in your request and must also exist in the Card Reserve Pool. The system assumes that requested Gift Card Id's are part of either a pre-printed or pre-generated approved pool.

if creating a Gift Card from a loyalty point redemption, you must specify a positive value for PointsToRedeem.
Otherwise, a SaleId is required.

GiftCardValue is optional. If requesting to Create from a GiftCardCode that does not allow value changes, do not include GiftCardValue. In this case, the default value for the GiftCardCode will be used. If the GiftCardValue is passed and it is not the same as the Default value or the GiftCardCode specified does not allow Value Change, the request will be rejected.

Because some requests will auto-generate the Gift Card Id, the response will always return the Gift Card Id.

Response: HTTP Status 200
Response Body:

{
    "GiftCard": {
        "Id": "WEB-9198262557214413"
    }
}

Errors:

400 Bad Request

400 SaleId is Required

404 Gift Card Code Not Found

400 Gift Card Value must be greater than 0

400 GiftCardCode specified does not allow value change

404 Customer Not Found

400 GiftcardId Already Exists

400 GiftcardId Not Reserved

500 Internal Server Error

BalanceCheck

Method: Giftcard/BalanceCheck

Parameters: {{id}}

Security: Bearer

Type: GET

URL: https://{{BaseUrl}}:{{Port}}/Giftcard/{{id}}/BalanceCheck

Response: HTTP Status 200

Response Body:

{
    "GiftCard": {
        "Id": "WEB-9198262557214413",
        "Type": "giftcard",
        "Status": "active",
        "Balance": 100.00,
        "OpenAuthorizations": 0.0,
        "AvailableBalance": 100.00,
        "History": [
            {
                "Activity": "Issued",
                "Date": "02/25/2020",
                "Amount": 100.00,
                "Location": "Kirbys Gourmet Gifts",
                "Document": null
            }
        ]
    }
}

Errors:

404 Id not found

500 Internal Server Error

Certificate

Method: Giftcard/Certificate

Parameters: {{id}}

Security: Bearer

Type: GET

URL: https://{{BaseUrl}}:{{Port}}/Giftcard/{{id}}/Certificate

Response: HTTP Status 200

Response Body: This request returns a ByteArray with Mimetype "image/jpeg".

Errors:

404 Id not found

500 Internal Server Error

Authorize

Method: Giftcard/Authorize

Security: Bearer

Type: POST

URL: https://{{BaseUrl}}:{{Port}}/Giftcard/Authorize

Request Body:


{
   "Type":"giftcard",
   "Ref":"WEB-9198262557214413",
   "SaleId":"WB-100-10259",
   "RequestedAmount":40.00
}

Response: HTTP Status 200

Response Body:


{
    "RequestId": "0cb3fb5b-6b65-4d52-860e-33297f97fa2e",
    "Type": "giftcard",
    "AuthorizedAmount": 40.00,
    "AuthCode": "GDA17E1614ABBA6596E5B3BA3781B339B"
}

Errors:

400 Required: Type, Ref, SaleId, and (RequestedAmount or RequestedPoints)

400 Type is required

400 GiftCard has been voided

400 GiftCard has expired

400 No Balance Remaining

500 Internal Server Error

API Overview

API Customer

CP Extender: Loyalty Methods

CP Extender: Setup

CP Extender: API Authorization Events