Payment forwarding API

  • Description
  • API endpoint
  • Request limits
  • Service fee
  • Payment forwarding
    • post Create forwarding address
    • get Payment address state
    • get List of payment address transactions
    • post Callback handler
  • Callback log
    • get Callback log for payment address
    • get Callback log for payment
  • Domain authorization
    • post Create domain authorization code
    • post Create domain access token
  • Domain statistics
    • get Domain statistics
    • get List of created addresses
    • get List of domain transactions
    • get Daily domain statistics

Payment forwarding API

version 1

API endpoint

For all supported cryptocurrencies, APIs are available for Mainnet, Testnet, and the Tor network. Created addresses in the same network can be used for all supported cryptocurrencies in this network (ex. ETH and USDT-ERC20, USDC-ERC20). For testnet networks available coins faucet and explorers. For Ethereum testnet please use Sepolia Network.

Mainnet URL: https://api.bitaps.com/{currency}/v1/
Testnet URL: https://api.bitaps.com/{currency}/testnet/v1/
Tor Mainnet URL: http://bitaps4nifcusilt.onion/{currency}/v1/

Available currency value: btc, eth, ltc, usdt-erc20, usdc-erc20.

Request limits

For API, restrictions of requests by IP addresses apply. Standard limit 60 requests within 5 seconds for a single IP address. If you need more requests, then you need to purchase an API token. For questions about obtaining a token API, contact support@bitaps.com. If the limit is exceeded, a page with the status 429 to many requests is given in response to the request. If an error is received, you should wait for the time limit to be restored, otherwise the IP address will be blocked for 3 minutes. The current status of the limits can be found in the response headers Ratelimit-Remaining and Ratelimit-Reset .

Service fee

The service charge a fixed commission from each payment processed. The miners commission paid when sending the payment is included in the service fee.

Commissions:

CurrencyService fee Min. TX Value
Bitcoin0.0002 BTC > 0.00000546 BTC + Service fee
Ethereum0.002 ETH> 0.001 ETH + Service fee
Litecoin0.0004 LTC > 0.00000546 LTC + Service fee
USDT-ERC2010 USDT> 1 USDT + Service fee
USDC-ERC2010 USDC> 1 USDC + Service fee

Payment forwarding

Created addresses for forwarding have no limit on the number of processed payments, as well as no limit on time of action. In blockchains with the UTXO architecture (btc, ltc), the transaction hash and the out number in the transaction are considered as a unique payment identifier. For blockchains with Account based (eth) architecture, a unique payment identifier is considered a transaction hash. When transferring payments for the same address, payout can be consolidated into one transaction but notifications will be received separately for each payment. The payment transaction is a pair of transaction hash + out number (for eth only hash). For each generated address, it is possible to query the current status and statistics, as well as a list of all transactions received by the address. Access to statistics is divided into public and private. Access to the private part of the information is provided through authorization using the request header Payment code or Access-Token for domain of the callback link. For callback link domain, the general statistics is accumulated. Domain statistics are accessed via Access-Token .

Create forwarding address
post /create/payment/address

To create a payment address, you must: specify the address for payment forwarding, a link to the payment notification (optional) and the number of confirmations required for accept the payment and notifications (optional, the default value is set if not specified). Information about the new payments and payment state will be sent to the specified notification link. For Bitcoin Cash and Litecoin, the response to the request also contains the address in the legacy format (the outdated address format). Both address formats can be used to receive payments and are correctly processed by service.

Request body
application/json
JSON object
    forwarding_address
string
Address for payout
required
    callback_link
string
Link for payment notification handler
optional
    confirmations
integer
Number of confirmations required for the payment
optional
Responses
application/json
200
payment_code
string
Payment code, used to authenticate payment notifications and receive statistics to the address (this code should not be disclosed for security reasons)
required
callback_link
string
Link for payment notification handler
optional
forwarding_address
string
Address for payout
required
domain_hash
string
The unique identifier for the domain of the callback handler.
optional
confirmations
integer
Number of confirmations required for the payment
required
address
string
Payment address
required
legacy_address
string
Payment address in outdated format
optional
domain
string
Domain derived from the payment notification link
optional
invoice
string
Public payment address identificator
required
currency
string
Currency
required
Payment address state
get /payment/address/state/{address}

