Credit Card Payments

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

Create a Customer

The first step is to create a Customer for which you want to charge.

Object: CardHolder | CardConsumer :

Parameter Description
FirstName First name of the card holder
LastName Last name of the card holder
Phone (optional) Phone number of card holder
Email (optional) Email address of the card holder.
Address A HpsAddress object that contains the users address information

Create a Credit Card Holder

var cardHolder = new HpsCardHolder()
{
    // Zip is required, but pass over as much as you have
    Address = new HpsAddress() { Zip = "47130" }
};
<?php
$cardHolder =  new HpsCardHolder();
$address = new HpsAddress();
$address->zip = "47130"
$cardHolder->address = $address;
HpsCardHolder cardHolder = new HpsCardHolder();
cardHolder.getAddress().setZip("47130");
card_holder = Hps::HpsCardHolder.new
card_holder.address.zip = "75024"
card_holder = HpsCardHolder()
card_holder.address.zip = '75024'
var cardHolder = {
    // Zip is required, but pass over as much as you have
    address: { zip: "47130" }
};

Charge a Credit Card Token

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.

Parameters:

Parameter Description
Amount The amount (in dollars)
Currency The currency (3-letter ISO code for currency).
Card A single-use token, multi-use token or an HpsCreditCard object
CardHolder (optional) The card holder information (used for AVS).
Request Multi Use Token (optional) Request a multi-use token.
Memo (optional) Free-form field (for Merchant reporting/record-keeping purposes only).

Returns: HpsAuthorization

Parameter Description
Authorization Code If authorized, authorization code returned by the Issuer
Avs Result Code If address verification requested, address verification result code returned by the Issuer
Avs Result Text Description of AVS result code
Cvv Result Code If card verification was provided in the request, card verification result code provided by the Issuer
Cvv Result Text Description of CVV result code
Cpc Indicator If the commercial card was specified in the request, the commercial card response indicator returned by the Issuer
Authorized Amount If supplied from the Issuer on a partial authorization, the authorized amount (less than the original or requested amount).
Card Type Card brand name
Descriptor Generated by concatenating the TxnDescriptor string from the transaction request to a configurable merchant DBA name. This string is sent to the card issuer for the Merchant Name.
Token Data Token Rsp Code, Token Rsp Message, Token Value

Charge a credit card token

creditService.Charge(10.00m, "usd", "Put single or multi-use token here", cardHolder);
<?php
$chargeService->charge(10, "usd", "put single or multi-use token here", $cardHolder);
chargeService.charge(new BigDecimal("10"), "usd", "put single or multi-use token here", cardHolder);
charge_service.charge(10, "usd", "put single or multi-use token here", card_holder)
response = credit_service.charge(10, 'usd', "put single or multi-use token here", card_holder)
creditService.chargeWithToken(10, "usd", "put single or multi-use token here", cardHolder, false, null, function (err, response) {
  if (err) {
    // handle error
    return;
  }
  // Do something with response
});

Verify a Credit Card Token

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, this provides a way for merchants to accomplish the same task while avoiding these penalties.

Parameters:

Parameter Description
Card The credit card information.
CardHolder (optional) The card holder information (used for AVS).

Returns: HpsAuthorization

Parameter Description
Authorization Code If authorized, authorization code returned by the Issuer
Avs Result Code If address verification requested, address verification result code returned by the Issuer
Avs Result Text Description of AVS result code
Cvv Result Code If card verification was provided in the request, card verification result code provided by the Issuer
Cvv Result Text Description of CVV result code
Cpc Indicator If the commercial card was specified in the request, the commercial card response indicator returned by the Issuer
Authorized Amount If supplied from the Issuer on a partial authorization, the authorized amount (less than the original or requested amount).
Card Type Card brand name
Descriptor Generated by concatenating the TxnDescriptor string from the transaction request to a configurable merchant DBA name. This string is sent to the card issuer for the Merchant Name.
Token Data Token Rsp Code, Token Rsp Message, Token Value

Verify Card Token

creditService.Verify("put single or multi-use token here", cardHolder);
<?php
$chargeService->verify("put single or multi-use token here", $cardHolder);
service.verify("put single or multi-use token here", cardHolder);
charge_service.verify("put single or multi-use token here", card_holder)
response = credit_service.verify("put single or multi-use token here", card_holder)
creditService.verifyWithToken("put single or multi-use token here", cardHolder, function (err, response) {
  if (err) {
    // handle error
    return;
  }
  // Do something with response
});

