Consultar cobrança imediata.

GET

/cob/{txid}

Cob

Endpoint para consultar uma cobrança através de um determinado txid.

Response Example

200 - Exemplo de cobrança imediata 1

{
    "calendario": {
        "criacao": "2020-09-09T20:15:00.358Z",
        "expiracao": 3600
    },
    "txid": "7978c0c97ea847e78e8849634473c1f1",
    "revisao": 0,
    "loc": {
        "id": 789,
        "location": "pix.example.com/qr/9d36b84fc70b478fb95c12729b90ca25",
        "tipoCob": "cob"
    },
    "location": "pix.example.com/qr/9d36b84fc70b478fb95c12729b90ca25",
    "status": "ATIVA",
    "devedor": {
        "cnpj": "12345678000195",
        "nome": "Empresa de Serviços SA"
    },
    "valor": {
        "original": "37.00",
        "modalidadeAlteracao": 1
    },
    "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"
        }
    ]
}

Requisição

Parâmetros Path

txid

string

requerido

Parâmetros Query

object {0}

Respostas

🟢200OK

application/json

Dados da cobrança imediata.

Body

Dados criados ou alterados da cobrança imediata via API Pix

status

enum<string>

Status do registro da cobrança.

requerido

Estado do registro da cobrança. Não se confunde com o estado da cobrança em si, ou seja, não guarda relação com o fato de a cobrança encontrar-se vencida ou expirada, por exemplo.

Os status são assim definidos:

ATIVA: indica que o registro se refere a uma cobrança que foi gerada mas ainda não foi paga nem removida;

CONCLUIDA: indica que o registro se refere a uma cobrança que já foi paga e, por conseguinte, não pode acolher outro pagamento;

REMOVIDA_PELO_USUARIO_RECEBEDOR: indica que o usuário recebedor solicitou a remoção do registro da cobrança; e

REMOVIDA_PELO_PSP: indica que o PSP Recebedor solicitou a remoção do registro da cobrança.

Valores permitidos:

ATIVACONCLUIDAREMOVIDA_PELO_USUARIO_RECEBEDORREMOVIDA_PELO_PSP

pix

array[object (Pix) {8}]

Pix recebidos

opcional

endToEndId

string

EndToEndId

requerido

The "endToEndId" field refers to a unique identifier that can be used to track and associate a specific transaction throughout the lifecycle of the operation. The term "end-to-end" pertains to the ability to trace the transaction from beginning to end, ensuring data integrity along the way.

txid

string

opcional

The "txId" field is a unique identifier generated by the Pix system to uniquely identify and monitor transactions.

Padrão de combinação:

(?=[a-zA-Z0-9]{1,35})(?=[a-zA-Z0-9]{26,35})

valor

string

Valor do Pix.

requerido

Valor do Pix.

Padrão de combinação:

\d{1,10}\.\d{2}

componentesValor

Informações sobre o valor do Pix

opcional

O objetivo dessa estrutura é explicar os elementos de composição do valor do Pix, incluindo informações sobre as multas, juros, descontos e abatimentos quando o Pix for relativo a cobranças com vencimento.

Regras da estrutura:

O valor do Pix é igual a:

(original.valor + saque.valor + troco.valor) + multa.valor + juros.valor – abatimento.valor – desconto.valor
considerando-se apenas os campos que estiverem presentes para cada tipo de cobrança pago.

As estruturas saque e troco só serão retornadas quando o Pix for relativo a um Pix Saque ou Pix Troco, respectivamente, e
as demais estruturas (juros, multa, abatimento e desconto) só serão pertinentes aos Pix de pagamentos das cobranças com vencimento.

Não pode haver simultaneamente uma subsestrutura do tipo saque e outra do tipo troco;

Não há restrição na ordem das subestruturas.

Para o caso de um Pix Saque pode-se retornar original com valor=0.00 (zero) uma vez que a soma será respeitada, ou pode-se omitir a
subestrutura original. No caso de um Pix Troco ou de um pagamento de cobrança com vencimento a subsestrutura original vai sempre estar
presente.

