PayHub Gateway
Authentication
Introduction
The purpose of this document is to provide you with information on how you can get started using PayHub RESTful Web Services to access certain resources associated with a Merchant’s PayHUb account. PayHub’s RESTfulWeb Services allow you and your applications to act on a Merchant’s behalf to do useful things like:
- Create a Sale transaction (POST a sale resource).
- Create a Void transaction (POST a void resource).
- Create a Refund transaction (POST a refund resource).
- Create a Recurring Bill (POST a recurring-bill resource).
- Update the status of a Recurring Bill, (PATCH the recurring-bill-status property of a RecurringBill resource).
- Retrieve the schedule(s) you used to create a Recurring Bill (GET one or more schedule resources).
- Retrieve your Merchants’ Customer information (GET one or more customer resources), for those Customers that you have historically created through using the service when you posted a Sale or a Recurring Bill.
- Retrieve information about the Merchants whose resources you have historically managed (GET one or more merchant resources).
- Retrieve your Merchants’ tokenized Card Data (GET one or more carddata resources), for the Sales or a Recurring Bills you have historically created.
- Retrieve the bill-related data, such as transaction amount, (GET one or more bill resources), for the Sales or a Recurring Bills you have historically created.
- Attach your own arbitrary JSON data to most of the resources you have created (PUT metadata ‘forResource’)
- Perform certain specialized search queries on the resources you have created.
- Supply parameters to control paging and sorting (ascending or descending on a top level property) on GETs that return multiple resources.
- Query the endpoint we provide and use the hypermedia-linked feature to discover resources from within your client application.
- Obtain, store, and use PayHub’s unique numeric identifiers for certain resources such as Customer Id and Recurring Bill Id.
How we Use OAuth 2.0 to Assure Security
Oauth 2.0 is an industry-standard, and widely accepted, authentication and authorization mechanism for providing third party applications and clients secure access to a user’s resources hosted service providers.
Typically, the third party (or client) is granted access to a user’s resources hosted by a service provider, using a unique token generated by the service provider at the time the user authorizes the client access to their resources. Think of the situation where you authorize a web site to register you using your identity hosted on Facebook (you click the 'log in with Facebook’ button on the web site and authorize the site to access your information on Facebook).
The PayHub RESTful Web Services currently uses OAuth 2.0 with:
- You as the Client
- Merchants as the Users (who has an account at PayHub)
- And PayHub as the Service Provider
You can think of the OAuth 2.0 token as linking the Client to the Merchant via the PayHub Service.
As a new third party integrator, you will be assigned a unique 'Client Id’ that you will use when requesting access to a Merchant’s resources.
We are current working on a way for you to automatically obtain an OAuth 2.0 Token for a Merchant without the need for the Merchant or PayHub Support to first visit the PayHub Virtual Terminal to generate the token for your Client Id.
Once you have your token, it is very important that you treat this as you would a user and password: never reveal it to anyone other than authorized developers, and never reference it in publicly available source code such as publicly exposed JavaScript or HTML pages.
Using Your OAuth 2.0 Token in calls to PayHub RESTful Web Services
Once you have the token, you can use it to authenticate your application to the PayHub RESTful Web Service by using the OAuth 2.0 standard HTTP Authorization Header structured as in this example:
Header Field Name: Authorization
Header Value: Bearer [your-token-here]
It is important to note that, although this token authorizes you to invoke the PayHub Restful Web Services on behalf of a particular Merchant:
- You will also need to know the Merchant’s unique Organization Id and 3rd Party Terminal Id when you POST a Recurring Bill and a Sale. You should have been supplied with this information when you received the token.
- You can use any of your valid OAuth 2.0 Tokens when performing GETs to your Merchants’ PayHub resources. A GET will retrieve all resources of the requested type (for example Customer) regardless of Merchant. You can filter by Merchant by using the supplied findByMerchantOrganizationId search functions.  
Sale Transaction
package transactions;
import java.io.IOException;
import java.io.InputStream;
import java.io.UnsupportedEncodingException;
import java.net.URL;
import org.apache.http.Header;
import org.apache.http.HttpResponse;
import org.apache.http.client.ClientProtocolException;
import org.apache.http.client.HttpClient;
import org.apache.http.client.methods.HttpPost;
import org.apache.http.entity.StringEntity;
import org.apache.http.impl.client.DefaultHttpClient;
import org.apache.http.params.HttpConnectionParams;
import org.apache.http.params.HttpParams;
import org.json.JSONException;
import org.json.JSONObject;
public class Sale {
public static void RunSale() {
try {
HttpClient client = new DefaultHttpClient();
HttpParams params = client.getParams();
HttpConnectionParams.setConnectionTimeout(params, 10000);
JSONObject jsonRequestObject = new JSONObject();
String url = "https://api.payhub.com/api/v2/sale";
JSONObject merchant = new JSONObject();
merchant.put("organization_id", "10005");//You put your org id here
merchant.put("terminal_id", "5");//You put your terminal id
jsonRequestObject.put("merchant", merchant);
JSONObject bill = new JSONObject();
JSONObject base_amount = new JSONObject();
base_amount.put("amount", "1275");//$12.75
bill.put("base_amount", base_amount);
JSONObject shipping_amount = new JSONObject();
shipping_amount.put("amount", "725");//$7.25
bill.put("shipping_amount", shipping_amount);
JSONObject tax_amount = new JSONObject();
tax_amount.put("amount", "113");//$1.13
bill.put("tax_amount", tax_amount);
bill.put("note", "Shipped as a gift");
bill.put("invoice_number", "4645782");
bill.put("po_number", "1234-654321");
jsonRequestObject.put("bill", bill);
JSONObject card_data = new JSONObject();
card_data.put("card_number", "5466410004374507");
card_data.put("card_expiry_date", "201809");// September 2018
card_data.put("billing_address_1", "237 E 33rd Street");
card_data.put("billing_address_2", "3rd Floor");
card_data.put("billing_city", "New York");
card_data.put("billing_zip", "10016");
card_data.put("billing_state", "NY");
card_data.put("cvv_data", "998");
card_data.put("cvv_code", "Y");
jsonRequestObject.put("card_data", card_data);
JSONObject customer = new JSONObject();
customer.put("first_name", "John");
customer.put("last_name", "Smith");
customer.put("company_name", "CBA Steakhouse");
customer.put("job_title", "Owner");
customer.put("email_address", "john@cbasteakhouse.com");
customer.put("web_address", "http://www.cbasteakhouse.com");
customer.put("phone_number", "(917) 479 1349");
customer.put("phone_ext", "5478");
customer.put("phone_type", "M");
jsonRequestObject.put("customer", customer);
jsonRequestObject.put("record_format", "CC");
HttpPost postCreate = new HttpPost(url);
postCreate.addHeader("Authorization", "Bearer dfd4f12a-79af-4825-8dba-db27342c8491");//You put your token here
postCreate.addHeader("Content-Type", "application/json");
postCreate.addHeader("Accept", "application/json");
StringEntity se = new StringEntity(jsonRequestObject.toString());
postCreate.setEntity(se);
HttpResponse response = client.execute(postCreate); //You return this response and work with it
String json = " ";
JSONObject jsonResponseObject = null;
InputStream in = response.getEntity().getContent();
int cnt = 0;
while ((cnt = in.read()) > -1) {
json += (char) cnt;
}
if (json.charAt(0) != '<') {
jsonResponseObject = new JSONObject(
(json.equalsIgnoreCase("")
|| json.equalsIgnoreCase(" ") ? "{\"MESSAGE\":\"NO RESPONSE...\"}"
: json));
}
String result = response.getStatusLine().getReasonPhrase();
System.out.println(result);
if (result.equals("Created")){
Header[] headers = response.getAllHeaders();
for (Header header : headers) {
if (header.getName().equals("Location")){
URL location = new URL(header.getValue());
String path = location.getPath();
int lastSlash = path.lastIndexOf("/");
String transactionId = path.substring(lastSlash+1);
System.out.println("Transaction Id: " + transactionId ); //Last resource of the path
}
}
}
else{
System.out.println(jsonResponseObject.toString());
}
} catch (JSONException e){
System.out.println(e.getMessage());
} catch (UnsupportedEncodingException e) {
System.out.println(e.getMessage());
} catch (ClientProtocolException e) {
System.out.println(e.getMessage());
} catch (IOException e) {
System.out.println(e.getMessage());
}
}
}
<?php
$trans_type = "sale";
$processed = FALSE;
$ERROR_MESSAGE = '';
//Defining the Web Service URL
$WsURL="https://api.payhub.com/api/v2/$trans_type";
//Defining data for the SALE transaction
// Merchant data (obtained from the payHub Virtual Terminal (3rd party integration)
$organization_id = 10002;
$terminal_id = 2;
$oauth_token = "22fe3c69-db70-4a8c-9aed-9a33ebb1e9b4";
// bill data
$base_amount = 10.0;
$shipping_amount = 1.23;
$tax_amount = 1.00;
$note = "this a sample note";
$invoice_number = "a-00240";
$po_number = "56";
//Credit card data
$card_number = "5466410004374507";
$card_expiry_date = "202011";
$cvv_data = "998";
$billing_address_1 = "2350 Kerner Blvd";
$billing_address_2 = "On the corner";
$billing_city = "San Rafael";
$billing_state = "CA";
$billing_zip = "94901";
// Customer data
$first_name = "First";
$last_name = "Contact";
$company_name = "Payhub Inc";
$job_title = "Software Engineer";
$email_address = "jhon@company.com";
$web_address = "http://payhub.com";
$phone_number = "(415) 479 1349";
$phone_ext = "123";
$phone_type = "M";
//Convert data to array to send it to the WS as JSON format
$data = array();
$data["merchant"] = array("organization_id" => "$organization_id", "terminal_id" => "$terminal_id");
$data["bill"] = array ("base_amount" => array ("currency" => "USD","amount" => $base_amount),
"shipping_amount" => array ("currency" => "USD","amount" => $shipping_amount),
"tax_amount" => array ("currency" => "USD","amount" => $tax_amount));
$data["card_data"] = array("card_number" => "$card_number","card_expiry_date" => "$card_expiry_date",
"cvv_data" => "$cvv_data","billing_address_1" => "$billing_address_1",
"billing_address_2" => "$billing_address_2","billing_city" => "$billing_city",
"billing_state" => "$billing_state","billing_zip" => "$billing_zip");
$data ["customer"]= array("first_name" => "$first_name","last_name" => "$last_name","company_name" => "$company_name",
"job_title" => "$job_title","email_address" => "$email_address","web_address" => "$web_address",
"phone_number" => "$phone_number","phone_ext" => "$phone_ext","phone_type" => "$phone_type");
//Convert data from Array to JSON
$data_string = json_encode($data);
//Creating a CURL object to access the WS
$ch = curl_init();
//Setting the address to connect to
curl_setopt($ch, CURLOPT_URL, $WsURL);
//Setting HTTP method. For a new transaction we need to use POST
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
//Setting data in JSON format
curl_setopt($ch, CURLOPT_POSTFIELDS, $data_string);
//Setting the proper header.
//Setting the oauth_token to access the WS with the proper authorization
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
'Content-Type: application/json',
'Accept: application/json',
'Authorization: Bearer '.$oauth_token)
);
//Store the response as a variable and not showing the content as echo $variable
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
//Set to return the response header, this is to analyze the result and the transaction ID
curl_setopt($ch, CURLOPT_HEADER, true);
//execute connection to the Web Service
$response = curl_exec($ch);
// get some data from the response
$httpcode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
$header_size = curl_getinfo($ch, CURLINFO_HEADER_SIZE);
//Get the header as string.
$header = substr($response, 0, $header_size);
//close connection to the Web Service
curl_close($ch);
//Obtain the data from the sale recently created
if ($httpcode==201){
//find the url of the sale (Location header in the response)
preg_match("!\r\n(?:Location): *(.*?) *\r\n!", $header, $matches);
//$url contains the URL to GET the data from the Web Service
$url = $matches[1];
//Once we get the transaction ID we will query for the information of the last transaction
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
//Setting HTTP method. To get a transaction response we need to use GET
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "GET");
//Setting the proper header.
//Setting the oauth_token to access the WS with the proper authorization
curl_setopt($ch, CURLOPT_HTTPHEADER, array('Authorization: Bearer '.$oauth_token));
//Store the response as a variable and not showing the content as echo $variable
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
//execute connection to the Web Service
$response_json=curl_exec($ch);
//close connection to the Web Service
curl_close($ch);
//show result (standard JSON), parse it, process it, etc..
echo $response_json;
// now you could parse the json object to array if you preffer: $obj = json_decode($response_json);
$array = json_decode($response_json);
echo "<pre>";
print_r($array);
echo "</pre>";
}
//There was an error with the WS
else{
echo "Error creating the ".strtoupper($trans_type).": RESPONSE MESSAGE";
echo "<pre>";
echo $response;
echo "</pre>";
}
?>
using Newtonsoft.Json;
using System;
using System.IO;
using System.Net;
namespace PayHubSamples
{
public class Sale
{
public static void RunSale()
{
try
{
var request = (HttpWebRequest)WebRequest.Create("https://api.payhub.com/api/v2/sale");
request.ContentType = "text/json";
request.Method = "POST";
var sale = new
{
merchant = new
{
organization_id = "10005",
terminal_id = "5",
},
bill = new
{
base_amount = new
{
amount = "1275" //$12.75
},
shipping_amount = new
{
amount = "725" //$7.25
},
tax_amount = new
{
amount = "113" //$1.13
},
note = "Shipped as a gift",
invoice_number = "4645782",
po_number = "1234-654321"
},
card_data = new
{
card_number = "5466410004374507",
card_expiry_date = "201809", //September 2018
billing_address_1 = "237 E 33rd Street",
billing_address_2 = "3rd Floor",
billing_city = "New York",
billing_state = "NY",
billing_zip = "10016",
cvv_data = "998",
cvv_code = "Y"
},
customer = new
{
first_name = "John",
last_name = "Smith",
company_name = "CBA Stakehouse",
job_title = "Owner",
email_address = "john@cbastakehouse.com",
web_address = "http://www.cbasteakhouse.com",
phone_number = "(917) 479 1349",
phone_ext = "5478",
phone_type = "M"
},
record_format = "CC"
};
string json = JsonConvert.SerializeObject(sale);
request.Headers.Add("Authorization", "Bearer dfd4f12a-79af-4825-8dba-db27342c8491");
request.ContentType = "application/json";
request.Accept = "application/json";
using (var streamWriter = new StreamWriter(request.GetRequestStream()))
{
streamWriter.Write(json);
streamWriter.Flush();
streamWriter.Close();
}
try
{
var response = (HttpWebResponse)request.GetResponse();//You return this response.
using (var reader = new StreamReader(response.GetResponseStream()))
{
string result = reader.ReadToEnd();
Console.WriteLine(response.StatusCode);//Created
for (int i = 0; i < response.Headers.Count; ++i)
{
if (response.Headers.Keys[i] == "Location")
{
string path = response.Headers[i];
int lastSlash = path.LastIndexOf("/");
string transactionId = path.Substring(lastSlash + 1);
Console.WriteLine("Transaction Id: " + transactionId);
}
}
}
}
catch (WebException wex)
{
if (wex.Response != null)
{
using (var errorResponse = (HttpWebResponse)wex.Response)//You return wex.Response instead
{
using (var reader = new StreamReader(errorResponse.GetResponseStream()))
{
string result = reader.ReadToEnd();
Console.WriteLine(result);
}
}
}
}
}
catch (IOException e)
{
Console.WriteLine(e);
}
}
}
}
require 'uri'
require 'net/http'
require 'json'
url = URI("https://api.payhub.com/api/v2/sale")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Post.new(url)
request["content-type"] = 'application/json'
request["accept"] = 'application/json'
request["authorization"] = 'Bearer 2a5d6a73-d294-4fba-bfba-957a4948d4a3'
request["cache-control"] = 'no-cache'
merchant = {
"organization_id"=>10074,
"terminal_id"=>134
}
# bill data
bill= {
"base_amount"=>Hash["amount" =>"1.00"],
"shipping_amount"=>Hash["amount" =>"1.00"],
"tax_amount"=>Hash["amount" =>"1.00"],
"note"=>"this a sample note",
"invoice_number"=>"this is an invoice",
"po_number"=>"a test po number"
}
#Credit card data
card_data = {
"card_number"=>"4055011111111111",
"card_expiry_date"=>"202012",
"cvv_data"=>"999",
"billing_address_1"=>"2350 Kerner Blvd",
"billing_address_2"=>"On the corner",
"billing_city"=>"San Rafael",
"billing_state"=>"CA",
"billing_zip"=>"99997-0003"
}
# Customer data
customer = {"first_name"=>"First",
"last_name"=>"Contact",
"company_name"=>"Payhub Inc",
"job_title"=>"Software Engineer",
"email_address"=>"jhon@company.com",
"web_address"=>"http://payhub.com",
"phone_number"=>"(415) 479 1349",
"phone_ext"=>"123",
"phone_type"=>"M"
}
informationToSend = {"merchant"=>merchant,"bill"=>bill,"customer"=>customer,"card_data"=>card_data}
request.body = JSON.generate(informationToSend)
response = http.request(request)
puts response.read_body
{
"merchant": {
"organization_id": 10002,
"terminal_id": 2
},
"bill": {
"base_amount": {
"amount": 10.0
},
"shipping_amount": {
"amount": 1.23
},
"tax_amount": {
"amount": 1.00
},
"note": "This is a note.",
"invoice_number": "328",
"po_number": "sample po number"
},
"card_data": {
"card_number": "5466410004374507",
"card_expiry_date": "202011",
"billing_address_1": "2350 Kerner Blvd",
"billing_address_2": "2 floor",
"billing_city": "San Rafael",
"billing_state": "CA",
"billing_zip": "94901",
"cvv_data": "998"
},
"customer": {
"first_name": "Miguel",
"last_name": "Smith",
"company_name": "Payhub Inc",
"job_title": "Software Engineer",
"email_address": "msmith14567@payhub.com",
"web_address": "http://payhub.com",
"phone_number": "(415) 479 1349",
"phone_ext": "123",
"phone_type": "M"
}
}
Introduction
This topic provides the information about the Sale transaction. Use a Sale transaction to charge a credit card.
Upon successful sale, you will receive an approval code. Once a sale transaction is settled, the money will be taken from the card holder’s account and deposited to the merchant’s account. This is the most common transaction type.
Request Method
POST
Endpoint (URL to Call)
POST https://api.payhub.com/api/v2/sale
Elements
merchant
| Key | Type | Value |
|---|---|---|
| organization_id | integer | The Organization Id of the Merchant. This must match the Organization Id of the Merchant that the passed Oauth Token is associated with. |
| terminal_id | integer | The Merchant’s Virtual Terminal Id for 3rd Party API. |
| record_format | string, optional | To specify if the sale has to be made over a credit card, debit card or cash payment. If it´s not present, default value “CREDIT_CARD” is assumed. Accepted values are:
|
customer
| Key | Type | Value |
|---|---|---|
| first_name | string | The first name of the customer. |
| last_name | string | The last name of the customer. |
| company_name | string, optional | The company name of the customer. |
| job_title | string, optional | The job title of the customer. |
| email_address | string, optional | The valid email address of the customer. The email address must be syntactically correct. If you do not specify the email address, you must provide a phone_number to identify the customer. |
| web_address | string, optional | The web address of the customer. The web address, if you specify, must be syntactically valid web address. |
| phone_number | string, optional | The phone number of the customer. The phone number must be syntactically correct. For example, (415) 234 5678, or 4152345678, or (415) 234-5678. If you do not specify the phone number, you must provide an email_address to identify the customer. |
| phone_ext | string, optional | The phone extension number of the customer. |
| phone_type | string, optional | The type ([‘H’ or 'W’ or ’M’]) of the phone number: H (Home), W (Work), M (Mobile). |
card_data
| Key | Type | Value |
|---|---|---|
| tokenized_card | string, optional | This is the 16 character PayHub-specific tokenized string representing the card number. The value for the given customer and credit card can be obtained by examining the last Sale by accessing the link to the card data that was successfully created. It is safer (and recommended) for the third party client to store and use this string in any future requests for the same customer. |
| card_number | string, optional | This is the 16 character card number. The card number is not stored by the API in plain text. The response will contain a tokenized card number that should always be used in future requests, (for the same Customer) in place of this property. |
| track1_data | string, optional | This is the string read by the swiper (It contents track 1 data without sentinels). |
| track2_data | string, optional | This is the string read by the swiper (It contents track 2 data without sentinels). |
| encrypted_track _data | Optional |
|
| billing_address_1 | string, optional | The billing street address of the customer. |
| billing_address_2 | string, optional | The additional billing street address of the customer. |
| billing_city | string, optional | The billing city of the customer. |
| billing_state | string, optional | The billing state Code of the customer. For example, CA, WI, NY, etc. The sate codes should be for the states in the USA. |
| billing_zip | string, optional | The billing Zip Code of the customer. The zip code must be either 5 digits or 5 plus four separated by a ’-’. The zip code is required if the merchant has turned ON the AVS flag. |
| card_expiry_date | string | The card expiry date in the YYYYMM format. |
| cvv_data | string | This is the three or four digit CVV code at the back side of the credit and debit card. |
bill
| Key | Type | Value |
|---|---|---|
| base_amount | TransactionAmount | The base amount of the recurring bill. The total amount charged will be the sum of this amount and (any) 'shipping_amount’ and 'tax_amount’. |
| shipping_amount | TransactionAmount, optional | The shipping amount for the transaction. This value will be included in the total amount charged. |
| tax_amount | TransactionAmount, optional | The tax amount for the transaction. This value will be included in the total amount charged. |
| invoice_number | string, optional | The invoice number for the transaction. |
| po_number | string, optional | The purchase order number for the transaction. |
| note | string, optional | A free format note for the transaction. The note will be read by the merchant. |
Note: One of the following fields must be present:
- tokenized_card
- card_number
- track1_data
- track2_data
- encrypted_track_data
{
"version": 0,
"createdAt": "2015-05-19T12:58:09.863-03:00",
"lastModified": "2015-05-19T12:58:09.863-03:00",
"createdBy": "10002",
"lastModifiedBy": "10002",
"metaData": null,
"record_format": null,
"settlementStatus": "Not settled",
"saleResponse": {
"saleId": "478",
"approvalCode": "VTLMC1",
"processedDateTime": null,
"avsResultCode": "N",
"verificationResultCode": "M",
"batchId": "38",
"responseCode": "00",
"responseText": "",
"cisNote": "",
"riskStatusResponseText": "",
"riskStatusRespondeCode": "",
"saleDateTime": "2015-05-19 12:58:09",
"tokenizedCard": null,
"customerReference": {
"customerId": 1,
"customerEmail": "msmith14567@payhub.com",
"customerPhones": []
},
"billingReferences": {
"cardObscured": null,
"tokenizedCard": "9999000000001804",
"customerId": 1,
"customerCardId": null,
"customerBillId": 1
}
},
"_links": {
"self": {
"href": "https://payhub.com/api/v2/sale/478"
},
"merchant": {
"href": "https://payhub.com/api/v2/sale/478/merchant"
},
"customer": {
"href": "https://payhub.com/api/v2/sale/478/customer"
},
"card_data": {
"href": "https://payhub.com/api/v2/sale/478/card_data"
},
"bill": {
"href": "https://payhub.com/api/v2/sale/478/bill"
}
}
}
Result
- A 201 code (created)
- The Id of the Sale will be provided in the Location header that is returned. This is referred as the Transaction Id.
Sample header in the response:Location → https:// [payhub-api-server]:8251/payhubws/api/sale/5501b651da06a879ce520d4d.
If you do a GET request to this URL, you will get all the transaction information in JSON format.
On the same way you can query about merchant, customer, bill and card data details using the given URLs.
Note: You will need to use Oauth token in the header request for sales or any other transaction. For more information, see the
OAuth 2.0 Access Tokens section.
Extended Methods
Request Method
GET
Endpoints (URLs to Call)
GET https://api.payhub.com/api/v2/sale/{id}
Use the sale Id in order to get the information of the sale response.
GET https://api.payhub.com/api/v2/sale/{id}/merchant
Use the sale Id in order to get the merchant information of the sale response.
GET https://api.payhub.com/api/v2/sale/{id}/customer
Use the sale Id in order to get the customer information of the sale response.
GET https://api.payhub.com/api/v2/sale/{id}/bill
Use the sale Id in order to get the bill information of the sale response.
GET https://api.payhub.com/api/v2/sale/{id}/card_data
Use the sale Id in order to get the card data of the sale response. (The information on this method is reduced by security policies)
GET https://api.payhub.com/api/v2/sale/
If the ID is not present, you will get a list with all the transactions.
By default, the list return only the first 20 resutls and it can be paged, you can modify this by adding the next parameters to the url:
page={pageNo}&size={size}
SDKs Methods
Each SDK has a transaction manager class with the next methods:
- Create a transaction: doSale
- Get transaction information based on the transaction ID: getSaleInformation({transactionId})
- Get all the transactions performed under this method: getAllSalesInformation (optional parameters for page and size)
The first two methods returns a SaleResponseInformation object, the third method returns a list of SaleResponseInformation objects.
Each SaleResponseInformation has the next methods:
- getMerchantInformation()
- getBillInformation()
- getCardDataInformation()
- getCustomerInformation()
Verify Transaction
package transactions;
import java.io.IOException;
import java.io.InputStream;
import java.io.UnsupportedEncodingException;
import java.net.URL;
import org.apache.http.Header;
import org.apache.http.HttpResponse;
import org.apache.http.client.ClientProtocolException;
import org.apache.http.client.HttpClient;
import org.apache.http.client.methods.HttpPost;
import org.apache.http.entity.StringEntity;
import org.apache.http.impl.client.DefaultHttpClient;
import org.apache.http.params.HttpConnectionParams;
import org.apache.http.params.HttpParams;
import org.json.JSONException;
import org.json.JSONObject;
public class Sale {
public static void RunVerify() {
try {
HttpClient client = new DefaultHttpClient();
HttpParams params = client.getParams();
HttpConnectionParams.setConnectionTimeout(params, 10000);
JSONObject jsonRequestObject = new JSONObject();
String url = "https://api.payhub.com/api/v2/verify";
JSONObject merchant = new JSONObject();
merchant.put("organization_id", "10005");//You put your org id here
merchant.put("terminal_id", "5");//You put your terminal id
jsonRequestObject.put("merchant", merchant);
JSONObject card_data = new JSONObject();
card_data.put("card_number", "5466410004374507");
card_data.put("card_expiry_date", "201809");// September 2018
card_data.put("billing_address_1", "237 E 33rd Street");
card_data.put("billing_address_2", "3rd Floor");
card_data.put("billing_city", "New York");
card_data.put("billing_zip", "10016");
card_data.put("billing_state", "NY");
card_data.put("cvv_data", "998");
card_data.put("cvv_code", "Y");
jsonRequestObject.put("card_data", card_data);
JSONObject customer = new JSONObject();
customer.put("first_name", "John");
customer.put("last_name", "Smith");
customer.put("company_name", "CBA Steakhouse");
customer.put("job_title", "Owner");
customer.put("email_address", "john@cbasteakhouse.com");
customer.put("web_address", "http://www.cbasteakhouse.com");
customer.put("phone_number", "(917) 479 1349");
customer.put("phone_ext", "5478");
customer.put("phone_type", "M");
jsonRequestObject.put("customer", customer);
jsonRequestObject.put("record_format", "CC");
HttpPost postCreate = new HttpPost(url);
postCreate.addHeader("Authorization", "Bearer dfd4f12a-79af-4825-8dba-db27342c8491");//You put your token here
postCreate.addHeader("Content-Type", "application/json");
postCreate.addHeader("Accept", "application/json");
StringEntity se = new StringEntity(jsonRequestObject.toString());
postCreate.setEntity(se);
HttpResponse response = client.execute(postCreate); //You return this response and work with it
String json = " ";
JSONObject jsonResponseObject = null;
InputStream in = response.getEntity().getContent();
int cnt = 0;
while ((cnt = in.read()) > -1) {
json += (char) cnt;
}
if (json.charAt(0) != '<') {
jsonResponseObject = new JSONObject(
(json.equalsIgnoreCase("")
|| json.equalsIgnoreCase(" ") ? "{\"MESSAGE\":\"NO RESPONSE...\"}"
: json));
}
String result = response.getStatusLine().getReasonPhrase();
System.out.println(result);
if (result.equals("Created")){
Header[] headers = response.getAllHeaders();
for (Header header : headers) {
if (header.getName().equals("Location")){
URL location = new URL(header.getValue());
String path = location.getPath();
int lastSlash = path.lastIndexOf("/");
String transactionId = path.substring(lastSlash+1);
System.out.println("Transaction Id: " + transactionId ); //Last resource of the path
}
}
}
else{
System.out.println(jsonResponseObject.toString());
}
} catch (JSONException e){
System.out.println(e.getMessage());
} catch (UnsupportedEncodingException e) {
System.out.println(e.getMessage());
} catch (ClientProtocolException e) {
System.out.println(e.getMessage());
} catch (IOException e) {
System.out.println(e.getMessage());
}
}
}
<?php
$trans_type = "verify";
$processed = FALSE;
$ERROR_MESSAGE = '';
//Defining the Web Service URL
$WsURL="https://api.payhub.com/api/v2/$trans_type";
//Defining data for the SALE transaction
// Merchant data (obtained from the payHub Virtual Terminal (3rd party integration)
$organization_id = 10002;
$terminal_id = 2;
$oauth_token = "22fe3c69-db70-4a8c-9aed-9a33ebb1e9b4";
//Credit card data
$card_number = "5466410004374507";
$card_expiry_date = "202011";
$cvv_data = "998";
$billing_address_1 = "2350 Kerner Blvd";
$billing_address_2 = "On the corner";
$billing_city = "San Rafael";
$billing_state = "CA";
$billing_zip = "94901";
// Customer data
$first_name = "First";
$last_name = "Contact";
$company_name = "Payhub Inc";
$job_title = "Software Engineer";
$email_address = "jhon@company.com";
$web_address = "http://payhub.com";
$phone_number = "(415) 479 1349";
$phone_ext = "123";
$phone_type = "M";
//Convert data to array to send it to the WS as JSON format
$data = array();
$data["merchant"] = array("organization_id" => "$organization_id", "terminal_id" => "$terminal_id");
$data["bill"] = array ("base_amount" => array ("currency" => "USD","amount" => $base_amount),
"shipping_amount" => array ("currency" => "USD","amount" => $shipping_amount),
"tax_amount" => array ("currency" => "USD","amount" => $tax_amount));
$data["card_data"] = array("card_number" => "$card_number","card_expiry_date" => "$card_expiry_date",
"cvv_data" => "$cvv_data","billing_address_1" => "$billing_address_1",
"billing_address_2" => "$billing_address_2","billing_city" => "$billing_city",
"billing_state" => "$billing_state","billing_zip" => "$billing_zip");
$data ["customer"]= array("first_name" => "$first_name","last_name" => "$last_name","company_name" => "$company_name",
"job_title" => "$job_title","email_address" => "$email_address","web_address" => "$web_address",
"phone_number" => "$phone_number","phone_ext" => "$phone_ext","phone_type" => "$phone_type");
//Convert data from Array to JSON
$data_string = json_encode($data);
//Creating a CURL object to access the WS
$ch = curl_init();
//Setting the address to connect to
curl_setopt($ch, CURLOPT_URL, $WsURL);
//Setting HTTP method. For a new transaction we need to use POST
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
//Setting data in JSON format
curl_setopt($ch, CURLOPT_POSTFIELDS, $data_string);
//Setting the proper header.
//Setting the oauth_token to access the WS with the proper authorization
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
'Content-Type: application/json',
'Accept: application/json',
'Authorization: Bearer '.$oauth_token)
);
//Store the response as a variable and not showing the content as echo $variable
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
//Set to return the response header, this is to analyze the result and the transaction ID
curl_setopt($ch, CURLOPT_HEADER, true);
//execute connection to the Web Service
$response = curl_exec($ch);
// get some data from the response
$httpcode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
$header_size = curl_getinfo($ch, CURLINFO_HEADER_SIZE);
//Get the header as string.
$header = substr($response, 0, $header_size);
//close connection to the Web Service
curl_close($ch);
//Obtain the data from the verify recently created
if ($httpcode==201){
//find the url of the sale (Location header in the response)
preg_match("!\r\n(?:Location): *(.*?) *\r\n!", $header, $matches);
//$url contains the URL to GET the data from the Web Service
$url = $matches[1];
//Once we get the transaction ID we will query for the information of the last transaction
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
//Setting HTTP method. To get a transaction response we need to use GET
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "GET");
//Setting the proper header.
//Setting the oauth_token to access the WS with the proper authorization
curl_setopt($ch, CURLOPT_HTTPHEADER, array('Authorization: Bearer '.$oauth_token));
//Store the response as a variable and not showing the content as echo $variable
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
//execute connection to the Web Service
$response_json=curl_exec($ch);
//close connection to the Web Service
curl_close($ch);
//show result (standard JSON), parse it, process it, etc..
echo $response_json;
// now you could parse the json object to array if you preffer: $obj = json_decode($response_json);
$array = json_decode($response_json);
echo "<pre>";
print_r($array);
echo "</pre>";
}
//There was an error with the WS
else{
echo "Error creating the ".strtoupper($trans_type).": RESPONSE MESSAGE";
echo "<pre>";
echo $response;
echo "</pre>";
}
?>
using Newtonsoft.Json;
using System;
using System.IO;
using System.Net;
namespace PayHubSamples
{
public class Verify
{
public static void RunVerify()
{
try
{
var request = (HttpWebRequest)WebRequest.Create("https://api.payhub.com/api/v2/verify");
request.ContentType = "text/json";
request.Method = "POST";
var sale = new
{
merchant = new
{
organization_id = "10005",
terminal_id = "5",
},
card_data = new
{
card_number = "5466410004374507",
card_expiry_date = "201809", //September 2018
billing_address_1 = "237 E 33rd Street",
billing_address_2 = "3rd Floor",
billing_city = "New York",
billing_state = "NY",
billing_zip = "10016",
cvv_data = "998",
cvv_code = "Y"
},
customer = new
{
first_name = "John",
last_name = "Smith",
company_name = "CBA Stakehouse",
job_title = "Owner",
email_address = "john@cbastakehouse.com",
web_address = "http://www.cbasteakhouse.com",
phone_number = "(917) 479 1349",
phone_ext = "5478",
phone_type = "M"
},
record_format = "CC"
};
string json = JsonConvert.SerializeObject(sale);
request.Headers.Add("Authorization", "Bearer dfd4f12a-79af-4825-8dba-db27342c8491");
request.ContentType = "application/json";
request.Accept = "application/json";
using (var streamWriter = new StreamWriter(request.GetRequestStream()))
{
streamWriter.Write(json);
streamWriter.Flush();
streamWriter.Close();
}
try
{
var response = (HttpWebResponse)request.GetResponse();//You return this response.
using (var reader = new StreamReader(response.GetResponseStream()))
{
string result = reader.ReadToEnd();
Console.WriteLine(response.StatusCode);//Created
for (int i = 0; i < response.Headers.Count; ++i)
{
if (response.Headers.Keys[i] == "Location")
{
string path = response.Headers[i];
int lastSlash = path.LastIndexOf("/");
string transactionId = path.Substring(lastSlash + 1);
Console.WriteLine("Transaction Id: " + transactionId);
}
}
}
}
catch (WebException wex)
{
if (wex.Response != null)
{
using (var errorResponse = (HttpWebResponse)wex.Response)//You return wex.Response instead
{
using (var reader = new StreamReader(errorResponse.GetResponseStream()))
{
string result = reader.ReadToEnd();
Console.WriteLine(result);
}
}
}
}
}
catch (IOException e)
{
Console.WriteLine(e);
}
}
}
}
{
"merchant" : {
"organization_id" : 10005,
"terminal_id" : 5
},
"card_data" : {
"card_number" : "5466410004374507",
"card_expiry_date" : "202011",
"billing_address_1" : "2350 Kerner Blvd",
"billing_address_2" : "On the corner",
"billing_city" : "San Rafael",
"billing_state" : "CA",
"billing_zip" : "94901",
"cvv_data" : "998"
},
"customer" : {
"first_name" : "Adam",
"last_name" : "Smith",
"company_name" : "Go Capitalism Inc",
"job_title" : "Author",
"email_address" : "adam@smith.com",
"web_address" : "http://gocaptilaism.com",
"phone_number" : "(415) 479 1349",
"phone_ext" : "123",
"phone_type" : "M"
}
}
require 'uri'
require 'net/http'
require 'json'
url = URI("https://api.payhub.com/api/v2/verify")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Post.new(url)
request["content-type"] = 'application/json'
request["accept"] = 'application/json'
request["authorization"] = 'Bearer 2a5d6a73-d294-4fba-bfba-957a4948d4a3'
request["cache-control"] = 'no-cache'
merchant = {
"organization_id"=>10074,
"terminal_id"=>134
}
#Credit card data
card_data = {
"card_number"=>"4055011111111111",
"card_expiry_date"=>"202012",
"cvv_data"=>"999",
"billing_address_1"=>"2350 Kerner Blvd",
"billing_address_2"=>"On the corner",
"billing_city"=>"San Rafael",
"billing_state"=>"CA",
"billing_zip"=>"99997-0003"
}
# Customer data
customer = {"first_name"=>"First",
"last_name"=>"Contact",
"company_name"=>"Payhub Inc",
"job_title"=>"Software Engineer",
"email_address"=>"jhon@company.com",
"web_address"=>"http://payhub.com",
"phone_number"=>"(415) 479 1349",
"phone_ext"=>"123",
"phone_type"=>"M"
}
informationToSend = {"merchant"=>merchant,"customer"=>customer,"card_data"=>card_data}
request.body = JSON.generate(informationToSend)
response = http.request(request)
puts response.read_body
Introduction
This topic provides the information about the using Verify transaction. Run the Verify transaction when you want to know if the card data you have is valid and ready to run other transactions,such as sale. This is a zero ($0.00) amount transaction, no funds are exchanged.
Request Method
POST
Endpoint (URL to Call)
https://api.payhub.com/api/v2/verify
Elements
merchant
| Key | Type | Description |
|---|---|---|
| organization_id | integer | The Organization Id of the Merchant. This must match the Organization Id of the Merchant that the passed Oauth Token is associated with. |
| terminal_id | integer | The merchant’s virtual terminal Id for 3rd Party API. |
card_data
| Key | Type | Description |
|---|---|---|
| tokenized_card | string, optional | This is the 16 character PayHub-specific tokenized string representing the card number. The value for the given customer and credit card can be obtained by examining the last Sale by accessing the link to the card data that was successfully created. It is safer (and recommended) for the third party client to store and use this string in any future requests for the same customer. This value is required if the ‘card_number’ property is not present in the request. |
| card_number | string, optional | This is the 16 character card number. This value is required if the 'tokenized_card’ property is not present in the request. Note: The card number is not stored by the API in plain text. The response will contain a tokenized card number that should always be used in future requests, (for the same Customer) in place of this property. |
| track1_data | string, optional | This is the string read by the swiper (It contents track 1 data without sentinels). |
| track2_data | string, optional | This is the string read by the swiper (It contents track 2 data without sentinels). |
| encrypted_track_data | optional |
|
| billing_address_1 | string, optional | The billing street address of the customer. |
| billing_address_2 | string, optional | The additional billing street address of the customer. |
| billing_city | string, optional | The billing city of the customer. |
| billing_state | string, optional | The billing state Code of the customer. For example, CA, WI, NY, etc. The sate codes should be for the states in the USA. |
| billing_zip | string, optional | The billing Zip Code of the customer. The zip code must be either 5 digits or 5 plus four separated by a ’-’. The zip code is required if the merchant has turned ON the AVS flag. |
| card_expiry_date | string | The card expiry in the YYYYMM format. |
| cvv_data | string, optional | This is the three or four digit CVV code on the credit and debit card. |
customer
| Key | Type | Description |
|---|---|---|
| first_name | string | The first name of the customer. |
| last_name | string | The last name of the customer. |
| company_name | string | The company name of the customer. |
| job_title | string, optional | The job title of the customer. |
| email_address | string, optional | The valid email address of the customer. The email address must be syntactically correct. If you do not specify the email address, you must provide a phone_number to identify the customer. |
| web_address | string, optional | The web address of the customer. The web address, if you specify, must be syntactically valid web address. |
| phone_number | string, optional | The phone number of the customer. The phone number must be syntactically correct. For example, (415) 234 5678, or 4152345678, or (415) 234-5678. If you do not specify the phone number, you must provide an email_address to identify the customer. |
| phone_ext | string, optional | The phone extension number of the customer. |
| phone_type | string, optional | The type (['H’ or 'W’ or ’M’]) phone number: H (Home), W (Work), M (Mobile). |
{
"id": "182364",
"version": 0,
"createdAt": "2015-07-07T08:45:15.594-07:00",
"lastModified": "2015-07-07T08:45:15.594-07:00",
"createdBy": "10127",
"lastModifiedBy": "10127",
"metaData": null,
"merchant": {
"id": "10127215",
"version": 1,
"createdAt": "2015-04-02T11:46:16.676-07:00",
"lastModified": "2015-04-28T13:28:21.427-07:00",
"createdBy": "10127",
"lastModifiedBy": "10127",
"metaData": null,
"organization_id": 10127,
"terminal_id": 215
},
"customer": {
"id": "182364",
"version": 0,
"createdAt": "2015-07-07T08:45:15.584-07:00",
"lastModified": "2015-07-07T08:45:15.584-07:00",
"createdBy": "10127",
"lastModifiedBy": "10127",
"metaData": null,
"first_name": "First",
"last_name": "Contact",
"email_address": "test@payhub.com",
"phone_number": "(415) 479 1349",
"phone_ext": "123",
"phone_type": "M",
"company_name": "Payhub Inc",
"job_title": "Software Engineer",
"web_address": "http://payhub.com",
"customerReference": {
"customerId": 2972,
"customerEmail": "test@payhub.com",
"customerPhones": []
},
"customerId": 182364
},
"card_data": {
"id": "9999000000001853",
"version": 248,
"createdAt": "2015-04-02T11:46:16.457-07:00",
"lastModified": "2015-10-22T11:42:39.589-07:00",
"createdBy": "10127",
"lastModifiedBy": "10127",
"metaData": null,
"cvv_data": null,
"track1_data": null,
"track2_data": null,
"encrypted_track_data": null,
"card_number": null,
"card_expiry_date": "202011",
"tokenized_card": "9999000000001853",
"billing_address_1": "2350 Kerner Blvd",
"billing_address_2": "On the corner",
"billing_city": "San Rafael",
"billing_state": "CA",
"billing_zip": "94901",
"cardObscured": null,
"cardType": null
},
"verifyResponse": {
"verifyId": "182364",
"approvalCode": "VTLMC1",
"processedDateTime": null,
"avsResultCode": "0",
"verificationResultCode": "",
"responseCode": "00",
"responseText": "APPROVAL VTLMC1",
"cisNote": "",
"riskStatusResponseText": "",
"riskStatusRespondeCode": "",
"saleDateTime": "2015-07-07 08:45:15",
"tokenizedCard": "9999000000001853",
"customerReference": {
"customerId": 2972,
"customerEmail": "test@payhub.com",
"customerPhones": []
},
"cardObscured": null,
"cardType": null
},
"_links": {
"self": {
"href": "https://api.payhub.com/api/v2/verify/182364"
},
"merchant": {
"href": "https://api.payhub.com/api/v2/verify/182364/merchant"
},
"customer": {
"href": "https://api.payhub.com/api/v2/verify/182364/customer"
},
"card_data": {
"href": "https://api.payhub.com/api/v2/verify/182364/card_data"
}
}
}
Response
- A 201 Created status if the card data is correct. That’s all you need to know if card data is valid.
- The Id of the Verify will be provided in the Location header that is returned. This is referred as the Transaction Id.
Verify header in the response:Location ? https:// [payhub-api-server]:8251/payhubws/api/verify/23053.
If you do a GET request to this URL, you will get all the transaction information in JSON format.
Note: You will need to use Oauth token in the header request for sales or any other transaction. For more information, see the
OAuth 2.0 Access Tokens section.
Extended Methods
Request Method
GET
Endpoints (URLs to Call)
GET https://api.payhub.com/api/v2/verify/{id}
Use the verify Id in order to get the information of the verify response.
GET https://api.payhub.com/api/v2/verify/{id}/merchant
Use the verify Id in order to get the merchant information of the verify response.
GET https://api.payhub.com/api/v2/verify/{id}/customer
Use the verify Id in order to get the customer information of the verify response.
GET https://api.payhub.com/api/v2/verify/{id}/card_data
Use the verify Id in order to get the card data of the verify response. (The information on this method is reduced by security policies)
GET https://api.payhub.com/api/v2/verify/
If the ID is not present, you will get a list with all the transactions.
By default, the list return only the first 20 resutls and it can be paged, you can modify this by adding the next parameters to the url:
page={pageNo}&size={size}
SDKs Methods
Each SDK has a transaction manager class with the next methods:
- Create a transaction: doVerify
- Get transaction information based on the transaction ID: getVerifyInformation({transactionId})
- Get all the transactions performed under this method: getAllVerifyInformation (optional parameters for page and size)
The first two methods returns a VerifyResponseInformation object, the third method returns a list of VerifyResponseInformation objects.
Each VerifyResponseInformation has the next methods:
- getMerchantInformation()
- getCardDataInformation()
- getCustomerInformation()
AuthOnly Transaction
package transactions;
import java.io.IOException;
import java.io.InputStream;
import java.io.UnsupportedEncodingException;
import java.net.URL;
import org.apache.http.Header;
import org.apache.http.HttpResponse;
import org.apache.http.client.ClientProtocolException;
import org.apache.http.client.HttpClient;
import org.apache.http.client.methods.HttpPost;
import org.apache.http.entity.StringEntity;
import org.apache.http.impl.client.DefaultHttpClient;
import org.apache.http.params.HttpConnectionParams;
import org.apache.http.params.HttpParams;
import org.json.JSONException;
import org.json.JSONObject;
public class AuthOnly {
public static void RunAuthOnly() {
try {
HttpClient client = new DefaultHttpClient();
HttpParams params = client.getParams();
HttpConnectionParams.setConnectionTimeout(params, 10000);
JSONObject jsonRequestObject = new JSONObject();
String url = "https://api.payhub.com/api/v2/authOnly";
JSONObject merchant = new JSONObject();
merchant.put("organization_id", "10005");//You put your org id here
merchant.put("terminal_id", "5");//You put your terminal id
jsonRequestObject.put("merchant", merchant);
JSONObject bill = new JSONObject();
JSONObject base_amount = new JSONObject();
base_amount.put("amount", "1275");//$12.75
bill.put("base_amount", base_amount);
JSONObject shipping_amount = new JSONObject();
shipping_amount.put("amount", "725");//$7.25
bill.put("shipping_amount", shipping_amount);
JSONObject tax_amount = new JSONObject();
tax_amount.put("amount", "113");//$1.13
bill.put("tax_amount", tax_amount);
bill.put("note", "Shipped as a gift");
bill.put("invoice_number", "4645782");
bill.put("po_number", "1234-654321");
jsonRequestObject.put("bill", bill);
JSONObject card_data = new JSONObject();
card_data.put("card_number", "5466410004374507");
card_data.put("card_expiry_date", "201809");// September 2018
card_data.put("billing_address_1", "237 E 33rd Street");
card_data.put("billing_address_2", "3rd Floor");
card_data.put("billing_city", "New York");
card_data.put("billing_zip", "10016");
card_data.put("billing_state", "NY");
card_data.put("cvv_data", "998");
card_data.put("cvv_code", "Y");
jsonRequestObject.put("card_data", card_data);
JSONObject customer = new JSONObject();
customer.put("first_name", "John");
customer.put("last_name", "Smith");
customer.put("company_name", "CBA Steakhouse");
customer.put("job_title", "Owner");
customer.put("email_address", "john@cbasteakhouse.com");
customer.put("web_address", "http://www.cbasteakhouse.com");
customer.put("phone_number", "(917) 479 1349");
customer.put("phone_ext", "5478");
customer.put("phone_type", "M");
jsonRequestObject.put("customer", customer);
jsonRequestObject.put("record_format", "CC");
HttpPost postCreate = new HttpPost(url);
postCreate.addHeader("Authorization", "Bearer dfd4f12a-79af-4825-8dba-db27342c8491");//You put your token here
postCreate.addHeader("Content-Type", "application/json");
postCreate.addHeader("Accept", "application/json");
StringEntity se = new StringEntity(jsonRequestObject.toString());
postCreate.setEntity(se);
HttpResponse response = client.execute(postCreate); //You return this response and work with it
String json = " ";
JSONObject jsonResponseObject = null;
InputStream in = response.getEntity().getContent();
int cnt = 0;
while ((cnt = in.read()) > -1) {
json += (char) cnt;
}
if (json.charAt(0) != '<') {
jsonResponseObject = new JSONObject(
(json.equalsIgnoreCase("")
|| json.equalsIgnoreCase(" ") ? "{\"MESSAGE\":\"NO RESPONSE...\"}"
: json));
}
String result = response.getStatusLine().getReasonPhrase();
System.out.println(result);
if (result.equals("Created")){
Header[] headers = response.getAllHeaders();
for (Header header : headers) {
if (header.getName().equals("Location")){
URL location = new URL(header.getValue());
String path = location.getPath();
int lastSlash = path.lastIndexOf("/");
String transactionId = path.substring(lastSlash+1);
System.out.println("Transaction Id: " + transactionId ); //Last resource of the path
}
}
}
else{
System.out.println(jsonResponseObject.toString());
}
} catch (JSONException e){
System.out.println(e.getMessage());
} catch (UnsupportedEncodingException e) {
System.out.println(e.getMessage());
} catch (ClientProtocolException e) {
System.out.println(e.getMessage());
} catch (IOException e) {
System.out.println(e.getMessage());
}
}
}
<?php
$trans_type = "authOnly";
$processed = FALSE;
$ERROR_MESSAGE = '';
//Defining the Web Service URL
$WsURL="https://api.payhub.com/api/v2/$trans_type";
//Defining data for the AuthOnly transaction
// Merchant data (obtained from the payHub Virtual Terminal (3rd party integration)
$organization_id = 10002;
$terminal_id = 2;
$oauth_token = "22fe3c69-db70-4a8c-9aed-9a33ebb1e9b4";
// bill data
$base_amount = 10.0;
$shipping_amount = 1.23;
$tax_amount = 1.00;
$note = "this a sample note";
$invoice_number = "a-00240";
$po_number = "56";
//Credit card data
$card_number = "5466410004374507";
$card_expiry_date = "202011";
$cvv_data = "998";
$billing_address_1 = "2350 Kerner Blvd";
$billing_address_2 = "On the corner";
$billing_city = "San Rafael";
$billing_state = "CA";
$billing_zip = "94901";
// Customer data
$first_name = "First";
$last_name = "Contact";
$company_name = "Payhub Inc";
$job_title = "Software Engineer";
$email_address = "jhon@company.com";
$web_address = "http://payhub.com";
$phone_number = "(415) 479 1349";
$phone_ext = "123";
$phone_type = "M";
//Convert data to array to send it to the WS as JSON format
$data = array();
$data["merchant"] = array("organization_id" => "$organization_id", "terminal_id" => "$terminal_id");
$data["bill"] = array ("base_amount" => array ("currency" => "USD","amount" => $base_amount),
"shipping_amount" => array ("currency" => "USD","amount" => $shipping_amount),
"tax_amount" => array ("currency" => "USD","amount" => $tax_amount));
$data["card_data"] = array("card_number" => "$card_number","card_expiry_date" => "$card_expiry_date",
"cvv_data" => "$cvv_data","billing_address_1" => "$billing_address_1",
"billing_address_2" => "$billing_address_2","billing_city" => "$billing_city",
"billing_state" => "$billing_state","billing_zip" => "$billing_zip");
$data ["customer"]= array("first_name" => "$first_name","last_name" => "$last_name","company_name" => "$company_name",
"job_title" => "$job_title","email_address" => "$email_address","web_address" => "$web_address",
"phone_number" => "$phone_number","phone_ext" => "$phone_ext","phone_type" => "$phone_type");
//Convert data from Array to JSON
$data_string = json_encode($data);
//Creating a CURL object to access the WS
$ch = curl_init();
//Setting the address to connect to
curl_setopt($ch, CURLOPT_URL, $WsURL);
//Setting HTTP method. For a new transaction we need to use POST
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
//Setting data in JSON format
curl_setopt($ch, CURLOPT_POSTFIELDS, $data_string);
//Setting the proper header.
//Setting the oauth_token to access the WS with the proper authorization
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
'Content-Type: application/json',
'Accept: application/json',
'Authorization: Bearer '.$oauth_token)
);
//Store the response as a variable and not showing the content as echo $variable
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
//Set to return the response header, this is to analyze the result and the transaction ID
curl_setopt($ch, CURLOPT_HEADER, true);
//execute connection to the Web Service
$response = curl_exec($ch);
// get some data from the response
$httpcode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
$header_size = curl_getinfo($ch, CURLINFO_HEADER_SIZE);
//Get the header as string.
$header = substr($response, 0, $header_size);
//close connection to the Web Service
curl_close($ch);
//Obtain the data from the sale recently created
if ($httpcode==201){
//find the url of the sale (Location header in the response)
preg_match("!\r\n(?:Location): *(.*?) *\r\n!", $header, $matches);
//$url contains the URL to GET the data from the Web Service
$url = $matches[1];
//Once we get the transaction ID we will query for the information of the last transaction
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
//Setting HTTP method. To get a transaction response we need to use GET
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "GET");
//Setting the proper header.
//Setting the oauth_token to access the WS with the proper authorization
curl_setopt($ch, CURLOPT_HTTPHEADER, array('Authorization: Bearer '.$oauth_token));
//Store the response as a variable and not showing the content as echo $variable
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
//execute connection to the Web Service
$response_json=curl_exec($ch);
//close connection to the Web Service
curl_close($ch);
//show result (standard JSON), parse it, process it, etc..
echo $response_json;
// now you could parse the json object to array if you preffer: $obj = json_decode($response_json);
$array = json_decode($response_json);
echo "<pre>";
print_r($array);
echo "</pre>";
}
//There was an error with the WS
else{
echo "Error creating the ".strtoupper($trans_type).": RESPONSE MESSAGE";
echo "<pre>";
echo $response;
echo "</pre>";
}
?>
using Newtonsoft.Json;
using System;
using System.IO;
using System.Net;
namespace PayHubSamples
{
public class AuthOnly
{
public static void RunAuthOnly()
{
try
{
var request = (HttpWebRequest)WebRequest.Create("https://api.payhub.com/api/v2/authonly");
request.ContentType = "text/json";
request.Method = "POST";
var authOnly = new
{
merchant = new
{
organization_id = "10005",
terminal_id = "5",
},
bill = new
{
base_amount = new
{
amount = "1275" //$12.75
},
shipping_amount = new
{
amount = "725" //$7.25
},
tax_amount = new
{
amount = "113" //$1.13
},
note = "Shipped as a gift",
invoice_number = "4645782",
po_number = "1234-654321"
},
card_data = new
{
card_number = "5466410004374507",
card_expiry_date = "201809", //September 2018
billing_address_1 = "237 E 33rd Street",
billing_address_2 = "3rd Floor",
billing_city = "New York",
billing_state = "NY",
billing_zip = "10016",
cvv_data = "998",
cvv_code = "Y"
},
customer = new
{
first_name = "John",
last_name = "Smith",
company_name = "CBA Stakehouse",
job_title = "Owner",
email_address = "john@cbastakehouse.com",
web_address = "http://www.cbasteakhouse.com",
phone_number = "(917) 479 1349",
phone_ext = "5478",
phone_type = "M"
},
record_format = "CC"
};
string json = JsonConvert.SerializeObject(authOnly);
request.Headers.Add("Authorization", "Bearer dfd4f12a-79af-4825-8dba-db27342c8491");
request.ContentType = "application/json";
request.Accept = "application/json";
using (var streamWriter = new StreamWriter(request.GetRequestStream()))
{
streamWriter.Write(json);
streamWriter.Flush();
streamWriter.Close();
}
try
{
var response = (HttpWebResponse)request.GetResponse();//You return this response.
using (var reader = new StreamReader(response.GetResponseStream()))
{
string result = reader.ReadToEnd();
Console.WriteLine(response.StatusCode);//Created
for (int i = 0; i < response.Headers.Count; ++i)
{
if (response.Headers.Keys[i] == "Location")
{
string path = response.Headers[i];
int lastSlash = path.LastIndexOf("/");
string transactionId = path.Substring(lastSlash + 1);
Console.WriteLine("Transaction Id: " + transactionId);
}
}
}
}
catch (WebException wex)
{
if (wex.Response != null)
{
using (var errorResponse = (HttpWebResponse)wex.Response)//You return wex.Response instead
{
using (var reader = new StreamReader(errorResponse.GetResponseStream()))
{
string result = reader.ReadToEnd();
Console.WriteLine(result);
}
}
}
}
}
catch (IOException e)
{
Console.WriteLine(e);
}
}
}
}
{
"merchant" : {
"organization_id" : 10002,
"terminal_id" : 2
},
"bill" : {
"base_amount" : {
"amount" : 10.0
},
"shipping_amount" : {
"amount" : 1.23
},
"tax_amount" : {
"amount" : 1.00
},
"note" : "Send as a gift.",
"invoice_number" : "328742",
"po_number" : "2474-6975"
},
"card_data" : {
"card_number" : "5466410004374507",
"card_expiry_date" : "202011",
"billing_address_1" : "2350 Kerner Blvd",
"billing_address_2" : "2 floor",
"billing_city" : "San Rafael",
"billing_state" : "CA",
"billing_zip" : "94901",
"cvv_data" : "998"
},
"customer" : {
"first_name" : "Miguel",
"last_name" : "Smith",
"company_name" : "Payhub Inc",
"job_title" : "Software Engineer",
"email_address" : "msmith14567@payhub.com",
"web_address" : "http://payhub.com",
"phone_number" : "(415) 479 1349",
"phone_ext" : "123",
"phone_type" : "M"
},
"record_format" : "CREDIT_CARD"
}
require 'uri'
require 'net/http'
require 'json'
url = URI("https://api.payhub.com/api/v2/authonly")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Post.new(url)
request["content-type"] = 'application/json'
request["accept"] = 'application/json'
request["authorization"] = 'Bearer 2a5d6a73-d294-4fba-bfba-957a4948d4a3'
request["cache-control"] = 'no-cache'
merchant = {
"organization_id"=>10074,
"terminal_id"=>134
}
# bill data
bill= {
"base_amount"=>Hash["amount" =>"1.00"],
"shipping_amount"=>Hash["amount" =>"1.00"],
"tax_amount"=>Hash["amount" =>"1.00"],
"note"=>"this a sample note",
"invoice_number"=>"this is an invoice",
"po_number"=>"a test po number"
}
#Credit card data
card_data = {
"card_number"=>"4055011111111111",
"card_expiry_date"=>"202012",
"cvv_data"=>"999",
"billing_address_1"=>"2350 Kerner Blvd",
"billing_address_2"=>"On the corner",
"billing_city"=>"San Rafael",
"billing_state"=>"CA",
"billing_zip"=>"99997-0003"
}
# Customer data
customer = {"first_name"=>"First",
"last_name"=>"Contact",
"company_name"=>"Payhub Inc",
"job_title"=>"Software Engineer",
"email_address"=>"jhon@company.com",
"web_address"=>"http://payhub.com",
"phone_number"=>"(415) 479 1349",
"phone_ext"=>"123",
"phone_type"=>"M"
}
informationToSend = {"merchant"=>merchant,"bill"=>bill,"customer"=>customer,"card_data"=>card_data}
request.body = JSON.generate(informationToSend)
response = http.request(request)
puts response.read_body
Introduction
This topic provides the information about the AuthOnly transaction.
You can use the AuthOnly transaction to authorize an amount on your customer’s credit card without making the actual settlement of that amount. With the AuthOnly transaction, you actually reserve an amount for a certain period against the credit limit of the card holder.
Usually, you use the AutOnly transaction type when you are selling an item, which is currently out of stock. So, you run the AuthOnly transaction when the item is not available and when the item becomes available in the stock, you run the Capture transaction to actually make the settlement for the reserved amount. To simply say, the AuthOnly and Capture transactions are essentially a sale process in two steps.
The sale is considered complete when you successfully complete both the Capture and AuthOnly transactions. The money will be debited from the card holder’s account and credited to your account after the sale is complete.
When the AuthOnly transaction is successfully executed, you will receive a 201 Created code on a successful AuthOnly. This code also includes the transaction ID. You can use this transaction ID to run the Capture transaction.
Request Method
POST
Endpoint (URL to Call)
POST https://api.payhub.com/api/v2/authOnly
Elements
merchant
| Key | Type | Value |
|---|---|---|
| organization_id | integer | The Organization Id of the Merchant. This value must match with the Organization Id of the Merchant with which the passed Oauth Token is associated. |
| terminal_id | integer | The virtual Terminal Id of the merchant for the 3rd Party API. |
bill
| Key | Type | Value |
|---|---|---|
| base_amount | TransactionAmount | The Base amount of the recurring bill. The total amount charged will be the sum of this amount and (any) ‘shipping_amount’ and 'tax_amount’. |
| shipping_amount | TransactionAmount, optional | The shipping amount for the transaction. The value will be included in the total amount charged. |
| tax_amount | TransactionAmount, optional | The tax amount for the transaction. The value will be included in the total amount charged. |
| invoice_number | string, optional | The invoice number for the transaction. |
| po_number | string, optional | The purchase order number for the transaction. |
| note | string, optional | A free format note for the transaction. The note will be read by the merchant. |
card_data
| Key | Type | Value |
|---|---|---|
| tokenized_card | string, optional | This is the 16 character PayHub-specific tokenized string that represents the card number. You can obtain the value for the given customer and credit card by examining the last sale, by accessing the link to the card data that was successfully created. It is safer (and recommended) method for the third party client to store and use this string in any future requests for the same customer. This value is required if the 'card_number’ property is not present in the request. |
| card_number | string, optional | This is the 16 character card number. The card number is not stored by the API in plain text. The response will contain a tokenized card number that should always be used in future requests, (for the same Customer) in place of this property. This value is required if the 'tokenized_card’ property is not present in the request. |
| billing_address_1 | string, optional | The billing street address of the customer. |
| billing_address_2 | string, optional | The additional billing street address of the customer. |
| billing_city | string, optional | The billing city of the customer. |
| billing_state | string, optional | The billing (US) State Code (CA, WI, NY, etc.) of the customer. |
| billing_zip | string, optional | The billing (US) Zip Code of the customer. The zip code must be either 5 digits or 5 plus four separated by a dash (’-’). This value is required if the Merchant has turned on the AVS flag. |
| card_expiry_date | string | The card expiry date in the YYYYMM format. |
| cvv_data | string | A three or four digit CVV code on the card. |
customer
| Key | Type | Value |
|---|---|---|
| first_name | string | The first name of the customer. |
| last_name | string | The last name of the customer. |
| company_name | string, optional | The company name of the customer. |
| job_title | string, optional | The job title of the customer. |
| email_address | string | The email address of the customer. The email address must be syntactically correct and valid. If email address is not specified, you must provide a phone_number to identify the customer. |
| web_address | string, optional | The web site address of the customer. The website address, if specified, must be syntactically correct and valid. |
| phone_number | string, optional | The phone number of the customer. The phone number must be syntactically correct. For example, (415) 234 5678, or 4152345678, or (415) 234-5678. If phone number is not specified, you must provide an email_address to identify the customer. |
| phone_ext | string, optional | The phone extension number of the customer. |
| phone_type | string, optional | The type of the phone the customer is using. The phone type can be ['H’ or 'W’ or ’M’]: H (Home), W (Work), M (Mobile). |
| record_format | string, optional | The value that indicates whether the sale has to be made over a credit card, debit card or cash payment. The default value is “CREDIT_CARD”. Following are the accepted values:
|
{
"version": 1,
"createdAt": "2015-07-06T19:41:02.984-07:00",
"lastModified": "2015-07-06T19:41:02.984-07:00",
"createdBy": "10127",
"lastModifiedBy": "10127",
"metaData": null,
"record_format": null,
"settlementStatus": "Settled",
"authOnlyResponse": {
"transactionId": "182349",
"approvalCode": "VTLMC1",
"processedDateTime": null,
"avsResultCode": "N",
"verificationResultCode": "M",
"batchId": "1395",
"responseCode": "00",
"responseText": "NO MATCH",
"cisNote": "",
"riskStatusResponseText": "",
"riskStatusRespondeCode": "",
"dateTime": "2015-07-06 19:41:02",
"customerReference": {
"customerId": 2972,
"customerEmail": "msmith14567@payhub.com",
"customerPhones": []
},
"billingReferences": {
"tokenizedCard": "9999000000001853",
"customerId": 2972,
"customerCardId": null,
"customerBillId": 1,
"cardObscured": null,
"cardType": null
}
},
"_links": {
"self": {
"href": "https://api.payhub.com/api/v2/authonly/182349"
},
"merchant": {
"href": "https://api.payhub.com/api/v2/authonly/182349/merchant"
},
"customer": {
"href": "https://api.payhub.com/api/v2/authonly/182349/customer"
},
"card_data": {
"href": "https://api.payhub.com/api/v2/authonly/182349/card_data"
},
"bill": {
"href": "https://api.payhub.com/api/v2/authonly/182349/bill"
}
}
}
Result
- 201 code (created)
- The Id of the AuthOnly will be provided in the Location header that is returned. This is referred as the Transaction Id.
Sample header in the response:Location: https://api.payhub.com/api/v2/authOnly/234
Note: You will need to use Oauth token in the header request for sales or any other transaction. For more information, see the
OAuth 2.0 Access Tokens section.
Extended Methods
Request Method
GET
Endpoints (URLs to Call)
GET https://api.payhub.com/api/v2/authonly/{id}
Use the Authorization Id in order to get the information of the Authorization response.
GET https://api.payhub.com/api/v2/authonly/{id}/merchant
Use the Authorization Id in order to get the merchant information of the Authorization response.
GET https://api.payhub.com/api/v2/authonly/{id}/customer
Use the Authorization Id in order to get the customer information of the Authorization response.
GET https://api.payhub.com/api/v2/authonly/{id}/bill
Use the Authorization Id in order to get the bill information of the Authorization response.
GET https://api.payhub.com/api/v2/authonly/{id}/card_data
Use the Authorization Id in order to get the card data of the Authorization response. (The information on this method is reduced by security policies)
GET https://api.payhub.com/api/v2/authonly/
If the ID is not present, you will get a list with all the transactions.
By default, the list return only the first 20 resutls and it can be paged, you can modify this by adding the next parameters to the url:
page={pageNo}&size={size}
SDKs Methods
Each SDK has a transaction manager class with the next methods:
- Create a transaction: doAuthonly
- Get transaction information based on the transaction ID: getAuthorizationInformation({transactionId})
- Get all the transactions performed under this method: getAllAuthOnlyInformation (optional parameters for page and size)
The first two methods returns a AuthorizationResponseInformation object, the third method returns a list of AuthorizationResponseInformation objects.
Each AuthorizationResponseInformation has the next methods:
- getMerchantInformation()
- getBillInformation()
- getCardDataInformation()
- getCustomerInformation()
Capture Transaction
package transactions;
import java.io.IOException;
import java.io.InputStream;
import java.io.UnsupportedEncodingException;
import java.net.URL;
import org.apache.http.Header;
import org.apache.http.HttpResponse;
import org.apache.http.client.ClientProtocolException;
import org.apache.http.client.HttpClient;
import org.apache.http.client.methods.HttpPost;
import org.apache.http.entity.StringEntity;
import org.apache.http.impl.client.DefaultHttpClient;
import org.apache.http.params.HttpConnectionParams;
import org.apache.http.params.HttpParams;
import org.json.JSONException;
import org.json.JSONObject;
public class Void {
public static void RunCapture() {
try {
HttpClient client = new DefaultHttpClient();
HttpParams params = client.getParams();
HttpConnectionParams.setConnectionTimeout(params, 10000);
JSONObject jsonRequestObject = new JSONObject();
String url = "https://api.payhub.com/api/v2/capture";
JSONObject merchant = new JSONObject();
merchant.put("organization_id", "10005"); //You put your org id here
merchant.put("terminal_id", "5");//You put your terminal id
jsonRequestObject.put("merchant", merchant);
jsonRequestObject.put("transaction_id", "223"); //You put the transaction id of the sale or refund you want to void
JSONObject bill = new JSONObject();
JSONObject base_amount = new JSONObject();
base_amount.put("amount", "1275");//$12.75
bill.put("base_amount", base_amount);
JSONObject shipping_amount = new JSONObject();
shipping_amount.put("amount", "725");//$7.25
bill.put("shipping_amount", shipping_amount);
JSONObject tax_amount = new JSONObject();
tax_amount.put("amount", "113");//$1.13
bill.put("tax_amount", tax_amount);
bill.put("note", "Shipped as a gift");
bill.put("invoice_number", "4645782");
bill.put("po_number", "1234-654321");
jsonRequestObject.put("bill", bill);
HttpPost postCreate = new HttpPost(url);
postCreate.addHeader("Authorization", "Bearer dfd4f12a-79af-4825-8dba-db27342c8491");//You put your token here
postCreate.addHeader("Content-Type", "application/json");
postCreate.addHeader("Accept", "application/json");
StringEntity se = new StringEntity(jsonRequestObject.toString());
postCreate.setEntity(se);
HttpResponse response = client.execute(postCreate); //You return this response and work with it
String json = " ";
JSONObject jsonResponseObject = null;
InputStream in = response.getEntity().getContent();
int cnt = 0;
while ((cnt = in.read()) > -1) {
json += (char) cnt;
}
if (json.charAt(0) != '<') {
jsonResponseObject = new JSONObject(
(json.equalsIgnoreCase("")
|| json.equalsIgnoreCase(" ") ? "{\"MESSAGE\":\"NO RESPONSE...\"}"
: json));
}
String result = response.getStatusLine().getReasonPhrase();
System.out.println(result);
if (result.equals("Created")){
Header[] headers = response.getAllHeaders();
for (Header header : headers) {
if (header.getName().equals("Location")){
URL location = new URL(header.getValue());
String path = location.getPath();
int lastSlash = path.lastIndexOf("/");
String transactionId = path.substring(lastSlash+1);
System.out.println("Transaction Id: " + transactionId );
}
}
}
else{
System.out.println(jsonResponseObject.toString());
}
} catch (JSONException e){
System.out.println(e.getMessage());
} catch (UnsupportedEncodingException e) {
System.out.println(e.getMessage());
} catch (ClientProtocolException e) {
System.out.println(e.getMessage());
} catch (IOException e) {
System.out.println(e.getMessage());
}
}
}
<?php
$trans_type = "capture";
$processed = FALSE;
$ERROR_MESSAGE = '';
//Defining the Web Service URL
$WsURL="https://api.payhub.com/api/v2/$trans_type";
//Defining data for the VOID transaction
// Merchant data (obtained from the payHub Virtual Terminal (3rd party integration)
$organization_id = 10002;
$terminal_id = 2;
$oauth_token = "22fe3c69-db70-4a8c-9aed-9a33ebb1e9b4";
$transaction_id="83";
// bill data
$base_amount = 10.0;
$shipping_amount = 1.23;
$tax_amount = 1.00;
$note = "this a sample note";
$invoice_number = "a-00240";
$po_number = "56";
//Convert data to array to send it to the WS as JSON format
$data = array();
$data["merchant"] = array("organization_id" => "$organization_id", "terminal_id" => "$terminal_id");
$data["transaction_id"]=$transaction_id;
$data["bill"] = array ("base_amount" => array ("currency" => "USD","amount" => $base_amount),
"shipping_amount" => array ("currency" => "USD","amount" => $shipping_amount),
"tax_amount" => array ("currency" => "USD","amount" => $tax_amount));
//Convert data from Array to JSON
$data_string = json_encode($data);
//Creating a CURL object to access the WS
$ch = curl_init();
//Setting the address to connect to
curl_setopt($ch, CURLOPT_URL, $WsURL);
//Setting HTTP method. For a new transaction we need to use POST
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
//Setting data in JSON format
curl_setopt($ch, CURLOPT_POSTFIELDS, $data_string);
//Setting the proper header.
//Setting the oauth_token to access the WS with the proper authorization
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
'Content-Type: application/json',
'Accept: application/json',
'Authorization: Bearer '.$oauth_token)
);
//Store the response as a variable and not showing the content as echo $variable
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
//Set to return the response header, this is to analyze the result and the transaction ID
curl_setopt($ch, CURLOPT_HEADER, true);
//execute connection to the Web Service
$response = curl_exec($ch);
// get some data from the response
$httpcode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
$header_size = curl_getinfo($ch, CURLINFO_HEADER_SIZE);
//Get the header as string.
$header = substr($response, 0, $header_size);
//close connection to the Web Service
curl_close($ch);
//Obtain the data from the void recently created
if ($httpcode==201){
//find the url of the void (Location header in the response)
preg_match("!\r\n(?:Location): *(.*?) *\r\n!", $header, $matches);
//$url contains the URL to GET the data from the Web Service
$url = $matches[1];
//Once we get the transaction ID we will query for the information of the last transaction
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
//Setting HTTP method. To get a transaction response we need to use GET
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "GET");
//Setting the proper header.
//Setting the oauth_token to access the WS with the proper authorization
curl_setopt($ch, CURLOPT_HTTPHEADER, array('Authorization: Bearer '.$oauth_token));
//Store the response as a variable and not showing the content as echo $variable
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
//execute connection to the Web Service
$response_json=curl_exec($ch);
//close connection to the Web Service
curl_close($ch);
//show result (standard JSON), parse it, process it, etc..
echo $response_json;
// now you could parse the json object to array if you preffer: $obj = json_decode($response_json);
$array = json_decode($response_json);
echo "<pre>";
print_r($array);
echo "</pre>";
}
//There was an error with the WS
else{
echo "Error creating the ".strtoupper($trans_type).": RESPONSE MESSAGE";
echo "<pre>";
echo $response;
echo "</pre>";
}
?>
using System;
using System.IO;
using System.Net;
using Newtonsoft.Json;
namespace PayHubSamples
{
public class Void
{
public static void RunCapture()
{
try
{
var request = (HttpWebRequest)WebRequest.Create("https://api.payhub.com/api/v2/capture");
request.ContentType = "text/json";
request.Method = "POST";
var capture = new
{
merchant = new
{
organization_id = "10005",
terminal_id = "5",
},
transaction_id = "238",
bill = new
{
base_amount = new
{
amount = "1275" //$12.75
},
shipping_amount = new
{
amount = "725" //$7.25
},
tax_amount = new
{
amount = "113" //$1.13
},
note = "Shipped as a gift",
invoice_number = "4645782",
po_number = "1234-654321"
}
};
string json = JsonConvert.SerializeObject(capture);
request.Headers.Add("Authorization", "Bearer dfd4f12a-79af-4825-8dba-db27342c8491");
request.ContentType = "application/json";
request.Accept = "application/json";
using (var streamWriter = new StreamWriter(request.GetRequestStream()))
{
streamWriter.Write(json);
streamWriter.Flush();
streamWriter.Close();
}
try
{
var response = (HttpWebResponse)request.GetResponse();//You return this response.
using (var reader = new StreamReader(response.GetResponseStream()))
{
string result = reader.ReadToEnd();
Console.WriteLine(response.StatusCode);//Created
for (int i = 0; i < response.Headers.Count; ++i)
{
if (response.Headers.Keys[i] == "Location")
{
string path = response.Headers[i];
int lastSlash = path.LastIndexOf("/");
string transactionId = path.Substring(lastSlash + 1);
Console.WriteLine("Transaction Id: " + transactionId);
}
}
}
}
catch (WebException wex)
{
if (wex.Response != null)
{
using (var errorResponse = (HttpWebResponse)wex.Response)//You return wex.Response instead
{
using (var reader = new StreamReader(errorResponse.GetResponseStream()))
{
string result = reader.ReadToEnd();
Console.WriteLine(result);
}
}
}
}
}
catch (IOException e)
{
Console.WriteLine(e);
}
}
}
}
{
"merchant" : {
"organization_id" : 10005,
"terminal_id" : 5
},
"transaction_id":"365",
"bill" : {
"base_amount" : {
"amount" : 6.00
},
"shipping_amount" : {
"amount" : 1.5
},
"tax_amount" : {
"amount" : 0.5
},
"note" : "Nice guest, giving him 20% discount.",
"invoice_number" : "789468",
"po_number" : "789468-CAP"
}
}
require 'uri'
require 'net/http'
require 'json'
url = URI("https://api.payhub.com/api/v2/capture")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Post.new(url)
request["content-type"] = 'application/json'
request["accept"] = 'application/json'
request["authorization"] = 'Bearer 2a5d6a73-d294-4fba-bfba-957a4948d4a3'
request["cache-control"] = 'no-cache'
merchant = {
"organization_id"=>10074,
"terminal_id"=>134
}
# bill data
bill= {
"base_amount"=>Hash["amount" =>"1.00"],
"shipping_amount"=>Hash["amount" =>"1.00"],
"tax_amount"=>Hash["amount" =>"1.00"],
"note"=>"this a sample note",
"invoice_number"=>"this is an invoice",
"po_number"=>"a test po number"
}
#transaction Id
transaction_id="114"
informationToSend = {"merchant"=>merchant,"bill"=>bill,"transaction_id"=>transaction_id}
request.body = JSON.generate(informationToSend)
response = http.request(request)
puts response.read_body
Introduction
This topic provides information about the Capture transaction.
Use the Capture transaction as the final step to collect the funds that you had asked for authorization through the AuthOnly transaction. You need to provide the transaction ID that you receive when you run the AuthOnly transaction.
In case the order fulfilment process, such as shipping goods some days after they were ordered, is delayed you might want to first run the AuthOnly transaction and then capture the respective funds. You might also need to change the amount that you got an authorization for. In that case, you need to provide a new bill section, including base amount and, if required, shipping amount, tax amount, invoice number, PO number, and note.
If the Capture transaction executes successfully, you will receive a 201 Created code. This code will include the transaction id. This transaction ID should be the same ID that you provided, which means, the same transaction id of the AuthOnly transaction that you just captured.
After capturing the amount for the AuthOnly transaction, the transaction will become a sale. The money will be taken from the card holder’s account and credited to your account during the settlement of the sale.
Request Method
Endpoint (URL to Call)
https://api.payhub.com/api/v2/capture
Elements
merchant (required)
| Key | Type | Value |
|---|---|---|
| organization_id | integer | The organization id of the merchant who did the AuthOnly that you are trying to capture. |
| terminal_id | integer | The terminal’s id of the merchant where the AuthOnly was done. |
transaction_id (integer, required)
The transaction id of the AuthOnly that you want to capture.
bill (optional)
| Key | Type | Value |
|---|---|---|
| base_amount | TransactionAmount | The base amount of the recurring bill. The total amount charged will be the sum of this amount and the ‘shipping_amount’, 'tax_amount’ if any. |
| shipping_amount | TransactionAmount, optional | The shipping amount for the transaction. This amount will be included in the total amount charged. |
| tax_amount | TransactionAmount, optional | The tax amount for the transaction. This amount will be included in the total amount charged. |
| invoice_number | string, optional | The invoice number of the transaction. |
| po_number | string, optional | The purchase order number of the transaction. |
| note | string, optional | A free format note for the transaction. The note will be read by the Merchant. |
Response
{
"id": "777",
"version": 0,
"createdAt": "2015-05-14T11:19:43.583-07:00",
"lastModified": "2015-05-14T11:19:43.583-07:00",
"createdBy": "10127",
"lastModifiedBy": "10127",
"metaData": null,
"merchant": {
"id": "10127215",
"version": 1,
"createdAt": "2015-04-02T11:46:16.676-07:00",
"lastModified": "2015-04-28T13:28:21.427-07:00",
"createdBy": "10127",
"lastModifiedBy": "10127",
"metaData": null,
"organization_id": 10127,
"terminal_id": 215
},
"bill": null,
"transaction_id": 114,
"lastCaptureResponse": {
"batchId": "702",
"transactionId": "114",
"billingReferences": null
},
"_links": {
"self": {
"href": "https://api.payhub.com/api/v2/capture/777"
},
"merchant": {
"href": "https://api.payhub.com/api/v2/capture/777/merchant"
},
"bill": {
"href": "https://api.payhub.com/api/v2/capture/777/bill"
}
}
}
Result
- 201 code (created)
- The Id of the Capture will be provided in the Location header that is returned. This is referred as the Transaction Id.
Sample header in the response:Location: https://api.payhub.com/api/v2/capture/234
Note: You will need to use Oauth token in the header request for sales or any other transaction. For more information, see the
OAuth 2.0 Access Tokens section.
Extended Methods
Request Method
GET
Endpoints (URLs to Call)
GET https://api.payhub.com/api/v2/capture/{id}
Use the Capture Id in order to get the information of the Capture response.
GET https://api.payhub.com/api/v2/capture/{id}/merchant
Use the Capture Id in order to get the merchant information of the Capture response.
GET https://api.payhub.com/api/v2/capture/{id}/bill
Use the Capture Id in order to get the bill information of the Capture response.
GET https://api.payhub.com/api/v2/capture/
If the ID is not present, you will get a list with all the transactions.
By default, the list return only the first 20 resutls and it can be paged, you can modify this by adding the next parameters to the url:
page={pageNo}&size={size}
SDKs Methods
Each SDK has a transaction manager class with the next methods:
- Create a transaction: doCapture
- Get transaction information based on the transaction ID: getCaptureInformation({transactionId})
- Get all the transactions performed under this method: getAllCaptureInformation (optional parameters for page and size)
The first two methods returns a CaptureResponseInfromation object, the third method returns a list of CaptureResponseInfromation objects.
Each CaptureResponseInfromation has the next methods:
- getMerchantInformation()
- getBillInformation()
Void Transaction
package transactions;
import java.io.IOException;
import java.io.InputStream;
import java.io.UnsupportedEncodingException;
import java.net.URL;
import org.apache.http.Header;
import org.apache.http.HttpResponse;
import org.apache.http.client.ClientProtocolException;
import org.apache.http.client.HttpClient;
import org.apache.http.client.methods.HttpPost;
import org.apache.http.entity.StringEntity;
import org.apache.http.impl.client.DefaultHttpClient;
import org.apache.http.params.HttpConnectionParams;
import org.apache.http.params.HttpParams;
import org.json.JSONException;
import org.json.JSONObject;
public class Void {
public static void RunVoid() {
try {
HttpClient client = new DefaultHttpClient();
HttpParams params = client.getParams();
HttpConnectionParams.setConnectionTimeout(params, 10000);
JSONObject jsonRequestObject = new JSONObject();
String url = "https://api.payhub.com/api/v2/void";
JSONObject merchant = new JSONObject();
merchant.put("organization_id", "10005"); //You put your org id here
merchant.put("terminal_id", "5");//You put your terminal id
jsonRequestObject.put("merchant", merchant);
jsonRequestObject.put("transaction_id", "223"); //You put the transaction id of the sale or refund you want to void
HttpPost postCreate = new HttpPost(url);
postCreate.addHeader("Authorization", "Bearer dfd4f12a-79af-4825-8dba-db27342c8491");//You put your token here
postCreate.addHeader("Content-Type", "application/json");
postCreate.addHeader("Accept", "application/json");
StringEntity se = new StringEntity(jsonRequestObject.toString());
postCreate.setEntity(se);
HttpResponse response = client.execute(postCreate); //You return this response and work with it
String json = " ";
JSONObject jsonResponseObject = null;
InputStream in = response.getEntity().getContent();
int cnt = 0;
while ((cnt = in.read()) > -1) {
json += (char) cnt;
}
if (json.charAt(0) != '<') {
jsonResponseObject = new JSONObject(
(json.equalsIgnoreCase("")
|| json.equalsIgnoreCase(" ") ? "{\"MESSAGE\":\"NO RESPONSE...\"}"
: json));
}
String result = response.getStatusLine().getReasonPhrase();
System.out.println(result);
if (result.equals("Created")){
Header[] headers = response.getAllHeaders();
for (Header header : headers) {
if (header.getName().equals("Location")){
URL location = new URL(header.getValue());
String path = location.getPath();
int lastSlash = path.lastIndexOf("/");
String transactionId = path.substring(lastSlash+1);
System.out.println("Transaction Id: " + transactionId );
}
}
}
else{
System.out.println(jsonResponseObject.toString());
}
} catch (JSONException e){
System.out.println(e.getMessage());
} catch (UnsupportedEncodingException e) {
System.out.println(e.getMessage());
} catch (ClientProtocolException e) {
System.out.println(e.getMessage());
} catch (IOException e) {
System.out.println(e.getMessage());
}
}
}
<?php
$trans_type = "void";
$processed = FALSE;
$ERROR_MESSAGE = '';
//Defining the Web Service URL
$WsURL="https://api.payhub.com/api/v2/$trans_type";
//Defining data for the VOID transaction
// Merchant data (obtained from the payHub Virtual Terminal (3rd party integration)
$organization_id = 10002;
$terminal_id = 2;
$oauth_token = "22fe3c69-db70-4a8c-9aed-9a33ebb1e9b4";
$transaction_id="83";
//Convert data to array to send it to the WS as JSON format
$data = array();
$data["merchant"] = array("organization_id" => "$organization_id", "terminal_id" => "$terminal_id");
$data["transaction_id"]=$transaction_id;
//Convert data from Array to JSON
$data_string = json_encode($data);
//Creating a CURL object to access the WS
$ch = curl_init();
//Setting the address to connect to
curl_setopt($ch, CURLOPT_URL, $WsURL);
//Setting HTTP method. For a new transaction we need to use POST
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
//Setting data in JSON format
curl_setopt($ch, CURLOPT_POSTFIELDS, $data_string);
//Setting the proper header.
//Setting the oauth_token to access the WS with the proper authorization
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
'Content-Type: application/json',
'Accept: application/json',
'Authorization: Bearer '.$oauth_token)
);
//Store the response as a variable and not showing the content as echo $variable
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
//Set to return the response header, this is to analyze the result and the transaction ID
curl_setopt($ch, CURLOPT_HEADER, true);
//execute connection to the Web Service
$response = curl_exec($ch);
// get some data from the response
$httpcode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
$header_size = curl_getinfo($ch, CURLINFO_HEADER_SIZE);
//Get the header as string.
$header = substr($response, 0, $header_size);
//close connection to the Web Service
curl_close($ch);
//Obtain the data from the void recently created
if ($httpcode==201){
//find the url of the void (Location header in the response)
preg_match("!\r\n(?:Location): *(.*?) *\r\n!", $header, $matches);
//$url contains the URL to GET the data from the Web Service
$url = $matches[1];
//Once we get the transaction ID we will query for the information of the last transaction
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
//Setting HTTP method. To get a transaction response we need to use GET
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "GET");
//Setting the proper header.
//Setting the oauth_token to access the WS with the proper authorization
curl_setopt($ch, CURLOPT_HTTPHEADER, array('Authorization: Bearer '.$oauth_token));
//Store the response as a variable and not showing the content as echo $variable
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
//execute connection to the Web Service
$response_json=curl_exec($ch);
//close connection to the Web Service
curl_close($ch);
//show result (standard JSON), parse it, process it, etc..
echo $response_json;
// now you could parse the json object to array if you preffer: $obj = json_decode($response_json);
$array = json_decode($response_json);
echo "<pre>";
print_r($array);
echo "</pre>";
}
//There was an error with the WS
else{
echo "Error creating the ".strtoupper($trans_type).": RESPONSE MESSAGE";
echo "<pre>";
echo $response;
echo "</pre>";
}
?>
using System;
using System.IO;
using System.Net;
using Newtonsoft.Json;
namespace PayHubSamples
{
public class Void
{
public static void RunVoid()
{
try
{
var request = (HttpWebRequest)WebRequest.Create("https://api.payhub.com/api/v2/void");
request.ContentType = "text/json";
request.Method = "POST";
var refund = new
{
merchant = new
{
organization_id = "10005",
terminal_id = "5",
},
transaction_id = "238"
};
string json = JsonConvert.SerializeObject(refund);
request.Headers.Add("Authorization", "Bearer dfd4f12a-79af-4825-8dba-db27342c8491");
request.ContentType = "application/json";
request.Accept = "application/json";
using (var streamWriter = new StreamWriter(request.GetRequestStream()))
{
streamWriter.Write(json);
streamWriter.Flush();
streamWriter.Close();
}
try
{
var response = (HttpWebResponse)request.GetResponse();//You return this response.
using (var reader = new StreamReader(response.GetResponseStream()))
{
string result = reader.ReadToEnd();
Console.WriteLine(response.StatusCode);//Created
for (int i = 0; i < response.Headers.Count; ++i)
{
if (response.Headers.Keys[i] == "Location")
{
string path = response.Headers[i];
int lastSlash = path.LastIndexOf("/");
string transactionId = path.Substring(lastSlash + 1);
Console.WriteLine("Transaction Id: " + transactionId);
}
}
}
}
catch (WebException wex)
{
if (wex.Response != null)
{
using (var errorResponse = (HttpWebResponse)wex.Response)//You return wex.Response instead
{
using (var reader = new StreamReader(errorResponse.GetResponseStream()))
{
string result = reader.ReadToEnd();
Console.WriteLine(result);
}
}
}
}
}
catch (IOException e)
{
Console.WriteLine(e);
}
}
}
}
require 'uri'
require 'net/http'
require 'json'
url = URI("https://api.payhub.com/api/v2/void")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Post.new(url)
request["content-type"] = 'application/json'
request["accept"] = 'application/json'
request["authorization"] = 'Bearer 2a5d6a73-d294-4fba-bfba-957a4948d4a3'
request["cache-control"] = 'no-cache'
merchant = {
"organization_id"=>10074,
"terminal_id"=>134
}
#transaction Id
transaction_id="114"
informationToSend = {"merchant"=>merchant,"transaction_id"=>transaction_id}
request.body = JSON.generate(informationToSend)
response = http.request(request)
puts response.read_body
{
"merchant": {
"organization_id": 10005,
"terminal_id": 5
},
"transaction_id": "114"
}
Introduction
Run a Void when you need to cancel a transaction (either a sale or a refund) that has not yet been settled and that has not already been voided. This will avoid the customer being charged any amount at all and will release the pending funds, given the issuer supports doing so.
Endpoint (URL to Call):
POST https://api.payhub.com/v2/api/void
Elements
merchant
| Key | Type | Value |
|---|---|---|
| organization_id | integer | The Organization Id of the Merchant. This must match the Organization Id of the Merchant that the passed Oauth Token is associated with. |
| terminal_id | integer | The Merchant’s Virtual Terminal Id for 3rd Party API. |
Transaction
| Key | Type | Value |
|---|---|---|
| transaction_id | string | The Transaction Id to be voided. |
Response
{
"version": 0,
"createdAt": "2015-05-14T07:34:16.552-07:00",
"lastModified": "2015-05-14T07:34:16.552-07:00",
"createdBy": "10127",
"lastModifiedBy": "10127",
"metaData": null,
"transaction_id": "181257",
"lastVoidResponse": {
"saleTransactionId": "181257",
"voidTransactionId": "181258",
"token": "9999000000001853"
},
"merchantOrganizationId": 10127,
"_links": {
"self": {
"href": "https://api.payhub.com/api/v2/void/181258"
},
"merchant": {
"href": "https://api.payhub.com/api/v2/void/181258/merchant"
}
}
}
Result
- A 201 code (created)
- The Id of the Void will be provided in the Location header that is returned. This is referred as the Transaction Id.
Sample header in the response:Location ? https:// [payhub-api-server]:8251/payhubws/api/void/5501b651da06a879ce520d4d.
If you do a GET request to this URL, you will get all the transaction information in JSON format.
On the same way you can query about merchant, customer, bill and card data details using the given URLs.
Note: You will need to use Oauth token in the header request for sales or any other transaction. For more information, see the
OAuth 2.0 Access Tokens section.
Extended Methods
Request Method
GET
Endpoints (URLs to Call)
GET https://api.payhub.com/api/v2/void/{id}
Use the Void Id in order to get the information of the Void response.
GET https://api.payhub.com/api/v2/void/{id}/merchant
Use the Void Id in order to get the merchant information of the Void response.
GET https://api.payhub.com/api/v2/void/
If the ID is not present, you will get a list with all the transactions.
By default, the list return only the first 20 resutls and it can be paged, you can modify this by adding the next parameters to the url:
page={pageNo}&size={size}
SDKs Methods
Each SDK has a transaction manager class with the next methods:
- Create a transaction: doVoid
- Get transaction information based on the transaction ID: getVoidInformation({transactionId})
- Get all the transactions performed under this method: getAllVoidInformation (optional parameters for page and size)
The first two methods returns a VoidResponseInformation object, the third method returns a list of VoidResponseInformation objects.
Each VoidResponseInformation has the next methods:
- getMerchantInformation()
Refund Transaction
package transactions;
import java.io.IOException;
import java.io.InputStream;
import java.io.UnsupportedEncodingException;
import java.net.URL;
import org.apache.http.Header;
import org.apache.http.HttpResponse;
import org.apache.http.client.ClientProtocolException;
import org.apache.http.client.HttpClient;
import org.apache.http.client.methods.HttpPost;
import org.apache.http.entity.StringEntity;
import org.apache.http.impl.client.DefaultHttpClient;
import org.apache.http.params.HttpConnectionParams;
import org.apache.http.params.HttpParams;
import org.json.JSONException;
import org.json.JSONObject;
public class Refund {
public static void RunRefund() {
try {
HttpClient client = new DefaultHttpClient();
HttpParams params = client.getParams();
HttpConnectionParams.setConnectionTimeout(params, 10000);
JSONObject jsonRequestObject = new JSONObject();
String url = "https://api.payhub.com/api/v2/refund";
JSONObject merchant = new JSONObject();
merchant.put("organization_id", "10005");//You put your org id here
merchant.put("terminal_id", "5");//You put your terminal id
jsonRequestObject.put("merchant", merchant);
jsonRequestObject.put("record_format", "CREDIT_CARD");
//optional
jsonRequestObject.put("transaction_id", "226");
//optional
JSONObject bill = new JSONObject();
JSONObject base_amount = new JSONObject();
base_amount.put("amount", "1275");//$12.75
bill.put("base_amount", base_amount);
JSONObject shipping_amount = new JSONObject();
shipping_amount.put("amount", "725");//$7.25
bill.put("shipping_amount", shipping_amount);
JSONObject tax_amount = new JSONObject();
tax_amount.put("amount", "113");//$1.13
bill.put("tax_amount", tax_amount);
bill.put("note", "Shipped as a gift");
bill.put("invoice_number", "4645782");
bill.put("po_number", "1234-654321");
jsonRequestObject.put("bill", bill);
//optional
JSONObject card_data = new JSONObject();
card_data.put("card_number", "5466410004374507");
card_data.put("card_expiry_date", "201809");// September 2018
card_data.put("billing_address_1", "237 E 33rd Street");
card_data.put("billing_address_2", "3rd Floor");
card_data.put("billing_city", "New York");
card_data.put("billing_zip", "10016");
card_data.put("billing_state", "NY");
card_data.put("cvv_data", "998");
card_data.put("cvv_code", "Y");
jsonRequestObject.put("card_data", card_data);
//optional
JSONObject customer = new JSONObject();
customer.put("first_name", "John");
customer.put("last_name", "Smith");
customer.put("company_name", "CBA Steakhouse");
customer.put("job_title", "Owner");
customer.put("email_address", "john@cbasteakhouse.com");
customer.put("web_address", "http://www.cbasteakhouse.com");
customer.put("phone_number", "(917) 479 1349");
customer.put("phone_ext", "5478");
customer.put("phone_type", "M");
jsonRequestObject.put("customer", customer);
HttpPost postCreate = new HttpPost(url);
postCreate.addHeader("Authorization", "Bearer dfd4f12a-79af-4825-8dba-db27342c8491");//You put your token here
postCreate.addHeader("Content-Type", "application/json");
postCreate.addHeader("Accept", "application/json");
StringEntity se = new StringEntity(jsonRequestObject.toString());
postCreate.setEntity(se);
HttpResponse response = client.execute(postCreate);//You return this response and work with it
String json = " ";
JSONObject jsonResponseObject = null;
InputStream in = response.getEntity().getContent();
int cnt = 0;
while ((cnt = in.read()) > -1) {
json += (char) cnt;
}
if (json.charAt(0) != '<') {
jsonResponseObject = new JSONObject(
(json.equalsIgnoreCase("")
|| json.equalsIgnoreCase(" ") ? "{\"MESSAGE\":\"NO RESPONSE...\"}"
: json));
}
String result = response.getStatusLine().getReasonPhrase();
System.out.println(result);
if (result.equals("Created")){
Header[] headers = response.getAllHeaders();
for (Header header : headers) {
if (header.getName().equals("Location")){
URL location = new URL(header.getValue());
String path = location.getPath();
int lastSlash = path.lastIndexOf("/");
String transactionId = path.substring(lastSlash+1);
System.out.println("Transaction Id: " + transactionId );
}
}
}
else{
System.out.println(jsonResponseObject.toString());
}
} catch (JSONException e){
System.out.println(e.getMessage());
} catch (UnsupportedEncodingException e) {
System.out.println(e.getMessage());
} catch (ClientProtocolException e) {
System.out.println(e.getMessage());
} catch (IOException e) {
System.out.println(e.getMessage());
}
}
}
<?php
$trans_type = "refund";
$processed = FALSE;
$ERROR_MESSAGE = '';
//Defining the Web Service URL
$WsURL="https://api.payhub.com/api/v2/$trans_type";
//Defining data for the REFUND transaction
// Merchant data (obtained from the payHub Virtual Terminal (3rd party integration)
$organization_id = 10002;
$terminal_id = 2;
$oauth_token = "22fe3c69-db70-4a8c-9aed-9a33ebb1e9b4";
//The rest of the data needed
$record_format="CREDIT_CARD";
$transaction_id="82";
//Convert data to array to send it to the WS as JSON format
$data = array();
$data["merchant"] = array("organization_id" => "$organization_id", "terminal_id" => "$terminal_id");
$data["record_format"]=$record_format;
//optional
$data["transaction_id"]=$transaction_id;
//optional
$data["bill"] = array ("base_amount" => array ("currency" => "USD","amount" => $base_amount),
"shipping_amount" => array ("currency" => "USD","amount" => $shipping_amount),
"tax_amount" => array ("currency" => "USD","amount" => $tax_amount));
//optional
$data["card_data"] = array("card_number" => "$card_number","card_expiry_date" => "$card_expiry_date",
"cvv_data" => "$cvv_data","billing_address_1" => "$billing_address_1",
"billing_address_2" => "$billing_address_2","billing_city" => "$billing_city",
"billing_state" => "$billing_state","billing_zip" => "$billing_zip");
//optional
$data ["customer"]= array("first_name" => "$first_name","last_name" => "$last_name","company_name" => "$company_name",
"job_title" => "$job_title","email_address" => "$email_address","web_address" => "$web_address",
"phone_number" => "$phone_number","phone_ext" => "$phone_ext","phone_type" => "$phone_type");
//Convert data from Array to JSON
$data_string = json_encode($data);
//Creating a CURL object to access the WS
$ch = curl_init();
//Setting the address to connect to
curl_setopt($ch, CURLOPT_URL, $WsURL);
//Setting HTTP method. For a new transaction we need to use POST
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
//Setting data in JSON format
curl_setopt($ch, CURLOPT_POSTFIELDS, $data_string);
//Setting the proper header.
//Setting the oauth_token to access the WS with the proper authorization
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
'Content-Type: application/json',
'Accept: application/json',
'Authorization: Bearer '.$oauth_token)
);
//Store the response as a variable and not showing the content as echo $variable
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
//Set to return the response header, this is to analyze the result and the transaction ID
curl_setopt($ch, CURLOPT_HEADER, true);
//execute connection to the Web Service
$response = curl_exec($ch);
// get some data from the response
$httpcode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
$header_size = curl_getinfo($ch, CURLINFO_HEADER_SIZE);
//Get the header as string.
$header = substr($response, 0, $header_size);
//close connection to the Web Service
curl_close($ch);
//Obtain the data from the refund recently created
if ($httpcode==201){
//find the url of the refund (Location header in the response)
preg_match("!\r\n(?:Location): *(.*?) *\r\n!", $header, $matches);
//$url contains the URL to GET the data from the Web Service
$url = $matches[1];
//Once we get the transaction ID we will query for the information of the last transaction
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
//Setting HTTP method. To get a transaction response we need to use GET
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "GET");
//Setting the proper header.
//Setting the oauth_token to access the WS with the proper authorization
curl_setopt($ch, CURLOPT_HTTPHEADER, array('Authorization: Bearer '.$oauth_token));
//Store the response as a variable and not showing the content as echo $variable
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
//execute connection to the Web Service
$response_json=curl_exec($ch);
//close connection to the Web Service
curl_close($ch);
//show result (standard JSON), parse it, process it, etc..
echo $response_json;
// now you could parse the json object to array if you preffer: $obj = json_decode($response_json);
$array = json_decode($response_json);
echo "<pre>";
print_r($array);
echo "</pre>";
}
//There was an error with the WS
else{
echo "Error creating the ".strtoupper($trans_type).": RESPONSE MESSAGE";
echo "<pre>";
echo $response;
echo "</pre>";
}
?>
using Newtonsoft.Json;
using System;
using System.IO;
using System.Net;
namespace PayHubSamples
{
public class Refund
{
public static void RunRefund()
{
try
{
var request = (HttpWebRequest)WebRequest.Create("https://api.payhub.com/api/v2/refund");
request.ContentType = "text/json";
request.Method = "POST";
var refund = new
{
merchant = new
{
organization_id = "10005",
terminal_id = "5",
},
record_format = "CREDIT_CARD",
transaction_id = "228",//optional
bill = new //optional
{
base_amount = new
{
amount = "1275" //$12.75
},
shipping_amount = new
{
amount = "725" //$7.25
},
tax_amount = new
{
amount = "113" //$1.13
},
note = "Shipped as a gift",
invoice_number = "4645782",
po_number = "1234-654321"
},
card_data = new //optional
{
card_number = "5466410004374507",
card_expiry_date = "201809", //September 2018
billing_address_1 = "237 E 33rd Street",
billing_address_2 = "3rd Floor",
billing_city = "New York",
billing_state = "NY",
billing_zip = "10016",
cvv_data = "998",
cvv_code = "Y"
},
customer = new //optional
{
first_name = "John",
last_name = "Smith",
company_name = "CBA Stakehouse",
job_title = "Owner",
email_address = "john@cbastakehouse.com",
web_address = "http://www.cbasteakhouse.com",
phone_number = "(917) 479 1349",
phone_ext = "5478",
phone_type = "M"
},
record_format = "CC"
};
string json = JsonConvert.SerializeObject(refund);
request.Headers.Add("Authorization", "Bearer dfd4f12a-79af-4825-8dba-db27342c8491");
request.ContentType = "application/json";
request.Accept = "application/json";
using (var streamWriter = new StreamWriter(request.GetRequestStream()))
{
streamWriter.Write(json);
streamWriter.Flush();
streamWriter.Close();
}
try
{
var response = (HttpWebResponse)request.GetResponse();//You return this response.
using (var reader = new StreamReader(response.GetResponseStream()))
{
string result = reader.ReadToEnd();
Console.WriteLine(response.StatusCode);//Created
for (int i = 0; i < response.Headers.Count; ++i)
{
if (response.Headers.Keys[i] == "Location")
{
string path = response.Headers[i];
int lastSlash = path.LastIndexOf("/");
string transactionId = path.Substring(lastSlash + 1);
Console.WriteLine("Transaction Id: " + transactionId);
}
}
}
}
catch (WebException wex)
{
if (wex.Response != null)
{
using (var errorResponse = (HttpWebResponse)wex.Response)//You return wex.Response instead
{
using (var reader = new StreamReader(errorResponse.GetResponseStream()))
{
string result = reader.ReadToEnd();
Console.WriteLine(result);
}
}
}
}
}
catch (IOException e)
{
Console.WriteLine(e);
}
}
}
}
{
"merchant": {
"organization_id": 10005,
"terminal_id": 5
},
"record_format": "CREDIT_CARD",
"transaction_id": "114",
"bill" : {
"base_amount" : {
"amount" : 0.30
},
"shipping_amount" : {
"amount" : 0.20
},
"tax_amount" : {
"amount" : 0.10
},
"note" : "This is a note.",
"invoice_number" : "This is an Invoice number.XXX",
"po_number" : "a test po number"
},
"card_data" : {
"card_number" : "5466410004374507",
"card_expiry_date" : "202011",
"billing_address_1" : "2350 Kerner Blvd",
"billing_address_2" : "",
"billing_city" : "San Rafael",
"billing_state" : "CA",
"billing_zip" : "99997-0003"
},
"customer" : {
"first_name" : "First",
"last_name" : "Contact",
"company_name" : "Payhub Inc",
"job_title" : "Software Engineer",
"email_address" : "test@payhub.com",
"web_address" : "http://payhub.com",
"phone_number" : "(415) 479 1349",
"phone_ext" : "123",
"phone_type" : "M"
}
}
require 'uri'
require 'net/http'
require 'json'
url = URI("https://api.payhub.com/api/v2/refund")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Post.new(url)
request["content-type"] = 'application/json'
request["accept"] = 'application/json'
request["authorization"] = 'Bearer 2a5d6a73-d294-4fba-bfba-957a4948d4a3'
request["cache-control"] = 'no-cache'
merchant = {
"organization_id"=>10074,
"terminal_id"=>134
}
#Record Format
record_format="CREDIT_CARD"
#transaction Id (optional)
transaction_id="114"
# bill data (optional)
bill= {
"base_amount"=>Hash["amount" =>"1.00"],
"shipping_amount"=>Hash["amount" =>"1.00"],
"tax_amount"=>Hash["amount" =>"1.00"],
"note"=>"this a sample note",
"invoice_number"=>"this is an invoice",
"po_number"=>"a test po number"
}
#Credit card data (optional)
card_data = {
"card_number"=>"4055011111111111",
"card_expiry_date"=>"202012",
"billing_address_1"=>"2350 Kerner Blvd",
"billing_address_2"=>"On the corner",
"billing_city"=>"San Rafael",
"billing_state"=>"CA",
"billing_zip"=>"99997-0003"
}
# Customer data (optional)
customer = {"first_name"=>"First",
"last_name"=>"Contact",
"company_name"=>"Payhub Inc",
"job_title"=>"Software Engineer",
"email_address"=>"jhon@company.com",
"web_address"=>"http://payhub.com",
"phone_number"=>"(415) 479 1349",
"phone_ext"=>"123",
"phone_type"=>"M"
}
informationToSend = {"merchant"=>merchant,"record_format"=>record_format,"transaction_id"=>transaction_id,"bill"=>bill,"customer"=>customer,"card_data"=>card_data}
request.body = JSON.generate(informationToSend)
response = http.request(request)
puts response.read_body
Introduction
This topic provides the information the Refund transaction.
Run the Refund transaction when you want to refund either the full amount or a partial amount of a sale. The refund amount it doesn’t needs to be the same as the total amount that was originally charged in the sale. The amount is refunded to the credit or debit card that was originally charged. Also, you can Refund amounts to your credit or debit card without enter the transaction id.
Request Method
Endpoint (URL to Call)
https://api.payhub.com/api/v2/refund
Elements
merchant (required)
| Element | Type | Value |
|---|---|---|
| organization_id | integer | The organization id of the merchant who did the sale that you are trying to refund. |
| terminal_id | integer | The terminal id of the merchant from where the sale is done. |
| record_format | string | To specify if the sale has to be made over a credit card, debit card or cash payment. The accepted values are:
|
Transaction (optional)
| Key | Type | Value |
|---|---|---|
| transaction_id | integer | The transaction id of the sale you want to refund. |
Note: you need the transaction_id if you want to refund a partial amount or the total ammount.If you want to refund an amount to your credit or debit card you don’t need the transaction Id at all.
Customer (required to create refunds that aren’t associated to existent transactions)
| Key | Type | Value |
|---|---|---|
| first_name | string | The first name of the customer. |
| last_name | string | The last name of the customer. |
| company_name | string, optional | The company name of the customer. |
| job_title | string, optional | The job title of the customer. |
| email_address | string, optional | The valid email address of the customer. The email address must be syntactically correct. If you do not specify the email address, you must provide a phone_number to identify the customer. |
| web_address | string, optional | The web address of the customer. The web address, if you specify, must be syntactically valid web address. |
| phone_number | string, optional | The phone number of the customer. The phone number must be syntactically correct. For example, (415) 234 5678, or 4152345678, or (415) 234-5678. If you do not specify the phone number, you must provide an email_address to identify the customer. |
| phone_ext | string, optional | The phone extension number of the customer. |
| phone_type | string, optional | The type ([‘H’ or 'W’ or ’M’]) of the phone number: H (Home), W (Work), M (Mobile). |
card_data (required to create refunds that aren’t associated to existent transactions)
| Key | Type | Value |
|---|---|---|
| tokenized_card | string, optional | This is the 16 character PayHub-specific tokenized string representing the card number. The value for the given customer and credit card can be obtained by examining the last Sale by accessing the link to the card data that was successfully created. It is safer (and recommended) for the third party client to store and use this string in any future requests for the same customer. |
| card_number | string, optional | This is the 16 character card number. The card number is not stored by the API in plain text. The response will contain a tokenized card number that should always be used in future requests, (for the same Customer) in place of this property. |
| track1_data | string, optional | This is the string read by the swiper (It contents track 1 data without sentinels). |
| track2_data | string, optional | This is the string read by the swiper (It contents track 2 data without sentinels). |
| encrypted_track _data | Optional |
|
| billing_address_1 | string, optional | The billing street address of the customer. |
| billing_address_2 | string, optional | The additional billing street address of the customer. |
| billing_city | string, optional | The billing city of the customer. |
| billing_state | string, optional | The billing state Code of the customer. For example, CA, WI, NY, etc. The sate codes should be for the states in the USA. |
| billing_zip | string, optional | The billing Zip Code of the customer. The zip code must be either 5 digits or 5 plus four separated by a ’-’. The zip code is required if the merchant has turned ON the AVS flag. |
| card_expiry_date | string | The card expiry date in the YYYYMM format. |
bill (required to create refunds with different ammounts, or to create new refunds that aren’t associated to existent transactions)
| Key | Type | Value |
|---|---|---|
| base_amount | TransactionAmount | The base amount of the recurring bill. The total amount charged will be the sum of this amount and (any) 'shipping_amount’ and 'tax_amount’. |
| shipping_amount | TransactionAmount, optional | The shipping amount for the transaction. This value will be included in the total amount charged. |
| tax_amount | TransactionAmount, optional | The tax amount for the transaction. This value will be included in the total amount charged. |
| invoice_number | string, optional | The invoice number for the transaction. |
| po_number | string, optional | The purchase order number for the transaction. |
| note | string, optional | A free format note for the transaction. The note will be read by the merchant. |
Note: One of the following fields must be present:
- tokenized_card
- card_number
- track1_data
- track2_data
- encrypted_track_data
Response
{
"version": 0,
"createdAt": "2015-05-15T13:16:27.466-07:00",
"lastModified": "2015-05-15T13:16:27.466-07:00",
"createdBy": "10127",
"lastModifiedBy": "10127",
"metaData": null,
"transaction_id": 181293,
"record_format": "CREDIT_CARD",
"lastRefundResponse": {
"saleTransactionId": "43063",//it will be empty if the refund is not associated to one transaction.
"refundTransactionId": "43064",
"token": null,
"approvalCode": " ",
"processedDateTime": null,
"avsResultCode": "0",
"verificationResultCode": "",
"batchId": "133",
"responseCode": "00",
"responseText": "OFFLINE APPROVAL",
"cisNote": "",
"riskStatusResponseText": "",
"riskStatusResponseCode": "",
"refundDateTime": "2016-01-20 17:46:36",
"customerReference": {
"customerId": 0,
"customerEmail": "",
"customerPhones": []
},
"billingReferences": {
"tokenizedCard": "9999000000001998",
"customerId": 0,
"customerCardId": 486,
"customerBillId": 1,
"cardObscured": "XXXXXXXXXXXX4507",
"cardType": "MasterCard"
}
},
"settlementStatus": "Not settled",
"merchantOrganizationId": 10127,
"_links": {
"self": {
"href": "https://api.payhub.com/api/v2/refund/181332"
},
"merchant": {
"href": "https://api.payhub.com/api/v2/refund/181332/merchant"
}
}
}
Result
- A 201 code (created)
- The Id of the Refund will be provided in the Location header that is returned. This is referred as the Transaction Id.
Sample header in the response:Location ? https:// [payhub-api-server]:8251/payhubws/api/refund/5501b651da06a879ce520d4d.
If you do a GET request to this URL, you will get all the transaction information in JSON format.
On the same way you can query about merchant, customer, bill and card data details using the given URLs.
Note: You will need to use Oauth token in the header request for sales or any other transaction. For more information, see the
OAuth 2.0 Access Tokens section.
Extended Methods
Request Method
GET
Endpoints (URLs to Call)
GET https://api.payhub.com/api/v2/refund/{id}
Use the Refund Id in order to get the information of the Refund response.
GET https://api.payhub.com/api/v2/refund/{id}/merchant
Use the Refund Id in order to get the merchant information of the Refund response.
GET https://api.payhub.com/api/v2/refund/
If the ID is not present, you will get a list with all the transactions.
By default, the list return only the first 20 resutls and it can be paged, you can modify this by adding the next parameters to the url:
page={pageNo}&size={size}
SDKs Methods
Each SDK has a transaction manager class with the next methods:
- Create a transaction: doRefund
- Get transaction information based on the transaction ID: getRefundInformation({refundId})
- Get all the transactions performed under this method: getAllRefundInformation (optional parameters for page and size)
The first two methods returns a RefundInformation object, the third method returns a list of RefundInformation objects.
Each RefundInformation has the next methods:
- getMerchantInformation()
Recurring Bill Transaction
package transactions;
import java.io.IOException;
import java.io.InputStream;
import java.io.UnsupportedEncodingException;
import java.net.URL;
import org.apache.http.Header;
import org.apache.http.HttpResponse;
import org.apache.http.client.ClientProtocolException;
import org.apache.http.client.HttpClient;
import org.apache.http.client.methods.HttpPost;
import org.apache.http.entity.StringEntity;
import org.apache.http.impl.client.DefaultHttpClient;
import org.apache.http.params.HttpConnectionParams;
import org.apache.http.params.HttpParams;
import org.json.JSONArray;
import org.json.JSONException;
import org.json.JSONObject;
public class RecurringBill {
public static void CreateRecurringBill() {
try {
HttpClient client = new DefaultHttpClient();
HttpParams params = client.getParams();
HttpConnectionParams.setConnectionTimeout(params, 10000);
JSONObject jsonRequestObject = new JSONObject();
String url = "https://api.payhub.com/api/v2/recurring-bill";
JSONObject merchant = new JSONObject();
merchant.put("organization_id", "10005");//You put your org id here
merchant.put("terminal_id", "5");//You put your terminal id
jsonRequestObject.put("merchant", merchant);
JSONObject bill = new JSONObject();
JSONObject base_amount = new JSONObject();
base_amount.put("amount", "1275");//$12.75
bill.put("base_amount", base_amount);
JSONObject shipping_amount = new JSONObject();
shipping_amount.put("amount", "725");//$7.25
bill.put("shipping_amount", shipping_amount);
JSONObject tax_amount = new JSONObject();
tax_amount.put("amount", "113");//$1.13
bill.put("tax_amount", tax_amount);
bill.put("note", "Shipped as a gift");
bill.put("invoice_number", "4645782");
bill.put("po_number", "1234-654321");
jsonRequestObject.put("bill", bill);
JSONObject card_data = new JSONObject();
card_data.put("card_number", "5466410004374507");
card_data.put("card_expiry_date", "201809");// September 2018
card_data.put("billing_address_1", "237 E 33rd Street");
card_data.put("billing_address_2", "3rd Floor");
card_data.put("billing_zip", "10016");
card_data.put("billing_city", "New York");
card_data.put("billing_state", "NY");
jsonRequestObject.put("card_data", card_data);
JSONObject customer = new JSONObject();
customer.put("first_name", "John");
customer.put("last_name", "Smith");
customer.put("company_name", "CBA Steakhouse");
customer.put("job_title", "Owner");
customer.put("email_address", "john@cbasteakhouse.com");
customer.put("phone_number", "(917) 479 1349");
customer.put("phone_ext", "5478");
customer.put("phone_type", "M");
jsonRequestObject.put("customer", customer);
JSONObject schedule = new JSONObject();
schedule.put("schedule_type", "S");
JSONObject specific_dates_schedule = new JSONObject();
JSONArray specific_dates = new JSONArray();
specific_dates.put(0,"2016-02-01");
specific_dates.put(1,"2016-10-31");
specific_dates_schedule.put("specific_dates", specific_dates);
schedule.put("specific_dates_schedule", specific_dates_schedule);
jsonRequestObject.put("schedule", schedule);
HttpPost postCreate = new HttpPost(url);
postCreate.addHeader("Authorization", "Bearer dfd4f12a-79af-4825-8dba-db27342c8491");//You put your token here
postCreate.addHeader("Content-Type", "application/json");
postCreate.addHeader("Accept", "application/json");
StringEntity se = new StringEntity(jsonRequestObject.toString());
postCreate.setEntity(se);
HttpResponse response = client.execute(postCreate);//You return this response and work with it
String json = " ";
JSONObject jsonResponseObject = null;
InputStream in = response.getEntity().getContent();
int cnt = 0;
while ((cnt = in.read()) > -1) {
json += (char) cnt;
}
if (json.charAt(0) != '<') {
jsonResponseObject = new JSONObject(
(json.equalsIgnoreCase("")
|| json.equalsIgnoreCase(" ") ? "{\"MESSAGE\":\"NO RESPONSE...\"}"
: json));
}
String result = response.getStatusLine().getReasonPhrase();
System.out.println(result);
if (result.equals("Created")){
Header[] headers = response.getAllHeaders();
for (Header header : headers) {
if (header.getName().equals("Location")){
URL location = new URL(header.getValue());
String path = location.getPath();
int lastSlash = path.lastIndexOf("/");
String transactionId = path.substring(lastSlash+1);
System.out.println("Recurring Bill Id: " + transactionId ); //Last resource of the path
}
}
}
else{
System.out.println(jsonResponseObject.toString());
}
} catch (JSONException e){
System.out.println(e.getMessage());
} catch (UnsupportedEncodingException e) {
System.out.println(e.getMessage());
} catch (ClientProtocolException e) {
System.out.println(e.getMessage());
} catch (IOException e) {
System.out.println(e.getMessage());
}
}
}
<?php
$processed = FALSE;
$ERROR_MESSAGE = '';
//Defining the Web Service URL
$WsURL="https://api.payhub.com/api/v2/$trans_type";
//Defining data for the RECURRING BILL transaction
// Merchant data (obtained from the payHub Virtual Terminal (3rd party integration)
$organization_id = 10002;
$terminal_id = 2;
$oauth_token = "22fe3c69-db70-4a8c-9aed-9a33ebb1e9b4";
// bill data
$base_amount = 10.0;
$shipping_amount = 1.23;
$tax_amount = 1.00;
$note = "this a sample note";
$invoice_number = "a-00240";
$po_number = "56";
//Credit card data
$card_number = "5466410004374507";
$card_expiry_date = "202011";
$cvv_data = "998";
$billing_address_1 = "2350 Kerner Blvd";
$billing_address_2 = "On the corner";
$billing_city = "San Rafael";
$billing_state = "CA";
$billing_zip = "94901";
// Customer data
$first_name = "First";
$last_name = "Contact";
$company_name = "Payhub Inc";
$job_title = "Software Engineer";
$email_address = "jhon@company.com";
$web_address = "https://payhub.com";
$phone_number = "(415) 479 1349";
$phone_ext = "123";
$phone_type = "M";
// Schedule data
$schedule_type = "M";
$bill_generation_interval="1";
//Schedule - schedule_start_and_end (object)
$start_date="2015-06-01";
$end_date_type="A";
$end_after_bill_count="6";
//Schedule - monthly_schedule (object)
$monthly_type="E";
//This is an array, put the elements separated by ","
$monthly_each_days="1";
//Convert data to array to send it to the WS as JSON format
$data = array();
$data["merchant"] = array("organization_id" => "$organization_id", "terminal_id" => "$terminal_id");
$data["bill"] = array ("base_amount" => array ("currency" => "USD","amount" => $base_amount),
"shipping_amount" => array ("currency" => "USD","amount" => $shipping_amount),
"tax_amount" => array ("currency" => "USD","amount" => $tax_amount));
$data["card_data"] = array("card_number" => "$card_number","card_expiry_date" => "$card_expiry_date",
"cvv_data" => "$cvv_data","billing_address_1" => "$billing_address_1",
"billing_address_2" => "$billing_address_2","billing_city" => "$billing_city",
"billing_state" => "$billing_state","billing_zip" => "$billing_zip");
$data["customer"]= array("first_name" => "$first_name","last_name" => "$last_name","company_name" => "$company_name",
"job_title" => "$job_title","email_address" => "$email_address","web_address" => "$web_address",
"phone_number" => "$phone_number","phone_ext" => "$phone_ext","phone_type" => "$phone_type");
$data["schedule"] = array("schedule_type" => $schedule_type, "bill_generation_interval" => $bill_generation_interval,
"schedule_start_and_end" => array ("start_date" => $start_date, "end_date_type" => $end_date_type, "end_after_bill_count" => $end_after_bill_count),
"monthly_schedule" => array ("monthly_type" => $monthly_type));
$data["schedule"]["monthly_schedule"]["monthly_each_days"]=explode(",",$monthly_each_days);
//Convert data from Array to JSON
echo $data_string = json_encode($data);
//Creating a CURL object to access the WS
$ch = curl_init();
//Setting the address to connect to
curl_setopt($ch, CURLOPT_URL, $WsURL);
//Setting HTTP method. For a new transaction we need to use POST
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
//Setting data in JSON format
curl_setopt($ch, CURLOPT_POSTFIELDS, $data_string);
//Setting the proper header.
//Setting the oauth_token to access the WS with the proper authorization
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
'Content-Type: application/json',
'Accept: application/json',
'Authorization: Bearer '.$oauth_token)
);
//Store the response as a variable and not showing the content as echo $variable
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
//Set to return the response header, this is to analyze the result and the transaction ID
curl_setopt($ch, CURLOPT_HEADER, true);
//execute connection to the Web Service
$response = curl_exec($ch);
// get some data from the response
$httpcode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
$header_size = curl_getinfo($ch, CURLINFO_HEADER_SIZE);
//Get the header as string.
$header = substr($response, 0, $header_size);
//close connection to the Web Service
curl_close($ch);
//Obtain the data from the recurring bill recently created
if ($httpcode==201){
//find the url of the recurring bill (Location header in the response)
preg_match("!\r\n(?:Location): *(.*?) *\r\n!", $header, $matches);
//$url contains the URL to GET the data from the Web Service
$url = $matches[1];
//Once we get the transaction ID we will query for the information of the last transaction
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
//Setting HTTP method. To get a transaction response we need to use GET
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "GET");
//Setting the proper header.
//Setting the oauth_token to access the WS with the proper authorization
curl_setopt($ch, CURLOPT_HTTPHEADER, array('Authorization: Bearer '.$oauth_token));
//Store the response as a variable and not showing the content as echo $variable
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
//execute connection to the Web Service
$response_json=curl_exec($ch);
//close connection to the Web Service
curl_close($ch);
//show result (standard JSON), parse it, process it, etc..
echo $response_json;
// now you could parse the json object to array if you preffer: $obj = json_decode($response_json);
$array = json_decode($response_json);
echo "<pre>";
print_r($array);
echo "</pre>";
}
//There was an error with the WS
else{
echo "Error creating the ".strtoupper($trans_type).": RESPONSE MESSAGE";
echo "<pre>";
echo $response;
echo "</pre>";
}
?>
using Newtonsoft.Json;
using System;
using System.IO;
using System.Net;
namespace PayHubSamples
{
public class RecurringBilling
{
public static void CreateRecurringBilling()
{
try
{
var request = (HttpWebRequest)WebRequest.Create("https://api.payhub.com/api/v2/recurring-bill");
request.ContentType = "text/json";
request.Method = "POST";
var recurringBill = new
{
merchant = new
{
organization_id = "10005",
terminal_id = "5",
},
bill = new
{
base_amount = new
{
amount = "1275" //$12.75
},
shipping_amount = new
{
amount = "725" //$7.25
},
tax_amount = new
{
amount = "113" //$1.13
},
note = "Shipped as a gift",
invoice_number = "4645782",
po_number = "1234-654321"
},
card_data = new
{
card_number = "5466410004374507",
card_expiry_date = "201809", //September 2018
billing_address_1 = "237 E 33rd Street",
billing_address_2 = "3rd Floor",
billing_city = "New York",
billing_state = "NY",
billing_zip = "10016"
},
customer = new
{
first_name = "John",
last_name = "Smith",
company_name = "CBA Stakehouse",
job_title = "Owner",
email_address = "john@cbastakehouse.com",
web_address = "http://www.cbasteakhouse.com",
phone_number = "(917) 479 1349",
phone_ext = "5478",
phone_type = "M"
},
schedule = new
{
schedule_type = "S",
specific_dates_schedule = new
{
specific_dates = new[]
{
"2016-02-01",
"2016-10-31"
}
}
}
};
string json = JsonConvert.SerializeObject(recurringBill);
request.Headers.Add("Authorization", "Bearer dfd4f12a-79af-4825-8dba-db27342c8491");
request.ContentType = "application/json";
request.Accept = "application/json";
using (var streamWriter = new StreamWriter(request.GetRequestStream()))
{
streamWriter.Write(json);
streamWriter.Flush();
streamWriter.Close();
}
try
{
var response = (HttpWebResponse)request.GetResponse();//You return this response.
using (var reader = new StreamReader(response.GetResponseStream()))
{
Console.WriteLine(response.StatusCode);//Created
for (int i = 0; i < response.Headers.Count; ++i)
{
if (response.Headers.Keys[i] == "Location")
{
string path = response.Headers[i];
int lastSlash = path.LastIndexOf("/");
string transactionId = path.Substring(lastSlash + 1);
Console.WriteLine("Recurring Billing Id: " + transactionId);
}
}
}
}
catch (WebException wex)
{
if (wex.Response != null)
{
using (var errorResponse = (HttpWebResponse)wex.Response)//You return wex.Response instead
{
using (var reader = new StreamReader(errorResponse.GetResponseStream()))
{
string result = reader.ReadToEnd();
Console.WriteLine(result);
}
}
}
}
}
catch (IOException e)
{
Console.WriteLine(e);
}
}
}
}
{
"merchant": {
"organization_id": 10005,
"terminal_id": 5
},
"bill": {
"base_amount": {
"amount": 72.34
},
"shipping_amount": {
"amount": 3.87
},
"tax_amount": {
"amount": 7.23
},
"note": "Gym stuff monthly delivered.",
"invoice_number": "FF7845742ARG",
"po_number": "What is a PO number?"
},
"card_data": {
"card_number": "4055011111111111",
"card_expiry_date": "201709",
"billing_address_1": "154 E 34th St",
"billing_address_2": "Fifth Floor",
"billing_city": "New York",
"billing_state": "NY",
"billing_zip": "10016"
},
"customer": {
"first_name": "Adam",
"last_name": "Smith",
"company_name": "Capital Inc",
"job_title": "President",
"email_address": "adam@smith.com",
"web_address": "http://capitalinc.com",
"phone_number": "(917) 479 1349",
"phone_ext": "5702",
"phone_type": "W"
},
"schedule": {
"schedule_type": "S",
"specific_dates_schedule": {
"specific_dates": [
"2015-10-01",
"2016-09-30"
]
}
}
}
require 'uri'
require 'net/http'
require 'json'
url = URI("https://api.payhub.com/api/v2/authonly")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Post.new(url)
request["content-type"] = 'application/json'
request["accept"] = 'application/json'
request["authorization"] = 'Bearer 2a5d6a73-d294-4fba-bfba-957a4948d4a3'
request["cache-control"] = 'no-cache'
merchant = {
"organization_id"=>10074,
"terminal_id"=>134
}
# bill data
bill= {
"base_amount"=>Hash["amount" =>"1.00"],
"shipping_amount"=>Hash["amount" =>"1.00"],
"tax_amount"=>Hash["amount" =>"1.00"],
"note"=>"this a sample note",
"invoice_number"=>"this is an invoice",
"po_number"=>"a test po number"
}
#Credit card data
card_data = {
"card_number"=>"4055011111111111",
"card_expiry_date"=>"202012",
"cvv_data"=>"999",
"billing_address_1"=>"2350 Kerner Blvd",
"billing_address_2"=>"On the corner",
"billing_city"=>"San Rafael",
"billing_state"=>"CA",
"billing_zip"=>"99997-0003"
}
# Customer data
customer = {
"first_name"=>"First",
"last_name"=>"Contact",
"company_name"=>"Payhub Inc",
"job_title"=>"Software Engineer",
"email_address"=>"jhon@company.com",
"web_address"=>"http://payhub.com",
"phone_number"=>"(415) 479 1349",
"phone_ext"=>"123",
"phone_type"=>"M"
}
informationToSend = {"merchant"=>merchant,"bill"=>bill,"customer"=>customer,"card_data"=>card_data}
request.body = JSON.generate(informationToSend)
response = http.request(request)
puts response.read_body
Introduction
This topic provides information about the Recurring Bill transaction.
Use the recurring billing transaction when you want to periodically charge certain amount to the customer. You can use this feature for subscriptions or for any ongoing product or service you offer. You can setup a recurring billing by calling our RESTful API through an HTTP post containing a JSON.
Request Method
POST
Endpoint (URL to Call)
https://api.payhub.com/api/v2/recurring-bill
Elements
RecurringBillInput
| Key | Type | Value |
|---|---|---|
| customer | CustomerInput | Customer detail. |
| card_data | CardDataInput | Card data to use in the bill. |
| merchant | MerchantInput | Merchant detail. |
| bill | BillInput | Bill-related data to use in the recurring bill. |
| schedule | ScheduleInput | Schedule detail. |
| metaData | MetaData, optional | A client-specific arbitrary (but valid) JSON string to represent data in the client’s domain that can be associated with this entity. |
CustomerInput
| Key | Type | Value |
|---|---|---|
| first_name | string | The first name of the customer. |
| last_name | string | The last name of the customer. |
| company_name | string, optional | The company name of the customer. |
| job_title | string, optional | The job title of the customer. |
| email_address | string, optional | The email address of the customer. The email address must be syntactically correct. If email address is not specified, you must provide a phone_number to identify the customer. |
| web_address | string, optional | The web address of the customer. The web address if specified, must be a syntactically valid web address. |
| phone_number | string, optional | The phone number of the customer. The phone number must be syntactically correct. For example: (415) 234 5678, or 4152345678, or (415) 234-5678. If phone number is not specified, you must provide an email_address to identify the customer. |
| phone_ext | string, optional | The phone extension number of the customer. |
| phone_type | string, optional | The type of the phone number: [‘H’ or 'W’ or ’M’]: H (Home), W (Work), M (Mobile). |
| metaData | MetaData, optional | A client-specific arbitrary (but valid) JSON string to represent data in the client’s domain that can be associated with this entity. |
MetaData
No parameters
CardDataInput
| Key | Type | Value |
|---|---|---|
| card_expiry_date | string | The card expiry date in YYYYMM format. |
| tokenized_card | string, optional | This is a 16 character PayHub-specific tokenized string representing the card number. The value for the given customer and credit card can be obtained by examining the lastRecurringBillResponse.billingReferences.tokenizedCard by accessing the link to the bill that was successfully created. It is safer (and recommended) for the third party client to store and use this string in any future requests for the same customer. This value is required if the 'card_number’ property is not present in the request. |
| card_number | string, optional | This is a 16 character card number. This value is required if the 'tokenized_card’ property is not present in the request. Note: The card number is not stored by the API in plain text - the response will contain a tokenized card number that should always be used in future requests, (for the same Customer) in place of this property. |
| billing_address_1 | string, optional | The billing street address of the customer. |
| billing_address_2 | string, optional | The additional billing street address of the customer. |
| billing_city | string, optional | The billing city of the customer. |
| billing_state | string, optional | The billing state Code of the customer. The codes are for the states in the USA. For example, CA, WI, NY, etc. |
| billing_zip | string, optional | The billing zip code of the customer. The codes are for the states in the USA. The code must be either 5 digits or 5 plus four separated by a ’-’. This value is required if the Merchant has the AVS flag turned on. |
| metaData | MetaData, optional | A client-specific arbitrary (but valid) JSON string to represent the data in the client’s domain, which can be associated with this entity. |
MerchantInput
| Key | Type | Value |
|---|---|---|
| organization_id | integer | The organization Id (['range[0-]’]) of the merchant. This Id must match the organization Id of the merchant that the passed Oauth Token is associated with. |
| terminal_id | integer | The Virtual Terminal Id (['range[0-]’]) for 3rd Party API of the merchant. |
| metaData | MetaData, optional | A client-specific arbitrary (but valid) JSON string to represent data in the client’s domain that can be associated with this entity. |
BillInput
| Key | Type | Value |
|---|---|---|
| tax_amount | TransactionAmount, optional | The tax amount for the transaction. This value will be included in the total amount charged. |
| po_number | string, optional | The purchase order number for the transaction. |
| base_amount | TransactionAmount | The Base amount of the recurring bill. The total amount charged will be the sum of this amount and (any) 'shipping_amount’ and 'tax_amount’. |
| shipping_amount | TransactionAmount, optional | The shipping amount for the transaction. This will be included in the total amount charged. |
| invoice_number | string, optional | The invoice number for the transaction. |
| note | string, optional | A free format note for the transaction. The note will be read by the Merchant. |
| metaData | MetaData, optional | A client-specific arbitrary (but valid) JSON string to represent data in the client’s domain, which can be associated with this entity. |
TransactionAmount
| Key | Type | Value |
|---|---|---|
| amount | Number | The amount expressed as a decimal number with at most two decimal places (example: 1.23), |
| currency | string, optional | The ISO 4217 currency code for this amount. ['USD’]: Currently only 'USD’ is accepted. |
ScheduleInput
| Key | Type | Value |
|---|---|---|
| specific_dates_schedule | SpecificDatesSchedule, optional | Required if the schedule_type is ’S’ (='Specific Dates’). |
| weekly_schedule | WeeklySchedule, optional | Required if the schedule_type is 'W’ (='Weekly’). |
| schedule_type | string | The type of schedule being set up, [’M’ or ’D’ or 'Y’ or 'W’ or ’S’]: ’M’ (='Monthly’), ’D’ (='Daily’), 'Y’ (='Yearly’), 'W’ (='Weekly’), S=Specific Dates. |
| bill_generation_interval | integer, optional | The interval between bills where the unit is dependent on the value of the schedule_type (example: if the schedule_type is 'W’ and this field is 3, the bill will recur every three weeks). Applicable to schedule_typeof ’M’ (='Monthly’), ’D’ (='Daily’), 'Y’ (='Yearly’), and 'W’ (='Weekly’). |
| monthly_schedule | MonthlySchedule, optional | Required if the schedule_type is ’M’ (='Monthly’). |
| schedule_start_and_end | ScheduleStartAndEnd, optional | Required if the schedule_type is not ’S’ ( not 'Specific Dates’). |
| yearly_schedule | YearlySchedule, optional | Required if the schedule_type is 'Y’ (='Yearly’). |
| metaData | MetaData, optional | A client-specific arbitrary (but valid) JSON string to represent data in the client’s domain that can be associated with this entity. |
SpecificDatesSchedule
| Key | Type | Value |
|---|---|---|
| specific_dates | array[string] | An array of specific dates on which the bill should recur. The dates should be in the YYYY-MM-DD format. There must be at least one date specified and all dates must be later than today’s date. |
WeeklySchedule
| Key | Type | Value |
|---|---|---|
| weekly_bill_days | array[string] | The day(s) of week on which the weekly bill recurs. The array must have at least one entry and each entry must be the first three characters of the day name, as in 'SUN’, and 'SAT’. |
MonthlySchedule
| Key | Type | Value |
|---|---|---|
| monthly_type | string | ['O’ or 'E’]: Determines the day(s) of the month on which the bill will recur. Valid values are 'O’ (='On the’ - also specify monthly_on_the_day_of_week_in_month and the monthly_day_of_week) and 'E’ (='Each’ - also specify monthly_each_days). |
| monthly_each_days | array[integer], optional | An array of integers that must have at least one entry and each entry must be in the range between 1 and 32 where a '1’ means 'first day of month’, a '2’ means 'second day of month and so on. An entry of '32’ means 'last day of month’. This value is applicable to monthly_type of 'E’ (='Each’). |
| monthly_on_the_day_of_week_in_month | integer, optional | A value (['range[1-5]’]) of 1 means 'first of month’, 2 means 'second of month’ and so on, with a value of 5 meaning 'last of month’. Must be specified in combination with monthly_day_of_week which supplies the day of week (Monday, Tuesday, etc.) that this applies to. This value is applicable to monthly_type of 'O’ (='On the’). |
| monthly_day_of_week | integer, optional | The day of week (['range[1-7]’]) on which the bill recurs, where 1 is Sunday and 7 is Saturday. The value must be specified in combination with monthly_on_the_day_of_week_in_month which supplies the 'position’ (First, Second, etc.) of the day in the month (First Monday, Second Friday, Last Saturday, etc.). This value is applicable to monthly_type of 'O’ (='On the’). |
ScheduleStartAndEnd
| Key | Type | Value |
|---|---|---|
| start_date | string, optional | The date to start the schedule in YYYY-MM-DD format. The value is required if the schedule_type is ’M’ (='Monthly’), ’D’ (='Daily’), or 'W’ (='Weekly’). |
| end_date | string, optional | The date to end the schedule in YYYY-MM-DD format. The value is applicable to end_date_type equal to 'O’ (='End On date’). |
| end_date_type | string, optional | Determines the date on which the schedule ends. The values (['N’ or ’ A’ or ’ O’]:) can be 'N’ (='Never’), 'A’ (='After a number of bills’ - you must also specify a end_after_bill_count), or 'O’ (='On or no later than a specific date’ - you must also specify a end_date). If not present, then 'N’ (='Never’) is assumed. |
| end_after_bill_count | integer, optional | The number of bills before ending the schedule. Applicable to end_date_type equal to 'A’ (='After a number of bills’). |
YearlySchedule
| Key | Type | Value |
|---|---|---|
| year_to_start | string | The year (in YYYY format) in which the schedule starts. You must also specify yearly_bill_on_month_number and yearly_bill_on_day_of_month. |
| yearly_bill_on_day_of_month | integer | The month number ( ['range[1-12]’]) on which the bill will recur, where 1 is January and 12 is December. Must be specified in combination with year_to_start and yearly_bill_on_day_of_month. |
| yearly_bill_on_day_of_month | string | The day of the month (['range[1-31]’]) on which the yearly bill will recur, where 1 is the 1st, 2 is the 2nd, etc. If you specify a day of month that is invalid for the month specified by yearly_bill_on_month_number, then the last day of the month is used. Must be specified in combination with year_to_start and yearly_bill_on_month_number. |
Response Messages
| Code | Meaning | Sample code |
|---|---|---|
| 200 | (not returned) | ResourceSupport { links (array[Link], optional) } Link { templated (boolean, optional), rel (string, optional), href (string, optional) } |
| 201 | The recurring bill was created - use the link in the response’s 'Location’ Header to view the Recurring Bill. | Void {} |
| 400 | Bad request due to incorrect or invalid data passed. | RestErrorStructure { errors ( array[RestError], optional)} RestError { status ( string, optional) = ['100' or '101' or '102' or '103' or '200' or '201' or '202' or '203' or '204' or '205' or '206' or '207' or '208' or '226' or '300' or '301' or '302' or '302' or '303' or '304' or '305' or '307' or '308' or '400' or '401' or '402' or '403' or '404' or '405' or '406' or '407' or '408' or '409' or '410' or '411' or '412' or '413' or '414' or '415' or '416' or '417' or '418' or '419' or '420' or '421' or '422' or '423' or '424' or '426' or '428' or '429' or '431' or '500' or '501' or '502' or '503' or '504' or '505' or '506' or '507' or '508' or '509' or '510' or '511']: The Http Status Code, code ( string, optional), location ( string, optional), reason ( string, optional), severity ( string, optional) } |
| 401 | Unauthorized. You do not have permission to perform this operation. Make sure you entered a valid API Key at the top of the page. | Void {} |
| 403 | Forbidden. The server does not permit you to use this URI. | Void {} |
| 500 | Internal server error due to encoding the data, or to a PayHub server failure. Contact PayHub. | Void {} |
Extended Methods
Request Method
GET
Endpoints (URLs to Call)
GET https://api.payhub.com/api/v2/recurring-bill/{id}
Use the Recurring Bill Id in order to get the information of the Recurring Bill response.
GET https://api.payhub.com/api/v2/recurring-bill/{id}/merchant
Use the Recurring Bill Id in order to get the merchant information of the Recurring Bill response.
GET https://api.payhub.com/api/v2/recurring-bill/{id}/customer
Use the Recurring Bill Id in order to get the customer information of the Recurring Bill response.
GET https://api.payhub.com/api/v2/recurring-bill/{id}/bill
Use the Recurring Bill Id in order to get the bill information of the Recurring Bill response.
GET https://api.payhub.com/api/v2/recurring-bill/{id}/card_data
Use the Recurring Bill Id in order to get the card data of the Recurring Bill response. (The information on this method is reduced by security policies)
GET https://api.payhub.com/api/v2/recurring-bill/{id}/schedule
Use the Recurring Bill Id in order to get the schedule of the Recurring Bill response. (The information on this method is reduced by security policies)
GET https://api.payhub.com/api/v2/recurring-bill/{id}/status
Use the Recurring Bill Id in order to get the status of the Recurring Bill response. (The information on this method is reduced by security policies)
GET https://api.payhub.com/api/v2/recurring-bill/
If the ID is not present, you will get a list with all the transactions.
By default, the list return only the first 20 resutls and it can be paged, you can modify this by adding the next parameters to the url:
page={pageNo}&size={size}
Request Method
PATCH
Endpoint (URL to Call)
https://api.payhub.com/api/v2/recurring-bill/{id}
By using this method, you are able to update the bill information, card_data information, or schedule information of one specific recurring bill. Elements described Recurring Bill Elements section.
SDKs Methods
Each SDK has a transaction manager class with the next methods:
- Create a Recurring Bill Transaction: doRecurringBill
- Update a Recurring Bill Transaction: updateRecurringBill({recurringBillId})
- Update the Status of one Recurring Bill Transaction: updateRecurringBillStatus({recurringBillId,{String:newRecurringBillStatus})
- Get transaction information based on the transaction ID: getRecurringBillInformation({recurringBillId})
- Get all the transactions performed under this method: getAllRecurringBillInformation (optional parameters for page and size)
The first method returns a RecurringBillInformation object, the second and third methods, returns a boolean value if the process was successful or not (TRUE or FALSE), the fourth method returns a list of RecurringBillInformation objects.
Each RecurringBillInformation has the next methods:
- getMerchantInformation()
- getBillInformation()
- getCardDataInformation()
- getCustomerInformation()
- getScheduleInformation()
- getStatusInformation()
Recurring Bill Status
Introduction
This topic provides the information about the Recurring Bill Status API. Use the Recurring Billing Status API to change the status of any recurring bill.
In order to get the current Recurring Bill Status, use the method described in the Extended Methods of the Recurring Bill Section above.
Request Method
PATCH
Endpoint (URL to Call)
https://api.payhub.com/api/v2/recurring-bill-status/{id}
Elements
RecurringBillStatusInput
| Key | Type | Value |
|---|---|---|
| recurring_bill_status | string | The status of the recurring bill: [‘ACTIVE’ or 'PAUSED’ or 'COMPLETED’ or 'CANCELED’ or 'DELINQUENT’ or 'UNKNOWN’]. The possible values to change to are:
|
{
"recurring_bill_status": "CANCELED"
}
Response Messages
| Code | Meaning | Sample code |
|---|---|---|
| 200 | (not returned) | ResourceSupport { links (array[Link], optional) } Link { templated (boolean, optional), rel (string, optional), href (string, optional) } |
| 204 | The recurring bill status was successfully updated. | Void {} |
| 400 | Bad request due to incorrect or invalid data passed. | RestErrorStructure { errors ( array[RestError], optional)} RestError { status ( string, optional) = ['100' or '101' or '102' or '103' or '200' or '201' or '202' or '203' or '204' or '205' or '206' or '207' or '208' or '226' or '300' or '301' or '302' or '302' or '303' or '304' or '305' or '307' or '308' or '400' or '401' or '402' or '403' or '404' or '405' or '406' or '407' or '408' or '409' or '410' or '411' or '412' or '413' or '414' or '415' or '416' or '417' or '418' or '419' or '420' or '421' or '422' or '423' or '424' or '426' or '428' or '429' or '431' or '500' or '501' or '502' or '503' or '504' or '505' or '506' or '507' or '508' or '509' or '510' or '511']: The Http Status Code, code ( string, optional), location ( string, optional), reason ( string, optional), severity ( string, optional) } |
| 401 | Unauthorized. You do not have permission to perform this operation. Make sure you entered a valid API Key at the top of the page. | Void {} |
| 403 | Forbidden. The server does not permit you to use this URI. | Void {} |
| 500 | Internal server error due to encoding the data, or to a PayHub server failure. Contact PayHub. | Void {} |
SDKs Method
Each SDK has a transaction manager class with the next method:
- Update the Status of one Recurring Bill Transaction: updateRecurringBillStatus({recurringBillId},{String:newRecurringBillStatus})
This method returns a boolean value if the process was successful or not (TRUE or FALSE).
Administration Configuration
Introduction
Now, with our API, you can see and modify your administration settings.
- General Settings.
- Validated Devices.
- Webhook Configuration.
- Risk and Fraud Settings.
- User Roles.
{
"terminalList": [
{
"nickName": "Terminal 1 - 3rd Party AP",
"terminalType": "3rd Party API",
"settlementTime": "11:59 PM"
},
{
"nickName": "Terminal 2 - VirtualHub",
"terminalType": "Virtual Terminal",
"settlementTime": "11:59 PM"
}
],
"inactivityHour": "60"
}
General Settings Methods
1. get General Settings
Request Method
GET
Endpoint (URL to Call)
GET https://api.payhub.com/api/v2/adminSettings/generalSettings
SDKs method:
Each SDK has a transaction manager class with the next method:
- getGeneralSettings()
Result:
You will get the list of all the terminals that you have associated to your account. Note: You will need to use the Oauth token in the header request. For more information, see the OAUTH section.
GET METHOD:
{
"enforce_device_validation": "false",
"devices": [
{
"product": "VT",
"nick_name": "FIRST VALIDATED DEVICE",
"platform": "Mac Firefox 34.0",
"details": "63188494329184fc2e373f656a44f0570bd6a384",
"date_added": "2015-01-13",
"device_id": 177
}
]
}
PATCH METHOD
{
"enforce_device_validation": "false"
}
Validated Devices Methods
1. Get Validated Devices
Request Method
GET
Endpoint (URL to Call)
GET https://api.payhub.com/api/v2/adminSettings/validatedDevices
SDKs method:
Each SDK has a transaction manager class with the next method:
- getValidatedDevices()
Result
You will get the list of all the devices that were associated to your account. Note: You will need to use the Oauth token in the header request. For more information, see the OAUTH section.
2. Patch Validated Devices
Request Method
PATCH
Endpoint (URL to Call)
PATCH https://api.payhub.com/api/v2/adminSettings/validatedDevices
Parameters
| Key | Type | Value |
|---|---|---|
| enforce_device_validation | Boolean | Device Validation is an enhanced security feature that allows you to reasonably control the devices that are allowed to access your PayHub account. Turning device validation ON will require users to enter a validation code when they try to access your account on a new device. The validation code is sent to the administrator’s email address. Turning device validation OFF will allow any device to access your account. |
SDKs method:
Each SDK has a transaction manager class with the next method:
- updateValidatedDevices()
Result
- A 201 code (created) Note: You will need to use the Oauth token in the header request. For more information, see the OAUTH section.
GET METHOD:
{
"webhookConfiguration": {
"virtualHub": false,
"endPoint": "https://yoursite/yourcontroller/",
"batchIsActive": true,
"api": true,
"webhookActive": false,
"recurringBill": true,
"mobileHub": false
}
}
PATCH METHOD
{
"virtualHub": true,
"endPoint": "https://yoursite/yourcontroller/",
"batchIsActive": true,
"api": true,
"webhookActive": true,
"recurringBill": true,
"mobileHub": true
}
Webhook Configuration
1. Get Webhook Configuration
Request Method
GET
Endpoint (URL to Call)
GET https://api.payhub.com/api/v2/adminSettings/webhookConfiguration
SDKs method:
Each SDK has a transaction manager class with the next method:
- getWebhookConfiguration()
Result
You will get the Webhook Configuration that was associated to your account. Note: You will need to use the Oauth token in the header request. For more information, see the OAUTH section.
2. Patch Webhook Configuration
Request Method
PATCH
Endpoint (URL to Call)
PATCH https://api.payhub.com/api/v2/adminSettings/webhookConfiguration
Parameters
| Key | Type | Value |
|---|---|---|
| webhookActive | Boolean | Set it to True/False to enable/disable the notifications |
| virtualHub | Boolean | Set it to True/False to enable/disable the notifications for transactions that are coming from your Virtual Terminal |
| endPoint | String | Your EndPoint for receive our notifications |
| batchIsActive | Boolean | Set it to True/False to enable/disable the notifications for Batches |
| api | Boolean | Set it to True/False to enable/disable the notifications for transactions that are coming from your API |
| recurringBill | Boolean | Set it to True/False to enable/disable the notifications for transactions that are coming from your Recurring bills |
| mobileHub | Boolean | Set it to True/False to enable/disable the notifications for transactions that are coming from your Mobile Hub |
SDKs method:
Each SDK has a transaction manager class with the next method:
- updateWebhookConfiguration()
Result
- A 201 code (created) Note: You will need to use the Oauth token in the header request. For more information, see the OAUTH section.
GET METHOD:
{
"customRBReport": true,
"emailTrnReceipt": true,
"emailExpPsw": true,
"emailRbSuccessTransaction": true,
"emailBatchSuccess": true,
"pdfOrCsvForRB": "0",
"customBatchReport": true,
"pdfOrCsvForBatch": "0",
"emailBatchFail": true,
"emailRbFailTransaction": true
}
PATCH METHOD:
{
"customRBReport": false,
"emailTrnReceipt": true,
"emailExpPsw": false,
"emailRbSuccessTransaction": true,
"emailBatchSuccess": true,
"pdfOrCsvForRB": "1",
"customBatchReport": false,
"pdfOrCsvForBatch": "1",
"emailBatchFail": true,
"emailRbFailTransaction": true
}
Email Configuration
1. Get Email Configuration
Request Method
GET
Endpoint (URL to Call)
GET https://api.payhub.com/api/v2/adminSettings/emailConfiguration
SDKs method:
Each SDK has a transaction manager class with the next method:
- getEmailConfiguration()
Result
You will get the Email Configuration that is associated to your account. Note: You will need to use the Oauth token in the header request. For more information, see the OAUTH section.
2. Patch Email Configuration
Request Method
PATCH
Endpoint (URL to Call)
PATCH https://api.payhub.com/api/v2/adminSettings/emailConfiguration
Parameters
| Key | Type | Value |
|---|---|---|
| customRBReport | Boolean | Set it to True/False to enable/disable the Custom Reports for Recurring Bills via email |
| pdfOrCsvForRB | String | Set it to “0” (zero - PDF) or 1 (one - XLS). This is the format for the Custom Recurring Billing Report |
| customBatchReport | Boolean | Set it to True/False to enable/disable the Custom Batch Report via email |
| pdfOrCsvForBatch | String | Set it to “0” (zero - PDF) or 1 (one - xls). This is the format for the Custom Batch Report |
| emailTrnReceipt | Boolean | Set it to True/False to enable/disable the notifications for transactions via email |
| emailExpPsw | Boolean | Set it to True/False to enable/disable the notification for password expiration on your account via email |
| emailRbSuccessTransaction | Boolean | Set it to True/False to enable/disable the email notifications for successful Recurring Bill transactions |
| emailRbFailTransaction | Boolean | Set it to True/False to enable/disable the email notifications for failed Recurring Bill transactions |
| emailBatchSuccess | Boolean | Set it to True/False to enable/disable the email notifications for settled batches |
| emailBatchFail | Boolean | Set it to True/False to enable/disable the email notifications for unsettled batches |
SDKs method:
Each SDK has a transaction manager class with the next method:
- updateEmailConfiguration()
Result
- A 201 code (created) Note: You will need to use the Oauth token in the header request. For more information, see the OAUTH section.
GET METHOD:
{
"transaction_volume_settings": {
"checked": false,
"hours_trn_number_more_than": {
"value": "20",
"option": 1
},
"days_trn_amount_more_than": {
"value": "$20.00",
"option": 1
},
"sale_trn_amount_below": {
"value": "$20.00",
"option": 1
},
"days_trn_number_more_than": {
"value": "40",
"option": 1
},
"refund_trn_amount_above": {
"value": "$20.00",
"option": 1
},
"refund_trn_amount_below": {
"value": "$20.00",
"option": 1
},
"sale_trn_amount_above": {
"value": "$20.00",
"option": 1
}
},
"card_filtering": {
"checked": false
},
"credit_card_security_codes": {
"checked": false,
"cvv_mismatch": {
"value": "$20.00",
"option": 1
}
},
"email": {
"checked": false,
"email_address": "agustinbreit@gmail.com"
},
"address_verification_system": {
"checked": false,
"avs_mismatch_street_and_zip_code": {
"value": "$20.00",
"option": 1
},
"avs_mismatch_street": {
"value": "$20.00",
"option": 1
},
"avs_mismatch_zip_code": {
"value": "$20.00",
"option": 1
}
}
}
PATCH METHOD
{
"transaction_volume_settings": {
"checked": "false",
"refund_trn_amount_below": {
"value": "10",
"option": "1"
},
"hours_trn_number_more_than": {
"value": "10",
"option": "1"
},
"days_trn_amount_more_than": {
"value": "10",
"option": "1"
},
"sale_trn_amount_below": {
"value": "10",
"option": "1"
},
"refund_trn_amount_above": {
"value": "10",
"option": "1"
},
"days_trn_number_more_than": {
"value": "10",
"option": "1"
},
"sale_trn_amount_above": {
"value": "10",
"option": "1"
}
},
"card_filtering": {
"checked": "true"
},
"credit_card_security_codes": {
"cvv_mismatch": {
"value": "10",
"option": "1"
},
"checked": "true"
},
"email": {
"checked": "true",
"email_address": "agustinbreit@gmail.com"
},
"address_verification_system": {
"checked": "true",
"avs_mismatch_street_and_zip_code": {
"value": "10",
"option": "1"
},
"avs_mismatch_street": {
"value": "10",
"option": "1"
},
"avs_mismatch_zip_code": {
"value": "10",
"option": "1"
}
}
}
Risk and Fraud Settings
1. Get Risk and Fraud Settings
Request Method
GET
Endpoint (URL to Call)
GET https://api.payhub.com/api/v2/adminSettings/riskFraudDetection
SDKs method:
Each SDK has a transaction manager class with the next method:
- getRiskFraudSettings()
Result
You will get the Risk and Fraud Settings that are associated to your account. Note: You will need to use the Oauth token in the header request. For more information, see the OAUTH section.
2. Patch Risk and Fraud Settings
Request Method
PATCH
Endpoint (URL to Call)
PATCH https://api.payhub.com/api/v2/adminSettings/riskFraudDetection
Parameters
| Key | Type | Value |
|---|---|---|
| checked | Boolean | Set it to True/False to enable/disable the “Copy the following email addresses on Risk/Fraud notifications” option |
| email_address | String | Valid email address for Risk/Fraud notifications |
Transaction Volume Settings
| Key | Type | Value |
|---|---|---|
| sale_trn_amount_below | Node | Set values for “When a sales transaction amount is below” |
| sale_trn_amount_above | Node | Set values for “When a sales transaction amount is above” |
| refund_trn_amount_below | Node | Set values for “When a refund transaction amount is below” |
| refund_trn_amount_above | Node | Set values for “When a sales transaction amount is above” |
| days_trn_amount_more_than | Node | Set values for “When the day’s transactions amount to more than” |
| hours_trn_number_more_than | Node | Set values for “When the hour’s transactions number more than” |
| days_trn_number_more_than | Node | Set values for “WWhen the day’s transactions number more than” |
Card filtering
| Key | Type | Value |
|---|---|---|
| checked | Boolean | Set it to True/False to enable/disable the “Require a matching authorization code for offline transactions (made in the last 30 days).” option |
Credit Card Security Codes
| Key | Type | Value |
|---|---|---|
| checked | Boolean | Set it to True/False to enable/disable the “Require a CVV/CCV/CID when processing manually entered (non swiped) transactions.” option |
| cvv_mismatch | Node | Set values for “Minimum Threshold” |
Address Verification System (AVS)
| Key | Type | Value |
|---|---|---|
| checked | Boolean | Set it to True/False to enable/disable the “Require an address when processing manually entered (non swiped) transactions.” option |
| avs_mismatch_street_and_zip_code | Node | Set values for “Mismatched Street Address and Zip Code” |
| avs_mismatch_street | Node | Set values for “Mismatched Street Address” |
| avs_mismatch_zip_code | Node | Set values for “Mismatched Zip Code” |
Options and Values for each node
Note: for each node described above these two options are required.
| Key | Type | Value |
|---|---|---|
| option | String | Posible Values are: 1, 2, and 3
|
| value | String | Amount |
SDKs method:
Each SDK has a transaction manager class with the next method:
- updateRiskFraudSettings()
Result
- A 201 code (created) Note: You will need to use the Oauth token in the header request. For more information, see the OAUTH section.
GET METHOD:
{
"transactions": {
"checked": "false",
"transactionOptions": {
"viewHostedShop": "false",
"viewSubmitBatch": "false",
"single": {
"singleOptions": {
"voidupto": "false",
"sales": "false",
"refund": "false",
"viewTransaction": "false"
},
"checked": "false"
},
"recurringBills": {
"recurringBillOptions": {
"viewHostedShop": "false",
"edit": "false",
"delete": "false",
"add": "false"
},
"checked": "false"
},
"currentBatches": "false",
"txtRefundupto": "0.01",
"allBatches": "false"
}
},
"reports": {
"reportOptions": {
"standard": {
"standardOptions": {
"product": "false",
"recurrbill": "false",
"users": "false",
"transaction": "false",
"batch": "false",
"customer": "false"
},
"checked": "false"
},
"custom": "false"
},
"checked": "false"
},
"help": {
"helpOptions": {
"tickets": {
"ticketsOptions": {
"edit": "false",
"add": "false"
},
"checked": "false"
}
},
"checked": "false"
},
"mobileVTAcces": {
"checked": "false"
},
"admin": {
"adminOptions": {
"product": {
"checked": "false",
"productOptions": {
"edit": "false",
"delete": "false",
"bulkUpload": "false",
"add": "false"
}
},
"users": {
"usersOptions": {
"deleteRole": "false",
"manageRole": "false",
"editRole": "false",
"edit": "false",
"delete": "false",
"addRole": "false",
"add": "false",
"usersEditAdmin": "false"
},
"checked": "false"
},
"hostedShopCart": "false",
"riskAndFraud": {
"riskAndFraudOptions": {
"riskfraudSetting": "false",
"riskfraudFlagTrn": "false"
},
"checked": "false"
},
"webposSetUp": "false",
"general": {
"generalOptions": {
"validateDev": "false",
"thirdParyApi": "false",
"shippingTax": "false",
"branding": "false",
"generalSetting": "false"
},
"checked": "false"
}
},
"checked": "false"
},
"customer": {
"customerOptions": {
"edit": "false",
"delete": "false",
"view": "false,
"add": "false"
},
"checked": "false"
},
"firstDefaultScreen": "2",
"webPosAccess": {
"checked": "false",
"webPosAccessOptions": {
"admin": {
"adminOptions": {
"hotKey": "false",
"submitBatch": "2",
"deviceList": "false",
"generalSettings": "false",
"tills": "false",
"display": "false",
"customPrompt": "false",
"customMessage": "false"
},
"checked": "false"
},
"quitPos": "false",
"manualPriceChange": "false"
}
},
"roleName": "test4"
}
PATCH AND POST METHODS (the same json structure is used)
{
"transactions": {
"checked": "true",
"transactionOptions": {
"viewHostedShop": "true",
"viewSubmitBatch": "true",
"single": {
"singleOptions": {
"voidupto": "true",
"sales": "true",
"refund": "true",
"viewTransaction": "true"
},
"checked": "true"
},
"recurringBills": {
"recurringBillOptions": {
"viewHostedShop": "true",
"edit": "true",
"delete": "true",
"add": "true"
},
"checked": "true"
},
"currentBatches": "true",
"txtRefundupto": "0.01",
"allBatches": "true"
}
},
"reports": {
"reportOptions": {
"standard": {
"standardOptions": {
"product": "true",
"recurrbill": "true",
"users": "true",
"transaction": "true",
"batch": "true",
"customer": "true"
},
"checked": "true"
},
"custom": "true"
},
"checked": "true"
},
"help": {
"helpOptions": {
"tickets": {
"ticketsOptions": {
"edit": "true",
"add": "true"
},
"checked": "true"
}
},
"checked": "true"
},
"mobileVTAcces": {
"checked": "true"
},
"admin": {
"adminOptions": {
"product": {
"checked": "true",
"productOptions": {
"edit": "true",
"delete": "true",
"bulkUpload": "true",
"add": "true"
}
},
"users": {
"usersOptions": {
"deleteRole": "true",
"manageRole": "true",
"editRole": "true",
"edit": "true",
"delete": "true",
"addRole": "true",
"add": "true",
"usersEditAdmin": "true"
},
"checked": "true"
},
"hostedShopCart": "false",
"riskAndFraud": {
"riskAndFraudOptions": {
"riskfraudSetting": "true",
"riskfraudFlagTrn": "true"
},
"checked": "true"
},
"webposSetUp": "true",
"general": {
"generalOptions": {
"validateDev": "true",
"thirdParyApi": "true",
"shippingTax": "true",
"branding": "true",
"generalSetting": "true"
},
"checked": "true"
}
},
"checked": "true"
},
"customer": {
"customerOptions": {
"edit": "true",
"delete": "true",
"view": "true,
"add": "true"
},
"checked": "true"
},
"firstDefaultScreen": "2",
"webPosAccess": {
"checked": "true",
"webPosAccessOptions": {
"admin": {
"adminOptions": {
"hotKey": "true",
"submitBatch": "2",
"deviceList": "true",
"generalSettings": "true",
"tills": "true",
"display": "true",
"customPrompt": "true",
"customMessage": "true"
},
"checked": "true"
},
"quitPos": "true",
"manualPriceChange": "true"
}
},
"roleName": "test4"
}
Role Settings
1. Get All user roles
Request Method
GET
Endpoint (URL to Call)
GET https://api.payhub.com/api/v2/userRole/roles
SDKs method:
Each SDK has a transaction manager class with the next method:
- getUserRoles()
Result
You will get the list of the rol names that are associated to your account. Note: You will need to use the Oauth token in the header request. For more information, see the OAUTH section.
2. Get user role by Id
Request Method
GET
Endpoint (URL to Call)
GET https://api.payhub.com/api/v2/userRole/roles/{id}
SDKs method:
Each SDK has a transaction manager class with the next method:
- getUserRolesById()
Result
You will get all the settings for that particular role. Note: You will need to use the Oauth token in the header request. For more information, see the OAUTH section.
3. Patch User Roles
Request Method
PATCH
Endpoint (URL to Call)
PATCH https://api.payhub.com/api/v2/userRole/roles/update/{id}
General Structure
| Key | Type | Value |
|---|---|---|
| roleName | String | the role name |
| firstDefaultScreen | Numeric String | The first default screen that will be showed after you login Allowed values are: 1,2, and 3
|
| transactions | NODE | Json Node that allows you to set permissions related to transactions |
| reports | NODE | Json Node that allows you to set permissions related to reports |
| help | NODE | Json Node that allows you to set permissions related to help options and tickets |
| mobileVTAcces | NODE | Json Node that allows you to set permissions related to you mobile vt access |
| admin | NODE | Json Node that allows you to set permissions related to other administration settings |
| customer | NODE | Json Node that allows you to set permissions related to customers |
| webPosAccess | NODE | Json Node that allows you to set permissions related to your webposs access |
Parameters
transactions
| Key | Type | Value |
|---|---|---|
| checked | Boolean | Set it to True/False |
| transactionOptions | NODE | Json Node Described above |
transactionOptions Node
| Key | Type | Value |
|---|---|---|
| viewHostedShop | Boolean | Set it to True/False |
| viewSubmitBatch | Boolean | Set it to True/False |
| currentBatches | Boolean | Set it to True/False |
| allBatches | Boolean | Set it to True/False |
| txtRefundupto | Numeric String | Enter a numeric value for this option, any other String will not be accepted |
| single | NODE | Json Node Described above |
| recurringBills | NODE | Json Node Described above |
Single Node
| Key | Type | Value |
|---|---|---|
| checked | Boolean | Set it to True/False |
| singleOptions | NODE | Json Node Described above |
Single Options Node
| Key | Type | Value |
|---|---|---|
| voidupto | Boolean | Set it to True/False |
| sales | Boolean | Set it to True/False |
| refund | Boolean | Set it to True/False |
| viewTransaction | Boolean | Set it to True/False |
RecurringBills Node
| Key | Type | Value |
|---|---|---|
| checked | Boolean | Set it to True/False |
| recurringBillOptions | NODE | Json Node Described above |
RecurringBills Options Node
| Key | Type | Value |
|---|---|---|
| viewHostedShop | Boolean | Set it to True/False |
| edit | Boolean | Set it to True/False |
| delete | Boolean | Set it to True/False |
| add | Boolean | Set it to True/False |
Reports
| Key | Type | Value |
|---|---|---|
| checked | Boolean | Set it to True/False |
| reportOptions | NODE | Json Node Described above |
Reports Options Node
| Key | Type | Value |
|---|---|---|
| checked | Boolean | Set it to True/False |
| custom | Boolean | Set it to True/False |
| standard | NODE | Json Node Described above |
Standard Node
| Key | Type | Value |
|---|---|---|
| checked | Boolean | Set it to True/False |
| standardOptions | NODE | Json Node Described above |
Standard Options Node
| Key | Type | Value |
|---|---|---|
| product | Boolean | Set it to True/False |
| recurrbill | Boolean | Set it to True/False |
| users | Boolean | Set it to True/False |
| transaction | Boolean | Set it to True/False |
| batch | Boolean | Set it to True/False |
| customer | Boolean | Set it to True/False |
MobileVT Access
| Key | Type | Value |
|---|---|---|
| checked | Boolean | Set it to True/False |
Help
| Key | Type | Value |
|---|---|---|
| checked | Boolean | Set it to True/False |
| helpOptions | NODE | Json Node Described above |
Help Options Node
| Key | Type | Value |
|---|---|---|
| tickets | NODE | Json Node Described above |
Tickets Node
| Key | Type | Value |
|---|---|---|
| checked | Boolean | Set it to True/False |
| ticketsOptions | NODE | Json Node Described above |
Tickets Options Node
| Key | Type | Value |
|---|---|---|
| edit | Boolean | Set it to True/False |
| add | Boolean | Set it to True/False |
Admin Settings
| Key | Type | Value |
|---|---|---|
| checked | Boolean | Set it to True/False |
| adminOptions | NODE | Json Node Described above |
Admin Options Node
| Key | Type | Value |
|---|---|---|
| product | NODE | Json Node Described above |
| users | NODE | Json Node Described above |
| hostedShopCart | Boolean | Set it to True/False |
| riskAndFraud | NODE | Json Node Described above |
| webposSetUp | Boolean | Set it to True/False |
| general | NODE | Json Node Described above |
Product Node
| Key | Type | Value |
|---|---|---|
| checked | Boolean | Set it to True/False |
| productOptions | NODE | Json Node Described above |
Product Options Node
| Key | Type | Value |
|---|---|---|
| edit | Boolean | Set it to True/False |
| delete | Boolean | Set it to True/False |
| bulkUpload | Boolean | Set it to True/False |
| add | Boolean | Set it to True/False |
Users Node
| Key | Type | Value |
|---|---|---|
| checked | Boolean | Set it to True/False |
| usersOptions | NODE | Json Node Described above |
User Options Node
| Key | Type | Value |
|---|---|---|
| deleteRole | Boolean | Set it to True/False |
| manageRole | Boolean | Set it to True/False |
| editRole | Boolean | Set it to True/False |
| addRole | Boolean | Set it to True/False |
| edit | Boolean | Set it to True/False |
| delete | Boolean | Set it to True/False |
| add | Boolean | Set it to True/False |
| usersEditAdmin | Boolean | Set it to True/False |
Risk and Fraud Node
| Key | Type | Value |
|---|---|---|
| checked | Boolean | Set it to True/False |
| riskAndFraudOptions | NODE | Json Node Described above |
Risk and Fraud Options
| Key | Type | Value |
|---|---|---|
| riskfraudSetting | Boolean | Set it to True/False |
| riskfraudFlagTrn | Boolean | Set it to True/False |
General Node
| Key | Type | Value |
|---|---|---|
| checked | Boolean | Set it to True/False |
| generalOptions | NODE | Json Node Described above |
General Options node
| Key | Type | Value |
|---|---|---|
| validateDev | Boolean | Set it to True/False |
| thirdParyApi | Boolean | Set it to True/False |
| shippingTax | Boolean | Set it to True/False |
| branding | Boolean | Set it to True/False |
| generalSetting | Boolean | Set it to True/False |
Customer Node
| Key | Type | Value |
|---|---|---|
| checked | Boolean | Set it to True/False |
| customerOptions | NODE | Json Node Described above |
Customer Options node
| Key | Type | Value |
|---|---|---|
| edit | Boolean | Set it to True/False |
| delete | Boolean | Set it to True/False |
| view | Boolean | Set it to True/False |
| add | Boolean | Set it to True/False |
WebPos Access Node
| Key | Type | Value |
|---|---|---|
| checked | Boolean | Set it to True/False |
| webPosAccessOptions | NODE | Json Node Described above |
WebPos Access Options node
| Key | Type | Value |
|---|---|---|
| admin | NODE | Json Node Described above |
| quitPos | Boolean | Set it to True/False |
| manualPriceChange | Boolean | Set it to True/False |
| add | Boolean | Set it to True/False |
Admin Node
| Key | Type | Value |
|---|---|---|
| checked | Boolean | Set it to True/False |
| adminOptions | NODE | Json Node Described above |
Admin Options node
| Key | Type | Value |
|---|---|---|
| hotKey | Boolean | Set it to True/False |
| submitBatch | Boolean | Set it to True/False |
| deviceList | Boolean | Set it to True/False |
| generalSettings | Boolean | Set it to True/False |
| tills | Boolean | Set it to True/False |
| display | Boolean | Set it to True/False |
| customPrompt | Boolean | Set it to True/False |
| customMessage | Boolean | Set it to True/False |
SDKs method:
Each SDK has a transaction manager class with the next method:
- updateRoleSettings()
Result
- A 201 code (created)
Note: You will need to use Oauth token in the header request. For more information, see the
OAuth 2.0 Access Tokens section. ### 4. Create User Roles
Request Method
POST
Endpoint (URL to Call)
POST https://api.payhub.com/api/v2/userRole/roles/create
SDKs method:
Each SDK has a transaction manager class with the next method:
- createRoleSettings()
Result
- A 201 code (created)
Note: You will need to use Oauth token in the header request. For more information, see the
OAuth 2.0 Access Tokens section.
Customers
Linking Customers
PayHub automatically identifies customers that have processed with the merchant before then associates the transaction or recurring billing schedule with the corresponding customer. This relationship is used when reporting on merchants and processing new transactions so you can reference the customerID instead of providing the full customer details. Then processing new transaction the email address is checked first for customer accounts, so that any transaction run which includes an email address will be associated with the existing account that uses that email address, or if none exists, it will create a new customer account based on that email address and associate the transaction with this account. PayHub uses the phone number as the secondary key for customer accounts, so that any transaction in which a phone number was included AND NO email address was provided, the transaction will be associated with the existing account that uses that phone number, or if none exists, it will create a new customer account based on that phone number and associate the transaction with this account. When both an email address and a phone number are present the system will use the email address to determine which account to associate the transaction with using the logic described above.
Transaction Report
package transactions;
import java.io.IOException;
import java.io.InputStream;
import java.io.UnsupportedEncodingException;
import java.net.URL;
import org.apache.http.Header;
import org.apache.http.HttpResponse;
import org.apache.http.client.ClientProtocolException;
import org.apache.http.client.HttpClient;
import org.apache.http.client.methods.HttpPost;
import org.apache.http.entity.StringEntity;
import org.apache.http.impl.client.DefaultHttpClient;
import org.apache.http.params.HttpConnectionParams;
import org.apache.http.params.HttpParams;
import org.json.JSONException;
import org.json.JSONObject;
public class Transactions {
public static void findTransactions() {
try {
HttpClient client = new DefaultHttpClient();
HttpParams params = client.getParams();
HttpConnectionParams.setConnectionTimeout(params, 10000);
JSONObject jsonRequestObject = new JSONObject();
String url = "https://api.payhub.com/api/v2/report/transactionReport";
jsonRequestObject.put("batchIdFrom", "5");
jsonRequestObject.put("batchIdTo", "10");
jsonRequestObject.put("transactionType", "Sale");
jsonRequestObject.put("responseCode", "00");
jsonRequestObject.put("amountFrom", "1");
jsonRequestObject.put("amountTo", "2");
jsonRequestObject.put("firstName", "First");
jsonRequestObject.put("lastName", "Contact");
jsonRequestObject.put("phoneNumber", "(415) 479 1349");
jsonRequestObject.put("email", "jhon@company.com");
jsonRequestObject.put("trnDateFrom", "2015-06-06 00:00:00");
jsonRequestObject.put("trnDateTo", "2015-07-07 23:59:59");
jsonRequestObject.put("cardType", "Visa");
HttpPost postCreate = new HttpPost(url);
postCreate.addHeader("Authorization", "Bearer dfd4f12a-79af-4825-8dba-db27342c8491");//You put your token here
postCreate.addHeader("Content-Type", "application/json");
postCreate.addHeader("Accept", "application/json");
StringEntity se = new StringEntity(jsonRequestObject.toString());
postCreate.setEntity(se);
HttpResponse response = client.execute(postCreate); //You return this response and work with it
String json = " ";
JSONObject jsonResponseObject = null;
int statusCode = responseDataRequest.getResponseCode();
InputStream in = response.getEntity().getContent();
if (statusCode >= 200 && statusCode < 400) {
BufferedReader in = new BufferedReader(new InputStreamReader(responseDataRequest.getInputStream()));
String line;
while ((line = in.readLine()) != null){
response.append(line);
}
in.close();
System.out.println(response.toString());
}else{
BufferedReader er = new BufferedReader(new InputStreamReader(responseDataRequest.getErrorStream()));
String line;
try {
int c = 0;
while((c = er.read()) != -1) {
response.append((char)c);
}
} catch (IOException e) {
// TODO Auto-generated catch block
e.printStackTrace();
}
System.out.println(response.toString());
}
} catch (JSONException e){
System.out.println(e.getMessage());
} catch (UnsupportedEncodingException e) {
System.out.println(e.getMessage());
} catch (ClientProtocolException e) {
System.out.println(e.getMessage());
} catch (IOException e) {
System.out.println(e.getMessage());
}
}
}
<?php
$processed = FALSE;
$ERROR_MESSAGE = '';
//Defining the Web Service URL
$WsURL="https://api.payhub.com/api/v2/report/transactionReport";
$batchIdFrom= "5";
$batchIdTo= "10";
$transactionType= "Sale";
$responseCode= "00";
$amountFrom= "1";
$amountTo= "2";
$firstName= "First";
$lastName= "Contact";
$phoneNumber= "(415) 479 1349";
$email= "jhon@company.com";
$trnDateFrom= "2015-06-06 00:00:00";
$trnDateTo= "2015-07-07 23:59:59";
$cardType= "Visa";
//Convert data to array to send it to the WS as JSON format
$data = array();
$data= array("batchIdFrom" => "$batchIdFrom", "batchIdTo" => "$batchIdTo",
"transactionType" => "$transactionType", "responseCode" => "$responseCode",
"amountFrom" => "$amountFrom", "amountTo" => "$amountTo",
"firstName" => "$firstName", "lastName" => "$lastName",
"phoneNumber" => "$phoneNumber", "email" => "$email",
"trnDateFrom" => "$trnDateFrom", "trnDateTo" => "$trnDateTo","cardType"=>"$cardType");
//Convert data from Array to JSON
$data_string = json_encode($data);
//Creating a CURL object to access the WS
$ch = curl_init();
//Setting the address to connect to
curl_setopt($ch, CURLOPT_URL, $WsURL);
//Setting HTTP method. For a new transaction we need to use POST
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
//Setting data in JSON format
curl_setopt($ch, CURLOPT_POSTFIELDS, $data_string);
//Setting the proper header.
//Setting the oauth_token to access the WS with the proper authorization
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
'Content-Type: application/json',
'Accept: application/json',
'Authorization: Bearer '.$oauth_token)
);
//Store the response as a variable and not showing the content as echo $variable
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
//Set to return the response header, this is to analyze the result and the transaction ID
curl_setopt($ch, CURLOPT_HEADER, true);
//execute connection to the Web Service
$response = curl_exec($ch);
// get some data from the response
$httpcode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
$header_size = curl_getinfo($ch, CURLINFO_HEADER_SIZE);
//Get the header as string.
$header = substr($response, 0, $header_size);
//close connection to the Web Service
curl_close($ch);
//Obtain the data from the sale recently created
if ($httpcode==201){
//find the url of the sale (Location header in the response)
preg_match("!\r\n(?:Location): *(.*?) *\r\n!", $header, $matches);
//$url contains the URL to GET the data from the Web Service
$url = $matches[1];
//Once we get the transaction ID we will query for the information of the last transaction
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
//Setting HTTP method. To get a transaction response we need to use GET
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "GET");
//Setting the proper header.
//Setting the oauth_token to access the WS with the proper authorization
curl_setopt($ch, CURLOPT_HTTPHEADER, array('Authorization: Bearer '.$oauth_token));
//Store the response as a variable and not showing the content as echo $variable
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
//execute connection to the Web Service
$response_json=curl_exec($ch);
//close connection to the Web Service
curl_close($ch);
//show result (standard JSON), parse it, process it, etc..
echo $response_json;
// now you could parse the json object to array if you preffer: $obj = json_decode($response_json);
$array = json_decode($response_json);
echo "<pre>";
print_r($array);
echo "</pre>";
}
//There was an error with the WS
else{
echo "Error creating the ".strtoupper($trans_type).": RESPONSE MESSAGE";
echo "<pre>";
echo $response;
echo "</pre>";
}
?>
using Newtonsoft.Json;
using System;
using System.IO;
using System.Net;
namespace PayHubSamples
{
public class Transactions
{
public static void findTransactions()
{
try
{
var request = (HttpWebRequest)WebRequest.Create("https://api.payhub.com/api/v2/report/transactionReport");
request.ContentType = "text/json";
request.Method = "POST";
var transaction = new
{
batchIdFrom= "5",
batchIdTo= "10",
transactionType= "Sale",
responseCode= "00",
amountFrom= "1",
amountTo= "2",
firstName= "First",
lastName= "Contact",
phoneNumber= "(415) 479 1349",
email= "jhon@company.com",
trnDateFrom= "2015-06-06 00:00:00",
trnDateTo= "2015-07-07 23:59:59",
cardType= "Visa"
};
string json = JsonConvert.SerializeObject(transaction);
request.Headers.Add("Authorization", "Bearer dfd4f12a-79af-4825-8dba-db27342c8491");
request.ContentType = "application/json";
request.Accept = "application/json";
using (var streamWriter = new StreamWriter(request.GetRequestStream()))
{
streamWriter.Write(json);
streamWriter.Flush();
streamWriter.Close();
}
try
{
var response = (HttpWebResponse)request.GetResponse();
Console.WriteLine("\nSending 'Put' request to URL");
Console.WriteLine("Response Code : " + response.StatusCode);
if (HttpStatusCode.OK == response.StatusCode)
{
using (var reader = new StreamReader(response.GetResponseStream()))
result = reader.ReadToEnd();
}
else
{
using (var reader = new StreamReader(response.GetResponseStream()))
{
result = reader.ReadToEnd();
}
}
}
catch (WebException wex)
{
if (wex.Response != null)
{
using (var errorResponse = (HttpWebResponse)wex.Response)//You return wex.Response instead
{
using (var reader = new StreamReader(errorResponse.GetResponseStream()))
{
result = reader.ReadToEnd();
}
}
}
}
Console.WriteLine(return result);
}
catch (IOException e)
{
Console.WriteLine(e);
}
}
}
}
require 'uri'
require 'net/http'
require 'json'
url = URI("https://api.payhub.com/api/v2/report/transactionReport")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Post.new(url)
request["content-type"] = 'application/json'
request["accept"] = 'application/json'
request["authorization"] = 'Bearer 2a5d6a73-d294-4fba-bfba-957a4948d4a3'
request["cache-control"] = 'no-cache'
informationToSend = {"batchIdFrom"=> "5",
"batchIdTo"=> "10",
"transactionType"=> "Sale",
"responseCode"=> "00",
"amountFrom"=> "1",
"amountTo"=> "2",
"firstName"=> "First",
"lastName"=> "Contact",
"phoneNumber"=> "(415) 479 1349",
"email"=> "jhon@company.com",
"trnDateFrom"=> "2015-06-06 00:00:00",
"trnDateTo"=> "2015-07-07 23:59:59",
"cardType"=> "Visa"
}
request.body = JSON.generate(informationToSend)
response = http.request(request)
puts response.read_body
{
"batchIdFrom": "5",
"batchIdTo": "10",
"transactionType": "Sale",
"responseCode": "00",
"amountFrom": "1",
"amountTo": "2",
"firstName": "First",
"lastName": "Contact",
"phoneNumber": "(415) 479 1349",
"email": "jhon@company.com",
"trnDateFrom": "2015-06-06 00:00:00",
"trnDateTo": "2015-07-07 23:59:59",
"cardType": "Visa"
}
Introduction
This API allows the merchant to search for transactions filtering by a wide range of optional parameters.
Request Method
POST
Endpoint (URL to Call)
webservice URL/api/v2/report/transactionReport
Required Headers
- Content-Type: application/json
- Accept: application/json
- Authorization: Bearer {auth_token}
Parameters
All the parameters are optional, they can be sent in no particular order. If one of the parameters is incorrect the server will return an error.
The parameters are case sensitive.
Below is an explanation of the parameters.
| Parameter | Description |
|---|---|
| batchIdFrom, batchIdTo | Allows the merchant to look for transactions where the batchId is between the batchIdFrom and batchIdTo. You can also use any one of the two parameters. In that case, the result will be the transactions with the batchId greater than batchIdFrom, or the batchId less than batchIdTo. |
| transactionType | Allows the merchant to look for transactions where the transaction type is any one of the following:
|
| responseCode | Allows the merchant to look for transactions where the response code is equal to a specific code. For example, the code “00” means a successful transaction. |
| amountFrom, amountTo | Allows the merchant to look for transactions where the amount of the transaction is between the amountFrom and amountTo. You can use any one of the two parameters. In that case, the result will be the transactions with the amount greater than amountFrom, or the amount less than amountTo. |
| firstName | Allows the merchant to look for transactions where the customer’s first name contains the value of the parameter. |
| lastName | Allows the merchant to look for transactions where the customer’s first name contains the value of the parameter. |
| phoneNumber | Allows the merchant to look for transactions where the customer’s phone number contains the value of the parameter. |
| This parameter allows the merchant to look for transactions where the customer’s email address contains the value of the parameter. | |
| trnDateFrom, trnDateTo | Allows the merchant to look for transactions where the date of the transaction is between the trnDateFrom and trnDateTo. You can use any one of the two parameters. In that case, the result will be the transactions with the date later than the trnDateFrom, or the date earlier than trnDateTo. Format: “yyyy-mm-dd hh:mm:ss”. |
| cardType | This parameter allows the merchant to look for transactions where the card type matches the value of the parameter. For instance: MasterCard, Visa, Discover, Amex, Diners, and JCB |
| cardLast4Digits | Allows the merchant to look for transactions where the credit card’s last four digits matches the value of the parameter. Format: “XXXX”. |
| cardToken | Allows the merchant to look for transactions where the credit card’s token matches the value of the parameter. Format: “XXXXXXXXXXXXXXXX”. |
| authAmountFrom, authAmountTo | Allows the merchant to look for transactions where the authorized amount of the transaction is between the authAmountFrom and authAmountTo. You can use any one of the two parameters. In that case the result will be the transactions with the authorization amount is greater than authAmountFrom, or the authorization amount less than authAmountTo. |
| swiped | Allows the merchant to look for transactions that where performed with a swiper device. Valid values: true, false |
| source | Allows the merchant to look for transactions where the source matches the value of the parameter. For instance: “3rd Party API” |
| note | Allows the merchant to look for transactions where the note matches the value of the parameter. |
| transactionStatus | Allows the merchant to look for transactions where the transaction status matches the value of the parameter. For instance: “Approved” |
| recurringBillId | Allows the merchant to look for transactions that were scheduled. |
| customerId | Allows the merchant to look for transactions that were executed by specific customers. |
Compatibility - Usability
All fields are NOT case sensitive. For instance, if the field is called “transactionType”, we might use it as “transactionType”, or “TransactionType” or “transactiontype”. All the fields with a compound name, such as, “transactionType” might also be referenced as “transaction_type”.
Field name (schema):
- batchIdFrom - batchidfrom, batch_id_from
- batchIdTo - batchidto, batch_id_to
- transactionType - transactiontype, transaction_type
- responseCode - responsecode, response_code
- amountFrom - amountfrom, amount_from
- amountTo - amountto, amountTo
- trnDateFrom - trndatefrom, trndate_from
- trnDateTo - trndateto, trndate_to
- firstName - firstname, first_name
- lastName - lastname, last_name
- customerId - customerid, customer_id
- cardType - cardtype, card_type
- cardLast4Digits - card_last_4_digits
- cardToken - cardtoken, card_token
- authAmountFrom - authamountfrom, auth_amount_from
- authAmountTo - authamountto, auth_amount_to
- swiped
- source
- phoneNumber - phonenumber, phone_number
- note
- transactionStatus - transactionstatus, transaction_status
- recurringBillId - recurringbillid, recurring_bill_id
Filters - Search Engine
Fields allowed for filters:
- transactiontype
- responsecode
- firstname
- lastname
- customerid
- cardtype
- cardlast4digits
- cardtoken
- swiped
- source
- phonenumber
- note
- transactionstatus
- recurringbillid
Usage
This is how a filter currently works:
The following JSON name/value pair,
“responseCode”:“00”
looks for transactions for which the Response Code is equal to “00”.
Now we have the option to look for multiple values by using semicolon “;” as a separator of the values that we send.
As an example,
“responseCode”:“00;0930;4004;05;N7”
looks for transactions for which the responseCode is equal to any of the values that were sent ( 00, 0930, 4004, 05 or N7 ).
Now we also have the option to negate values using the exclamation mark “!” before the value.
Such as in this example in which:
“responseCode”:“!00”
looks for all the transactions for which the result is NOT 00.
We also have the option of mixing the use of inclusion (include) and exclusion (include) at the same time.
For instance:
“responseCode”:“!00;!4004;N7;0930”
gets all the transactions where the Response Code is either N7 or 0930 or is neither 00 nor 4004.
There is a unique option when using the “recurringBillId” field where:
“!” means Get all the transactions that belong to a recurring bill
“” means Get all the transactions that DO NOT belong to a recurring bill
FINALLY we can mix the use of inclusion (include) and exclusion (exclude) with recurring bill ids using the “recurringBillId” field such that, as in this example:
“recurringBillId”:“300;301;!302;!303”
gets all the transactions where the recurringBillId is equal to 300 or 301 or both, but neither 302 nor 303.
Result Data
[
{
"amount": "99.25",
"authAmount": "99.25",
"batchID": "1302",
"cardLast4Digits": "XXXXXXXXXXXX8888",
"cardToken": "9999000000001838",
"cardType": "Visa",
"customerName": "Joe Tester",
"email": "lsun@payhub.com",
"isCaptured": "False",
"note": "",
"phoneNumber": "(917) 823-4567",
"recurringBillId": "2108",
"refundedBy": "0",
"responseCode": "00",
"responseText": "NO MATCH",
"source": "Recurring",
"swiped": "true",
"transactionDate": "2015-02-15 01:10:19",
"transactionID": "180628",
"transactionStatus": "Approved",
"transactionType": "Sale",
"voidedBy": "0",
"settlementStatus":"Risk Hold"
},
{
"amount": "99.25",
"authAmount": "99.25",
"batchID": "1302",
"cardLast4Digits": "XXXXXXXXXXXX8888",
"cardToken": "9999000000001838",
"cardType": "Visa",
"customerName": "Joe Tester",
"email": "lsun@payhub.com",
"isCaptured": "False",
"note": "",
"phoneNumber": "(917) 823-4567",
"recurringBillId": "2109",
"refundedBy": "0",
"responseCode": "00",
"responseText": "NO MATCH",
"source": "Recurring",
"swiped": "true",
"transactionDate": "2015-02-15 01:10:21",
"transactionID": "180629",
"transactionStatus": "Approved",
"transactionType": "Sale",
"voidedBy": "0",
"settlementStatus":"Settled"
}
]
The result data is an array of objects in JSON format.
SDKs method:
Each SDK has a transaction manager class with the next method:
- findTransactions()
PayHub Webhook
Configuration Process
With this new service you can receive a notification in two cases:
- for each transaction in your account.
- when a batch was settled.
Go to your Merchant Administration and select Webhook Configuration.
There, you will see your current webhook configuration.
From this page, you can enter your website url and select those services for which you would like to receive notifications. Also, once that the webhook is configured, you can disable or enable it at any time.
Services
Transaction Services
- VirtualHub
- MobileHub
- Recurring Billing
- API
Batch Service
- Batch
Requirements
- The endpoint validation only allows HTTPS.
- The controller for your endpoint must be implemented with a POST method.
- The controller for your endpoint must be set to accept JSON.
After you have saved your configuration (by selecting the green “Update” button), our service will send you a notification for each event that occurs on your account to the endpoint that you have indicated.
Events
There are two kinds of events: transactions and settled batches.
Transaction Message from Webhook to your endpoint
The JSON message is as follows:
{
"endpoint": "https://yoursite.com/your_controller/",
"eventType": "transaction",
"event": {
"type": {
"transaction": {
"transactionType": "Sale",
"recurringBillId": "",
"responseText": "VER UNAVAILABLE",
"source": "3rd Party API",
"cardObscured": "XXXXXXXXXXXX4507",
"orgId": "10002",
"transactionId": "721",
"responseCode": "00"
}
}
}
}
Fields Meaning
| Key | Type | Value |
|---|---|---|
| endpoint | String | Your site endpoint to receive the notifications |
| eventType | String | In this case the type is always “transaction” |
| batch_settled | Object | JSON object with batch information |
| transaction | String | Possible values:
|
| source | String | Possible values:
|
| orgId | String | String |
| transactionId | String | The transaction id. |
| recurringBillId | String | The recurring bill id if the transaction was scheduled. |
| cardObscured | String | the obscured card entered for the transaction. |
| responseText | String | A descriptive text of the transaction result. |
| responseCode | String | The code for the transaction result. |
Batch Message from Webhook to your endpoint
The JSON message is at follows:
{
"endpoint": "https://yoursite.com/your_controller/",
"eventType": "batch_settled",
"event": {
"type": {
"batch_settled": {
"date": "Thu Oct 29 11:23:11 ART 2015",
"batch_id": "102",
"net_total": "15",
"terminal": "Virtual Hub",
"trans_count": "15",
"status": "Settled"
}
}
}
}
Fields Meaning
| Key | Type | Value |
|---|---|---|
| endpoint | String | Your site endpoint to receive the notifications |
| eventType | String | In this case the type is always “batch_settled” |
| batch_settled | Object | JSON object with batch information |
| date | String | Date. |
| batch_id | String | The batch id. |
| net_total | String | The total amount of money |
| terminal | String | The terminal name. |
| trans_count | String | The number of transaction that were settled on the batch. |
| status | String | The batch status . |
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 |
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 |
Errors
| Error Code | Meaning |
|---|---|
| 00 | VALID_OPERATION |
| 02 | CARD_NUMBER_MISSING_CODE |
| 1009 | INVALID_REFERENCE_NUMBER |
| 4006 | INVALID_MERCHANT |
| 4007 | INVALID_TERMINAL |
| 4008 | INVALID_USER_NAME |
| 4009 | INVALID_USER_PASSWORD |
| 4010 | INVALID_RECORD_FORMAT |
| 4011 | INACTIVE_TERMINAL |
| 4012 | INVALID_AUTHENTICATION |
| 4013 | INVALID_TRANSACTION_CD |
| 4014 | INVALID_OFFLINE_APPROVAL_CD |
| 4015 | INVALID_CARDHOLDER_ID_CODE |
| 4016 | INVALID_CARD_HOLDER_ID_DATA |
| 4017 | INVALID_ACCOUNT_DATA_SOURCE |
| 4018 | INVALID_CUSTOMER_DATA_FIELD |
| 4019 | INVALID_CVV_CODE |
| 4020 | INVALID_CVV_DATA |
| 4021 | INVALID_TRANSACTION_AMOUNT |
| 4022 | INVALID_CARD_NUMBER |
| 4023 | INVALID_BATCH_ID |
| 4024 | INVALID_TRANSACTION_ID |
| 4025 | INVALID_CARD_EXPIRY_DATE |
| 4026 | INVALID_AVS_DATA_FLAG |
| 4027 | INVALID_CUSTOMER_ID |
| 4028 | INVALID_CUSTOMER_WEB |
| 4029 | INVALID_CUSTOMER_EMAIL_ID |
| 4030 | INVALID_CUSTOMER_BILLING_ADD_ZIP |
| 4031 | INVALID_CUSTOMER_SHIPPING_ADD_ZIP |
| 4032 | INACTIVE_MERCHANT |
| 4033 | INVALID_TERMINAL_ORIGIN |
| 4034 | INVALID_CARD_DATA_FOR_DEBIT |
| 4035 | INVALID_TRANSACTION_CODE_FOR_DEBIT |
| 4036 | INVALID_CUSTOMER_ADDRESS |
| 4037 | INVALID_CUSTOMER_COMPANY_NAME |
| 4038 | INVALID_CUSTOMER_DATA |
| 4039 | INVALID_TRANSACTION_NOTE |
| 4040 | CARD_NOT_SUPPORT_CODE |
| 4041 | CVV_REQUIRED_CODE |
| 4042 | AVS_REQUIRED_CODE |
| 4043 | CARD_REQUIRED_CODE |
| 4044 | EXPIRY_REQUIRED_CODE |
| 4045 | TRACK_DATA_REQUIRED_CODE |
| 4046 | CARD_TOKEN_GENRATION_FAILED_CODE |
| 4047 | PAYMENT_TYPE_REQUIRED_CODE |
| 4048 | TRANSACTION_TYPE_REQUIRED_CODE |
| 4049 | TRANSACTION_ID_REQUIRED_CODE |
| 4050 | BATCH_ID_REQUIRED_CODE |
| 4051 | TERMINAL_ID_REQUIRED_CODE |
| 4052 | ORGANIZATION_REQUIRED_CODE |
| 4053 | BATCH_TRANSACTION_NOT_FOUND_CODE |
| 4054 | ALREADY_SETTLED_BATCH_CODE |
| 4055 | DUPLICATE_BATCH_CODE |
| 4056 | BATCH_SETTLED_SUCCESSFULLY_CODE |
| 4057 | BATCH_SETTLEMENT_FAILD_CODE |
| 4058 | BATCH_REJECTED_CODE |
| 4059 | NETWORK_UNAVAILABLE_CODE |
| 4060 | UNABLE_TO_BUILT_REQUEST_CODE |
| 4061 | RECORD_NOT_FOUND_CODE |
| 4062 | RECURRING_SAVED_CODE |
| 4063 | RECURRING_SAVING_FAILED_CODE |
| 4064 | RECURRING_UPDATION_CODE |
| 4065 | RECURRING_UPDATION_FAILED_CODE |
| 4066 | RECURRING_STATUS_CHANGED_SUCCESSFULLY |
| 4067 | RECURRING_STATUS_CHANGING_FAILED |
| 4068 | INVALID_TRANSACTION_ID_CODE |
| 4069 | TRANSACTION_ALREADY_VOIDED_CODE |
| 4070 | CARD_TYPE_REQUIRED_CODE |
| 4071 | INVALID_BATCH_NO_CODE |
| 4072 | TRANSACTION_ALREADY_REFUNDED_CODE |
| 4073 | UNABLE_TO_VOID_CODE |
| 4074 | UNABLE_TO_REFUND_CODE |
| 4075 | UNABLE_TO_CAPTURE_CODE |
| 4076 | CAPTURED_TRANSACTION_SENT_CODE |
| 4077 | CAPTURED_TRANSACTION_FAILED_CODE |
| 4078 | INVALID_INVOICE_NUMBER |
| 4080 | INVALID_BILL_TYPE_CODE |
| 4081 | INVALID_BILL_GENERATION_SPAN_CODE |
| 4082 | INVALID_END_DATE_TYPE_CODE |
| 4083 | INVALID_END_BILL_COUNT_CODE |
| 4084 | INVALID_END_BILL_DATE_CODE |
| 4085 | INVALID_WEEK_DAYS_CODE |
| 4086 | INVALID_MONTHLY_TYPE_CODE |
| 4087 | INVALID_MONTHLY_WEEK_DAYS_CODE |
| 4088 | INVALID_MONTHLY_DAYS_POSSION_CODE |
| 4089 | INVALID_MONTHLY_DAYS_CODE |
| 4090 | INVALID_START_DATE_CODE |
| 4091 | INVALID_SPECIFIC_DATES_CODE |
| 4092 | SPECIFIC_SAME_DATES_CODE |
| 4093 | INVALID_RECURRING_DATA_CODE |
| 4094 | END_BILL_DATE_BEFORE_START_CODE |
| 4095 | CARD_HOLDER_DATA_REQUIRED_CODE |
| 4096 | CARD_HOLDER_CODE_REQUIRED_CODE |
| 4097 | INVALID_STATUS_CODE |
| 4098 | UNABLE_TO_CHANGE_STATUS |
| 4099 | CARD_VALIDATION_FAILED_CODE |
| 4100 | RECURRING_CIS_FAILED_CODE |
| 4101 | UNABLE_BUILT_RECURRING_FILTER__CODE |
| 4103 | UNABLE_TO_BUILT_NEXT_BILL_CODE |
| 4501 | INVALID_PHONE_TYPE |
| 4502 | INVALID_PHONE_NUMBER |
| 4503 | INVALID_ZIP_CODE |
| 4504 | INVALID_STATE_CODE |
| 4505 | INVALID_INTERVAL_TYPE |
| 4506 | INVALID_END_DATE |
| 4507 | INVALID_BILL_WEEKLY_DAYS |
| 4508 | INVALID_YEAR_MONTH_DAYS |
| 4509 | INVALID_YEAR_BILL_ON_MONTH_NO |
| 4510 | INVALID_MONTHLY_BILL_TYPE |
| 4511 | INVALID_MDAYS_POSITION |
| 4512 | INVALID_MDAYS |
| 4513 | INVALID_MDAY_EACH_POSITIONS |
| 4514 | INCONSISTENT_SCHEDULE_FIELDS |
| 4515 | ACCOUNT_IS_NOT_ADMINISTRATOR |
| 4516 | INCONSISTENT_CARD_DATA_FIELDS |
| 4517 | WRONG_OAUTH_TOKEN_FOR_MERCHANT |
| 4518 | NO_MERCHANT_ACCOUNT_FOR_OUTH_TOKEN_FOR_MERCHANT |
| 4519 | NO_SETUP_ACCOUNT_FOR_OUTH_TOKEN_FOR_MERCHANT |
| 4520 | NO_VT_CLIENT_ACCOUNT_FOR_OUTH_TOKEN_FOR_MERCHANT |
| 4521 | INVALID_CURRENCY_CODE |
| 4522 | INVALID_RECURRING_BILL_STATUS_CHANGE_CODE |
| 4523 | INCONSISTENT_CURRENCIES |
| 4524 | MISSING_PROPERTY_CODE |
| 4525 | INCONSISTENT_CUSTOMER_DATA_CODE |
| 4526 | DUPLICATE_DEVELOPER_CODE |
| 9989 | METHOD_REQUEST_BODY_VALIDATION_ERROR_CODE |
| 9990 | HTTP_NOT_READABLE_EXCEPTION_CODE |
| 9991 | JSONPARSE_EXCEPTION_CODE |
| 9992 | MAPPING_EXCEPTION_CODE |
| 9993 | MEDIA_TYPE_NOT_SUPPORTED_CODE |
| 9994 | METHOD_NOT_SUPPORTED_CODE |
| 9995 | PAGE_NOT_FOUND_ERROR_CODE |
| 9996 | ACCESS_DENIED_ERROR_CODE |
| 9997 | JSON_SYNTAX_ERROR_CODE |
| 9998 | NOT_FOUND_ERROR_CODE |
| 9999 | INTERNAL_SERVER_ERROR_CODE |
Changelog
Release Date 2016-05-26
Virtual Terminal (VPOS or VT)
- Added customizable Processing Modal logo
- Misc bug fixes
recurring-bill
- Misc bug fixes
WebService (WS)
- Misc bug fixes
- Added recurring bill update methods
- Added Transaction Totals method.
- Added Email Settings methods.
transaction Report
- Added SettlementStatus to transaction result report
- Misc bug fixes
Release Date 2016-04-27
Virtual Terminal (VPOS or VT)
- Misc bug fixes
WebService (WS)
- Misc bug fixes
Release Date 2016-02-23
WebService (WS)
transaction Report
- Added customerId in the request. This allows the merchant to look for transactions that were executed by specific customers.
- Added isCaptured in the response. (true / false) This allows to know if an Auth Only is Captured.
- Added voidedBy in the response. Shows the number of the transaction that voided the transaction searched.
- Added refundedB in the response. Shows (as an array) the numbers of the transactions that refunded the transaction searched.
recurring-bill
- Misc bug fixes
Customers > Linking Customers
- Provided documentation on how Customers are linked together