HTTPS POST API Reference

This document is meant as a complete reference for the features of the SALT Technology Credit Card POST API.

The POST API allows you to integrate your website with the SALT payment platform via HTTPS POST requests and can be used instead of the SALT Client Libraries.


Single Purchase

The singlePurchase method runs a one-time charge against a credit card.

requestCode "singlePurchase"
merchantId Your merchant ID.
apiToken Your API Token.
marketSegmentCode I (Internet) or M (Mail/Telephone)
orderId Merchant assigned orderId.
creditCardNumber The PAN of the paying credit card.
expiryDate The expiry of the paying credit card in the format MMYY.
storageTokenId If the customer is stored in Secure Storage, you can supply this ID instead of the customer's credit card credentials.
amount The amount of the purchase in cents.
avsRequestCode 0 or 1, Whether or not you require AVS.
cvv2RequestCode 0 or 1, Whether or not you require CVV2.

Example Single Purchase

requestCode=singlePurchase
merchantId=1
apiToken=token
marketSegmentCode=I
orderId=orderid
creditCardNumber=4242424242424242
expiryDate=1231
amount=1000
avsRequestCode=0
cvv2RequestCode=1

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).

requestCode"void"
merchantIdYour merchant ID.
apiToken Your API Token.
marketSegmentCodeI (Internet) or M (Mail/Telephone)
transactionIdThe ID of the transaction you are voiding.
transactionOrderIdThe order Id of the transaction you are voiding.

Example Void

requestCode=void
merchantId=1
apiToken=token
marketSegmentCode=I
transactionId=1
transactionOrderId=orderid

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.

requestCode"refund"
merchantIdYour merchant ID.
apiToken Your API Token.
marketSegmentCodeI (Internet) or M (Mail/Telephone)
transactionIdThe ID of the transaction you are refunding.
transactionOrderIdThe order Id of the transaction you are refunding.
orderIdThe merchant assigned orderId to be attached to this refund request. amountThe amount of the purchase in cents.

Example Refund

requestCode=refund
merchantId=1
apiToken=token
marketSegmentCode=I
transactionId=1
transactionOrderId=orderid
orderId=refundid
amount=1000

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.

requestCode"verifyTransaction"
merchantIdYour merchant ID.
apiToken Your API Token.
marketSegmentCodeI (Internet) or M (Mail/Telephone)
transactionIdThe ID of the transaction you are verifying.

Example Transaction Verification

requestCode=verifyTransaction
merchantId=1
apiToken=token
marketSegmentCode=I
transactionId=1

Credit Card Verification

Use a verifyCreditCard request to check the status of a credit card. The returned receipt will contain information about the card’s validity, Secure Storage information if the card uses Secure Storage and Fraud information if the card uses the Advanced Fraud Suite.

requestCode"verifyCreditCard"
merchantIdYour merchant ID.
apiToken Your API Token.
marketSegmentCodeI (Internet) or M (Mail/Telephone)
creditCardNumberThe PAN of the paying credit card.
expiryDateThe expiry of the paying credit card in the format MMYY.
avsRequestCode0 or 1, Whether or not your require AVS.
cvv2RequestCode0 or 1, Whether or not your require CVV2.

Example Credit Card Verification

requestCode=verifyCreditCard
merchantId=
apiToken=yourtoken
marketSegmentCode=I
creditCardNumber=4242424242424242
expiryDate=1231
avsRequestCode=0
cvv2RequestCode=1

Recurring Payments

You can use SALT’s Recurring Payment feature when the customer is billed periodically, or when splitting payment into a number of separate payments.

To create a recurring payment:

requestCode"recurringPurchase"
merchantIdYour merchant ID.
apiToken Your API Token.
marketSegmentCodeI (Internet) or M (Mail/Telephone)
operationCodecreate
amountThe amount of the purchase in cents.
periodicPurchaseStateCodeone of NEW(0), IN_PROGRESS(1), COMPLETE(2), ON_HOLD(3), CANCELLED(4), ERROR(5)
periodicPurchaseScheduleTypeCodeone of MONTH(0), WEEK(1), DAY(2)
periodicPurchaseIntervalLengthDuration of the interval.
orderIdMerchant assigned orderId.
customerIdOptional meta field that can be used to describe a customer.
startDateThe 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.
endDateThe date of when to end the payments. A payment will not be issued if it falls on this date
nextPaymentDateChange when the next payment will occur.
creditCardNumberThe PAN of the paying credit card.
expiryDateThe expiry of the paying credit card in the format MMYY.
storageTokenIdIf the customer is stored in Secure Storage, you can supply this ID instead of the customer's credit card credentials.
avsRequestCode0 or 1, Whether or not your require AVS.
cvv2RequestCode0 or 1, Whether or not your require CVV2.

To execute a recurring payment:

merchantIdYour merchant ID.
apiToken Your API Token.
marketSegmentCodeI (Internet) or M (Mail/Telephone)
operationCode"execute"
cvv2The purchasing credit card's CVV2.
transactionOrderIdThe order Id of the transaction you are executing.

To hold/resume/cancel a recurring payment:

requestCode"recurringPurchase"
merchantIdYour merchant ID.
apiToken Your API Token.
marketSegmentCodeI (Internet) or M (Mail/Telephone)
operationCode"update"
transactionOrderIdThe order Id of the transaction you are updating.
periodicPurchaseStateCode1 = resume, 3 = hold, 4 = cancel

Create Recurring Purchase

requestCode=recurringPurchase
merchantId=1
apiToken=token
marketSegmentCode=I
operationCode=create
amount=1000
periodicPurchaseStateCode=0
periodicPurchaseScheduleTypeCode=2
periodicPurchaseIntervalLength=5
orderId=orderid
customerId=customerid
startDate=2013-06-17
endDate=2013-06-17
nextPaymentDate=2013-06-17
creditCardNumber=4242424242424242
expiryDate=1231
avsRequestCode=0
cvv2RequestCode=1

Execute Recurring Purchase

requestCode=recurringPurchase
merchantId=1
apiToken=token
marketSegmentCode=I
operationCode=execute
cvv2=cvv
transactionId=1

Hold Recurring Purchase

requestCode=recurringPurchase
merchantId=1
apiToken=token
marketSegmentCode=I
operationCode=update
transactionId=1
periodicPurchaseStateCode=3

Resume Recurring Purchase

requestCode=recurringPurchase
merchantId=1
apiToken=token
marketSegmentCode=I
operationCode=update
transactionId=1
periodicPurchaseStateCode=1

Update Recurring Purchase

requestCode=recurringPurchase
merchantId=1
apiToken=token
marketSegmentCode=I
operationCode=update
transactionId=0
amount=1000
periodicPurchaseStateCode=0
periodicPurchaseScheduleTypeCode=2
periodicPurchaseIntervalLength=5
orderId=orderid
customerId=customerid
startDate=2013-06-17
endDate=2013-06-17
nextPaymentDate=2013-06-17
creditCardNumber=4444444444444444
expiryDate=1231
avsRequestCode=0
cvv2RequestCode=1

Cancel Recurring Purchase

requestCode=recurringPurchase
merchantId=1
apiToken=token
marketSegmentCode=I
operationCode=update
transactionId=1
periodicPurchaseStateCode=4

Batch Closure

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 with a batch request. Note that this will NOT prevent the automatic daily batch closure.

requestCode"batch"
merchantIdYour merchant ID.
apiTokenYour API Token.
marketSegmentCodeI (Internet) or M (Mail/Telephone)
operationCodeclose

Example Batch Closure

requestCode=batch
merchantId=1
apiToken=token
marketSegmentCode=I
operationCode=close

Fraud

Allow merchants to update fraud AUTH status if they use other payment processing service.

requestCode"fraudUpdate"
merchantIdYour merchant ID.
apiToken Your API Token.
marketSegmentCodeI (Internet) or M (Mail/Telephone)
transactionIdThe ID of the transaction you are updating.
fraudSessionIdFraud Session ID string.
authAuth string.