Exemplos válidos:

Exemplo de preenchimentos válidos.

Pix para pagamento de cobrança imediata (sem saque ou troco).

...
"componentesValor": {
  "original": {
    "valor": "100.00"
  } 
}
...

Pix Saque.

...
"componentesValor": {
  "saque": {
    "valor": "100.00",
    "modalidadeAgente": "AGPSS",
    "prestadorDeServicoDeSaque": "12345678"
  } 
}
...

Pix para pagamento de cobrança imediata com saque (pode vir original.valor=0.00).

...
"componentesValor": {
  "original": {
    "valor": "0.00"
  },
  "saque": {
    "valor": "100.00",
    "modalidadeAgente": "AGPSS",
    "prestadorDeServicoDeSaque": "12345678"
  } 
}
...

Pix Troco.

...
"componentesValor": {
  "original": {
    "valor": "80.00"
  },
  "troco": {
    "valor": "20.00",
    "modalidadeAgente": "AGTEC",
    "prestadorDeServicoDeSaque": "12345678"
  } 
}
...

Pix para pagamento de cobrança imediata com troco (ordem não importa).

...
"componentesValor": {
  "troco": {
    "valor": "20.00",
    "modalidadeAgente": "AGTEC",
    "prestadorDeServicoDeSaque": "12345678"
  },
  "original": {
    "valor": "80.00"
  }
}
...

Pix para pagamento de cobrança com vencimento de R $100, 00 co n s i d er an d o - se u ma t r a so d e 2 d ia s a u mam u lt a d e 3$ 105,00.

...
"componentesValor": {
  "original": {
    "valor": "100.00"
  },
  "multa": {
    "valor": "3.00"
  },
  "juros": {
    "valor": "2.00"
  }
}
...

Exemplos inválidos:

Exemplos, não exaustivos, de preenchimentos inválidos.

original.valor maior que 0.00 (zero) e saque juntos

...
"componentesValor": {
  "original": {
    "valor": "80.00"
  },
  "saque": {
    "valor": "20.00",
    "modalidadeAgente": "AGPSS",
    "prestadorDeServicoDeSaque": "12345678"
  } 
}
...

dois elementos de saque

...
"componentesValor": [
  "saque": {
    "valor": "20.00",
    "modalidadeAgente": "AGPSS",
    "prestadorDeServicoDeSaque": "12345678"
  },
  "saque": {
    "valor": "10.00",
    "modalidadeAgente": "AGPSS",
    "prestadorDeServicoDeSaque": "12345678"
  } 
]
...

saque e troco simultaneamente

...
"componentesValor": {
  "original": {
    "valor": "60.00"
  },
  "saque": {
    "valor": "20.00",
    "modalidadeAgente": "AGPSS",
    "prestadorDeServicoDeSaque": "12345678"
  },
  "troco": {
    "valor": "20.00",
    "modalidadeAgente": "AGTEC",
    "prestadorDeServicoDeSaque": "12345678"
  } 
}
...

chave

string

Chave DICT do recebedor

opcional

Formato do campo chave

Campo chave do recebedor conforme atribuído na respectiva PACS008.

Os tipos de chave podem ser: telefone, e-mail, cpf/cnpj ou EVP.

O formato das chaves pode ser encontrado na seção "Formatação das chaves do DICT no BR Code" do Manual de Padrões para iniciação do Pix.

<= 77 Caracteres

horario

string <date-time>

Horário

requerido

Horário em que o Pix foi processado no PSP.

infoPagador

string

Informação livre do pagador

opcional

<= 140 Caracteres

devolucoes

array[object (Devolução) {8}]

Devoluções

opcional

calendario

object

Calendário

opcional

Os campos aninhados sob o identificador calendário organizam informações a respeito de controle de tempo da cobrança.

expiracao

integer <int32>

Tempo de vida da cobrança, especificado em segundos.

requerido

Tempo de vida da cobrança, especificado em segundos a partir da data de criação (Calendario.criacao)

