Pular para o conteúdo principal
Aviso Importante: Essa é uma documentação que visa antecipar o lançamento do Pix Automático. Com ela, queremos proporcionar aos nossos clientes uma visão antecipada dos novos serviços que estarão disponíveis em breve.
API docs by Redocly

API Pix Automático

A API Pix Automático é a solução que permite o pagamento de uma cobrança recorrente, de forma automática, mediante a concessão de uma permissão pelo usuário pagador ao usuário recebedor e de uma autorização ao PSP pagador, utilizando a infraestrutura do Pix.

Uma vez concedida a permissão pelo usuário pagador, o usuário recebedor enviará periodicamente as informações das cobranças recorrentes ao seu PSP, utilizando-se para isso da API Pix.

O PSP Recebedor então gerará a instrução de pagamento correspondente e a enviará ao PSP Pagador que, por sua vez, realizará o agendamento do débito e, posteriormente, sua liquidação na data prevista, de forma automática, sem a necessidade de qualquer ação do usuário pagador a cada nova transação.

Tratamento de erros

A API Pix Automático retorna códigos de status HTTP para indicar sucesso ou falhas das requisições.

Códigos 2xx indicam sucesso.

Códigos 4xx indicam falhas causadas pelas informações enviadas pelo cliente ou pelo estado atual das entidades.

Códigos 5xx indicam problemas no serviço no lado da API Pix.

As respostas de erro incluem no corpo detalhes do erro seguindo o schema da RFC 7807.

O campo type identifica o tipo de erro e segue o padrão: https://pix.bcb.gov.br/api/v2/error/<TipoErro>

O padrão acima listado, referente ao campo type, não consiste, necessariamente, em uma URL que apresentará uma página web válida, ou um endpoint válido, embora possa, futuramente, ser exatamente o caso.

O objetivo primário é apenas e tão somente identificar o tipo de erro.

Erros Gerais

Esta seção lista os tipos de erro e possíveis violações que podem ser retornados pelos endpoints listados na API Pix Automático.

RequisicaoInvalida

  • Significado: Requisição não atende aos requisitos esperados pelo servidor, seja por formatação, dados ausentes ou incorretos.
  • HTTP Status Code: 400 Bad Request.

AcessoNegado

  • Significado: Requisição de participante autenticado que viola alguma regra de autorização.
  • HTTP Status Code: 403 Forbidden.

NaoEncontrado

  • Significado: Entidade não encontrada.
  • HTTP Status Code: 404 Not Found.

PermanentementeRemovido

  • Significado: Indica que a entidade existia, mas foi permanentemente removida.
  • HTTP Status Code: 410 Gone.

ErroInternoDoServidor

ServicoIndisponivel

  • Significado: Serviço não está disponível no momento. Serviço solicitado pode estar em manutenção ou fora da janela de funcionamento.
  • HTTP Status Code: 503 Service Unavailable.

IndisponibilidadePorTempoEsgotado

  • Significado: Indica que o serviço demorou além do esperado para retornar.
  • HTTP Status Code: 504 Gateway Timeout.

Tag Recorrência

Esta seção reúne erros retornados pelos endpoints organizados sob a tag Recorrência.

Esses erros indicam problemas no gerenciamento de uma recorrência.

RecNaoEncontrada

  • Significado: Recorrência não encontrada para o idRec informado.
  • HTTP Status Code: 404.
  • endpoints: [GET|PATCH] /rec/{idRec}.

RecOperacaoInvalida

  • Significado: a requisição que busca alterar ou criar uma recorrência não respeita o schema ou está semanticamente errada.
  • HTTP Status Code: 400.
  • endpoints: [POST] /rec e [PATCH] /rec/{idRec}.

Violações específicas para o endpoint POST /rec:

  • O objeto rec.vinculo não respeita o schema.
  • O campo rec.calendario.dataInicial é anterior à data de criação da recorrência.
  • O campo rec.calendario.dataFinal é anterior ao campo rec.calendario.dataInicial.
  • O campo rec.calendario.periodicidade não respeita o schema.
  • O objeto rec.valor não respeita o schema.
  • O campo rec.valor.valorRec não respeita o schema.
  • O campo rec.valor.valorMinimoRecebedor não respeita o schema.
  • Ambos os campos rec.valor.valorRec e rec.valor.valorMinimoRecebedor estão preenchidos.
  • O objeto rec.recebedor não respeita o schema.
  • O campo rec.politicaRetentativa não respeita o schema.
  • O location referenciado por rec.loc inexiste.
  • O location referenciado por rec.loc já está sendo utilizado por outra recorrência.
  • O valor do campo rec.recebedor.convenio não é aceito pelo PSP Recebedor.

Violações específicas para o endpoint PATCH /rec/{idRec}:

  • O campo rec.calendario.dataInicial é anterior à data de criação da recorrência.
  • O location referenciado por rec.loc inexiste.
  • O location referenciado por rec.loc já está sendo utilizado por outra recorrência.
  • O campo rec.status não respeita o schema.
  • A recorrência encontra-se encerrada.
  • O campo rec.loc somente pode ser alterado quando a recorrência apresentar-se com o status CRIADA.
  • O campo rec.calendario.dataInicial somente pode ser alterado quando a recorrência apresentar-se com o status CRIADA.
  • O campo rec.dadosJornada.txid não pode ser alterado quando a recorrência apresentar-se com o status REJEITADA ou CANCELADA.

