API PIX

Cielo - Pix
API docs by Redocly

Cielo - Pix (1.0.2)

Download OpenAPI specification:

API para geração de PIX QR CODE

Autenticação:

Api:


Callback de Notificação:

Na seção Webhook dentro do método Put, há uma aba denominada Callbacks.

Nesta aba é definido o callback que será enviado para o endereço cadastrado no webhook.

Autenticação

Criar Access Token

Endpoint para criar um access token

Authorizations:
basicAuth
Request Body schema: application/json
grant_type
string (GrantType)
Default: "client_credentials"

Tipo de fluxo de autenticação oauth

Responses

Request samples

Content type
application/json
{
  • "grant_type": "client_credentials"
}

Response samples

Content type
application/json
{
  • "access_token": "24c18dab-e8ad-4627-b181-540009c95892",
  • "token_type": "bearer",
  • "expires_in": "3600"
}

Transacional

Criar cobrança imediata.

Endpoint para criar uma cobrança imediata, neste caso, o txid deve ser definido pelo PSP.

Authorizations:
bearerAuth
Request Body schema: application/json
required
object (Expiração)
Pessoa Física (object) or Pessoa Jurídica (object)
required
object (Valor da cobrança imediata)

valores monetários referentes à cobrança.

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

Formato do campo chave

  • O campo chave 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": "string",
  • "solicitacaoPagador": "string",
  • "infoAdicionais": [
    ]
}

Response samples

Content type
application/json
{
  • "calendario": {
    },
  • "txid": "string",
  • "revisao": 0,
  • "devedor": {
    },
  • "loc": {
    },
  • "location": "pix.example.com/qr/v2/2353c790eefb11eaadc10242ac120002",
  • "status": "ATIVA",
  • "valor": {
    },
  • "pixCopiaECola": "string",
  • "chave": "string",
  • "solicitacaoPagador": "string",
  • "infoAdicionais": [
    ]
}

Criar cobrança imediata.

Endpoint para criar uma cobrança imediata.

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

Identificador da transação

O campo txid 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
required
object (Expiração)
Pessoa Física (object) or Pessoa Jurídica (object)
required
object (Valor da cobrança imediata)

valores monetários referentes à cobrança.

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

Formato do campo chave

  • O campo chave 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": "string",
  • "solicitacaoPagador": "string",
  • "infoAdicionais": [
    ]
}

Response samples

Content type
application/json
{
  • "calendario": {
    },
  • "txid": "string",
  • "revisao": 0,
  • "devedor": {
    },
  • "loc": {
    },
  • "location": "pix.example.com/qr/v2/2353c790eefb11eaadc10242ac120002",
  • "status": "ATIVA",
  • "valor": {
    },
  • "pixCopiaECola": "string",
  • "chave": "string",
  • "solicitacaoPagador": "string",
  • "infoAdicionais": [
    ]
}

Revisar cobrança imediata.

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

Identificador da transação

O campo txid 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
object (Expiração)
Pessoa Física (object) or Pessoa Jurídica (object)
object
status
string (Status do registro da cobrança)
Value: "REMOVIDA_PELO_USUARIO_RECEBEDOR"
object (Valor da cobrança imediata)

valores monetários referentes à cobrança.

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

Formato do campo chave

  • O campo chave 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": {
    },
  • "loc": {
    },
  • "status": "REMOVIDA_PELO_USUARIO_RECEBEDOR",
  • "valor": {
    },
  • "chave": "string",
  • "solicitacaoPagador": "string",
  • "infoAdicionais": [
    ]
}

Response samples

Content type
application/json
{
  • "calendario": {
    },
  • "txid": "string",
  • "revisao": 0,
  • "devedor": {
    },
  • "loc": {
    },
  • "location": "pix.example.com/qr/v2/2353c790eefb11eaadc10242ac120002",
  • "status": "ATIVA",
  • "valor": {
    },
  • "pixCopiaECola": "string",
  • "chave": "string",
  • "solicitacaoPagador": "string",
  • "infoAdicionais": [
    ]
}

Consultar cobrança imediata.

Endpoint para consultar uma cobrança através de um determinado txid.

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

Identificador da transação

O campo txid 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.

query Parameters
revisao
integer <int32> (Revisão)

O campo revisao

Denota a revisão da cobrança. Sempre começa em zero. Sempre varia em acréscimos de 1. O incremento em uma cobrança deve ocorrer sempre que um objeto da cobrança em questão for alterado. O campo loc é uma exceção a esta regra. Se em uma determinada alteração em uma cobrança, o único campo alterado for o campo loc, então esta operação não incrementa a revisão da cobrança. O campo loc não ocasiona uma alteração na cobrança em si. Não é necessário armazenar histórico das alterações do campo loc para uma determinada cobrança. Para os outros campos da cobrança, registra-se histórico.

