How to integrate

Go through the API documentation to know about the endpoints to integrate. This page talks about certain request parameters and the values they take.

Generating a new order

Before performing integration, please ensure that you have at least registered your testnet smart contract function with us. You must have received a smart contract config ID, which you need to pass in the smartContractFunctionId param.

One needs to call the Create Order endpoint to generate a new order and redirect the user to the hosted checkout URL to complete the journey. If you are integrating with our Web SDK, then you don't need to redirect your user. Instead a widget will open on top of your website and the user can engage with it until they complete the journey and close that widget.

Parameters required to execute the smart contract

You need to specify appropriate values for payment.payableCryptoSymbol, payment.payableCryptoContractAddress and network_params.networkName within the contractExecution object corresponding to the smart contract function you intend to call. Permissible values of these params are listed below.

payableCryptoSymbol	payableCryptoContractAddress	NetworkName
ETH	-	Ethereum
BNB	-	Binance Smart Chain

Currently, we do not support smart contracts which receive ERC20 / BEP20 tokens

Nivapay does not have semantic understand of what your smart contract function does. So depending on the function_args, only you would know how much compute intensive it will be and how much funds does it need for successful execution. Therefore, while generating an order please provide accurate values for function_args, payment.totalValue and network_params.customGasLimit because there will be minimal validation from our end.

If network_params.customGasLimit is skipped then we will use the default gas limit provided at the time of smart contract registration.

If the smart contract function does not require any funds to execute (or is not payable) then the entire payment object in the request can be skipped.

Parameters corresponding to payment to be done by the user

Permissible values for crypto_symbol, crypto_network and crypto_contract_address are listed below.

Symbol	Network	contract_address	Description
ETH	Ethereum	-	Ether, the native currency of Ethereum mainnet
BNB	Binance Smart Chain	-	BNB coin, the native currency of BSC mainnet

Currently, we do not support paying in ERC20 / BEP20 tokens

Once you specify these params accurately, the Create Order endpoint will do the job of back calculating the crypto amount required to successfully execute the entire order. This amount is shared with you in the endpoint's response and order.created webhook event. It will also be shown to the user on the order preview (first) page.

If you want to display this fiat amount pre-emptively to the user on your platform, then you can call the Generate Crypto Quote endpoint with the same set of params as discussed above. This endpoint returns the crypto_amount and allowed param, which tells that whether this amount is permissible to be paid. If allowed = FALSE, then message contains the detailed reason. This reason can be displayed to your user so that they can take necessary action.

User session validity

The hosted checkout URL when accessed by the user, generates a session for that order. The user can interact with the payment gateway screens to complete the journey during that session. However, once that session is closed or interrupted, it cannot be accessed again due to security reasons. A new order is required to be created to reattempt the transaction. In case the user has already made the payment, then they should wait for at least 2 hours and receive the final status update through email.