RecConsultaInvalida

  • Significado: Os parâmetros de consulta à lista de recorrências que não respeitam o schema ou não fazem sentido semanticamente.
  • HTTP Status Code: 400.
  • endpoints: [GET] /rec e [GET] /rec/{idRec}.

Violações específicas para o endpoint GET /rec:

  • Algum dos parâmetros informados para a consulta não respeita o schema.
  • O timestamp representado pelo parâmetro fim é anterior ao timestamp representado pelo parâmetro inicio.
  • Ambos os parâmetros cpf e cnpj estão preenchidos.
  • O parâmetro paginacao.paginaAtual é negativo.
  • O parâmetro paginacao.itensPorPagina é negativo.

Violações específicas para o endpoint GET /rec/{idRec}:

  • O parâmetro txid não corresponde a uma cobrança compatível com o campo ativacao.tipoJornada. (Exemplo: txid correspondente a uma CobV e ativacao.tipoJornada igual a JORNADA_3.)
  • O parâmetro txid corresponde a uma cobrança imediata diferente da informada no campo ativacao.dadosJornada.txid. Esta violação não ocorre caso o parâmetro txid corresponda a uma cobrança com vencimento.

Tag Solicitar Recorrência

Esta seção reúne erros retornados pelos endpoints organizados sob a tag SolicRec.

Esses erros indicam problemas no gerenciamento de uma solicitação de confirmação de recorrência.

SolicRecNaoEncontrada

  • Significado: Solicitação de recorrência não encontrada para o idSolicRec informado.
  • HTTP Status Code: 404.
  • Endpoints: [GET] /solicrec/{idSolicRec}.

SolicRecOperacaoInvalida

  • Significado: a requisição que busca criar ou alterar uma solicitação de confirmação de recorrência não respeita o schema ou está semanticamente errada.
  • HTTP Status Code: 400.
  • Endpoints: [POST] /solicrec e [PATCH] /solicrec/{idSolicRec}.

Violações específicas para o endpoint POST /solicrec:

  • O objeto solicrec.calendario não respeita o schema.
  • O campo solicrec.calendario.dataExpiracaoSolicitacao é anterior à data de criação da solicitação da recorrência.
  • O objeto solicrec.destinatario não respeita o schema.
  • Existe uma solicitação ativa referente ao mesmo solicrec.idRec.

Violações específicas para o endpoint PATCH /solicrec/{idSolicRec}:

  • Não é possível cancelar uma solicitação de recorrência com o status diferente de CRIADA, ENVIADA ou RECEBIDA.

Tag Cobrança Recorrente

Esta seção reúne erros retornados pelos endpoints organizados sob a tag CobR.

Esses erros indicam problemas no gerenciamento de uma cobrança recorrente.

CobRNaoEncontrado

  • Significado: Cobrança não encontrada para o txid informado.
  • HTTP Status Code: 404.
  • Endpoints: [GET|PATCH] /cobr/{txid} e [POST] /cobr/{txid}/retentativa/{data}.

CobROperacaoInvalida

  • Significado: a requisição que busca alterar ou criar uma cobrança recorrente não respeita o schema ou está semanticamente errada.
  • HTTP Status Code: 400.
  • Endpoints: [POST|PUT|PATCH] /cobr/{txid} e [POST] /cobr/{txid}/retentativa/{data}.

Violações específicas para o endpoint PUT /cobr/{txid}:

  • O campo cobr.infoAdicional não respeita o schema.
  • O campo cobr.status não respeita o schema.
  • O objeto cobr.calendario não respeita o schema.
  • O campo cobr.calendario.dataDeVencimento é anterior à data de criação da cobrança.
  • O campo cobr.valor não respeita o schema.
  • O objeto cobr.recebedor não respeita o schema.
  • Os campos cobr.recebedor.conta e cobr.recebedor.agencia correspondem a uma conta que não pertence a este usuário recebedor.
  • O objeto cobr.devedor não respeita o schema.
  • O campo cobr.txid encontra-se em uso.
  • Existe uma CobR com status diferente de REJEITADA e CANCELADA referente ao mesmo cobr.idRec com calendario.dataDeVencimento no mesmo ciclo.

Violações específicas para o endpoint PATCH /cobr/{txid}:

  • Não é possível cancelar uma cobrança em uma data igual ou maior que a data prevista da primeira tentativa de liquidação.

Violações específicas para o endpoint POST /cobr/{txid}/retentativa/{data}:

  • Existe uma tentativa com status SOLICITADA ou AGENDADA.
  • Existe uma tentativa em andamento.
  • Existe uma tentativa ativa.
  • Existe uma tentativa não finalizada.
  • Existe uma tentativa vigente para a data informada.
  • O parâmetro data não corresponde a uma data futura.
  • A política configurada na recorrência não permite retentativa de cobrança.

CobRConsultaInvalida

  • Significado: os parâmetros de consulta à lista de cobranças que não respeitam o schema ou não fazem sentido semanticamente.
  • HTTP Status Code: 400.
  • endpoints: [GET] /cobr e [GET] /cobr/{txid}.

Violações específicas para o endpoint GET /cobr:

  • Algum dos parâmetros informados para a consulta não respeita o schema.
  • O timestamp representado pelo parâmetro fim é anterior ao timestamp representado pelo parâmetro inicio.
  • ambos os parâmetros cpf e cnpj estão preenchidos.
  • O parâmetro paginacao.paginaAtual é negativo.
  • O parâmetro paginacao.itensPorPagina é negativo.

Tag Location da Recorrência

Esta seção reúne erros retornados pelos endpoints organizados sob a tag RecPayload.

