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"
    }
  }
},
...