Receiving callbacks

Contents

When our system detects a payment, our server will notify your specified callback URL with information about the transaction. You'll have to create a payment processing page to handle the callbacks and finalize your customers' orders.

Our service starts doing callbacks from 0 (a new unconfirmed transaction in bitcoin network) up to 6 confirmations. Totally, you can get 7 callbacks per one transaction.

After 1 confirmation we will forward your bitcoins to the destination address, and then there will be added a transaction hash and a destination address to callback parameters.

In order to confirm a successful processing of the callback, your server should respond in plain text format:

*ok*

When we get *ok* we will stop doing callbacks for this transaction.

In case your server doesn’t respond or responds incorrectly, our callback server will make new attempts for every new block within 3 days.

The callbacks will always be sent as GET-requests containing the details of the payment and the forwarded transaction, in addition to any parameters already presented in the callback URL. Once again, please remember that callback URLs have a maximum length of 1024 characters.

Callback example

Using GET-method to URL callback is like opening a link in your browser. You can enter your callback URL and experiment with variables in the form below. Then test your callback response from our server-side or COPY+PAST the link from the block to test it in the browser.

The following block shows an example of the callback request URL:

http://example.com/callback?invoice_id=1234&secret=7j0ap91o99cxj8k9&value=100000000&input_address=1E2VSRsaW3Kb1gDkdRUGDo6knAKfi9iYsb&confirmations=1&transaction_hash=0e3e2357e806b6cdb1f70b54c3a3a17b6714ee1f0e68bebb44a74b1efd512098&input_transaction_hash=4a5e1e4baab89f3a32518a88c31bc87f618f76673e2cc77ab2127b7afdeda33b&destination_address=1LisLsZd3bx8U1NYzpNHqpo8Q6UCXKMJ4z&value_forwarded=99979800
Parameters and variables

The following table lists all GET parameters that will be sent in the request to your server:

Parameter Variables Present Experiment with a value
URL
<1024 chars
Callback URL
Your server's URL with optional extra GET parameters
Always
{value}
integer, range 1-10^16

Amount in Satoshi
The amount of bitcoin sent by the customer in satoshi (1 BTC = 100,000,000 satoshi). Make sure to convert this to BTC when necessary by dividing by 100,000,000.

Always
{input_address}
base58, 32 chars
Input Address
The generated bitcoin address to which customer sent the payment.
Always
{confirmations}
integer, range 0-1000

Confirmations
Number of accepted confirmations. Default range 0-6.'

Always
{transaction_hash}
text, 64 chars
Transaction Hash
The transaction hash of forwarded payment to your destination bitcoin address.
After bitcoin forwarding only
{input_transaction_hash}
text, 64 chars

Input Transaction Hash
The hash of the customer's transaction sent to the generated input address.

Always
{destination_address}
base58, 32 chars
Destination address
Your supplied destination bitcoin address where confirmed payments will be transferred
After bitcoin forwarding only
{value_forwarded}
integer, range 1-10^16
Forwarded amount in Satoshi
The forwarded amount in satoshi without blockchain network and service fee (1 BTC = 100,000,000 satoshi). Make sure to convert this to BTC when necessary by dividing by 100,000,000.
After bitcoin forwarding only  
  Reset Values Try callback
Response from server:
*ok*

It's wrong response. Successful callback response should be in plain text format only without other chars. Right response: *ok*

Right response. Thank you.

Receiving Callback - Code Example

Don't finish order with 0 confirmation! Because sender can create a new transaction with more fee to another receiver and network may confirm it. Then payment to you will never arrive. Just update your order that you see transaction and wait for confirmation.

Finish order or top-up user's account balance within 1-6 confirmations, recommended 3. And you will be sure that each payment arrives to you. Second PHP example demonstrates it.