Pagar.me - Dashboard | Novo status de Chargeback na Cobrança

Com o intuito de aumentar o detalhamento dos status das transações no Pagar.me, a partir de 16 de setembro de 2022 teremos um novo status nas nossas API's Pagar.me, o "chargedback". Com essa alteração, garantimos que você saiba quais cobranças sofreram chargeback para que possa contestá-las, caso seja necessário.

Nota

O novo status chargedback só será incluído para clientes no modelo PSP. Clientes do modelo Gateway não receberão esta atualização via API.

O que irá mudar?

No seu Dashboard: A partir do lançamento da funcionalidade, toda cobrança com status chargedback será mostrada dentro da própria visualização da transação.

Na sua integração via API: Teremos duas maneiras de verificar se uma transação sofreu chargeback, via Webhook ou via consulta de pedidos/cobranças em GET /orders ou GET /charges. Abaixo explicamos as duas integrações:

Webhook: Para receber o novo webhook de chargedback é necessário que você configure o evento charge.chargedback na sessão de "Configurações"->"Webhook" no seu Dashboard. Para saber mais sobre esta configuração de webhook, clique aqui.

Consulta de Pedido/Cobranças: Essa é a alteração que pode impactar o seu sistema atual! Se você já utiliza os recursos de consultas da Pagar.me v5, você irá precisar adaptar o seu sistema para que ele entenda o que é o novo estado de chargeback em uma cobrança.

Regras do status chargedback

O estado de chargedback é o estado final da transação. Quer dizer que, depois de se tornar chargedback a transação não vai sofrer mais alterações de status de forma alguma.

O estado de chargedback só existe dentro de um cobrança (charge), ele não influencia em nenhum forma o pedido (order).

Quando uma cobrança sofre chargeback, várias operações sobre a cobrança são bloqueadas. Você não poderá:

Cancelar a cobrança;
Retentar a cobrança manualmente;
Usar retentativa offline;
Usar retentativa online;
Confirmar a cobrança em cash;
Editar método de pagamento;
Editar cartão da cobrança;
Editar data de vencimento da cobrança;
Capturar a cobrança;
Passar por retentativa.

Fluxo de Assinatura com cobranças em chargeback

No cenário de assinaturas, ao receber um chargeback de uma cobrança que está atrelada a este modelo, a nossa API irá cancelar a assinatura de forma automática. Este é um procedimento finalizador para a assinatura que impede de gerar qualquer nova fatura ou ciclo.

Para que possa cobrar novamente este cliente, será necessário criar uma nova assinatura utilizando um novo cartão. Nenhuma nova fatura/cobrança será gerada a partir desta assinatura cancelada.

Ao recebermos um chargeback em um cobrança de assinatura (subscription):

A assinatura (subscription) irá mudar para o status canceled;
A fatura (invoice) receberá o status failed;
A cobrança (charge) ficará como chargedback.

Como preparar o meu sistema para receber o novo status

Existem três mudanças especificas que podem ser realizadas para adaptar o seu sistema ao novo status.

1- Consulta de Cobrança/Pedidos (Obrigatório se integrado em GET /order ou GET /charges): É importante mapear o novo status chargedback na cobrança do nosso payload no seu sistema. Se isso não for feito, seu sistema pode não entender em qual estado a cobrança se encontra e isso gerar algum tipo de erro indevido;
2- Webhooks (opcional): Atualizar o seu sistema para receber o novo evento charge.chargedback, via webhook;
3- Assinaturas (opcional): Caso utilize a API de assinaturas (subscriptions), mapear o novo campo string status_reason:chargeback.

Exemplos:

1-Cobrança

{ "id": "ch_ZpMELzPSdwhmnL5l", "code": "M1L0ZU0C7R", "gateway_id": "16886452", "amount": 1000, "paid_amount": 1000, *** "status": "chargedback", "currency": "BRL", "payment_method": "credit_card", "paid_at": "2022-05-06T18:11:40Z", "created_at": "2022-05-06T18:11:35Z", "updated_at": "2022-05-06T18:11:40Z", "customer": { "id": "cus_1QRpXgRHXetKjgEv", "name": "Tony Stark", "email": "b0c31eee-9b22-460c-a76d-5e790d3e566a@ligadajustica.com.br", "document": "01234567890", "type": "individual", "delinquent": false, "created_at": "2022-05-06T18:11:35Z", "updated_at": "2022-05-06T18:11:35Z", "phones": { "home_phone": { "country_code": "55", "number": "22180513", "area_code": "21" } } }, "last_transaction": { "id": "tran_rNv9DDbtGjcmD9jR", "transaction_type": "credit_card", "gateway_id": "16886452", "amount": 1000, "status": "chargedback", "success": true, "installments": 1, "statement_descriptor": "AVENGERS", "acquirer_name": "pagarme", "acquirer_tid": "16886452", "acquirer_nsu": "16886452", "acquirer_auth_code": "217287", "acquirer_return_code": "0000", "operation_type": "chargeback", "card": { "id": "card_vN1RqKmFOSNYPW5a", "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": "2022-05-06T18:11:36Z", "updated_at": "2022-05-06T18:11:36Z", "billing_address": { "street": "Av. General Justo", "number": "375", "complement": "8º andar", "zip_code": "70070300", "neighborhood": "Centro", "city": "Rio de Janeiro", "state": "RJ", "country": "BR", "line_1": "375, Av. General Justo, Centro", "line_2": "8º andar" } }, "created_at": "2022-05-06T18:11:37Z", "updated_at": "2022-05-06T18:11:37Z", "gateway_response": { "code": "200", "errors": [] }, "antifraud_response": { "status": "approved", "score": "very_low", "provider_name": "pagarme" }, "metadata": {} } }

