Identificador da transação (txid)
O campo txid determina o identificador da transação. O objetivo desse campo é ser um elemento que possibilite ao PSP do recebedor apresentar ao usuário recebedor a funcionalidade de conciliação de pagamentos.
Na pacs.008, é referenciado como TransactionIdentification ou idConciliacaoRecebedor.
Em termos de fluxo de funcionamento, o txid é lido pelo aplicativo do PSP do pagador e, depois de confirmado o pagamento, é enviado para o SPI via pacs.008. Uma pacs.008 também é enviada ao PSP do recebedor, contendo, além de todas as informações usuais do pagamento, o txid. Ao perceber um recebimento dotado de txid, o PSP do recebedor está apto a se comunicar com o usuário recebedor, informando que um pagamento específico foi liquidado.
O txid é criado exclusivamente pelo usuário recebedor e está sob sua responsabilidade. O txid, no contexto de representação de uma cobrança, é único por CPF/CNPJ do usuário recebedor. Cabe ao PSP recebedor validar essa regra na API Pix.
Scopes:
cob.write - Permissão para alteração de cobranças imediatas
cob.read - Permissão para consulta de cobranças imediatas
cobv.write - Permissão para alteração de cobranças com vencimento
cobv.read - Permissão para consulta de cobranças com vencimento
lotecobv.write - Permissão para alteração de lotes de cobranças com vencimento
lotecobv.read - Permissão para consulta de lotes de cobranças com vencimento
pix.write - Permissão para alteração de Pix
pix.read - Permissão para consulta de Pix
webhook.read - Permissão para consulta do webhook
webhook.write - Permissão para alteração do webhook
payloadlocation.write - Permissão para alteração de payloads
payloadlocation.read - Permissão para consulta de payloads
Mais informações sobre "retirada":
É 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"
}
}
},
...