Estes erros indicam problemas na tentativa de recuperação, via location, do Payload JSON que representa a recorrência.

RecPayloadNaoEncontrado

  • Significado: a recorrência em questão não foi encontrada para a location requisitada.
  • HTTP Status Code: 404 ou 410.
  • endpoint: GET /rec/{recUrlAccessToken}.

Se a presente location exibia uma recorrência, mas não a exibirá mais de maneira permanentemente, pode-se aplicar o HTTP status code 410. Se a presente location não está exibindo nenhuma recorrência, pode-se utilizar o HTTP status code 404.

Uma recorrência pode estar encerrada, cancelada ou rejeitada, nesses casos, é uma liberalidade do PSP recebedor retornar o presente código de erro ou optar por servir o payload de qualquer maneira, objetivando fornecer uma informação adicional ao usuário pagador final a respeito da recorrência.

RecPayloadOperacaoInvalida

  • Significado: a recorrência em questão encontra-se em encerrada, rejeitada ou cancelada para a location requisitada.
  • HTTP Status Code: 400.
  • endpoint: GET /rec/{recUrlAccessToken}.

Violações específicas para o endpoint GET /rec/{recUrlAccessToken}:

  • O campo recUrlAccessToken referencia uma recorrência encerrada, rejeitada ou cancelada.

Tag Payload Location da Recorrência

Esta seção reúne erros referentes a endpoints que tratam do gerenciamento de locations de uma recorrência.

PayloadLocationRecNaoEncontrado

  • Significado: Location não encontrada para o id informado.
  • HTTP Status Code: 404.
  • endpoints: [GET] /locrec/{id}, DELETE /locrec/{id}/idRec.

PayloadLocationRecConsultaInvalida

  • Significado: os parâmetros de consulta à lista de locations não respeitam o schema ou não fazem sentido semanticamente.
  • HTTP Status Code: 400.
  • endpoints: GET /locrec e GET /locrec/{id}.

Violações específicas para o endpoint GET /locrec:

  • algum dos parâmetros informados para a consulta não respeitam o schema.
  • O timestamp representado pelo parâmetro fim é anterior ao timestamp representado pelo parâmetro inicio.
  • O parâmetro paginacao.paginaAtual é negativo.
  • O parâmetro paginacao.itensPorPagina é negativo.

Tag Webhook de Recorrências

Reúne erros dos endpoints que tratam do gerenciamento dos Webhooks de recorrências da API Pix.

WebhookRecOperacaoInvalida

  • Significado: a presente requisição busca criar um webhook sem respeitar o schema ou, ainda, apresenta semântica inválida.
  • HTTP Status Code: 400.
  • endpoints: PUT /webhookrec.

Violações específicas para o endpoint PUT /webhookrec:

  • O campo webhookUrl não respeita o schema.

WebhookRecConsultaInvalida

  • Significado: os parâmetros de consulta à lista de webhooks ativados não respeitam o schema ou não fazem sentido semanticamente.
  • HTTP Status Code: 400.
  • endpoints: GET /webhookrec.

Violações específicas para o endpoint GET /webhookrec:

  • algum dos parâmetros informados para a consulta não respeita o schema.
  • O timestamp representado pelo parâmetro fim é anterior ao timestamp representado pelo parâmetro inicio.
  • O parâmetro paginacao.paginaAtual é negativo.
  • O parâmetro paginacao.itensPorPagina é negativo.

Tag Webhook de Cobranças Recorrentes

Reúne erros dos endpoints que tratam do gerenciamento dos Webhooks de cobranças recorrentes da API Pix.

WebhookCobROperacaoInvalida

  • Significado: a presente requisição busca criar um webhook sem respeitar o schema ou, ainda, apresenta semântica inválida.
  • HTTP Status Code: 400.
  • endpoints: PUT /webhookcobr.

Violações específicas para o endpoint PUT /webhookcobr:

  • O campo webhookUrl não respeita o schema.

WebhookCobRConsultaInvalida

  • Significado: os parâmetros de consulta à lista de webhooks ativados não respeitam o schema ou não fazem sentido semanticamente.
  • HTTP Status Code: 400.
  • endpoints: GET /webhookcobr.

Violações específicas para o endpoint GET /webhookcobr:

  • algum dos parâmetros informados para a consulta não respeita o schema.
  • O timestamp representado pelo parâmetro fim é anterior ao timestamp representado pelo parâmetro inicio.
  • O parâmetro paginacao.paginaAtual é negativo.
  • O parâmetro paginacao.itensPorPagina é negativo.

Recorrência

Essa seção apresenta os endpoints relacionados ao gerenciamento de recorrências do Pix Automático.

Para que as cobranças sejam geradas automaticamente para os clientes pagadores, devemos criar uma recorrência que o cliente pagador deverá autorizar.

Criar recorrência

Endpoint utilizado para criar uma recorrência.

Qualquer cobrança gerada pelo fluxo de Pix Automático, precisa estar vinculada a uma recorrência.

Para isso, é preciso gerar a recorrência de acordo com o contrato realizado com o cliente pagador, com relação a período vigente, periodicidade, valor, se permite retentativa, dentre outros.

  • Escopo requerido: rec.write
Request Body schema: application/json

Dados para geração da recorrência.

required
object (Descrição do Objeto da Recorrência)

Contendo objeto, devedor e contrato.

required
object (Informações sobre calendário da recorrência)

Contendo dataInicial, dataFinal e periodicidade da recorrência.

object

Contendo valorRece ValorMinimoRecebedor

