Gift Card Integration Use Cases

The purpose of this document is to outline all the possible gift card integration use cases developed by a Point-Of-Sale into Ackroo’s API. The scope of the use case document and coverage is decided by the gift card integration project plan from the POS to Ackroo. Ideally, all these use cases are implemented and tested by the POS developer to ensure full gift card functionality for Ackroo’s merchants.

 

Use Case 1 – Gift Card Issue

  1. Customer asks to purchase a new gift card for 10$

/device/card returns that card is not active and has no gift balance

/transaction/gift/issue activates and loads gift card with 10$

 

JSON request payload:

 {
 "device_id": "0d373af2942291bf",
 "cardnumber": "612573981949778930",
 ”amount”: “10”,
 “clerk_id”: “POS Clerk”
}

 2. Ackroo issues gift card (activates cards) and new gift balance returned is $10

 

 

Use Case 2 – Gift Card Issue on activated card

 1. Customer asks to issue a new gift card that’s already been issued to another customer

/device/card returns that card is already active and has a gift balance

/transaction/gift/issue throws a CardAlreadyActive error

 

JSON request payload:

{
 "device_id": "0d373af2942291bf",
 "cardnumber": "612573981949778930",
 ”amount”: “10”,
 “clerk_id”: “POS Clerk”
}

 2. Ackroo returns CardAlreadyActive error

 

Note: There are 2 redemptions modes with POS to Ackroo integration. The first mode is InsufficientFunds mode which denies a redemption if the amount to redeem is greater than the gift balance. The second mode is Partial Payment mode which redeems all available funds on a gift card if the amount to redeem is greater than the balance on the gift. This mode essentially never denies gift redemptions and allows other payment methods to be tendered while redeeming everything it can on the gift card up to maximum amount being the gift card balance.

 

These modes are ideally implemented as configuration options by the POS integration and offered to the merchant, or one mode is assumed to be always the preferred configuration based on the merchant line of business the POS sells into (restaurants, hospitality, etc)

 

 

Use Case 3 – Gift Card Redeem

1. Customer spends 5$ at the store and wants to redeem gift

/device/card returns outstanding gift balance gc_balance

/transaction/gift/debit redeems gift for amount specified

 

JSON request payload:

{
 "device_id": "4b28fd4d7f23d301",
 "cardnumber": "637738991414324630",
 ”amount”: “5”,
 “clerk_id”: “POS Clerk”
}

 2. Ackroo debits 5$, new gift balance is gc_balance - 5$

 

 

Use Case 4 – Gift Card Redeem on InsufficientFunds

 1. Customer spends 50$ at the store and wants to redeem gift:

/device/card returns outstanding gift balance gc_balance

 /transaction/gift/debit redeems gift

 

JSON request payload:

 {
 "device_id": "4b28fd4d7f23d301",
 "cardnumber": "637738991414324630",
 ”amount”: “50”,
 “clerk_id”: “POS Clerk”
}

 2. Ackroo returns InsufficientFunds and payment is denied

 

 

Use Case 5 – Gift Card Redeem in Partial Payment Mode

 1. Customer spends 50$ at the store and wants to redeem gift (gift balance is less than 50$):

 /device/card returns outstanding gift balance gc_balance

/transaction/gift/debit/partial redeems gift as partial payment

 

JSON request payload:

 {
 "device_id": "4b28fd4d7f23d301",
 "cardnumber": "637738991414324630",
 "amount”: “50”,
 “clerk_id”: “POS Clerk”
}

 2. Ackroo debits total gift balance amount returned on check balance gc_balance in Step 1, new gift balance is 0

 

 

Use Case 6 – Gift Card Reload

 1. Customer reloads gift card in store with 10$

/device/card returns card is active and the outstanding gift balance gc_balance

 /transaction/gift/credit reloads gift card

 

JSON request payload:

{
 "device_id": "4b28fd4d7f23d301",
 "cardnumber": "637738991414324630",
 "amount”: “10”,
 “clerk_id”: “POS Clerk”
}

 2. Ackroo loads gift card and new gift balance returned is gc_balance  + 10

 

 

Use Case 7 – Gift Card Fund Reversal

 1. Customer reloads gift card in store with 10$

 /device/card returns card is active and the outstanding gift balance gc_balance

/transaction/gift/credit reloads gift card

 

JSON request payload:

{
 "device_id": "4b28fd4d7f23d301",
 "cardnumber": "637738991414324630",
 "amount”: “10”,
 “clerk_id”: “POS Clerk”
}

2. Ackroo loads gift card and new gift balance returned is gc_balance  + 10, transaction number returned is txn_id

3. Merchant decides to reverse the gift load transaction

/transaction/reversal reverses the transaction by txn_id

 

JSON request payload:

{
 "device_id": "4b28fd4d7f23d301",
 "transaction_number": “txn_id “
}

 4. Ackroo reverses the transaction for txn_id, returns new balance which has the gift fund amount reversed, new balance equals the original gc_balance 

 

 

Use Case 8 – Gift Card Cashout

 1. Customer wants to cashout the balance on his gift card in store

 /device/card returns card is active and the outstanding gift balance gc_balance

 /transaction/gift/debit/cash debits all the balance on the gift card

 

JSON request payload:

{
 "device_id": "4b28fd4d7f23d301",
 "cardnumber": "637738991414324630” ,
 “clerk_id”: “POS Clerk”
}

2. Ackroo debits the outstanding balance on gift card and new gift balance returned is 0, amount returned as debited is total balance on card

 

 

Use Case 9 – Gift Card Refund

 1. Customer wants to do a return on an item purchased through gift redemption and wants a refund on his gift card in store

 /device/card returns card is active and the outstanding gift balance gc_balance

/transaction/gift/refund refunds a card with an amount

 

JSON request payload:

{
 "device_id": "4b28fd4d7f23d301",
 "cardnumber": "637738991414324630”,
 "amount”: “10” ,
 “clerk_id”: “POS Clerk”
}

 2. Ackroo credits an amount back on the gift card for the refund amount specified of 10$

 

 

Use Case 10 – Check Balance

 1. Customer checks balance in store

 /device/card returns outstanding gift balance and card is active

 

JSON request payload:

{
 "device_id": "4b28fd4d7f23d301",
 "cardnumber": "637738991414324630"
}

2. Ackroo returns gift balance to be displayed on receipt or POS