Skip to main content

Automatic payments

The following endpoints are responsible for initiating and managing Automatic Payments




Atenção!

To use the Automatic Payments features, you need to have an Efí Business Digital Account.


Request creation of an enrollment for automatic payment​

This endpoint is used to receive a request from the integrator to create the automatic payment consent and return a redirect URL.

POST /v1/pagamentos-automaticos/adesao
Requires authorization for the scope: gn.opb.automatic.consent.write


Request

{
  "pagador": {
    "cpf": "10134280059",
    "cnpj": "34836879000128",
    "nome": "Josué Villa Real",
    "idParticipante": "64c189e5-9d4a-4319-aa5e-d02c36e1815d"
  },
  "favorecido": {
    "contaBanco": {
      "nome": "Lucas Silva",
      "documento": "17558266300",
      "codigoBanco": "09089356",
      "agencia": "0001",
      "conta": "654984",
      "tipoConta": "TRAN"
    }
  },
  "assinatura": {
    "expiracao": "2026-08-27",
    "descricao": "Mensalidades do curso XYZ",
    "idProprio": "6236574863254",
    "configuracao": {
      "automatico": {
        "valorFixo": "500.00",
        "valorMinimo": "450.00",
        "valorMaximo": "750.00",
        "intervalo": "SEMANAL",
        "dataInicio": "2025-06-06",
        "permiteRetentativa": false,
        "primeiroPagamento": {
          "data": "2024-06-08",
          "valor": "9.99",
          "infoPagador": "Parcela 1"
        }
      }
    }
  }
}

Responses

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

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

At this point, the flow proceeds as follows:
1. The URL is clicked by the end user, who is redirected to the paying institution.
2. The end user logs into their account and approves the consent.
3. The paying institution redirects back to Gerencianet, which then redirects back to the application via the redirectURI registered in the system.

Get parameters of an enrollment​

This endpoint is used to receive a request from the integrator to retrieve the parameters of an automatic payment.

GET /v1/pagamentos-automaticos/adesao
Requires authorization for the scope: gn.opb.automatic.consent.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-automaticos/adesao?inicio=2022-05-01&fim=2022-12-30

Responses

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

{
  "adesoes": [
    {
      "identificadorAdesao": "urn:efi:49315a93-d39c-4564-9edb-9a73678dbdb1",
      "status": "autorizado",
      "dataCriacao": "2022-06-09T11:55:03.000Z",
      "favorecido": {
        "contaBanco": {
          "nome": "Lucas Silva",
          "documento": "17558266300",
          "codigoBanco": "09089356",
          "agencia": "0001",
          "conta": "654984",
          "tipoConta": "TRAN"
        }
      },
      "assinatura": {
        "expiracao": "2026-08-27",
        "descricao": "Mensalidades do curso XYZ",
        "idProprio": "6236574863254",
        "configuracao": {
          "automatico": {
            "valorFixo": "500.00",
            "valorMinimo": "450.00",
            "valorMaximo": "750.00",
            "intervalo": "SEMANAL",
            "dataInicio": "2025-06-06",
            "permiteRetentativa": false,
            "primeiroPagamento": {
              "data": "2024-06-08",
              "valor": "9.99",
              "infoPagador": "Parcela 1"
            }
          }
        }
      }
    }
  ],
  "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"
}

Edit an enrollment​

This endpoint is used to receive a request from the integrator to update the parameters of an automatic payment.

Information

Currently, only the status of a enrollment can be changed.


PATCH /v1/pagamentos-automaticos/adesao
Requires authorization for the scope: gn.opb.automatic.consent.write


Request

{
  "identificador": "urn:efi:19ba4105-9ae2-4637-89f2-96506d3c8770",
  "nomeFavorecido": "Marco Antonio de Brito",
  "status": "revogado",
  "dataExpiracao": "2021-05-21",
  "valorMaximo": "500.00"
}

Responses

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

{
  "identificadorAdesao": "urn:efi:49315a93-d39c-4564-9edb-9a73678dbdb1",
  "status": "revogado",
  "motivo": "O usuário pagador revogou a recorrência da adesão",
  "favorecido": {
    "contaBanco": {
      "nome": "Lucas Silva",
      "documento": "17558266300",
      "codigoBanco": "09089356",
      "agencia": "0001",
      "conta": "654984",
      "tipoConta": "TRAN"
    }
  },
  "assinatura": {
    "expiracao": "2026-08-27",
    "descricao": "Mensalidades do curso XYZ",
    "idProprio": "6236574863254",
    "configuracao": {
      "automatico": {
        "valorFixo": "500.00",
        "valorMinimo": "450.00",
        "valorMaximo": "750.00",
        "intervalo": "SEMANAL",
        "dataInicio": "2025-06-06",
        "permiteRetentativa": false,
        "primeiroPagamento": {
          "data": "2024-06-08",
          "valor": "9.99",
          "infoPagador": "Parcela 1"
        }
      }
    }
  }
}

Request creation of an automatic payment​

This endpoint is used to receive a request from the integrator to submit a payment.

POST /v1/pagamentos-automaticos/pix
Requires authorization for the scope: gn.opb.automatic.payment.write


Request

{
  "identificadorAdesao": "urn:efi:19ba4105-9ae2-4637-89f2-96506d3c8770",
  "pagamento": {
    "valor": "9.99",
    "data": "2024-06-08",
    "codigoCidadeIBGE": "5300108",
    "infoPagador": "Parcela 2x20"
  }
}

Responses

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

{
  "identificadorAdesao": "urn:efi:ae71713f-875b-4af3-9d85-0bcb43288847",
  "endToEndId": "E00038166201907261559y6j5",
  "status": "pendente",
  "data": "2024-06-08"
}

Get automatic payments​

This endpoint is a search tool. It allows the user to look up a specific payment, payments with a specific status, or payments that meet certain criteria within a given time frame.

GET /v1/pagamentos-automaticos/pix
Requires authorization for the scope: gn.opb.automatic.payment.read


Responses

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

{
  "identificadorAdesao": "urn:efi:49315a93-d39c-4564-9edb-9a73678dbdb1",
  "idProprio": "6236574863254",
  "status": "autorizado",
  "descricao": "Parcelas da faculdade",
  "pagamentos": [
    {
      "endToEndId": "E00038166201907261559y6j6",
      "valor": "1.99",
      "status": "aceito",
      "dataCriacao": "2022-04-29T11:55:03.000Z",
      "infoPagador": "Mensalidade 1x18",
      "devolucoes": [
        {
          "identificadorDevolucao": "D09089356202211111429d82ecc2ecde",
          "valor": "1.99",
          "status": "aceito",
          "dataCriacao": "2022-04-29T11:59:03.000Z"
        }
      ]
    }
  ]
}

Request cancellation of an automatic payment​

This endpoint is used to receive a request from the integrator to cancel an automatic payment.

PATCH /v1/pagamentos-automaticos/pix
Requires authorization for the scope: gn.opb.automatic.payment.write


Request

{
  "identificadorAdesao": "urn:efi:19ba4105-9ae2-4637-89f2-96506d3c8770",
  "endToEndId": "E00038166201907261559y6j5"
}

Responses

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

{
  "identificadorAdesao": "urn:efi:ae71713f-875b-4af3-9d85-0bcb43288847",
  "idProprio": "6236574863254",
  "endToEndId": "E00038166201907261559y6j5",
  "valor": "9.99",
  "status": "cancelado",
  "motivo": "Cancelado pelo integrador",
  "dataCriacao": "2022-04-29T11:55:03.000Z"
}
Last updated on