NFT Checkout

Create Order

POST https://api-ramp-nft.nivapay.com/merchant/hosted/nftCheckout/order

Merchant will call this endpoint to generate a new order. Merchant needs to redirect their user to the hosted checkout URL to complete the journey.

Headers

Name

Type

Description

X-API-KEY*

string

Merchant API key

Request Body

Name

Type

Description

order_fiat_symbol*

string

Symbol of the fiat currency in which the user would like to make payment

user_city

string

User’s residential city as per their identity document

user_addressLine2

string

User’s residential address (line 2) as per their identity document

user_addressLine1

string

User’s residential address (line 1) as per their identity document

user_dob

string

User’s date of birth in yyyy-mm-dd format

user_mobileNumber

string

Mobile number with ISD code prefixed e.g. +919876543210

user_last_name

string

Last name of your user

user_first_name

string

First name of your user

user_email_id

string (email)

Email ID of your user

merchant_webhook_url

string (url)

URL where you want to receive webhook events

merchant_redirect_url*

string (url)

URL to which the user will be redirected back at the end of the journey or when user cancels the session. For SDK integration, pass a dummy value.

merchant_txn_id

string

Internal ID provided by the merchant to track this order. This will be passed in the webhook events too.

merchant_user_id*

string

Internal ID provided by the merchant for the user

merchant_id*

string

ID assigned to the merchant by Nivapay

fiat_payment_method*

string (enum)

The payment method through which the user will pay

contractExecution*

json

Smart contract (SC) execution details

user_countryCode

string

ISO alpha2 code of the user’s residential country as per their identity document e.g. US, GB, etc. Refer to the full list: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2

user_postCode

string

User’s residential postal / zip code as per their identity document e.g. 90001

user_state

string

User’s residential state as per their identity document

network_params*

json

Contains network params

totalValue*

string

Total value of crypto to be paid to the function for this particular call (with above function_args). Value must not be in wei. You can use big decimals up to 18 digits.

payableCryptoContractAddress

string

If the virtual asset is an ERC20 / BEP20 token then it’s contract address to uniquely identify it

payableCryptoSymbol*

string

Symbol of the virtual asset to be paid to the SC function

payment

json

Required only if the SC function is expected to receive funds for its successful execution

function_args*

json

JSON containing the list of arguments (key-value pairs) this SC function takes. Arguments must adhere to the data type defined in the function ABI registered. Refer to the example below.

smartContractFunctionId*

string

ID of the SC function registered by the merchant

customGasLimit

string

Gas limit to override the defaultGasLimit specified at the time of registering your SC. If your SC function can vary in terms of computational effort, then it is strongly recommended to set this to avoid “insufficient gas fee” failures.

networkName*

string

Blockchain network on which this SC exists

param

type

description

required

order_id

string

Order ID assigned by Nivapay

yes

order_fiat_symbol

string

Fiat currency which the user will pay in

yes

fiat_payment_method

string (enum)

The payment method through which the user will pay

yes

order_fiat_amount

string

Amount in fiat to be paid to fulfil this order

yes

hash

string

Secret hash which allows you to access the gateway_url. It is already added as a query param to the gateway_url.

yes

gateway_url

string (url)

URL to the hosted checkout page where you need to redirect your user

yes

{
	"order_id": "VKP3OBZ3XG",
	"order_fiat_symbol": "EUR",
	"fiat_payment_method": "credit_debit_card",
	"order_fiat_amount": "4605",
	"hash": "1441a7909c087dbbe7ce59881b9df8b9",
	"gateway_url": "https://ramp-nft.nivapay.com/order?order_id=VKP3OBZ3XG&hash=1441a7909c087dbbe7ce59881b9df8b9"
}

