Guides
GuidesSuporteAPI Reference

[Visa e Elo] Identificador de recorrência para assinaturas externas

Suggest Edits

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

  1. 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_id e charge_id correspondente. Caso a assinatura seja uma migração de outro sistema, a informação de brand_id já deve ser enviada na primeira transação.
    1. Cada bandeira pode retornar um padrão de brand_transaction_id. Exemplos:
      1. Mastercard: BUQY9X (Alfanumérico)
      2. Visa: 384269516450059 (Numérico)
      3. Elo: 2692422A0574101 (Alfanumérico)
      4. Hiper: GHZR9W (Alfanumérico)
  2. Transações Subsequentes: Para todas as cobranças futuras da assinatura, é obrigatório incluir o payment_origin.charge_id ou payment_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.

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 9 days ago