politicaRetentativa
required
string (Política de retentativa pós vencimento da recorrência)
Enum: "NAO_PERMITE" "PERMITE_3R_7D"
loc
integer <int64> (Id da location)

Identificador da location a ser informado na criação de uma recorrência.

object (Confirmação da ativação da recorrência)

Contendo dadosJornada

Responses

Request samples

Content type
application/json
Example
{
  • "vinculo": {
    },
  • "calendario": {
    },
  • "valor": {
    },
  • "politicaRetentativa": "NAO_PERMITE",
  • "loc": 108,
  • "ativacao": {
    }
}

Response samples

Content type
application/json
Example
{
  • "idRec": "RN1234567820240115abcdefghijk",
  • "vinculo": {
    },
  • "calendario": {
    },
  • "politicaRetentativa": "NAO_PERMITE",
  • "recebedor": {
    },
  • "valor": {
    },
  • "status": "CRIADA",
  • "loc": {
    },
  • "ativacao": {
    },
  • "atualizacao": [
    ]
}

Consultar lista de recorrências

Endpoint utilizado para consultar várias recorrências.

Tem por objetivo consultar dados das recorrências como: status, pagador, periodicidade, política de retentativa, log de atualização, dentre outros.

Pode ser chamado passando outros parâmetros, como: período, CPF, CNPJ, status, dentre outros.

  • Escopo requerido: rec.read
query Parameters
inicio
required
string <date-time> (Data de início)
Example: inicio=2023-02-30T12:09:00Z

Formato: yyyy-MM-dd'T'HH:mm:ss[.SSS]XXX

fim
required
string <date-time> (Data de fim)
Example: fim=2023-03-30T12:09:00Z

Formato: yyyy-MM-dd'T'HH:mm:ss[.SSS]XXX

cpf
string (CPF)

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

cnpj
string (CNPJ)

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

locationPresente
boolean
status
string (Status do registro da recorrência)
Enum: "CRIADA" "APROVADA" "REJEITADA" "EXPIRADA" "CANCELADA"

Filtro pelo status da recorrência.

paginacao.paginaAtual
integer <int32> (Página atual)
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) <= 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.

convenio
string (Convênio) <= 60 characters

Filtro pelo convênio associado.

Responses

Response samples

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

Consultar recorrência

Endpoint utilizado para consultar uma recorrência específica.
Tem por objetivo buscar os dados da recorrência, como: status, pagador, periodicidade, política de retentativa, log de atualização, dentre outros.

  • Escopo requerido: rec.read
path Parameters
idRec
required
string (Id Recorrência)
query Parameters
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.

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.

Responses

Response samples

Content type
application/json
Example
{
  • "idRec": "RN1234567820240115abcdefghijk",
  • "status": "APROVADA",
  • "valor": {
    },
  • "vinculo": {
    },
  • "calendario": {
    },
  • "politicaRetentativa": "NAO_PERMITE",
  • "loc": {
    },
  • "pagador": {
    },
  • "recebedor": {
    },
  • "atualizacao": [
    ],
  • "dadosQR": {
    }
}

Revisar recorrência

Endpoint utilizado para cancelar uma recorrência já criada.

O cancelamento de uma recorrência pode ser solicitado tanto pelo cliente recebedor que pode ter deixado de utilizar a forma de pagamento de Pix Automático, como o pagador pode solicitar o cancelamento, uma vez que ele não deseja mais realizar seus pagamentos por meio do Pix Automático.

Alguns campos podem ser alterados somente enquanto a recorrência ainda estiver pendente de confirmação pelo pagador, são eles: Data prevista do primeiro pagamento e identificador da transação.

Outros campos podem ser alterados mesmo após a confirmação da recorrência, são eles: Location e nome do devedor.

  • Escopo requerido: rec.write
path Parameters
idRec
required
string (Id Recorrência)
Request Body schema: application/json

Dados para revisão da recorrência.

status
string (Status do registro da recorrência)
Value: "CANCELADA"
Pessoa Física (object) or Pessoa Jurídica (object) (devedor)

Contendo PessoaFisica ou PessoaJuridica

loc
integer <int64> (Id da location)

Identificador da location a ser informado na criação de uma recorrência.

object (Informações sobre calendário da recorrência)

Contendo dataInicial

object (Confirmação da ativação da recorrência)

Contendo dadosJornada

Responses

Request samples

Content type
application/json
{
  • "loc": 108,
  • "vinculo": {
    },
  • "calendario": {
    },
  • "ativacao": {
    }
}

Response samples

Content type
application/json
{
  • "idRec": "RN1234567820240115abcdefghijk",
  • "vinculo": {
    },
  • "calendario": {
    },
  • "politicaRetentativa": "NAO_PERMITE",
  • "recebedor": {
    },
  • "valor": {
    },
  • "status": "CRIADA",
  • "loc": {
    },
  • "ativacao": {
    },
  • "atualizacao": [
    ]
}

Solicitar Recorrência

Esta seção apresenta os endpoints relacionados ao gerenciamento de solicitações de confirmação de recorrência, que equivalem às autorizações necessárias.

Para que as recorrências tenham validade e possam gerar cobranças automaticamente, o cliente pagador precisa realizar o aceite.

Por meio dessa autorização, o cliente confirma que concorda com a recorrência estabelecida.

Criar solicitação de confirmação de recorrência

Endpoint utilizado para gerar a solicitação de recorrência.

Antes de gerar a solicitação de confirmação, é necessário criar a recorrência.