Responses

Response samples

Content type
application/json
{
  • "calendario": {
    },
  • "devedor": {
    },
  • "loc": {
    },
  • "valor": {
    },
  • "chave": "string",
  • "solicitacaoPagador": "string",
  • "infoAdicionais": [
    ],
  • "txid": "string",
  • "revisao": 0,
  • "location": "pix.example.com/qr/v2/2353c790eefb11eaadc10242ac120002",
  • "status": "ATIVA",
  • "pixCopiaECola": "string",
  • "pix": [
    ]
}

Solicitar devolução.

Endpoint para solicitar uma devolução através de um e2eid do Pix e do ID da devolução. O motivo que será atribuído à PACS.004 será "Devolução solicitada pelo usuário recebedor do pagamento original" cuja sigla é "MD06" de acordo com a aba RTReason da PACS.004 que consta no Catálogo de Mensagens do Pix.

Authorizations:
bearerAuth
path Parameters
e2eid
required
string (Id fim a fim da transação) = 32 characters [a-zA-Z0-9]{32}

EndToEndIdentification que transita na PACS002, PACS004 e PACS008

id
required
string (Id da Devolução) [a-zA-Z0-9]{1,35}

Id gerado pelo cliente para representar unicamente uma devolução.

Request Body schema: application/json
valor
required
string (Valor) \d{1,10}\.\d{2}

Valor solicitado para devolução. A soma dos valores de todas as devolucões não podem ultrapassar o valor total do Pix.

natureza
string (Natureza da Devolução Solicitada)
Enum: "ORIGINAL" "RETIRADA"

Indica qual é a natureza da devolução solicitada. Uma solicitação de devolução pelo usuário recebedor pode ser relacionada a um Pix comum (com código: MD06 da pacs.004), ou a um Pix de Saque ou Troco (com códigos possíveis: MD06 e SL02 da pacs.004). Na ausência deste campo a natureza deve ser interpretada como sendo de um Pix comum (ORIGINAL).

As naturezas são assim definidas:

  • ORIGINAL: quando a devolução é solicitada pelo usuário recebedor e se refere a um Pix comum ou ao valor da compra em um Pix Troco (MD06);
  • RETIRADA: quando a devolução é solicitada pelo usuário recebedor e se refere a um Pix Saque ou ao valor do troco em um Pix Troco (SL02).

Os valores de devoluções são sempre limitados aos valores máximos a seguir:

  • Pix comum: o valor da devolução é limitado ao valor do próprio Pix (a natureza nesse caso deve ser: ORIGINAL);
  • Pix Saque: o valor da devolução é limitado ao valor da retirada (a natureza nesse caso deve ser: RETIRADA); e
  • Pix Troco: o valor da devolução é limitado ao valor relativo à compra ou ao troco:
    • Quando a devolução for referente à compra, o valor limita-se ao valor da compra (a natureza nesse caso deve ser ORIGINAL); e
    • Quando a devolução for referente ao troco, o valor limita-se ao valor do troco (a natureza nesse caso deve ser RETIRADA).
descricao
string (Mensagem ao pagador relativa à devolução.) <= 140 characters

O campo descricao, opcional, determina um texto a ser apresentado ao pagador contendo informações sobre a devolução. Esse texto será preenchido, na pacs.004, pelo PSP do recebedor, no campo RemittanceInformation. O tamanho do campo na pacs.004 está limitado a 140 caracteres.

Responses

Request samples

Content type
application/json
{
  • "valor": "string",
  • "natureza": "ORIGINAL",
  • "descricao": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "rtrId": "D12345678202009091000abcde123456",
  • "valor": "10.23",
  • "natureza": "ORIGINAL",
  • "descricao": "string",
  • "horario": {
    },
  • "status": "EM_PROCESSAMENTO",
  • "motivo": "string"
}

Consultar devolução.

Endpoint para consultar uma devolução através de um End To End ID do Pix e do ID da devolução

Authorizations:
bearerAuth
path Parameters
e2eid
required
string (Id fim a fim da transação) = 32 characters [a-zA-Z0-9]{32}

EndToEndIdentification que transita na PACS002, PACS004 e PACS008

id
required
string (Id da Devolução) [a-zA-Z0-9]{1,35}

Id gerado pelo cliente para representar unicamente uma devolução.

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "rtrId": "D12345678202009091000abcde123456",
  • "valor": "10.23",
  • "natureza": "ORIGINAL",
  • "descricao": "string",
  • "horario": {
    },
  • "status": "EM_PROCESSAMENTO",
  • "motivo": "string"
}

Conciliação

Consultar lista de cobranças imediatas.

Endpoint para consultar cobranças imediatas através de parâmetros como início, fim, cpf, cnpj e status.

