Começe por aqui

Aqui você irá encontrar toda a documentação relacionada a API da Gateway PIX. Abaixo segue algumas orientações gerais sobre a utilização dos nossos serviços.

Endpoints

Abaixo estão listadas as URLs que serão utilizadas para acessar a nossa API. No ambiente de produção e sandbox.

Dúvidas ou sugestões

Mande um e-mail para [email protected] em caso de dúvidas ou sugestões de melhorias e integrações da API.

Autenticação

Em todas as requisições é necessário passar um token de acesso no header da request. Veja nessa documentação como gerar as credenciais e esse token de acesso.

Geração das credenciais de produção

Para gerar o token de acesso é necessário antes ter em mãos um client_id e client_secret. Para obter as credenciais de produção, acesse o menu API->Gerar chaves no app

Obtendo suas credenciais de acesso ao sandbox

Para obter suas credenciais, basta solicitá-las ao nosso time de suporte através do e-mail [email protected] informando o seu CNPJ de cadastro.

Autorização

Com o client_id e client_secret em mãos poderá fazer uma requisição para o nosso endpoint de autorização, conforme detalhado a seguir:

Autorização Basic Auth

Para se autenticar conosco você deve enviar suas credenciais no cabeçalho Authorization, seguindo o padrão da HTTP Basic Authentication.

Para obter o seu token de acesso, você deve seguir o seguintes passos:

1) Gerar o header de autenticação

• Criar uma string concatenando: client_id e o client_secret, usando o símbolo 2 pontos entre eles.
  Exemplo:

  usuariotste_63c4ff64237==:1759dd06-4640-41b1-82f2-a18abae597a0

• Codificar a string com base64
  Resultado:

  dXN1YXJpb3RzdGVfNjNjNGZmNjQyMzc9PToxNzU5ZGQwNi00NjQwLTQxYjEtODJmMi1hMThhYmFlNTk3YTA===

• Enviar essa string no header, juntamente com o prefixo "Authorization: Basic" .

• Request
• Response

curl --location 'https://api-sandbox.gatewaypix.com.br/v2/oauth/token' \
        --header 'Authorization: Basic dXN1YXJpb3RzdGVfNjNjNGZmNjQyMzc9PToxNzU5ZGQwNi00NjQwLTQxYjEtODJmMi1hMThhYmFlNTk3YTA===' \
        --form 'grant_type="client_credentials"'
                

{
            "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9....",
            "expires_in": 300
        }

{
            "statusCode": 401,
            "message": "Unauthorized"
        } 

{
            "statusCode": 403,
            "message": "Forbidden"
        }

Para utilizar o seu token de acesso nas próximas requisições, você deverá enviar o access_token recebido através do parâmetro header, juntamente com o prefixo "Authorization: Bearer".

Erros

Rate limit

Todas as chamadas das APIs de autenticação possuem um rate limit de 10 requisições por segundo. Caso esse limite seja atingido você receberá um retorno de um erro com HTTP status code 429.

Tabela dos HTTP Status Code

Response de erro

Além do http_status você também receberá no corpo o erro contendo:

statusCode : Código do erro

message : Mensagem do erro

Exemplo de response contendo erro

{
            "statusCode": 401,
            "message": "Error message"
        }

PIX

A API Pix é o elemento final para que o usuário recebedor possa automatizar sua interação com a Gateway PIX, a fim de receber e gerenciar transações Pix.

O usuário recebedor poderá gerar QR Code de cobrança para pagamentos e verificar a liquidação desses pagamentos, entre outras possibilidades.

Gerar um QRCode de recebimento PIX

• Request
• Response

curl --location 'https://api-sandbox.gatewaypix.com.br/v2/pix/qrcode' \
        --header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOi...'
        --data '{
            "amount": 2.50,
            "payerQuestion": "Pagamento referente a X produto/serviço",
            "external_id": "123456",
            "postbackUrl": "https://linkdoseuwebhook.com",
            "payer": {
                "name": "Roronoa Zoro",
                "document": "01234567899",
                "email": "[email protected]"
            }
        }'
                

{
                "transactionId": "D42FDD03D7A60945",
                "external_id": "123456",
                "status": "PENDING",
                "amount": "1.50",
                "calendar": {
                    "expiration": 1800,
                    "dueDate": "2021-04-27 17:02:59"
                },
                "debtor": {
                    "name": "Roronoa Zoro",
                    "document": "99999999999"
                },
                "qrcode": "00020101021226930014br.gov.bcb.pix..."
        }

Sugerimos que seja armazenada em sua aplicação, o valor do campo transactionId, para conseguir receber o status da cobrança via webhook e para outras consultas do QRCode.

Fazer uma transferência via PIX

Iniciar pagamento PIX informando todos os dados necessários.

• Request
• Response

curl --location 'https://api-sandbox.gatewaypix.com.br/v2/pix/payment' \
        --header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOi...'
        --data '{
            "amount": 1.50,
            "external_id": "123456",
            "description": "Descrição",
            "postbackUrl": "https://linkdoseuwebhook.com",
            "creditParty": {
                "name": "Monkey D. Luffy",
                "keyType": "EMAIL",
                "key": "[email protected]",
                "taxId": "99999999999"
            }
        }'

{
                "transactionId": "63E81BEF793518F3",
                "external_id": "123456",
                "amount": 10.50,
                "createdAt": "2021-12-20 00:27:31",
                "status": "PROCESSING",
                "creditParty": {
                    "name": "Monkey D. Luffy",
                    "key": "[email protected]",
                    "taxId": "99999999999",
                    "accountType": "CACC",
                    "bank": "ITAÚ UNIBANCO S.A."
                },
                "endToEndId": "E1393589320211224022700615888922"
            }

{
        "amount": "350.00",
        "transactionId": "63E81BEF793518F3",
        "createdAt": "2021-12-23 23:00:24",
        "status": "PEND_CONFIRM",
        "endToEndId": null
        }

Webhook

Adicionamos duas camadas a mais de segurança na troca de mensagens da aplicação, garantindo que somente requisições autorizadas e autenticadas cheguem até você, ou seja aumentando a segurança e confiabilidade.

• 1 - Autenticação Basic Auth
• 2 - Validação de Assinatura

Você pode validar um ou os dois métodos ao receber uma notificação de pagamento ou recebimento.

Autenticação Basic Auth

No momento do cadastro do seu webhook, você pode informar um usuário e uma senha, quer será convertido para padrão Basic Auth que será enviado no header com o nome Authorization em cada evento que enviamos.

Authorization: Basic dXN1YXJpbzp0ZXN0ZTEyM3Nlbmhh

Verificação da assinatura

Toda notificação que enviamos para o seu endpoint é assinada. Fazemos isso incluindo um header com o nome Verify-Signature em cada evento que enviamos.

O Header Verify-Signature contêm um timestamp e uma ou mais assinaturas. O timestamp é prefixado por t= e cada assinatura é prefixado por um schema. Schemas começa com vsign= seguido de um integer. Atualmente existe apenas um schema de assinatura que é o vsign.

Exemplo do Header Verify-Signature:

Verify-Signature: t=1580306324381,vsign=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd

Assinaturas são geradas usando uma mensagem baseada em hash com código de autenticação (HMAC) com SHA-256. Para prevenir ataques de reversão de versão (downgrade attacks), você deve ignorar todos os schemas que não são vsign.

Como validar a assinatura

Passo 1: Extrair o timestamp e assinatura do Header

Faça um split no header usando o caractere , como separador para pegar a lista de elementos. Feito isso, faça outro split usando o caractere = como separador, para pegar o prefixo e o valor.

O valor obtido no prefixo t corresponde ao timestamp e o vsign corresponde à assinatura. Você pode descartar outros valores.

Passo 2: Preparar a string para comparar as assinaturas

Você deve concatenar essas informações:

• O timestamp (como string)
• O caractere .
• O payload JSON (corpo da requisição, em formato de string)

Computar o HMAC com a função hash SHA256. Use o Signature Secret recebido na hora da criação do webhook e use a string signed_payload como mensagem.

Exemplo em PHP:

$requestPayload = file_get_contents('php://input');
        
        $secretKey = 'my-signature-secret'; //Valor do Signature Secret, obtido na criação do webhook
        
        $ts = 1580306324381; //Valor de "t" recebido no header Verify-Signature
        
        $signed_payload = hash_hmac('sha256', $ts.'.'.$requestPayload, $secretKey);
        
        
        print_r($signed_payload);
        
        //Output: 5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd
        

Passo 3: Comparar as assinaturas

Compare a assinatura Recebida no Header com a assinatura que você gerou no Passo 2.

Exemplo em PHP:

// Comparando assinaturas
        // Exemplo do Header da requisição 
        $requestHeaders = {
            Verify-Signature: t=1580306324381,vsign=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd
        }
        $requestHeadersExp = explode(',', $requestHeaders);
        
        // Extraia o valor de "t" do  Header   "Verify-Signature" 
        $reqTimestamp  = str_replace('t=', '', $requestHeadersExp[0]); //Output: 1580306324381
        
        // Extraia o valor de "vsign" do Header "Verify-Signature"
        $reqSignature = str_replace('vsign=', '', $requestHeadersExp[1]); //Output: 5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd
        
        
        // A Assinatura que você gerou no Passo 2 deve ser igual ao valor da variável "reqSignature"
        if (hash_equals($reqSignature, $signed_payload)) {
        
            //executa as ações necessárias    
        }

Modelos de eventos

Todos os eventos serão enviados no endpoint configurado e enviados através de uma requisição HTTP/HTTPS POST com o formato JSON no payload.

O endpoint informado precisa retornar um http_status_code de sucesso na resposta, sendo (2xx) um formato válido, assim consideraremos como entregue. Caso contrário, vamos retentar entregar a notificação mais 4 vezes, com intervalo de 1 minuto entre cada nova tentativa, depois disso, não vamos mais tentar entregar a notificação deste evento.

1. Exemplo de Payload de uma confirmação de recebimento

{
            "requestBody": {
                "transactionType": "RECEIVEPIX",
                "transactionId": "0424ADBC8402150B",
                "external_id": "123456",
                "amount": 1.04,
                "dateApproval": "2021-04-01 06:24:25",
                "payerName": "Roronoa Zoro",
                "creditParty": {
                    "userId": "luffy",
                    "email": "[email protected]",
                    "taxId": "99988877732",
                    "name": "Monkey D. Luffy"
                },
                "debitParty": {
                    "account": "999999999",
                    "bank": "NU PAGAMENTOS S.A.",
                    "branch": "1",
                    "taxId": "99999999999",
                    "name": "Naruto Jose"
                },
                "authentication": "E18236120202104220033s01591135PO"
            }
        }

Esta requisição deve ser respondida apenas com um HTTP status 200.

2. Exemplo de Payload de uma expiração de um QRCode

{
            "requestBody": {
                "transactionType": "EXPIRED",
                "transactionId": "D42FDD03D7A60945",
                "external_id": "123456"
            }
        }

Esta requisição deve ser respondida apenas com um HTTP status 200.

3. Exemplo de Payload com confirmação transferência PIX.

{
          "requestBody": {
            "transactionType": "PAYMENT",
            "transactionId": "840887545",
            "external_id": "123456",
            "amount": "10.00",
            "statusCode": {
              "statusId": 2,
              "description": "Confirmed"
            }
          }
        }

Esta requisição deve ser respondida apenas com um HTTP status 200.

4. Exemplo de Payload com erro na transferência PIX.

{
            "requestBody": {
                "transactionType": "PAYMENT",
                "transactionId": "840887545",
                "external_id": "123456",
                "amount": "10.00",
                "statusCode": {
                    "statusId": 3,
                    "description": "Error"
                },
                "error": {
                    "code": "PBE339",
                    "description":"General reject operation"
                        }
            }
        }

Esta requisição deve ser respondida apenas com um HTTP status 200.

6. Exemplo de Payload cancelamento de um pagamento.

{
            "requestBody": {
                "transactionType": "PAYMENT_CANCELLED",
                "transactionId": "7D07F7CD774018FB",
                "external_id": "123456",
                "amount": "300.50",
                "statusCode": {
                    "statusId": 9999,
                    "description": "Cancelled"
                }
            }
        }

Esta requisição deve ser respondida apenas com um HTTP status 200.