Authorize a Credit Card Token

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

Parameters:

Parameter Description
Amount The amount (in dollars)
Currency The currency (3-letter ISO code for currency).
Card A single-use token, multi-use token or an HpsCreditCard object
CardHolder (optional) The card holder information (used for AVS).
Request Multi Use Token (optional) Request a multi-use token.
Memo (optional) Free-form field (for Merchant reporting/record-keeping purposes only).

Authorize Card Token

creditService.Authorize(10.00m, "usd", "put single or multi-use token here", cardHolder);
<?php
$chargeService->authorize(10, "usd", "put single or multi-use token here", $cardHolder);
chargeService.authorize(new BigDecimal("10"), "usd", "put single or multi-use token here", cardHolder);
charge_service.authorize(50.00, "usd", "put single or multi-use token here", card_holder)
response = credit_service.authorize(10, 'usd', "put single or multi-use token here", card_holder)
creditService.authorizeWithToken(10, "usd", "put single or multi-use token here", cardHolder, false, null, function (err, response) {
  if (err) {
    // handle error
    return;
  }
  // Do something with response
});

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

// Request Token with Charge
var chargeResponse = creditService.Charge(10, "usd", creditCard, cardHolder, true);
var chargeToken = chargeResponse.TokenData.TokenValue;

// Request Token with Authorize
var authResponse = creditService.Authorize(10, "usd", creditCard, cardHolder, true);
var authToken = authResponse.TokenData.TokenValue;
<?php
// Request Token with Charge
$response = $chargeService->charge(10, "usd", $validCard, null, true);
$token = $response->tokenData->tokenValue;

// Request Token with Authorize
$response = $chargeService->authorize(10, "usd", $validCard, null, true);
$token = $response->tokenData->tokenValue;
/** Request Token with Charge */
HpsCharge chargeResponse = chargeService.charge(new BigDecimal("10"), "usd", creditCard, cardHolder, true, null);
String chargeToken = chargeResponse.getTokenData().getTokenValue();

/** Request Token with Authorize */
HpsAuthorization authResponse = chargeService.authorize(new BigDecimal("10"), "usd", creditCard, cardHolder, true, null);
String authToken = authResponse.getTokenData().getTokenValue();
charge_response = charge_service.charge(10, "usd", credit_card, card_holder, true)
charge_token = charge_response.token_data.token_value

auth_response = charge_service.authorize(10, "usd", credit_card, card_holder, true)
auth_token = auth_response.token_data.token_value
# Request Token with Charge
charge_response = credit_service.charge(10, 'usd', credit_card, card_holder, True)
charge_token = charge_response.token_data.token_value

# Request Token with Authorize
auth_response = credit_service.authorize(10, 'usd', credit_card, card_holder, True)
auth_token = auth_response.token_data.token_value
// Request token with Charge
creditService.chargeWithCard(10.00, 'usd', card, cardHolder, true, null, function (err, result) {
  // Do something with the results...
});

// Request token with Authorize
creditService.authorizeWithCard(10.00, 'usd', card, cardHolder, true, null, function (err, result) {
  // Do something with the results...
});

Charging a multi-use token

creditService.Charge(10, "usd", chargeToken, cardHolder);
<?php
$muToken = new HpsTokenData();
$muToken->tokenValue = $tokenValue;
$response = $chargeService->charge(10, "usd", $muToken, $cardHolder);
chargeService.charge(new BigDecimal("10"), "usd", chargeToken, cardHolder);
charge_service.charge(10, "usd", charge_token, card_holder)
response = credit_service.charge(10, 'usd', charge_token, card_holder)
creditService.chargeWithToken(10.00, 'usd', token, cardHolder, false, null, function (err, result) {
  // Do something with the results...
});

Authorizing a multi-use token

creditService.authorize(10.00m, "usd", chargeToken, cardHolder);
<?php
$muToken = new HpsTokenData();
$muToken->tokenValue = $tokenValue;
$response = $chargeService->authorize(10, "usd", $muToken, $cardHolder);
chargeService.authorize(new BigDecimal("10"), "usd", authToken, cardHolder);
charge_service.authorize(10, "usd", auth_token, card_holder)
response = credit_service.authorize(10, 'usd', auth_token, card_holder)
creditService.authorizeWithToken(10.00, 'usd', token, cardHolder, false, null, function (err, result) {
  // Do something with the results...
});