Authorizations:
bearerAuth
query Parameters
inicio
required
string <date-time> (Data de início)

Filtra os registros cuja data de criação seja maior ou igual que a data de início. Respeita RFC 3339.

fim
required
string <date-time> (Data de fim)

Filtra os registros cuja data de criação seja menor ou igual que a data de fim. Respeita RFC 3339.

cpf
string (CPF) /^\d{11}$/

Filtro pelo CPF do devedor. Não pode ser utilizado ao mesmo tempo que o CNPJ.

cnpj
string (CNPJ) /^\d{14}$/

Filtro pelo CNPJ do devedor. Não pode ser utilizado ao mesmo tempo que o CPF.

locationPresente
boolean
status
string (Status do registro da cobrança)

Filtro pelo status da cobrança.

paginacao.paginaAtual
integer <int32> (Página atual) >= 0
Default: 0

Página a ser retornada pela consulta. Se não for informada, o PSP assumirá que será 0.

paginacao.itensPorPagina
integer <int32> (Itens por Página) [ 1 .. 1000 ]
Default: 100

Quantidade máxima de registros retornados em cada página. Apenas a última página pode conter uma quantidade menor de registros.

Responses

Response samples

Content type
application/json
{
  • "parametros": {
    },
  • "cobs": [
    ]
}

Consultar Pix.

Endpoint para consultar um Pix através de um e2eid.

Authorizations:
bearerAuth
path Parameters
e2eid
required
string (Id fim a fim da transação)

EndToEndIdentification que transita na PACS002, PACS004 e PACS008

Responses

Response samples

Content type
application/json
{
  • "endToEndId": "E01027058202505231200XXXXXXXXXXX",
  • "txid": "1232c88b8f1e6ec4ddd9361e7faed7b24b2",
  • "valor": "10.23",
  • "componentesValor": {
    },
  • "chave": "string",
  • "horario": "2019-08-24T14:15:22Z",
  • "infoPagador": "string",
  • "devolucoes": [
    ]
}

Consultar Pix recebidos.

Endpoint para consultar Pix recebidos

Authorizations:
bearerAuth
query Parameters
inicio
required
string <date-time> (Data de início)

Filtra os registros cuja data de criação seja maior ou igual que a data de início. Respeita RFC 3339.

fim
required
string <date-time> (Data de fim)

Filtra os registros cuja data de criação seja menor ou igual que a data de fim. Respeita RFC 3339.

txid
string (Id da Transação) [a-zA-Z0-9]{26,35}

Identificador da transação

O campo txid 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.

txIdPresente
boolean
devolucaoPresente
boolean
cpf
string (CPF) /^\d{11}$/

Filtro pelo CPF do pagador. Não pode ser utilizado ao mesmo tempo que o CNPJ.

cnpj
string (CNPJ) /^\d{14}$/

Filtro pelo CNPJ do pagador. Não pode ser utilizado ao mesmo tempo que o CPF.

paginacao.paginaAtual
integer <int32> (Página atual) >= 0
Default: 0

Página a ser retornada pela consulta. Se não for informada, o PSP assumirá que será 0.

paginacao.itensPorPagina
integer <int32> (Itens por Página) [ 1 .. 1000 ]
Default: 100

Quantidade máxima de registros retornados em cada página. Apenas a última página pode conter uma quantidade menor de registros.

Responses

Response samples

Content type
application/json
{
  • "parametros": {
    },
  • "pix": [
    ]
}

Webhook

Configurar o Webhook Pix.

Endpoint para configuração do serviço de notificações acerca de Pix recebidos. Somente Pix associados a um txid serão notificados.

Authorizations:
bearerAuth
path Parameters
chave
required
string (Chave DICT do recebedor) <= 77 characters
Request Body schema: application/json
required
webhookUrl
required
string <uri>

Responses

Callbacks

Request samples

Content type
application/json
{}

Response samples

Content type
application/problem+json
{}

Callback payload samples

Callback
POST: O callback deve ser acionado sempre que um ou mais
Content type
application/json
{
  • "pix": [
    ]
}

Exibir informações acerca do Webhook Pix.

Endpoint para recuperação de informações sobre o Webhook Pix.

Authorizations:
bearerAuth
path Parameters
chave
required
string (Chave DICT do recebedor) <= 77 characters

Responses

Response samples

Content type
application/json
{}

Cancelar o webhook Pix.

Endpoint para cancelamento do webhook. Não é a única forma pela qual um webhook pode ser removido.

O PSP recebedor está livre para remover unilateralmente um webhook que esteja associado a uma chave que não pertence mais a este usuário recebedor.

Authorizations:
bearerAuth
path Parameters
chave
required
string (Chave DICT do recebedor) <= 77 characters

Responses

Response samples

Content type
application/json
{}
English