{"activeVersionTag":"latest","latestAvailableVersionTag":"latest","collection":{"info":{"_postman_id":"1cc909b8-8d21-4d25-b888-c1899d563bbc","name":"SuitPay API's PIX Documentation","description":"### Welcome!\n\nHere you will find everything you need to make your integration easily. Join us and we will help to boost your business.\n\n# Authentication\n\nIn order to access the EndPoints, first you will need generate an account Access Key. This can be achieved by logging in the [<b>portal</b>](https://web.suitpay.app) with client username an password.\n\nOnce logged in the platform, follow the instructions on screen to Generate Keys by clicking on the sidebar item VENDAS -> GATEWAY DE PAGAMENTO -> Chaves API.\n\nThe **Client ID (ci) and Client Secret (cs)** will be shown at the end of these steps. The generated keys must be stored in a safe place, since you wont be able to access these again. It is only possible to gerenate new keys, removing the access from the previous one.\n\nThe Access Keys must be present in the HTTP **header** of every request made, where Client ID must be sent as 'ci' and Client Secret must be sent as 'cs'\n\n# Environment Variables\n\n**Sandbox**\n\nhost: [https://sandbox.ws.suitpay.app](https://)\n\n**Production**\n\nhost: [https://ws.suitpay.app](https://)\n\n# Responses\n\n200 - Success.\n\n401 - Authentication Failure.\n\n400 - Request error. Check the 'response' field of the returned payload.\n\n500 - Internal Error.\n\n# Webhook\n\nYou can validate if the calls to your webhook are valid, if it comes from the following IP:\n\n3.132.137.46\n\n### Webhook (PIX Cash-in)\n\nIt is mandatory to create a webhook in you software, so you can receive the status updates of the transactions made by your system.\n\nIt must be a REST Webhook, that accepts POST requests and will receive the following payload(JSON):\n\n<table><tbody><tr><th>Field</th><th>Type</th><th>Description</th></tr><tr><td><div>idTransaction</div><div contenteditable=\"false\"><div><div><div></div></div></div><div></div></div></td><td><div>String</div><div contenteditable=\"false\"><div><div><div></div></div></div><div></div></div></td><td><div>Transaction ID</div><div contenteditable=\"false\"><div><div><div></div></div></div><div></div></div></td></tr><tr><td><div>typeTransaction</div><div contenteditable=\"false\"><div><div><div></div></div></div><div></div></div></td><td><div>String</div><div contenteditable=\"false\"><div><div><div></div></div></div><div></div></div></td><td><div>Transaction type (PIX).</div><div contenteditable=\"false\"><div><div><div></div></div></div><div></div></div></td></tr><tr><td><div>statusTransaction</div><div contenteditable=\"false\"><div><div><div></div></div></div><div></div></div></td><td><div>String</div><div contenteditable=\"false\"><div><div><div></div></div></div><div></div></div></td><td><div>Transaction status (PAID_OUT, CHARGEBACK)</div><div contenteditable=\"false\"><div><div><div></div></div></div><div></div></div></td></tr><tr><td><div>value</div><div contenteditable=\"false\"><div><div><div></div></div></div><div></div></div></td><td><div>Number</div><div contenteditable=\"false\"><div><div><div></div></div></div><div></div></div></td><td><div>Transaction value</div><div contenteditable=\"false\"><div><div><div></div></div></div><div></div></div></td></tr><tr><td><div>payerName</div><div contenteditable=\"false\"><div><div><div></div></div></div><div></div></div></td><td><div>String</div><div contenteditable=\"false\"><div><div><div></div></div></div><div></div></div></td><td><div>Payer name</div><div contenteditable=\"false\"><div><div><div></div></div></div><div></div></div></td></tr><tr><td><div>payerTaxId</div><div contenteditable=\"false\"><div><div><div></div></div></div><div></div></div></td><td><div>String</div><div contenteditable=\"false\"><div><div><div></div></div></div><div></div></div></td><td><div>Payer tax Id</div><div contenteditable=\"false\"><div><div><div></div></div></div><div></div></div></td></tr><tr><td><div>paymentDate</div><div contenteditable=\"false\"><div><div><div></div></div></div><div></div></div></td><td><div>String</div><div contenteditable=\"false\"><div><div><div></div></div></div><div></div></div></td><td><div>Payment datetime. (dd/MM/yyyy HH:mm:ss)</div><div contenteditable=\"false\"><div><div><div></div></div></div><div></div></div></td></tr><tr><td><div>paymentCode</div><div contenteditable=\"false\"><div><div><div></div></div></div><div></div></div></td><td><div>String</div><div contenteditable=\"false\"><div><div><div></div></div></div><div></div></div></td><td><div>Payment code (brCode)</div><div contenteditable=\"false\"><div><div><div></div></div></div><div></div></div></td></tr><tr><td><div>requestNumber</div><div contenteditable=\"false\"><div><div><div></div></div></div><div></div></div></td><td><div>String</div><div contenteditable=\"false\"><div><div><div></div></div></div><div></div></div></td><td><div>requestNumber sent in the request</div><div contenteditable=\"false\"><div><div><div></div></div></div><div></div></div></td></tr><tr><td><div>hash</div><div contenteditable=\"false\"><div><div><div></div></div></div><div></div></div></td><td><div>String</div><div contenteditable=\"false\"><div><div><div></div></div></div><div></div></div></td><td><div>Hash code for the content inside this payload**</div><div contenteditable=\"false\"><div><div><div></div></div></div><div></div></div></td></tr></tbody></table>\n\n``` json\n{\n  \"idTransaction\": \"15b24518-1a28-4701-81e4-19bd6137ff2e\",\n  \"typeTransaction\": \"PIX\",\n  \"statusTransaction\": \"PAID_OUT\",\n  \"value\": 10,\n  \"payerName\": \"PAULO DA SILVA\",\n  \"payerTaxId\": \"55102688081\",\n  \"paymentDate\": \"18/04/2024 12:36:05\",\n  \"paymentCode\": \"00020126780014br.gov.bcb.pix2556qrcode.qitech.app/bacen/3c8b8d9b4c214db685f89d51d4e514525204000053039865802BR5925SuitpayInstituicaoDePagam6008SaoPaulo61080145200062070503***6304EE10\",\n  \"requestNumber\": \"1234567\",\n  \"hash\": \"d76885c90c49368b4ec70a1d85f449a577d0216d2f44d9d8d175456959594b25\"\n}\n\n ```\n\n**statusTransaction:**\n\nPAID_OUT - PIX Payment Confirmed  \nCHARGEBACK - Charged back\n\n**hash:**\n\nThis security code is an integrity check to ensure the Webhook you received was generated by SuitPay's software. To validate it, follow these steps:\n\n1. Concatenate all field values (except the hash itself) into a single string. Maintain the order of the contatenated values consistent with the order of the received values in the JSON.\n    \n2. Concatenate your ClientSecret (cs) with the result from step 1.\n    \n3. Calculate the SHA-256 hash of the resulting string from step 2.\n    \n4. Compare the resulting SHA-256 hash with the hash field in the received payload. If it matches, the JSON you received is valid.\n    \n\n### Webhook (PIX Cash-out)\n\nIt is mandatory to create a webhook in you software, so you can receive the status updates of the transactions made by your system.\n\nIt must be a REST Webhook, that accepts POST requests and will receive the following payload(JSON):\n\n<table><tbody><tr><th>Field</th><th>Type</th><th>Description</th></tr><tr><td><div>idTransaction</div><div contenteditable=\"false\"><div><div><div></div></div></div><div></div></div></td><td><div>String</div><div contenteditable=\"false\"><div><div><div></div></div></div><div></div></div></td><td><div>Transaction ID</div><div contenteditable=\"false\"><div><div><div></div></div></div><div></div></div></td></tr><tr><td><div>typeTransaction</div><div contenteditable=\"false\"><div><div><div></div></div></div><div></div></div></td><td><div>String</div><div contenteditable=\"false\"><div><div><div></div></div></div><div></div></div></td><td><div>Transaction type (PIX_CASHOUT).</div><div contenteditable=\"false\"><div><div><div></div></div></div><div></div></div></td></tr><tr><td><div>statusTransaction</div><div contenteditable=\"false\"><div><div><div></div></div></div><div></div></div></td><td><div>String</div><div contenteditable=\"false\"><div><div><div></div></div></div><div></div></div></td><td><div>Transaction status (PAID_OUT, CANCELED)</div><div contenteditable=\"false\"><div><div><div></div></div></div><div></div></div></td></tr><tr><td><div>value</div><div contenteditable=\"false\"><div><div><div></div></div></div><div></div></div></td><td><div>Number</div><div contenteditable=\"false\"><div><div><div></div></div></div><div></div></div></td><td><div>Value sent.</div><div contenteditable=\"false\"><div><div><div></div></div></div><div></div></div></td></tr><tr><td><div>destinationName</div><div contenteditable=\"false\"><div><div><div></div></div></div><div></div></div></td><td><div>String</div><div contenteditable=\"false\"><div><div><div></div></div></div><div></div></div></td><td><div>Recipient name.</div><div contenteditable=\"false\"><div><div><div></div></div></div><div></div></div></td></tr><tr><td><div>destinationTaxId</div><div contenteditable=\"false\"><div><div><div></div></div></div><div></div></div></td><td><div>String</div><div contenteditable=\"false\"><div><div><div></div></div></div><div></div></div></td><td><div>Recipient tax ID.</div><div contenteditable=\"false\"><div><div><div></div></div></div><div></div></div></td></tr><tr><td><div>destinationBank</div><div contenteditable=\"false\"><div><div><div></div></div></div><div></div></div></td><td><div>String</div><div contenteditable=\"false\"><div><div><div></div></div></div><div></div></div></td><td><div>Recipient bank Name.</div><div contenteditable=\"false\"><div><div><div></div></div></div><div></div></div></td></tr><tr><td><div>hash</div><div contenteditable=\"false\"><div><div><div></div></div></div><div></div></div></td><td><div>String</div><div contenteditable=\"false\"><div><div><div></div></div></div><div></div></div></td><td><div>Hash code for the content inside this payload**</div><div contenteditable=\"false\"><div><div><div></div></div></div><div></div></div></td></tr></tbody></table>\n\n``` json\n{\n  \"idTransaction\": \"ea3835d7-5f71-4807-8d1c-e11be77f332c\",\n  \"typeTransaction\": \"PIX_CASHOUT\",\n  \"statusTransaction\": \"PAID_OUT\",\n  \"value\": 1.25,\n  \"destinationName\": \"PAULO DA SILVA\",\n  \"destinationTaxId\": \"***.026.88*-**\",\n  \"destinationBank\": \"C6\",\n  \"hash\": \"ff05459466564d3df93a18cc83419a4dd617dc4c13f34f4fa25f9dca589419d9\"\n}\n\n ```\n\n**statusTransaction:**\n\nPAID_OUT - Payment Confirmed  \nCANCELED - Canceled Transaction (Payment canceled or charged back)\n\n**hash:**\n\nThis security code is an integrity check to ensure the Webhook you received was generated by SuitPay's software. To validate it, follow these steps:\n\n1. Concatenate all field values (except the hash itself) into a single string. Maintain the order of the contatenated values consistent with the order of the received values in the JSON.\n    \n2. Concatenate your ClientSecret (cs) with the result from step 1.\n    \n3. Calculate the SHA-256 hash of the resulting string from step 2.\n    \n4. Compare the resulting SHA-256 hash with the hash field in the received payload. If it matches, the JSON you received is valid.\n    \n\n### Backward Compatibility:\n\nSuitPay may periodically add new fields to the webhook payloads in order to provide additional information and enhance the integration experience.\n\nTo ensure your application remains compatible with future updates from SuitPay, it is essential that your system **ignores any unknown fields** that may be included in the webhook structure.\n\n**Recommendation:**  \nImplement webhook serialization and/or parsing in a **tolerant** manner, ensuring that additional fields **do not affect the current behavior** of your integration.\n\n#### Example:\n\nIf today you receive:\n\n``` json\n{ \n  \"idTransaction\": \"12345\",\n  \"statusTransaction\": \"PAID_OUT\"\n}\n\n ```\n\nSuitPay may later send:\n\n``` json\n{\n  \"idTransaction\": \"12345\",\n  \"statusTransaction\": \"PAID_OUT\",\n  \"paymentDate\": \"2025-07-23T14:00:00Z\",\n  \"channel\": \"api\"\n}\n\n ```\n\nYour system should continue to operate normally, even if it does not process the `paymentDate` and `channel` fields.\n\n**Important:**  \nIntegration failures caused by rejecting unknown fields are the responsibility of the integrator. To avoid such issues, always follow the tolerance practices described above.\n\n# Endpoints","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","isPublicCollection":false,"owner":"14064322","team":1487097,"collectionId":"1cc909b8-8d21-4d25-b888-c1899d563bbc","publishedId":"2sA3BrXVKq","public":true,"publicUrl":"https://pix.suitpay.app","privateUrl":"https://go.postman.co/documentation/14064322-1cc909b8-8d21-4d25-b888-c1899d563bbc","customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"FF6C37"},"documentationLayout":"classic-double-column","customisation":{"metaTags":[{"name":"description","value":""},{"name":"title","value":""}],"appearance":{"default":"light","themes":[{"name":"dark","logo":null,"colors":{"top-bar":"212121","right-sidebar":"303030","highlight":"FF6C37"}},{"name":"light","logo":null,"colors":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"FF6C37"}}]}},"version":"8.11.6","publishDate":"2024-04-24T05:06:26.000Z","activeVersionTag":"latest","documentationTheme":"light","metaTags":{"title":"","description":""},"logos":{"logoLight":null,"logoDark":null}},"statusCode":200},"environments":[{"name":"sandbox","id":"0883d471-53cf-4e3f-9953-5e4c888fc3d6","owner":"14064322","values":[{"key":"host","value":"https://sandbox.ws.suitpay.app","enabled":true,"type":"default"},{"key":"ci","value":"testesandbox_1687443996536","enabled":true,"type":"default"},{"key":"cs","value":"5b7d6ed3407bc8c7efd45ac9d4c277004145afb96752e1252c2082d3211fe901177e09493c0d4f57b650d2b2fc1b062d","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/ec6e9c861bd42bfff2031aedad220fe8eae50bc19f62a97597b3f25cba8887d5","favicon":"https://suitpay.app/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":"sandbox","value":"14064322-0883d471-53cf-4e3f-9953-5e4c888fc3d6"}],"canonicalUrl":"https://pix.suitpay.app/view/metadata/2sA3BrXVKq"}