{"activeVersionTag":"latest","latestAvailableVersionTag":"latest","collection":{"info":{"_postman_id":"e4a8de08-382c-4642-9fd2-5bf3d38a746e","name":"API Kamoney (Versão 2.0)","description":"Seja bem vindo à nova versão de nossa API de operação.\n\n> Recomendamos que migre o uso para nossa nova API, o quanto antes, pois a versão anterior será descontinuada em breve. \n \n\nEsta documentação visa detalhar métodos, exemplos práticos de requisição e retorno de dados, buscando facilitar sua implementação e consumo.\n\nTodas as consultas retornam sempre um código **HTTP Status 200**, salvo em casos de falhas em nossos servidores, que enviará um código conforme o erro, como por exemplo **HTTP Status 500**.\n\nO retorno será em formato **JSON (application/json)**, de acordo com cada endpoint.\n\n**RESPONSE:**\n\n**Padronização de retornos da API.**\n\nNossa API, sempre irá retornar em seu objeto, o atributo \"success\". Ele irá retornar em caso de suscesso um true e em caso de erro um false.\n\nQuando o atributo for success=true irá retornar um atributo do tipo String chamado \"msg\", que conterá o texto referente ao que foi solicitado. Quando o atributo for success=false irá retornar um atributo do tipo String chamado \"error\", que conterá a mensagem referente ao erro ocorrido.\n\nHaverá também um atributo \"data\", que conterá o conteúdo solicitado, de acordo com o método utilizado. Por exmeplo, em um GET, poderá haver duas formas básicas:\n\n- Objeto simples. EX.: \"data\": {id: 1, \"name\": \"João Fulano\" }\n- Lista (array) de objetos. EX.: \"data\": \\[{id: 1, \"name\": \"Item 1\" }, {id: 1, \"name\": \"Item 2\" }, ...\\]\n \n\n**Retorno do tipo success=true e data=object:**\n\n```\n{\"success\": true, \"msg\": \"\", \"data\": {}}\n\n ```\n\n**Retorno do tipo success=true e data=array:**\n\n```\n{\"success\": true, \"msg\": \"\", \"data\": [{}, {}, ...]}\n\n ```\n\n**Retorno do tipo success=false:**\n\n```\n{\"success\": false, \"error\": \"Mensagem de erro\", \"code\": \"codigo_do_erro\"}\n\n ```\n\nEm breve disponibilizaremos em nosso repositório no GitHub, nossos SDKs para reutilização, e melhor implementação de nossa API V.2.\n\n

Como funciona

\n\nOs endpoints estão separados entre **PÚBLICOS** e **PRIVADOS**.\n\nEndpoints públicos, como sugere, estão abertos para consultas sem envio de identificação do usuário, enquanto que os privados, é necessário enviar as credenciais.\n\n

Autenticação

\n\nEsta sessão, descreve o processo para gerar uma assinatura segura a ser utilizada na autenticação de solicitações à API. A autenticação é baseada no algoritmo HMAC (Hash-based Message Authentication Code) utilizando uma chave secreta (ou \"secret key\"). Antes de gerar a assinatura, é necessário preparar os dados para serem assinados.\n\n**Passo 1: Preparando os Dados para Assinatura**\n\nVamos considerar o seguinte objeto.\n\n``` php\n$req = [\n 'user' => [\n 'name' => 'João Silva',\n 'email' => 'joao@example.com',\n ],\n 'product' => 'Celular',\n 'quantity' => 2,\n];\n\n ```\n\nNeste exemplo, precisamos converter esse array multidimensional em um array unidimensional. Como no exemplo abaixo:\n\n``` php\n$req_data_query = [\n 'username' => 'João Silva',\n 'useremail' => 'joao@example.com',\n 'product' => 'Celular',\n 'quantity' => 2,\n];\n\n ```\n\n**Passo 2: Gerando a String de Consulta (Query String)**\n\nUma vez que o array unidimensional tenha sido gerado, devemos criar uma string de consulta (query string: chave=valor) que represente os dados enviados e que darão origem à assintura a ser igualmente enviada no cabeçalho header da requisição.\n\nPrecisamos que nosso array, agora unidimensional, se torne algo como:\n\n``` plaintext\nJohn+Doe&email=john@example.com&product=Laptop\n\n ```\n\n**Passo 3: Gerando a Assinatura (Signature)**\n\nApós gerar a string de consulta, é hora de calcular a assinatura utilizando o algoritmo HMAC e a chave secreta. A função `hash_hmac` no PHP é um bom exemplo a ser utilizada para esse propósito, conforme mostrado abaixo. Considere a variável `$query_string` no exemplo, como sendo a Query String gerada acima.\n\n``` php\n$secret = 'SUA_CHAVE_SECRETA'; // Substitua por sua chave secreta\n$signature = hash_hmac(\"sha512\", $query_string, $secret);\n\n ```\n\nNeste momento, a variável `$signature` conterá a assinatura gerada a partir dos dados da string de consulta e da chave secreta.\n\n**Passo 4: Enviando a Requisição**\n\nApós gerar a assinatura, o desenvolvedor deve incluir a chave pública (public key) e a assinatura (sign) no headers na requisição à API.\n\nNossa API irá autenticar os dados recebidos comparando a assinatura gerada com a assinatura enviada pelo cliente no header, garantindo assim a integridade e autenticidade dos dados.\n\n**Exemplo Completo:**\n\nA seguir, um exemplo completo de como realizar a geração da assinatura utilizando PHP. Caso deseje pode acessar no repositório no GitHub e obter mais códigos de exemplo.\n\nSegue o exemplo.\n\n``` php\n// função de geração da query string\nfunction querystring(array $req) {\n $req_data_query = [];\n foreach ($req as $key => $value) {\n if(is_array($value)) {\n $req_data_query = array_merge($req_data_query, querystring($value, $key));\n } else {\n $req_data_query[$key] = $value;\n }\n }\n return $req_data_query;\n}\n// Array de exemplo\n$req = [\n 'user' => [\n 'name' => 'John Doe',\n 'email' => 'john@example.com',\n ],\n 'product' => 'Laptop',\n];\n$req_data_query = querystring($req);\n// suas chaves publica e secreta geradas na plataforma kamoney\n$public_key = 'SUA_CHAVE_PUBLICA'; // Substitua pela chave pública fornecida\n$secret = 'SUA_CHAVE_SECRETA'; // Substitua pela chave secreta fornecida\n// Gerando a query string\n$query_string = http_build_query($req_data_query, '', '&'); // Resultado semelhante à: name=John+Doe&email=john@example.com&product=Laptop\n// Gerando a assinatura\n$signature = hash_hmac(\"sha512\", $query_string, $secret); // Resultado semelhante à: 348f4de94dc37ad4036dd2adf9a3334306564b40bf8cd80a986261008ebe539d2b05b849d84ac678fbc48e0e0892c598d0c353a57e3ac4bfda08a693512a4ca9\n\n ```\n\n> Observação: Certifique-se de substituir as variáveis $public_key e $secret pelos valores fornecidos pela API. A chave pública deve ser enviada como header public, e a assinatura deve ser enviada como header sign ao realizar as requisições à API. \n \n\nCom sua public e sign (assinatura) em preparadas, envie as informações junto ao header da requisição, como informado no início desse passo. Abaixo, um exemplo em PHP.\n\n``` php\n$headers = [\n \"public: $public_key\",\n \"sign: $sign\",\n \"Content-Type: application/json\"\n];\n$url = \"https://api2.kamoney.com.br/v2/private/YOUR_END_POINT\";\n$ch = curl_init();\nif ($type == 'POST') {\n curl_setopt($ch, CURLOPT_URL, $url);\n curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($req));\n curl_setopt($ch, CURLOPT_POST, 1);\n} else {\n curl_setopt($ch, CURLOPT_URL, $url . '?' . $req_data_query);\n curl_setopt($ch, CURLOPT_POST, 0);\n}\ncurl_setopt($ch, CURLOPT_RETURNTRANSFER, true);\ncurl_setopt($ch, CURLOPT_HTTPHEADER, $headers);\ncurl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);\ncurl_setopt($ch, CURLOPT_TIMEOUT, 10);\n$data = curl_exec($ch);\n$obj = json_decode($data);\n\n ```\n\n**IMPORTANTE:** Como alguns endpoints, como por exemplo DELETE, PUT e GET, que podem não solicitar o envio de parâmetros, envie sempre o parâmetro nonce.\n\n> O parâmetro \"nonce\" é um conceito importante em criptografia e segurança da informação, geralmente usado em contextos de autenticação e proteção contra replay attacks (ataques de repetição). O termo \"nonce\" é uma contração de \"number used once\" (número usado apenas uma vez). \n \n\nUm \"nonce\" é um valor único e não repetido que é incluído em uma mensagem ou em uma requisição para evitar que a mesma mensagem seja processada mais de uma vez ou para proteger contra ataques maliciosos que tentam repetir ou reutilizar requisições anteriores.\n\nEm contextos de API e segurança, um \"nonce\" é frequentemente utilizado em conjunto com a assinatura (como a que foi explicada anteriormente). O desenvolvedor inclui o \"nonce\" na requisição, ao gerar a assinatura, garantindo que cada requisição tenha um valor único e que a mesma mensagem ou requisição não seja processada mais de uma vez.\n\nO \"nonce\" pode ser um número sequencial, um timestamp (marca de data e hora) ou um valor aleatório, desde que seja único e não se repita em requisições subsequentes. O servidor que recebe a requisição verifica se o \"nonce\" é válido e se já foi usado anteriormente para evitar repetições.\n\nUm exemplo de como o \"nonce\" pode ser incluído em uma requisição é através de um parâmetro adicional na string de consulta (query string) ou no corpo da requisição, dependendo do método utilizado (GET, POST, etc.).\n\n

Endpoints indisponíveis via autenticação PUBLIC e SIGN

\n\n| Descrição | Method | Endpoint |\n| --- | --- | --- |\n| Habilitar / Desabilitar 2FA | POST | private/security/tfs |\n| Criar chave API | POST | private/security/api |\n| Visualizar chave API | POST | private/security/api/:id/secret |\n| Excluir chave API | DELETE | private/security/api/:id |\n\n

Repositórios

\n\n- GitHub Kamoney\n \n\nDemais dúvidas, estamos à disposição! Acesse nosso [suporte](https://) das 8h às 20h, de seg à sex (exceto feriados).\n\n# Status\n\n## Status de pedido\n\nCada pedido, pode conter os seguintes status listados abaixo.\n\n| **Código** | **Nome** | **Informações** |\n| --- | --- | --- |\n| PENDING | Pendente | Quando ainda não foi identificado o envio das criptomoedas |\n| ERROR | Erro | Quando houve algum problema em finalizar o pedido por parte da Kamoney. Este erro por ser por exemplo, código de barras inválido, chave pix inválida, problemas na chave pix no banco de destino, entre outros. |\n| CANCELED | Cancelado | Quando o pedido é cancelado por algum motivo, como por exemplo, falta de envio das criptomoedas. |\n| PARTIAL | Parcial | Quando é identificado um envio inferior ao devido no pedido. |\n| PROCESSING | Processando | O processando, pode indicar qualquer ação de nossa parte, como por exemplo, identificação de envio, aguardando o sistema realizar o pagamento, entre outros. Dúvidas consulte nosso suporte. |\n| COMPLETED | Completado | Quando o pedido é pago e finalizado. |\n\n## Status lojista\n\nCada venda criada, pode conter os seguintes status listados abaixo.\n\n| **Código** | **Nome** | **Informações** |\n| --- | --- | --- |\n| PENDING | Pendente | Quando ainda não foi identificado o envio das criptomoedas |\n| CANCELED | Cancelado | Quando a venda é cancelada por algum motivo, como por exemplo, falta de envio das criptomoedas. |\n| PARTIAL | Parcial | Quando é identificado um envio inferior ao devido no pedido. Neste caso o cliente poderá enviar a diferença ou o lojista aceitar a diferença. |\n| PROCESSING | Processando | O processando indica a identificação de um novo envio de criptomoedas e está aguardando as confirmações. |\n| COMPLETED | Completado | Quando o pagamento é recebido por integral. |\n\n**OBSERVAÇÃO:** Como processador de pagamento, mesmo o pedido estando cancelado, caso o cliente envie as criptomoedas, somos obrigados as identificar e processar o valor em conta do lojista, ou seja, se o pedido estiver cancelado e o cliente enviar as criptomoedas, nosso sistema irá identiicar e fazer o crédito devido em conta, de acordo com a cotação do momento da confirmação.\n\nÉ de responsabildiade do lojista, tratar tais casos, e fazer o estorno quando solicitado pelo seu cliente em Reais (R$), pois não trabalhamos com estorno de criptomoedas.\n\n# Cancelamentos de solicitações\n\nNa Kamoney trabalhamos com um tempo limite para cancelamento automático de pedidos e vendas. Atualmente, esse valor está em 45 min, ou seja, se em 45 min não for identificado envio do pagamento, o pedido será cancelado. Este mesmo tempo está relacionado ao tempo que mantemos a cotação, ou seja, a cotação será mantida no pedido ou na venda por até 45 min\n\n**OBS:** Este tempo pode ser alterado sem aviso prévio.\n\n# Limites\n\nConfira os limites de operação em nossa plataforma [https://dash.kamoney.com.br/](https://)\n\n

Registo de alterações

\n\n## 2024-10-30\n\n- Adicionado endpoint de solicitação de nova verificação KYC na conta do cliente;\n \n\n## 2024-10-29\n\n- Atualizado endpoint de criação de compra: parâmetros base_coin e quantity disponibilizados;\n \n\n## 2024-09-26\n\n- Adicionado o atributo limits à rota public/services/order;\n- Adicionado endpoint com limites referentes a serviço da conta do cliente;\n \n\n## 2024-08-07\n\n- Adicionado campo remaining ao objeto order;\n \n\n## 2024-05-09\n\n- Atualizado endpoint de criação de saque para PIX;\n- Adiciona o atributo payer aos detalhes do merchant;\n \n\n## 2024-05-02\n\n- Novo atributo adicionado ao endpoint de consulta de extrato da carteira;\n \n\n## 2023-07-27\n\n- Melhorias de segurança aplicadas na validação via Public e Sign;\n- Remoção do método de autenticação via Token JWT;\n \n\n## 2023-07-11\n\n- Adicionada informações sobre cancelamento, status e tempo;\n \n\n## 2023-06-28\n\n- Correção no nome do objeto informado no webhook, de **id_order** para **order_id;**","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","isPublicCollection":true,"owner":"941225","team":119070,"collectionId":"e4a8de08-382c-4642-9fd2-5bf3d38a746e","publishedId":"Uz5GoFym","public":true,"publicUrl":"https://doc2.kamoney.com.br","privateUrl":"https://go.postman.co/documentation/941225-e4a8de08-382c-4642-9fd2-5bf3d38a746e","customColor":{"top-bar":"FFFFFF","right-sidebar":"25D482","highlight":"25D482"},"documentationLayout":"classic-double-column","customisation":{"metaTags":[{"name":"description","value":"Kamoney API Client Documentation"},{"name":"title","value":"Kamoney API Client Documentation"}],"appearance":{"default":"light","themes":[{"name":"dark","logo":"https://content.pstmn.io/a535d936-ab3b-4874-be7d-ec1a50f69a9f/a2Ftb25leS1sb2dvLWZ1bGwucG5n","colors":{"top-bar":"212121","right-sidebar":"131A22","highlight":"131A22"}},{"name":"light","logo":"https://content.pstmn.io/a535d936-ab3b-4874-be7d-ec1a50f69a9f/a2Ftb25leS1sb2dvLWZ1bGwucG5n","colors":{"top-bar":"FFFFFF","right-sidebar":"25D482","highlight":"25D482"}}]}},"version":"8.10.1","publishDate":"2023-06-20T11:02:29.000Z","activeVersionTag":"latest","documentationTheme":"light","metaTags":{"title":"Kamoney API Client Documentation","description":"Kamoney API Client Documentation"},"logos":{"logoLight":"https://content.pstmn.io/a535d936-ab3b-4874-be7d-ec1a50f69a9f/a2Ftb25leS1sb2dvLWZ1bGwucG5n","logoDark":"https://content.pstmn.io/a535d936-ab3b-4874-be7d-ec1a50f69a9f/a2Ftb25leS1sb2dvLWZ1bGwucG5n"}},"statusCode":200},"environments":[],"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/e83a49e7cad9b426558fa7b1768dffc407c8d4cfcb11d5e32c5ef4087713ae00","favicon":"https://kamoney.com.br/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"}],"canonicalUrl":"https://doc2.kamoney.com.br/view/metadata/Uz5GoFym"}