BrandTID e TransactionLinkID
Motor Próprio de Recorrência
É quando o cliente/lojista opta por integrar sua solução com o Vindi Gateway utilizando a fatura avulsa e aplicando seu próprio mecanismo de recorrência.
Como a transação é processada como uma fatura única, isso pode resultar em erros de transação e, consequentemente, na redução da taxa de aprovação.
Com o objetivo de adequar as transações avulsas no formato recorrência para clientes que desejam ter o motor de recorrência do seu próprio lado, resolvemos fazer algumas adequações para a bandeira observar a transação de faturas avulsas no formato de recorrência.
O que é o BrandTID e TransactionLinkID?
São códigos únicos gerados pelas bandeiras (como Visa, Mastercard e Elo) para rastrear o ciclo de vida das transações recorrentes. O fluxo é dividido em duas etapas:
CIT (Customer Initiated Transaction / Transação inciada pelo Pagador): É a 1ª transação, onde o cliente insere ativamente os dados do cartão. Aqui, o código original é gerado pela bandeira.
MIT (Merchant Initiated Transaction/ Transação inciada pelo Lojista/Motor Vindi): São as renovações automáticas, geração de faturas avulsas com cartão armazenado (sem a presença do cliente). Nestas transações, é obrigatório enviar o código gerado na etapa CIT para comprovar que a cobrança faz parte de uma cadeia autorizada.
Requisitos para uso,
- O Cliente/Lojista deve controlar a periodicidade - intervalo que acontece entre as cobranças ex mensal, bimestral, semestral etc - das assinaturas (motor de recorrência próprio);
- O Cliente/Lojista precisa gerenciar as regras do BrandTid ou TransactionLinkID -
- Para Rede, Stone e Getnet versão 2 o BrandTid deve ser recebido no retorno da primeira cobrança e enviado atrelado a segunda fatura via API;
- Para Cielo o BrandTid ou TransactionLinkID deve ser recebido no retorno da segunda cobrança e enviado atrelado a terceira fatura via API;
- O Cliente/Lojista tem de estar trabalhando no formato de fatura avulsa (Endpoints /v1/bills e /v1/billing para parceiros);
- O gateway obrigatoriamente deve estar configurado em “01 Etapa: Cobrança automática”;
- A flag de recorrência obrigatoriamente habilitada como
truepara indicar que uma fatura avulsa, na verdade, é uma cobrança recorrente. - O parcelamento de cobranças com intervalo definido deverá ser igual a 1 a cada fatura.
O que é o BrandTID e TransactionLinkID?
O BrandTid e o TransactionLinkID são campos únicos e dinâmicos, recebidos a cada resposta de transação, e são utilizados para identificar planos de recorrência.
Devem ser enviado para a bandeira a partir da segunda transação recorrente, e faz a correlação das transações subsequentes com a primeira.
- Enviado apenas quando há uma recorrência.
- O estabelecimento/lojista é responsável por armazenar o BrandTid (Visa e Elo) ou TransactionLinkID (Mastercard) retornado e enviá-los em todas as transações subsequentes.
Os identificadores das bandeiras são importantes para garantir uma melhor taxa de aprovação, pois permitem relacionar a transação atual com uma transação anterior, facilitando o reconhecimento pelo emissor.
-
Visa: uso obrigatório, especialmente em transações tokenizadas.
-
Mastercard : o envio é necessário para relacionar corretamente as recorrências.
-
Elo : uso obrigatório para correlacionar transações iniciadas pelo estabelecimento, recorrentes e com cartão armazenado.
-
Adquirentes que suportam BrandTID: e.Rede, Cielo v3, Stone e Getnet v2 (Mastercard, Visa e Elo).
-
Adquirentes que suportam TransactionLinkID: e.Rede, Cielo v3 e Getnet v2 (Mastercard - à partir de 23/10/2026 para Cielo e Rede e 01/11/2026 para Getnet)
-
ATENÇÃO:
Importante- O campo BrandTID foi implantado e é monitorado pelas adquirentes suportadas desde junho/2024.
- A bandeira Mastercard deixará de usar o identificador BrandTID, substituindo-o obrigatoriamente pelo TransactionLinkID para transações recorrentes com esta bandeira - as demais bandeiras continuarão com campo BrandTID.
- O monitoramento geral começará em 23/10/2026 (Cielo e Rede) e 01/11/2026 (Getnet versão 2). A não utilização correta do TransactionLinkID nessas transações poderá resultar em sinalizações e multas a partir de janeiro de 2027, repassadas por sua adquirente contratada.
Regras de controle BrandTid e TransactionLinkID
O BrandTid e TransactionLinkID seguem algumas regras obrigatórias. Caso não sejam cumpridas, as bandeiras podem rejeitar a transação.
As seguintes situações reiniciam o BrandTid e TransactionLinkID, sendo necessário iniciar um novo ciclo:
- Mudança de periodicidade (ex: intervalo entre cobranças como mensal, bimestral, semestral, anual)
- Alteração no valor da cobrança
- Novo cartão utilizado na transação
IMPORTANTE
Na primeira transação, o BrandTid deve ser armazenado e utilizado nas transações subsequentes do ciclo de recorrência.
ATENÇÃO:A adquirente Cielo não retorna o BrandTid ou TransactionLinkID na primeira transação, apenas a partir do segundo ciclo de recorrência.
OBSERVAÇÃO:Caso a transação não siga as regras do BrandTid ou TransactionLinkID, há chance de rejeição pela Bandeira.
Exemplo: Endpoint, Chamadas e Retornos BrandTid/TransactionLinkID
O endpoint continua sendo o mesmo do transacional.
-
Documentação Vindi:
https://vindi.github.io/api-docs/dist/#/bills/postV1Bill -
URL:
http://app.vindi.com.br/api/v1/bills
Incluímos um novo parâmetro chamado brand_tid que deve ser enviado conforme as regras estabelecidas.
Exemplo de envio BrandTID:
{
"customer_id": 2,
"installments": 1,
"payment_method_code": "credit_card",
"brand_tid": "6iqHnxgugSjmMDxQJMBxC9E",
"bill_items": [
{
"product_id": 1,
"amount": 199
}
],
"payment_profile": {
"gateway_token": "34800622-7d98-4195-aba8-4c34e1e074f6"
}
}
Exemplo de envio TransactionLinkID:
Incluímos um novo parâmetro chamado transaction_link_id que deve ser enviado conforme as regras estabelecidas.
{
"customer_id": 2,
"installments": 1,
"payment_method_code": "credit_card",
"transaction_link_id": "5iRHnxgugSjmMDxQJMBxC9E",
"bill_items": [
{
"product_id": 1,
"amount": 199
}
],
"payment_profile": {
"gateway_token": "34800622-7d98-4195-aba8-4c34e1e074f6"
}
}
Exemplo parcial do retorno cielo_v3 (bills.charge.last_transaction):
"last_transaction": {
"id": 987958754,
"transaction_type": "charge",
"status": "success",
"amount": "5.55",
"installments": 1,
"gateway_message": "Transacao capturada com sucesso",
"gateway_response_code": null,
"gateway_authorization": "6b50fbe4-a39e-4f17-a208-aaed08031weg",
"gateway_transaction_id": "19c7dd53-65d8-4c71-b372-99b481d8c87a",
"gateway_response_fields": {
"tid": "28559795305MV97HGA2B",
"authorization_code": "437213",
"proof_of_sale": "042861",
"payment_id": "6b50fbe4-a39e-4f17-a208-aaed08031weg",
"issuer_transaction_id": "YTV0I6",
"brand_tid": "YTV0I6",
"transaction_link_id": "KHI3FCRFQ9aVIR6LPbyGFT"
}Exemplo parcial do retorno e_rede_rest (bills.charge.last_transaction):
"last_transaction": {
"id": 987958754,
"transaction_type": "charge",
"status": "success",
"amount": "5.55",
"installments": 1,
"gateway_message": "Transacao capturada com sucesso",
"gateway_response_code": null,
"gateway_authorization": "6b50fbe4-a39e-4f17-a208-aaed08031weg",
"gateway_transaction_id": "19c7dd53-65d8-4c71-b372-99b481d8c87a",
"gateway_response_fields": {
"tid": "28559795305MV97HGA2B",
"authorization_code": "437213",
"proof_of_sale": "042861",
"payment_id": "6b50fbe4-a39e-4f17-a208-aaed08031weg",
"issuer_transaction_id": "YTV0I6",
"brand_tid": "YTV0I6",
"transaction_link_id": "KHI3FCRFQ9aVIR6LPbyGFT"
}Exemplo parcial do retorno getnet_v2 (bills.charge.last_transaction):
"last_transaction": {
"id": 1001699748,
"transaction_type": "charge",
"status": "success",
"amount": "192.73",
"installments": 2,
"gateway_message": "captured",
"gateway_response_code": "00",
"gateway_authorization": "",
"gateway_transaction_id": "b7a42485-a90e-4e31-9c09-03a901934123",
"gateway_response_fields": {
"acquirer_transaction_id": "000530829123",
"authorization_code": "453123",
"authorized_at": "2026-11-08T21:45:31.834Z",
"issuer": "Banco Santander Brasil SA",
"order_id": "2082878",
"original_transaction_id": "MPLM5ZSWR1110",
"payment_id": "787c6ca6-9545-4f90-bc87-82059c66cb9c",
"payment_method": "CREDIT_AUTHORIZATION",
"received_at": "2026-11-08T21:45:30.000Z",
"request_id": "c75a6982-ff1f-4e50-b50d-00d814d68ef6",
"seller_id": "1f1a907f-9c86-4755-be33-3067b8bbbb83",
"soft_descriptor": "LOJA X",
"status": "CAPTURED",
"transaction_id": "MPLM5ZSWR1108",
"transaction_link_identifier": "22NkhB1MvzTN-5gzX5d543rt",
"captured_at": "2026-11-08T21:45:33.769Z"
}Toda transação retorna um valor de BrandTid/TransactionLinkID diferente, você deve salvar o novo BrandTid/TransactionLinkID somente se ocorrer uma mudança de periodicidade da assinatura (intervalo entre cobranças), valor da transação e/ou mudança de dados do cartão.
Toda primeira transação com um novo cartão será feita com o CVV, às demais transações recorrentes de um cartão já cadastrado será enviado sem o uso do CVV em conformidade com as regras da adquirente e bandeira.
Updated 14 days ago
