Payment forwarding API is a tool for organizing the acceptance of cryptocurrency payments by the payment transfer method. This API is a low-level tool that allows you to integrate cryptocurrency payments (BTC, BCH, ETH, LTC) for various types of applications, such as web sites, mobile and desktop applications.
Accepting payments from users is a transfer of payments in favor of the seller and matching the payment received with the order number or user account.
Cryptocurrencies are decentralized systems in which only the owner of the wallet has the ability to initiate a payment. In connection with this feature, payment every time implies waiting for a payment from the user, since automatic debiting is impossible. It is also not possible to identify the payment by the sender's address, since the sender's address may not belong to the user if paid through the stock exchange or the centralized service of the wallets.
To solve the problem of identification and matching of payments, the method is used when a unique address is generated for each expected payment in the corresponding cryptocurrency. In the case of a payment related to goods or services, the generated address is associated with an invoice / order number. For the case of refill the user's balance, the generated address is associated with the user account.
The resulting set of generated addresses is monitored for payments. Received payments are further consolidated and forwarded to the main seller wallet.
The Payment Forwarding API is a ready solution for generating temporary addresses with specified rules for forward payments to the seller’s wallet and a payment notification system. Payment forward is carried out to achieve confirmation of payments in the blockchain. Payment notification is sent to the merchant's server and have fault tolerance algorithm. Addresses can be used an unlimited number of times, which allows you to associate the generated address with a user account and receive payments in its favor.
When transferring a payment, a fixed service fee is charged, which includes the miners commission to pay for the payment transfer transaction. The service fee is described in detail in section Service fee.
Read more about the payment notification system in the section Callback handler.
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 firstname.lastname@example.org. 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 .
The service charge a fixed commission from each payment processed. The miners commission paid when sending the payment is included in the service fee.
|Bitcoin cash||0.0004 BCH|
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, bch, 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 ethereum, 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 .
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 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.
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.
Description of the payment notification handler with the description of the incoming POST parameters. Payment notifications are received when the following events occur.:
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:
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
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. Authorization required by request headers Payment-Code or Access-Token.
Callback logs for payment transaction hash. Authorization required by request headers Payment-Code or Access-Token.
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.
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.