Integration Guide - SALT Technology

Introduction

Document Overview

This document describes how to integrate your website with the SALT Credit Card API. This document provides a step-by-step guide to completing the integration process as well as information on test and configuration tools available to you.

Abbreviations, Definitions, and Acronyms

The following is a list of abbreviations, acronyms, and terms that are used throughout this document:

Abbreviations, Definitions, and Acronyms
Term	Definition
API	Application Programming Interface
Approval (or Authorization) Code	Code obtained from the credit card processing network that is required to complete any credit card transaction. Note that the Approval/Authorization code is not a guarantee of acceptance or payment of a transaction. Receipt of an approval/authorization code does not mean that the merchant will not receive a chargeback for that transaction.
CVV2 (a.k.a. CVD)	Card Verification Value. A three or four digit code which is printed on a credit card, but which is not a part of the card number.
Elavon	Company providing access to the credit card payment processing network, c/o SALT.
HTML	Hyper Text Markup Language
HTTPS	Secure Hyper Text Transfer Protocol
Issuer	A Bank/Financial Institution issuing credit cards
SSL	Secure Sockets Layer

Credit Card API Workflow

To get a better understanding of what is involved in the integration process, you should first understand the workflow of the SALT Credit Card API.

The SALT Credit Card API Solution workflow consists of four phases, as illustrated in the following diagram:

When the customer is ready to checkout and pay for their order, you collect the customer credit card information on your website.
You then obtain approval for the payment by invoking the SALT API with the customer credit card information.
SALT API Handler will process the request through the credit card network. The result of the payment approval will be returned to you from the SALT API.
You generate and display a receipt to the customer.

Integration At-a-Glance

At-a-glance, the process of integrating with the Credit Card API consists of the following steps:

	Step	Description
1)	SALT Sandbox Environment	Accessing/familiarizing yourself with the SALT Sandbox environment.
2)	Working with the SALT API	Writing the HTML POST that will allow you to send transactions to the SALT Payment Handler.
3)	Working with Receipts	Writing HTML/web scripting code to display the receipt from transaction data returned by the API.
4)	Certification	Working with SALT to ensure that your completed web application meets the requirements set out by Elavon for any merchant using credit card payment processing.
5)	Going into Production	Moving from the Sandbox environment to the production environment.

The SALT Sandbox Environment

The SALT Sandbox Environment is a environment mirroring the production environment that allows you to perform testing and integration before going into production.

If you don't yet have a Sandbox account, you can create one by following the link below!

Create a SALT Sandbox Account

SALT Sandbox Environment
	URL	Description
SALT Merchant Management Website	https://test.saltpayments.com/merchantmanagement/	Allows you to perform administrative tasks such as viewing transaction activity and configuring your services.
SALT Payment Gateway	https://test.saltpayments.com/gateway/creditcard/processor.do	Receives Credit Card API requests

The SALT Merchant Management Console requires a login, which consists of a Username and Password set by you when creating your Sandbox account. You can change your password at any time.

Finding Your Merchant Credentials

In order to process payments through your Sandbox account, you will need to retrieve your Sandbox Merchant Credentials - merchantId and apiToken. To find your credentials:

Login to the SALT Sandbox Merchant Management Console at https://test.saltpayments.com/merchantmanagement/
Click the 'Services' link in the main menu. A list of all of your services will be displayed.
Click the Service to view your merchantId and apiToken.

Working With the SALT Core API

You will need to use the SALT Credit Card API to perform credit card transactions.

Client Library

Before working with the SALT Core API, ensure that you have downloaded the client library file to your computer. The Core API consists of a single package package com.salt.payment.client.creditcard.api with two main classes:

HttpsCreditCardService - Calls the SALT Payment Gateway to process credit card transactions, such as purchases, voids, and refunds.
CreditCardReceipt - A container class for the HttpsCreditCardService method response.

These classes and their methods will be described in full in the following sections.

IMPORTANT: This document discusses development using the Java version of the Core API. For examples using other languages, including Microsoft .NET and PHP, please see the Appendix.

The HttpsCreditCardService

To process a credit card transaction, you will need to construct an instance of the HttpsCreditCardService class as follows:

Core API: HttpsCreditCardService Constructor
Name	Type	Description
`HttpsCreditCardService(merchant, url)`
merchant	Merchant	Contains your merchant credentials. See Table 3.2.
url	String(255)	URL to the SALT Core API handler. In the environment this ishttps://test.saltpayments.com/gateway/creditcard/processor.do

NOTE: If you are using the HttpsCreditCardService from API versions 1.3.1 or older, the old constructors are still supported but are now considered deprecated.

Core API: Merchant Constructor
Name	Type	Description
`Merchant(merchantId, apiToken [, storeId])`
merchantId	Integer	Merchant ID as assigned to you by SALT (can check this in the Merchant Management Website).
apiToken	String(20)	API Token as assigned to you by SALT (can check this in the Merchant Management Website)
storeId OPTIONAL	String(50)	Store ID field that can be used to identify/group transactions. Optional field.

After you have created a new instance of HttpsCreditCardService, you can use it to process transactions.

Purchase

To perform a credit card purchase you will invoke the singlePurchase() method:

Core API: HttpsCreditCardService.singlePurchase() Method
Name	Type	Description
`HttpsCreditCardService.singlePurchase(orderId, creditCard, amount, verificationRequest)`
`orderId`	`String(32)`	Merchant assigned orderId. Must be unique.
`creditCard`	`CreditCard`	Credit Card information (see Table 3.4)
`amount`	`Long`	Amount of the purchase in cents. Do NOT include a $ or any decimal place. (e.g. if your purchase is $10.00, then send 1000 as the total).
`verificationRequest`	`VerificationRequest`	Credit Card Verification request information, null if not used. See Section 5 for details on how to use this field.
Returns:
`CreditCardReceipt`		The results of the purchase request

The customer credit card information is submitted using the data object CreditCard. The basic constructor is shown below.

CreditCard Class (Basic Constructor)
Name	Type	Description
CreditCard Constructor Parameters
`creditCardNumber`	`Long`	Credit Card Number
`expiryDate`	`Short`	Credit Card Expiry Date in MMYY format

To use advanced features such as Address Verification System and CVV, you will have to use the full constructor that provides additional fields. See Section 5.1 for details.

The CreditCardReceipt object contains the results of the Purchase:

Core API: CreditCardReceipt Class
Field	Type	Description
CreditCardReceipt
`getApprovalInfo()`	`ApprovalInfo`	Transaction approval information
`getAvsResponse()`	`AvsResponse`	The AVS response from processing the purchase, or null if AVS was not enabled or no response. See Section 5
`getCardBrand()`	`Integer`	Returns the brand of the credit card, as a number: 1=Visa, 2=MasterCard, 3=AMEX, 4=Discover, 5=Diners, 6=JCB, 7=Other
`getCvv2Response()`	`Cvv2Response`	The CVV2 response from processing the purchase, or null if CVV2 was not enabled or no response. See Section 5
`getDebugMessage()`	`String(255)`	Debug message, if applicable
`getErrorCode()`	`String(128)`	Error code, if applicable
`getErrorMessage()`	`String(255)`	Error message, if applicable
`getOrderId()`	`String(32)`	Merchant-assigned orderId
`getPeriodicPurchaseInfo()`	`PeriodicPurchaseInfo`	Information about the periodic purchase, if this was a periodic purchase transaction
`getProcessedDateTime()`	`Date`	Date/time when the transaction was processed
`getSanitizedCardNumber()`	`String(20)`	Storage/display-safe version of the credit card number. E.g. 424242****4242
`getTransactionId()`	`Long`	SALT TransactionId for this transaction
`isApproved()`	`Boolean`	Returns true if the request was approved, otherwise the request was declined due to some error.

The ApprovalInfo object contains the transaction approval information of the Transaction:

Core API: ApprovalInfo Class
Field	Type	Description
ApprovalInfo
`getApprovalCode()`	`String`	Credit Card Approval Code
`getAuthorizedAmount()`	`Long`	Amount authorized on approval, in cents
`getReferenceNumber()`	`Integer`	Credit Card approval Reference Number
`getTraceNumber()`	`Integer`	Credit Card approval Trace Number

Void and Refund

You may need to void or refund a purchase made by a customer from time to time. You can do this programmatically through the Core API (see below) but if you don't need/want to, you can perform refunds manually through the Merchant Management Website.

What is a Void? What is a Refund?

Void: Cancels a transaction, preventing it from being settled. A Void can only be performed on a transaction belonging to the current batch, before the current batch is closed (i.e. before the end of day).
Refund: Returns funds from a previously settled purchase to the customer. Refunds can only be performed on a purchase that is part of an already-closed batch.

Core API: HttpsCreditCardService.voidTransaction() Method
Name	Type	Description
`HttpsCreditCardService.voidTransaction(transactionId, transactionOrderId)`
`transactionId`	`Long`	The SALT transactionId of the transaction to void
`transactionOrderId`	`String(32)`	The orderId previously assigned to the transaction that is to be voided. This is an extra check to prevent inadvertent voiding of a transaction. Not null.
Returns:
`CreditCardReceipt`		The results of the void request

Core API: HttpsCreditCardService.refund() Method
Name	Type	Description
`HttpsCreditCardService.refund(purchaseId, purchaseOrderId, refundOrderId, amount)`
`purchaseId`	`Long`	The SALT transactionId of the purchase to void
`purchaseOrderId`	`String(32)`	The order id previously assigned to the purchase that is to be refunded. This is an extra check to prevent inadvertent refunding of a purchase. Not null.
`refundOrderId`	`String(32)`	The merchant assigned orderId to be attached to this refund request. Will be generated if null.
`amount`	`Long`	Amount to refund in cents. Do NOT include a $ or any decimal place. (e.g. if your purchase is $10.00, then send 1000 as the total). This value does NOT have to match the original purchase amount.
Returns:
`CreditCardReceipt`		The results of the Refund Request

The CreditCardReceipt object is the same as is described in Section 3.3.

Void/Refund Notes and Restrictions

Credit Card Void and Refund operations are subject to the following restrictions/conditions:

Only transactions belonging to a batch that has not yet been closed may be voided. Once a batch has closed, you may only refund that transaction. Conversely transactions belonging to a batch that has not yet been closed may not be refunded.
You may only Refund/Void a Purchase that has been approved successfully. Any declined/erroneous/cancelled Purchases cannot be refunded or voided.
You may perform multiple refunds against a given Purchase (example scenario: the customer incrementally returns parts of their order, and you refund the cost of each increment when it is received)
You can void a refund request, providing it belongs to a batch that has not yet been closed.

Manual Void/Refund Using the Merchant Management Website

If you do not need/want to perform Void/Refund operations programmatically, you can always perform them manually using the Merchant Management Website:

Login to the SALT Merchant Management Website at https://test.saltpayments.com/merchantmanagement/
Select the Void/Refund link under the Terminal section.
Search for the Purchase transaction that you wish to void/refund (by date, Store ID, etc)
When you find the transaction to void/refund, press the void or refund button
If you are performing a Refund, you will be asked to enter the amount to refund (the default is the original purchase amount).
Press the Submit Void or Submit Refund button.

Periodic/Recurring Payments

You can use SALT Periodic Purchase features when the customer is billed periodically, or when splitting payment into a number of separate payments.

Creating a Recurring Payment

In the API version 1.4 and below, calling recurringPurchase() will automatically create, verify and process the transaction. However, starting in 2.0, recurringPurchase() will only create and verify the transaction. The funds are not immediately captured from the customer credit card until executeRecurringPurchase() is explicitly called.

You can set up a customer for recurring billing by using the recurringPurchase() method:

Core API: HttpsCreditCardService.recurringPurchase() Method
Name	Type	Description
`HttpsCreditCardService.recurringPurchase(periodicPurchaseInfo, creditCard, storageTokenId, verificationRequest)`
`periodicPurchaseInfo`	`PeriodicPurchaseInfo`	Defines periodic-specific information, such as schedule, dates, and customer ID. See Table 3.10.
`creditCard`	`CreditCard`	Credit Card information (see Table 3.4). If storageTokenId is provided, this will be ignored
`storageTokenId`	`String`	Storage Token ID specifying the stored credit card to use for this purchase. Takes precedence over the creditCard field.
`verificationRequest`	`Verification Request`	Credit Card Verification request information, null if not used. Note that CVV2 will not be stored/used in recurring purchases. See Section 5 for details on how to use this field.
Returns:
`CreditCardReceipt`		The results of the purchase request.

The periodicPurchaseInfo object is constructed as follows:

Core API: PeriodicPurchaseInfo Class (Full Constructor)
Name	Type	Description
`PeriodicPurchaseInfo` Constructor Parameters
`periodicTransactionId`	`Long`	SALT recurring purchase ID returned when the purchase was originally created. Not applicable to new recurring purchases
`state`	`State`	One of IN_PROGRESS, ON_HOLD, CANCELLED. Note a cancelled payment will not be run again and cannot be further modified. Not applicable to new recurring purchases.
`schedule`	`Schedule`	The schedule on which to issue payments. See Table 3.11. If null, will default to monthly payments.
`perPaymentAmount`	`Long`	Per-payment amount of the in cents. Do NOT include a $ or any decimal place. (e.g. if your purchase is $10.00, then send 1000 as the total).
`orderId`	`String(32)`	Merchant assigned orderId. Must be unique. Cannot be modified after the first payment has been issued.
`customerId`	`String(32)`	Optional meta field that can be used to describe a customer
`startDate`	`Date`	The date of when to issue the first payment. If this date is null or in the past, then the first payment will be issued immediately. Cannot be modified after the first payment has been issued.
`endDate`	`Date`	The date of when to end the payments. A payment will not be issued if it falls on this date.
`nextPaymentDate`	`Date`	Change when the next payment will occur. Must be set between the start and end date (as currently defined or as modified by their respective parameters). Not used in a new recurring payment (startDate defines first payment date).
Parameters Outside of the full constructor
`ExecutionType`	`enum`	Has a value of either `MANUAL` or `AUTO` `AUTO` = the recurring purchase will execute immediately. `MANUAL` = the recurring purchase will not run unless first explicitly executed via executeRecurringPurchase(). If not provided, will default to `MANUAL`
`setExecutionType(ExecutionType executionType)`		Sets the execution type to either manual or auto
`getExecutionType()`	`ExecutionType`	Returns the value of the execution type
`installmentNumber`	`Integer`	The value of the instalment the periodic purchase transaction is on. (e.g. if there are 4 instalments, and the card is charged for the second time, the installmentNumber = 2)
`setInstallmentNumber(Integer installmentNumber)`
`getInstallmentNumber()`	`Integer`	Returns the installmentNumber

You can define a custom schedule for when to issue recurring payments:

Core API: Schedule Class (Basic Constructor)
Name	Type	Description
`Schedule` Constructor Parameters
`scheduleType`	`ScheduleType`	Schedule based on days, weeks, or months (See Table 3.12 ScheduleType Enumeration)
`intervalLength`	`Short`	Payments will be issued every number of days/weeks/months

ScheduleType Enumeration
Value	Description
`ScheduleType`
MONTH	Schedule based on months
WEEK	Schedule based on weeks
DAY	Schedule based on days

So for example, if you create a Schedule using scheduleType = WEEK and intervalLength = 2, then payments will be issued every two weeks.

Executing Recurring Payments

Once a recurring purchase has been successfully created (with recurringPurchase() ), it can be executed by calling the executeRecurringPurchase() method.

HttpsCreditCardService.executeRecurringPurchase() method
Name	Type	Description
`HttpsCreditCardService.executeRecurringPurchase(recurringPurchaseId, cvv2)`
`recurringPurchaseId`	`Long`	SALT recurring purchase ID returned when the purchase was originally created.
`cvv2`	`String`	Card Verification Value/Card Verification Digits. This parameter provides optional verification when performing this transaction
Returns:
`CreditCardReceipt`		The results of the transaction

Managing Recurring Payments

There are additional operations available that you can use to manage your recurring payments.

Putting a Payment on Hold (and Resuming a Payment on Hold)

Putting a hold on a recurring payment means that further payments will be suspended until the recurring payment is resumed. You can resume payments by calling the resumeRecurringPurchase() method.

Core API: HttpsCreditCardService.holdRecurringPurchase() Method
Name	Type	Description
`HttpsCreditCardService.holdRecurringPurchase(recurringPurchaseId)`
`recurringPurchaseId`	`Long`	SALT recurring purchase ID returned when the purchase was originally created.
Returns:
`CreditCardReceipt`		The results of the hold

Core API: HttpsCreditCardService.resumeRecurringPurchase() Method
Name	Type	Description
`HttpsCreditCardService.resumeRecurringPurchase(recurringPurchaseId)`
`recurringPurchaseId`	`Long`	SALT recurring purchase ID returned when the purchase was originally created.
Returns:
`CreditCardReceipt`		The results of the hold

Cancelling a Payment

You can cancel a payment entirely by calling the cancelRecurringPurchase() method. This means that no further payments will be made regardless of whether the payment has reached its endDate. Note that you cannot resume or otherwise update a cancelled payment.

Core API: HttpsCreditCardService.cancelRecurringPurchase() Method
Name	Type	Description
`HttpsCreditCardService.cancelRecurringPurchase(recurringPurchaseId)`
`recurringPurchaseId`	`Long`	SALT recurring purchase ID returned when the purchase was originally created.
Returns:
`CreditCardReceipt`		The results of the cancellation

Updating Recurring Payment Details

To update the payment details of a recurring purchase such as when a customer credit card expires/is changed, you can use the updateRecurringPurchase() method. Note that you cannot update a recurring purchase that has been cancelled or that has completed.

If any parameters provided are null, the existing corresponding fields will not be updated.

Core API: HttpsCreditCardService.updateRecurringPurchase() Method
Name	Type	Description
`HttpsCreditCardService.updateRecurringPurchase(periodicPurchaseInfo, creditCard, storageTokenId, verificationRequest)`
`periodicPurchaseInfo`	`PeriodicPurchaseInfo`	Defines periodic-specific information, such as schedule, dates, and customer ID. See Table 3.10.
`creditCard`	`CreditCard`	Credit Card information (see Table 3.4). If storageTokenId is provided, this will be ignored
`storageTokenId`	`String(32)`	Storage Token ID specifying the stored credit card to use for this purchase. Takes precedence over the creditCard field.
`verificationRequest`	`VerificationRequest`	Credit Card Verification request information, null if not used. Note that CVV2 will not be stored/used in recurring purchases. See Section 5 for details on how to use this field.
Returns:
`CreditCardReceipt`		The results of the update request

Miscellaneous

The queryRecurringPurchase() method is a convenience method that you can use to check the current status of a recurring purchase, including the last successful payment made.

Core API: HttpsCreditCardService.queryRecurringPurchase() Method
Name	Type	Description
`HttpsCreditCardService.queryRecurringPurchase(recurringPurchaseId)`
`recurringPurchaseId`	`Long`	SALT recurring purchase ID returned when the purchase was originally created.
Returns:
`CreditCardReceipt`		The results of the query retrieve the `PeriodicPurchaseInfo` field for periodic purchase fields.

The PeriodicPurchaseInfo object contains a subset of the fields from the class:

periodicTransactionId the ID when the periodic purchase was originally created
state current state of the periodic purchase
nextPaymentDate next date the payment will be run
lastPaymentId the transaction ID of the last successful payment run. You can use this ID to run a verifyTransaction() to retrieve the transaction information.

Manual Periodic Payments Using the Merchant Management Website

If you do not need/want to manage Periodic Payments programmatically, you can always perform them manually using the Merchant Management Website:

Login to the SALT Merchant Management Website at https://test.saltpayments.com/merchantmanagement/
Select the Periodic Purchases Link under the Terminal section.
You can add a new Periodic Purchase by pressing the add a New Periodic Purchase link
You can view/update existing Periodic Purchases by using the search form (by date, order Id, etc)

Transaction Verification

In certain cases when you are unsure of the results of the transaction, such as when a transaction times out, you may need to double-check its status. You can run the verifyTransaction() method to perform this check. This method returns a receipt containing the results of the transaction.

