The easiest way to receive payments in TittieCoin! You don't even need to install the wallet on your server.
If you're already receiving Bitcoin payments with Blockchain's API, you already know how to add TittieCoin support.
Through a GET call, you ask for a unique TittieCoin address. Every payment sent there will be automatically forwarded to you,
and your server gets an instant notification.
Here's how the process works:
1) The user makes an order
2) Your server asks for a new address
3) api.tittiecoin.com returns a new address
4) Your server displays the address to the user
5) The user makes the payment to api.tittiecoin.com
6) api.tittiecoin.com forwards the payment and instantly notifies your server
7) Your server delivers the order to the user
You don't need to install the wallet on your server, but you do need and address to receive the payments.
There are several options:
• The official desktop wallet: Tittiecoin.com
• Cold storage: Wallet Generator
• An exchange: Exchanges
Call this method to create a unique address and present it to the user. You should create a new address for every order, or at least every user.
However, you could use your same address to receive the forwarded payment.
The minimum supported amount is 2 TTC (after fee charges).
The current cost of the service is: 0% plus a fixed fee of 2 TTC
Check the variables fee_percent and fee_fixed (see below) after every call to get updated information.
https://api.tittiecoin.com/receive.php?method=create&address;=$receiving_address&callback;=$callback_url
(Important: Your Callback URL may be called immediately to validate it. It should not process anything if the parameters value or input_address are missing)
Response: 200 OK, APPLICATION/JSON
{
"fee_percent":0,
"fee_fixed":2,
"destination":"$receiving_address",
"input_address":"TZDQb8LNaJq1gBxxiKXYFbDNHpRM9QFAx6",
"callback_url":"$callback_url",
"salt_hash":"iBkhwPi1HTa7TBgdHkeycg9KZgf5rPf9"
}
salt_hash is used to create a unique security hash on every call to your callbak URL (see below).
Note your callback URL cannot exceed 255 characters.
If your callback URL is not valid, or if there is any other error, you'll get this:
Response: ERROR 500, TEXT/PLAIN
This is the error description
PHP Example (Based on Blockchain's API)
$my_address = '{YOUR TittieCoin ADDRESS}';
$my_callback_url = 'http://example.com/process_purchase.php?
purchase_id=1234567890;
$root_url = 'https://api.tittiecoin.com/receive.php';
$parameters = 'method=create&address;=' . $my_address .'&callback;='. urlencode($my_callback_url);
$response = file_get_contents($root_url . '?' . $parameters);
$object = json_decode($response);
echo 'Send Payment To : ' . $object->input_address;
// Store input_address and salt_hash on the database
A complete example can be seen here:
https://github.com/tittiecoin/tittiecoin-api/blob/master/index.php
Implementing the Callback
When a payment is received, api.tittiecoin.com will notify your server. It will do so by calling the callback url you sent.
The following parameters will be supplied via GET:
• {Custom} All the parameters you included in your callback URL, for example purchase_id
• value The value of the payment received in Tittoshis. Divide by 100000000 to get the value in TittieCoins.
• input_address The TittieCoin address that received the payment from your user.
• confirmations The number of confirmations of that transaction.
• transaction_hash The hash of the forwarding transaction, or empty if the payment hasn't been forwarded yet.
• input_transaction_hash The hash of the original transaction, before the forwarding.
• destination_address The address where the payment was or will be forwarded to. Check this matches your own address.
• security_hash A lower case md5 hash calculated as md5( salt_hash + "-" + input_transaction_hash + "-" + value + "-" + confirmations ).
Note: Your payment will be forwarded to destination_address (and therefore transaction_hash will be supplied) when the original transaction (input_transaction_hash) reaches 1 confirmations (confirmations).
Expected response: *ok*
Once your server has successfully processed the information sent by api.tittiecoin.com, it must respond with the text "*ok*".
If it responds with anything else, the callback will be resent again every 3 minutes for up to 500 times (25 hours).
Once your server has responded with *ok*, it won't receive a callback for the same transaction.
PHP Example(Based on Blockchain's API)
$purchase_id = $_GET['purchase_id']; //purchase_id is past back to the callback URL
$transaction_hash = $_GET['transaction_hash'];
$input_transaction_hash = $_GET['input_transaction_hash'];
$input_address = $_GET['input_address'];
$value_in_tittoshi = $_GET['value'];
$value_in_ttc = $value_in_tittoshi / 100000000;
$confirmations = $_GET['confirmations'];
$security_hash = $_GET['security_hash'];
//Commented out to test, uncomment when live
if ($_GET['test'] == true) {
return;
}
try {
//create or open the database
$database = new SQLiteDatabase('db.sqlite', 0666, $error);
} catch(Exception $e) {
die($error);
}
// Verify the security hash
$salt_hash = // Get the salt_hash from DB
$my_hash = md5( $salt_hash . "-" . $input_transaction_hash . "-" .
$value_in_tittoshi . "-" . $confirmations );
if( $my_hash != $security_hash ) {
die("Security hash is invalid");
}
//Register the payment
if( $confirmations > 1 && $transaction_hash )
echo "*ok*"; // This will be the last callback
// Verify this transaction_hash hasn't been registered yet
// Register into confirmed payments
} else {
// Insert into pending payments
// Don't print *ok* yet
}
A complete example can be seen here:
https://github.com/tittiecoin/tittiecoin-api/blob/master/callback.php
Security
Store salt_hash on your database when you call /receive.php.
Then, when you receive the callback, calculate it and compare with the receive parameter security_hash
(see example above).
This method is recommended because the salt_hash will be encrypted by SSL (because the API uses http).
Additionally (or instead), you can pass your own security code when calling /receive.php. That same value will be
passed to your callback, so you can compare it.
Also, to prevent chargebacks or double spends, make sure to verify the number of confirmations (see example above).
Address Expiration and Limits
Every generated address is guaranteed to work for one month.
There is no limit on how many times you can use this API. However, your server can be banned under some conditions:
• A great percentage of requested addresses never receive payments (usually, more than 500 and more than 90%).
• Your server never responds with *ok* or usually takes several hours to do so.
• Your server is constantly unreachable.
Testing your Callbak: /test
You can use this tool to test your Callbak URL and the complete process:
/Test
When your Callback is reached by this tool, you'll receive and additional parameter test=true.
You should not process anything when that parameter is received (see example above).
Open-source PHP example:
You can download a simple but complete PHP/MySQL example on GitHub.
https://github.com/tittiecoin/tittiecoin-api
Which is installed and running here:
https://api.tittiecoin.com/receive_payment_php_demo/