# Receiving callbacks

The Apirone service receives payments in cryptocurrency. For creating accounts, wallets, addresses, or invoices a callback URL can be specified, calling which we will inform you about blockchain events.

When the Apirone service detects a transaction, the server will notify the specified callback URL with information about the event. You have to create a payment processing page to manage these callbacks.

All callbacks come from domain name callback.apirone.com

Also, if you have a firewall, please add the Apirone callback service domain name callback.apirone.com to the white list for getting callbacks correctly.
Otherwise, we cannot guarantee a proper callback to your host.

# Accounts, wallets and addresses

Generally, the Apirone service starts doing callbacks from 0 confirmations (a new unconfirmed transaction on the network).

If funds are forwarded to specified destinations, some additional info will be added to the callback data.

Warning: Do not top the up the balance or finish a customer’s order when you got an unconfirmed transaction. Scammers can do double spending (opens new window) and re-route this payment. Please finish an order after 1-3 network confirmations only. Callbacks will be sent until the *ok* response is received (HTTP status code 200, content type text/plain). That will mean the event proceeds successfully on your side.

If your server responds incorrectly or does not respond, the Apirone service will make new attempts for every new block within 255 confirmations for Bitcoin, Litecoin, Bitcoin cash, Doge and 20000 confirmations for Tron network.

Note: Due to the fast confirmation of blocks on the Tron network, we perform callbacks every 5 blocks.

# Transaction callback example

{
  "value": 30000,
  "input_address": "2N5DUsqXGdytkDsVRF5AQUnMi2s46Q3xRQr",
  "confirmations": 1,
  "input_transaction_hash": "7975e90fd581ace5f61e2b3d6dee926eab1ca635f923e8871cdf26a89c4d1cf0",
  "data": {
    "id": "test new bitcoin wallet"
  },
  "account": "apr-6da0dd459c0907e66fda52b8567b00e7",
  "currency": "tbtc",
  "transaction_hash": "1a16d74a5c6afd29a209242b825428efacccedb8e43da08703c3d2d73ebe4f51",
  "payment": "d5eb22388bc534a3f56fa6ac7ec9fc222392b6ed609febe71f8ca42c8681e7ed",
  "destinations": [
    {
      "address": "2MubB6DVoK9mzUffqb2WWkfdVCJfadaXqrs",
      "amount": 29895
    }
  ]
}

The following table lists all parameters that are sent in a typical callback request.

Parameter	Description	Required
`value`	Amount in specified units	✓
`input_address`	The generated cryptocurrency address to which a customer sent the payment	✓
`confirmation`	Number of accepted confirmations	✓
`input_transaction_hash`	The hash of the transaction sent to the generated input address	✓
`data`	Object of user parameters for the payment
`account`	Account Id	✓
`currency`	Currency type (btc, ltc, bch, doge, trx, usdt@trx, usdc@trx)	✓
`transaction_hash`	Forwarded transaction hash in the blockchain	*
`payment`	Payment id	*
`destinations`	Destinations	*

# Invoices

Every time an invoice's lifetime status changes, we provide a callback (if it has been specified during the invoice creation).

HTTP Method: POST
Content Type: application/json

Parameter	Description	Required
`account`	Account ID	✓
`invoice`	Invoice ID	✓
`status`	Invoice status	✓

# Invoice Status

Type	Description
`created`	Initial state when the invoice is created in the account
`paid`	As soon as the payment is received, the service compares the paid amount with the invoice requested amount. If the paid amount is equal to the amount expected, then the invoice is marked as paid
`partpaid`	Status will be returned for cases when a customer partially paid for the invoice. When an invoice is expired with the ‘partially paid’ status, check the amount arrived. The difference in some Satoshi may be unimportant for you. Otherwise ,contact the payer to send the amount remained or cancel the order and refund the money
`overpaid`	Status will be returned, if the payment from the customer exceeds the amount indicated in the invoice. This invoice is completed but you should contact the payer directly to refund the difference
`completed`	When the block with the invoice's transaction is added to the blockchain, the transaction received the required number of confirmations, the invoice gets this status
`expired`	The invoice has got the "expired" status, if the expiration date has arrived. But if the transaction has already been sent and stuck in the blockchain, the invoice will be closed after the payment confirmation.

# Simple Forwarding (V 1.0)

For simple forwarding addresses, a callback is sent strictly to a specified URL with the GET method. Also, some specific parameters will be added to the typical callback request arguments. Attention! In case the network fee is more than 50% of amount, we do not forward this payment until the network fee decreases. Otherwise, it’s inefficient.

# Simple forwarding callback example

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

Parameter	Description
`url`	URL with optional extra GET parameters (e.g. `invoice_id`, `order_id`, etc.). Also you can increase security by adding an optional parameter `secret` with some hash value and check this value when callback is received (more information see here (opens new window).
`value`	Amount in specified units
`input_address`	The generated cryptocurrency address to which a customer sent the payment
`confirmation`	Number of accepted confirmations. Default range is 0-6
`input_transaction_hash`	The hash of the customer's transaction sent to the generated input address
`destination_address`	Specified crypto address to which confirmed payments will be sent. For crypto forwarding only
`value_forwarded`	Forwarded amount. For crypto forwarding only

← Simple Forwarding Supported currencies →