Immediate charges

The following set of endpoints are responsible for managing immediate charges.

Create immediate charge

Endpoint to create an immediate charge, in this case, the txid must be defined by the PSP.

POST /v1/cob

Requires authorization for the scope: cob.write

Request

Example

{
  "calendario": {
    "expiracao": 3600
  },
  "devedor": {
    "cnpj": "12345678000195",
    "nome": "Empresa de Serviços SA"
  },
  "valor": {
    "original": "37.00"
  },
  "chave": "7d9f0335-8dcc-4054-9bf9-0dbd61d36906",
  "solicitacaoPagador": "Serviço realizado.",
  "infoAdicionais": [
    {
      "nome": "Campo 1",
      "valor": "Informação Adicional1 do PSP-Recebedor"
    },
    {
      "nome": "Campo 2",
      "valor": "Informação Adicional2 do PSP-Recebedor"
    }
  ]
}

Responses

The responses below represent Success(201) and consumption Failures/errors.

🟢 201

{
  "responseTime": 123,
  "correlationId": "abcdef01-2345-6789-0123-456789012345",
  "calendario": {
    "criacao": "2020-09-09T20:15:00.358Z",
    "expiracao": 3600
  },
  "txid": "7978c0c97ea847e78e8849634473c1f1",
  "revisao": 0,
  "loc": {
    "id": 789,
    "location": "qrcodes-pix.sejaefi.com.br/v2/9d36b84fc70b478fb95c12729b90ca25",
    "tipoCob": "cob"
  },
  "location": "qrcodes-pix.sejaefi.com.br/v2/9d36b84fc70b478fb95c12729b90ca25",
  "status": "ATIVA",
  "devedor": {
    "cnpj": "12345678000195",
    "nome": "Empresa de Serviços SA"
  },
  "valor": {
    "original": "567.89"
  },
  "chave": "a1f4102e-a446-4a57-bcce-6fa48899c1d1",
  "solicitacaoPagador": "Informar cartão fidelidade"
}

🔴 400

{
  "responseTime": 123,
  "correlationId": "abcdef01-2345-6789-0123-456789012345",
  "error": {
    "detail": "O documento desta conta tem bloqueios que impedem a emissão",
    "title": "documento_bloqueado",
    "status": 400
  }
}

🔴 409

{
  "responseTime": 123,
  "correlationId": "abcdef01-2345-6789-0123-456789012345",
  "error": {
    "title": "txid_duplicado",
    "detail": "Campo txid informado já foi utilizado em outra cobrança",
    "status": 409
  }
}

🔴 500

{
  "responseTime": 123,
  "correlationId": "abcdef01-2345-6789-0123-456789012345",
  "error": {
    "title": "erro_aplicacao",
    "detail": "Ocorreu um erro ao validar a chave",
    "status": 500
  }
}

Create immediate charge with txid

Endpoint to create an immediate charge (cob) with a specific TxId provided by the PSP.

Immediate Payment (Cob) Characteristics:

• Immediate payment: Must be paid at the time of request
• No due date: Does not have a specific due date
• Automatically expires: Based on the time set in expiracao (default 24h)
• Dynamic QR Code: Generates a unique QR Code for payment

Differences between Cob and Cobv:

Characteristic	Cob (Immediate)	Cobv (With Due Date)
Due date	❌ None	✅ Required
Payment	Immediate	Can be future
Interest/Fine	❌ Not allowed	✅ Configurable
Discount	❌ Not allowed	✅ Configurable
Debtor address	❌ Basic optional	✅ Fully required

Idempotency:

The operation is idempotent when using the same txid. Repeated requests with the same txid will return the same data as the first processed request.

Validations:

• Chave Pix: Must be a valid and active key
• Valor: Must be positive and in the correct format (e.g., "100.50")
• Debtor CPF/CNPJ: If provided, must be valid and not blocked
• Expiração: Between 1 second and 365 days (default: 86400s = 24h)

PUT /v1/cob/:txid

Requires authorization for the scope: cob.write

Request

Simple payment

{
  "calendario": {
    "expiracao": 3600
  },
  "valor": {
    "original": "50.00"
  },
  "chave": "+5561988887777"
}

Complete payment with debtor

{
  "calendario": {
    "expiracao": 7200
  },
  "devedor": {
    "nome": "João Silva",
    "cpf": "12345678901"
  },
  "valor": {
    "original": "150.75"
  },
  "chave": "[email protected]",
  "solicitacaoPagador": "Pagamento referente ao serviço prestado",
  "infoAdicionais": [
    {
      "nome": "Pedido",
      "valor": "#456"
    },
    {
      "nome": "Categoria",
      "valor": "Serviços"
    }
  ]
}

Responses

The responses below represent Success(201) and consumption Failures/errors.

🟢 200