{
	"order_id": "VKP3OBZ3XG",
	"order_fiat_symbol": "EUR",
	"fiat_payment_method": "credit_debit_card",
	"order_fiat_amount": "4605",
	"hash": "1441a7909c087dbbe7ce59881b9df8b9",
	"gateway_url": "https://ramp-nft.nivapay.com/order?order_id=VKP3OBZ3XG&hash=1441a7909c087dbbe7ce59881b9df8b9",
	"info": "Secret is not configured for creating X-Nivapay-Webhook-Signature for signing webhook events. There won't be any webhooks events in this order. Contact Nivapay for configuring the secret."
}

{
	"statusCode": 400,
	"timestamp": "2023-07-20T05:19:18.018Z",
	"message": "payableCryptoSymbol #USDC #Ethereum is invalid",
	"path": "/merchant/hosted/nftCheckout/order",
	"status": false
}

{
	"statusCode": 401,
	"timestamp": "2024-02-07T07:03:18.153Z",
	"message": "Unauthorized",
	"path": "/merchant/hosted/nftCheckout/order",
	"status": false
}

{
	"statusCode": 403,
	"timestamp": "2024-02-07T07:05:05.641Z",
	"message": "The functional args are not valid. Errors are - No sufficient functional arguments passed. Total arguments of 3 required",
	"path": "/merchant/hosted/nftCheckout/order",
	"status": false
}

{
	"statusCode": 403,
	"timestamp": "2024-02-07T07:08:34.227Z",
	"message": "The functional args are not valid. Errors are - tokenIds should be uint256[]",
	"path": "/merchant/hosted/nftCheckout/order",
	"status": false
}

Create Order request example (curl)

curl --location 'http://api-ramp-nft.nivapay.com/merchant/hosted/nftCheckout/order' \
--header 'Content-Type: application/json' \
--header 'x-api-key: 2b03fc9e-550e-4ffb-9136-92b627f9988b' \
--data-raw '{
    "order_fiat_symbol": "EUR",
    "fiat_payment_method": "credit_debit_card",

"contractExecution": {
		"smartContractFunctionId": "c6214bdf-051f-4000-8879-590d9b03d4af",
		"function_args": {
			"numberOfNFTs": "3",
			"tokenIds": ["1003","1004","1010"],
			"to_addr": "0x8e23ee67d1332ad560396262c48ffbb01f93d052"
		},
		"payment": {
			"payableCryptoSymbol": "ETH",
			"payableCryptoContractAddress": "",
			"totalValue": "1.98"
		},
		"network_params": {
			"networkName": "Ethereum",
			"customGasLimit": "1320837"
		}
	}

    "merchant_id": "M7184835",
    "merchant_user_id": "1xdeavy",
    "merchant_txn_id": "3589cb4a-0830-497d-a92d-c5178eb2ab9f",
    "merchant_redirect_url": "https://nivapay.com",
    "merchant_webhook_url": "https://hooks.nivapay.com/payment-services/",

    "user_email_id": "daves@yahoo.com",
    "user_first_name": "Dave",
    "user_last_name": "Smith",
    "user_mobileNumber": "+12025550164",
    "user_dob": "1994-08-26",
    "user_addressLine1": "2819 Brannon Street",
    "user_addressLine2": "",
    "user_city": "Los Angeles",
    "user_state": "California",
    "user_postCode": "90001",
    "user_countryCode": "US"
}'

Get Fiat currencies

GET https://api-ramp-nft.nivapay.com/merchant/hosted/nftCheckout/fiatCurrencies

Returns the list of fiat currencies along with the payment methods supported for on-ramping

Headers

Name

Type

Description

X-API-KEY*

string

Merchant API key

param

type

description

required

currencies

json array

Array containing the list of active fiat currencies

yes

symbol

string

ISO symbol of the fiat currency

yes

name

string

Name of the fiat currency

yes

supportedCountries

string array

List of countries supporting this currency. Values are in ISO alpha2 country codes.

yes

paymentOptions

json array

Array containing the list of active payment methods

yes

name

string

Name of the payment method available for this fiat

yes

string (enum)

Unique Code of the payment method

yes

icon

string (url)

Display icon for this payment method

yes

maxAmount

number (int)

Max amount which can be paid through this payment method for this fiat

yes

minAmount

number (int)

