API Docs

Get Support

Contact us at 844-286-1300 op. 1,3 or [email protected] for any support you may need.

Overview

Our transaction API allows you to process card-not-present (CNP) transactions, which covers any system where card information is entered manually. The most obvious example is e-commerce websites, but really you can use it with any application that has access to the internet. The sections below detail how to process various transaction types. They will show the raw request and also give examples in common web programming languages.

Submitting a transaction requires you to send POST request over HTTPS with a JSON formatted payload.

The API endpoint used for both production and test transactions is https://checkout.payhub.com/transaction/api

We do offer a more advanced API that allows you to submit swiped transaction data. Please contact us if you require this option.

Getting Access Credentials

You can run API tests without credentials by setting the "mode" field to "demo". See the How to Test section for more details. All transactions shown below are test or "demo" mode transactions.

In order to get live processing credentials, you must have a processing account with PayHub. Please contact us to setup an account.

You must set the "mode" parameter to "live" in order for transactions to process through our production system.

Sale Transactions

Use a Sale transaction to charge a card. You will receive an authorization code on a successful sale. Once a sale transaciton is settled, the money will be taken from the cardholder's account and deposited to the merchant's account. This is the most common transaction type by far.

Here is a an example of a sale request payload in it's simplest form. Note that access credentials have been omitted for brevity. Go to the API Field Reference section for details on each available field.
{
  "mode" => "demo",
  "trans_type" => "sale",
  "cc" => "4012881888818888", 
  "month" => "06", 
  "year" => "2020", 
  "amount" => "29.95"
}

Address Verification System (AVS)

When processing a CNP transaction, you should include billing address information for the card being used. If the card issuing bank (CIB) supports AVS, then it will verify the billing address and billing zip code provided against the information for those fields. The CIB will return an AVS result and we will pass it through to your application.

Go to AVS response codes

{
  "mode" => "demo",
  "trans_type" => "sale",
  "cc" => "4012881888818888", 
  "month" => "06", 
  "year" => "2020", 
  "amount" => "29.95",
  "address1" => "123 Happy St.", 
  "city" => "Happy City", 
  "state" => "CA", 
  "zip" => "94901"
}

Card Verification Value (CVV)

The CVV is a three or four digit number printed on the credit card. It is meant to verify that the client has posession of the card when it is used for a CNP transaction. To illustrate, you may have noticed that you are almost always asked to enter the CVV when making a purchase on a website, but never when you actually swipe the card at a business. This is because the track data encoded on the card ensures to a high degree that the card is present.

CVV is known by many differenct abbreviations - CVV2, CVC2, CVC, CID are some common ones.

Go to CVV response codes

{
  "mode" => "demo", 
  "cc" => "4012881888818888", 
  "month" => "06", 
  "year" => "2020", 
  "cvv" => "999", 
  "amount" => "29.95",
}

Tracking Client Data

You can track client data (names, emails, phone number, etc.) by including it with a transaction request. Our system tracks client data in two ways:

  • Every transaction will include a snapshot of customer data provided when the transcation was run.
  • If you provide at least an email or phone number, then a Customer Profile is created with a unique client id, which is is returned with the transaction request; and the transaction will be associated with the Customer Profile.

Here is an example sale transaction payload that includes client data:
{
  "mode" => "demo",
  "trans_type" => "sale",
  "cc" => "4012881888818888", 
  "month" => "06", 
  "year" => "2020", 
  "amount" => "29.95",
  "first_name" => "Gerry", 
  "last_name" => "Mander", 
  "phone" => "1231231234", 
  "email" => "[email protected]"
}

Refund Transactions

A refund is the opposite of a sale, in that the money is transferred from the merchant's account to the cardholder's account. It does not require an authorization, and therefore you will not receive an authorization code when processing a refund. A refund must be settled before any money changes hands.

A refund may only be run on an existing sale that has already been settled. Here is an example refund payload.
{
  "mode" => "demo",
  "trans_type" => "refund",
  "trans_id" => 123
}
The "trans_id" is simply the transaction ID of the transaction that you want to refund. It will automatically be refunded for the full amount.

Void Transactions

A void transaction negates a sale BEFORE it is settled. This makes it so that no money actually changes hands from the original sale transaction.

Here is an example void payload.
{
  "mode" => "demo",
  "trans_type" => "void",
  "trans_id" => 123
}
The "trans_id" is simply the transaction ID of the transaction that you want to void. Generally, if the transaction was run the same day then you will want to process a void as opposed to a refund transaction.

Auth-only Transactions

