Pix Automático

O conjunto de endpoints a seguir é responsável pela gestão de Pix Automático.

Listar as autorizações de Pix Automático com filtros opcionais

Endpoint para recuperar uma lista de autorizações de Pix Automático com filtros opcionais.

GET /v1/pix/authorizations

Requer autorização para o escopo: cobv.read

Requisição

O trecho de código abaixo ilustra o consumo do endpoint em uma requisição com o mínimo de parâmetros possível (o intervalo de datas inicio e fim) e o formato em que esses parâmetros devem ser repassados.

/v1/pix/authorizations?inicio=2020-10-22T16:01:35Z&fim=2020-11-30T20:10:00Z

Respostas

As respostas abaixo representam Sucesso(200) e Falhas/erros do consumo.

🟢 200

{
"responseTime": 0,
"correlationId": "string",
"page": 0,
"total": 0,
"contracts": [
  {
    "type": "payer",
    "recurrenceId": "CR0451581002680711EeMO6xwEPtT",
    "recurrenceRequestId": "SS9510845179514582zyIy9IZWjaW",
    "endUserAccount": "string",
    "frequencyType": "WEEK",
    "retryPolicy": "NONE",
    "status": "waiting",
    "startDate": "2025-12-22T22:11:30.914Z",
    "endDate": "2025-12-22T22:11:30.914Z",
    "value": 1,
    "minValue": 1,
    "maxValue": 1,
    "debtor": {
      "name": "string",
      "document": "string"
    },
    "codMunIbge": "string",
    "contractNumber": "string",
    "requestExpirationDate": "2025-12-22T22:11:30.914Z",
    "description": "string",
    "authorizationFlow": "AUT1",
    "confirmationDate": "2025-12-22T22:11:30.914Z",
    "cancellationDate": "2025-12-22T22:11:30.914Z",
    "createdAt": "2025-12-22T22:11:30.914Z",
    "counterParty": {
      "type": "LEGAL_PERSON",
      "document": "71094348622",
      "name": "string",
      "participant": "string",
      "branch": "string",
      "accountType": "string",
      "accountNumber": "string"
    },
    "canceledContract": {
      "identifier": "string",
      "reason": "ACCL",
      "canceledAt": "2025-12-22T22:11:30.914Z"
    }
  }
]
}

🔴 401

{
  "correlationId": "abcdef01-2345-6789-0123-456789012345",
  "error": {
      "title": "Unauthorized",
      "detail": "Token de acesso inválido ou expirado",
      "status": 401
  }
}

🔴 403

{
  "correlationId": "abcdef01-2345-6789-0123-456789012345",
  "error": {
      "title": "Forbidden",
      "detail": "Acesso negado",
      "status": 403
  }
}

🔴 500

{
  "correlationId": "abcdef01-2345-6789-0123-456789012345",
  "error": {
      "title": "InternalServerError",
      "detail": "Erro interno do servidor",
      "status": 500
  }
}

Consultar autorização de Pix Automático

Endpoint para consultar uma autorização específica de Pix Automático

GET /v1/pix/authorizations/:recurrenceId

Requer autorização para o escopo: cob.read

Respostas

As respostas abaixo representam Sucesso(200) e Falhas/erros do consumo.

🟢 200

{
  "responseTime": 0,
  "correlationId": "string",
  "contract": {
      "type": "payer",
      "recurrenceId": "CR44561789577280283wbYBAXIGPr",
      "recurrenceRequestId": "SS2540314113384654bvwfoOJMClM",
      "endUserAccount": "string",
      "frequencyType": "WEEK",
      "retryPolicy": "NONE",
      "status": "waiting",
      "startDate": "2025-12-22T22:21:37.276Z",
      "endDate": "2025-12-22T22:21:37.276Z",
      "value": 1,
      "minValue": 1,
      "maxValue": 1,
      "debtor": {
      "name": "string",
      "document": "string"
      },
      "codMunIbge": "string",
      "contractNumber": "string",
      "requestExpirationDate": "2025-12-22T22:21:37.276Z",
      "description": "string",
      "authorizationFlow": "AUT1",
      "confirmationDate": "2025-12-22T22:21:37.276Z",
      "cancellationDate": "2025-12-22T22:21:37.276Z",
      "createdAt": "2025-12-22T22:21:37.276Z",
      "counterParty": {
      "type": "LEGAL_PERSON",
      "document": "21751703955270",
      "name": "string",
      "participant": "string",
      "branch": "string",
      "accountType": "string",
      "accountNumber": "string"
      },
      "canceledContract": {
      "identifier": "string",
      "reason": "ACCL",
      "canceledAt": "2025-12-22T22:21:37.276Z"
      }
  }
}

</TabItem>
<TabItem value="400">

