# 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.

# 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. 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.

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

  • Source Domain Name: callback.apirone.com

# 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
transaction_hash Forwarded transaction hash in the blockchain *
payment Payment id *
destinations Destinations *

|*|- For crypto forwarding only

# 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.

  • Source IP: callback.apirone.com

# Simple forwarding callback example

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
Parameter Description Required
url URL with optional extra GET parameters
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 *
value_forwarded Forwarded amount *

* For crypto forwarding only

# 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
overpaid Status will be returned, if the payment from the customer exceeds the amount indicated in the invoice
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