An auth-only transaction is similar to a sale in that it requests an authorization on a card, but it differs in that it is not automatically settled. This type of transaction is most often used in rental situations where a merchant may want to hold an amount on a card, but not immediately charge it.

Here is an example auth-only payload.
{
  "mode" => "demo",
  "trans_type" => "auth",
  "cc" => "4012881888818888", 
  "month" => "06", 
  "year" => "2020", 
  "amount" => "29.95",
  "address1" => "123 Happy St.", 
  "city" => "Happy City", 
  "state" => "CA", 
  "zip" => "94901"
}


To "capture" an auth-only for settlement, use a capture transaction type.

Capture Transactions

A capture transaction updates an auth-only transaction so that it is automatically settled in the next settlement run.

Here is an example capture payload.
{
  "mode" => "demo",
  "trans_type" => "capture",
  "trans_id" => 123,
  "amount" => "10.00"
}
The "trans_id" is simply the transaction ID of the transaction that you want to capture. The amount may be any amount less than or equal to the original authorization amount.

You should not attempt to capture a transaction that was authorized more than 30 days in the past.

Recharging Cards

All successful transactions return a CARD_TOKEN_NO field, which contains a unique value that represents the card number used in the original transaction. If you store this token you can use it to recharge the card at a later time. The token is an arbitrary value that is not derived from the card number itself, so you can safely store it on your application's database without increasing your PCI scope.

To recharge an existing card, just provide the token instead of the card number in the transaction request. Here is an example Sale transaction payload using a token.
{
  "mode" => "demo",
  "trans_type" => "sale",
  "cc_token" => "9999000000001705", 
  "month" => "06", 
  "year" => "2020", 
  "amount" => "29.95",
  "first_name" => "Gerry", 
  "last_name" => "Mander", 
  "phone" => "1231231234", 
  "email" => "[email protected]"
}

You will need to also store the card expiration date in your application's database so that you can provide it with the transaction request. Also, it is against PCI regulations to store the CVV value, so if you want to include that in the transaction request then you will need to collect it from the user at the time the transaction is run.

Settlement

Settlement is necessary to finalize transactions so that they are deposited to your account. By default, all accounts are configured to automatically settle on a daily basis.

Handling API Responses

API responses are sent in JSON formatted payloads. Response payloads will always have a "RESULT" field. A result field of "00" ALWAYS indicates that the request was successful, regardless of request type. Anything besides "00" is an error of some kind.

Here is an example response to a Sales transaction request. Go to the API Field Reference section for details on each available field.
{
  "CARD_TOKEN_NO": "9999000000001033",
  "AVS_RESULT_CODE": "N",
  "TRANSACTION_ID": "479",
  "CUSTOMER_ID": "18",
  "VERIFICATION_RESULT_CODE": "M",
  "RESPONSE_CODE": "00",
  "RISK_STATUS_RESPONSE_CODE": "",
  "TRANSACTION_DATE_TIME": "2014-05-13 13:36:17",
  "RISK_STATUS_RESPONSE_TEXT": "",
  "APPROVAL_CODE": "TAS214",
  "BATCH_ID": "97",
  "RESPONSE_TEXT": "SUCCESS",
  "CIS_NOTE": ""
}

How to Test

To run test transactions, simply set the "mode" parameter to "demo" and all transactions will automatically be routed through our test system. When in demo mode, the "orgid", "username", "password", and "tid" fields are optional.

Use the following test data to run test transactions:
Test Data
Card Type Card # Card CVV Transaction Amount Expected Result
Visa 4012881888818888 999 10.00 Success
Visa 4266841082854082 999 0.01 Fail
MasterCard 5466410004374507 998 10.00 Success
MasterCard 5454545454545454 998 0.20 Fail
American Express 371449635398431 9997 10.00 Success
American Express 371449635398431 9997 0.20 Fail
Discover 6011000990156527 996 10.00 Success

The expiration date used can be any time in the future.

To test AVS, just provide any valid address or zip information with the request and you will get a successful AVS response. To test for a failed CVV code, use a different CVV than what is specified in the table above.

End-to-end Example (Demo mode)

Here is an end-to-end example on how to process a TEST Sale request in PHP:
<?php
# Tested with PHP 5.4.7 and cURL 7.27.0.
# Note: This requires PHP compiled with cURL support.
# See http://www.php.net/manual/en/book.curl.php for details.

$api_endpoint = "https://checkout.payhub.com/transaction/api"; 
$debug = true; #boolean

