API Integration
Bitnovo crypto payment gateway
Designed to be use in two different ways:
Redirect Gateway: Only available for online payments. The user is redirected to the Bitnovo Pay gateway where the user is assisted to make the crypto payment. Depending on the merchant configuration is returned to the merchant environment when the transaction is detected or confirmed.
API Gateway: Available for online and offline payments. The merchant/payment provider receives the payment information from Bitnovo and it is shown by the merchant to the final user.
Redirect Gateway
There are also two options to use the gateway in this mode:
Indicating the cryptocurrency symbol
The process begins when the merchant calls the currencies_list endpoint. To ensure that the currency it wants to show it is available at this moment. Once confirmed, the merchant calls the orders_create endpoint. Sending the fiat amount, the cryptocurrency symbol, OK and KO URLs and an optional description for the payment. Then, Bitnovo Pay answers with the redirection url and the merchant moves the user to the redirection url. Once the user is redirected, it will try to make the payment in Bitnovo Pay gateway. When the user ends the payment process, he is redirected to the OK URL (successful payments url) or KO URL (unsuccessful payments url) depending on the result.
Not indicating the cryptocurrency symbol
The process begins when the merchant calls the orders_create endpoint. Sending the fiat amount, OK and KO URLs and an optional description for the payment. Then, Bitnovo Pay answers with the redirection url and the merchant moves the user to the redirection url. Once the user is redirected, it will try to make the payment in Bitnovo Pay gateway. When the user ends the payment process, he is redirected to the OK URL (successful payments url) or KO URL (unsuccessful payments url) depending on the result.
In both cases, the merchant will be notified of the status changes through the notify_merchant webhook.
API Gateway
The process begins when the merchant calls the orders_create endpoint. Sending the fiat amount, the cryptocurrency symbol (optional) and a description if needed. Then, Bitnovo answers with the payment information.
The payment information has to be shown to the user by the merchant, during the payment process Bitnovo will inform the merchant about the process status updates by the notify_merchant webhook.
Important Payment Status
"AC"
"Awaiting Completion" + 'safe'= True
For this payment status you should check the parameter 'safe'. If 'safe'= True, the cryptocurrency amount has been detected in the meempool and will be confirmed shortly. This happens just with UTXO cryptocurrencies such as Bitcoin if the transaction fee is optimal and RBF (Replace by fee) is not activated. . The merchant can take this status as "Completed" for a faster flow.
"CO"
"Completed"
The cryptocurrency amount has at least 1 confirmation in the blockchain.
"OC"
"Out of Condition"
The cryptocurrency amount is insufficient, so the payment is incomplete. In this case the merchant can ask for the rest of the payment via Bitnovo (or other method) or make a refund. The merchant must check the parameter 'received_amount' to know the amount remaining.
“RF”
“Refunded”
Once the payment is “Completed” or “Out of Condition”, it can be refunded via API or Dashboard.
Other payment status
"NR"
"Not Ready"
The payment didn't receive a cryptocurrency symbol yet. (Redirect Gateway Only)
"PE"
"Pending"
The payment is waiting to receive the cryptocurrency amount.
"AC"
"Awaiting Completion" + 'safe'= False
For this payment status you should check the parameter 'safe'. If 'safe'= False, the cryptocurrency amount has been detected in the meempool and must wait to get confirmed. This happens just with UTXO cryptocurrencies such as Bitcoin if the transaction fee is lower than market and/or RBF (Replace by fee) is activated. The merchant/client must wait for the payment to be switched "Completed" after confirmation.
"IA"
"Insufficient Amount"
The cryptocurrency amount is lower than the required. The client stills has time to pay the rest and satisfies the amount required
"CA"
"Cancelled"
The payment was expired for more than 24 hours or the client canceled it.
"EX"
"Expired"
The payment didn't receive any crypto during the expiration time (15/60 minutes).
"FA"
"Failed"
Payment has failed because the transaction didn't confirm.
Payment flow
As a Merchant you can implement the following payment flow:
NR (Not Ready) / PE (Pending) / AC (Awaiting Completion) + safe=False
Pending
CO (Completed) / AC (Awaiting Completion) + safe=True
Processing
CA (Cancelled) / EX (Expired)
Cancelled
FA (Failed) / OC (Out of Condition)
Failed
RF (Refunded)
Refunded
Endpoints
Here you can find the swagger API documentation to integrate Bitnovo Pay into any platform.
Última actualización