Receiving callbacks

V 2.0

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 difference between Callback V1 and V2 is in the type of HTTP method requests (GET / POST) and the construction of parameters in JSON. If you use V2 processing, use V2 callback handlers!

In this version, callbacks will always be sent to specified URL as POST-requests containing the details of the payment and the forwarded transaction.

Cloud Flare callbackPlease add our domain and source IP to the white list in Cloudflare CDN dashboard.
Otherwise, we can not guaranty properly callback to your host.

HTTP and HTTPS protocol schemas in URL are required. Also, we support callback to TOR project logo network.

Parameters and variables

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

Parameter Description Present Experiment with a value
{data} Array of user parameters for the payment Optional  
{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}
string, 32 chars
Input Address
The generated bitcoin address to which customer sent the payment.
Always
confirmations
integer, range 0-1000

Confirmations
A number of accepted confirmations. Default range 0-6.

Always
{input_transaction_hash}
string, 64 chars

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

Always
  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.
Callback example

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

{
  "data": 
  {
      "invoice_id": 1234,
      "secret": "7j0ap91o99cxj8k9"
  },
  "input_address": "1E2VSRsaW3Kb1gDkdRUGDo6knAKfi9iYsb",
  "confirmations": 1,
  "input_transaction_hash": "4a5e1e4baab89f3a32518a88c31bc87f618f76673e2cc77ab2127b7afdeda33b",
  "value" : 100000000
}

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 will never arrive. Just update your order 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.