$sale_data = array("mode" => "demo",
                   "orgid" => "123456",
                   "username" => "api_username",
                   "password" => "api_password",
                   "tid" => "123",
                   "first_name" => "Gerry", 
                   "last_name" => "Mander", 
                   "phone" => "1231231234", 
                   "email" => "[email protected]", 
                   "address1" => "123 Happy St.", 
                   "city" => "Happy City", 
                   "state" => "CA", 
                   "zip" => "94901", 
                   "cc" => "4012881888818888", 
                   "month" => "06", 
                   "year" => "2020", 
                   "cvv" => "999", 
                   "note" => "This is a test sale transaction.", 
                   "invoice" => "1-X services", 
                   "amount" => "29.95");
       
$json_payload = json_encode($sale_data);

$ch = curl_init();

$c_opts = array(CURLOPT_URL => $api_endpoint,
                CURLOPT_VERBOSE => $debug,
                CURLOPT_SSL_VERIFYHOST => 0,
                CURLOPT_SSL_VERIFYPEER => true,
                CURLOPT_HTTPHEADER => array('Content-Type: application/json'),
                CURLOPT_RETURNTRANSFER => true,
                CURLOPT_POST => true,
                CURLOPT_POSTFIELDS => $json_payload);

curl_setopt_array($ch, $c_opts);

$result = curl_exec($ch);

curl_close($ch);

$result = json_decode($result);

if($debug) var_dump($result);

if($result->RESPONSE_CODE == "00")
{
    #Success
    echo "It worked.";
}
else
{
    #Fail
    echo "Transaction failed.  Error: {$result->RESPONSE_CODE}";
}
?>

API Field Reference

Request Parameters
Field Description Requirement Validation Examples
mode Use this field to differentiate between test and live transactions. Required Must be "demo" or "live". demo, live
orgid Your PayHub Organization ID. This is assigned to you when you setup an account with PayHub. Required 5-8 digits. 10002, 123456
username Your API username. This can be found in the Admin section in Virtual Hub. Required Alphanumeric. abc123DEF
password Your API password. This can be found in the Admin section in Virtual Hub. Required Alphanumeric. abc123DEF
tid Your API terminal ID. This can be found in the Admin section in Virtual Hub. Required 1-8 digits. 12, 3421, 456781
trans_type The transaction type to run. Defaults to "sale" if not provided.
  • A sale is the most common transaction. It puts an authorization on the card and will automatically settle within 24 hours.
  • A void will stop a sale from being settled. It must be run before the transaction is settled or it will not work.
  • An auth transaction will hold the amount on the card, but not settle it until it is "captured".
  • A "capture" transaction updates an auth transaction so that it is settled within 24 hours.
Optional "sale", "void", "auth", "capture". sale, void
cc The Credit Card number. Required if "cc_token" is not provided. 15-16 digits. 4012881888818888
cc_token A PayHub token that represents the card number. This key takes precedence over a credit card number, so if both the "cc" and "cc_token" parameters are provided, we will charge the card that is associated with the "cc_token".

See the Recharging Cards section for more details.
Required if "cc" is not provided. 16 digits. 9990000000123456
month The card expiration month. Required 2 digits. 01, 02, 11
year The card expiration year. Required 4 digits. 2014, 2020
cvv The 3 or 4 digit security code of the card. Not Required 4 digits for Amex cards. 3 digits for all other card types. 123, 4321
amount The total amount to process. Required Must be a valid currency format. 10, 10.00
first_name The customer's first name. Not Required Maximum 30 characters. Invalid characters are automatically stripped. Joe
last_name The customer's last name. Not Required Maximum 30 characters. Invalid characters are automatically stripped. Shmoe
phone The customer's phone number. Not Required 10 digits. Non-numberic characters are automatically stripped. 1231231234
email The customer's email address. Not Required Must be a valid email format. Maximum 79 characters. [email protected]
address1 The billing street address of the card. Not Required Maximum 30 characters. Invalid characters are automatically stripped. 2350 Kerner Blvd
address2 Use this for Suite, Apt., etc part of the billing address. Not Required Maximum 30 characters. Invalid characters are automatically stripped. Ste. 380
city The billing address city. Not Required Maximum 30 characters. Invalid characters are automatically stripped. San Rafael
state The billing state. Can be "CA" or "California". Not Required Currently only supports US states. Must be the standard abbreviation or full state name. CA, California
zip The 5-digit billing zip code. Not Required 5 digits. 94901
ship_to_name The name of the persont to ship to. Not Required Maximum 30 characters. Invalid characters are automatically stripped. Joe Shmoe
ship_address1 The shipping street address. Not Required Maximum 30 characters. Invalid characters are automatically stripped. 2350 Kerner Blvd
ship_address2 Use this for Suite, Apt., etc part of the shipping address. Not Required Maximum 30 characters. Invalid characters are automatically stripped. Ste 380
ship_city The shipping address city. Maximum 30 characters. Invalid characters are automatically stripped. Not Required San Rafael
ship_state The shipping address state. Can be "CA" or "California". Not Required Currently only supports US states. Must be the standard abbreviation or full state name. CA, California
ship_zip The shipping zip code. Not Required 5 digits. 94901
note Arbitrary notes that will be added to the transaction in Virtual Hub. Not Required Maximum 200 characters. Invalid characters are automatically stripped. This is a test note.
invoice An optional invoice field. Not Required Maximum 30 characters. abc-123

