Immediate Payments

The following endpoints are responsible for Immediate Payments

Request to start using 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/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": "51687574219",
    "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",
    "identificadorTransacao": "E00038166201907261559y6j6"
  }
}

Payment initiation (Pix key)

Example of payment initiation
{
  "pagador": {
    "idParticipante": "9f4cd202-8f2b-11ec-b909-0242ac120002",
    "cpf": "51687574219",
    "cnpj": "90293071000112"
  },
  "favorecido": {
    "chave": "2badfe30-d03b-4da1-9f2f-02b5dcef765c"
  },
  "pagamento": {
    "valor": "9.99",
    "infoPagador": "Churrasco",
    "idProprio": "6236574863254",
    "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 Payments for a Specific Period

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

GET /v1/pagamentos/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/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",
      "dataCriacao": "2022-04-29T11:55:03.000Z",
      "devolucoes": [
        {
          "identificadorDevolucao": "D09089356202211111429d82ecc2ecde",
          "valor": "1.99",
          "status": "aceito",
          "dataCriacao": "2022-04-29T11:59:03.000Z"
        }
      ],
      "idProprio": "6236574863254"
    }
  ],
  "total": 3,
  "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"
}

Perform a payment refund

This endpoint is used to process a payment refund.

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

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

Request

Refund

{
  "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": "identificador_pagamento_invalido",
  "mensagem": "O identificador de pagamento é inválido"
}

Or

{
  "nome": "status_pagamento_invalido_para_devolucao",
  "mensagem": "O status do pagamento é invalido para devolução"
}

Or

{
  "nome": "saldo_devolucao_insuficiente",
  "mensagem": "O valor da devolução ultrapassou o valor recebido"
}

Or

{
  "nome": "saldo_insuficiente",
  "mensagem": "O saldo em conta é insuficiente para efetuar esta transação"
}

🔴 500

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