--- title: Create Crypto Checkout Order slug: create-crypto-checkout-order docTags: createdAt: 2025-05-02T10:40:00.252Z --- This API creates a payin order where user can deposit digital assets to wallet address provided by the application. It accepts `address`, `currency` and `amount`. On creating an order a dynamic `token` is returned from this api which is required to be passed [openCryptoCheckout()](docId\:Wr9g8-0vvAo95lsm3g1ye) This api requires access token that can be generated using [Access Token](docId\:lq-v6fF_2i-h1O3XD5KKA) API. :::ApiMethodV2 ```json { "name": "Create Crypto Order", "method": "POST", "url": "https://your-hostname.pay3.app/v1/client/crypto-checkout/create-order", "description": "Create an order with payin details from application's backend", "tab": "examples", "examples": { "languages": [ { "id": "nyfSHp7J-NrsuqTH3FW7t", "language": "curl", "code": "curl --location 'https://your-hostname.pay3.app/v1/client/crypto-checkout/create-order' \\\n--header 'signature': \"generated-signature\"\\\n--header 'access-token' : \"dynamic-access-token\" \\\n--header 'Accept: application/json' \\\n--header 'Content-Type: application/json' \\\n--data '{\n \"requestId\":\"input-request-id\",\n \"address\":\"input-destination-address\",\n \"currency\":\"currency-id\",\n \"amount\":\"input-amount-in-eth-or-btc\",\n \"clientId\":\"your-client-id\"\n}'", "customLabel": "amount" }, { "id": "wQGcNgsjTaxg3bJeZn3f2", "language": "curl", "code": "curl --location 'https://your-hostname.pay3.app/v1/client/crypto-checkout/create-order' \\\n--header 'signature': \"generated-signature\"\\\n--header 'access-token' : \"dynamic-access-token\" \\\n--header 'Accept: application/json' \\\n--header 'Content-Type: application/json' \\\n--data '{\n \"requestId\":\"input-request-id\",\n \"address\":\"input-destination-address\",\n \"currency\":\"currency-id\",\n \"fiatAmount\":\"10.00\",\n \"fiatCurrency\":\"fiat-currency-id\",\n \"clientId\":\"your-client-id\"\n}'", "customLabel": "fiatAmount" }, { "id": "1UznSlcEst18mwFcilRCg", "language": "curl", "code": "curl --location 'https://your-hostname.pay3.app/v1/client/crypto-checkout/create-order' \\\n--header 'signature': \"generated-signature\"\\\n--header 'access-token' : \"dynamic-access-token\" \\\n--header 'Accept: application/json' \\\n--header 'Content-Type: application/json' \\\n--data '{\n \"requestId\":\"input-request-id\",\n \"address\":\"input-destination-address\",\n \"currency\":\"currency-id\",\n \"fiatAmount\":\"10.00\",\n \"fiatCurrency\": \"usdc_ethereum\",\n \"clientId\":\"your-client-id\",\n \"otherChainAddresses\": {\n \"polygon\": \"polygon-address\",\n \"tron\": \"tron-address\"\n }\n}'", "customLabel": "otherChainAddresses" } ], "selectedLanguageId": "1UznSlcEst18mwFcilRCg" }, "results": { "languages": [ { "id": "VQyRchSR38UbBEhATUpjh", "language": "200", "customLabel": "", "code": "{\n \"token\": \"generated-token-id\",\n \"requestId\": \"input-request-id\",\n \"requestInfoData\": {\n \"amount\": \"crypto-amount-in-eth\",\n \"address\": \"input-destination-address\",\n \"clientId\": \"your-client-id\",\n \"signature\": \"generated-signature\",\n \"currency\": \"currency-id\",\n \"type\": \"CRYPTO-CHECKOUT\"\n }\n}" }, { "id": "tIvoQbUSKGnrqallvNDVQ", "language": "401", "customLabel": "", "code": "{\n error: {\n code: '7001',\n message: 'Order already exists for given requestId'\n }\n}" } ], "selectedLanguageId": "VQyRchSR38UbBEhATUpjh" }, "request": { "pathParameters": [], "queryParameters": [], "headerParameters": [ { "name": "signature", "kind": "required", "type": "string", "description": "Signature generated with sha256 followed by base64 encoding. Check below section for more details", "children": [] }, { "name": "access-token", "kind": "required", "type": "string", "description": "Access token received from Access token API. You can reuse the access token across multiple API calls till it is expired", "children": [] } ], "bodyDataParameters": [ { "name": "requestId", "kind": "required", "type": "string", "description": "Identifier that is created by client application's backend. This will be passed in relevant events and webhooks from Pay3 to Application", "children": [] }, { "name": "address", "kind": "required", "type": "string", "description": "The address is your destination wallet address where funds will be sent after the transaction is confirmed. Use a wallet that supports the selected currency and blockchain. Copy the address from your wallet’s Receive section; never type it manually to avoid irreversible errors.", "": "The address is your destination wallet address where funds will be sent after the transaction is confirmed. Use a wallet that supports the selected currency and blockchain. Copy the address from your wallet’s Receive section; never type it manually to avoid irreversible errors." }, { "name": "currency", "kind": "required", "type": "string", "description": "The currency is Pay3's unique string ID denoting the token that needs to be purchased. Example value are btc_bitcoin, usdt_polygon, uni_eth. " }, { "name": "amount", "kind": "optional", "type": "string", "description": "The amount in ethereum / btc user needs to pay. The API expects either this parameter or fiatAmount & fiatCurrency parameter.", "children": [] }, { "name": "clientId", "kind": "required", "type": "string", "description": "Client id. Application's identifier", "children": [] }, { "name": "fiatAmount", "kind": "optional", "type": "string", "description": "Amount in Fiat say USD (eg: 10.50). This parameter is required when amount is not passed. Example values for ten dollar fifty cents is 10.50.", "children": [] }, { "name": "fiatCurrency", "kind": "optional", "type": "string", "description": "Fiat currency code is Pay3's unique string ID denoting the fiat currency. This parameter is required along with fiatAmount when amount is not passed. Pay3 uses current exchange rate to translate fiatAmount to amount.\nSupported fiat currencies are usd_usa, gbp_gb and eur_eu.", "children": [] }, { "name": "mode", "kind": "optional", "type": "string", "description": "When the mode is set to \"returnUrl\", the API response includes an additional field \"url\", which provides a direct checkout page link for accepting crypto payments. \n\nWhen the mode is set to \"returnAddress\" . the API response includes an additional field \"paymentAddress\" , which provides a wallet address that can be used by you to accept payment for the particular order. Please note that an \"expiryTs\" is also provided in this case, users must make payment to the address assigned within the order expiry time.\n\nThe supported values for mode are \"returnUrl\" , \"returnAddress\".\n", "": "When the mode is set to \"returnUrl\", the API response includes an additional field \"url\", which provides a direct checkout page link for accepting crypto payments. \n\nWhen the mode is set to \"returnAddress\" . the API response includes an additional field \"paymentAddress\" , which provides a wallet address that can be used by you to accept payment for the particular order. Please note that an \"expiryTs\" is also provided in this case, users must make payment to the address assigned within the order expiry time.\n\nThe supported values for mode are \"returnUrl\" , \"returnAddress\".\n" }, { "name": "callbackUrl", "kind": "optional", "type": "string", "description": "Application can provide a url in this parameter. After completion of the transaction, user will be redirected to this url. An additional parameter data query parameter will be added to the url. ", "": "callbackUrl" }, { "name": "lang", "kind": "optional", "type": "string", "description": "This parameter specifies the language preference for the Pay3 SDK. The strings used follow two letter language code as in ISO 639-1. Example pt for Portuguese, en for English.", "": "lang" }, { "name": "otherChainAddresses", "kind": "optional", "type": "object", "description": "The \"otherChainAddresses\" parameter defines wallet addresses for alternate blockchain networks when the user switches network in the payment widget. Do not include the address specified in the primary address parameter here.\n\nFor example, for USDC on Ethereum (currency = usdc_ethereum and address = 0x1234...), you can specify alternative addresses for Tron and Polygon networks like so:\n\notherChainAddresses = {\n \"tron\": \"Txabc123...\",\n \"polygon\": \"0x2345...\"\n} \n\nWhen using this parameter, set payment by fiat with \"fiatAmount\" and \"fiatCurrency\" instead of using the \"amount\" parameter.\n\nThis automatically send payments to the correct destination wallet based on the network selected by the user.", "": "The \"otherChainAddresses\" parameter defines wallet addresses for alternate blockchain networks when the user switches network in the payment widget. Do not include the address specified in the primary address parameter here.\n\nFor example, for USDC on Ethereum (currency = usdc_ethereum and address = 0x1234...), you can specify alternative addresses for Tron and Polygon networks like so:\n\notherChainAddresses = {\n \"tron\": \"Txabc123...\",\n \"polygon\": \"0x2345...\"\n} \n\nWhen using this parameter, set payment by fiat with \"fiatAmount\" and \"fiatCurrency\" instead of using the \"amount\" parameter.\n\nThis automatically send payments to the correct destination wallet based on the network selected by the user.", "children": [], "schema": [] }, { "name": "payerEmail", "kind": "optional", "type": "string", "description": "Pass the email for the user (uniqueId) to identify and map the orders against the user.\n\nIf both \"userId\" and \"payerEmail\" are provided in the request, userId takes precedence and is used as the primary identifier.", "": "Pass the email for the user (uniqueId) to identify and map the orders against the user.\n\nIf both \"userId\" and \"payerEmail\" are provided in the request, userId takes precedence and is used as the primary identifier." }, { "name": "userId", "kind": "optional", "type": "string", "description": "Pass any string for the user (uniqueId) to identify and map the orders against the user. This can be same value which you are using in your application to uniquely identify the users.\n\nIf both \"userId\" and \"payerEmail\" are provided in the request, userId takes precedence and is used as the primary identifier.", "": "Pass any string for the user (uniqueId) to identify and map the orders against the user. This can be same value which you are using in your application to uniquely identify the users.\n\nIf both \"userId\" and \"payerEmail\" are provided in the request, userId takes precedence and is used as the primary identifier." }, { "name": "metadata", "kind": "optional", "type": "object", "description": "This key accepts a JSON object that can be used to pass additional details for future reference in the Order Details API.\n\nFor example:\n\n{\n \"metadata\": {\n \"notes\": \"payment for August invoice\",\n \"merchant_name\": \"xyz\"\n }\n}", "": "This key accepts a JSON object that can be used to pass additional details for future reference in the Order Details API.\n\nFor example:\n\n{\n \"metadata\": {\n \"notes\": \"payment for August invoice\",\n \"merchant_name\": \"xyz\"\n }\n}" } ], "formDataParameters": [] }, "currentNewParameter": { "label": "Body Parameter", "value": "bodyDataParameters" }, "hasTryItOut": false, "autoGeneratedAnchorSlug": "create-crypto-order", "legacyHash": "sqj7sRsDC04r4g-8bBx8B" } ``` ::: ## Signature Generation The request for creating payout order requires a header `signature`. This can be generated using following javascript code snippet. ### Case 1: With amount parameter ```javascript const crypto = require('crypto'); // Required Parameters const secretKey="Api-Secret-Provided-By-Pay3"; const address = "destination-wallet-address"; const currency = "currency-id"; const amount = "0.02"; const requestId = "Order-Id-Generated-By-Application"; const getSignature = (secretKey, address, currency, amount, requestId) => { // Prepare the string to sign in same format. const stringToSign = 'address=' + address + '¤cy=' + currency + '&amount=' + amount + '&requestId=' + requestId; // Generating signature using SHA256 and provided secret and // base64 encode the result const mac = crypto.createHmac('sha256', secretKey); return mac.update(stringToSign).digest('base64'); } // Generate Signature const signature = getSignature(secretKey, address, currency, amount, requestId); ``` ### Case 2: With fiatAmount & fiatCurrency parameter ```javascript const crypto = require('crypto'); // Required Parameters const secretKey="Api-Secret-Provided-By-Pay3"; const address = "destination-wallet-address"; const currency = "currency-id"; const fiatAmount = "10.50"; // $10.50 const fiatCurrency = "usd_usa"; // Example for USD const requestId = "Order-Id-Generated-By-Application"; const getSignature = (secretKey, address, currency, fiatAmount, fiatCurrency, requestId) => { // Prepare the string to sign in same format. const stringToSign = 'address=' + address + '¤cy=' + currency + '&fiatAmount=' + fiatAmount + '&fiatCurrency=' + fiatCurrency + '&requestId=' + requestId; // Generating signature using SHA256 and provided secret and // base64 encode the result const mac = crypto.createHmac('sha256', secretKey); return mac.update(stringToSign).digest('base64'); } // Generate Signature const signature = getSignature(secretKey, address, currency, fiatAmount, fiatCurrency, requestId); ``` ### Case 3: With otherChainAddresses parameters ```javascript const crypto = require('crypto'); // Required Parameters const secretKey = "Api-Secret-Provided-By-Pay3"; const address = "destination-wallet-address"; const currency = "currency-id"; const fiatAmount = "10.50"; // $10.50 const fiatCurrency = "usd_usa"; // Example for USD const requestId = "Order-Id-Generated-By-Application"; const otherChainAddresses = { "ethereum": "0x...", "solana": "...", "devnet": "...", "amoy": "..." }; const getSignature = (secretKey, address, currency, amount, fiatAmount, fiatCurrency, requestId, otherChainAddresses = {}) => { // Build otherChainAddresses parameter string let otherChainAddressesParam = ""; if (Object.keys(otherChainAddresses).length > 0) { // Sort alphabetically by key const sortedEntries = Object.entries(otherChainAddresses).sort(([a], [b]) => a.localeCompare(b)); otherChainAddressesParam = sortedEntries.map(([key, value]) => `&${key}=${value}`).join(''); } let stringToSign = 'address=' + address + '¤cy=' + currency + '&fiatAmount=' + fiatAmount + '&fiatCurrency=' + fiatCurrency + '&requestId=' + requestId + otherChainAddressesParam; // Generating signature using SHA256 and provided secret and // base64 encode the result const mac = crypto.createHmac('sha256', secretKey); return mac.update(stringToSign).digest('base64'); }; // Generate Signature const signature = getSignature(secretKey, address, currency, amount, fiatAmount, fiatCurrency, requestId, otherChainAddresses); ``` ***