Scheduled Payments

The following endpoints are responsible for Scheduled Payments

Request to start using Scheduled Pix via Open Finance

This endpoint is used to enter payment information that will be initiated in the Open Finance API. The response of this endpoint will be a redirection URL, which must be incorporated into a button in the application or web page. When the user clicks on this button, they will be redirected to the account holding institution, where the payment will be made.

POST /v1/pagamentos-agendados/pix

Requires authorization for the scope: gn.opb.payment.pix.send

Request

Payment initiation (account)

Example of payment initiation
{
  "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": "TRAN"
    }
  },
  "pagamento": {
    "valor": "9.99",
    "infoPagador": "Churrasco",
    "idProprio": "6236574863254",
    "dataAgendamento": "2024-08-06",
    "identificadorTransacao": "E00038166201907261559y6j6"
  }
}

Payment initiation (Pix key)

Example of payment initiation
{
  "pagador": {
    "idParticipante": "9f4cd202-8f2b-11ec-b909-0242ac120002",
    "cpf": "45204392050",
    "cnpj": "90293071000112"
  },
  "favorecido": {
    "chave": "2badfe30-d03b-4da1-9f2f-02b5dcef765c"
  },
  "pagamento": {
    "valor": "9.99",
    "infoPagador": "Churrasco",
    "idProprio": "6236574863254",
    "dataAgendamento": "2024-08-06",
    "identificadorTransacao": "E00038166201907261559y6j6"
  }
}

Payment initiation (qrcode)

Example of payment initiation
{
  "pagador": {
    "idParticipante": "9f4cd202-8f2b-11ec-b909-0242ac120002",
    "cpf": "51687574219",
    "cnpj": "90293071000112"
  },
  "pagamento": {
    "valor": "9.99",
    "infoPagador": "Churrasco",
    "idProprio": "6236574863254",
    "qrCode": "00020104141234567890123426660014BR.GOV.BCB.PIX014466756C616E6F32303139406578616D706C652E636F6D27300012BR.COM.OUTRO011001234567895204000053039865406123.455802BR5915NOMEDORECEBEDOR6008BRASILIA61087007490062530515RP12345678-201950300017BR.GOV.BCB.BRCODE01051.0.080450014BR.GOV.BCB.PIX0123PADRAO.URL.PIX/0123ABCD81390012BR.COM.OUTRO01190123.ABCD.3456.WXYZ6304EB76",
    "identificadorTransacao": "E00038166201907261559y6j6"
  }
}

Responses

The responses below represent Success(200) and consumption failures/errors.

🟢 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"
}

Or

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

Or

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

Or

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

Or

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

Or

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

Or

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

Or

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

Or

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

Or

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

Or

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

Or

{
  "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"
}

Or

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

Or

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

Or

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

Or

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

Or

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

Or

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

Or

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

Or

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

Or

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

Or

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

Or

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

Or

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

🔴 431

Application error
{
  "nome": "chave_idempotencia_invalida",
  "mensagem": "Tamanho da chave de idempotência inválido"
}

🔴 500

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

List of Scheduled Payments for a Specific Period

This endpoint is used to list information about scheduled payments that were made within a specific time period.

GET /v1/pagamentos-agendados/pix

Requires authorization for the scope: gn.opb.payment.pix.read

Request

To obtain the query result, it is necessary to inform the parameters `inicio` and `fim`, as shown in the code snippet below. These parameters represent the date range within which the queried payments should be included.
/v1/pagamentos-agendados/pix?inicio=2022-05-01&fim=2022-12-30

Responses

The responses below represent Success(200) and consumption failures/errors.

🟢 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"
}

Or

{
  "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"
}

Or

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

Or

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

Or

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

🔴 500

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

Cancel a scheduled payment

This endpoint is used to cancel a recurring payment. It must receive as input a valid Payment identifier in the parameter.

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

Requires authorization for the scope: gn.opb.payment.pix.cancel

Request

The request sent to this endpoint does not need a body, only the OAuth authorization headers, the parameters and the account certificate.

Responses

The responses below represent Success(200) and consumption failures/errors.

🟢 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"
}

Perform a Scheduled payment refund

This endpoint is used to process a scheduled payment refund. It must receive as input the Payment identifier and the amount to be returned in the body of the request.

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

Requires authorization for the scope: gn.opb.payment.pix.refund

Request

Refund

{
  "endToEndId": "E09089356202408281500624f423208f",
  "valor": "0.01"
}

Responses

The responses below represent Success(202) and consumption failures/errors.

🟢 202

Processing refund
{
  "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"
}

Or

{
  "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"
}