Example Fraud Update

requestCode=fraudUpdate
merchantId=1
apiToken=
marketSegmentCode=I
transactionId=1
fraudSessionId=fraudid
auth=auth

Secure Storage

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.

requestCode"secureStorage"
merchantIdYour merchant ID.
apiToken Your API Token.
marketSegmentCodeI (Internet) or M (Mail/Telephone)
operationCode"create"
storageTokenIdMerchant defined storage token ID.
creditCardNumberThe PAN of the paying credit card.
expiryDateThe expiry of the paying credit card in the format MMYY.
profileFirstNameThe customer's first name.
profileLastNameThe customer's last name.
profilePhoneNumberThe customer's phone number.
profileAddress1The customer's address.
profilePostalThe customer's postal code.

Example Secure Storage Creation

requestCode=secureStorage
merchantId=1
apiToken=token
marketSegmentCode=I
operationCode=create
storageTokenId=token
creditCardNumber=4242424242424242
expiryDate=1231
profileFirstName=firstName
profileLastName=lastName
profilePhoneNumber=555-555-5555
profileAddress1=address1
profilePostal=postal

Example Recurring Purchase with Secure Storage

requestCode=recurringPurchase
merchantId=1
apiToken=token
marketSegmentCode=I
operationCode=create
amount=1000
periodicPurchaseStateCode=0
periodicPurchaseScheduleTypeCode=2
periodicPurchaseIntervalLength=5
orderId=orderid
customerId=customerid
startDate=2013-06-17
endDate=2013-06-17
nextPaymentDate=2013-06-17
storageTokenId=token
avsRequestCode=0
cvv2RequestCode=1

Example Update Secure Storage

requestCode=secureStorage
merchantId=1
apiToken=token
marketSegmentCode=I
operationCode=update
storageTokenId=token
creditCardNumber=4012888888881881
expiryDate=1010

Example Query Secure Storage

requestCode=secureStorage
merchantId=1
apiToken=token
marketSegmentCode=I
operationCode=query
storageTokenId=token

Receipts

These following lists contain the return parameters you can expect to receive back from each type of call

Batch
BATCH_SALE_AMOUNT
APPROVED
BATCH_NET_COUNT
BATCH_SALE_COUNT
BATCH_NET_AMOUNT
BATCH_RETURN_AMOUNT
BATCH_VOID_COUNT
BATCH_RETURN_COUNT
BATCH_VOID_AMOUNT
PROCESSED_DATE
PROCESSED_TIME
ERROR_MESSAGE
ERROR_CODE

Successful Purchase
ORDER_ID
CVV2_RESPONSE_AVAILABLE
PROCESSED_TIME
TRANSACTION_ID
REFERENCE_NUMBER
TRACE_NUMBER
CVV2_RESPONSE_CODE
CARD_BRAND
RESPONSE_HASH
AUTHORIZED_AMOUNT
ERROR_CODE
STORAGE_TOKEN_EXPIRY
DEBUG_MESSAGE
ERROR_MESSAGE
CARD_NUMBER
PROCESSED_DATE
CVV2_RESPONSE_MESSAGE
APPROVAL_CODE
APPROVED

Failed Purchase
DEBUG_MESSAGE
ERROR_CODE
APPROVED
ERROR_MESSAGE
PROCESSED_TIME
PROCESSED_DATE

Recurring Purchase Created
APPROVED
TRANSACTION_ID
PERIODIC_TRANSACTION_ID
AUTHORIZED_AMOUNT
DEBUG_MESSAGE
PERIODIC_TRANSACTION_STATE
ORDER_ID
TRACE_NUMBER
PROCESSED_DATE
PROCESSED_TIME
ERROR_MESSAGE
ERROR_CODE

