--- title: Create Crypto Payout Order slug: create-crypto-payout-order docTags: createdAt: 2025-05-02T10:40:00.252Z --- This API creates a payout order to enable users to withdraw funds. It accepts `address`, `currency` ,`clientId` and `amount`. This api requires access token that can be generated using [Access Token](docId\:lq-v6fF_2i-h1O3XD5KKA) API. :::ApiMethodV2 ```json { "name": "Create Crypto Payout Order", "method": "POST", "url": "https://your-hostname.pay3.app/v1/client/crypto-payout/create-order", "description": "Create an order with payout details from application's backend", "tab": "examples", "examples": { "languages": [ { "id": "nyfSHp7J-NrsuqTH3FW7t", "language": "curl", "code": "curl --location 'https://api.dev.pay3.app/v1/client/crypto-payout/create-order' \\\n--header 'signature: {{signature}}' \\\n--header 'access-token: {dynamic-access-toke}' \\\n--header 'Content-Type: application/json' \\\n--data '{\n \"clientId\": \"....\",\n \"requestId\": \"a1d4a50e-5577-4581-a980-98b03bc76260\",\n \"amount\": \"0.0001\",\n \"currency\": \"btc_bitcointestnet\",\n \"address\": \"0x5Fc0D01A67E756a15B8eb56937Fcb382637E8D2\",\n \"mode\":\"returnUrl\"\n }", "customLabel": "" } ], "selectedLanguageId": "nyfSHp7J-NrsuqTH3FW7t" }, "results": { "languages": [ { "id": "VQyRchSR38UbBEhATUpjh", "language": "200", "code": "mode=returnUrl\n{\n \"token\": \"b5ed337a-e299-4f2b-aa76-50c68097d9c1\",\n \"requestId\": \"a1d4a50e-5577-4581-a980-98b03bc76260\",\n \"url\": \"https://host.pay3.app/pay3-sdk-ui-path\"\n}\n\nmode=createEstimate\n{\n \"token\": \"a003d60c-d0ae-40e5-a7cb-2634ab607253\",\n \"requestId\": \"a1d4a50e-5577-4581-a980-98b03bc76260\",\n \"currency\": \"btc_bitcointestnet\",\n \"address\": \"tb1q7sqtxktz3jle8evmfnnhv45s0maudwdtknmdqu\",\n \"warning\": \"The btc_bitcointestnet balance (0.0031) is below the configured threshold (100.0000).\",\n \"estimatedFees\": \"0.000066\",\n \"estimatedNetAmount\": \"0.000034\"\n}", "customLabel": "" }, { "id": "tIvoQbUSKGnrqallvNDVQ", "language": "401", "code": "{\n error: {\n code: '7001',\n message: 'Order already exists for given requestId'\n }\n}", "customLabel": "" } ], "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 the destination wallet address where the crypto token currency will be deposited after the payout is processed. (User's wallet address should be passed in this)", "": "The address is the destination wallet address where the crypto token currency will be deposited after the payout is processed. (User's wallet address should be passed in this)" }, { "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": "required", "type": "string", "description": "The amount in ethereum / btc user needs to pay. ", "": "The amount in ethereum / btc user needs to pay. " }, { "name": "clientId", "kind": "required", "type": "string", "description": "Client id. Application's identifier", "children": [] }, { "name": "mode", "kind": "optional", "type": "string", "description": "The supported values for mode are returnUrl, createEstimate, and default.\n\nreturnUrl: API response includes an additional field token, requestId and url.\nThis URL provides a direct checkout page link where users can complete their crypto payment through a hosted frontend flow.\n\ncreateEstimate: API returns a token and requestId.\nThese values must be passed to the Execute Crypto Payout Order API to complete the payout. This flow is fully backend-driven and does not involve any frontend or UI.", "": "The supported values for mode are returnUrl, createEstimate, and default.\n\nreturnUrl: API response includes an additional field token, requestId and url.\nThis URL provides a direct checkout page link where users can complete their crypto payment through a hosted frontend flow.\n\ncreateEstimate: API returns a token and requestId.\nThese values must be passed to the Execute Crypto Payout Order API to complete the payout. This flow is fully backend-driven and does not involve any frontend or UI." }, { "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": "sponsorFee", "kind": "optional", "type": "boolean", "description": "When sponsorFee is set to true, the exact amount is sent to the destination address (user's address) without deducting fees.", "": "When sponsorFee is set to true, the exact amount is sent to the destination address (user's address) without deducting fees." }, { "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.", "": "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." }, { "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" }, "response": [ { "name": "token", "kind": "optional", "type": "string", "description": "Returned as part of the payout order creation. This value authorizes and links the execution request to the original payout order. \n\nFor mode = createEstimate\nThis token must be passed to the Execute Crypto Payout Order API to finalize and trigger the payout. " }, { "name": "requestId", "kind": "optional", "type": "string", "description": "This is the same value of requestId passed while calling this API", "children": [] }, { "name": "url", "kind": "optional", "type": "string", "description": "(Returned only when mode = returnUrl)\nA direct checkout page link where users can complete their crypto payment through a hosted frontend page.", "children": [] }, { "name": "currency", "kind": "optional", "type": "string", "description": "(Returned for mode = createEstimate)\nThe currency string representing the token selected for payout. Example values include btc_bitcoin, usdt_polygon etc. Same as passed in the request.", "children": [] }, { "name": "address", "kind": "optional", "type": "string", "description": "(Returned for mode = createEstimate)\nThe destination wallet address where the payout is intended to be processed. Same as passed in the request.", "children": [] }, { "name": "warning", "kind": "optional", "type": "string", "description": "May provide additional information or caution related to the payout session, eg. Payout wallet balance is lesser than threshold. \n", "children": [] }, { "name": "estimatedFees", "kind": "optional", "type": "string", "description": "(Returned for mode = createEstimate)\nThe estimated gas/network fees in \"currency\" value, required to complete the payout.", "children": [] }, { "name": "estimatedNetAmount", "kind": "optional", "type": "string", "description": "(Returned for mode = createEstimate)\nThe estimated net amount in \"currency\" value, the user will receive after deducting gas fees and any applicable charges.", "children": [] } ], "hasTryItOut": false, "autoGeneratedAnchorSlug": "create-crypto-payout-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. ```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); ``` ***