A autorização sempre estará vinculada a uma recorrência.

Para gerar a solicitação de confirmação, basta enviar o ID da recorrência, a data de expiração da solicitação e os dados do destinatário.

  • Escopo requerido: solicrec.write
Request Body schema: application/json

Dados para geração da solicitação da recorrência.

idRec
required
string (ID Recorrência) = 29 characters [a-zA-Z0-9]{29}

Identificador da Recorrência

Regra de formação:

  • RAxxxxxxxxyyyyMMddkkkkkkkkkkk (29 caracteres; "case sensitive", isso é, diferencia letras maiúsculas e minúsculas), sendo:
    • "R": fixo (1 caractere). "R" para a recorrência criada dentro do Pix;
    • "A": identificação da possibilidade de novas tentativas, sendo possíveis os valores "R" ou "N" (1 caractere). "R" caso a recorrência permita novas tentativas de pagamento pós vencimento, ou "N" caso não permita novas tentativas.
    • "xxxxxxxx": identificação do agente que presta serviço para o usuário recebedor que gerou o , podendo ser: o ISPB do participante direto, o ISPB do participante indireto ou os 8 primeiros dígitos do CNPJ do prestador de serviço de iniciação (8 caracteres numéricos [0-9]);
    • "yyyyMMdd": data (8 caracteres) de criação da recorrência;
    • "kkkkkkkkkkk": sequencial criado pelo agente que gerou o (11 caracteres alfanuméricos [a-z|A-Z|0-9]). Deve ser único dentro de cada "yyyyMMdd".

Dessa forma, o ID da recorrência deve ser formado de acordo com um dos tipos a seguir:

  • "RRxxxxxxxxyyyyMMddkkkkkkkkkkk"; para recorrência criada dentro do Pix e que permite novas tentativas de pagamento pós vencimento; ou
  • "RNxxxxxxxxyyyyMMddkkkkkkkkkkk"; para recorrência criada dentro do Pix e que não permite novas tentativas de pagamento pós vencimento.
required
object (Informações de calendário da solicitação da recorrência)

Contendo dataExpiracaoSolicitacao da solicitação de recorrência.

required
object or object (DadosBancarios)

Contendo conta, ìspbParticipante, agencia e cpf ou cnpj do recebedor.

Responses

Request samples

Content type
application/json
{
  • "idRec": "RN123456782024011577825445612",
  • "calendario": {
    },
  • "destinatario": {
    }
}

Response samples

Content type
application/json
{
  • "idSolicRec": "SC876456782024021577825445312",
  • "idRec": "RN123456782024011577825445612",
  • "calendario": {
    },
  • "status": "CRIADA",
  • "destinatario": {
    },
  • "atualizacao": [
    ],
  • "recPayload": {
    }
}

Consultar solicitação de recorrência.

Endpoint utilizado para consultar uma solicitação específica de recorrência.

O objetivo é obter os dados da solicitação de confirmação, como: status, informações do beneficiário, histórico de atualizações, política de retentativa, entre outros.

  • Escopo requerido: solicrec.read
path Parameters
idSolicRec
required
string (Id da solicitação da recorrência)

Responses

Response samples

Content type
application/json
Example
{
  • "idSolicRec": "SC876456782024021577825445312",
  • "idRec": "RN123456782024011577825445612",
  • "calendario": {
    },
  • "status": "CRIADA",
  • "destinatario": {
    },
  • "atualizacao": [
    ],
  • "recPayload": {
    }
}

Revisar solicitação de confirmação de recorrência.

Endpoint utilizado com o objetivo de cancelar uma solicitação de recorrência.

  • Escopo requerido: solicrec.write
path Parameters
idSolicRec
required
string (Id da solicitação da recorrência)
Request Body schema: application/json

Dados para revisão da solicitação da recorrência.

status
required
string (Status do registro da solicitação de recorrência)
Value: "CANCELADA"

Responses

Request samples

Content type
application/json
{
  • "status": "CANCELADA"
}

Response samples

Content type
application/json
{
  • "idSolicRec": "SC876456782024021577825445312",
  • "idRec": "RN123456782024011577825445612",
  • "calendario": {
    },
  • "status": "CANCELADA",
  • "destinatario": {
    },
  • "atualizacao": [
    ],
  • "recPayload": {
    }
}

Cobrança Recorrente

Esta seção apresenta os endpoints relacionados ao gerenciamento de cobranças associadas a uma recorrência.

As cobranças só poderão ser geradas utilizando este endpoint após a recorrência ser autorizada por meio da solicitação de recorrência (autorização).

Criar cobrança recorrente com TxId

Endpoint utilizado para gerar uma cobrança recorrente usando um txId específico.

Lembre-se de que as cobranças geradas nas jornadas de autorização 3 e 4 não são geradas por este endpoint.

Na jornada 3, será gerada uma cobrança do tipo "cob", enquanto na jornada 4 será uma cobrança do tipo "cobv".

Para a geração da cobrança recorrente, devem ser informados o ID da recorrência, a data de vencimento da cobrança, o valor, se ajusta para dia útil, os dados do devedor, os dados do recebedor, entre outros.

  • Escopo requerido: cobr.write
path Parameters
txid
required
string[a-zA-Z0-9]{26,35}

O campo txid determina o identificador da transação.

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.

Request Body schema: application/json

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

idRec
required
string (ID Recorrência) = 29 characters [a-zA-Z0-9]{29}

Identificador da Recorrência

