Credit Card Payments

Follow these steps to take credit card payments using your language of choice.

## Prepare to Charge a Credit Card

For the below sections, the code samples will reference the following objects:

Prepare to charge a credit card

Card details can be consumed on the front-end side and checked when the Single-Use token is generated. For example, the cards last four digits, expiration date, and card brand can be accessed during this step. Here’s a jsfiddle that demonstrates accessing these properties. Additional information can be found in our public repository here.

using GlobalPayments.Api.Entities;
using GlobalPayments.Api.PaymentMethods;

var card = new CreditCardData {
    Token = "single- or multi-use token"
};

var address new Address {
    PostalCode = "12345"
};

<?php
use GlobalPayments\Api\Entities\Address;
use GlobalPayments\Api\PaymentMethods\CreditCardData;

$card = new CreditCardData();
$card->token = "single- or multi-use token";

$address = new Address();
$address->postalCode = "12345";

import com.global.api.entities.Address;
import com.global.api.paymentMethods.CreditCardData;

CreditCardData card = new CreditCardData();
card.setToken("single- or multi-use token");

Address address = new Address();
address.setCode("12345");

# coming soon

from globalpayments.api.entities import Address
from globalpayments.api.payment_methods import CreditCardData

card = CreditCardData()
card.token = 'single- or multi-use token'

address = Address()
address.postal_code = '12345'

import { Address, CreditCardData } from "globalpayments-api";

const card = new CreditCardData();
card.token = "single- or multi-use token";

const address = new Address();
address.code = "12345";

Not using tokens?

Our SDKs support using tokens in place of card data, but using tokens is an option for you. You can also pass raw card data to us:

Manual Entry credit card data

using GlobalPayments.Api.PaymentMethods;

var card = new CreditCardData {
    Number = "4111111111111111",
    ExpMonth = "12",
    ExpYear = "2025",
    Cvn = "123"
};

<?php
use GlobalPayments\Api\PaymentMethods\CreditCardData;

$card = new CreditCardData();
$card->number = "4111111111111111";
$card->expMonth = "12";
$card->expYear = "2025";
$card->cvn = "123";

import com.global.api.paymentMethods.CreditCardData;

CreditCardData card = new CreditCardData();
card.setNumber("4111111111111111");
card.setExpMonth("12");
card.setExpYear("2025");
card.setCvn("123");

# coming soon

from globalpayments.api.payment_methods import CreditCardData

card = CreditCardData()
card.number = '4111111111111111'
card.exp_month = '12'
card.exp_year = '2025'
card.cvn = '123'

import { CreditCardData } from "globalpayments-api";

const card = new CreditCardData();
card.number = "4111111111111111";
card.expMonth = "12";
card.expYear = "2025";
card.cvn = "123";

Credit card track data

using GlobalPayments.Api.Entities;
using GlobalPayments.Api.PaymentMethods;

var card = new CreditTrackData {
    Value = "%B401200******0016^VI TEST CREDIT ...",
    EntryMethod = EntryMethod.Swipe
};

<?php
use GlobalPayments\Api\PaymentMethods\CreditTrackData;
use GlobalPayments\Api\Entities\Enums\EntryMethod;

$card = new CreditTrackData();
$card->value = "%B401200******0016^VI TEST CREDIT ...";
$card->entryMethod = EntryMethod::SWIPE;

import com.global.api.paymentMethods.CreditTrackData;
import com.global.api.entities.enums.EntryMethod;

CreditTrackData card = new CreditTrackData();
card.setValue("%B401200******0016^VI TEST CREDIT ...");
card.setEntryMethod(EntryMethod.Swipe);

# coming soon

from globalpayments.api.payment_methods import CreditTrackData
from globalpayments.api.entities.enums import EntryMethod

card = CreditTrackData()
card.value = '%B401200******0016^VI TEST CREDIT ...'
card.entry_method = EntryMethod.Swipe

import { CreditTrackData, EntryMethod } from "globalpayments-api";

