Skip to main content

Recurrent Payments

The following endpoints are responsible for Recurrent Payments


Important!

This feature is currently in beta. We are excited to provide you with this tool, but please note that it is still under active development and changes may apply during this period.

Your feedback is incredibly valuable to us during this phase. We invite you to share your experiences and suggestions to help us improve. Feel free to reach out through our Discord community or other support channels.


Information

The first charge of a recurring Pix payment must occur at least one day after the scheduling confirmation. This means that the first payment cannot be made on the same day that the recurrences are confirmed in the customer's choice of bank.

Additionally, for Recurring Pix it is only required a single authorization to set up the entire schedule of future debits. Once authorized all subsequent Pix payments will be processed automatically according to the established plan.


Request to start using Recurrent 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-recorrentes/pix
Requires authorization for the scope: gn.opb.payment.pix.send


Request

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.90",
    "codigoCidadeIBGE": "3540000",
    "infoPagador": "Churrasco",
    "idProprio": "6236574863254",
    "recorrencia": {
      "tipo": "diaria",
      "dataInicio": "2025-12-31",
      "quantidade": 3
    },
    "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"
  }
}

Responses

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

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

List of Recurrent Payments for a Specific Period​

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

GET /v1/pagamentos-recorrentes/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-recorrentes/pix?inicio=2022-05-01&fim=2022-12-30

Responses

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

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

Cancel a scheduled payment​

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

PATCH /v1/pagamentos-recorrentes/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.

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

Perform a recurrent payment refund​

This endpoint is used to process a recurrent payment refund. It must receive as input a valid endToEndId in the parameter and the value to be returned in the body of the request.

POST /v1/pagamentos-recorrentes/pix/:identificadorPagamento/devolver
Requires authorization for the scope: gn.opb.payment.pix.refund


Request

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

Responses

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

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

Replace recurrent payment parcel​

Information

This endpoint only works for payments (parcels) with the status cancelado or rejeitado.


This endpoint is a tool for replacing parcels for recurring payments. This endpoint must receive a identificadorPagamento and a validendToEndId as parameters. It is also possible to enter the valor field in the body of the request to specify a value for the new parcel. If not entered, the system understands that the new parcel will have the same value as the previous parcel. This endpoint only works for payments (parcel) with the status cancelado or rejeitado.

PATCH /v1/pagamentos-recorrentes/pix/:identificadorPagamento/substituir/:endToEndId
Requires authorization for the scope: gn.opb.payment.pix.send


Request

{
  "valor": "9.99"
}


Responses

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

{
  "identificadorPagamento": "urn:efi:ae71713f-875b-4af3-9d85-0bcb43288847",
  "redirectURI": "https://open-finance.banco.com.br/authorize?request=eyJjd&redirect_uri=https://pub.opb.testegerencianet.com.br/callback&scope=openid%20pagamentos%20consent:urn:efi:fdf36ac8-f213-4057-bf2e-2ce7bd828abf&response_type=code%20id_token"
}
Last updated on