Regra de formação:

  • RAxxxxxxxxyyyyMMddkkkkkkkkkkk (29 caracteres; "case sensitive", isso é, diferencia letras maiúsculas e minúsculas), sendo:
    • "R": fixo (1 caractere). "R" para a recorrência criada dentro do Pix;
    • "A": identificação da possibilidade de novas tentativas, sendo possíveis os valores "R" ou "N" (1 caractere). "R" caso a recorrência permita novas tentativas de pagamento pós vencimento, ou "N" caso não permita novas tentativas.
    • "xxxxxxxx": identificação do agente que presta serviço para o usuário recebedor que gerou o , podendo ser: o ISPB do participante direto, o ISPB do participante indireto ou os 8 primeiros dígitos do CNPJ do prestador de serviço de iniciação (8 caracteres numéricos [0-9]);
    • "yyyyMMdd": data (8 caracteres) de criação da recorrência;
    • "kkkkkkkkkkk": sequencial criado pelo agente que gerou o (11 caracteres alfanuméricos [a-z|A-Z|0-9]). Deve ser único dentro de cada "yyyyMMdd".

Dessa forma, o ID da recorrência deve ser formado de acordo com um dos tipos a seguir:

  • "RRxxxxxxxxyyyyMMddkkkkkkkkkkk"; para recorrência criada dentro do Pix e que permite novas tentativas de pagamento pós vencimento; ou
  • "RNxxxxxxxxyyyyMMddkkkkkkkkkkk"; para recorrência criada dentro do Pix e que não permite novas tentativas de pagamento pós vencimento.
infoAdicional
string (Informações adicionais da fatura.) <= 140 characters

Informações adicionais da fatura.

required
object (Informações sobre calendário da cobrança)

Contendo dataDeVencimento

required
object (Valor da cobrança recorrente)

Contendo valorOriginal

ajusteDiaUtil
required
boolean (Ajuste data vencimento para próximo dia útil)
Default: true

Campo de ativação do ajuste da data de vencimento para próximo dia útil caso o vencimento corrente seja um dia não útil. O PSP Pagador deverá considerar os feriados locais com base no código município do usuário pagador.

required
object (Dados bancários do recebedor)

Contendo nome, cnpj, conta, tipoConta e agencia

object (Dados do devedor)

Contendo email, logradouro, cidade, uf e cep

Responses

Request samples

Content type
application/json
{
  • "idRec": "RR1234567820240115abcdefghijk",
  • "infoAdicional": "Serviços de Streamming de Música e Filmes.",
  • "calendario": {
    },
  • "valor": {
    },
  • "ajusteDiaUtil": true,
  • "devedor": {
    },
  • "recebedor": {
    }
}

Response samples

Content type
application/json
{
  • "idRec": "RR1234567820240115abcdefghijk",
  • "txid": "3136957d93134f2184b369e8f1c0729d",
  • "infoAdicional": "Serviços de Streamming de Música e Filmes.",
  • "calendario": {
    },
  • "valor": {
    },
  • "status": "CRIADA",
  • "politicaRetentativa": "PERMITE_3R_7D",
  • "ajusteDiaUtil": true,
  • "devedor": {
    },
  • "recebedor": {
    },
  • "atualizacao": [
    ]
}

Revisar cobrança recorrente

Endpoint utilizado com o objetivo de cancelar uma cobrança recorrente.

  • Escopo requerido: cobr.write
path Parameters
txid
required
string[a-zA-Z0-9]{26,35}

O campo txid determina o identificador da transação.

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.

Request Body schema: application/json

Dados para geração da cobrança.

status
string (Status do registro da cobrança)
Value: "CANCELADA"

Responses

Request samples

Content type
application/json
{
  • "status": "CANCELADA"
}

Response samples

Content type
application/json
{
  • "idRec": "RN985156112024071999000566354",
  • "txid": "517bd858b59d458a841280b0f0a60bfa",
  • "calendario": {
    },
  • "valor": {
    },
  • "status": "CANCELADA",
  • "politicaRetentativa": "NAO_PERMITE",
  • "ajusteDiaUtil": true,
  • "devedor": {
    },
  • "recebedor": {
    },
  • "tentativas": [
    ],
  • "encerramento": {
    },
  • "atualizacao": [
    ]
}

Consultar cobrança recorrente

Endpoint utilizado para consultar uma cobrança recorrente específica.

O objetivo é obter os dados da cobrança recorrente, como: status, histórico de atualizações, política de retentativa, entre outros.

  • Escopo requerido: cobr.read
path Parameters
txid
required
string[a-zA-Z0-9]{26,35}

O campo txid determina o identificador da transação.

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.

Responses

Response samples

Content type
application/json
Example
{
  • "idRec": "RR1234567820240115abcdefghijk",
  • "txid": "3136957d93134f2184b369e8f1c0729d",
  • "infoAdicional": "Serviços de Streamming de Música e Filmes.",
  • "calendario": {
    },
  • "valor": {
    },
  • "status": "CRIADA",
  • "politicaRetentativa": "PERMITE_3R_7D",
  • "ajusteDiaUtil": true,
  • "devedor": {
    },
  • "recebedor": {
    },
  • "atualizacao": [
    ]
}

Criar cobrança recorrente

Endpoint utilizado para gerar uma cobrança recorrente.

Lembre-se de que as cobranças geradas nas jornadas de autorização 3 e 4 não são geradas por este endpoint.

Na jornada 3, será gerada uma cobrança do tipo "cob", enquanto na jornada 4 será uma cobrança do tipo "cobv".