{
  "calendario": {
    "criacao": "2023-10-15T14:30:00Z",
    "expiracao": 3600
  },
  "txid": "fb2761260e054c7a94fb7b7b",
  "revisao": 0,
  "loc": {
    "id": 789,
    "location": "pix.example.com/qr/v2/cobv/9d36b84fc70b478fb95c12729b90ca25",
    "tipoCob": "cob"
  },
  "status": "ATIVA",
  "valor": {
    "original": "50.00"
  },
  "chave": "+5561988887777",
  "pixCopiaECola": "00020101021226580014BR.GOV.BCB.PIX0136123e4567-e89b-12d3-a456-426655440000520400005303986540510.005802BR5913Fulano de Tal6008BRASILIA62070503***630445CC"
}

🔴 400

{
  "correlationId": "a9f13566e19f5ca51329479a5bae60c5",
  "error": {
    "status": 400,
    "title": "Bad Request",
    "detail": "Chave Pix informada é inválida"
  }
}

🔴 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
  }
}

🔴 503

{
  "correlationId": "abcdef01-2345-6789-0123-456789012345",
  "error": {
    "title": "ServiceUnavailable",
    "detail": "Serviço temporariamente indisponível",
    "status": 503
  }
}

Get immediate charge

Endpoint to retrieve detailed information of a specific immediate charge through its txid.

Use Cases:

• Check status: Before attempting to update or cancel
• Get QR Code: To provide to the payer
• Audit: Track modification history

GET /v1/cob/:txid

Requires authorization for the scope: cob.read

Request

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

Responses

The responses below represent Success(200) and Failures/errors from the consumption.

🟢 200

// Cobrança ativa
{
  "calendario": {
    "criacao": "2023-10-15T14:30:00Z",
    "expiracao": 3600
  },
  "txid": "fb2761260e054c7a94fb7b7b",
  "revisao": 0,
  "loc": {
    "id": 789,
    "location": "pix.example.com/qr/v2/cob/fb2761260e054c7a94fb7b7b",
    "tipoCob": "cob",
    "criacao": "2023-10-15T14:30:00Z"
  },
  "status": "ATIVA",
  "devedor": {
    "nome": "João Silva",
    "cpf": "12345678901"
  },
  "valor": {
    "original": "50.00"
  },
  "chave": "+5561988887777",
  "solicitacaoPagador": "Pagamento referente ao serviço prestado",
  "infoAdicionais": [
    {
      "nome": "Pedido",
      "valor": "#123"
    }
  ],
  "pixCopiaECola": "00020101021226580014BR.GOV.BCB.PIX0136123e4567-e89b-12d3-a456-426655440000520400005303986540510.005802BR5913Fulano de Tal6008BRASILIA62070503***630445CC"
}

🟢 200

// Charge completed
{
  "calendario": {
    "criacao": "2023-10-15T14:30:00Z",
    "expiracao": 3600
  },
  "txid": "fb2761260e054c7a94fb7b7b",
  "revisao": 0,
  "loc": {
    "id": 789,
    "location": "pix.example.com/qr/v2/cob/fb2761260e054c7a94fb7b7b",
    "tipoCob": "cob",
    "criacao": "2023-10-15T14:30:00Z"
  },
  "status": "CONCLUIDA",
  "valor": {
    "original": "50.00"
  },
  "chave": "+5561988887777",
  "pixCopiaECola": "00020101021226580014BR.GOV.BCB.PIX0136123e4567-e89b-12d3-a456-426655440000520400005303986540510.005802BR5913Fulano de Tal6008BRASILIA62070503***630445CC"
}

🔴 400

{
  "correlationId": "a9f13566e19f5ca51329479a5bae60c5",
  "error": {
    "status": 400,
    "title": "Bad Request",
    "detail": "TxId deve ter entre 26 e 35 caracteres alfanuméricos"
  }
}

🔴 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

{
  "correlationId": "a9f13566e19f5ca51329479a5bae60c5",
  "error": {
    "status": 404,
    "title": "Not Found",
    "detail": "Cobrança com o txid informado não foi encontrada"
  }
}

🔴 500

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

🔴 503

{
  "correlationId": "abcdef01-2345-6789-0123-456789012345",
  "error": {
    "title": "ServiceUnavailable",
    "detail": "Serviço temporariamente indisponível",
    "status": 503
  }
}

Update immediate charge

Endpoint to update information of an existing immediate charge (cob).

Restrictions:

• Status: Only payments with ACTIVE status can be updated
• Key: Cannot be changed after creation
• Calendar: Cannot be changed after creation
• Location: Cannot be changed after creation

Behaviors:

• Revision: Automatically increments with each update
• QR Code: Regenerated with the new information
• Idempotency: Identical updates do not change the revision

Validations:

• Amount: Must be positive and in the correct format
• CPF/CNPJ: If changed, must be valid and not blocked
• ACTIVE status: Payment must be active to allow changes

Important!

After updating, a new QR Code will be generated. Previous QR Codes may not work.

PATCH /v1/cob/:txid

Requires authorization for the scope: cob.write

Request

Update only the amount

{
  "valor": {
    "original": "75.00"
  }
}

Update payer information