Min amount which can be paid through this payment method for this fiat

yes

{
	"currencies": [
		{
			"symbol": "GBP",
			"supportedCountries": [
				"GB"
			],
			"paymentOptions": [
				{
					"id": "gbp_bank_transfer",
					"name": "Instant Transfer",
					"icon": "https://assets.transak.com/images/fiat-currency/Faster_Payments_logo.svg",
					"minAmount": 16,
					"maxAmount": 59148
				},
				{
					"id": "pm_open_banking",
					"name": "Open Banking",
					"icon": "https://assets.transak.com/images/fiat-currency/nuvei_open_banking.svg",
					"minAmount": 24,
					"maxAmount": 59148
				},
				{
					"id": "credit_debit_card",
					"name": "Card Payment",
					"icon": "https://assets.transak.com/images/fiat-currency/visa_master_h.png",
					"minAmount": 4,
					"maxAmount": 4732
				},
				{
					"id": "apple_pay",
					"name": "Apple Pay",
					"icon": "https://assets.transak.com/images/fiat-currency/apple_logo.svg",
					"minAmount": 24,
					"maxAmount": 2366
				},
				{
					"id": "google_pay",
					"name": "Google Pay",
					"icon": "https://assets.transak.com/images/fiat-currency/google_pay.svg",
					"minAmount": 24,
					"maxAmount": 2366
				}
			]
		},
		{
			"symbol": "EUR",
			"supportedCountries": [
				"AT",
				"BE",
				"DK",
				"EE",
				"FI",
				"CY",
				"NOK",
				"FR",
				"CH",
				"DE",
				"HU",
				"PL",
				"GR",
				"IE",
				"IT",
				"LV",
				"LT",
				"LU",
				"MT",
				"NL",
				"PT",
				"SK",
				"SI",
				"ES",
				"SE",
				"AD",
				"GF",
				"GP",
				"MQ",
				"YT",
				"ME",
				"RE",
				"BL",
				"MF",
				"PM",
				"AX",
				"VA",
				"HR",
				"AS",
				"WS"
			],
			"paymentOptions": [
				{
					"id": "sepa_bank_transfer",
					"name": "Instant Transfer",
					"icon": "https://assets.transak.com/images/fiat-currency/sepa_en.png",
					"minAmount": 19,
					"maxAmount": 69391
				},
				{
					"id": "credit_debit_card",
					"name": "Card Payment",
					"icon": "https://assets.transak.com/images/fiat-currency/visa_master_h.png",
					"minAmount": 5,
					"maxAmount": 5551
				},
				{
					"id": "apple_pay",
					"name": "Apple Pay",
					"icon": "https://assets.transak.com/images/fiat-currency/apple_logo.svg",
					"minAmount": 28,
					"maxAmount": 2776
				},
				{
					"id": "google_pay",
					"name": "Google Pay",
					"icon": "https://assets.transak.com/images/fiat-currency/google_pay.svg",
					"minAmount": 28,
					"maxAmount": 2776
				}
			]
		},
		{
			"symbol": "USD",
			"supportedCountries": [
				"US",
				"PR",
				"VI",
				"GU",
				"TC",
				"MP"
			],
			"paymentOptions": [
				{
					"id": "credit_debit_card",
					"name": "Card Payment",
					"icon": "https://assets.transak.com/images/fiat-currency/visa_master_h.png",
					"minAmount": 5,
					"maxAmount": 3000
				},
				{
					"id": "apple_pay",
					"name": "Apple Pay",
					"icon": "https://assets.transak.com/images/fiat-currency/apple_logo.svg",
					"minAmount": 30,
					"maxAmount": 1500
				},
				{
					"id": "google_pay",
					"name": "Google Pay",
					"icon": "https://assets.transak.com/images/fiat-currency/google_pay.svg",
					"minAmount": 30,
					"maxAmount": 1500
				},
				{
					"id": "pm_cash_app",
					"name": " ",
					"icon": "https://assets.transak.com/images/fiat-currency/cash_app_icon.svg",
					"minAmount": 30,
					"maxAmount": 1000
				},
				{
					"id": "pm_jwire",
					"name": " ",
					"icon": "https://assets.transak.com/images/fiat-currency/wire_payment_icon.svg",
					"minAmount": 100,
					"maxAmount": 1000
				}
			]
		}
		// And more currencies
	]
}