```json
// Identificação do contrato ausente
{
  "responseTime": 0,
  "correlationId": "abcdef01-2345-6789-0123-456789012345",
  "error": {
      "title": "Contract ID was not provided",
      "detail": "Parameter contract ID not provided"
  }
}

OU

//Conta de usuário final
{
  "responseTime": 0,
  "correlationId": "abcdef01-2345-6789-0123-456789012345",
  "error": {
      "title": "Account number was not provided",
      "detail": "Parameter account number not provided"
  }
}

🔴 400

{
  "correlationId": "abcdef01-2345-6789-0123-456789012345",
  "error": {
      "title": "Unauthorized",
      "detail": "Token de acesso inválido ou expirado",
      "status": 401
  }
}

🔴 401

{
  "correlationId": "abcdef01-2345-6789-0123-456789012345",
  "error": {
      "title": "Forbidden",
      "detail": "Acesso negado",
      "status": 403
  }
}

🔴 403

{
  "error": {
      "title": "NotFound",
      "detail": "Recurso não encontrado",
      "status": 404
  }
}

🔴 404

{
  "correlationId": "abcdef01-2345-6789-0123-456789012345",
  "error": {
      "title": "InternalServerError",
      "detail": "Erro interno do servidor",
      "status": 500
  }
}

Alterar o valor máximo de uma autorização de Pix Automático

Este endpoint é utilizado para receber uma requisição do integrador para alterar o valor máximo de uma autorização de Pix Automático.

PATCH /v1/pix/authorizations/:recurrenceId

Requer autorização para o escopo: cobr.write

Requisição

Exemplo

{
  "maxValue": 0
}

Respostas

As respostas abaixo representam Sucesso(200) e Falhas/erros do consumo.

🟢 204

{
 "Valor máximo alterado com sucesso"
}

🔴 400

// valor máximo ausente
{
  "responseTime": 0,
  "correlationId": "abcdef01-2345-6789-0123-456789012345",
  "error": {
    "title": "The new max value must be provided.",
    "detail": "New max value was not provided"
  }
}

OU

// conta de usuário final ausente
{
  "responseTime": 0,
  "correlationId": "abcdef01-2345-6789-0123-456789012345",
  "error": {
    "title": "The account number must be provided.",
    "detail": "Account code was not provided"
  }
}

OU

//contrato não ativo
{
  "responseTime": 0,
  "correlationId": "abcdef01-2345-6789-0123-456789012345",
  "error": {
    "title": "The given contract is not active, cannot proceed with operation.",
    "detail": "Contract status is different from active"
  }
}

OU

// contrato com valor fixo
{
  "responseTime": 0,
  "correlationId": "abcdef01-2345-6789-0123-456789012345",
  "error": {
    "title": "The given contract has a fixed value.",
    "detail": "Fixed value contracts does not allow maxValue configuration"
  }
}

OU

// valor máximo excede valor mínimo
{
  "responseTime": 0,
  "correlationId": "abcdef01-2345-6789-0123-456789012345",
  "error": {
    "title": "The new max value must be bigger than the minimum value.",
    "detail": "Payer has informed a max value that is lower than receiver min value"
  }
}

🔴 401

{
  "correlationId": "abcdef01-2345-6789-0123-456789012345",
  "error": {
    "title": "Unauthorized",
    "detail": "Token de acesso inválido ou expirado",
    "status": 401
  }
}

🔴 403

{
  "correlationId": "abcdef01-2345-6789-0123-456789012345",
  "error": {
    "title": "Forbidden",
    "detail": "Acesso negado",
    "status": 403
  }
}

🔴 404

{
  "responseTime": 0,
  "correlationId": "abcdef01-2345-6789-0123-456789012345",
  "error": {
    "title": "The contract id must be provided.",
    "detail": "Contract id was not provided"
  }
}

🔴 500

{
  "correlationId": "abcdef01-2345-6789-0123-456789012345",
  "error": {
    "title": "InternalServerError",
    "detail": "Erro interno do servidor",
    "status": 500
  }
}

Enviar resposta de autorização

Endpoint para enviar a resposta do usuário para uma solicitação de autorização de Pix Automático

POST /v1/pix/authorizations/:recurrenceId

Requer autorização para o escopo: cob.write

Requisição

Exemplo

{
"endUserAccount": "string",
"endUserAccountBranch": "string",
"recurrenceRequestId": "string",
"userResponse": "confirmed",
"maxValue": 0,
"authorizationFlow": "AUT1",
"endToEndId": "string",
"contract": {
  "recurrence": {
    "frequencyType": "WEEK",
    "retryPolicy": "NONE",
    "startDate": "2025-12-23T13:19:16.895Z",
    "endDate": "2025-12-23T13:19:16.895Z",
    "codMunIbge": "string",
    "value": 0,
    "minValue": 0,
    "maxValue": 0,
    "contractNumber": "string",
    "description": "string",
    "processingDetails": {
      "createdAt": "2025-12-23T13:19:16.895Z",
      "requestedAt": "2025-12-23T13:19:16.895Z",
      "expiresAt": "2025-12-23T13:19:16.895Z"
    }
  },
  "receiver": {
    "name": "string",
    "document": "string",
    "participant": "string"
  },
  "payer": {
    "document": "string",
    "accountNumber": "string",
    "accountType": "CACC",
    "branch": "string",
    "participant": "string"
  },
  "debtor": {
    "name": "string",
    "document": "string"
  }
}
}

Respostas

As respostas abaixo representam Sucesso(201) e Falhas/erros do consumo.

🟢 200

{
"responseTime": 0,
"correlationId": "string",
"contract": {
  "type": "payer",
  "recurrenceId": "RR6395704046975780MvIDkJKn1nC",
  "recurrenceRequestId": "SS6840702423316991S5fH0nD6JP5",
  "endUserAccount": "string",
  "frequencyType": "WEEK",
  "retryPolicy": "NONE",
  "status": "waiting",
  "startDate": "2025-12-23T13:26:36.396Z",
  "endDate": "2025-12-23T13:26:36.396Z",
  "value": 1,
  "minValue": 1,
  "maxValue": 1,
  "debtor": {
    "name": "string",
    "document": "string"
  },
  "codMunIbge": "string",
  "contractNumber": "string",
  "requestExpirationDate": "2025-12-23T13:26:36.396Z",
  "description": "string",
  "authorizationFlow": "AUT1",
  "confirmationDate": "2025-12-23T13:26:36.396Z",
  "cancellationDate": "2025-12-23T13:26:36.396Z",
  "createdAt": "2025-12-23T13:26:36.396Z",
  "counterParty": {
    "type": "LEGAL_PERSON",
    "document": "07039985791",
    "name": "string",
    "participant": "string",
    "branch": "string",
    "accountType": "string",
    "accountNumber": "string"
  },
  "canceledContract": {
    "identifier": "string",
    "reason": "ACCL",
    "canceledAt": "2025-12-23T13:26:36.396Z"
  }
}
}

🔴 400

{
"responseTime": 0,
"correlationId": "abcdef01-2345-6789-0123-456789012345",
"error": {
  "title": "The recurrence confirmation request was already confirmed",
  "detail": "The recurrence confirmation request was already confirmed"
}
}

🔴 401

{
"correlationId": "abcdef01-2345-6789-0123-456789012345",
"error": {
  "title": "Unauthorized",
  "detail": "Token de acesso inválido ou expirado",
  "status": 401
}
}

🔴 403

{
"correlationId": "abcdef01-2345-6789-0123-456789012345",
"error": {
  "title": "Forbidden",
  "detail": "Acesso negado",
  "status": 403
}
}

🔴 404

{
"responseTime": 0,
"correlationId": "abcdef01-2345-6789-0123-456789012345",
"error": {
  "title": "Contract not found",
  "detail": "Contract not found"
}
}

🔴 422

{
"responseTime": 0,
"correlationId": "abcdef01-2345-6789-0123-456789012345",
"error": {
  "title": "Recurrence was authorized after mandate expiration",
  "detail": "Recurrence was authorized after mandate expiration"
}
}

🔴 500

{
"correlationId": "abcdef01-2345-6789-0123-456789012345",
"error": {
  "title": "InternalServerError",
  "detail": "Erro interno do servidor",
  "status": 500
}
}

Cancelar autorização de Pix Automático

Você pode cancelar uma autorização de Pix Automático existente a qualquer momento. Para isso, basta informar o recurrenceId da recorrência que deseja cancelar.

DELETE/v1/pix/authorizations/:recurrenceId/cancel

Requer ativação da API de Emissão de cobranças em sua aplicação

Requisição

Dados de entrada

{
"reason": "string",
"identifier": "string",
"cancellationDate": "2025-12-23T15:19:54.963Z"
}

Respostas

As respostas abaixo representam Sucesso(201) do consumo.

🟢 200

{
"responseTime": 0,
"correlationId": "string",
"contract": {
  "type": "payer",
  "recurrenceId": "RR2244120002448067UpW8EIpgpKr",
  "recurrenceRequestId": "SS0104272712951961dW1UgTpidaE",
  "endUserAccount": "string",
  "frequencyType": "WEEK",
  "retryPolicy": "NONE",
  "status": "waiting",
  "startDate": "2025-12-23T15:19:54.991Z",
  "endDate": "2025-12-23T15:19:54.991Z",
  "value": 1,
  "minValue": 1,
  "maxValue": 1,
  "debtor": {
    "name": "string",
    "document": "string"
  },
  "codMunIbge": "string",
  "contractNumber": "string",
  "requestExpirationDate": "2025-12-23T15:19:54.991Z",
  "description": "string",
  "authorizationFlow": "AUT1",
  "confirmationDate": "2025-12-23T15:19:54.991Z",
  "cancellationDate": "2025-12-23T15:19:54.991Z",
  "createdAt": "2025-12-23T15:19:54.991Z",
  "counterParty": {
    "type": "LEGAL_PERSON",
    "document": "03994959288140",
    "name": "string",
    "participant": "string",
    "branch": "string",
    "accountType": "string",
    "accountNumber": "string"
  },
  "canceledContract": {
    "identifier": "string",
    "reason": "ACCL",
    "canceledAt": "2025-12-23T15:19:54.992Z"
  }
}
}

🔴 400

{
  "correlationId": "abcdef01-2345-6789-0123-456789012345",
  "error": {
    "detail": "Could not parse request body",
    "status": 400,
    "title": "Bad Request",
    "type": "https://dict.pi.rsfn.net.br/api/v2/error/BadRequest"
  },
  "responseTime": 0
}

🔴 401

{
  "correlationId": "abcdef01-2345-6789-0123-456789012345",
  "error": {
    "title": "Unauthorized",
    "detail": "Token de acesso inválido ou expirado",
    "status": 401
  }
}

🔴 403

{
  "correlationId": "abcdef01-2345-6789-0123-456789012345",
  "error": {
    "title": "Forbidden",
    "detail": "Acesso negado",
    "status": 403
  }
}

🔴 404

{
  "error": {
    "title": "NotFound",
    "detail": "Recurso não encontrado",
    "status": 404
  }
}

🔴 409

{
  "responseTime": 0,
  "correlationId": "abcdef01-2345-6789-0123-456789012345",
  "error": {
    "title": "Contract already cancelled",
    "detail": "Contract already cancelled"
  }
}

🔴 500

{
  "correlationId": "abcdef01-2345-6789-0123-456789012345",
  "error": {
    "title": "InternalServerError",
    "detail": "Erro interno do servidor",
    "status": 500
  }
}

Listar execuções de autorização

Endpoint para recuperar uma lista de execuções de autorizações de Pix Automático.

GET /v1/pix/authorizations/:recurrenceId/executions

Requer autorização para o escopo: cobv.read

Requisição

O trecho de código abaixo ilustra o consumo do endpoint em uma requisição com o mínimo de parâmetros possível (o intervalo de datas inicio e fim) e o formato em que esses parâmetros devem ser repassados.

/v1/pix/authorizations?inicio=2020-10-22T16:01:35Z&fim=2020-11-30T20:10:00Z

Respostas

As respostas abaixo representam Sucesso(200) e Falhas/erros do consumo.

🟢 200

{
"responseTime": 0,
"correlationId": "string",
"total": 0,
"page": 0,
"limit": 0,
"executions": [
  {
    "payment": {
      "status": "waiting",
      "txid": "string",
      "endToEndId": "ENJ79HDCT993802390552dneuswpGEIs",
      "requestId": "string",
      "type": "credit",
      "value": 1,
      "key": "string",
      "description": "string",
      "effectiveDatetime": "2025-12-23T15:50:30.881Z",
      "errorCode": "string",
      "errorDescription": "string"
    },
    "autoSchedule": {
      "type": "receiver",
      "endUserAccount": "string",
      "status": "waiting",
      "dueDate": "2025-12-23T15:50:30.881Z",
      "origin": {
        "document": "99210021955627",
        "name": "string",
        "accountNumber": "string",
        "branch": "string"
      },
      "destination": {
        "document": "47186483341",
        "name": "string",
        "accountNumber": "string",
        "branch": "string"
      }
    }
  }
]
}

🔴 400

{
"responseTime": 0,
"correlationId": "abcdef01-2345-6789-0123-456789012345",
"error": {
  "detail": "Request body is invalid",
  "status": 400,
  "title": "Bad Request"
}
}

🔴 401

{
"correlationId": "abcdef01-2345-6789-0123-456789012345",
"error": {
  "title": "Unauthorized",
  "detail": "Token de acesso inválido ou expirado",
  "status": 401
}
}

🔴 403

{
"correlationId": "abcdef01-2345-6789-0123-456789012345",
"error": {
  "title": "Forbidden",
  "detail": "Acesso negado",
  "status": 403
}
}

🔴 404

{
"responseTime": 0,
"correlationId": "abcdef01-2345-6789-0123-456789012345",
"error": {
  "detail": "Contract not found for recurrenceId RCXXXX",
  "status": 404,
  "title": "Contract not found"
}
}

🔴 500

{
"correlationId": "abcdef01-2345-6789-0123-456789012345",
"error": {
  "title": "InternalServerError",
  "detail": "Erro interno do servidor",
  "status": 500
}
}