{
  "devedor": {
    "nome": "João Silva Santos",
    "cpf": "98765432100"
  },
  "solicitacaoPagador": "Dados do devedor atualizados"
}

Complete update

{
  "devedor": {
    "nome": "Maria Silva",
    "cnpj": "12345678000195"
  },
  "valor": {
    "original": "150.00"
  },
  "solicitacaoPagador": "Pagamento atualizado com novos dados",
  "infoAdicionais": [
    {
      "nome": "Desconto",
      "valor": "5%"
    },
    {
      "nome": "Categoria",
      "valor": "Premium"
    }
  ]
}

Responses

The responses below represent Success(200) and Failures/errors from the consumption.

🟢 200

{
  "calendario": {
    "criacao": "2023-10-15T14:30:00Z",
    "expiracao": 3600
  },
  "txid": "fb2761260e054c7a94fb7b7b",
  "revisao": 1,
  "loc": {
    "id": 789,
    "location": "pix.example.com/qr/v2/cob/fb2761260e054c7a94fb7b7b",
    "tipoCob": "cob"
  },
  "status": "ATIVA",
  "devedor": {
    "nome": "João Silva Santos",
    "cpf": "98765432100"
  },
  "valor": {
    "original": "75.00"
  },
  "chave": "+5561988887777",
  "solicitacaoPagador": "Pagamento atualizado - referente ao pedido #123",
  "pixCopiaECola": "00020101021226580014BR.GOV.BCB.PIX0136123e4567-e89b-12d3-a456-426655440000520400005303986540510.005802BR5913Fulano de Tal6008BRASILIA62070503***630445CC"
}

🔴 400

{
  "correlationId": "a9f13566e19f5ca51329479a5bae60c5",
  "error": {
    "status": 400,
    "title": "Bad Request",
    "detail": "Cobrança não está no status ATIVA, não pode ser atualizada"
  }
}

🔴 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

{
  "correlationId": "a9f13566e19f5ca51329479a5bae60c5",
  "error": {
    "status": 404,
    "title": "Not Found",
    "detail": "Cobrança com o txid informado não foi encontrada"
  }
}

🔴 500

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

🔴 503

{
  "correlationId": "abcdef01-2345-6789-0123-456789012345",
  "error": {
    "title": "ServiceUnavailable",
    "detail": "Serviço temporariamente indisponível",
    "status": 503
  }
}

List immediate charges

Endpoint to retrieve a paginated list of immediate charges (cob) created by the PSP.

This endpoint includes filters to narrow down search results, such as CPF/CNPJ and status. Among all available filters, inicio and fim are mandatory and represent the date range within which the queried payments must fall.

GET /v1/cob

Requires authorization for the scope: cob.read

Request

The code snippet below illustrates consuming the endpoint with the minimum required parameters (the date range inicio and fim) and the format in which these parameters must be passed.

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

Responses

The responses below represent Success(200) from the consumption.

🟢 200

{
  "parametros": {
    "inicio": "2023-10-01T00:00:00Z",
    "fim": "2023-10-31T23:59:59Z",
    "paginacao": {
      "paginaAtual": 0,
      "itensPorPagina": 100,
      "quantidadeDePaginas": 1,
      "quantidadeTotalDeItens": 2
    }
  },
  "cobs": [
    {
      "calendario": {
        "criacao": "2023-10-15T14:30:00Z",
        "expiracao": 3600
      },
      "txid": "fb2761260e054c7a94fb7b7b",
      "revisao": 0,
      "loc": {
        "id": 789,
        "location": "pix.example.com/qr/v2/cob/fb2761260e054c7a94fb7b7b",
        "tipoCob": "cob"
      },
      "status": "ATIVA",
      "devedor": {
        "nome": "João Silva",
        "cpf": "12345678901"
      },
      "valor": {
        "original": "50.00"
      },
      "chave": "+5561988887777",
      "solicitacaoPagador": "Pagamento referente ao serviço prestado",
      "infoAdicionais": [
        {
          "nome": "Pedido",
          "valor": "#123"
        }
      ]
    },
    {
      "calendario": {
        "criacao": "2023-10-16T09:15:00Z",
        "expiracao": 7200
      },
      "txid": "ac3849f6b2d54e8a95fb1b2c",
      "revisao": 0,
      "loc": {
        "id": 790,
        "location": "pix.example.com/qr/v2/cob/ac3849f6b2d54e8a95fb1b2c",
        "tipoCob": "cob"
      },
      "status": "CONCLUIDA",
      "valor": {
        "original": "100.00"
      },
      "chave": "[email protected]"
    }
  ]
}

🔴 400

{
  "correlationId": "a9f13566e19f5ca51329479a5bae60c5",
  "error": {
    "status": 400,
    "title": "Bad Request",
    "detail": "Data de início deve ser anterior à data de fim"
  }
}

🔴 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
  }
}

🔴 503

{
  "correlationId": "abcdef01-2345-6789-0123-456789012345",
  "error": {
    "title": "ServiceUnavailable",
    "detail": "Serviço temporariamente indisponível",
    "status": 503
  }
}