const card = new CreditTrackData();
card.value = "%B401200******0016^VI TEST CREDIT ...";
card.entryMethod = EntryMethod.Swipe;

Encrypted credit card track data

using GlobalPayments.Api.Entities;
using GlobalPayments.Api.PaymentMethods;

var card = new CreditTrackData {
    Value = "<E1050711%B401200******0016^VI TEST CREDIT ...",
    EntryMethod = EntryMethod.Swipe,
    EncryptionData = new EncryptionData {
        Version = "01"
    }
};

<?php
use GlobalPayments\Api\Entities\EncryptionData;
use GlobalPayments\Api\Entities\Enums\EntryMethod;
use GlobalPayments\Api\PaymentMethods\CreditTrackData;

$card = new CreditTrackData();
$card->value = "<E1050711%B401200******0016^VI TEST CREDIT ...";
$card->entryMethod = EntryMethod::SWIPE;
$card->encryptionData = new EncryptionData();
$card->encryptionData->version = "01";

import com.global.api.entities.EncryptionData;
import com.global.api.entities.enums.EntryMethod;
import com.global.api.paymentMethods.CreditTrackData;

EncryptionData encryptionData = new EncryptionData();
encryptionData.setVersion("01");

CreditTrackData card = new CreditTrackData();
card.setValue("<E1050711%B401200******0016^VI TEST CREDIT ...");
card.setEntryMethod(EntryMethod.Swipe);
card.setEncryptionData(encryptionData);

# coming soon

from globalpayments.api.entities import EncryptionData
from globalpayments.api.entities.enums import EntryMethod
from globalpayments.api.payment_methods import CreditTrackData

card = CreditTrackData()
card.value = '<E1050711%B401200******0016^VI TEST CREDIT ...'
card.entry_method = EntryMethod.Swipe
card.encryption_data = EncryptionData()
card.encryption_data.version = '01'

import {
  CreditTrackData,
  EncryptionData,
  EntryMethod
} from "globalpayments-api";

const card = new CreditTrackData();
card.value = "<E1050711%B401200******0016^VI TEST CREDIT ...";
card.entryMethod = EntryMethod.Swipe;
card.encryptionData = new EncryptionData();
card.encryptionData.version = "01";

Charge a Credit Card

The credit sale transaction authorizes a sale purchased with a credit card. The authorization is placed in the current open batch (should auto-close for e-commerce transactions). If a batch is not open, this transaction will create an open batch.

Charge a credit card

var response = card.Charge(10.00m)
    .WithCurrency("USD")
    .WithAddress(address)
    .Execute();

<?php
$response = $card->charge(10)
    ->withCurrency("USD")
    ->withAddress($address)
    ->execute();

import com.global.api.entities.Transaction;
import java.math.BigDecimal;

Transaction response = card.charge(new BigDecimal("10"))
    .withCurrency("USD")
    .withAddress(address)
    .execute();

# coming soon

response = card.charge(10) \
    .with_currency('USD') \
    .with_address(address) \
    .execute()

const response = await card.charge(10)
  .withCurrency("USD")
  .withAddress(address)
  .execute();

Verify a Credit Card

A credit account verify transaction is used to verify that the account is in good standing with the issuer. This is a zero dollar transaction with no associated authorization. Since VISA and other issuers have started assessing penalties for one dollar authorizations when verifying credit cards, this provides a way for merchants to accomplish the same task while avoiding these penalties.

Verify Card Token

var response = card.Verify()
    .WithCurrency("USD")
    .WithAddress(address)
    .Execute();

<?php
$response = $card->verify()
    ->withCurrency("USD")
    ->withAddress($address)
    ->execute();

import com.global.api.entities.Transaction;

Transaction response = card.verify()
    .withCurrency("USD")
    .withAddress(address)
    .execute();

# coming soon

response = card.verify() \
    .with_currency('USD') \
    .with_address(address) \
    .execute()