Secure Storage
CUSTOMER_PROFILE_PROVINCE
CUSTOMER_PROFILE_ADDRESS2
CUSTOMER_PROFILE_ADDRESS1
CUSTOMER_PROFILE_AVAILABLE
PROCESSED_TIME
CUSTOMER_PROFILE_FIRST_NAME
ERROR_CODE
PAYMENT_PROFILE_AVAILABLE
DEBUG_MESSAGE
CREDIT_CARD_AVAILABLE
CUSTOMER_PROFILE_LAST_NAME
CREDIT_CARD_NUMBER
ERROR_MESSAGE
STORAGE_TOKEN_ID
PROCESSED_DATE
CUSTOMER_PROFILE_COUNTRY
CUSTOMER_PROFILE_CITY
CUSTOMER_PROFILE_POSTAL
EXPIRY_DATE
CUSTOMER_PROFILE_TRADE_NAME
CUSTOMER_PROFILE_LEGAL_NAME
CUSTOMER_PROFILE_PHONE_NUMBER
APPROVED

Batch

BATCH_SALE_AMOUNT=0
APPROVED=true
BATCH_NET_COUNT=0
BATCH_SALE_COUNT=0
BATCH_NET_AMOUNT=0
BATCH_RETURN_AMOUNT=0
BATCH_VOID_COUNT=0
BATCH_RETURN_COUNT=0
BATCH_VOID_AMOUNT=0
PROCESSED_DATE=130617
PROCESSED_TIME=132953
ERROR_MESSAGE=SUCCESS
ERROR_CODE=0

Successful Purchase

ORDER_ID=orderid
CVV2_RESPONSE_AVAILABLE=true
PROCESSED_TIME=133615
TRANSACTION_ID=692606
REFERENCE_NUMBER=992929991
TRACE_NUMBER=23492
CVV2_RESPONSE_CODE=M
CARD_BRAND=1
RESPONSE_HASH=ef5934ca4b6c352854c90e2747b1deff19732b54
AUTHORIZED_AMOUNT=1000
ERROR_CODE=0
STORAGE_TOKEN_EXPIRY=1231
DEBUG_MESSAGE=APPROVAL
ERROR_MESSAGE=SUCCESS
CARD_NUMBER=424242******4242
PROCESSED_DATE=130617
CVV2_RESPONSE_MESSAGE=CVV2 Match
APPROVAL_CODE=TS2343
APPROVED=true

Failed Purchase

DEBUG_MESSAGE=Card number is invalid
ERROR_CODE=200
APPROVED=false
ERROR_MESSAGE=C200_INVALID_CREDIT_CARD_NUMBER
PROCESSED_TIME=132946
PROCESSED_DATE=130617

Recurring Purchase Created

APPROVED=true
TRANSACTION_ID=692607
PERIODIC_TRANSACTION_ID=692607
AUTHORIZED_AMOUNT=1000
DEBUG_MESSAGE=Success
PERIODIC_TRANSACTION_STATE=1
ORDER_ID=orderid
TRACE_NUMBER=
PROCESSED_DATE=130617
PROCESSED_TIME=135911
ERROR_MESSAGE=SUCCESS
ERROR_CODE=0

Secure Storage

CUSTOMER_PROFILE_PROVINCE=
CUSTOMER_PROFILE_ADDRESS2=
CUSTOMER_PROFILE_ADDRESS1=address1
CUSTOMER_PROFILE_AVAILABLE=true
PROCESSED_TIME=140137
CUSTOMER_PROFILE_FIRST_NAME=firstName
ERROR_CODE=0
PAYMENT_PROFILE_AVAILABLE=true
DEBUG_MESSAGE=
CREDIT_CARD_AVAILABLE=true
CUSTOMER_PROFILE_LAST_NAME=lastName
CREDIT_CARD_NUMBER=424242******4242
ERROR_MESSAGE=SUCCESS
STORAGE_TOKEN_ID=yourtoken
PROCESSED_DATE=130617
CUSTOMER_PROFILE_COUNTRY=
CUSTOMER_PROFILE_CITY=
CUSTOMER_PROFILE_POSTAL=postal
EXPIRY_DATE=1231
CUSTOMER_PROFILE_TRADE_NAME=
CUSTOMER_PROFILE_LEGAL_NAME=
CUSTOMER_PROFILE_PHONE_NUMBER=phone
APPROVED=true