Request status and statistics of the payment address. The request without authorization returns only public information, full information is available with request header Payment-Code or Access-Token.

Headers parameters
Payment-Code
string
payment code
optional
Access-Token
string
Domain access token
optional
Path parameters
address
string
Payment address
required
Responses
application/json
200
callback_link
string
Link for payment notification handler
optional
pending_received
integer
Amount of pending payments
required
fee_paid
integer
Total number of fee paid for this address
required
create_date
integer
Address date of creation
required
invalid_transaction_count
integer
Invalid transaction count
required
paid
integer
Payout amount
required
received
integer
Total amount of payments received
required
forwarding_address
string
Address for payout
required
confirmations
integer
The number of confirmations required to confirm the payment
required
address
string
Payment address
required
legacy_address
string
Payment address in outdated format
optional
type
string
Тип платежного адреса
required
transaction_count
integer
The number of transactions received
required
pending_paid
integer
Pending payout amount
required
pending_transaction_count
integer
Pending payout count
required
currency
string
Addresss currency
required
create_date_timestamp
number
Address date of creation in unix timestamp format
required
List of payment address transactions
get /payment/address/transactions/{address}

Request list of payment address transactions. The request without authorization returns only public information, full information is available with request header Payment-Code or Access-Token.

Headers parameters
Payment-Code
string
Payment code corresponding to address
optional
Access-Token
string
Domain access token
optional
Path parameters
address
string
Payment address
required
GET parameters
from
number
From timestamp
optional
to
number
Until timestamp
optional
limit
number
Limit per page
optional
page
number
Page number
optional
Responses
application/json
200
next_page
boolean
Next page indicator
required
address
string
Payment address
required
tx_list
array
List of transactions
optional
   payout
object
optional
      miner_fee
integer
Paid miner fee
optional
      tx_hash
string
Payout transaction hash
required
      service_fee
integer
Paid service fee
required
      outs
array
optional
         amount
integer
payout amount
required
         tx_out
integer
Transactions output for payout
optional
         address
string
Address for payout
required
   timestamp
integer
Transaction time in unix timestamp
required
   time
string
Transaction time in ISO UTC 0
required
   status
string
Transaction status
required
   hash
string
Transaction hash
required
   amount
integer
Transaction amoint in satoshi/wei/lite
required
   tx_out
integer
Transaction output
required
   notification
string
Notification status
required
Callback handler
post /callback/handler/example

Description of the payment notification handler with the description of the incoming POST parameters. Payment notifications are received when the following events occur.:

  • new payment detected
  • count of confirmations changed
  • count of payment confirmations has reached the specified value and the payment is confirmed
  • payout has been sent
  • payout confirmed

For example, if a payment address is created with 2 confirmations, it will receive the following notifications: unconfirmed, pending [1/2], confirmed, payout sent, payout confirmed. Event notifications payout sent,payout confirmed, may come before the event confirmed, in these notifications field confirmations should be ignored.

The logic for processing payment notifications should be as follows. Each payment address corresponds to a confirmed and unconfirmed balance. N - the number of required confirmations.

Processing incoming notifications:

  • confirmations = 0 check if there is a payment in the database (unique payment identifier = transaction hash + out number), if not exist, then we insert it to the database and add an unconfirmed balance to the user
  • 0 < confirmations < N check if there is a payment in the database, if not, then insert it in the database and add an unconfirmed balance to the user
  • confirmations >= N check if there is a payment in the database, if there is one and it is not processed, reduce the unconfirmed balance, increase the confirmed one and mark the payment as processed. If there is no payment, then add it as processed, add the confirmed balance to the user.
Acknowledgment

Payment notifications have logic to protect against failure. As a confirmation that the notification has been received, the service expects to receive a response in the form of a code invoice code in response body for each http request.