Core API: HttpsCreditCardService.verifyTransaction() Method
Name	Type	Description
`HttpsCreditCardService.verifyTransaction(transactionId, transactionOrderId)`
`transactionId`	`Long`	The SALT transactionId of the transaction to verify
`transactionOrderId`	`String(32)`	The orderId assigned to the transaction.
Returns:
`CreditCardReceipt`		The results of the transaction verification request

You must specify at least one of the transactionId or transactionOrderId arguments.

Note that if the specified transaction cannot be found, you will receive a not-found C111_TRANSACTION_DOES_NOT_EXIST error in the receipt, as opposed to the results of the transaction.

Credit Card Verification

Use the verifyCreditCard() method to check the validity of a credit card without charging the customer (i.e. a $0.00 transaction). A CreditCardReceipt object is returned, containing information about the card validity, Secure Storage information if the card uses Secure Storage and Fraud information if the card uses the Advanced Fraud Suite.

IMPORTANT: American Express currently does not support card verification with a $0.00 value transaction. For Amex cards, you will have to use a small-value singlePurchase() ($1.00 is sufficient) instead.

Core API: HttpsCreditCardService.verifyCreditCard() Method
Name	Type	Description
`HttpsCreditCardService.verifyCreditCard(creditCard, verificationRequest)`
`creditCard`	`CreditCard`	Credit Card information (see Table 3.4)
`verificationRequest`	`Verification Request`	Credit Card Verification request information, null if not used. See Section 5 for details on how to use this field.
Returns:
`CreditCardReceipt`		The results of the `verifyCreditCard` request. (See Table 3.21)

Closing Batches

All batches are closed automatically every night at 12:00 am EST. If for some reason you want to close a batch manually during the day, this may be done by invoking the closeBatch() method. Note that this will NOT prevent the automatic daily batch closure.

`HttpsCreditCardService.closeBatch()`
Returns:
`CreditCardReceipt`	The results of the batch close

Updating Fraud

Applies only when using the Advanced Fraud Sute. This function allows you to update fraud service with the appropriate credit card authorization status if you are using a non-SALT payment processing service.

Core API: HttpsCreditCardService.updateFraud() Method
Name	Type	Description
`HttpsCreditCardService.updateFraud(Long transactionId, String fraudSessionId, String auth)`
`transactionId`	`Long`	Transaction ID number of the transaction whose fraud authentication is being updated. Cannot be null.
`fraudSessionId`	`String`	Fraud Session ID string. Cannot be null. Used to track which merchant is preforming the fraud update.
`auth`	`String`	Auth string. If null, will decline the update request.
Returns:
`CreditCardReceipt`		The results of the fraud update

Receipts

When a transaction has been completed, you must display a receipt to your customer. The following section describes the requirements of a receipt.

What do I need to display in a Receipt?

The required receipt fields listed below include the corresponding CreditCardReceipt field name as returned by SALT (where applicable). Note that there are different fields to be displayed depending on if the transaction was successful or unsuccessful.

In the case of a Successful Transaction, you must display:

Your Merchant Name
That the transaction was successful? (based on if isApproved() == true)
Invoice Number (getOrderId())
Amount of the transaction (getApprovalInfo().getAuthorizedAmount() field, be sure to convert back to dollars/cents and also to include currency)
Date of the transaction (getProcessedDateTime())
Approval Code (getApprovalInfo().getApprovalCode())
A button/link allowing the user to print the receipt page
Also, optionally:
- Last 4 digits of the Credit Card Number (never display the entire Credit Card number)
- A button/link allowing the customer to return to your home page/account page etc

In the case of an Unsuccessful Transaction, you must display:

Your Merchant Name
That the transaction was unsuccessful?(based on if isApproved() == false)
Date of the transaction (getProcessedDateTime())
About payment retries:
- If you allow the customer to try a different payment option (e.g.INTERAC Online) or to retry Credit Card payment, then indicate to the customer that they can retry payment (provide a link to the retry page or display the actual retry options).
- Otherwise display a clear statement that the order has been cancelled.
Also, optionally: Invoice Number (getOrderId())

Do NOT display the Approval Code or Card Number to the customer on an Unsuccessful Transaction.

Example Receipt/Error Pages

An example of an appropriate receipt for a successful transaction is shown below:

An Example Receipt Screen:

This receipt shows all required information, a print page link, and a return link. You can use this as a reference for the generation of your own receipt.

Below are two examples of an appropriate error page for an unsuccessful transaction:

Example Error Screen With Payment Retry:
Example Unsuccessful Receipt Screen

Example Error Screen With No Payment Retry (Order Cancellation):
Example Unsuccessful Receipt Screen (no retry)

Advanced Core API Features

Credit Card Security Features

To use the Client API Credit Card security features, you will need to use the full constructor for the CreditCard class, which includes additional data fields.

Name	Type	Description
`CreditCard` Constructor Parameters
`creditCardNumber`	`Long`	Credit Card Number
`expiryDate`	`Short`	Credit Card Expiry Date
`cvv2`	`String`	Card Verification Value/Card Verification Digits
`street`	`String`	Cardholder street address
`zip`	`String`	Cardholder zip/postal code
`secureCode`	`String`	Verified by Visa/MasterCard SecureCode value
`cardHolderName`	`String`	Credit Card Holder Name

Card Verification Value (CVV2)

