{"activeVersionTag":"latest","latestAvailableVersionTag":"latest","collection":{"info":{"_postman_id":"6f6cb213-891d-452c-ba2b-f0a17a04afa1","name":"KIOSK Production","description":"Welcome to the Kiosk API! This guide will help you get started with secure deposit and withdrawal flows using our KIOSK integration and webhook validation.\n\nFor whitelisting webhooks `3.10.74.120/32, 13.41.136.246/32, 3.11.12.254/32`\n\n## Getting Started\n\nBefore you begin, ensure the following variables are set:\n\n| Variable | Description |\n| --- | --- |\n| `Customer` | Found in the Custodian Portal URL: `https://custody.lmax.com/accounts/82/` → `82` is the Customer Account number |\n| `ClientID` | Provided by Custodian for API access |\n| `ClientSecret` | Provided by Custodian for API access |\n\n## Process Flow Overview\n\n<img src=\"https://content.pstmn.io/bd2fe6c6-05b8-411a-a272-ef17775c2120/aW1hZ2UucG5n\" width=\"413\" height=\"222\">\n\n### 1\\. KIOSK Settings & Webhook Setup\n\n- Configure webhook in Custody Portal under [https://uat.custody.lmax.com/accounts/{{account_id}}](https://uat.custody.lmax.com/accounts)\n    \n- Logo image size must be < 5MB\n    \n- Webhook responses are signed\n    \n- To validate the signature, you'll need:\n    \n    - Secret from `{{base_url}}/customer/v1/accounts/kiosk-secret`\n        \n    - `timestamp`, `nonce`, and `message` from the webhook POST\n        \n\n<img src=\"https://content.pstmn.io/b4665009-40ce-4756-a683-486c230a379b/aW1hZ2UucG5n\" width=\"940\" height=\"198\">\n\n### 2\\. Authentication\n\n**Endpoint:** `{{auth_endpoint}}/oauth/token`  \nUse Auth0 to retrieve your API token.\n\n### 3\\. Fetch KIOSK Secret\n\n**Endpoint:** `{{base_url}}/customer/v1/accounts/kiosk-secret`  \nRetrieves the HMAC secret used for deposit page and webhook signature validation.\n\n### 4\\. Generate Deposit Request\n\n**Endpoint:** `{{base_url}}/customer/v1/accounts/deposit-request`  \nReturns a KIOSK deposit page URL (valid for 10 minutes). Example payload:\n\nExample Request:\n\n``` json\n{\n  \"assetName\": \"USDC\", // Required: Name of the asset\n  \"blockchain\": \"ETHEREUM\", // Required: Blockchain network\n  \"clientReference\": \"Client Ref\", // Required: Unique identifier assigned to the customer (not a ID per transaction)\n  \"reference\": \"randomString4\", // Optional:Reference assigned to the request (Will be returned as depositRequestReference on a callback)\n   \"beneficiary\": {\n        \"personType\": \"NATURAL\", // Type of entity: \"NATURAL\" for individuals, \"LEGAL\" for corporate entities\n        \"naturalPersonPrimaryIdentifier\": \"Smith\",// Required only if personType is \"NATURAL\"\n        \"naturalPersonSecondaryIdentifier\": \"John\"// Required only if personType is \"NATURAL\"\n        \"legalPersonName\": \"\", // Required only if personType is \"LEGAL\"\n        \"buildingNumber\": \"1\",  // At least one of buildingNumber or buildingName is required\n        \"buildingName\": \"The Cottage\",  // At least one of buildingNumber or buildingName is required\n        \"streetName\": \"Client Street\", //Required: Street name of the address\n        \"country\": \"UK\" //Required: ISO 3166 alpha-2 country code\n    }\n}\n\n ```\n\nExample Response:\n\n``` json\n{\n  \"address\": \"0x<deposit_address>\",   // Blockchain deposit address\n  \"url\": \"https://customer-<env>.custody.lmax.com/hosted-deposits/<token>\", // Hosted deposit page URL (valid ~10 minutes)\n  \"expiryTime\": \"<ISO-8601 timestamp>\", // Expiration time of the deposit URL\n  \"reference\": \"randomString4\"        // Echo of your provided reference\n    }\n}\n\n ```\n\n### 5\\. Load Deposit Page\n\n**Endpoint:** `{{audience}}/hosted-deposits/{{signature_string}}`  \nReturns a signed URL to load the deposit page. Ensure the URL is **encoded**.\n\n<img src=\"https://content.pstmn.io/e4d8baf8-0ae7-4422-8c05-4d28fcdee196/aW1hZ2UucG5n\" width=\"406\" height=\"482\">\n\n### 6\\. Webhook Response\n\nWebhook will return a valid deposit or withdrawal notification.  \nUse Postman mock server to collect and test webhook responses.\n\nWebhook\n\n``` json\n{\n  \"message\": {\n  \"assetName\": \"USDC\",                  // Asset deposited\n  \"blockchain\": \"ETHEREUM\",             // Blockchain used\n  \"clientReference\": \"Client Ref\",             // Your client reference\n  \"depositRequestReference\": \"randomString4\", // Echo of your provided reference\n  \"notificationType\": \"DEPOSIT\",        // Event type\n  \"toAddress\": \"0x<deposit_address>\",   // Deposit address issued in response\n  \"fromAddress\": null,                  // Sender address (if available)\n  \"blockchainTransactionId\": \"0x<tx_hash>\", // On-chain transaction hash\n  \"amount\": \"1.000000\",                 // Amount credited\n  \"nonce\": \"<uuid>\",                    // Unique event identifier for idempotency\n  \"timestamp\": \"<ISO-8601 timestamp>\",  // Event creation time\n   },\n   \"signature\": \"tz/v4FbbOgrOc0FpaOi4I9b3czIeKxiPNb7Ek1Jc9eM=\" // Signature for authenticity verification\n   }\n}\n\n ```\n\n### 7\\. Create Withdrawal Address\n\n**Endpoint:** `{{base_url}}/customer/v1/withdrawals/addresses?preApproved=true`  \nCreates a withdrawal address. If `preApproved=true`, ownership is assumed verified. Otherwise, manual verification is required.\n\n> It is advised that withdrawal addresses be managed, stored and approved via a separate process flow to ensure adequate compliance with travel rule and the security requirements around withdrawal addresses. Withdrawal address verification can be delayed even if auto approval is set. \n  \n\n### 8\\. Create Withdrawal Request\n\n**Endpoint:** `{{base_url}}/customer/v1/accounts/withdrawals`  \nInitiates a withdrawal. Webhook will confirm once signed.\n\nWebhook example on blockchain confirmation\n\n``` json\n{\n  \"message\": {\n    \"assetName\": \"USDC\",\n    \"notificationType\": \"WITHDRAWAL\",\n    \"blockchain\": \"ETHEREUM\",\n    \"clientReference\": \"test11213\",\n    \"fromAddress\": \"0x2bdf41c2be1a55a12f411774cae1420ff2878f74\",\n    \"toAddress\": \"0xf2abFEf28D04bAD4feC2C14a049cB76596a65B06\",\n    \"blockchainTransactionId\": \"0xce5a3e9612991a5ae6674712b4e9419fe2d9a0038a6be8cd553f31bb693e5c0d\",\n    \"amount\": \"10.000000\",\n    \"nonce\": \"e609aba6-79c1-474e-9199-940e43c536d0\",\n    \"timestamp\": \"2026-01-29T12:46:20.410Z\",\n    \"externalRequestId\": \"testwebhook\" \n  },\n  \"signature\": \"tz/v4FbbOgrOc0FpaOi4I9b3czIeKxiPNb7Ek1Jc9eM=\"\n}\n\n ```\n\n## Webhook Signature Validation\n\nHere is a python example to validate it\n\n``` python\nimport hmac\nimport hashlib\nimport base64\nimport getpass\nimport json\n#json blob\njson_data= input(\"Provide the full json blob: \")\n# Parse the JSON data\ndata = json.loads(json_data)\nmessage = {k: v for k, v in data[\"message\"].items() if v is not None}\n#Inputs\nsecret_base64 = getpass.getpass(prompt='Enter your secret key: ')\n#The signature provided\nexpected_signature= (data[\"signature\"])\n#Remove the whitespaces\nstringMessage = json.dumps(message, separators=(',', ':'))\nprint(stringMessage)\n#Base64 decode the secret\nsecret = base64.b64decode(secret_base64)\n#Generate the HMAC using SHA-256\ncalculated_hmac = hmac.new(secret, stringMessage.encode('utf-8'), hashlib.sha256).digest()\n#Base64 encode the HMAC\ncalculated_signature = base64.b64encode(calculated_hmac).decode('utf-8')\n#Validate by comparing the calculated signature with the expected one\nif calculated_signature == expected_signature:\n    print(\"Signature is valid!\")\nelse:\n    print(\"Signature is invalid.\")\n\n ```","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","isPublicCollection":false,"owner":"22310895","team":5157060,"collectionId":"6f6cb213-891d-452c-ba2b-f0a17a04afa1","publishedId":"2sB3dLVY2F","public":true,"publicUrl":"https://kiosk-docs.lmax.com","privateUrl":"https://go.postman.co/documentation/22310895-6f6cb213-891d-452c-ba2b-f0a17a04afa1","customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"d3d3d3"},"documentationLayout":"classic-double-column","customisation":{"metaTags":[{"name":"description","value":""},{"name":"title","value":""}],"appearance":{"default":"light","themes":[{"name":"dark","logo":"https://content.pstmn.io/60c8b3b9-677a-4b2a-9707-c81e75c745be/TE1BWEdyb3VwV2hpdGVPbkxvZ28uanBn","colors":{"top-bar":"212121","right-sidebar":"303030","highlight":"d3d3d3"}},{"name":"light","logo":"https://content.pstmn.io/dc3a403a-3d95-4ce4-996e-3851b7fab7ba/TE1BWEdyb3VwQmxhY2tPbkxvZ28uanBn","colors":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"d3d3d3"}}]}},"version":"8.10.1","publishDate":"2025-12-01T14:25:41.000Z","activeVersionTag":"latest","documentationTheme":"light","metaTags":{"title":"","description":""},"logos":{"logoLight":"https://content.pstmn.io/dc3a403a-3d95-4ce4-996e-3851b7fab7ba/TE1BWEdyb3VwQmxhY2tPbkxvZ28uanBn","logoDark":"https://content.pstmn.io/60c8b3b9-677a-4b2a-9707-c81e75c745be/TE1BWEdyb3VwV2hpdGVPbkxvZ28uanBn"}},"statusCode":200},"environments":[{"name":"Custodian Production","id":"1e08debf-d111-48f2-8653-3898328d8028","owner":"22310895","values":[{"key":"base_url","value":"https://api.custody.lmax.com","enabled":true,"type":"default"},{"key":"auth_endpoint","value":"https://auth.lmax.com","enabled":true,"type":"default"},{"key":"audience","value":"https://customer.custody.lmax.com","enabled":true,"type":"default"},{"key":"","value":"","enabled":false,"type":"default"}],"published":true}],"user":{"authenticated":false,"permissions":{"publish":false}},"run":{"button":{"js":"https://run.pstmn.io/button.js","css":"https://run.pstmn.io/button.css"}},"web":"https://www.getpostman.com/","team":{"logo":"https://res.cloudinary.com/postman/image/upload/t_team_logo_pubdoc/v1/team/aab4ba27f27729754c2485392557dec0f80a0978cc1690b85a2dda8595acd031","favicon":"https://lmax.com/favicon.ico"},"isEnvFetchError":false,"languages":"[{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"HttpClient\"},{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"RestSharp\"},{\"key\":\"curl\",\"label\":\"cURL\",\"variant\":\"cURL\"},{\"key\":\"dart\",\"label\":\"Dart\",\"variant\":\"http\"},{\"key\":\"go\",\"label\":\"Go\",\"variant\":\"Native\"},{\"key\":\"http\",\"label\":\"HTTP\",\"variant\":\"HTTP\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"OkHttp\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"Unirest\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"Fetch\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"jQuery\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"XHR\"},{\"key\":\"c\",\"label\":\"C\",\"variant\":\"libcurl\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Axios\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Native\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Request\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Unirest\"},{\"key\":\"objective-c\",\"label\":\"Objective-C\",\"variant\":\"NSURLSession\"},{\"key\":\"ocaml\",\"label\":\"OCaml\",\"variant\":\"Cohttp\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"cURL\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"Guzzle\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"HTTP_Request2\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"pecl_http\"},{\"key\":\"powershell\",\"label\":\"PowerShell\",\"variant\":\"RestMethod\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"http.client\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"Requests\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"httr\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"RCurl\"},{\"key\":\"ruby\",\"label\":\"Ruby\",\"variant\":\"Net::HTTP\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"Httpie\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"wget\"},{\"key\":\"swift\",\"label\":\"Swift\",\"variant\":\"URLSession\"}]","languageSettings":[{"key":"csharp","label":"C#","variant":"HttpClient"},{"key":"csharp","label":"C#","variant":"RestSharp"},{"key":"curl","label":"cURL","variant":"cURL"},{"key":"dart","label":"Dart","variant":"http"},{"key":"go","label":"Go","variant":"Native"},{"key":"http","label":"HTTP","variant":"HTTP"},{"key":"java","label":"Java","variant":"OkHttp"},{"key":"java","label":"Java","variant":"Unirest"},{"key":"javascript","label":"JavaScript","variant":"Fetch"},{"key":"javascript","label":"JavaScript","variant":"jQuery"},{"key":"javascript","label":"JavaScript","variant":"XHR"},{"key":"c","label":"C","variant":"libcurl"},{"key":"nodejs","label":"NodeJs","variant":"Axios"},{"key":"nodejs","label":"NodeJs","variant":"Native"},{"key":"nodejs","label":"NodeJs","variant":"Request"},{"key":"nodejs","label":"NodeJs","variant":"Unirest"},{"key":"objective-c","label":"Objective-C","variant":"NSURLSession"},{"key":"ocaml","label":"OCaml","variant":"Cohttp"},{"key":"php","label":"PHP","variant":"cURL"},{"key":"php","label":"PHP","variant":"Guzzle"},{"key":"php","label":"PHP","variant":"HTTP_Request2"},{"key":"php","label":"PHP","variant":"pecl_http"},{"key":"powershell","label":"PowerShell","variant":"RestMethod"},{"key":"python","label":"Python","variant":"http.client"},{"key":"python","label":"Python","variant":"Requests"},{"key":"r","label":"R","variant":"httr"},{"key":"r","label":"R","variant":"RCurl"},{"key":"ruby","label":"Ruby","variant":"Net::HTTP"},{"key":"shell","label":"Shell","variant":"Httpie"},{"key":"shell","label":"Shell","variant":"wget"},{"key":"swift","label":"Swift","variant":"URLSession"}],"languageOptions":[{"label":"C# - HttpClient","value":"csharp - HttpClient - C#"},{"label":"C# - RestSharp","value":"csharp - RestSharp - C#"},{"label":"cURL - cURL","value":"curl - cURL - cURL"},{"label":"Dart - http","value":"dart - http - Dart"},{"label":"Go - Native","value":"go - Native - Go"},{"label":"HTTP - HTTP","value":"http - HTTP - HTTP"},{"label":"Java - OkHttp","value":"java - OkHttp - Java"},{"label":"Java - Unirest","value":"java - Unirest - Java"},{"label":"JavaScript - Fetch","value":"javascript - Fetch - JavaScript"},{"label":"JavaScript - jQuery","value":"javascript - jQuery - JavaScript"},{"label":"JavaScript - XHR","value":"javascript - XHR - JavaScript"},{"label":"C - libcurl","value":"c - libcurl - C"},{"label":"NodeJs - Axios","value":"nodejs - Axios - NodeJs"},{"label":"NodeJs - Native","value":"nodejs - Native - NodeJs"},{"label":"NodeJs - Request","value":"nodejs - Request - NodeJs"},{"label":"NodeJs - Unirest","value":"nodejs - Unirest - NodeJs"},{"label":"Objective-C - NSURLSession","value":"objective-c - NSURLSession - Objective-C"},{"label":"OCaml - Cohttp","value":"ocaml - Cohttp - OCaml"},{"label":"PHP - cURL","value":"php - cURL - PHP"},{"label":"PHP - Guzzle","value":"php - Guzzle - PHP"},{"label":"PHP - HTTP_Request2","value":"php - HTTP_Request2 - PHP"},{"label":"PHP - pecl_http","value":"php - pecl_http - PHP"},{"label":"PowerShell - RestMethod","value":"powershell - RestMethod - PowerShell"},{"label":"Python - http.client","value":"python - http.client - Python"},{"label":"Python - Requests","value":"python - Requests - Python"},{"label":"R - httr","value":"r - httr - R"},{"label":"R - RCurl","value":"r - RCurl - R"},{"label":"Ruby - Net::HTTP","value":"ruby - Net::HTTP - Ruby"},{"label":"Shell - Httpie","value":"shell - Httpie - Shell"},{"label":"Shell - wget","value":"shell - wget - Shell"},{"label":"Swift - URLSession","value":"swift - URLSession - Swift"}],"layoutOptions":[{"value":"classic-single-column","label":"Single Column"},{"value":"classic-double-column","label":"Double Column"}],"versionOptions":[],"environmentOptions":[{"value":"0","label":"No Environment"},{"label":"Custodian Production","value":"22310895-1e08debf-d111-48f2-8653-3898328d8028"}],"canonicalUrl":"https://kiosk-docs.lmax.com/view/metadata/2sB3dLVY2F"}