Response Parameters
Field Description Examples
RESPONSE_CODE A numeric code that is 2 or 4 digits long. It indicates whether or not the transaction was successful. A "00" code means that the transaction was successful, any other code means the transaction failed. See the Response Codes section below. 00, 51, 4006
RESPONSE_TEXT A short message describing the response code. SUCCESS, DECLINE, INVALID ORG ID
TRANSACTION_ID A numeric ID generated by PayHub that uniquely identifies the transaction. 12423, 53245, 413245
AVS_RESULT_CODE A single character code that indicates the result of the billing address check. See the AVS Response Codes table below. M, Y, 1
VERIFICATION_RESULT_CODE A single character code that indicates the result of the CVV check. See the CVV Response Codes table below. M, N
APPROVAL_CODE A 6 character (alphanumeric) code that will be populated in the case of a successful transaction. abc123, TAS142
TRANSACTION_DATE_TIME The timestamp of the transaction in YYYY-MM-DD HH:MM:SS format. The time is in 24-hour format. It's always in PST (Pacific) time. 2014-06-12 14:04:17
BATCH_ID A numeric id that uniquely identifies the batch on PayHub's system that the transaction belongs to. 123123, 34565
CUSTOMER_ID A numeric id that uniqhely identifies the customer on PayHub's sytem. This will only be populated if a customer profile exists for the card that was submitted. Note: You can automatically create a customer profile on the PayHub system by providing a customer email or phone number in the request. 12, 5124
CIS_NOTE This field is only populated if there was a problem creating a customer profile. It will never affect that actual approval or decline of the transaction itself. FAILED TO CREATE CUSTOMER PROFILE
CARD_TOKEN_NO A unique token that represents the card number. This can be stored in your application's database and used at a later time to recharge cards. 9999000000001705, 9999000000018273
RISK_STATUS_RESPONSE_CODE Not currently applicable to API calls, but is present for future implementation. n/a
RISK_STATUS_RESPONSE_TEXT Not currently applicable to API calls, but is present for future implementation. n/a

Response Codes

Issuer (Bank) Response Codes
Response Code Response Text Description
00 Approval Successful - Approved and completed
01 Call Failed - Refer to issuer
02 Call Failed - Refer to issuer-Special condition
03 Term ID Error No Merchant Failed - Invalid Merchant ID
04 Hold-call or Pick Up Card Failed - Pick up card (no fraud)
05 Decline Failed - Do not honor
06 Error XXXX Failed - General error
06* (Check Service Custom Text) Failed - Error response text from check service
07 Hold-call or Pick Up Card Failed - Pick up card, special condition (fraud account)
08 Approval Successful - Honor MasterCard with ID
10 Partial Approval Failed - PayHub does not support partial approvals.
11 Approval Successful - VIP approval
12 Invalid Trans Failed - Invalid transaction
13 Amount Error Failed - Invalid amount
14 Card No. Error Failed - Invalid card number
15 No such Issuer Failed - No such issuer
19 RE Enter Failed - Re-enter transaction
21 No Action Taken Failed - Unable to back out transaction
28 No Reply Failed - File is temporarily unavailable
34 Transaction Cancelled Failed - MasterCard use only, Transaction Cancelled; Fraud Concern (Used in reversal requests only)
39 No Credit Acct Failed - No credit account
41 Hold-call or Pick Up Card Failed - Lost card, pick up (fraud account)
43 Hold-call or Pick Up Card Failed - Stolen card, pick up (fraud account)
51 Decline Failed - Insufficient funds
52 No Check Account Failed - No checking account
53 No Save Account Failed - No savings account
54 Expired Card Failed - Expired card
55 Wrong PIN Failed - Incorrect PIN
57 Serv not allowed Failed - Transaction not permitted-Card
58 Serv not allowed Failed - Transaction not permitted-Terminal
59 Serv not allowed Failed - Transaction not permitted-Merchant
61 Declined Failed - Exceeds withdrawal limit
62 Declined Failed - Invalid service code, restricted
63 Sec Violation Failed - Security violation
65 Declined Failed - Activity limit exceeded
75 PIN Exceeded Failed - PIN tried exceeded
76 Unsolicated Reversal Failed - Unable to locate, no match
77 No Action Taken Failed - Inconsistent data, reversed, or repeat
78 No Account Failed - No account
79 Already Reversed Failed - Already reversed at switch
80 Date Error Failed - Invalid date
81 Encryption Error Failed - Cryptographic error
82 Incorrect CVV Failed - CVV data is not correct
83 Cannot Verify PIN Failed - Cannot verify PIN
85 Card OK Successful - No reason to decline
86 Cannot Verify PIN Failed - Cannot verify PIN
91 No Reply Failed - Issuer or switch is unavailable
92 Invalid Routing Failed - Destination not found
93 Decline Failed - Violation, cannot complete
94 Duplicate Trans Failed - Unable to locate, no match
96 System Error Failed - System malfunction