Padrão:

86400

Exemplo:

3600

criacao

string <date-time>

Data de Criação

requerido

Timestamp que indica o momento em que foi criada a cobrança. Respeita o formato definido na RFC 3339.

devedor

opcional

Os campos aninhados sob o objeto devedor são opcionais e identificam o devedor, ou seja, a pessoa ou a instituição a quem a cobrança está endereçada. Não identifica, necessariamente, quem irá efetivamente realizar o pagamento. Um CPF pode ser o devedor de uma cobrança, mas pode acontecer de outro CPF realizar, efetivamente, o pagamento do documento. Não é permitido que o campo devedor.cpf e campo devedor.cnpj estejam preenchidos ao mesmo tempo. Se o campo devedor.cnpj está preenchido, então o campo devedor.cpf não pode estar preenchido, e vice-versa. Se o campo devedor.nome está preenchido, então deve existir ou um devedor.cpf ou um campo devedor.cnpj preenchido.

One of

Pessoa Física

Pessoa Jurídica

cpf

string

CPF

requerido

CPF do usuário.

Padrão de combinação:

/^\d{11}$/

nome

string

Nome

requerido

Nome do usuário.

<= 200 Caracteres

contas

array [object {3}]

Contas

opcional

Lista de contas associadas ao devedor.

loc

object

opcional

Identificador da localização do payload.

integer <int64>

Id da location

read-onlyrequerido

Identificador da location a ser informada na criação da cobrança .

location

string <uri>

Localização do payload

read-onlyrequerido

Localização do Payload a ser informada na criação da cobrança.

<= 77 Caracteres

Exemplo:

pix.example.com/qr/v2/2353c790eefb11eaadc10242ac120002

tipoCob

enum<string>

Tipo da cobrança

requerido

Valores permitidos:

cobcobv

criacao

string <date-time>

Data de Criação

read-onlyrequerido

Data e hora em que a location foi criada. Respeita RFC 3339.

valor

object

opcional

valores monetários referentes à cobrança.

original

string

Valor

requerido

Valor original da cobrança.

Padrão de combinação:

\d{1,10}\.\d{2}

modalidadeAlteracao

integer <int32>

Modalidade de alteração

opcional

Trata-se de um campo que determina se o valor final do documento pode ser alterado pelo pagador. Na ausência desse campo, assume-se que não se pode alterar o valor do documento de cobrança, ou seja, assume-se o valor 0. Se o campo estiver presente e com valor 1, então está determinado que o valor final da cobrança pode ter seu valor alterado pelo pagador.

>= 0<= 1

retirada

Informações de retirada

opcional

É uma estrutura opcional relacionada ao conceito de recebimento de numerário. Apenas um agrupamento por vez é permitido, quando há saque não há troco e vice-versa.

Quando uma cobrança imediata tem uma estrutura de retirada ela deixa de ser considerada Pix comum e passa à categoria de Pix Saque ou Pix Troco.

Para que o preenchimento do objeto retirada seja considerado válido as seguintes regras se aplicam:

os campos modalidadeAgente e prestadorDoServicoDeSaque são de preenchimento obrigatório;

quando o saque estiver presente a cobrança deve respeitar as seguintes condições:

O campo valor.original deve ser preenchido com valor igual a 0.00 (zero);

O campo valor.modalidadeAlteracao deve possuir o valor 0 (zero) explicitamente, ou implicitamente (pelo não preenchimento).

quando o troco estiver presente a cobrança deve respeitar as seguintes condições:

O campo valor.original deve ser preenchido com valor maior que 0.00 (zero);

O campo valor.modalidadeAlteracao deve possuir o valor 0 (zero) explicitamente, ou implicitamente (pelo não preenchimento).

IMPORTANTE: Quando usados o saque ou troco não será permitida a alteração do valor.original recebido. Na presença de saque ou troco o recebimento do campo valor.modalidadeAlteracao com valor 1 (um) é considerado erro.

Exemplos válidos:

Considerando os campos da estrutura valor e o predicado 'presente' cujo resultado é verdade quando a estrutura apontada é encontrada temos:

uma cobrança com valor fixo (condições: valor.original > 0 && valor.modalidadeAlteração = 0 && !presente(valor.retirada))

...
"valor": {
  "original": "10.00"
},
...

uma cobrança com valor alterável (condições: valor.original >= 0.00 && modalidadeAlteração = 1 && !presente(valor.retirada))

...
"valor": {
  "original": "10.00",
  "modalidadeAlteracao": 1
},

saque com valor fixo (condições: valor.original = 0.00 && valor.modalidadeAlteração = 0 && presente(valor.retirada.saque) && valor.retirada.saque.valor > 0 && valor.retirada.saque.modalidadeAlteracao = 0)

...
"valor": {
  "original": "0.00",
  "retirada": {
    "saque": {
      "valor": "5.00",
      "modalidadeAgente": "AGPSS",
      "prestadorDoServicoDeSaque": "12345678"
    }
  }
},
...

saque com valor alterável (condições: valor.original = 0.00 && valor.modalidadeAlteração = 0 && presente(valor.retirada.saque) && valor.retirada.saque.valor >= 0 && valor.retirada.saque.modalidadeAlteracao = 1)

...
"valor": {
  "original": "0.00",
  "retirada": {
    "saque": {
      "valor": "5.00",
      "modalidadeAlteracao": 1,
      "modalidadeAgente": "AGPSS",
      "prestadorDoServicoDeSaque": "12345678"
    }
  }
},
...

cobrança com troco fixo (condições: valor.original > 0.00 && valor.modalidadeAlteração = 0 && presente(valor.retirada.troco) && valor.retirada.troco.valor > 0 && valor.retirada.troco.modalidadeAlteracao = 0)

...
"valor": {
  "original": "10.00",
  "retirada": {
    "troco": {
      "valor": "5.00",
      "modalidadeAgente": "AGTEC",
      "prestadorDoServicoDeSaque": "12345678"
    }
  }
},
...

cobrança com troco alterável (condições: valor.original > 0.00 && valor.modalidadeAlteração = 0 && presente(valor.retirada.troco) && valor.retirada.troco.valor >= 0 && valor.retirada.troco.modalidadeAlteracao = 1)

...
  "valor": {
    "original": "10.00",
    "retirada": {
      "troco": {
        "valor": "0.00",
        "modalidadeAlteracao": 1,
        "modalidadeAgente": "AGTEC",
        "prestadorDoServicoDeSaque": "12345678"
      }
    }
  },
...

Exemplos inválidos:

Abaixo alguns exemplos que não são válidos. Convém observar que esta listagem não tem pretensão de ser completa, sendo tão somente uma referência para alguns erros possíveis.

saque sem modalidadeAgente e prestadorDoServicoDeSaque

...
"valor": {
  "original": "0.00",
  "retirada": {
    "saque": {
      "valor": "5.00"
    }
  }
},
...

cobrança com saque e troco juntos (não pode ter os dois ao mesmo tempo)

...
"valor": {
  "original": "100.00",
  "retirada": {
    "saque": {
      "valor": "50.00",
      "modalidadeAgente": "AGPSS",
      "prestadorDoServicoDeSaque": "12345678"
    },
    "troco": {
      "valor": "30.00",
      "modalidadeAgente": "AGTEC",
      "prestadorDoServicoDeSaque": "12345678"
    }
  }
},
...

saque com valor.original maior que 0.00 (zero) (saque requer valor.original = 0.00)

...
"valor": {
  "original": "10.00",
  "retirada": {
    "saque": {
      "valor": "5.00",
      "modalidadeAgente": "AGPSS",
      "prestadorDoServicoDeSaque": "12345678"
    }
  }
},
...

troco com valor.original igual a 0.00 (zero) (para haver troco tem que haver valor.original > 0.00)

...
"valor": {
  "original": "0.00",
  "retirada": {
    "troco": {
      "valor": "5.00",
      "modalidadeAgente": "AGTEC",
      "prestadorDoServicoDeSaque": "12345678"
    }
  }
},
...