Returns: HpsCharge | HpsAuthorization

Parameter Description
Authorization Code If authorized, authorization code returned by the Issuer
Avs Result Code If address verification requested, address verification result code returned by the Issuer
Avs Result Text Description of AVS result code
Cvv Result Code If card verification was provided in the request, card verification result code provided by the Issuer
Cvv Result Text Description of CVV result code
Cpc Indicator If the commercial card was specified in the request, the commercial card response indicator returned by the Issuer
Authorized Amount If supplied from the Issuer on a partial authorization, the authorized amount (less than the original or requested amount).
Card Type Card brand name
Descriptor Generated by concatenating the TxnDescriptor string from the transaction request to a configurable merchant DBA name. This string is sent to the card issuer for the Merchant Name.
Token Data Token Rsp Code, Token Rsp Message, Token Value

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.

Parameters:

Parameter Description
Transaction Id The authorization transaction Id.
Amount (optional) An amount to charge (optional). Used if different from original authorization.

Returns: HpsReportTransactionDetails (of HpsAuthorization)

Parameter Description
HpsAuthorization Returns the above HpsAuthorization data
Original Transaction Id If the transaction performed an action on a previous transaction, this field records the transaction that was acted upon.
Masked Card Number Card number (masked)
Settlement Amount Settlement amount
Transaction Type The transaction type (i.e. Authorize, Capture, Charge, Refund, etc…)
Transaction Utc Date Date of the transaction in universal time.
Exceptions Any exceptions which may have occured during the transaction.
Memo a free-form field (for Merchant reporting/record-keeping purposes only).
Invoice Number This will not be used at settlement. (for Merchant reporting/record-keeping purposes only).
Customer Id free-form field for Merchant use. This is intended to be the customer identification. (for Merchant reporting/record-keeping purposes only).

Capture Authorization

var authResponse = creditService.Authorize(10.00m, "usd", "put single or multi-use token here", cardHolder); // create auth
creditService.Capture(authResponse.TransactionId); // capture auth
<?php
$response = $chargeService->authorize(10, "usd", "put single or multi-use token here", $cardHolder); // create auth
$captureResponse = $chargeService->capture($response->transactionId); // capture auth
var authResponse = chargeService.authorize(new BigDecimal("10"), "usd", "put single or multi-use token here", cardHolder); // create auth
chargeService.capture(authResponse.getTransactionID()); // capture auth
response = charge_service.authorize(10, "usd", "put single or multi-use token here", card_holder)
capture_response = charge_service.capture(response.transaction_id);
auth_response = credit_service.authorize(10, 'usd', "put single or multi-use token here", card_holder)
capture_response = credit_service.capture(auth_response.transaction_id)
creditService.authorizeWithToken(10, "usd", "put single or multi-use token here", cardHolder, false, null, function (err, response) {
  if (err) return;

  creditService.capture(response.transactionId, 10, function (err, resp) {
    // Do something with the response
  });
});

Refund a Transaction

The credit return transaction returns funds to the cardholder. The transaction is generally used as a counterpart to a credit card transaction that needs to be reversed, and 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.

Parameters:

Parameter Description
Amount The amount (in specified currency)
Currency The currency (3-letter ISO code for currency).
Transaction Id The Id of the Transaction to be refunded.
CardHolder (optional) The card holder information (used for AVS).
Memo (optional) Free-form field (for Merchant reporting/record-keeping purposes only).

Returns: HpsRefund

Refund Transaction

var chargeResponse = creditService.Charge(10.00m, "usd", "put single or multi-use token here", cardHolder);
creditService.Refund(10.00m, "usd", chargeResponse.TransactionId);
<?php
$response = $chargeService->charge(10, "usd", "put single or multi-use token here", $cardHolder);
$chargeService->refund(10, "usd", $response->transactionId);
var chargeResponse = chargeService.Charge(new BigDecimal("10"), "usd", "put single or multi-use token here", cardHolder);
chargeService.refund(new BigDecimal("10"), "usd", chargeResponse.getTransactionID());
charge_response = charge_service.charge(10, "usd", "put single or multi-use token here", card_holder)
charge_service.refund_transaction(10, "usd", charge_response.transaction_id)
charge_response = credit_service.charge(10, 'usd', "put single or multi-use token here", card_holder)
refund_response = credit_service.refund(10, 'usd', charge_response.transaction_id)
creditService.chargeWithToken(10, "usd", "put single or multi-use token here", cardHolder, false, null, function (err, response) {
  if (err) return;

  creditService.refundWithTransactionId(10, 'usd', response.transactionId, null, null, function (err, resp) {
    // Do something with the response
  });
});

