Heartland SDK Documentation

Gift Card Payments

Merchant gift card programs lead customers to spend—on average—60 percent more than the value of their gift cards. In addition, 72 percent of shoppers also shop for themselves when they go online or in-store to purchase a gift card.

Heartland helps you acquire more loyal customers with our innovative gift card program. You can personalize your own gift cards, offer reloading capabilities and use a card-not-present program that allows your customers to use their phone number as their identifier.

Create a Gift Card Object

When consuming gift cards, you will need to first create a GiftCardData object to pass to the subsequent methods.

Creating a Gift Card

<?php
$card = new GiftCardData();
$card->number = "5022440000000000098";
var card = new GiftCardData {
    Number = "5022440000000000098";
};
GiftCardData card = new GiftCardData();
card.setNumber("5022440000000000098");
# coming soon
# coming soon
const card = new GiftCardData();
card.number = "5022440000000000098";

Get a Gift Card Balance

You might want to check the balance of a Gift Card before you try to create a sale.

Get Gift Card Balance

<?php
$response = $card->balanceInquiry()->execute();
var response = card.BalanceInquiry().Execute();
Transaction response = card.balanceInquiry().execute();
# coming soon
# coming soon
card.balanceInquiry()
  .execute()
  .then((response) => {
    // handle response
  });

Charge a Gift Card (Sale)

Creating a sale on a Gift Card is simple.

Charge Gift Card

<?php
$response = $card->charge(10)
    ->withCurrency("USD")
    ->execute();
var response = card.Charge(10m)
    .WithCurrency("USD")
    .Execute();
Transaction response = card.charge(new BigDecimal("10"))
    .withCurrency("USD")
    .execute();
# coming soon
# coming soon
card.charge(10)
  .withCurrency("USD")
  .execute()
  .then((response) => {
    // handle response
  });

Add Value to a Gift Card

You can add a value to an existing Gift Card

Add to Gift Card

<?php
$response = $card->addValue(10)
    ->withCurrency("USD")
    ->execute();
var response = card.AddValue(10m)
    .WithCurrency("USD")
    .Execute();
Transaction response = card.addValue(new BigDecimal("10"))
    .withCurrency("USD")
    .execute();
# coming soon
# coming soon
card.addValue(10)
  .withCurrency("USD")
  .execute()
  .then((response) => {
    // handle response
  });

Reward a Gift Card

To create a reward against a gift card you just need to pass in the card and the dollar amount to be rewarded.

Reward Gift Card

<?php
$response = $card->rewards(10)->execute();
var response = card.Rewards(10m).Execute();
Transaction response = card.rewards(new BigDecimal("10")).execute();
# coming soon
# coming soon
card.rewards(10)
  .execute()
  .then((response) => {
    // handle response
  });

Activate a Gift Card

Activating a gift card is as simple as providing the dollar amount, currency code and gift card object

Activate Gift Card

<?php
$response = $card->activate(10)->execute();
var response = card.Activate(10m).Execute();
Transaction response = card.activate(new BigDecimal("10")).execute();
# coming soon
# coming soon
card.activate(10)
  .execute()
  .then((response) => {
    // handle response
  });

Deactivate a Gift Card

Activating a gift card is as simple as providing the dollar amount, currency code and gift card object

Deactivate Gift Card

<?php
$response = $card->deactivate()->execute();
var response = card.Deactivate().Execute();
Transaction response = card.deactivate().execute();
# coming soon
# coming soon
card.deactivate()
  .execute()
  .then((response) => {
    // handle response
  });

Replace a Gift Card

Sometimes there is a need to replace a gift card with a new gift card.

Replace Gift Card

<?php
$card2 = new GiftCardData();
$card2->number = "5022440000000000007";
$response = $card->replaceWith($card2)->execute();
var card2 = new GiftCardData {
    Number = "5022440000000000007";
};
var response = card.ReplaceWith(card2).Execute();
GiftCardData card2 = new GiftCardData();
card2.setNumber("5022440000000000007");
Transaction response = card.replaceWith(card2).execute();
# coming soon
# coming soon
const card2 = new GiftCardData();
card2.number = "5022440000000000007";
card.replaceWith(card2)
  .execute()
  .then((response) => {
    // handle response
  });

Void a Gift Card Transaction

To void a gift card transaction, you will need only a gift transaction id.

Void Gift Card Transaction

<?php
$response = Transaction::fromId($transactionId)
    ->void()
    ->execute();
var response = Transaction.FromId(transactionId)
    .Void()
    .Execute();
Transaction response = Transaction.fromId(transactionId)
    .void()
    .execute();
# coming soon
# coming soon
Transaction.fromId(transactionId)
  .void()
  .execute()
  .then((response) => {
    // handle response
  });

Reverse a Gift Card By Transaction

You can reverse (or partially reverse) a gift card transaction with the transaction id.

Reverse Gift Card By Transaction

<?php
$response = Transaction::fromId($transactionId)
    ->reverse(10)
    ->execute();
var response = Transaction.FromId(transactionId)
    .reverse(10m)
    .Execute();
Transaction response = Transaction.fromId(transactionId)
    .reverse(new BigDecimal("10"))
    .execute();
# coming soon
# coming soon
Transaction.fromId(transactionId)
  .reverse(10)
  .execute()
  .then((response) => {
    // handle response
  });

Reverse a Gift Card

You can reverse (or partially reverse) a gift card transaction with the transaction id.

Reverse Gift Card

<?php
$response = $card->reverse(10)
    ->execute();
var response = Transaction.FromId(transactionId)
    .reverse(10m)
    .Execute();
Transaction response = Transaction.fromId(transactionId)
    .reverse(new BigDecimal("10"))
    .execute();
# coming soon
# coming soon
Transaction.fromId(transactionId)
  .reverse(10)
  .execute()
  .then((response) => {
    // handle response
  });