API Authentication
Step 1: TPV issues API credentials
Brand is issued a token by logging into the management portal, going to Brands and clicking edit for the appropriate brand. Next a new token is issued from the API Access tab. The Application Token and Application Secret are provided to the client. The application secret should be treated as extremely confidential like a password and it is never sent over the wire, only used to verify identity.
Step 2: Prove Identity for Auth Token
Endpoint: POST (clients portal)/api/v1/auth
Query Parameters:
* token: Client Application Token
* _signature: generated signature
* timestamp: current UTC unix style timestamp (seconds since epoch, like php's time() function)
Generating Authorization Signature
All signatures are sha256 hmac, in PHP this uses the hash_hmac:
$signature = hash_hmac('sha256', 'token=' . $token . '×tamp=' . $timestamp, $appSecret);
In essence it builds the query string and generates the signature.
If done correctly you will receive a JSON response containing the auth_token.
This token is good for 30 minutes and will be used in all other api calls.
The login endpoint is the only endpoint where token/signature in the url query string is required, all other
endpoints should put the auth token in the Authorization header (without bearer) and the
signature generated for the request in the Signature header.
Example with curl
curl -X POST (clients portal)/api/v1/auth?token={your app token}×tamp={current utc timestamp}&_signature={generated signature}
Step 3: Signing Requests
Normal Request Testing Auth Example
curl -X POST -H 'Authorization: {your auth token here}' (clients portal)/api/v1/test/api?your=Parameters&here=1
API Endpoints
TPV Post
POST /api/v1/tpv
Example data
{
"digital_delivery": "email",
"channel": "dtd",
"language": "english",
"external_id": null,
"market": "residential",
"company_name": null,
"authorizing_first_name": "Bill",
"authorizing_last_name": "Jones",
"billing_first_name": "Bill",
"billing_last_name": "Jones",
"btn": "19181112222",
"email_address": "bill@jones.com",
"service_address": "123 Main St.",
"service_city": "New York",
"service_state": "NY",
"service_zip": "10001",
"billing_address": "123 Main St.",
"billing_city": "New York",
"billing_state": "NY",
"billing_zip": "10001",
"vendor": "TPV Test",
"sales_agent_id": "testest",
"products": [
{
"program_code": "555",
"account_numbers": [
{
"account_number": "123123123123123",
"account_number_label": "Account Number"
}
]
}
]
}
Example request
curl -X POST -H "Content-Type: application/json" -H 'Authorization: {your auth token here}' -d "@example.json" (clients portal)/api/v1/tpv
Response 200
Upon a successful request, a confirmation code will be returned from our system. This acts as a unique identifier that is assigned to the sales transaction.
{
"success": "00090894407"
}
Failure Responses 400
All failure responses will return a status code 400 and an accompanying error message.
Example
{
"error": "channel must be defined as one of dtd, tm, or retail."
}
GET /api/v1/products
curl -X POST -H 'Authorization: {your auth token here}' (clients portal)/api/v1/products
GET /api/v1/digital/send/{confirmation code}
curl -X POST -H 'Authorization: {your auth token here}' (clients portal)/api/v1/digital/send/{confirmation code}
GET /api/v1/queue/call/{confirmation_code}
curl -X POST -H 'Authorization: {your auth token here}' (clients portal)/api/v1/queue/call/{confirmation code}
Example Code
<?php
$token = "(token here)";
$appSecret = "(application secret)";
$timestamp = time();
$url = "(client portal)";
$auth = auth($url, $token, $appSecret);
if ($auth) {
$auth_token = $auth['auth_token'];
echo "API Authenticated :: AUTH TOKEN IS " . $auth_token . "\n";
$data = [
"digital_delivery" => "email",
"channel" => "dtd",
"language" => "english",
"external_id" => null,
"market" => "residential",
"company_name" => null,
"authorizing_first_name" => "John",
"authorizing_last_name" => "Williams",
"billing_first_name" => "John",
"billing_last_name" => "Williams",
"btn" => "12223334444",
"email_address" => "nobody@tpv.com",
"service_address" => "123 Main St.",
"service_city" => "Chicago Ridge",
"service_state" => "IL",
"service_zip" => "60415",
"billing_address" => "123 Main St.",
"billing_city" => "Chicago Ridge",
"billing_state" => "IL",
"billing_zip" => "60415",
"vendor" => "TPV Test",
"sales_agent_id" => "testest",
"products" => [
[
"program_code" => "555",
"account_numbers" => [
[
"account_number" => "123123123123123",
"account_number_label" => "Account Number",
]
]
]
]
];
$tpv = tpvPostTest(
$url,
$auth_token,
$data
);
$confirmation_code = $tpv->success;
echo 'TPV Submission Successful :: Confirmation Code is ' . $confirmation_code . "\n";
if (isset($confirmation_code)) {
$digital = sendDigital(
$url,
$auth_token,
$confirmation_code
);
echo 'DIGITAL :: ' . $digital->success . "\n";
}
}
function auth(
string $url,
string $token,
string $appSecret
) {
$signature = hash_hmac('sha256', 'token=' . $token . '×tamp=' . time(), $appSecret);
$endpoint = $url . "/api/v1/auth?token=" . $token . "×tamp=" . time() . "&_signature=" . $signature;
$ch = curl_init($endpoint);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_VERBOSE, false);
curl_setopt($ch, CURLOPT_DNS_USE_GLOBAL_CACHE, false);
curl_setopt($ch, CURLOPT_DNS_CACHE_TIMEOUT, 2);
curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, 0);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, 0);
$response = curl_exec($ch);
if ($response === false) {
echo curl_error($ch);
} else {
return json_decode($response, true);
}
curl_close($ch);
return null;
}
function tpvPostTest(
string $url,
string $auth_token,
array $fields
) {
$endpoint = $url . "/api/v1/tpv";
$options = array(
'http' => array(
'ignore_errors' => true,
'method' => 'POST',
'content' => json_encode($fields),
'header' => "Content-Type: application/json\r\n" .
"Accept: application/json\r\n" .
"Authorization: " . $auth_token . "\r\n"
),
'ssl' => array(
'verify_peer' => false,
),
);
$context = stream_context_create($options);
$result = file_get_contents($endpoint, false, $context);
$response = json_decode($result);
return $response;
}
function sendDigital(
string $url,
string $auth_token,
$confirmation_code
) {
$endpoint = $url . "/api/v1/digital/send/" . $confirmation_code;
$options = array(
'http' => array(
'ignore_errors' => true,
'method' => 'POST',
'content' => null,
'header' => "Content-Type: application/json\r\n" .
"Accept: application/json\r\n" .
"Authorization: " . $auth_token . "\r\n"
),
'ssl' => array(
'verify_peer' => false,
),
);
$context = stream_context_create($options);
$result = file_get_contents($endpoint, false, $context);
$response = json_decode($result);
return $response;
}