Para a geração da cobrança recorrente, devem ser informados o ID da recorrência, a data de vencimento da cobrança, o valor, se ajusta para dia útil, os dados do devedor, os dados do recebedor, entre outros.

  • Escopo requerido: cobr.write
Authorizations:
None
Request Body schema: application/json

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

idRec
required
string (ID Recorrência) = 29 characters [a-zA-Z0-9]{29}

Identificador da Recorrência

Regra de formação:

  • RAxxxxxxxxyyyyMMddkkkkkkkkkkk (29 caracteres; "case sensitive", isso é, diferencia letras maiúsculas e minúsculas), sendo:
    • "R": fixo (1 caractere). "R" para a recorrência criada dentro do Pix;
    • "A": identificação da possibilidade de novas tentativas, sendo possíveis os valores "R" ou "N" (1 caractere). "R" caso a recorrência permita novas tentativas de pagamento pós vencimento, ou "N" caso não permita novas tentativas.
    • "xxxxxxxx": identificação do agente que presta serviço para o usuário recebedor que gerou o , podendo ser: o ISPB do participante direto, o ISPB do participante indireto ou os 8 primeiros dígitos do CNPJ do prestador de serviço de iniciação (8 caracteres numéricos [0-9]);
    • "yyyyMMdd": data (8 caracteres) de criação da recorrência;
    • "kkkkkkkkkkk": sequencial criado pelo agente que gerou o (11 caracteres alfanuméricos [a-z|A-Z|0-9]). Deve ser único dentro de cada "yyyyMMdd".

Dessa forma, o ID da recorrência deve ser formado de acordo com um dos tipos a seguir:

  • "RRxxxxxxxxyyyyMMddkkkkkkkkkkk"; para recorrência criada dentro do Pix e que permite novas tentativas de pagamento pós vencimento; ou
  • "RNxxxxxxxxyyyyMMddkkkkkkkkkkk"; para recorrência criada dentro do Pix e que não permite novas tentativas de pagamento pós vencimento.
infoAdicional
string (Informações adicionais da fatura.) <= 140 characters

Informações adicionais da fatura.

required
object (Informações sobre calendário da cobrança)

Contendo dataDeVencimento

required
object (Valor da cobrança recorrente)

Contendo valorOriginal

ajusteDiaUtil
required
boolean (Ajuste data vencimento para próximo dia útil)
Default: true

Campo de ativação do ajuste da data de vencimento para próximo dia útil caso o vencimento corrente seja um dia não útil. O PSP Pagador deverá considerar os feriados locais com base no código município do usuário pagador.

required
object (Dados bancários do recebedor)

Contendo nome, cnpj, conta, tipoConta e agencia

object (Dados do devedor)

Contendo email, logradouro, cidade, uf e cep

Responses

Request samples

Content type
application/json
{
  • "idRec": "RR1234567820240115abcdefghijk",
  • "infoAdicional": "Serviços de Streamming de Música e Filmes.",
  • "calendario": {
    },
  • "valor": {
    },
  • "ajusteDiaUtil": true,
  • "devedor": {
    },
  • "recebedor": {
    }
}

Response samples

Content type
application/json
{
  • "idRec": "RR1234567820240115abcdefghijk",
  • "txid": "3136957d93134f2184b369e8f1c0729d",
  • "infoAdicional": "Serviços de Streamming de Música e Filmes.",
  • "calendario": {
    },
  • "status": "CRIADA",
  • "valor": {
    },
  • "politicaRetentativa": "PERMITE_3R_7D",
  • "ajusteDiaUtil": true,
  • "devedor": {
    },
  • "recebedor": {
    },
  • "atualizacao": [
    ]
}

Consultar lista de cobranças recorrentes

Endpoint utilizado para consultar uma lista de cobranças recorrentes através de parâmetros como início, fim, idRec, cpf, cnpj e status. Endpoint utilizado para consultar várias cobranças recorrentes.

Tem por objetivo consultar os dados das cobranças recorrentes como: idRec, txId, valor, status, pix, dentre outros.

Pode ser chamado passando parâmetros, como: período, CPF, CNPJ, status.

  • Escopo requerido: cobr.read
query Parameters
inicio
required
string <date-time> (Data de início)
Example: inicio=2023-02-30T12:09:00Z

Formato: yyyy-MM-dd'T'HH:mm:ss[.SSS]XXX

fim
required
string <date-time> (Data de fim)
Example: fim=2023-03-30T12:09:00Z

Formato: yyyy-MM-dd'T'HH:mm:ss[.SSS]XXX

idRec
string (ID Recorrência) = 29 characters [a-zA-Z0-9]{29}

Filtro pelo Identificador da Recorrência.

cpf
string (CPF)

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

cnpj
string (CNPJ)

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

status
string (Status do registro da recorrência)
Enum: "CRIADA" "APROVADA" "REJEITADA" "EXPIRADA" "CANCELADA"

Filtro pelo status da recorrência.

paginacao.paginaAtual
integer <int32> (Página atual)
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) <= 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.

convenio
string (Convênio) <= 60 characters

Filtro pelo convênio associado.

Responses

Response samples

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

Solicitar retentativa de cobrança.

Endpoint utilizado para solicitar a retentativa de uma cobrança recorrente.

Caso uma cobrança não seja liquidada na data esperada, o cliente recebedor pode solicitar uma nova tentativa de liquidação.

Para isso, ele precisa informar o TXID e a data prevista de liquidação da cobrança em questão.

  • Escopo requerido: cobr.write
path Parameters
txid
required
string[a-zA-Z0-9]{26,35}