In case no correct answer, notifications will be repeated with each new block within 24 hours. IP addresses from which notifications are sent are available via dns request to the domain name callback.bitaps.com. If the answer is not successful, repeated attempts are made from different IP addresses. To stop sending notifications, notification handler should reply with correct response to any notification with the number of payment confirmations greater than or equal to the specified value when generating a payment address.

Tor

Tor notifications supported

Responses
text/plain
200
event
string
Notification event [unconfirmed, pending [N/M], confirmed, payout sent, payout confirmed]
optional
address
string
Payment address received payment
optional
amount
string
Payment amount
optional
currency
string
Currency
optional
confirmations
string
Payment transaction confirmations
optional
tx_hash
string
Payment transaction hash
optional
tx_out
string
Payment transaction output
optional
invoice
string
Invoice code
optional
code
string
Payment code
optional
payout_tx_hash
string
Payout transaction hash
optional
payout_tx_outs
string
List of outputs with payout (btc, ltc)
optional
payout_miner_fee
string
deprecated
optional
payout_service_fee
string
service fee
optional
received_tx
string
Total transactions received by address
optional
received_amount
string
Total amount received by address
optional
pending_received_tx
string
Unconfrimed transaction count
optional
pending_received_amount
string
Total unconfirmed amount
optional

Callback log

When sending a notification of a new payment or a change in the status of a payment, the response received is logged. The log contains the IP address from which the notification was made, the HTTP response status and 256 characters of the received response body. To access the logs, authorization is required by request header Payment Code or Access-Token.

Callback log for payment address
get /payment/address/callback/log/{address}

Callback log for payment address. Authorization required by request headers Payment-Code or Access-Token.

Headers parameters
Payment-Code
string
payment code
optional
Access-Token
string
Domain access token
optional
GET parameters
limit
number
limit per page
optional
page
number
Page number
optional
Responses
application/json
200
callback_list
array
Log records list
optional
   status
['string', 'array']
Payment status at the time of sending the payment notification
optional
   response
object
Response logs
optional
      request_status
integer
HTTP status
optional
      request_ip_log
array
optional
         ip
string
IP from which the notification was sent
optional
         status
integer
Status
optional
         time
integer
Request time in milliseconds
optional
      request_response
string
Response string
optional
      request_success
boolean
Notification status
optional
      request_id
integer
Notification id
optional
      request_error
string
Notification error
optional
   time
string
The time of sending the notification in ISO UTC 0 format
optional
   timestamp
integer
The time of sending the notification in unix timestamp format
optional
   event
string
Notification event
optional
   confirmations
integer
Transaction confirmation count
optional
   outpount
string
Unique payment id (transaction hash : out number)
optional
   response_status
string
Notification handler response status
optional
   amount
integer
Payment amount
optional
next_page
boolean
Next page indicator
optional
Callback log for payment
get /payment/callback/log/{tx_hash}/{output}

Callback logs for payment transaction hash. Authorization required by request headers Payment-Code or Access-Token.

Headers parameters
Payment-Code
string
payment code
optional
Access-Token
string
Domain access token
optional
GET parameters
limit
number
Limit per page
optional
page
number
Page number
optional
Responses
application/json
200
callback_list
array
Log records list
optional
   status
['string', 'array']
Payment status at the time of sending the payment notification
optional
   response
object
Response logs
optional
      request_status
integer
HTTP status
optional
      request_ip_log
array
optional
         ip
string
IP from which the notification was sent
optional
         status
integer
Status
optional
         time
integer
Request time in milliseconds
optional
      request_response
string
Response string
optional
      request_success
boolean
Notification status
optional
      request_id
integer
Notification id
optional
      request_error
string
Notification error
optional
   time
string
The time of sending the notification in ISO UTC 0 format
optional
   timestamp
integer
The time of sending the notification in unix timestamp format
optional
   event
string
Notification event
optional
   confirmations
integer
Transaction confirmation count
optional
   outpount
string
Unique payment id (transaction hash : out number)
optional
   response_status
string
Notification handler response status
optional
   amount
integer
Payment amount
optional
next_page
boolean
Next page indicator
optional

Domain authorization