The Card Verification Value (sometimes known as CVV2 or CVN is a security feature for credit card transactions, giving increased protection against credit card fraud. It is a series of digits (3 or 4) that can be usually found on the back of a credit card.

Many card issuers will decline a transaction if the CVV2 is not provided. If the value provided by the customer does not match the value on file with the card issuer, the issuer may decline the transaction (although this is not always the case).

Using CVV2

To use CVV2, you must

Collect and include the CVV2 value as part of the CreditCard object
Create a VerificationRequest with the Cvv2Request parameter set to CVV2_PRESENT.
Call the singlePurchase() method with the VerificationRequest.

Value	Description	Indicator*
`Cvv2Request`
`CVV2_NOT_SUBMITTED`	CVV2 value is deliberately bypassed or is not provided by the merchant.	0
`CVV2_PRESENT`	Cardholder states that the CVV2 value is present on the card and can be verified.	1
`CVV2_PRESENT_BUT_ILLEGIBLE`	Cardholder states that the CVV2 value is present on the card but it is illegible.	2
`CARD_HAS_NO_CVV2`	Cardholder states that the card has no value imprint.	9

* Denotes the indicator digit typically associated with CVV2 verification. Is not needed when using this API, but may be referred to in other documentation.

An example of a singlePurchase() with CVV2 checking is shown below:

import com.salt.payment.client.creditcard.api.*;
:
:
int merchantId=12345; // as assigned by SALT
String apiToken="DNZHRC6dNgppYYzR"; // as assigned by SALT
long pan=4242424242424242L;
short expiry=1212;
String invoice="order-12345"; // merchant invoice/orderId
String cvv2="888"; // CVV2 digits
long amount=3420; // in cents
HttpsCreditCardService ccService = new HttpsCreditCardService(
  new Merchant(merchantId, apiToken),  "https://test.saltpayments.com/gateway/creditcard/processor.do");
// specify additional credit card parameters
CreditCard creditCard = new CreditCard(pan, expiry, cvv2, null, null);
// specify the VerificationRequest contains an AvsRequest and/or Cvv2Request
VerificationRequest verify = new VerificationRequest(
  null,
  Cvv2Request.CVV2_PRESENT,
  );
CreditCardReceipt receipt =
  ccService.singlePurchase(invoice, creditCard, amount, verify);
:
:
// Extract Results from CreditCardReceipt...
:
:
// Verification results from CreditCardReceipt...
Cvv2Response cvv2Response = receipt.getCvv2Response();
:
:

The results of the CVV2 check are returned as a Cvv2Response object as part of the CreditCardReceipt.

Field (Accessor)	Type	Description
`Cvv2Response`
`getCode()`	`String`	CVV2 Response Code
`getMessage()`	`String`	CVV2 Response Message

The CVV2 response code will denote a match/mismatch:

Code	Description	Match
M	CVV2 Match	Match
N	CVV2 No Match	Mismatch
P	Not Processed	Unknown
S	Issuer indicates that CVV2 data should be present on the card, but the merchant has indicated data is not present on the card	Unknown
U	Issuer has not certified for CVV2 or Issuer has not provided Visa with the CVV2 encryption keys	Unknown
<blank>	CVV2 was not performed, occurs if you did not provide a cvv2 or an invalid cvv2 value	Unknown

Note that if a CVV2 check results in a mismatch or is not supported by the cardholder financial institution, this does NOT necessarily mean that a transaction will be declined. Some financial institutions may decline but others will not. CVV2 gives you additional information on which you can base your decision whether or not to accept the transaction as legitimate . If the financial institution does not decline the transaction, and you choose not to accept the transaction, you must issue a void against it. (See Section 3.4 on how to perform a void)

Address Verification System (AVS)

Address Verification System (AVS) provides additional security by comparing a given billing address against the address on file at the cardholder financial institution. If an AVS check indicates that the address does not fully match, you may have cause to suspect a possibly fraudulent transaction.

The result of an AVS check is a letter code indicating the degree of match, which can be full, partial, or a mismatch. Some financial institutions, in particular those outside the US, Canada, and UK, may not support AVS checking which can result in a corresponding not supportedmresponse code being returned.

Note that if an AVS check results in a mismatch or is not supported by the cardholder financial institution, this does NOT necessarily mean that a transaction will be rejected. AVS only gives you additional information on which you can base your decision whether or not to accept the transaction as legitimate. If you choose not to accept the transaction, you must issue a void against it

Using AVS

To use AVS, you must

Collect and include the customer zip/postal code and address as part of the CreditCard object
Create a VerificationRequest with the AvsRequest parameter set.
Call the singlePurchase() method with the VerificationRequest.

Value	Description
`AvsRequest`
VERIFY_STREET_AND_ZIP	Verify that both specified street number & name (combined) and zip/postal code of the cardholder matches the values in the cardholder issuer file.
VERIFY_ZIP_ONLY	Verify that specified zip/postal code of the cardholder matches the value in the cardholder issuer file. If this is specified, address will not be verified

An example of a singlePurchase() with AVS checking is shown below:

import com.salt.payment.client.creditcard.api.*;
:
:
int merchantId=12345; // as assigned by SALT
String apiToken="DNZHRC6dNgppYYzR"; // as assigned by SALT
long pan=4242424242424242L;
short expiry=1212;
String invoice="order-12345"; // merchant invoice/orderId
String avsStreet="123 Easy Street"; // AVS Street number and name
String avsZip="A1B2C3"; // AVS ZIP/Postal code
long amount=3420; // in cents
HttpsCreditCardService ccService = new HttpsCreditCardService(
  new Merchant(merchantId, apiToken),  "https://test.saltpayments.com/gateway/creditcard/processor.do");
// specify additional credit card parameters
CreditCard creditCard = new CreditCard(pan, expiry, null, avsStreet, avsZip);
// specify the VerificationRequest contains an AvsRequest and/or Cvv2Request
VerificationRequest verify = new VerificationRequest(
  AvsRequest.VERIFY_STREET_AND_ZIP,
  null
);
CreditCardReceipt receipt =
  ccService.singlePurchase(invoice, creditCard, amount, verify);
:
:
// Extract Results from CreditCardReceipt...
:
:
// Verification results from CreditCardReceipt...
AvsResponse avsResponse = receipt.getAvsResponse();
:
:

The results of the AVS request are returned as an AvsResponse object as part of the CreditCardReceipt.

Field (Accessor)	Type	Description
`AvsResponse`
`getAvsErrorCode()`	`String`	The code of the error that prevented AVS from being performed, or null if no error
`getAvsErrorMessage()`	`String`	The message of the error that prevented AVS from being performed, or null if no error
`getAvsResponseCode()`	`String`	The standard alphabetic AVS response code (see Table 5.7)
`getZipType()`	`String`	The type of the zip (either zip or postal code) or null if there was an AVS error
`isAvsPerformed()`	`Boolean`	true if AVS was performed, false if it wasn't
`isStreetFormatValid()`	`Boolean`	true if the street format is valid, false otherwise
`isStreetFormatValidAndMatched()`	Boolean	true if the street format is valid and matches
`isZipFormatValid()`	`Boolean`	true if the zip/postal code format is valid, false otherwise
`isZipFormatValidAndMatched()`	Boolean	true if the zip/postal code format is valid and matches

The getResponseCode() field indicates: a full match (both address and zip/postal match), a partial match (one field matches), a mismatch (both do not match), or unknown (AVS may be unavailable/unsupported by this cardholder bank).

Code	Description	Match
A	Street address matches, but zip/postal does not (Domestic)	Partial
B	Street address matches, but postal code not verified (International)	Partial
C	Street address and postal code do not match (International)	Mismatch
D, M	Street address and postal code match (International)	Full Match
E	AVS data invalid or not allowed for this card type	Unknown
G	Non-US bank does not support AVS	Unknown
I	Address not verified	Unknown
N	Street address and postal code do not match (Domestic)	Mismatch
P	Postal code matches, but street address not verified (International)	Partial
R	System unavailable (Domestic)	Unknown
S	Bank Does not support AVS (Domestic)	Unknown
U	Address information unavailable. Returned if the US bank does not support non-US AVS or if the AVS in a US bank is not functioning properly.	Unknown
W, Z	Street address does not match, but zip code matches (Domestic)	Partial
X, Y	Street address and zip code match (Domestic)	Full Match
<blank>	AVS was not performed, occurs if you did not provide a billing address	Unknown

Suggestions for Interpreting/Handling an AVS Response

AVS is not a foolproof security feature, so even if a full match is obtained, there is no guarantee that a transaction is not fraudulent. However, a partial, or better yet, full match makes it more likely that whoever is submitting the transaction is the real cardholder (since they have access to the correct address information, which typically only appears the cardholder statement).

Below are some suggestions for the interpretation/handling of AVS responses. Please note that these are just suggestions and the ultimate decision of whether or not to accept a transaction is still up to you. Also remember that if you do not want to accept a transaction, you must void it yourself.

Partial Match Typically if the user has one part of the address correct, they probably know the entire address. Of course, a full match is more reassuring, but sometimes a partial match occurs because of differences in the formats of the entered address and the address on file (for example, sometimes the cardholder may enter the unit number before their street number).
Mismatch You probably should not accept this transaction without confirming with the cardholder directly.
Unknown If the cardholder address is international, you may see this result. If you typically do business with international customers, then this will be expected. Otherwise, you may want to consider whether or not to accept the transaction.

Secure Storage API

With the Secure Storage API, merchants can remotely store credit card and other sensitive customer data with SALT to increase security and reduce the scope of PCI Compliance.

When information is stored with SALT, a Storage Token (which identifies the information in secure storage) is returned in response. This Storage Token can be used for all subsequent transactions including purchases and credit card verification.

Storing Customer Information (Creating a Storage Token)

Name	Type	Description
`HttpsCreditCardService.addToStorage(paymentProfile, storageTokenId)`
`storageTokenId`	`String(32)`	Optional. Specifies the identifier (storage token) for the stored information. Must be unique. If not provided, SALT will auto-generate one for you.
`paymentProfile`	`PaymentProfile`	Contains the customer information to be stored. See Table 5.9 for details
Returns:
`StorageReceipt`		The results of the storage request

The PaymentProfile class contains a CreditCard data object as well as a CustomerProfile data object. The basic constructor is shown below.

Name	Type	Description
`PaymentProfile` Constructor Parameters
`creditCard`	`CreditCard`	Contains Credit Card information, optional. However, if you intend to run transactions with this PaymentProfile you must provide this field.
`customerProfile`	`CustomerProfile`	Contains Customer information, optional. See Table 5.10 for details

The CreditCard class is described in Table 5.1. Note that CVV2 will not be stored, even if specified.

The CustomerProfile class allows you to store various customer details such as name and address. All fields are completely optional you can choose to store any or all of the following fields:

Field	Type	Description
`CustomerProfile`
`setFirstName()`	`String`	Customer first name
`setLastName()`	`String`	Customer last name
`setAddress1()`	`String`	Address 1 (first line of address)
`setAddress2()`	`String`	Address 2 (second line of address)
`setCity()`	`String`	City
`setProvince()`	`String`	Province/State
`setPostal()`	`String`	Postal/ZIP Code
`setCountry()`	`String`	Country
`setPhoneNumber()`	`String`	Customer Phone Number
`setFaxNumber()`	`String`	Customer Fax Number
`setWebsite()`	`String`	Customer website
`setLegalName()`	`String`	Customer Company Legal Name
`setTradeName()`	`String`	Customer Company Trade Name

An example of storing customer data (credit card and customer profile) is shown below:

import com.salt.payment.client.creditcard.api.*;
:
:
int merchantId=12345; // as assigned by SALT
String apiToken="DNZHRC6dNgppYYzR"; // as assigned by SALT
String storageTokenId="myToken-001"; // will be used to identify the storage record
long ccNumber=4242424242424242L; // Credit Card Number
short ccExpiry=1212; // Credit Card Expiry
String firstName="John"; // Customer first name
String lastName="Smith"; // Customer last name
String address1="123 Easy Street"; // Customer address1
String postal="A1B2C3"; // Customer Postal code
String phone="4165551234"; // Customer phone number
HttpsCreditCardService ccService = new HttpsCreditCardService(
    new Merchant(merchantId, apiToken), "https://test.saltpayments.com/gateway/creditcard/processor.do");
// credit card to store
CreditCard creditCard = new CreditCard(ccNumber, ccExpiry);
// customer profile details to store
CustomerProfile customerProfile = new CustomerProfile();
customerProfile.setFirstName(firstName);
customerProfile.setLastName(lastName);
customerProfile.setAddress1(address1);
customerProfile.setPostal(postal);
customerProfile.setPhoneNumber(phone);

// put together data into a payment profile
PaymentProfile paymentProfile = new PaymentProfile(creditCard, customerProfile);

// Store the data under the specified storageTokenId
StorageReceipt receipt =
  ccService.addToStorage(storageTokenId, paymentProfile);
:
:
// Use Results from StorageReceipt...
if (receipt.isApproved()) {
  :
  :
}

The results of the storage request are returned as a StorageReceipt object. This is a data class similar to the CreditCardReceipt, and contains the following fields:

Field	Type	Description
`StorageReceipt`
`getDebugMessage()`	`String`	Debug message, if applicable
`getErrorCode()`	`String`	Error code, if applicable
`getErrorMessage()`	`String`	Error message, if applicable
`getProcessedDateTime()`	`Date`	Date/time when the transaction was processed
`getPaymentProfile()`	`PaymentProfile`	Payment profile retrieved or updates (via the storage query or update methods). For creation/deletion, this field is null
`getStorageTokenId()`	`String(32)`	The storageTokenId used. For storage record creation where no storageTokenId was specified, this will contain the value of the SALT-generated storageTokenId.
`isApproved()`	`Boolean`	Returns true if the request was approved, otherwise the request was declined due to some error.

Running a Transaction with a Storage Token

Once you have created a Storage Token, you can use it in place of a CreditCard object in any transaction that requires a credit card. The SALT Gateway will use the storageTokenId to look up the stored credit card information, which in turn will be used in the transaction.

IMPORTANT: Credit card information is required to be stored in order to run transactions with the storage token. If you do not provide this information when creating/updating the storage record (for example, if you are just storing the customer profile), then you will be unable to use that storage token to run a transaction

To use the storageTokenId, all you need to do is call the appropriate Storage Token transaction methods (which are the same as the credit card methods, just replacing the credit card with the token). The Storage Token singlePurchase() is shown below:

Name	Type	Description
`HttpsCreditCardService.singlePurchase(orderId, storageTokenId, amount, verificationRequest)`
`orderId`	`String(32)`	Merchant assigned orderId. Must be unique.
`storageTokenId`	`String(32)`	Storage Token ID as returned to you/specified by you when the storage record was created, will specify the stored credit card to use for this purchase.
`amount`	`Long`	Amount of the purchase in cents. Do NOT include a $ or any decimal place. (e.g. if your purchase is $10.00, then send 1000 as the total).
`verificationRequest`	`Verification Request`	Credit Card Verification request information, null if not used. See Section 5.1 for details on how to use this field. Note that because CVV2 is not stored, you cannot specify a CVV2 check.
Returns:
`CreditCardReceipt`		The results of the purchase request

There is a method that can provide the merchant a combined transaction for both purchase and secure storage creation.

Name	Type	Description
`HttpsCreditCardService.singlePurchase(orderId, storageTokenId, amount, verificationRequest)`
`orderId`	`String(32)`	Merchant assigned orderId. Must be unique.
`creditCard`	`CreditCard`	Credit Card information (see Table 3.4)
`amount`	`Long`	Amount of the purchase in cents. Do NOT include a $ or any decimal place. (e.g. if your purchase is $10.00, then send 1000 as the total).
`verificationRequest`	`Verification Request`	Credit Card Verification request information, null if not used. See Section 5.1 for details on how to use this field. Note that because CVV2 is not stored, you cannot specify a CVV2 check.
`storageTokenId`	`String(32)`	The secure storage token id that will be used to create storage record for this credit card.
Returns:
`CreditCardReceipt`		The results of the purchase request

The other methods that can use the storageTokenId are:

recurringPurchase (orderId, storageTokenId, perPaymentAmount, startDate, endDate, schedule, verificationRequest)
updateRecurringPurchase (recurringPurchaseId, storageTokenId, perPaymentAmount, verificationRequest)
verifyCreditCard (storageTokenId, verificationRequest)
verifyCreditCard (creditCard, verificationRequest, storageTokenId)

Querying for Stored Information

You can query and retrieve the contents of any previously stored customer information.

Name	Type	Description
`HttpsCreditCardService.queryStorage(storageTokenId)`
`storageTokenId`	`String(32)`	The Storage Token ID of the stored information to retrieve.
Returns:
`StorageReceipt`		The results of the query request

You can access the data through StorageReceipt.getPaymentProfile() and then retrieving the contained creditCard and/or customerProfile.

IMPORTANT: For security purposes, the credit card number returned will always be only the last 4 digits of the full credit card number. All other data will be returned in its original form, including the card expiry date and all of the customer profile information.

Updating and Deleting Stored Information

If you need to update/modify a stored record:

Name	Type	Description
`HttpsCreditCardService.updateStorage(storageTokenId, paymentProfile)`
`storageTokenId`	`String(32)`	The Storage Token ID of the stored information to update.
`paymentProfile`	`PaymentProfile`	Customer information to be stored. Will overwrite any existing customer information.
Returns:
`StorageReceipt`		The results of the update request

The provided PaymentProfile will overwrite any existing data. If a null value is provided for the PaymentProfile creditCard or customerProfile parameters, then the corresponding stored data will be deleted. Note that even if you delete all of the data, the record itself will still exist (but be blank).

If you need to delete a stored record altogether:

Name	Type	Description
`HttpsCreditCardService.deleteFromStorage(storageTokenId)`
`storageTokenId`	`String(32)`	The Storage Token ID of the stored information to delete.
Returns:
`StorageReceipt`		The results of the delete request

Deleting a record will free up the associated storageTokenId for re-use.

Non-Page Specific Requirements

General Requirements

Domain: The domain of the merchant website must be registered to the merchant

Customer Notification of Transaction Results

The customer must have a means to receive notification of the results of a transaction through a separate channel in addition to display on screen. This is to ensure that even in the case of an accident such as the customer closing their browser, the customer will still be able to determine if the transaction succeeded or failed.

Suggested means of implementing such a feature:

Email Notification: Send an email notification/receipt to the customer, in both success and failure cases. The email should contain the same information as on the receipt.
Self-Serve: Allow the customer to check the status of their transaction through a website or other such system.

If you do not already have such a feature it is recommended that the Email Notification method be used for ease of implementation.

Security and Privacy

Your store must make a Privacy Statement/Policy clearly available to the customer. A Privacy Statement should tell the customer:

What kinds of personal information are being collected,
What purpose(s) this information is used for,
How this information is protected, and
Under what circumstances this information is shared (if at all)

You must adhere to the following security and privacy requirements:

SSL Certificate: Your website must use at least 128-bit SSL encryption with a valid Certificate. In particular the page where the customer enters their credit card information must be secured.
- The ownership status on the SSL Certificate should be registered to the merchant or the developer of the website.
Consumer Information: You may collect a consumer personal information so long as
- You do not retain the customer credit card information. You may only collect this information for the sole purpose of submitting a transaction through the Client API, afterwards it must not be stored.
- You have procedures to control access/protect personal information
Code of Practice: Adhere to the Canadian Code of Practice for Consumer Protection in Electronic Commerce: http://cmcweb.ca/epic/internet/incmc-cmc.nsf/en/fe00064e.html

Certification

Credit card associations, including Visa and Mastercard, require that all merchants offering online credit card payment follow a set of standard guidelines for implementation. The process of verifying that your website meets the card association requirements is known as Certification.

Approval for processing may be contingent on meeting these guidelines, depending on your credit card processor.

Approval

A full Approval requires a fully-functional, secure and complete e-commerce website to be created by the merchant. Since you will want to obtain some kind of approval before actually starting integration, you will typically go for a Conditional Approval first if supported by your processor (see below).

Conditional Approval

A Conditional Approval can be granted to a merchant who has not yet integrated their site with the SALT Payment Gateway. A Conditional Approval means that you are guaranteed a full Approval so long as the payment portion of your site is completed.

As long as the informational parts of your website are complete (product, return/refund policy, delivery policy, and privacy policy), you can be conditionally approved.

Important notes about Conditional Approval:

It allows you to process REAL credit card payments
It will expire after a set time period if full approval is not obtained by that point, your entire application will have to be re-submitted. A typical validity period is 30 days.
No integration is required to obtain Conditional Approval

Certification Checklist

Each merchant implementation must undergo a brief certification process to obtain approval. To complete certification, you will need to supply SALT with:

The URL to your credit card store implementation
Any instructions (logins, registration etc) needed to complete a test purchase

SALT and the processor will conduct a review of your site, and once this is complete you will receive the appropriate approval(s). Please ensure that you have met all website requirements before submitting your request.

The following self-assessment checklist summarizes the requirements that need to be met:

✔	Requirement	Description
	Correlation between business and product/service	There should be a correlation between the registered merchant name and the product/service offered.
	Customer service contact provided	There must be a clear posting of a Customer Service Telephone # or Email Address.
	Return/Refund policy	Return/refund policy is clearly stated on the merchant website.
	Delivery policy	The merchant's delivery methods and timing are clearly described
	*Display correct receipt	The receipt presented to the customer after a successful or unsuccessful transaction must contain certain fields. Make sure to follow the guidelines presented in the Receipts section.
	*Display timeout warning (if applicable)	Display a warning message to the customer if the customer has < 30 minutes to complete payment (e.g. their session times out). If there is no such restriction, no message needs to be displayed
	Product/service description	The product/service offered for sale is clearly described
	*Display correct currency	Must indicate the currency of payment (e.g. USD, CAD). Explicitly indicate the currency type on the payment total
	English language option	There must be an English translation option for foreign language websites
	*Customer Notification	You must have some way for a customer to be notified/determine the status of a transaction. Follow the requirements presented in the Non-page-specific requirements section.
	Age Verification	The website includes an age Verification process for products sold that require age verification (alcohol, tobacco etc.).
	Customer Ready?	The website must be ready to accept real orders from customers at the website URL specified in your application the site should NOT use language/pages that imply that it is coming soon or under construction or use a testing URL (e.g. www.yourdomain.com/test)
	Privacy Policy	Make sure a privacy policy/statement is clearly stated on your website.
	*Secure Payment Page	Ensure that you have an SSL Certificate protecting your payment information entry page. Follow the requirements presented in the Non-page-specific requirements section.

* Required for full approval, but not required for conditional approval

Moving to Production

Once certification is complete, you will be ready to move to the SALT Production environment. Moving to the Production environment involves changing the API handler URL to the production URL, and verifying your configuration settings in the production Merchant Management Website.

Production Site	URL
SALT Merchant Management Website	https://manage.saltpayments.com/merchantmanagement/
Payment API Handler	https://gateway.saltpayments.com/gateway/creditcard/processor.do

When you want to move to production:

Notify SALT so that we can enable your account on our production system.
Where you invoke the SALT Client API, change the SALT API Handler URL from https://test.saltpayments.com/gateway/creditcard/processor.do to https://gateway.saltpayments.com/gateway/creditcard/processor.do.
Finally, verify that your account is enabled and that your configurations are correct by logging into the production Merchant Management Website at https://manage.saltpayments.com/merchantmanagement/.

Appendix

Differences Between INTERAC Online and Credit Card Integration

The INTERAC Online and Credit Card Client API integrations are similar, with a few minor differences listed below:

Area	INTERAC Online	Credit Card
Client API URL	Ends with iop/merchantprocessor.do	Ends with cc/processor.do
Purchase Transaction	Is created through an HTTP POST to the SALT Payment Handler	Is performed directly through the SALT Client API
Entry of Payment Information	Banking information is entered at the customer online banking website, it is not seen by the merchant	Credit card information is entered into your website (but must not be retained)
Transaction Types	Purchase, Refund (there is no Void or Periodic Purchase in IOP)	Purchase, Refund, Void, Periodic Purchase, Secure Storage
Secure Payment Page	Not required because no banking information is entered on your website.	Page where credit card information is entered on your website must be protected by a valid SSL certificate

Client API for Other Programming Languages

Microsoft .NET

The SALT Client API is available for Microsoft .NET (for both .NET Framework versions 1.1 and 2.0). Below is a sample code fragment of a single purchase with the .NET Client API (in C#):

using com.salt.payment.client.creditcard.api;
:
:
int merchantId=12345; // your SALT merchantId
string apiToken="a3fer6321asdf1HY"; // your SALT API token
long pan = 4242424242424242; // Credit Card Number
short expiry = 1212; // Credit Card Expiry
string invoice="unique invoice"; // assign a unique invoice number
long amount = 10000; // amount of txn

HttpsCreditCardService ccService = new HttpsCreditCardService(new Merchant(merchantId, apiToken), "https://test.saltpayments.com/gateway/creditcard/processor.do");
CreditCard creditCard = new CreditCard(pan, expiry);
CreditCardReceipt resp = null;
resp = ccService.singlePurchase(invoice, creditCard, amount, null);

if(resp.isApproved()){
    Console.WriteLine("TransactionId: {0}",resp.getTransactionId());
    Console.WriteLine("ApprovalInfo: {0}", resp.getApprovalInfo().ToString());
} else {
    // display error for debugging: it is recommended not to display full error
    // message to external user
    Console.WriteLine("Error Code: {0} Message: {1}",
    resp.getErrorCode(),resp.getErrorMessage());
}

Package and Versioning

The SALT Credit Card Client API for Microsoft .NET package will contain the following:

admeriscc[dot net version].dll (where dot net version = version of .NET Framework)
CCGatewayTest.exe tests credit card functions
StorageGatewayTest.exe tests secure storage functions

Copy the admeriscc*.dll to your web bin folder. The Test executable files are provided so that you can quickly test some of the gateway functions from the command line. Run the executable(s) with no arguments for usage instructions.

PHP

The SALT Client API is available for PHP 4.3 (or greater). Below is a sample code fragment of a single purchase with the PHP Client API.

<?php
    include "HttpsCreditCardService.php";
    :
    :
    $merchantId=12345; // your SALT merchantId
    $apiToken="a3fer6321asdf1HY"; // your SALT API token
    $pan = 4242424242424242; // Credit Card Number
    $expiry = 1212; // Credit Card Expiry
    $invoice="unique invoice"; // assign a unique invoice number
    $amount = 10000; // amount of txn
    $ccService = new HttpsCreditCardService($merchantId, $apiToken,
        "https://test.saltpayments.com/gateway/creditcard/processor.do");
    $creditCard = new CreditCard($pan, $expiry);
    $resp = $ccService->singlePurchase($invoice, $creditCard, $amount, null);
    if($resp->isApproved()){
        print_r($resp->params);
    } else {
        // display error for debugging: it not recommended to display full error
        // message to external users
        echo "Error Code: " . $resp->getErrorCode() . "Message: " .
        $resp->getErrorMessage();
    }
?>

Below is an example of a Single Purchase with Secure Storage in PHP:

<?php
    include "HttpsCreditCardService.php";
    :
    :
    $merchantId=12345; // your SALT merchantId
    $apiToken="a3fer6321asdf1HY"; // your SALT API token
    $pan = 4242424242424242; // Credit Card Number
    $expiry = 1212; // Credit Card Expiry
    $invoice="unique invoice"; // assign a unique invoice number
    $amount = 10000; // amount of txn
    $storage="token123"
    // Credit Card Storage Token Id
    $ccService = new HttpsCreditCardService($merchantId, $apiToken,
        "https://test.saltpayments.com/gateway/creditcard/processor.do");
    $creditCard = new CreditCard($pan, $expiry);
    $resp = $ccService->singlePurchase($invoice, $creditCard, $amount, null, $storageTokenId);
    if($resp->isApproved()){
        print_r($resp->params);
    } else {
        // display error for debugging: it is recommended not to display full error
        // message to external user
        echo "Error Code: " . $resp->getErrorCode() . "Message: " .
        $resp->getErrorMessage();
    }
?>

Mail Support

Main Menu