{
	"statusCode": 401,
	"timestamp": "2024-02-07T07:38:18.431Z",
	"message": "Unauthorized",
	"path": "/merchant/hosted/nftCheckout/fiatCurrencies",
	"status": false
}

Generate Fiat Quote

POST https://api-ramp-nft.nivapay.com/merchant/hosted/nftCheckout/fiatQuote

Get the amount to be paid in fiat currency via the chosen payment method in order to fulfil the desired NFT Checkout order

Headers

Name

Type

Description

X-API-KEY*

string

Merchant API key

Request Body

Name

Type

Description

order_fiat_symbol*

string

Symbol of the fiat currency in which the user would like to make payment

merchant_id*

string

ID assigned to the merchant by Nivapay

fiat_payment_method*

string (enum)

The payment method through which the user will pay

contractExecution*

json

Smart contract (SC) execution details

network_params*

json

Contains network params

totalValue*

string

Total value of crypto to be paid to the function for this particular call (with above function_args). Value must not be in wei. You can use big decimals up to 18 digits.

payableCryptoContractAddress

string

If the virtual asset is an ERC20 / BEP20 token then it’s contract address to uniquely identify it

payableCryptoSymbol*

string

Symbol of the virtual asset to be paid to the SC function

payment

json

Required only if the SC function is expected to receive funds for its successful execution

function_args*

json

JSON containing the list of arguments (key-value pairs) this SC function takes. Arguments must adhere to the data type defined in the function ABI registered. Refer to the example below.

smartContractFunctionId*

string

ID of the SC function registered by the merchant

customGasLimit

string

networkName*

string

Blockchain network on which this SC exists

param

type

description

required

fiat_amount

string

Amount in fiat to be paid to fulfil this order

yes

payable_crypto_symbol

string

Virtual asset symbol in which funds will be paid to the SC

yes

payable_crypto_contract_address

string

Contract address is required, if symbol+network is not a native currency, else can be null

payable_crypto_network

string

Name of blockchain on which this crypto exists

yes

payable_crypto_amount

string

Crypto amount received when the above fiat amount is converted

yes

allowed

boolean

Whether the fiat amount is allowed for payment for the given fiat symbol and payment method combination. If this is false then the NFT Checkout order also won't get generated.

yes

message

string

Message explaining if it is not allowed or Bad request

{
	"fiat_amount": "4605",
	"fiat_symbol": "EUR",
	"payable_crypto_symbol": "ETH",
	"payable_crypto_contract_address": "",
	"payable_crypto_network": "Ethereum",
	"payable_crypto_amount": "2.01434",
	"allowed": true,
	"message": "Fiat quote generate successfully"
}

{
	"fiat_amount": "",
	"fiat_symbol": "EUR",
	"payable_crypto_symbol": "ETH",
	"payable_crypto_contract_address": "",
	"payable_crypto_network": "Ethereum",
	"payable_crypto_amount": "0.009",
	"allowed": false,
	"message": "Minimum ETH buy amount is 35 EUR"
}

{
    "statusCode": 401,
    "timestamp": "2024-02-07T07:09:42.190Z",
    "message": "Unauthorized",
    "path": "/merchant/hosted/nftCheckout/fiatQuote",
    "status": false
}

{
	"fiat_amount": "9478.03",
	"fiat_symbol": "EUR",
	"payable_crypto_symbol": "ETH",
	"payable_crypto_contract_address": "",
	"payable_crypto_network": "Ethereum",
	"payable_crypto_amount": "4.126",
	"allowed": false,
	"message": "Please place an order of less than 5575"
}

PreviousOnramp to Merchant Deposit NextNFT Minting

Last updated 11 months ago

Was this helpful?