Pagamentos Recorrentes

Os endpoints a seguir são responsáveis pelos Pagamentos Recorrentes

Importante!

Atualmente este recurso está em versão beta. Estamos entusiasmados em compartilhar essa ferramenta com você, porém, é essencial lembrar que ela está em desenvolvimento ativo e pode passar por alterações durante este período.

Valorizamos profundamente seu feedback durante esta fase e queremos ouvir suas experiências e sugestões para aprimorar continuamente nossos serviços. Sinta-se à vontade para entrar em contato conosco por meio de nossa comunidade do Discord ou outros canais de suporte.

Informação

A primeira cobrança de um Pix recorrente deve ocorrer, no mínimo, um dia após a confirmação dos agendamentos. Isso significa que não é possível que o primeiro pagamento seja realizado no mesmo dia em que as recorrências forem confirmadas.

Além disso, para os Pagamentos Recorrentes basta um único aceite para configurar todo cronograma de débitos futuros. Uma vez autorizado, todos os pagamentos Pix subsequentes serão processados automaticamente de acordo com o plano estabelecido.

Solicitar iniciação de Pix Recorrente via Open Finance

Este endpoint é utilizado para inserir as informações do pagamento que será iniciado na API Open Finance. A resposta desse endpoint será uma URL de redirecionamento, que deve ser incorporada a um botão no aplicativo ou página web. Quando a pessoa usuária clicar nesse botão, ela será redirecionada para a instituição detentora da conta, onde o pagamento será efetuado.

POST /v1/pagamentos-recorrentes/pix

Requer autorização para o escopo: gn.opb.payment.pix.send

Requisição

Iniciação de pagamento

Exemplo de iniciação de pagamento
{
  "pagador": {
    "idParticipante": "9f4cd202-8f2b-11ec-b909-0242ac120002",
    "cpf": "45204392050",
    "cnpj": "90293071000112"
  },
  "favorecido": {
    "contaBanco": {
      "nome": "Lucas Silva",
      "documento": "17558266300",
      "codigoBanco": "09089356",
      "agencia": "0001",
      "conta": "654984",
      "tipoConta": "CACC"
    }
  },
  "pagamento": {
    "valor": "9.90",
    "codigoCidadeIBGE": "3540000",
    "infoPagador": "Churrasco",
    "idProprio": "6236574863254",
    "recorrencia": {
      "tipo": "diaria",
      "dataInicio": "2025-12-31",
      "quantidade": 8,
      "diaDaSemana": "SEGUNDA_FEIRA",
      "diaDoMes": 15,
      "datas": [
        "2024-08-01",
        "2024-08-08",
        "2024-08-15"
      ],
      "descricao": "Petshop"
    }
  }
}

Respostas

As respostas abaixo representam Sucesso(200) e Falhas/erros do consumo.

🟢 200

{
  "identificadorPagamento": "urn:efi:ae71713f-875b-4af3-9d85-0bcb43288847",
  "redirectURI": "https://open-finance.banco.com.br/authorize?request=eyJjd"
}

🔴 400

{
  "nome": "codigo_banco_favorecido_obrigatorio",
  "mensagem": "O código do banco favorecido é obrigatório"
}

Ou

{
  "nome": "agencia_favorecido_obrigatorio",
  "mensagem": "A agência do favorecido é obrigatório"
}

Ou

{
  "nome": "numero_conta_favorecido_obrigatorio",
  "mensagem": "O número da conta do favorecido é obrigatório"
}

Ou

{
  "nome": "tipo_conta_favorecido_obrigatorio",
  "mensagem": "O tipo conta do favorecido é obrigatório"
}

Ou

{
  "nome": "documento_favorecido_obrigatorio",
  "mensagem": "O documento do favorecido é obrigatório"
}

Ou

{
  "nome": "nome_favorecido_obrigatorio",
  "mensagem": "O nome do favorecido é obrigatório"
}

Ou

{
  "nome": "cpf_pagador_obrigatorio",
  "mensagem": "O cpf do pagador é obrigatório"
}

Ou

{
  "nome": "dados_pagador_obrigatorio",
  "mensagem": "Os dados do pagador são obrigatórios"
}

Ou

{
  "nome": "erro_iniciacao_pagamento",
  "mensagem": "${mensagem}"
}

Ou