O campo txid determina o identificador da transação.

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.

data
required
string <date>
Example: 2023-04-01

Data prevista para liquidação da ordem de pagamento correspondente. Trata-se de uma data, no formato YYYY-MM-DD, segundo ISO 8601.

Responses

Response samples

Content type
application/json
{
  • "idRec": "RR123456782024061999000566354",
  • "txid": "7f733863543b4a16b516d839bd4bc34e",
  • "calendario": {
    },
  • "valor": {
    },
  • "status": "ATIVA",
  • "politicaRetentativa": "PERMITE_3R_7D",
  • "ajusteDiaUtil": true,
  • "devedor": {
    },
  • "recebedor": {
    },
  • "tentativas": [
    ],
  • "atualizacao": [
    ]
}

Location da Recorrência

Esta seção apresenta os endpoints relacionados ao gerenciamento de payloads associadas a uma recorrência.

Criar location do payload.

Endpoint utilizado para criar o payload location da recorrência.

  • Escopo requerido: payloadlocationrec.write

Responses

Response samples

Content type
application/json
{
  • "id": 12069,
  • "location": "pix.example.com/qr/v2/rec/2353c790eefb11eaadc10242ac120002",
  • "criacao": "2023-12-20T12:38:28.774Z"
}

Consultar locations cadastradas.

Endpoint utilizado para consultar as locations de recorrência cadastradas.

  • Escopo requerido: payloadlocationrec.read
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.

idRecPresente
boolean
convenio
string (Convênio) <= 60 characters

Filtro pelo convênio associado.

paginacao.paginaAtual
integer <int32> (Página atual)
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) <= 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": {
    },
  • "loc": [
    ]
}

Recuperar location do payload.

Endpoint utilizado para recuperar a location do payload

  • Escopo requerido: payloadlocationrec.read
path Parameters
id
required
string (Id da location cadastrada para servir um payload)

Responses

Response samples

Content type
application/json
{
  • "id": 12069,
  • "location": "pix.example.com/qr/v2/rec/2353c790eefb11eaadc10242ac120002",
  • "criacao": "2023-12-20T12:38:28.774Z",
  • "idRec": "RR123456782024011510056892226"
}

Desvincular uma recorrência de uma location.

Endpoint destinado para desvincular uma recorrência de uma location.

Se executado com sucesso, a entidade loc não apresentará mais uma recorrência, se apresentava anteriormente à chamada.

Adicionalmente, a entidade associada ao recurso desvinculado também passará a não mais apresentar um location.

Esta operação não altera o status do recurso em questão.

  • Escopo requerido: payloadlocationrec.write
path Parameters
id
required
string (Id da location cadastrada para servir um payload)

Responses

Response samples

Content type
application/json
{
  • "id": 12069,
  • "location": "pix.example.com/qr/v2/rec/2353c790eefb11eaadc10242ac120002",
  • "criacao": "2023-12-20T12:38:28.774Z"
}

Webhook de Recorrências

Esta seção apresenta os endpoints relacionados ao gerenciamento do serviço de notificações acerca de recorrências.

Criar WebhookRec

Endpoint destinado a criar um webhook para receber notificações (callbacks) relacionados a recorrências.

Somente recorrências associadas a chave e conta serão notificadas.

Caso o servidor de webhook retorne erro de recebimento do callback, serão realizadas até 4 tentativas com intervalos de 20, 30, 60 e 120 minutos.

  • Escopo requerido: webhookrec.write
Request Body schema: application/json
webhookUrl
required
string <uri> (URL Webhook)

Responses

Callbacks

Request samples

Content type
application/json
{}

Response samples

Content type
application/problem+json
{}

Callback payload samples

Callback
POST: {$request.body#/webhookUrl}/rec
Content type
application/json
{
  • "recs": [
    ]
}

Consultar Webhook cadastrado

Endpoint utilizado para recuperar de informações sobre o Webhook cadastrado.

  • Escopo requerido: webhookrec.read

Responses

Response samples

Content type
application/json
{}

Excluir Webhook

Endpoint destinado ao cancelamento de um webhookRec.

  • Escopo requerido: webhookrec.write

Responses

Response samples

Content type
application/problem+json
{}

Webhook de Cobranças Recorrentes

Esta seção apresenta os endpoints relacionados ao gerenciamento do serviço de notificações de cobranças recorrentes.

Criar WebhookCobR

Endpoint destinado a criar um webhook para receber notificações (callbacks) relacionados a cobranças recorrentes.

Somente cobranças recorrentes associadas ao usuário recebedor serão notificadas.

Caso o servidor de webhook retorne erro de recebimento do callback, serão realizadas até 4 tentativas com intervalos de 20, 30, 60 e 120 minutos.

  • Escopo requerido: webhookcobr.write
Request Body schema: application/json
webhookUrl
required
string <uri> (URL Webhook)

Responses

Callbacks

Request samples

Content type
application/json
{}

Response samples

Content type
application/problem+json
{}

Callback payload samples

Callback
POST: {$request.body#/webhookUrl}/cobr
Content type
application/json
{
  • "cobsr": [
    ]
}

Consultar Webhook cadastrado

Endpoint utilizado para recuperar de informações sobre o Webhook cadastrado.

  • Escopo requerido: webhookcobr.read

Responses

Response samples

Content type
application/json
{}

Excluir Webhook

Endpoint destinado ao cancelamento de um webhookCobR.

  • Escopo requerido: webhookcobr.write

Responses

Response samples

Content type
application/problem+json
{}