Pagamentos Agendados

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

Solicitar iniciação de Pix Agendado 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-agendados/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.99",
    "codigoCidadeIBGE": "3540000",
    "infoPagador": "Churrasco",
    "idProprio": "6236574863254",
    "dataAgendamento": "2024-08-06"
  }
}

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 agendados por um determinado período

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

GET /v1/pagamentos-agendados/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-agendados/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",
      "endToEndId": "E00038166201907261559y6j6",
      "valor": "1.99",
      "status": "aceito",
      "dataOperacao": "2024-06-08",
      "dataCriacao": "2022-06-09T11:55:03.000Z",
      "idProprio": "6236574863254",
      "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 agendado

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

PATCH /v1/pagamentos-agendados/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 agendado

Este endpoint é utilizado para realizar a devolução de um pagamento agendado. Deve receber como entrada o identificadorPagamento e o valor a ser devolvido no corpo da requisição.

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

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

Requisição

Devolução

{
  "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": "E090893562024072215009e91a097af2",
  "valor": "0.01",
  "dataCriacao": "2022-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"
}