{
  "nome": "chave_idempotencia_obrigatorio",
  "mensagem": "O cabeçalho de 'x-idempotency-key' é obrigatório"
}

Ou

{
  "nome": "identificador_participante_obrigatorio",
  "mensagem": "O identificador do participante é requerido"
}

Ou

{
  "nome": "valor_obrigatorio",
  "mensagem": "O valor da transação é obrigatório"
}

🔴 409

{
  "nome": "conflito_chave_idempotencia",
  "mensagem": "Chave de idempotência repetida para pagamento diferente"
}

🔴 422

{
  "nome": "codigo_banco_nao_permitido",
  "mensagem": "O código do banco informado não é permitido"
}

Ou

{
  "nome": "codigo_banco_invalido",
  "mensagem": "O código do banco é inválido"
}

Ou

{
  "nome": "agencia_invalida",
  "mensagem": "A agência é invalida"
}

Ou

{
  "nome": "numero_conta_favorecido_invalido",
  "mensagem": "O número da conta do favorecido é inválido"
}

Ou

{
  "nome": "tipo_conta_favorecido_invalida",
  "mensagem": "O tipo conta do favorecido é invalida, permitido (CACC/SLRY/SVGS/TRAN)"
}

Ou

{
  "nome": "documento_favorecido_invalido",
  "mensagem": "O documento do favorecido é inválido"
}

Ou

{
  "nome": "id_proprio_invalido",
  "mensagem": "O campo idProprio deve ser texto"
}

Ou

{
  "nome": "cnpj_pagador_invalido",
  "mensagem": "O cnpj do pagador é obrigatório"
}

Ou

{
  "nome": "cpf_pagador_invalido",
  "mensagem": "O cpf do pagador é obrigatório"
}

Ou

{
  "nome": "codigo_cidade_ibge_invalido",
  "mensagem": "O código de IBGE da cidade é inválido"
}

Ou

{
  "nome": "nome_favorecido_invalido",
  "mensagem": "O nome do favorecido é inválido"
}

Ou

{
  "nome": "identificador_participante_invalido",
  "mensagem": "O identificador do participante é inválido"
}

Ou

{
  "nome": "valor_invalido",
  "mensagem": "O valor da transação é inválido"
}

🔴 431

Erro na aplicação
{
  "nome": "chave_idempotencia_invalida",
  "mensagem": "Tamanho da chave de idempotência inválido"
}

🔴 500

Erro na aplicação
{
  "nome": "erro_aplicacao",
  "mensagem": "Erro interno do servidor"
}

Listar pagamentos recorrentes por um determinado período

Este endpoint é utilizado para listar as informações dos pagamentos recorrentes que foram efetuados em um período de tempo.

GET /v1/pagamentos-recorrentes/pix

Requer autorização para o escopo: gn.opb.payment.pix.read

Requisição

Para obter o resultado da consulta é necessário informar os parâmetros inicio e fim, como exibido no trecho de código abaixo. Esses parâmetros representam o intervalo de datas em que as cobranças consultadas devem estar compreendidas.
/v1/pagamentos-recorrentes/pix?inicio=2022-05-01&fim=2022-12-30

Respostas

As respostas abaixo representam Sucesso(200) e Falhas/erros do consumo.

🟢 200

{
  "pagamentos": [
    {
      "identificadorPagamento": "urn:efi:49315a93-d39c-4564-9edb-9a73678dbdb1",
      "valor": "1.99",
      "status": "ativa",
      "dataCriacao": "2022-06-09T11:55:03.000Z",
      "idProprio": "6236574863254",
      "recorrencias": [
        {
          "endToEndId": "E00038166201907261559y6j6",
          "dataOperacao": "2024-06-08",
          "status": "pendente",
          "devolucoes": [
            {
              "identificadorDevolucao": "D09089356202211111429d82ecc2ecde",
              "valor": "1.99",
              "status": "aceito",
              "dataCriacao": "2022-04-29T11:59:03.000Z"
            }
          ]
        }
      ]
    }
  ],
  "total": 1,
  "porPagina": 1,
  "ultimo": "/pagamentos/pix?inicio=2022-04-29&fim=2022-04-29&quantidade=1&pagina=3",
  "proximo": "/pagamentos/pix?inicio=2022-04-29&fim=2022-04-29&quantidade=1&pagina=2",
  "anterior": null,
  "atual": "/pagamentos/pix?inicio=2022-04-29&fim=2022-04-29&quantidade=1&pagina=1"
}

