0841f245.03a9f0ad.js

(window.webpackJsonp=window.webpackJsonp||[]).push([[9],{105:function(e,t,n){"use strict";n.r(t),n.d(t,"frontMatter",(function(){return r})),n.d(t,"metadata",(function(){return c})),n.d(t,"rightToc",(function(){return l})),n.d(t,"default",(function(){return b}));var a=n(2),o=n(6),i=(n(0),n(250)),r={id:"Introducao",title:"Introdu\xe7\xe3o",hide_title:!0,sidebar_label:"Introduction"},c={id:"apiPagamentos/Introducao",isDocsHomePage:!1,title:"Introdu\xe7\xe3o",description:"Introduction",source:"@site/docs\\apiPagamentos\\Introducao.md",permalink:"/documentation/docs/apiPagamentos/Introducao",sidebar_label:"Introduction",sidebar:"someSidebar",previous:{title:"Flowcharts",permalink:"/documentation/docs/PIX/Flowcharts"},next:{title:"Endpoints",permalink:"/documentation/docs/apiPagamentos/Endpoints"}},l=[{value:"Payment API Gerencianet",id:"payment-api-gerencianet",children:[]},{value:"Understanding the application escopes",id:"understanding-the-application-escopes",children:[]},{value:"OAuth2 authentication",id:"oauth2-authentication",children:[]},{value:"Authorization",id:"authorization",children:[]},{value:"Setting tests on Postman",id:"setting-tests-on-postman",children:[{value:"1. Importing the Payment API Collection",id:"1-importing-the-payment-api-collection",children:[]},{value:"2. Creating an Environment",id:"2-creating-an-environment",children:[]},{value:"3. Setting the certificate in Postman",id:"3-setting-the-certificate-in-postman",children:[]},{value:"4. Assigning the Client_Id and Client_Secret in Postman",id:"4-assigning-the-client_id-and-client_secret-in-postman",children:[]}]}],s={rightToc:l};function b(e){var t=e.components,n=Object(o.a)(e,["components"]);return Object(i.b)("wrapper",Object(a.a)({},s,n,{components:t,mdxType:"MDXLayout"}),Object(i.b)("h1",{className:"titulo"},"Introduction"),Object(i.b)("div",{className:"subtitulo"},"This page contains a introduction of the Gerencianet's payments API and informations about how to configure an environment to your consume.",Object(i.b)("br",null)," ",Object(i.b)("br",null),Object(i.b)("h2",{id:"payment-api-gerencianet"},"Payment API Gerencianet"),Object(i.b)("p",null,"The Gerencianet Payment API make available the services to pay charges. With this API it is possible to check bills to pay, sen requests to pay it and verify the statuses of this payment."),Object(i.b)("h2",{id:"understanding-the-application-escopes"},"Understanding the application escopes"),Object(i.b)("p",null,"When creating or editing an application on you Gerencianet account, it's necessary to set the scopes in which this application will have access to. The choices of scopes defines the actions that the application is allowed to request through the API."),Object(i.b)("p",null,"The following list is the scopes available in the Gerencianet Payment API, and your descriptions:"),Object(i.b)("ul",null,Object(i.b)("li",{parentName:"ul"},Object(i.b)("code",null,"gn.barcode.read")," - It givesermission to check the charges to be paid;"),Object(i.b)("li",{parentName:"ul"},Object(i.b)("code",null,"gn.barcode.pay.write")," - It gives permission to send a payment request;"),Object(i.b)("li",{parentName:"ul"},Object(i.b)("code",null,"gn.barcode.pay.read")," - It gives permission to read payments already done;")),Object(i.b)("div",{className:"admonition admonition-caution alert alert--warning"},Object(i.b)("div",Object(a.a)({parentName:"div"},{className:"admonition-heading"}),Object(i.b)("h5",{parentName:"div"},Object(i.b)("span",Object(a.a)({parentName:"h5"},{className:"admonition-icon"}),Object(i.b)("svg",Object(a.a)({parentName:"span"},{xmlns:"http://www.w3.org/2000/svg",width:"16",height:"16",viewBox:"0 0 16 16"}),Object(i.b)("path",Object(a.a)({parentName:"svg"},{fillRule:"evenodd",d:"M8.893 1.5c-.183-.31-.52-.5-.887-.5s-.703.19-.886.5L.138 13.499a.98.98 0 0 0 0 1.001c.193.31.53.501.886.501h13.964c.367 0 .704-.19.877-.5a1.03 1.03 0 0 0 .01-1.002L8.893 1.5zm.133 11.497H6.987v-2.003h2.039v2.003zm0-3.004H6.987V5.987h2.039v4.006z"})))),"Setting the scopes")),Object(i.b)("div",Object(a.a)({parentName:"div"},{className:"admonition-content"}),Object(i.b)("p",{parentName:"div"},"To use the Gerencianet Payment API its necessary to configure the scopes above and to use that, please contact our Discord community on the channel ",Object(i.b)("a",{href:"https://discord.com/invite/Xsb3AmKtyC",alt:"api-pagamentos discord"},'"api-pagamentos" ')," "))),Object(i.b)("h2",{id:"oauth2-authentication"},"OAuth2 authentication"),Object(i.b)("p",null,"The process to authenticate in the Gerencianet Payment API follows the ","[OAuth2]","((",Object(i.b)("a",Object(a.a)({parentName:"p"},{href:"http://oauth.net/2/"}),"http://oauth.net/2/"),") process, in this process, it is included the security certificate generated in your Gerencianet account. Through this, the OAuth2 authentication can access the authorizations of you application and authorize or deny the requests. "),Object(i.b)("p",null,"For more details regarding authentication with OAuth2, just click on the button below:"),Object(i.b)("a",{href:"https://gerencianet.com.br/pix/?utm_referrer=https%3A%2F%2Fdev.gerencianet.com.br%2F",target:"_blank",alt:"QUERO SER CLIENTE GERENCIANET"},Object(i.b)("button",{type:"button",className:"buttonCTA buttonorange"},"OAuth2 authentication")),Object(i.b)("br",null),Object(i.b)("br",null),Object(i.b)("h2",{id:"authorization"},"Authorization"),Object(i.b)("p",null,"The Payments API requires the use of a PFX(.p12) certificate that is generated in your Gerencianet account. The Auth2 provides an authorization mechanism called mutual Transport Layer Security (mTLS) through the certificate created in your Gerencianet account, this method adds another level of security to the requests between your application and the Gerencianet Payment API."),Object(i.b)("p",null,"For more details about the PFX(.p12) creation and the mTLS pattern, just click on the button below:"),Object(i.b)("a",{href:"https://gerencianet.com.br/pix/?utm_referrer=https%3A%2F%2Fdev.gerencianet.com.br%2F",target:"_blank",alt:"QUERO SER CLIENTE GERENCIANET"},Object(i.b)("button",{type:"button",className:"buttonCTA buttonorange"},"Authorization with mTLS")),Object(i.b)("br",null),Object(i.b)("br",null),Object(i.b)("h2",{id:"setting-tests-on-postman"},"Setting tests on Postman"),Object(i.b)("p",null,"To proceed with the Postman configuration step, you must have:"),Object(i.b)("ol",null,Object(i.b)("li",{parentName:"ol"},"A pair of ",Object(i.b)("inlineCode",{parentName:"li"},"Client_Id")," and ",Object(i.b)("inlineCode",{parentName:"li"},"Client_Secret")," credentials of an application registered in your Gerencianet Account;"),Object(i.b)("li",{parentName:"ol"},"A P12/PEM certificate generated in your Gerencianet account;"),Object(i.b)("li",{parentName:"ol"},"The Postman software installed on your computer (If you don't have it, ",Object(i.b)("a",{href:"https://www.postman.com/downloads/"},"click here ")," to download it);")),Object(i.b)("h3",{id:"1-importing-the-payment-api-collection"},"1. Importing the Payment API Collection"),Object(i.b)("p",null,"This is the ",Object(i.b)("a",{href:"https://documenter.getpostman.com/view/13574984/UyrDCurw"},"link "),"to our Collection that we will keep updated with the Gerencianet Payment API endpoints."),Object(i.b)("a",{href:"https://documenter.getpostman.com/view/13574984/UyrDCurw",target:"_blank",alt:"QUERO SER CLIENTE GERENCIANET"},Object(i.b)("button",{type:"button",className:"buttonCTA buttonorange"},"Run in Postman")),Object(i.b)("br",null),Object(i.b)("br",null),Object(i.b)("ol",{start:2},Object(i.b)("li",{parentName:"ol"},"With Postman started, use the shortcut ",Object(i.b)("code",null,"Ctrl+O")," to open the import screen;"),Object(i.b)("li",{parentName:"ol"},"Select ",Object(i.b)("em",{parentName:"li"},"Collection")," file;"),Object(i.b)("li",{parentName:"ol"},"Click ",Object(i.b)("em",{parentName:"li"},"Import"))),Object(i.b)("a",{href:"/documentation/img/import-collection-postman.png",target:"_blank"},Object(i.b)("img",{src:"/documentation/img/import-collection-postman.png",alt:"Ilustra\xe7\xe3o do in\xedcio do processo de importa\xe7\xe3o"})),Object(i.b)("br",null),Object(i.b)("br",null),Object(i.b)("a",{href:"/documentation/img/2-import-collection-postman.png",target:"_blank"},Object(i.b)("img",{src:"/documentation/img/2-import-collection-postman.png",alt:"Ilustra\xe7\xe3o da importa\xe7\xe3o do arquivo"})),Object(i.b)("br",null),Object(i.b)("br",null),Object(i.b)("a",{href:"/documentation/img/3-import-collection-postman.png",target:"_blank"},Object(i.b)("img",{src:"/documentation/img/3-import-collection-postman.png",alt:"Ilustra\xe7\xe3o da etapa final da importa\xe7\xe3o"})),Object(i.b)("br",null),Object(i.b)("br",null),Object(i.b)("h3",{id:"2-creating-an-environment"},"2. Creating an Environment"),Object(i.b)("p",null,"Creating an ",Object(i.b)("em",{parentName:"p"},"Environment")," in Postman is necessary for some automations built into the collection to work. These automations are designed to make it easier for developers during testing."),Object(i.b)("p",null,"With them you need to request the authorization only once, and then the ",Object(i.b)("inlineCode",{parentName:"p"},"access_token")," is recorded as a Postman environment variable, available for use in subsequent requests."),Object(i.b)("p",null,"To create an Environment follow the steps below."),Object(i.b)("ol",null,Object(i.b)("li",{parentName:"ol"},"Use the ",Object(i.b)("inlineCode",{parentName:"li"},"Ctrl+N")," shortcut and select 'Environment';"),Object(i.b)("li",{parentName:"ol"},"Give a name specifying whether this Environment will be pointed to the production or homologation environment;"),Object(i.b)("li",{parentName:"ol"},"Create the variable ",Object(i.b)("inlineCode",{parentName:"li"},"gn-api-pag")," and as initial value enter the URL of the Production or Homologation Payment API;"),Object(i.b)("li",{parentName:"ol"},"Save your Environment;"),Object(i.b)("li",{parentName:"ol"},"Select the desired Environment, so Postman will understand the created variable.")),Object(i.b)("p",null,"The images below shows the steps above. As an example, an Environment was created for Gerencianet Payment API Production environment."),Object(i.b)("a",{href:"/documentation/img/1-config-env-postman.png",target:"_blank"},Object(i.b)("img",{src:"/documentation/img/1-config-env-postman.png",alt:"Criando um novo environment"}))," ",Object(i.b)("br",null),Object(i.b)("br",null),Object(i.b)("a",{href:"/documentation/img/2-config-env-postman.png",target:"_blank"},Object(i.b)("img",{src:"/documentation/img/2-config-env-postman.png",alt:"Configura\xe7\xf5es do environment"}))," ",Object(i.b)("br",null),Object(i.b)("br",null),Object(i.b)("h3",{id:"3-setting-the-certificate-in-postman"},"3. Setting the certificate in Postman"),Object(i.b)("p",null,"All requests made to the Gerencianet Payment API need the certificate generated in your Gerencianet account. Therefore, to help you testing Postman, follow the steps below to configure the certificate usage during requests automatically:"),Object(i.b)("ol",null,Object(i.b)("li",{parentName:"ol"},"Click the gear icon in the upper right corner of the Postman;"),Object(i.b)("li",{parentName:"ol"},'Then click "Settings" to open the settings;'),Object(i.b)("li",{parentName:"ol"},'In the top tab, click "Certificates";'),Object(i.b)("li",{parentName:"ol"},'Then click on "Add Certificate";'),Object(i.b)("li",{parentName:"ol"},'In the configuration window of the new certificate, fill the "Host" field with the Base Route of the environment to which the certificate belongs (Production or Homologation);'),Object(i.b)("li",{parentName:"ol"},'Use the "PFX File" field to tell Postman where your P12/PEM certificate file is located;'),Object(i.b)("li",{parentName:"ol"},'Finish by clicking "Add" to save your settings.')),Object(i.b)("p",null,"By following these steps, Postman will use the certificate for any requests made to the Host of the configured environment."),Object(i.b)("br",null),Object(i.b)("a",{href:"/documentation/img/1-add-cert-postman.png",target:"_blank"},Object(i.b)("img",{src:"/documentation/img/1-add-cert-postman.png",alt:"Acessando as configura\xe7\xf5es do Postman"}))," ",Object(i.b)("br",null),Object(i.b)("br",null),Object(i.b)("a",{href:"/documentation/img/2-add-cert-postman.png",target:"_blank"},Object(i.b)("img",{src:"/documentation/img/2-add-cert-postman.png",alt:"Adicionando um novo certificado no Postman"}))," ",Object(i.b)("br",null),Object(i.b)("br",null),Object(i.b)("a",{href:"/documentation/img/3-add-cert-postman.png",target:"_blank"},Object(i.b)("img",{src:"/documentation/img/3-add-cert-postman.png",alt:"Configura\xe7\xf5es do certificado"}))," ",Object(i.b)("br",null),Object(i.b)("br",null),Object(i.b)("h3",{id:"4-assigning-the-client_id-and-client_secret-in-postman"},"4. Assigning the Client_Id and Client_Secret in Postman"),Object(i.b)("p",null,"To complete the configuration of your Postman it is necessary to configure the credentials of an application of your Gerencianet account. These credentials are used for Basic Auth and to get the ",Object(i.b)("inlineCode",{parentName:"p"},"access_token")," from OAuth."),Object(i.b)("p",null,"Follow the steps below to include the credentials and perform your first test in the Gerencianet's Payment API."),Object(i.b)("ol",null,Object(i.b)("li",{parentName:"ol"},"In the imported collection, navigate to the ",Object(i.b)("inlineCode",{parentName:"li"},"/oauth/token")," route and double-click to open;"),Object(i.b)("li",{parentName:"ol"},'Go to the "Authorization" menu and make sure that the "Type" (authorization type) is selected as "Basic Auth";'),Object(i.b)("li",{parentName:"ol"},'In the "username" and "password" fields fill with your application credentials, Client_Id and Client_Secret respectively;'),Object(i.b)("li",{parentName:"ol"},'To test, click the "Send" button to submit the request')),Object(i.b)("p",null,"The image below illustrates the steps above. If everything was followed correctly, you should get a response in JSON format, containing the ",Object(i.b)("inlineCode",{parentName:"p"},"access_token"),", ",Object(i.b)("inlineCode",{parentName:"p"},"token_type"),", ",Object(i.b)("inlineCode",{parentName:"p"},"expires_in")," e ",Object(i.b)("inlineCode",{parentName:"p"},"scope")," (like the image bellow)."),Object(i.b)("a",{href:"/documentation/img/1-request-auth-postman.png",target:"_blank"},Object(i.b)("img",{src:"/documentation/img/1-request-auth-postman.png",alt:"Uso das credenciais de uma aplica\xe7\xe3o para autoriza\xe7\xe3o de requisi\xe7\xf5es"}))))}b.isMDXComponent=!0},250:function(e,t,n){"use strict";n.d(t,"a",(function(){return u})),n.d(t,"b",(function(){return d}));var a=n(0),o=n.n(a);function i(e,t,n){return t in e?Object.defineProperty(e,t,{value:n,enumerable:!0,configurable:!0,writable:!0}):e[t]=n,e}function r(e,t){var n=Object.keys(e);if(Object.getOwnPropertySymbols){var a=Object.getOwnPropertySymbols(e);t&&(a=a.filter((function(t){return Object.getOwnPropertyDescriptor(e,t).enumerable}))),n.push.apply(n,a)}return n}function c(e){for(var t=1;t<arguments.length;t++){var n=null!=arguments[t]?arguments[t]:{};t%2?r(Object(n),!0).forEach((function(t){i(e,t,n[t])})):Object.getOwnPropertyDescriptors?Object.defineProperties(e,Object.getOwnPropertyDescriptors(n)):r(Object(n)).forEach((function(t){Object.defineProperty(e,t,Object.getOwnPropertyDescriptor(n,t))}))}return e}function l(e,t){if(null==e)return{};var n,a,o=function(e,t){if(null==e)return{};var n,a,o={},i=Object.keys(e);for(a=0;a<i.length;a++)n=i[a],t.indexOf(n)>=0||(o[n]=e[n]);return o}(e,t);if(Object.getOwnPropertySymbols){var i=Object.getOwnPropertySymbols(e);for(a=0;a<i.length;a++)n=i[a],t.indexOf(n)>=0||Object.prototype.propertyIsEnumerable.call(e,n)&&(o[n]=e[n])}return o}var s=o.a.createContext({}),b=function(e){var t=o.a.useContext(s),n=t;return e&&(n="function"==typeof e?e(t):c(c({},t),e)),n},u=function(e){var t=b(e.components);return o.a.createElement(s.Provider,{value:t},e.children)},p={inlineCode:"code",wrapper:function(e){var t=e.children;return o.a.createElement(o.a.Fragment,{},t)}},m=o.a.forwardRef((function(e,t){var n=e.components,a=e.mdxType,i=e.originalType,r=e.parentName,s=l(e,["components","mdxType","originalType","parentName"]),u=b(n),m=a,d=u["".concat(r,".").concat(m)]||u[m]||p[m]||i;return n?o.a.createElement(d,c(c({ref:t},s),{},{components:n})):o.a.createElement(d,c({ref:t},s))}));function d(e,t){var n=arguments,a=t&&t.mdxType;if("string"==typeof e||a){var i=n.length,r=new Array(i);r[0]=m;var c={};for(var l in t)hasOwnProperty.call(t,l)&&(c[l]=t[l]);c.originalType=e,c.mdxType="string"==typeof e?e:a,r[1]=c;for(var s=2;s<i;s++)r[s]=n[s];return o.a.createElement.apply(null,r)}return o.a.createElement.apply(null,n)}m.displayName="MDXCreateElement"}}]);