2- Webhook

{ "id": "hook_xxxxxxxxxxxxxxxx", "account": { "id": "acc_RblpWnMDfqH7dqa7", "name": "Recebimento de Chargeback - Test" }, "type": "charge.created", "created_at": "2022-05-05T14:21:48Z", "data": { "id": "ch_w8eydjNfdUpLJDKa", "code": "EG80CZ6SOR-01", "gateway_id": "16873775", "amount": 3490, "paid_amount": 3490, *** "status": "chargedback", "currency": "BRL", "payment_method": "credit_card", "due_at": "2022-05-05T23:59:59", "paid_at": "2022-05-05T14:21:50", "created_at": "2022-05-05T14:21:48", "updated_at": "2022-05-05T14:21:58", "invoice": { "id": "in_RPD9WqUKWTYO1byK", "code": "1W82A9I45W", "url": "/invoices/in_RPD9WqUKWTYO1byK", "amount": 3490, "status": "failed", "payment_method": "credit_card", "due_at": "2022-05-05T23:59:59", "created_at": "2022-05-05T14:21:47", "subscriptionId": "sub_og7OLyXDu2HRqevN", "metadata": {} }, "customer": { "id": "cus_BodWm2S7aTkVM56R", "name": "Tony Stark", "email": "c8cd2659-64ef-404d-8314-e37cbc482aa3@ligadajustica.com.br", "document": "01234567890", "type": "individual", "delinquent": false, "created_at": "2022-05-05T14:21:43", "updated_at": "2022-05-05T14:21:43", "phones": { "home_phone": { "country_code": "55", "number": "22180513", "area_code": "21" } } }, "last_transaction": { "id": "tran_v6Z8R9sP5cyj7waq", "transaction_type": "credit_card", "gateway_id": "16873775", "status": "chargedback", "success": true, "installments": 1, "acquirer_name": "pagarme", "acquirer_tid": "16873775", "acquirer_nsu": "16873775", "acquirer_return_code": "0000", "operation_type": "chargeback", "card": { "id": "card_mrV0zWrcQPSB7oB3", "first_six_digits": "492509", "last_four_digits": "9790", "brand": "Visa", "holder_name": "Tony Stark", "exp_month": 12, "exp_year": 2030, "status": "active", "type": "credit", "created_at": "2022-05-05T14:21:44", "updated_at": "2022-05-05T14:21:44", "billing_address": { "street": "Malibu Point", "number": "10880", "zip_code": "70070300", "neighborhood": "Central Malibu", "city": "Malibu", "state": "CA", "country": "US", "line_1": "10880, Malibu Point, Central Malibu" } }, "created_at": "2022-05-05T14:21:58", "updated_at": "2022-05-05T14:21:58", "gateway_response": {}, "antifraud_response": {}, "metadata": {} } } }

3-Assinatura

