[Visa e Elo] Identificador de recorrência para assinaturas externas
Introdução
A implementação de assinaturas externas tem como objetivo melhorar a gestão de transações recorrentes, assegurando que o identificador da primeira cobrança seja utilizado em todas as cobranças subsequentes.
Essa prática, exigida pelas bandeiras Visa e Elo, visa trazer mais controle, transparência e conformidade às transações de assinaturas, além de evitar multas por não atender às novas regulamentações.
O prazo para adequação é até 30 de setembro de 2024.
Novos Campos: Facilitando a Identificação das Transações
Para garantir que todas as transações de assinaturas externas sejam corretamente vinculadas à cobrança original, foram criados dois novos campos que estarão disponíveis nas rotas de criação de pedido, atualização do método de pagamento e atualização do cartão:
payment_origin.charge_id: Identificador da primeira cobrança da assinatura externa.payment_origin.brand_id: Identificador da bandeira referente a primeira transação da assinatura externa.
Esses campos precisam ser incluídos em todas as transações subsequentes. Basta utilizar qualquer um dos dois para garantir a identificação correta de uma assinatura externa.
Fluxo de assinaturas externas
- Primeira Transação (Criação do Pedido): Quando você realiza a criação de pedido para iniciar uma assinatura externa, a primeira transação é registrada, gerando o
brand_idecharge_idcorrespondente. Caso a assinatura seja uma migração de outro sistema, a informação debrand_idjá deve ser enviada na primeira transação.- Cada bandeira pode retornar um padrão de brand_transaction_id. Exemplos:
- Mastercard: BUQY9X (Alfanumérico)
- Visa: 384269516450059 (Numérico)
- Elo: 2692422A0574101 (Alfanumérico)
- Hiper: GHZR9W (Alfanumérico)
- Cada bandeira pode retornar um padrão de brand_transaction_id. Exemplos:
- Transações Subsequentes: Para todas as cobranças futuras da assinatura, é obrigatório incluir o
payment_origin.charge_idoupayment_origin.brand_id. Esses campos garantem o correto rastreamento e vínculo com a transação original, conforme exigido pelas bandeiras.
Com esses novos campos, o fluxo de assinaturas externas se torna mais eficiente e em conformidade com os requisitos regulatórios, oferecendo mais controle e transparência nas transações.
Alterações na Recorrência
Caso ocorra alguma alteração na recorrência, como mudança de cartão (seja com a mesma bandeira ou com bandeiras diferentes), alteração de meio de pagamento ou alteração de valores, o ID da primeira transação após a alteração deverá ser considerado como o novo primeiro, passando a ser o ID enviado.
Para clientes que utilizam o produto Card Updater (Bandeira Visa) para a atualização de cartões vencidos, não é necessário alterar o ID enviado, uma vez que essa alteração é comunicada diretamente com a bandeira Visa.
Exemplo de Request para Criação de Pedido:
curl --request POST \
--url https: //api.pagar.me/core/v5/orders \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--data '
{
"customer": {
"phones": {
"home_phone": {
"country_code": "55",
"area_code": "21",
"number": "000000000"
}
},
"name": "Tony Stark",
"email": "[email protected]",
"type": "individual",
"document": "03154435026",
"document_type": "cpf"
},
"items": [
{
"amount": 2990,
"description": "Chaveiro do Tesseract",
"quantity": 1,
"code": 123
}
],
"payments": [
{
"payment_method": "credit_card",
"credit_card": {
"recurrence_cycle": "subsequent",
"payment_origin": {
"charge_id": "ch_3zQKDq3srCog1dmy", // limite de 35 caracteres
"brand_id": "id_da_bandeira" // limite de 35 caracteres
},
// enviar ou charge_id ou brand_id
"installments": 1,
"statement_descriptor": "AVENGERS",
"card": {
"number": "4000000000000010",
"holder_name": "Tony Stark",
"exp_month": 1,
"exp_year": 25,
"cvv": "351"
}
}
}
]
}
'
--url https: //api.pagar.me/core/v5/orders \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--data '
{
"customer": {
"name": "Tony Stark",
"email": "[email protected]",
"type": "individual",
"document": "03154435026",
"document_type": "cpf"
},
"items": [
{
"amount": 2990,
"description": "Chaveiro do Tesseract",
"quantity": 1,
"code": 123
}
],
"payments": [
{
"payment_method": "credit_card",
"credit_card": {
"recurrence_cycle": "subsequent",
"payment_origin": {
"charge_id": "ch_3zQKDq3srCog1dmy", // limite de 35 caracteres
"brand_id": "id_da_bandeira" // limite de 35 caracteres
},
// enviar ou charge_id ou brand_id
"installments": 1,
"statement_descriptor": "AVENGERS",
"card": {
"number": "4000000000000010",
"holder_name": "Tony Stark",
"exp_month": 1,
"exp_year": 25,
"cvv": "351"
}
}
}
]
}
'
{
"id": "or_152l3pBC1cdgWKVY",
"code": "N7KJB6S5E9",
"amount": 2990,
"currency": "BRL",
"closed": true,
"items": [
{
"id": "oi_Nv148b7kFdHq6A0j",
"type": "product",
"description": "Chaveiro do Tesseract",
"amount": 2990,
"quantity": 1,
"status": "active",
"created_at": "2024-09-12T15:07:45Z",
"updated_at": "2024-09-12T15:07:45Z",
"code": "123"
}
],
"customer": {
"id": "cus_3LVRrkoUVF8AlrY0",
"name": "Tony Stark",
"email": "[email protected]",
"code": "{{Código do cliente}}",
"document": "03154435026",
"document_type": "cpf",
"type": "individual",
"delinquent": false,
"address": {
"id": "addr_LWOyBr0IevTD9y0z",
"line_1": "7221, Avenida Dra Ruth Cardoso, Pinheiro",
"line_2": "Prédio",
"zip_code": "05425070",
"city": "São Paulo",
"state": "SP",
"country": "BR",
"status": "active",
"created_at": "2023-02-09T13:26:48Z",
"updated_at": "2023-10-11T21:33:05Z"
},
"created_at": "2020-11-23T17:55:51Z",
"updated_at": "2024-08-22T15:06:10Z",
"birthdate": "1993-01-09T00:00:00Z",
"phones": {
"home_phone": {
"country_code": "55",
"number": "000000000",
"area_code": "21"
},
"mobile_phone": {
"country_code": "55",
"number": "000000000",
"area_code": "11"
}
},
"metadata": {
"classificação": "Cliente VIP"
}
},
"status": "paid",
"created_at": "2024-09-12T15:07:45Z",
"updated_at": "2024-09-12T15:07:45Z",
"closed_at": "2024-09-12T15:07:45Z",
"charges": [
{
"id": "ch_z1ZdJ9Zu8DCOLobM",
"code": "N7KJB6S5E9",
"gateway_id": "2206087980",
"amount": 2990,
"paid_amount": 2990,
"status": "paid",
"currency": "BRL",
"payment_method": "credit_card",
"paid_at": "2024-09-12T15:07:45Z",
"created_at": "2024-09-12T15:07:45Z",
"updated_at": "2024-09-12T15:07:45Z",
"payment_origin": {
"charge_id": "string", // Campo Novo
"brand_id": "string" // Campo Novo
},
"customer": {
"id": "cus_3LVRrkoUVF8AlrY0",
"name": "Tony Stark",
"email": "[email protected]",
"code": "{{Código do cliente}}",
"document": "03154435026",
"document_type": "cpf",
"type": "individual",
"delinquent": false,
"address": {
"id": "addr_LWOyBr0IevTD9y0z",
"line_1": "7221, Avenida Dra Ruth Cardoso, Pinheiro",
"line_2": "Prédio",
"zip_code": "05425070",
"city": "São Paulo",
"state": "SP",
"country": "BR",
"status": "active",
"created_at": "2023-02-09T13:26:48Z",
"updated_at": "2023-10-11T21:33:05Z"
},
"created_at": "2020-11-23T17:55:51Z",
"updated_at": "2024-08-22T15:06:10Z",
"birthdate": "1993-01-09T00:00:00Z",
"phones": {
"home_phone": {
"country_code": "55",
"number": "000000000",
"area_code": "21"
},
"mobile_phone": {
"country_code": "55",
"number": "000000000",
"area_code": "11"
}
},
"metadata": {
"classificação": "Cliente VIP"
}
},
"last_transaction": {
"id": "tran_X0kYbz5skqtEYPxj",
"transaction_type": "credit_card",
"gateway_id": "2206087980",
"amount": 2990,
"status": "captured",
"brand_id": "string", // Campo Novo
"success": true,
"installments": 1,
"statement_descriptor": "AVENGERS",
"acquirer_name": "pagarme",
"acquirer_tid": "2206087980",
"acquirer_nsu": "2206087980",
"acquirer_auth_code": "866328",
"acquirer_message": "Transação aprovada com sucesso",
"acquirer_return_code": "0000",
"operation_type": "auth_and_capture",
"card": {
"id": "card_Yx4Qy3LtYtmk7qr6",
"first_six_digits": "400000",
"last_four_digits": "0010",
"brand": "Visa",
"holder_name": "Tony Stark",
"exp_month": 1,
"exp_year": 2025,
"status": "active",
"type": "credit",
"created_at": "2021-02-17T18:32:41Z",
"updated_at": "2024-09-12T15:07:45Z",
"billing_address": {
"zip_code": "90265",
"city": "Malibu",
"state": "CA",
"country": "US",
"line_1": "10880, Malibu Point, Malibu Central"
}
},
"funding_source": "credit",
"created_at": "2024-09-12T15:07:45Z",
"updated_at": "2024-09-12T15:07:45Z",
"gateway_response": {
"code": "200",
"errors": []
},
"antifraud_response": {},
"metadata": {}
},
"recurrence_cycle": "subsequent"
}
],
"checkouts": []
}
Assinaturas Internas
Se você utiliza o motor de recorrência do Pagar.me, não é necessário se preocupar com o envio manual dessas informações.
O sistema cuidará automaticamente de transmitir os identificadores necessários, garantindo que todas as transações sejam processadas corretamente.
Assinaturas Externas
Se você não utiliza o motor de recorrência do Pagar.me e que trabalha com mais de um meio de pagamento ou mais de um cartão na mesma assinatura deve considerar cada meio de pagamento ou cartão como uma transação separada. Portanto, é necessário o envio do ID correspondente a cada uma delas.
Outras Versões da API
Caso utilize uma versão anterior das nossas APIs, clique aqui para acessar a documentação.
Funcionalidade por Adquirentes
Caso sua empresa utilize a Stone como adquirente, a integração já está preparada para receber e repassar essas informações para as Bandeiras.
Se utilizar outra adquirente, recomendamos verificar com a mesma se está pronta para o recebimento e repasse dos dados exigidos pelas Bandeiras e os prazos de adequação.
Conclusão
Essa implementação é crucial para garantir que as assinaturas externas sejam identificadas de forma precisa e estejam em conformidade com os requisitos das bandeiras. Adequar-se a essas mudanças garante que cada transação subsequente de uma assinatura tenha uma referência clara à primeira cobrança, facilitando o monitoramento e evitando penalidades.
Em caso de dúvidas, entre em contato com nosso time de atendimento ao cliente pelo e-mail [email protected], pelo chat na sua dashboard ou pelo telefone 4004-1330.
Updated about 1 month ago