🔴 400

{
  "nome": "data_inicio_invalido",
  "mensagem": "A data início é inválida"
}

Ou

{
  "nome": "data_fim_invalido",
  "mensagem": "A data fim é inválida"
}

🔴 404

{
  "nome": "pagamento_nao_encontrado",
  "mensagem": "Nenhum pagamento encontrado"
}

🔴 422

{
  "nome": "data_inicio_obrigatorio",
  "mensagem": "A data início é obrigatória"
}

Ou

{
  "nome": "data_fim_obrigatorio",
  "mensagem": "A data fim é obrigatória"
}

Ou

{
  "nome": "identificador_pagamento_invalido",
  "mensagem": "O identificador do pagamento é inválido"
}

Ou

{
  "nome": "status_pagamento_invalido",
  "mensagem": "O status do pagamento informado é inválido, permitido (pendente/agendado/rejeitado/aceito/erro)"
}

🔴 500

Erro na aplicação
{
  "nome": "erro_aplicacao",
  "mensagem": "Erro interno do servidor"
}

Cancelar um pagamento recorrente

Este endpoint é utilizado para cancelar um pagamento recorrente. Deve receber como entrada um identificadorPagamento ou EndToEndId válido no parametro.

PATCH /v1/pagamentos-recorrentes/pix/:identificadorPagamento/cancelar

Requer autorização para o escopo: gn.opb.payment.pix.cancel

Requisição

A requisição enviada para esse endpoint não precisa de um body, apenas os cabeçalhos de autorização OAuth, parâmetros e o certificado da conta.

Respostas

As respostas abaixo representam Sucesso(200) e Falhas/erros do consumo.

🟢 200

{
  "identificadorPagamento": "urn:efi:ae71713f-875b-4af3-9d85-0bcb43288847",
  "status": "cancelado",
  "dataCancelamento": "2023-08-16 10:02:25"
}

🔴 400

{
  "nome": "identificador_pagamento_obrigatorio",
  "mensagem": "O campo identificadorPagamento é obrigatório"
}

🔴 422

{
  "nome": "identificador_pagamento_invalido",
  "mensagem": "O identificador do pagamento é inválido"
}

🔴 500

{
  "nome": "erro_aplicacao",
  "mensagem": "Erro interno do servidor"
}

Efetuar uma devolução de um pagamento recorrente

Este endpoint é utilizado para realizar a devolução de um pagamento recorrente. Deve receber como entrada um endToEndId válido no parâmetro e o valor a ser devolvido no corpo da requisição.

POST /v1/pagamentos-recorrentes/pix/:identificadorPagamento/devolver

Requer autorização para o escopo: gn.opb.payment.pix.refund

Requisição

Devolução

[
  {
    "endToEndId": "E09089356202408281500624f423208f",
    "valor": "0.01"
  },
  {
    "endToEndId": "E09089356202408291500a0ecaa22e86",
    "valor": "0.01"
  }
]

Respostas

As respostas abaixo representam Sucesso(202) e Falhas/erros do consumo.

🟢 202

Processando devolução
[
{
  "identificadorPagamento": "urn:efi:ae71713f-875b-4af3-9d85-0bcb43288847",
  "endToEndId": "E09089356202408281500624f423208f",
  "valor": "0.01",
  "dataCriacao": "2024-09-06 15:15:21",
  "status": "pendente"
},
{
  "identificadorPagamento": "urn:efi:89744c4c-1b05-4aea-8237-a78e4ea0b9a7",
  "endToEndId": "E09089356202408291500a0ecaa22e86",
  "valor": "0.01",
  "dataCriacao": "2024-10-28 10:02:25",
  "status": "pendente"
}
]

🔴 400

Erro na requisição
{
  "nome": "identificador_pagamento_obrigatorio",
  "mensagem": "O campo identificadorPagamento é obrigatório"
}

Ou

{
  "nome": "valor_devolucao_invalido",
  "mensagem": "O valor de devolução inválido"
}

🔴 422

Erro na requisição
{
  "nome": "endToEnd_pagamento_invalido",
  "mensagem": "O endToEnd do pagamento é inválido"
}

🔴 500

Erro no servidor
{
  "nome": "erro_aplicacao",
  "mensagem": "Erro interno do servidor"
}