Consultar cobrança imediata

get https://api.pix.voluti.com.br/cob/{txid}

Use este endpoint para consultar uma cobrança através de um determinadotxid.

time	status	user agent
Retrieving recent requests…

Loading…

Path Params

txid

string

required

Identificador da transação (txid):

O campo txid determina o identificador da transação, sendo crucial para o processo de conciliação de pagamentos, pois determina a transação de forma única. Na pacs.008, é mencionado como TransactionIdentification <txId> ou idConciliacaoRecebedor.

Funcionalidade:

O txid é gerado pelo usuário recebedor e enviado ao PSP do pagador.
Após a confirmação do pagamento, é transmitido para o SPI via pacs.008 e também para o PSP do recebedor.
Ao detectar um pagamento com txid, o PSP do recebedor pode informar ao usuário recebedor sobre a liquidação específica desse pagamento.

Responsabilidades:

O txid é criado exclusivamente pelo usuário recebedor e está sob sua responsabilidade.
Cada txid é único por CPF/CNPJ do usuário recebedor, com a validação dessa regra realizada pelo PSP recebedor na API Pix.

Query Params

revisao

json

Indica a revisão da cobrança

Responses

Response body

object

calendario

object

required

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

expiracao

int32

Defaults to 86400

Tempo de vida da cobrança, especificado em segundos a partir da data do campo criação.

criacao

date-time

required

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

devedor

Os campos contidos 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.

cpf ou cnpj: A cobrança pode ter um CPF ou um CNPJ como devedor. Não é permitido preencher ambos ao mesmo tempo.
nome: Se o nome do devedor estiver preenchido, deve existir um CPF ou CNPJ preenchido.

loc

object

Identificador da localização do payload.

int64

required

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

location

uri

required

length ≤ 77

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

tipoCob

string

required

Tipo de cobrança.

cob cobv

criacao

date-time

required

Data e hora em que a localização foi criada. Respeita RFC 3339.

valor

object

required

valores monetários referentes à cobrança.

original

string

Valor original da cobrança.

modalidadeAlteracao

int32

0 to 1

Indica se o valor final do documento pode ser alterado pelo pagador. Se ausente, assume-se que o valor é fixo (0). Se presente e definido como 1, o valor pode ser alterado pelo pagador.

retirada

object

É 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

length ≤ 77

Formato da Chave Pix na qual a conta receberá o valor.

Conforme especificado na PACS.008. Os tipos de chave permitidos são:

Telefone
E-mail
CPF/CNPJ
O Endereço Virtual de Pagamento (EVP)

O formato detalhado das chaves está na seção "Formatação das chaves do DICT no BR Code" do Manual de Padrões para Iniciação do Pix.
.

solicitacaoPagador

string

length ≤ 140

Permite que o pagador inclua um texto livre relacionado ao recebedor.

Preenchimento: O PSP do pagador insere esse texto no campo RemittanceInformation da pacs.008.

Limite de caracteres: Restrito a 140 caracteres.

infoAdicionais

array of objects

Apresentação das informações adicionais ao pagador:

Cada informação adicional contida nos campos nome e valor deve ser exibida ao pagador.

Informações adicionais

object

nome

string

required

length ≤ 50

Nome do pagador.

valor

string

required

length ≤ 200

Valor de cobrança.

txid

string

required

Identificador da transação (txid):

Funcionalidade:

O txid é gerado pelo usuário recebedor e enviado ao PSP do pagador.
Após a confirmação do pagamento, é transmitido para o SPI via pacs.008 e também para o PSP do recebedor.
Ao detectar um pagamento com txid, o PSP do recebedor pode informar ao usuário recebedor sobre a liquidação específica desse pagamento.

Responsabilidades:

O txid é criado exclusivamente pelo usuário recebedor e está sob sua responsabilidade.
Cada txid é único por CPF/CNPJ do usuário recebedor, com a validação dessa regra realizada pelo PSP recebedor na API Pix.

revisao

int32

required

Indica a revisão da cobrança, começando sempre em zero e aumentando em incrementos de 1.

Incremento: A revisão é incrementada sempre que um objeto da cobrança é alterado, exceto pelo campo loc.
Exceção: Se a única alteração em uma cobrança for no campo loc, a revisão não é incrementada, pois o loc não altera a cobrança em si.
Armazenamento: Não é necessário manter histórico das alterações do campo loc, mas é necessário para outros campos da cobrança.

location

uri

length ≤ 77

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

status

string

required

Estado do registro da cobrança.

Os status:

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;
REMOVIDO_PELO_USUARIO_RECEBEDOR: Indica que o usuário recebedor solicitou a remoção do registro da cobrança;
REMOVIDO_PELO_PSP: Indica que o PSP recebedor solicitou a remoção do registro da cobrança.

ATIVA CONCLUIDA REMOVIDA_PELO_USUARIO_RECEBEDOR REMOVIDA_PELO_PSP

pixCopiaECola

string

length ≤ 512

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.

pix

array of objects

Pix recebidos

object

endToEndId

string

required

length between 32 and 32

O identificador da transação ou End to End ID é utilizado para identificar um pagamento Pix realizado contemplando todo o mercado que transita na PACS002, PACS004 e PACS008.

PACS.002: Mensagem de status de pagamento. Utiliza o EndToEndIdentification para relacionar a resposta ao pagamento original.
PACS.004: Mensagem de devolução de pagamento. Garante que a devolução seja associada corretamente ao pagamento inicial.
PACS.008: Mensagem de crédito interbancário. Rastreia o pagamento da origem ao destino final.

txid

string

Identificador da transação (txid):

Funcionalidade:

O txid é gerado pelo usuário recebedor e enviado ao PSP do pagador.
Após a confirmação do pagamento, é transmitido para o SPI via pacs.008 e também para o PSP do recebedor.
Ao detectar um pagamento com txid, o PSP do recebedor pode informar ao usuário recebedor sobre a liquidação específica desse pagamento.

Responsabilidades:

O txid é criado exclusivamente pelo usuário recebedor e está sob sua responsabilidade.
Cada txid é único por CPF/CNPJ do usuário recebedor, com a validação dessa regra realizada pelo PSP recebedor na API Pix.

valor

string

required

Valor do Pix.

componentesValor

object

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 considerando-se um atraso de 2 dias a uma multa de 3% e juros de 1% ao dia. O valor do Pix será R$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

length ≤ 77

Formato da Chave Pix.

O campo chave do recebedor é atribuído conforme especificado na PACS.008. Os tipos de chave permitidos são:

Telefone
E-mail
CPF/CNPJ
O Endereço Virtual de Pagamento (EVP)

O formato detalhado das chaves está na seção "Formatação das chaves do DICT no BR Code" do Manual de Padrões para Iniciação do Pix.

horario

date-time

required

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

infoPagador

string

length ≤ 140

Informação livre do pagador.

devolucoes

array of objects

Devoluções

object

string

required

Identificação gerada pelo cliente para representar uma devolução.

rtrId

string

required

length between 32 and 32

ReturnIdentification é utilizado para identificar de forma única uma transação de devolução na mensagem PACS.004. Ele assegura a correta associação entre a devolução e a transação original.

A utilização do ReturnIdentification garante a integridade e a rastreabilidade das devoluções no sistema de pagamentos.

valor

string

required

Valor da devolução.

natureza

string

Indica qual é a natureza da devolução. Uma devolução pode ser relacionada a um Pix comum (com códigos possíveis: MD06, BE08 e FR01 da pacs.004),
ou a um Pix de Saque ou Troco (com códigos possíveis: MD06 e SL02 da pacs.004). Na ausência deste campo a natureza deve ser interpretada como
sendo de um Pix comum (ORIGINAL).

As naturezas são assim definidas:

ORIGINAL: quando a devolução é solicitada pelo usuário recebedor e se refere a um Pix comum ou ao valor da compra em um Pix Troco (MD06);
RETIRADA: quando a devolução é solicitada pelo usuário recebedor e se refere a um Pix Saque ou ao valor do troco em um Pix Troco (SL02);
MED_OPERACIONAL: quando a devolução ocorre no âmbito do MED por motivo de falha operacional e se refere a um Pix comum (BE08);
MED_FRAUDE: quando a devolução ocorre no âmbito do MED por fundada suspeita de fraude e se refere a um Pix comum (FR01).

Os valores de devoluções são sempre limitados aos valores máximos a seguir:

Pix comum: o valor da devolução é limitado ao valor do próprio Pix (a natureza nesse caso pode ser: ORIGINAL, MED_OPERACIONAL ou MED_FRAUDE);
Pix Saque: o valor da devolução é limitado ao valor da retirada (a natureza nesse caso deve ser: RETIRADA);
Pix Troco: o valor da devolução é limitado ao valor relativo à compra ou ao troco:
- Quando a devolução for referente à compra, o valor limita-se ao valor da compra (a natureza nesse caso deve ser ORIGINAL);
- Quando a devolução for referente ao troco, o valor limita-se ao valor do troco (a natureza nesse caso deve ser RETIRADA).

ORIGINAL RETIRADA MED_OPERACIONAL MED_FRAUDE

descricao

string

length ≤ 140

O campo descricao é opcional e permite que informações sobre a devolução sejam apresentadas ao pagador. Na mensagem PACS.004, este campo é preenchido pelo PSP do recebedor e inserido no campo RemittanceInformation.

horario

object

required

status

string

required

Status da devolução.

EM_PROCESSAMENTO DEVOLVIDO NAO_REALIZADO

motivo

string

length ≤ 140

Status da Devolução

Campo opcional que pode ser utilizado pelo PSP recebedor para detalhar os motivos
de a devolução ter atingido o status em questão.
Pode ser utilizado, por exemplo, para detalhar o motivo de a devolução não ter sido realizada.

Language

Credentials

OAuth2


xxxxxxxxxx
1
curl --request GET \
2
     --url https://api.pix.voluti.com.br/cob/txid \
3
     --header 'accept: application/json'


xxxxxxxxxx
35
}
1
{
2
  "calendario": {
3
    "criacao": "2020-09-09T20:15:00.358Z",
4
    "expiracao": 3600
5
  },
6
  "txid": "7978c0c97ea847e78e8849634473c1f1",
7
  "revisao": 0,
8
  "loc": {
9
    "id": 789,
10
    "location": "pix.example.com/qr/9d36b84fc70b478fb95c12729b90ca25",
11
    "tipoCob": "cob"
12
  },
13
  "location": "pix.example.com/qr/9d36b84fc70b478fb95c12729b90ca25",
14
  "status": "ATIVA",
15
  "devedor": {
16
    "cnpj": "12345678000195",
17
    "nome": "Empresa de Serviços SA"
18
  },
19
  "valor": {
20
    "original": "37.00",
21
    "modalidadeAlteracao": 1
22
  },
23
  "chave": "7d9f0335-8dcc-4054-9bf9-0dbd61d36906",
24
  "solicitacaoPagador": "Serviço realizado.",
25
  "infoAdicionais": [

200Dados da cobrança imediata.

Exemplos válidos:

Exemplos inválidos:

Exemplos válidos:

Exemplos inválidos:

403Requisição de participante autenticado que viola alguma regra de autorização.

404Recurso solicitado não foi encontrado.

503Serviço não está disponível no momento. Serviço solicitado pode estar em manutenção ou fora da janela de funcionamento.