Processor Response Codes
Response Code Response Text Description
A1 Activated POS device authentication successful
A2 Not Activated POS device authentication not successful
A3 Deactivated POS device deactivation successful
B1 SRCHG Not Allowed Surcharge amount not permitted on Visa cards or EBT food stamps
B2 SRCHG Not Allowed Surcharge amount not supported
CV Failure CV network issuer
E1 ENCR NOT CONFIGD Card Type Verification Error
E2 TERM NOT AUTHENT Encryption is not configured
E3 DECRYPT FAILURE Terminal is not authenticated
EA Acct Length Err Data could not be decrypted
EB Check Digit Err Verification error
EC CID Format Error Verification error
HV Failure HV Verification error
KO TOKEN RESPONSE Hierarchy Verification Error
N3 Cashback Not Avl Failed - Cash back service not available
N4 Decline Exceeds issuer withdrawal limit
N7 CCV2 Mismatch CVV2 Value supplied is invalid
R0 Stop recurring Customer requested stop of specific
R1 Stop recurring recurring payment
T0 Approval Customer requested stop of all recurring
T1 Cannot Convert payments from specific merchant
T2 Invalid ABA First check is OK and has been converted
T3 Amount Error Check is OK but cannot be converted
T4 Unpaid Items This is a declined transaction
T5 Duplicate Number Invalid ABA number, not an ACH
T6 MICR Error participant
T7 Too Many Checks Amount greater than the limit
V1 Failure VM Unpaid items, failed negative file check
RB Rejected Batch Batch Capturing Failed
QD Duplicate Batch Batch Capturing Failed due to Duplicate Batch ID submitted

AVS Response Codes
AVS Code Description
"" (empty string) Not Requested
0 Approved, Address verification was not requested.
A Approved, Address matches only.
B Address Match. Street Address match for international transaction Postal Code not verified because of incompatible formats (Acquirer sent both street address and Postal Code)
C Serv Unavailable. Street address and Postal Code not verified for international transaction because of incompatible formats (Acquirer sent both street and Postal Code).
D Exact Match, Street Address and Postal Code match for international transaction.
F Exact Match, Street Address and Postal Code match. Applies to UK only.
G Ver Unavailable, Non-U.S. Issuer does not participate.
I Ver Unavailable, Address information not verified for international transaction
M Exact Match, Street Address and Postal Code match for international transaction
N No - Address and ZIP Code does not match
P Zip Match, Postal Codes match for international transaction Street address not verified because of incompatible formats (Acquirer sent both street address and Postal Code).
R Retry - Issuer system unavailable
S Serv Unavailable, Service not supported
U Ver Unavailable, Address unavailable.
W ZIP match - Nine character numeric ZIP match only.
X Exact match, Address and nine-character ZIP match.
Y Exact Match, Address and five character ZIP match.
Z Zip Match, Five character numeric ZIP match only.
1 Cardholder name and ZIP match AMEX only.
2 Cardholder name, address, and ZIP match AMEX only.
3 Cardholder name and address match AMEX only.
4 Cardholder name match AMEX only.
5 Cardholder name incorrect, ZIP match AMEX only.
6 Cardholder name incorrect, address and ZIP match AMEX only.
7 Cardholder name incorrect, address match AMEX only.
8 Cardholder, all do not match AMEX only.

CVV Response Codes
CVV Code Description
M Match
N No Match
P Not Processed
S Merchant has indicated that Verification Code is not present on card.
U Issuer is not certified and/or has not provided Visa encryption keys.