Payment API

Introduction

Our receive payments API is the quickest and easiest way to begin accepting automated Bitcoin, Litecoin, Zcash, Bitcoin Cash or Bitcoin SV payments, system only requires one confirmation to forward the payment. No delays. A small fee of 1% is taken automatically before system forwards the payment, we use those fees to keep the services up and running.

If you need help implementing the API, you can contact us and we'll do that for you for a small fee.


Generating Receiving Addresses

This method creates a unique address which should be presented to the customer. Any payments sent to this address will be forwarded to your own BTC/LTC/ZEC/BCH/BSV address. Each time a payment is forwarded the callback URL will be called.

The minimum supported transaction size is pegged at $1 in crypto currency you are sending/receiving. Forwarding transactions will include a network fee paid from the amount you are sending.

https://litepay.ch/api/receive?method=$method&address=$receiving_address&callback=$callback_url&callback_req=1
  • $method - Use 'btc' / 'ltc' / 'zec' / 'bch' / 'bsv' as a value for parameter method, based on entered value a Bitcoin, Litecoin, Zcash, Bitcoin Cash, Bitcoin SV address will be generated
  • $receiving_address - Your Receiving Bitcoin/Litecoin/Zcash/BCASH/BitcoinSV Address (Where you would like the payment to be sent)
  • $callback_url - The callback URL to be notified when a payment is received. Remember to URL Encode the callback URL when calling the create method. The domain must be valid, or else your request will be denied.
  • $callback_req - It allows you to choose if you want to get a callback from our system. 0 for no, 1 for yes (Default is 1)

TOR USERS:
https://litepay.ch/api/receive?method=$method&address=$receiving_address&callback_req=0
* Remove $callback and set $callback_req to 0 to be able to generate addresses without the system checking domain validity.
* This means you need to make a small script to check for the payment. You can use Blockchain API or blockexplorer.

RESPONSE: 200 OK, APPLICATION/JSON
{
callback_url    "http://yourwebsite.com/callback_page?id=123&secret=random_secret"
input_address   "1EMnFbKfoCNptj9dQX3bpyunNhC6mfj7sa"
destination     "1BDesouFJaHyr7DejtGrq7K14D5gSbS4DT"
fee_percent     "0.01"
callback_req    "0"
}
If you do not receive the callback double check the callback_url provided in the response is correct.

ERROR RESPONSE: 200 OK, APPLICATION/JSON
status     "error"
message    "You requested callback_req 1 and no callback_url"
Example
$secret = 'NTIzMzUxN2E4Yjc2YWEzNDI0M2NlMjZh';
$my_address = '{YOUR BTC/LTC/ZEC/BCH/BSV ADDRESS}';
$my_callback_url = 'http://yourwebsite.com/callbackurl.php?call=123&secret='.$secret;
$method = '{YOUR METHOD}';
$parameters = 'address=' . $my_address . '&method=' . $method . '&callback='. urlencode($my_callback_url);
$response = file_get_contents('http://litepay.ch/api/receive?' . $parameters);
$object = json_decode($response);
echo 'Send Payment To : ' . $object->input_address;

Implementing The Callback

When a payment is received our API will notify the callback URL passed using the create method. The parameters will be supplied in a http GET request. The callback url is limited to 255 characters in length.

Parameters
  • {Custom Parameters} - Any parameters included in the callback URL will be passed back to the callback URL in the notification.
  • value - The value of the payment received in satoshi. Divide by 100000000 to get the value in BTC.
  • input_address - The Bitcoin/Litecoin/Zcash/BitcoinCash/BitcoinSV address that received the transaction.
  • transaction_hash - The transaction hash.
  • destination_address - The destination Bitcoin/Litecoin/Zcash/BitcoinCash/BitcoinSV address. Check this matches your address.
  • coin - The coin used in the transaction BTC/LTC/ZEC/BCH/BSV

Expected Response

In order to acknowledge successful processing of the callback the server should respond with the text “*ok*”. If the server responds with anything else the callback will be resent again every new block (approximately every 10 minutes) up to 100 confirmations.

A notification will never be sent for the same transaction twice once acknowledged with “*ok*”. It is a good idea to record the transaction hash even if not needed to detect duplicates for logging purposes.

If you are using Cloudflares service, make sure you are allowing our GET request, if you do not receive callbacks from us, check your cloudflare rules first.

Security

A custom secret parameter should be included in the callback URL. The secret will be passed back to the callback script when the callback is fired and will be checked for validity. If the secret is invalid, callback will not execute.

Double Spends & Chargebacks

A double spend occurs when a malicious user spends the same BTC twice. A payment that initial appears successful could be reversed at a later date. This is counteracted by waiting for the transaction to be included in the blockchain and reaching a number of confirmations. 6 confirmations is generally considered safe for high value transactions.

Address Expiration

Normal addresses expire after 30 days of idle. Don't use the same address for multiple payments, generate a new one each time.

Fair Usage

There is no limit to the number of receiving address which can be generated, the service is designed to monitor millions of addresses.
The minimum transaction size is $1 in crypto. There is no maximum payment or any other limitations.
Transactions lower than the minimum transaction amount specified earlier are considered donations.
Callback domains which appear dead or never return the “*ok*” response may be blocked from the service.