saque com valor.original alterável (não se pode alterar o valor.original na presença do saque)

...
"valor": {
  "original": "0.00",
  "modalidadeAlteracao": 1,
  "retirada": {
    "saque": {
      "valor": "5.00",
      "modalidadeAlteracao": 1,
      "modalidadeAgente": "AGPSS",
      "prestadorDoServicoDeSaque": "12345678"
    }
  }
},
...

troco com valor.original alterável (não se pode alterar o valor.original na presença do troco)

...
"valor": {
  "original": "0.01",
  "modalidadeAlteracao": 1,
  "retirada": {
    "troco": {
      "valor": "5.00",
      "modalidadeAlteracao": 1,
      "modalidadeAgente": "AGTOT",
      "prestadorDoServicoDeSaque": "12345678"
    }
  }
},
...

chave

string

Chave DICT do recebedor

opcional

Formato do campo chave

O campo chave determina a chave Pix registrada no DICT que será utilizada para a cobrança. Essa chave será lida pelo aplicativo do PSP do pagador para consulta ao DICT, que retornará a informação que identificará o recebedor da cobrança.

Os tipos de chave podem ser: telefone, e-mail, cpf/cnpj ou EVP.

O formato das chaves pode ser encontrado na seção "Formatação das chaves do DICT no BR Code" do Manual de Padrões para iniciação do Pix.

<= 77 Caracteres

solicitacaoPagador

string

Solicitação ao pagador

opcional

O campo solicitacaoPagador, opcional, determina um texto a ser apresentado ao pagador para que ele possa digitar uma informação correlata, em formato livre, a ser enviada ao recebedor. Esse texto será preenchido, na pacs.008, pelo PSP do pagador, no campo RemittanceInformation . O tamanho do campo na pacs.008 está limitado a 140 caracteres.

<= 140 Caracteres

infoAdicionais

array [object {2}]

Informações adicionais

opcional

Cada respectiva informação adicional contida na lista (nome e valor) deve ser apresentada ao pagador.

nome

string

Nome

requerido

Nome do campo.

<= 50 Caracteres

valor

string

Valor

requerido

Dados do campo.

<= 200 Caracteres

txid

string

TxId

opcional

The "txId" field is a unique identifier generated by the Pix system to uniquely identify and monitor transactions.

revisao

integer <int32>

Revisão

read-onlyopcional

O campo `revisao`

Denota a revisão da cobrança. Sempre começa em zero. Sempre varia em acréscimos de 1.

O incremento em uma cobrança deve ocorrer sempre que um objeto da cobrança em questão for alterado.
O campo loc é uma exceção a esta regra.

Se em uma determinada alteração em uma cobrança, o único campo alterado for o campo loc,
então esta operação não incrementa a revisão da cobrança.

O campo loc não ocasiona uma alteração na cobrança em si.
Não é necessário armazenar histórico das alterações do campo loc para uma determinada cobrança.
Para os outros campos da cobrança, registra-se histórico.

location

string <uri>

Localização do payload

read-onlyopcional

Localização do Payload a ser informada na criação da cobrança.

<= 77 Caracteres

Exemplo:

pix.example.com/qr/v2/2353c790eefb11eaadc10242ac120002

pixCopiaECola

string

Pix Copia e Cola correspondente à cobrança.

opcional

Este campo retorna o valor do Pix Copia e Cola correspondente à cobrança. Trata-se da sequência de caracteres que representa o BR Code.

<= 512 Caracteres

🟠403Forbidden

🟠404Record Not Found

🔴503Service Unavailable

Página anterior

Revisar cobrança imediata.

Próxima página

Criar cobrança imediata.

Consultar cobrança imediata.

Requisição

Respostas

Exemplos válidos:

Exemplos inválidos:

Formato do campo chave

Exemplos válidos:

Exemplos inválidos:

Formato do campo chave

O campo revisao

O campo `revisao`