If callback link is specified for the payment, statistics by the domain name is collected. Statistics collects information on the number of generated addresses and incoming transactions. To gain access to statistics, you must verify domain ownership and get Access-Token .

Create domain authorization code
post /create/domain/authorization/code

To access the statistics on payments and addresses created for the domain, you need to create an access token. To create a token, you must authorize the request using the callback link. The first step is the generation of an authorization code for the specified link.

Request body
application/json
JSON object
    callback_link
string
Link for payment notification handler
optional
Responses
200
domain
string
Domain
optional
authorization_code
string
Authorization code
optional
domain_hash
string
Unique domain ID
optional
Create domain access token
post /create/domain/access/token

To get access token, you need to add the output of the authorization code as plain / text when you receive a GET request through callback link.

Request body
application/json
JSON object
    callback_link
string
Link for payment notification handler
optional
Responses
application/json
200
domain
string
optional
access_token
string
optional
domain_hash
string
optional

Domain statistics

Domain statistics
get /domain/state/{domain_hash}
A request header Access-Token is required.
Headers parameters
Access-Token
string
Domain access token
required
Responses
default
address_count
integer
Count of created addresses
optional
pending_received
integer
Amount of pending payments
optional
status
string
Domain status
optional
service_fee
integer
Service fee for domain
optional
paid
integer
Payout amount
optional
success_callbacks
integer
Success callback notifications count
optional
failed_callbacks
integer
Failed callback notificatins count
optional
transaction_count
integer
Transactions count
optional
domain
string
Domain
optional
pending_transaction_count
integer
Unconfirmed transactions count
optional
invalid_transaction_count
integer
Invalid transactions count
optional
fee_paid
integer
Total fee paid
optional
pending_paid
integer
Amount of pending payout
optional
received
integer
Total amount of payments received
optional
create_date
integer
Registration date
optional
List of created addresses
get /domain/addresses/{domain_hash}
A request header Access-Token is required.
Headers parameters
Access-Token
string
Domain access token
required
GET parameters
from
string
optional
to
string
optional
limit
string
optional
page
string
optional
Responses
application/json
default
next_page
boolean
optional
address_list
array
optional
   received_tx
integer
optional
   received_amount
integer
optional
   pending_paid_amount
integer
optional
   invioce
string
optional
   address
string
optional
   fee_paid
integer
optional
   pending_received_tx
integer
optional
   invalid_tx
integer
optional
   pending_received_amount
integer
optional
   paid_amount
integer
optional
   time
string
optional
   timestamp
integer
optional
List of domain transactions
get /domain/transactions/{domain_hash}
A request header Access-Token is required.
Headers parameters
Access-Token
string
Domain access token
required
GET parameters
from
string
optional
to
string
optional
limit
string
optional
page
string
optional
type
string
optional
Responses
default
transaction_list
array
optional
   timestamp
integer
optional
   invioce
string
optional
   time
string
optional
   tx_hash
string
optional
   notification
integer
optional
   tx_out
integer
optional
   address
string
optional
   payout
object
optional
      outs
array
optional
         tx_out
integer
optional
         address
string
optional
         amount
integer
optional
      tx_hash
string
optional
      miner_fee
integer
optional
      service_fee
integer
optional
   status
integer
optional
next_page
boolean
optional
Daily domain statistics
get /domain/daily/statistic/{domain_hash}
A request header Access-Token is required.
Headers parameters
Access-Token
string
Domain access token
required
GET parameters
from
string
optional
to
string
optional
limit
string
optional
page
string
optional
Responses
default
next_page
boolean
optional
day_list
array
optional
   invalid_count
integer
optional
   pending_received_count
integer
optional
   pending_paid_count
integer
optional
   pending_received_amount
integer
optional
   datestamp
integer
optional
   address_count
integer
optional
   received_amount
integer
optional
   success_callbacks
integer
optional
   failed_callbacks
integer
optional
   received_count
integer
optional
   paid_count
integer
optional
   service_fee_paid_amount
integer
optional
   date
string
optional
   pending_paid_amount
integer
optional
   paid_amount
integer
optional