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.

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",
  "transaction_hash": "0e3e2357e806b6cdb1f70b54c3a3a17b6714ee1f0e68bebb44a74b1efd512098",
  "value" : 100000000,
  "value_forwarded": 99979800,
  "destinations": 
  [
    {"address": "1apiKcJM95jENZeom2dQo8ShK7dUQkRaS", "amount": 20000000},
    {"address": "1apimr7q2cL3xPma8SfiDPyTdWSHXSEyB", "amount": 30000000},
    {"address": "1ApiwpetcWnBbkpU7cb7biPfc6Tiucasf8", "amount": 49979800}
  ]
}
Parameters and variables

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

Parameter Variables 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
{transaction_hash}
string, 64 chars
Transaction Hash
The transaction hash of forwarded payment to your destination bitcoin address.
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  
{destinations}
The array of destination addresses with amounts where confirmed payments will be forwarded. 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.

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.