{"activeVersionTag":"latest","latestAvailableVersionTag":"latest","collection":{"info":{"_postman_id":"d6f13556-583d-4ae0-a4fd-470caf8ca02c","name":"IonBlock API","description":"## Introduction\n\nThis document describes the IonBlock REST API and everything that is necessary to access its resources. In order to use the API, you first need to have a verified IonBlock merchant account. If you did not receive your credentials yet, please contact [support@ionblock.io](https://mailto:support@ionblock.io).\n\n# Configuration\n\nThe base URL hosts for all API requests documented below are:\n\nMainnet: [https://gateway.ionblock.io](https://gateway.ionblock.io)\n\nTestnet: [https://staging-gateway.xyzprocessing.com](https://staging-gateway.xyzprocessing.com/)\n\nAll API requests are performed over HTTPS. All data is sent and received as JSON with the content type `application/json`  \nThe IonBlock REST API follows a `major.minor` versioning scheme. All request formats, headers and semantics are backwards compatible within the same major version, which can also be identified by looking at the request path.  \nNewer minor versions may add additional headers or fields in the responses or allow for more valid parameter combinations in the requests. It is safe to use implementations for a given major version of the API with any future minor versions. The major version of the REST API (also visible in the request path) is reserved for non-backwards-compatible changes and in general you cannot use an implementation of the API for different major versions.\n\n# Requests and response format\n\nAll API requests are performed over HTTPS. All data is sent and received as JSON with the content type `application/json`\n\n### Authentication Headers\n\nAll requests to the API MUST include the following headers for authentication:\n\nUsing curl:\n\n``` sh\ncurl -H \"X-Crypto-Key: ...\" -H \"X-Crypto-Nonce: ...\" -H \"X-Crypto-Signature: ...\" ...\n\n ```\n\n### GET Requests\n\nAll requests MUST include the \"Accept\" header as follows: Accept: application/json  \nUsing curl:\n\n``` sh\ncurl -H \"Accept: application/json\" ...\n\n ```\n\n### POST Requests\n\nPOST requests MUST send data in JSON format within request body and have a header Content-Type: `application/json`\n\n``` sh\nPOST /v1/test\n    X-Crypto-Key: ...\n    X-Crypto-Nonce: ... \n    X-Crypto-Signature: ...\n    Content-Type: application/json Accept: \n    application/json\n    {\n        \"foobar\": \"1x Foo + 1x Bar\", \n        \"foo\": 12345,\n        \"bar\": 0.75\n    }\n\n ```\n\nUsing curl:\n\n``` sh\ncurl -H \"Content-Type: ...\" -H \"Accept: ...\" -X POST -d '{\"foobar\": \"1x Foo + 1x Bar\", \"foo\": 12345, \"bar\": 0.75}' ...\n\n ```\n\n# Responses\n\nAll API server responses are in JSON format with a Content-Type `application/json`\n\n``` sh\nHTTP/1.1 200 OK Content-Type: application/json {\"status\": \"success\" }\n\n ```\n\nAppropriate HTTP status codes are used both for successful processing and in case of errors.\n\n### Success Responses\n\nSuccessful responses have one of the following HTTP status codes:\n\n- 200 OK: Request was accepted, validated and processed\n    \n- 201 Created: The request was accepted, validated and processed. Also, a resource was created\n    \n\n### Error Responses\n\nIn case of any error the server responds with an appropriate HTTP status code and a JSON body:  \nThe message key in the JSON body of a response will always include a human readable description of the error.\n\n# Authentication\n\nTo use the IonBlock API you have to first get an API token (key + secret) from our support team. All requests to the API have to be authenticated using this token information in the headers.\n\nEach valid authenticated request has to include the following HTTP headers:\n\n### API key: X-Crypto-Key\n\nX-Crypto-Key is the API access key which you receive when you generate an API access token. It is a sequence of hex-digits represented as a string, randomly generated when a new key is created in the web interface.  \nAPI access keys are case-sensitive\n\nExample:\n\n``` sh\nX-Crypto-Key: 549653887407b9b8ad66d4b47093eb9f\n\n ```\n\n### Nonce: X-Crypto-Nonce\n\nX-Crypto-Nonce is a 64-bit integer number, which you must generate for every request you make to the API. This nonce (\"number used once\") has to meet the following two requirements:\n\n1. nonce must be unique for every request you make with the same API access key, ever. If you make a request with the same API access key and nonce again, it will be rejected.\n    \n2. Every nonce that you generate for the request, has to be greater than any of the previous nonces that you used to make requests to the API. There is no way to reset the nonce value for a given API key but you can always just generate a new API key.\n    \n\nOne way to generate nonces is to use the UNIX epoch timestamp of the request. Be sure, though, that you use enough precision: if you use only the second’s part of the timestamp and you send two requests to the API within the same second, one of them will be rejected. It is recommended that you use the UNIX epoch to microsecond resolution. The nonce value must be representable as an unsigned 64-bit integer therefore it has to be within the range \\[0...18446744073709551615\\].\n\nExample:\n\n``` sh\nX-Crypto-Nonce: 1411754081462609\n\n ```\n\n### API secret: Crypto_Secret\n\nThe secret is a randomly generated 64 characters long string from the Base62 character set:  \nABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789  \nUpon creation of a new API access token, the secret is displayed in the web-interface. Since it is only displayed once, you should write the secret down or copy it into your application code immediately. You can however create new API keys at every point in time.\n\n### Signature: X-Crypto-Signature\n\nThe signature is derived from the API access secret (CRYPTO_SECRET), the nonce (X-Crypto-Nonce) and the request body. Its format is a hex-string representation of the result of the following hash calculation:\n\n``` sh\nHMAC-SHA512(k, msg)\n\n ```\n\nWhere:\n\n``` sh\nCRYPTO_SECRET : OJ7C3DBkMScVk89fJllpKFujspsP9aa4KVnGa3DGVQXUA5lTaBK4eWtONQEg5pAX\n\n ```\n\n- `k` is your API access secret (CRYPTO_SECRET) as UTF-8 string\n    \n- `msg` is a UTF-8 string, constructed by string concatenation of uri_path + nonce_s + SHA256(request_data)\n    \n- `uri_path` is the path part of the request URI as UTF-8 string\n    \n- `nonce_s` is the nonce (X-Crypto-Nonce) of the request, converted to a UTF-8 string\n    \n- `SHA256(request_data)` is the hex-encoded SHA256 digest of request_data as a UTF-8 string, downcased.\n    \n- `request_data` is either the JSON encoded request body in case of POST requests, or the URL-encoded query in case of a GET request as specified in RFC3986\n    \n\n# Callbacks\n\n### General\n\nSetting up a callback_url in your account page for a resource supporting callbacks (e.g. channel), will trigger a POST request to this URL upon any change of an attribute of the respective resource. The request body of the callback will contain the same output that a GET request to the updated resource would return right after the event that triggered the update.\n\nExample\n\n### Channel creation\n\n``` sh\nPOST /v1/channels \n    HTTP/1.1 \n    Content-Type: application/json \n    Accept: application/json \n    X-Crypto-Key: * \n    X-Crypto-Nonce: * \n    X-Crypto-Signature: *\n    {\n        \"receiver_currency\": \"USD\", \"receiver_amount\": \"500\", \"reference\": \" OIUYMSLASSNAFS\"\n    }\n\n ```\n\n#### Callback after funds are received:\n\n``` sh\n    {\n        \"channel_id\": 5,\n        \"status\": 1,\n        \"receiver_reference\": \"OIUYMSLASSNAFS\", \"receiver_currency\": \"USD\",\n        \"receiver_amount\": 500,\n        \"address\": \"n43uUFW98Mt8aooppqyB8k2wSwUhqBXptf\", \"sender_currency\": \"BTC\",\n        \"sender_amount\": 0.4792026,\n        \"sender_rate\": 1043.4,\n        \"valid_until\": 1490919030,\n        \"created_at\": 1490918730\n    }\n\n ```\n\n### Authenticating Callbacks\n\nTo provide authentication for the callback, IonBlock API signs the POST request body with the API key and secret, which were used to create or last update the resource. The signature and API key is then passed in the callback headers, together with the callback ID.\n\n#### POST Request Headers\n\n##### X-Crypto-Signature\n\nThe signature is derived from the API access secret (CRYPTO_SECRET) that was used to create the resource, a unique identifier of the callback (X-Crypto-Callback-Id) and the request body. It is Crypto as a hex-string of the result of the following has calculation:\n\n`HMAC-SHA512(k, msg)`\n\nWhere:\n\n- `k` is your API access secret (CRYPTO_SECRET) as UTF-8 string\n    \n- `msg` is a UTF-8 string, constructed by string concatenation of X-Crypto-Callback-Id + SHA256(request_data)\n    \n- `X-Crypto-Callback-Id` is a UTF-8 string value of the callback unique IonBlock passed in the request headers.\n    \n- `SHA256(request_data)` is the hex-encoded SHA256 digest of request_data as a UTF-8 string, downcased.\n    \n- `request_data` is the JSON encoded request body\n    \n\nIt is very important that you verify the authenticity of the callback and ensure that the it was actually posted by IonBlock. Otherwise it is quite simple for some attacker to forge a callback and to trick you into believing that the payment was made, whereas it was not.\n\nThere are two ways to achieve this:\n\n1. Check the callback signature, provided in the callback headers\n    \n2. After receiving a callback, get the resource id request.\n    \n\n### Callback Retry\n\nThe IonBlock callback API will only consider a callback as successfully sent when it receives a 200 or 201 HTTP status code from your application, that is processing the callback POST request. In case your application is currently unable to process the callback or if there is some error, it should return with a different status code, letting IonBlock know that it should retry the callback. By that we make sure that updates to the status of a resource is not lost even in case of some downtime of your application. Our system will retry the callback a total of 5 times in 5 minute intervals.","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","isPublicCollection":false,"owner":"5246195","collectionId":"d6f13556-583d-4ae0-a4fd-470caf8ca02c","publishedId":"SVtVT85c","public":true,"publicUrl":"https://docs.ionblock.io","privateUrl":"https://go.postman.co/documentation/5246195-d6f13556-583d-4ae0-a4fd-470caf8ca02c","customColor":{"top-bar":"3F5CFD","right-sidebar":"272D38","highlight":"DD724A"},"documentationLayout":"classic-double-column","customisation":{"metaTags":[{"name":"description","value":""},{"name":"title","value":""}],"appearance":{"default":"light","themes":[{"name":"dark","logo":"https://content.pstmn.io/088037e8-b802-4037-b622-c778bc3ef456/aW9uYmxvY2sgZm9vdGVyLnBuZw==","colors":{"top-bar":"3F5CFD","right-sidebar":"272D38","highlight":"DD724A"}},{"name":"light","logo":"https://content.pstmn.io/088037e8-b802-4037-b622-c778bc3ef456/aW9uYmxvY2sgZm9vdGVyLnBuZw==","colors":{"top-bar":"3F5CFD","right-sidebar":"272D38","highlight":"DD724A"}}]}},"version":"8.10.1","publishDate":"2024-01-16T22:06:58.000Z","activeVersionTag":"latest","documentationTheme":"light","metaTags":{"title":"","description":""},"logos":{"logoLight":"https://content.pstmn.io/088037e8-b802-4037-b622-c778bc3ef456/aW9uYmxvY2sgZm9vdGVyLnBuZw==","logoDark":"https://content.pstmn.io/088037e8-b802-4037-b622-c778bc3ef456/aW9uYmxvY2sgZm9vdGVyLnBuZw=="}},"statusCode":200},"environments":[{"name":"Mainnet","id":"fa991662-f4cb-4367-85f0-fa118bd92434","owner":"17259627","values":[{"key":"URL_GW","value":"https://gateway.ionblock.io","enabled":true,"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/11dcdedc34b727c980b67cedf4dbf31a2e995a249861a57a89c05b3f3c8f09fc","favicon":"https://res.cloudinary.com/postman/image/upload/v1705420392/team/we7msbqgwocu3kslarmp.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":"Mainnet","value":"17259627-fa991662-f4cb-4367-85f0-fa118bd92434"}],"canonicalUrl":"https://docs.ionblock.io/view/metadata/SVtVT85c"}