Reverse a Transaction

A reverse transaction reverses a Charge or Authorize transaction from the active open authorizations or current open batch.

Parameters:

Parameter Description
Transaction ID The transaction ID of charge to reverse.
Amount The amount (in specified currency).
Currency The currency (3-letter ISO code for currency).
Memo (optional) Free-form field (for Merchant reporting/record-keeping purposes only).

Returns: HpsReversal

Reverse Transaction

var authResponse = creditService.Authorize(10.00m, "usd", "put single or multi-use token here", cardHolder);
creditService.Reverse(authResponse.TransactionId, 10.00m, "usd");
<?php
$response = $chargeService->authorize(10, "usd", "put single or multi-use token here", $cardHolder);
$chargeService->reverse($response->transactionId, 10, "usd");
var authResponse = chargeService.authorize(new BigDecimal("10"), "usd", "put single or multi-use token here", cardHolder);
chargeService.reverse(authResponse.transactionId, BigDecimal("10"), "usd");
response = charge_service.authorize(10, "usd", "put single or multi-use token here", card_holder)
charge_service.reverse(response.transactionId, 10, "usd");
auth_response = credit_service.authorize(10, 'usd', "put single or multi-use token here", card_holder)
reverse_response = credit_service.reverse(auth_response.transaction_id, 10, 'usd')
creditService.chargeWithToken(10, "usd", "put single or multi-use token here", cardHolder, false, null, function (err, response) {
  if (err) return;

  creditService.reverseWithTransactionId(10, 'usd', response.transactionId, null, function (err, resp) {
    // Do something with the response
  });
});

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.

Parameters:

Parameter Description
Transaction ID The transaction ID of charge to void.

Returns: HpsVoid

Void Transaction

var authResponse = creditService.Authorize(10.00m, "usd", "put single or multi-use token here", cardHolder);
creditService.Void(authResponse.TransactionId);
<?php
$response = $chargeService->authorize(10, "usd", "put single or multi-use token here", $cardHolder);
$chargeService->void($response->transactionId);
var authResponse = chargeService.authorize(new BigDecimal("10"), "usd", "put single or multi-use token here", cardHolder);
chargeService.void(authResponse.transactionId);
response = charge_service.authorize(10, "usd", "put single or multi-use token here", card_holder)
charge_service.void(response.transactionId);
auth_response = credit_service.authorize(10, 'usd', "put single or multi-use token here", card_holder)
void_response = credit_service.void(auth_response.transaction_id)
// coming soon

Edit a Transaction

An edit transaction changes the data on a previously approved Charge or Authorize transaction.

Parameters:

Parameter Description
Transaction ID The transaction ID of charge to void.
Amount If not null, revises (replaces) the authorized amount of the original auth. If null, does not affect the authorized amount of the original auth.
Gratuity If not null, revises (replaces) the gratuity amount information of the original auth. If null, does not affect the gratuity amount information, if any, of the original auth. This element is for informational purposes only and does not affect the authorized amount.
Client Transaction Id The optional client transaction ID.

Returns: HpsTransaction

Edit Transaction

var authResponse = creditService.Authorize(10.00m, "usd", "put a single or multi-use token here", cardHolder);
creditService.Edit(authResponse.TransactionId, 15.00m, 5.00m);
<?php
$response = $chargeService->authorize(10, "usd", "put a single or multi-use token here", $cardHolder);
$chargeService->edit($response->transactionId, 15, 5);
var authResponse = chargeService.authorize(new BigDecimal("10"), "usd", "put a single or multi-use token here", cardHolder);
chargeService.edit(authResponse.transactionId, new BigDecimal("15"), new BigDecimal("5"));
response = charge_service.authorize(10, "usd", "put a single or multi-use token here", card_holder)
charge_service.edit(response.transactionId, 15, 5);
auth_response = credit_service.authorize(10, 'usd', "put a single or multi-use token here", card_holder)
void_response = credit_service.edit(auth_response.transaction_id, 15, 5)
// coming soon