Payment API

Introduction

Our receive payments API is the quickest and easiest way to begin accepting automated Bitcoin and Litecoin 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.


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 Bitcoin/Litecoin address. Each time a payment is forwarded the callback URL will be called.

The minimum supported transaction size is 0.0010 BTC and 0.010 LTC. 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=0
  • $method - Use 'bitcoin' or 'litecoin' as a value for parameter method, based on entered value a Bitcoin or Litecoin address will be generated
  • $receiving_address - Your Receiving Bitcoin/Litecoin 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: ERROR 500, TEXT/PLAIN
Error Generating Receiving Address
Example
$secret = 'NTIzMzUxN2E4Yjc2YWEzNDI0M2NlMjZh';
$my_address = '{YOUR BITCOIN/LITECOIN ADDRESS}';
$my_callback_url = 'http://yourwebsite.com/callbackurl.php?call=123&secret='.$secret;
$method = '{YOUR METHOD, BITCOIN OR LITECOIN}';
$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
  • value - The value of the payment received in satoshi. Divide by 100000000 to get the value in BTC.
  • input_address - The Bitcoin/Litecoin address that received the transaction.
  • {Custom Parameters} - Any parameters included in the callback URL will be passed back to the callback URL in the notification.
  • transaction_hash - The transaction hash.
  • destination_address - The destination Bitcoin/Litecoin address. Check this matches your address.

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.

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 0.0010 BTC. 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.





Merchant API

Introduction

Our Merchant System will provide you with a way to sell your products without the need for a messy code implementation. With our system, the only thing you need to do, is to create your invoice. After the invoice has been paid, you will be notified by email. Payments are forwarded after 1 network confirmation (usually 5-30 minutes) to prevent any unwanted scenarios.Bitcoin USD rate is valid for 15 minutes, after that the price is regenerated because of Bitcoins price volatility. A small fee of 1% is taken automatically before system forwards the payment, we use those fees to keep the services up and running.

The minimum supported transaction size is 0.0010 BTC. Forwarding transactions will include a network fee paid from the amount you received.


Generating Invoices

Please contact us to provide you with a MerchantID and a secret code. Once that is all done, you'll need to send a POST request to our API servers, with the following information;

url:  https://litepay.ch/merch/
method: POST
data required:
vendor     = vendor id we supplied
invoice       = invoice number you generated (from your shop)
secret  = secret word needed to confirm that you are said vendor
price    = price of the invoice in USD
callbackUrl = a callback url where you can receive callbacks from our system.
returnUrl = a returnUrl for us to send the client to after the payment.


A correct input of data will redirect you/customer to the invoice payment page. 
An incorrect input of data will reply with "ERROR: Please double check the information you submitted" or in case of missing fields "You have missing fields".

An example invoice:

https://litepay.ch/merch/inv?id=LTPP-2722

For automated shops, the POST will be done automatically and the client will be redirected to our payment system. If the invoice is already in our system, the buyer will be redirected to the existing invoice.

Once the invoice has been paid, our system will send you an email confirming that. We can offer support for websites that require a callback to update their database on the spot.

This is how the email might look like;

Subject:

LitePay.ch Merchant | Invoice Example-818 has been paid!

Body:

Hello, Coffee Shop
Invoice number #Example-818 has been paid.

Payment information:
Used BTC address : 3LNUEC3cCMqXCr5yhLDxjv1BhYrnhzGmXP
Amount:  0.004546 BTC / ~32 USD
TxID: a781b7bccbee0c1ea5b2f4c3ddca4c7396b4508f3067e0a4bf644a19e68db8ce
TxTime: 2017-11-01 22:35:45
Status: Payment has 0 confirmations

During the next 30 minutes (after transaction is verified) this payment will be automatically forwarded to your own external wallet address. 

Best Regards,
LitePay.ch Team
Thank you for using www.LitePay.ch
Support is available at: [email protected]
Address Expiration

BTC Address will expire once the invoice has been paid. Unpaid/Paid invoices expire after 30 days since their creation.