{ "id": "sub_RlKG5VYtGHeb4g0r", "code": "ZP51TK4T1J", "start_at": "2022-04-12T00:00:00Z", "interval": "month", "interval_count": 1, "billing_type": "prepaid", "current_cycle": { "id": "cycle_RD9qQK3tr7sYQEgz", "start_at": "2022-04-12T00:00:00Z", "end_at": "2022-05-11T23:59:59Z", "billing_at": "2022-04-12T00:00:00Z", "status": "billed", "cycle": 1 }, "next_billing_at": "2022-05-12T00:00:00Z", "payment_method": "credit_card", "currency": "BRL", "installments": 1, "status": "canceled", *** "status_reason": "chargeback", "created_at": "2022-04-12T20:50:07Z", "updated_at": "2022-04-12T20:56:50Z", "canceled_at": "2022-04-12T20:56:50Z", "customer": { "id": "cus_yxVB85JBfZsg4JpW", "name": "Tony Stark", "email": "e64668a0-9a84-43d7-9fe1-31c553e6c140@ligadajustica.com.br", "document": "01234567890", "type": "individual", "delinquent": false, "created_at": "2022-04-12T20:50:04Z", "updated_at": "2022-04-12T20:50:04Z", "phones": { "home_phone": { "country_code": "55", "number": "22180513", "area_code": "21" } } }, "card": { "id": "card_xEwBlVKikKS1MV58", "first_six_digits": "492509", "last_four_digits": "9790", "brand": "Visa", "holder_name": "Tony Stark", "exp_month": 12, "exp_year": 2030, "status": "active", "type": "credit", "created_at": "2022-04-12T20:50:06Z", "updated_at": "2022-04-12T20:50:06Z", "billing_address": { "street": "Malibu Point", "number": "10880", "zip_code": "70070300", "neighborhood": "Central Malibu", "city": "Malibu", "state": "CA", "country": "US", "line_1": "10880, Malibu Point, Central Malibu" } }, "items": [ { "id": "si_P3JD26XinHdGQZro", "name": "Premium", "description": "Sem anuncios", "quantity": 1, "status": "active", "created_at": "2022-04-12T20:50:07Z", "updated_at": "2022-04-12T20:50:07Z", "pricing_scheme": { "price": 1490, "scheme_type": "unit" } }, { "id": "si_YNaRwx8c5Oc93JvE", "name": "Silver", "description": "Com anuncios", "quantity": 1, "status": "active", "created_at": "2022-04-12T20:50:07Z", "updated_at": "2022-04-12T20:50:07Z", "pricing_scheme": { "price": 2000, "scheme_type": "unit" } } ] }

IMPORTANTE: o status novo é chargedback com uma d no meio da palavra, caso colocar o status chargeback sem a letra d, o seu sistema não vai reconhecer o novo status.

Testando

Para você testar o novo status chargedback, liberamos a funcionalidade no simulador antes do lançamento da funcionalidade, assim você consegue preparar o seu sistema para entender o novo status.

Para ver mais detalhes em como usar o simulador clique aqui

Nota: O simulador trabalha apenas com cobranças, não com assinaturas.

Perguntas frequentes

Qual é a diferença entre Pedidos (Order) e Cobranças (Charge) ?

O pedido é a forma completa de criar vendas. Ele permite que você crie vendas com informações completas de cobranças, itens, shipping, antifraude e também explore outros recursos exclusivos da API Pagar.me como multimeios, multicompradores, checkout por e-mail e split de pagamentos.

Enquanto isso, a cobrança é a apresentação de um único pagamento na API Pagar.me. Ela só pode ser gerada através de uma estrutura de um pedido ou uma de uma assinatura.

Em que data vai ser lançada o novo status?

O novo status chargedback vai ser lançado no dia 16 de Setembro, porém recomendamos fortemente que faça testes com o simulador antes da data do lançamento para ter o seu sistema preparado para tal mudança.

Se eu não preparar o meu sistema para esse novo status, o que pode acontecer?

Dependendo da configuração do seu sistema, ele pode ignorar o novo status ou até rejeita-lo, trazendo problemas operativos para o seu negócio. Por exemplo: Não deixar de enviar algum tipo de produto que sofreu chargeback, não conseguir fazer a contestação a tempo ou ter informação não congruente no seu banco de dados sobre os pedidos feitos, trazendo problemas no relatório de vendes, fechamento de mês, etc.

Não quero receber esse novo status de chargedback na cobrança, é possível?

O status novo será implementado a nível de API, por isso, toda cobrança vai obrigatoriamente, receber esse novo status caso sofra um chargeback.

Você pode optar por não assinar o novo webhook, dessa forma não irá receber a mudança ativamente da nossa API para o seu sistema.

Se eu faço o gerenciamento do meus pedidos a través de Orders (Pedidos) e não das charges (Cobranças), como eu vou saber que um pedido sofreu chargeback?

Para saber se o seu pedido sofreu chargeback será necessário conferir o status da cobrança (não do pedido). Para isso, basta configurar o webhook charge.chargeback, que é disparado cada vez que uma cobrança recebe um chargeback.

No caso da assinatura, se ela foi cancelada como vou saber que foi por ter sofrido chargeback?

Para lidar com os casos de cancelamento de assinatura por chargeback criamos um campo novo, o status_reason:chargeback.Dessa forma você vai saber o motivo do cancelamento da sua assinatura.

Nota: O status_reason só notifica o cancelamento da assinatura por chargeback, qualquer outro motivo de cancelamento não é especificado pois é realizado pelo lado do cliente.

Artigos sugeridos da base de conhecimento: