- API Pix

API Pix (2.1.0)

Download OpenAPI specification:Download

A API Pix padroniza serviços oferecidos pelo PSP recebedor no contexto do arranjo Pix, como criação de cobrança, verificação de Pix recebidos, devolução e conciliação. Os serviços expostos pelo PSP recebedor permitem ao usuário recebedor estabelecer integração de sua automação com os serviços Pix do PSP.

Evolução da API Pix

As seguintes mudanças são esperadas e consideradas retro-compatíveis (backwards-compatibility):

  • Adição de novos recursos na API Pix.
  • Adição de novos parâmetros opcionais a cobranças.
  • Adição de novos campos em respostas da API Pix.
  • Alteração da ordem de campos.
  • Adição de novos elementos em enumerações

Mudanças compatíveis não geram nova versão da API Pix. Clientes devem estar preparados para lidar com essas mudanças sem quebrar.

Mudanças incompatíveis geram nova versão da API Pix.

Authentication

OAuth2

Security Scheme Type OAuth2
clientCredentials OAuth Flow
Token URL: https://pix.example.com/oauth/token
Scopes:
  • cob.write -

    Permissão para alteração de cobranças imediatas

  • cob.read -

    Permissão para consulta de cobranças imediatas

  • cobv.write -

    Permissão para alteração de cobranças com vencimento

  • cobv.read -

    Permissão para consulta de cobranças com vencimento

  • lotecobv.write -

    Permissão para alteração de lotes de cobranças com vencimento

  • lotecobv.read -

    Permissão para consulta de lotes de cobranças com vencimento

  • pix.write -

    Permissão para alteração de Pix

  • pix.read -

    Permissão para consulta de Pix

  • webhook.read -

    Permissão para consulta do webhook

  • webhook.write -

    Permissão para alteração do webhook

  • payloadlocation.write -

    Permissão para alteração de payloads

  • payloadlocation.read -

    Permissão para consulta de payloads

Payload JSON que representa uma Cobrança imediata.

Endpoint (location) utilizado pelo usuário devedor para recuperar o payload JSON que representa uma cobrança.

Recuperar o payload JSON que representa a cobrança imediata.

Endpoint (location) que serve um payload que representa uma cobrança imediata.

No momento que o usuário devedor efetua a leitura de um QR Code dinâmico gerado pelo recebedor, esta URL será acessada e seu conteúdo consiste em uma estrutura JWS. As informações sobre a segurança no acesso às urls encontram-se no Manual de Segurança do Pix disponível em nesse link.

path Parameters
pixUrlAcessToken
required
string

Responses

Response samples

Content type
application/jose
{
  "calendario": {
    "criacao": "2020-09-15T19:39:54.013Z",
    "apresentacao": "2020-04-01T18:00:00Z",
    "expiracao": "3600"
  },
  "txid": "fc9a4366ff3d4964b5dbc6c91a8722d3",
  "revisao": "3",
  "status": "ATIVA",
  "valor": {
    "original": "500.00"
  },
  "chave": "7407c9c8-f78b-11ea-adc1-0242ac120002",
  "solicitacaoPagador": "Informar cartao fidelidade",
  "infoAdicionais": [
    {
      "nome": "quantidade",
      "valor": "2"
    }
  ]
}

Recuperar o payload JSON que representa a cobrança com vencimento.

Endpoint (location) que serve um payload que representa uma cobrança com vencimento.

No momento que o usuário devedor efetua a leitura de um QR Code dinâmico gerado pelo recebedor, esta URL será acessada e seu conteúdo consiste em uma estrutura JWS. As informações sobre a segurança no acesso às urls encontram-se no Manual de Segurança do Pix disponível em nesse link.

path Parameters
pixUrlAcessToken
required
string
query Parameters
codMun
string (Código do município)

Código baseado na Tabela de Códigos de Municípios do IBGE que apresenta a lista dos municípios brasileiros associados a um código composto de 7 dígitos, sendo os dois primeiros referentes ao código da Unidade da Federação.

DPP
string <date>

Data de pagamento pretendida

Responses

Response samples

Content type
application/jose
{
  "calendario": {
    "criacao": "2020-09-15T19:39:54.013Z",
    "apresentacao": "2020-04-01T18:00:00Z",
    "dataDeVencimento": "2020-12-31",
    "validadeAposVencimento": 30
  },
  "devedor": {
    "logradouro": "Alameda Santos, Numero 10, Bairro Braz",
    "cidade": "Diadema",
    "uf": "SP",
    "cep": "70800100",
    "cnpj": "56989000019533",
    "nome": "Empresa de Alimentos SA"
  },
  "recebedor": {
    "logradouro": "Rua 20 Numero 70, Bairro Luz",
    "cidade": "Belo Horizonte",
    "uf": "MG",
    "cep": "55120750",
    "cnpj": "58900633120711",
    "nome": "Empresa de Abastecimento SA"
  },
  "txid": "fc9a4366ff3d4964b5dbc6c91a8722d3",
  "revisao": "3",
  "status": "ATIVA",
  "valor": {
    "original": "123.45",
    "multa": "15.00",
    "juros": "2.00",
    "final": "140,45"
  },
  "chave": "7407c9c8-f78b-11ea-adc1-0242ac120002",
  "solicitacaoPagador": "Informar cartao fidelidade",
  "infoAdicionais": [
    {
      "nome": "quantidade",
      "valor": "2"
    }
  ]
}

Gerenciamento de cobranças imediatas

Reune endpoints destinados a lidar com gerenciamento de cobranças imediatas.

Criar cobrança imediata.

Endpoint para criar uma cobrança imediata.

Authorizations:
OAuth2 (cob.write)
path Parameters
txid
required
string (Id da Transação) [a-zA-Z0-9]{26,35}

Identificador da transação

O campo txid, obrigatório, determina o identificador da transação. O objetivo desse campo é ser um elemento que possibilite ao PSP do recebedor apresentar ao usuário recebedor a funcionalidade de conciliação de pagamentos.

Na pacs.008, é referenciado como TransactionIdentification <txId> ou idConciliacaoRecebedor.

Em termos de fluxo de funcionamento, o txid é lido pelo aplicativo do PSP do pagador e, depois de confirmado o pagamento, é enviado para o SPI via pacs.008. Uma pacs.008 também é enviada ao PSP do recebedor, contendo, além de todas as informações usuais do pagamento, o txid. Ao perceber um recebimento dotado de txid, o PSP do recebedor está apto a se comunicar com o usuário recebedor, informando que um pagamento específico foi liquidado.

O txid é criado exclusivamente pelo usuário recebedor e está sob sua responsabilidade. O txid, no contexto de representação de uma cobrança, é único por CPF/CNPJ do usuário recebedor. Cabe ao PSP recebedor validar essa regra na API Pix.

Request Body schema: application/json

Dados para geração da cobrança imediata.

required
object (Calendário)

Os campos aninhados sob o identificador calendário organizam informações a respeito de controle de tempo da cobrança.

(object or object) or (object or object)
object

Identificador da localização do payload.

required
object

Todos os campos que indicam valores monetários obedecem ao formato do ID 54 da especificação EMV/BR Code para QR Codes. O separador decimal é o caractere ponto. Não é aplicável utilizar separador de milhar. Exemplos de valores aderentes ao padrão: “0.00”, “1.00”, “123.99”, “123456789.23

chave
required
string (Chave DICT do recebedor) <= 77 characters

Formato do campo chave

  • O campo chave, obrigatório, determina a chave Pix registrada no DICT que será utilizada para a cobrança. Essa chave será lida pelo aplicativo do PSP do pagador para consulta ao DICT, que retornará a informação que identificará o recebedor da cobrança.
  • Os tipos de chave podem ser: telefone, e-mail, cpf/cnpj ou EVP.
  • O formato das chaves pode ser encontrado na seção "Formatação das chaves do DICT no BR Code" do Manual de Padrões para iniciação do Pix.
solicitacaoPagador
string (Solicitação ao pagador) <= 140 characters

O campo solicitacaoPagador, opcional, determina um texto a ser apresentado ao pagador para que ele possa digitar uma informação correlata, em formato livre, a ser enviada ao recebedor. Esse texto será preenchido, na pacs.008, pelo PSP do pagador, no campo RemittanceInformation . O tamanho do campo na pacs.008 está limitado a 140 caracteres.

Array of objects (Informações adicionais) <= 50

Cada respectiva informação adicional contida na lista (nome e valor) deve ser apresentada ao pagador.

Responses

Request samples

Content type
application/json
{
  • "calendario":
    {
    },
  • "devedor":
    {
    },
  • "valor":
    {
    },
  • "chave": "7d9f0335-8dcc-4054-9bf9-0dbd61d36906",
  • "solicitacaoPagador": "Serviço realizado.",
  • "infoAdicionais":
    [
    ]
}

Response samples

Content type
application/json
{
  • "calendario":
    {
    },
  • "txid": "7978c0c97ea847e78e8849634473c1f1",
  • "revisao": 0,
  • "loc":
    {
    },
  • "location": "pix.example.com/qr/v2/9d36b84fc70b478fb95c12729b90ca25",
  • "status": "ATIVA",
  • "devedor":
    {
    },
  • "valor":
    {
    },
  • "chave": "a1f4102e-a446-4a57-bcce-6fa48899c1d1",
  • "solicitacaoPagador": "Informar cartão fidelidade"
}

Revisar cobrança imediata.

Authorizations:
OAuth2 (cob.write)
path Parameters
txid
required
string (Id da Transação) [a-zA-Z0-9]{26,35}

Identificador da transação

O campo txid, obrigatório, determina o identificador da transação. O objetivo desse campo é ser um elemento que possibilite ao PSP do recebedor apresentar ao usuário recebedor a funcionalidade de conciliação de pagamentos.

Na pacs.008, é referenciado como TransactionIdentification <txId> ou idConciliacaoRecebedor.

Em termos de fluxo de funcionamento, o txid é lido pelo aplicativo do PSP do pagador e, depois de confirmado o pagamento, é enviado para o SPI via pacs.008. Uma pacs.008 também é enviada ao PSP do recebedor, contendo, além de todas as informações usuais do pagamento, o txid. Ao perceber um recebimento dotado de txid, o PSP do recebedor está apto a se comunicar com o usuário recebedor, informando que um pagamento específico foi liquidado.

O txid é criado exclusivamente pelo usuário recebedor e está sob sua responsabilidade. O txid, no contexto de representação de uma cobrança, é único por CPF/CNPJ do usuário recebedor. Cabe ao PSP recebedor validar essa regra na API Pix.

Request Body schema: application/json

Dados para geração da cobrança.