# 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: | | 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 | {% tabs %} {% tab title="201: Created Order created successfully" %} {% tabs %} {% tab title="Body" %} {% endtab %} {% tab title="Example" %} {% code overflow="wrap" %} ```json { "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" } ``` {% endcode %} {% endtab %} {% endtabs %} {% endtab %} {% tab title="201: Created Webhook URL is passed but webhook secret is not set" %} {% tabs %} {% tab title="Example" %} {% code overflow="wrap" %} ```json { "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." } ``` {% endcode %} {% endtab %} {% endtabs %} {% endtab %} {% tab title="400: Bad Request Wrong crypto currency is provided" %} {% tabs %} {% tab title="Example" %} {% code overflow="wrap" %} ```json { "statusCode": 400, "timestamp": "2023-07-20T05:19:18.018Z", "message": "payableCryptoSymbol #USDC #Ethereum is invalid", "path": "/merchant/hosted/nftCheckout/order", "status": false } ``` {% endcode %} {% endtab %} {% endtabs %} {% endtab %} {% tab title="401: Unauthorized Invalid merchant API key" %} {% tabs %} {% tab title="Example" %} {% code overflow="wrap" %} ```json { "statusCode": 401, "timestamp": "2024-02-07T07:03:18.153Z", "message": "Unauthorized", "path": "/merchant/hosted/nftCheckout/order", "status": false } ``` {% endcode %} {% endtab %} {% endtabs %} {% endtab %} {% tab title="400: Bad Request Incorrect function args" %} {% tabs %} {% tab title="Example" %} {% code overflow="wrap" %} ```json { "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 } ``` {% endcode %} {% endtab %} {% endtabs %} {% endtab %} {% tab title="400: Bad Request Function args data type mismatch" %} {% tabs %} {% tab title="Example" %} {% code overflow="wrap" %} ```json { "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 } ``` {% endcode %} {% endtab %} {% endtabs %} {% endtab %} {% endtabs %}
Create Order request example (curl) ```json 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 | {% tabs %} {% tab title="200: OK Success" %} {% tabs %} {% tab title="Body" %} {% endtab %} {% tab title="Example" %} {% code fullWidth="false" %} ```json { "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 ] } ``` {% endcode %} {% endtab %} {% endtabs %} {% endtab %} {% tab title="401: Unauthorized Invalid merchant API key" %} {% tabs %} {% tab title="Example" %} {% code overflow="wrap" %} ```json { "statusCode": 401, "timestamp": "2024-02-07T07:38:18.431Z", "message": "Unauthorized", "path": "/merchant/hosted/nftCheckout/fiatCurrencies", "status": false } ``` {% endcode %} {% endtab %} {% endtabs %} {% endtab %} {% endtabs %} ## 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 | 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 | {% tabs %} {% tab title="200: OK Success" %} {% tabs %} {% tab title="Body" %} {% endtab %} {% tab title="Example" %} {% code overflow="wrap" %} ```json { "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" } ``` {% endcode %} {% endtab %} {% endtabs %} {% endtab %} {% tab title="200: OK Estimated fiat amount is less than the min amount set for that payment method" %} {% tabs %} {% tab title="Example" %} {% code overflow="wrap" %} ```json { "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" } ``` {% endcode %} {% endtab %} {% endtabs %} {% endtab %} {% tab title="401: Unauthorized Invalid merchant API key" %} {% tabs %} {% tab title="Example" %} {% code overflow="wrap" %} ```json { "statusCode": 401, "timestamp": "2024-02-07T07:09:42.190Z", "message": "Unauthorized", "path": "/merchant/hosted/nftCheckout/fiatQuote", "status": false } ``` {% endcode %} {% endtab %} {% endtabs %} {% endtab %} {% tab title="200: OK Estimated fiat amount is higher than the max amount set for that payment method" %} {% tabs %} {% tab title="Example" %} {% code overflow="wrap" %} ```json { "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" } ``` {% endcode %} {% endtab %} {% endtabs %} {% endtab %} {% endtabs %} --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://nivapay.gitbook.io/product-and-api-documentation/api-documentation/nft-checkout.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.