const response = await card.verify()
  .withCurrency("USD")
  .withAddress(address)
  .execute();

Authorize a Credit Card

A credit authorization transaction authorizes a credit card transaction. The authorization is not placed in the batch. The credit authorization transaction can be added to a batch by using the capture method.

Authorize Card

var response = card.Authorize(10.00m)
    .WithCurrency("USD")
    .WithAddress(address)
    .Execute();

<?php
$response = $card->authorize(10)
    ->withCurrency("USD")
    ->withAddress($address)
    ->execute();

import com.global.api.entities.Transaction;
import java.math.BigDecimal;

Transaction response = card.authorize(new BigDecimal("10"))
    .withCurrency("USD")
    .withAddress(address)
    .execute();

# coming soon

response = card.authorize(10) \
    .with_currency('USD') \
    .with_address(address) \
    .execute()

const response = await card.authorize(10)
  .withCurrency("USD")
  .withAddress(address)
  .execute();

Assessing a Surcharge Fee {: #assessing-a-surcharge-fee }

The Heartland Online Payment Surcharge Program helps businesses offset online credit card processing costs and stay compliant with state, federal and card brand guidelines. By charging customers a percentage fee for processing credit card purchases online, the Program helps businesses keep their prices and payment options competitive — and preserve all the ways customers want to pay.

Surcharging is legal in all but six states (CO, CT, KS, MA, ME, OK), allowing businesses to recoup their processing costs. Heartland’s Online Payment Surcharge Program is a turnkey solution that helps business owners collect surcharges and be 100 percent confident that they meet all requirements.

Determining Eligibility {: #determining-eligibility }

Online payments integrations can determine surcharge eligibility by including a BIN check during single-use tokenization. Read more about a BIN check in the Global Payments GitHub. This will expose a boolean on the single-use tokenization response (result.details.canSurcharge) which will alert your integration if the current card can be surcharged.

Authorize Card with a Surcharge

var amount = 10.00m;
var surcharge = amount * .035m;

var response = card.Authorize(amount + surcharge)
    .WithCurrency("USD")
    .WithAddress(address)
    .WithSurchargeAmount(surcharge)
    .Execute();

<?php
$amount = 10;
$surcharge = $amount * .035;

$response = $card->authorize($amount + $surcharge)
    ->withCurrency("USD")
    ->withAddress($address)
    ->withSurchargeAmount($surcharge)
    ->execute();

import com.global.api.entities.Transaction;
import java.math.BigDecimal;

BigDecimal amount = new BigDecimal("10");
BigDecimal surcharge = amount.multiply(new BigDecimal(".035"));

Transaction response = card.authorize(amount.add(surcharge))
    .withCurrency("USD")
    .withAddress(address)
    .withSurchargeAmount(surcharge)
    .execute();

# coming soon

# coming soon

# coming soon

Using Multi-Use Tokens

Multi-Use Tokenization allows a secure and PCI friendly way to store credit card information within your system. A multi-use token can be generated as part of any of our initial gateway calls: charge, verify, or authorize.

Requesting a multi-use token

var response = card.Verify()
    .WithAddress(address)
    .WithRequestMultiUseToken(true)
    .Execute();

<?php
$response = $card->verify()
    ->withAddress($address)
    ->withRequestMultiUseToken(true)
    ->execute();

import com.global.api.entities.Transaction;

Transaction response = card.verify()
    .withAddress(address)
    .withRequestMultiUseToken(true)
    .execute();

# coming soon

response = card.verify() \
    .with_address(address) \
    .with_request_multi_use_token(True) \
    .execute()

const response = await card.verify()
  .withAddress(address)
  .withRequestMultiUseToken(true)
  .execute();

Charging a multi-use token

var response = card.Charge(10.00m)
    .WithCurrency("USD")
    .WithAddress(address)
    .Execute();

<?php
$response = $card->charge(10)
    ->withCurrency("USD")
    ->withAddress($address)
    ->execute();

import com.global.api.entities.Transaction;
import java.math.BigDecimal;

Transaction response = card.charge(new BigDecimal("10"))
    .withCurrency("USD")
    .withAddress(address)
    .execute();

# coming soon

repsonse = card.charge(10) \
    .with_currency('USD') \
    .with_address(address) \
    .execute()

const response = await card.charge(10)
  .withCurrency("USD")
  .withAddress(address)
  .execute();

Authorizing a multi-use token

var response = card.Authorize(10.00m)
    .WithCurrency("USD")
    .WithAddress(address)
    .Execute();

<?php
$response = $card->authorize(10)
    ->withCurrency("USD")
    ->withAddress($address)
    ->execute();

import com.global.api.entities.Transaction;
import java.math.BigDecimal;

Transaction response = card.authorize(new BigDecimal("10"))
    .withCurrency("USD")
    .withAddress(address)
    .execute();

# coming soon

repsonse = card.authorize(10) \
    .with_currency('USD') \
    .with_address(address) \
    .execute()

const response = await card.authorize(10)
  .withCurrency("USD")
  .withAddress(address)
  .execute();

Capture an Authorization

A capture transaction adds a previous authorization transaction to the current open batch. If a batch is not open, this transaction will create one.

Capture Authorization

using GlobalPayments.Api.Entities;

var response = card.Authorize(10.00m)
    .WithCurrency("USD")
    .WithAddress(address)
    .Execute();

Transaction.FromId(response.TransactionId)
    .Capture(10.00m)
    .Execute();

<?php
use GlobalPayments\Api\Entities\Transaction;

$response = $card->authorize(10)
    ->withCurrency("USD")
    ->withAddress($address)
    ->execute();

Transaction::fromId($response->transactionId)
    ->capture(10)
    ->execute();

import com.global.api.entities.Transaction;
import java.math.BigDecimal;

Transaction response = card.authorize(new BigDecimal("10"))
    .withCurrency("USD")
    .withAddress(address)
    .execute();

Transaction.fromId(response.getTransactionId())
    .capture(new BigDecimal("10"))
    .execute();

# coming soon

from globalpayments.api.entities import Transaction

response = card.authorize(10) \
    .with_currency('USD') \
    .with_address(address) \
    .execute()

Transaction.from_id(response.transaction_id) \
    .capture(10) \
    .execute()

import { Transaction } from "globalpayments-api";

const response = await card.authorize(10)
  .withCurrency("USD")
  .withAddress(address)
  .execute();

await Transaction.fromId(response.transactionId)
  .capture(10)
  .execute();

Refund a Transaction

The credit return transaction returns funds to the cardholder’s account. The transaction is generally used as a counterpart to a credit card transaction that needs to be reversed when the batch containing the original transaction has already been closed. The credit return transaction is placed in the current open batch. If a batch is not open, this transaction will create an open batch.

Refund Transaction

using GlobalPayments.Api.Entities;

var response = card.Charge(10.00m)
    .WithCurrency("USD")
    .WithAddress(address)
    .Execute();

Transaction.FromId(response.TransactionId)
    .Refund(10.00m)
    .Execute();

<?php
use GlobalPayments\Api\Entities\Transaction;

$response = $card->charge(10)
    ->withCurrency("USD")
    ->withAddress($address)
    ->execute();

Transaction::fromId($response->transactionId)
    ->refund(10)
    ->execute();

import com.global.api.entities.Transaction;
import java.math.BigDecimal;

Transaction response = card.charge(new BigDecimal("10"))
    .withCurrency("USD")
    .withAddress(address)
    .execute();

Transaction.fromId(response.getTransactionId())
    .refund(new BigDecimal("10"))
    .execute();

# coming soon

from globalpayments.api.entities import Transaction

response = card.authorize(10) \
    .with_currency('USD') \
    .with_address(address) \
    .execute()

Transaction.from_id(response.transaction_id) \
    .refund(10) \
    .execute()

import { Transaction } from "globalpayments-api";

const response = await card.charge(10)
  .withCurrency("USD")
  .withAddress(address)
  .execute();

await Transaction.fromId(response.transactionId)
  .refund(10)
  .execute();

Reverse a Transaction

A reverse transaction reverses a charge or authorize transaction from the active open authorizations or current open batch.

Reverse Transaction

using GlobalPayments.Api.Entities;

var response = card.Authorize(10.00m)
    .WithCurrency("USD")
    .WithAddress(address)
    .Execute();

Transaction.FromId(response.TransactionId)
    .Reverse(10.00m)
    .Execute();

<?php
use GlobalPayments\Api\Entities\Transaction;

$response = $card->authorize(10)
    ->withCurrency("USD")
    ->withAddress($address)
    ->execute();

Transaction::fromId($response->transactionId)
    ->reverse(10)
    ->execute();

import com.global.api.entities.Transaction;
import java.math.BigDecimal;

Transaction response = card.authorize(new BigDecimal("10"))
    .withCurrency("USD")
    .withAddress(address)
    .execute();

Transaction.fromId(response.getTransactionId())
    .reverse(new BigDecimal("10"))
    .execute();

# coming soon

from globalpayments.api.entities import Transaction

response = card.authorize(10) \
    .with_currency('USD') \
    .with_address(address) \
    .execute()

Transaction.from_id(response.transaction_id) \
    .reverse(10) \
    .execute()

import { Transaction } from "globalpayments-api";

const response = await card.authorize(10)
  .withCurrency("USD")
  .withAddress(address)
  .execute();

await Transaction.fromId(response.transactionId)
  .reverse(10)
  .execute();

Void a Transaction

A credit void transaction is used to inactivate a transaction. The transaction must be an authorize, charge or return. The transaction must be active in order to be voided. Authorize transactions do not have to be associated with a batch to be voided. Transactions may be voided after they are associated with a batch as long as the batch is not closed.

Void Transaction

using GlobalPayments.Api.Entities;

var response = card.Authorize(10.00m)
    .WithCurrency("USD")
    .WithAddress(address)
    .Execute();

Transaction.FromId(response.TransactionId)
    .Void()
    .Execute();

<?php
use GlobalPayments\Api\Entities\Transaction;

$response = $card->authorize(10)
    ->withCurrency("USD")
    ->withAddress($address)
    ->execute();

Transaction::fromId($response->transactionId)
    ->void()
    ->execute();

import com.global.api.entities.Transaction;
import java.math.BigDecimal;

Transaction response = card.authorize(new BigDecimal("10"))
    .withCurrency("USD")
    .withAddress(address)
    .execute();

Transaction.fromId(response.getTransactionId())
    .void()
    .execute();

# coming soon

from globalpayments.api.entities import Transaction

response = card.authorize(10) \
    .with_currency('USD') \
    .with_address(address) \
    .execute()

Transaction.from_id(response.transaction_id) \
    .void() \
    .execute()

import { Transaction } from "globalpayments-api";

const response = await card.authorize(10)
  .withCurrency("USD")
  .withAddress(address)
  .execute();

await Transaction.fromId(response.transactionId)
  .void()
  .execute();

Edit a Transaction

An edit transaction changes the data on a previously approved charge or authorize transaction.

Edit Transaction

using GlobalPayments.Api.Entities;

var response = card.Authorize(10.00m)
    .WithCurrency("USD")
    .WithAddress(address)
    .Execute();

Transaction.FromId(response.TransactionId)
    .Edit()
    .WithAmount(15.00m)
    .WithGratuity(5.00m)
    .Execute();

<?php
use GlobalPayments\Api\Entities\Transaction;

$response = $card->authorize(10)
    ->withCurrency("USD")
    ->withAddress($address)
    ->execute();

Transaction::fromId($response->transactionId)
    ->edit()
    ->withAmount(15.00)
    ->withGratuity(5.00)
    ->execute();

import com.global.api.entities.Transaction;
import java.math.BigDecimal;

Transaction response = card.authorize(new BigDecimal("10"))
    .withCurrency("USD")
    .withAddress(address)
    .execute();

Transaction.fromId(response.getTransactionId())
    .edit()
    .withAmount(new BigDecimal("15.00"))
    .withGratuity(new BigDecimal("5.00"))
    .execute();

# coming soon

from globalpayments.api.entities import Transaction

response = card.authorize(10) \
    .with_currency('USD') \
    .with_address(address) \
    .execute()

Transaction.from_id(response.transaction_id) \
    .edit() \
    .with_amount(15) \
    .with_gratuity(5) \
    .execute()

import { Transaction } from "globalpayments-api";

const response = await card.authorize(10)
  .withCurrency("USD")
  .withAddress(address)
  .execute();

await Transaction.fromId(response.transactionId)
  .edit()
  .withAmount(15.00)
  .withGratuity(5.00)
  .execute();

Lodging

Heartland supports all the major payment processing industries. The following sections provide information on how to use the different services based on the Lodging industry.

CHECK IN / CHECK OUT

Date of check-in/Check-out. Duration of stay in days. The stay Duration range is from 1 to 99.

CHECK IN / CHECK OUT

using GlobalPayments.Api.Entities;

var lodgingData = new LodgingData { StayDuration = 1 };

# coming soon

# coming soon

# coming soon

# coming soon

# coming soon

ADVANCED DEPOSIT

Indicates the advance deposit type.

Advanced Deposit

using GlobalPayments.Api.Entities;

var lodgingData = new LodgingData {
	StayDuration = 1,
	AdvancedDepositType = AdvancedDepositType.CARD_DEPOSIT
};

Transaction response = card.Charge(41m)
	.WithLodgingData(lodgingData)
	.Execute();

# coming soon

# coming soon

# coming soon

# coming soon

# coming soon

ASSURED RESERVATION / NO SHOW

Indicates that this charge is due to a “no show” on a reservation.

No Show

using GlobalPayments.Api.Entities;

var lodgingData = new LodgingData {
	StayDuration = 1,
	NoShow = true
};

Transaction response = card.Charge(42m)
	.WithLodgingData(lodgingData)
	.Execute();

# coming soon

# coming soon

# coming soon

# coming soon

# coming soon

VISA PRESTIGIOUS PROPERTY

Used by merchants participating in the Prestigious Lodging Program.

VISA PRESTIGIOUS PROPERTY

using GlobalPayments.Api.Entities;

var lodgingData = new LodgingData {
	StayDuration = 1,
	PrestigiousPropertyLimit = PrestigiousPropertyLimit.LIMIT_500
};

Transaction response = track.Charge(44m)
	.WithLodgingData(lodgingData)
	.Execute();

# coming soon

# coming soon

# coming soon

# coming soon

# coming soon

MASTERCARD PREFERRED CUSTOMER

For MasterCard only. Indicates whether or not the customer has a preferred status.

MASTERCARD PREFERRED CUSTOMER

using GlobalPayments.Api.Entities;

var lodgingData = new LodgingData {
	StayDuration = 1,
	PreferredCustomer = true
};

Transaction response = track.Charge(47m)
	.WithLodgingData(lodgingData)
	.Execute();

# coming soon

# coming soon

# coming soon

# coming soon

# coming soon

EXTRA / ADDITIONAL CHARGES

Types of extra charges included in the extra charge amount information and the total transaction amount.

EXTRA / ADDITIONAL CHARGES

using GlobalPayments.Api.Entities;

var lodgingData = new LodgingData()
	.AddExtraCharge(ExtraChargeType.GiftShop)
	.AddExtraCharge(ExtraChargeType.MiniBar)
	.AddExtraCharge(ExtraChargeType.Telephone);

Transaction response = track.Charge(50m)
	.WithLodgingData(lodgingData)
	.Execute();

# coming soon

# coming soon

# coming soon

# coming soon

# coming soon