Inclusão de novo status de chargeback nas cobranças da API v5

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

Esta nova funcionalidade será implementada a partir do dia 12 de Setembro de 2022.

📘
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 Chargeback será mostrada na pagina de cobranças dentro do seu portal transacional Pagar.me.

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 charge 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.

🚧
Pedidos e o Status Chargeback
O estado de chargedback só existe dentro de um cobrança (objeto charge), ele não influencia em nenhuma forma o estado de um pedido (objeto order).
Por exemplo, ao receber um chargeback, somente o campo status da charge irá mudar, o campo status da order não irá mudar.

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 à este modelo, a nossa API irá cancelar a assinatura de forma automática, esse é 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. (opcional)
3- Assinaturas (opcional): Caso utilize a API de assinaturas (subscriptions), mapear o novo campo string status_reason:chargeback

Exemplos:

{
    "id": "or_RM7paKE7FJfZDWPm",
    "code": "9NX8T3IXK7",
    "amount": 3090,
    "currency": "BRL",
    "closed": true,
    "items": [
        {
            "id": "oi_rVlB9VaCRWu8wy2a",
            "type": "product",
            "description": "Chaveiro do Tesseract",
            "amount": 2990,
            "quantity": 1,
            "status": "active",
            "created_at": "2022-08-30T13:27:25Z",
            "updated_at": "2022-08-30T13:27:25Z",
            "code": "123"
        }
    ],
    "customer": {
        "id": "cus_Rr1dD3PUdUbyWkOw",
        "name": "Tony Stark",
        "email": "[email protected]",
        "document": "03154435026",
        "document_type": "cpf",
        "type": "individual",
        "delinquent": false,
        "address": {
            "id": "addr_7xmOnbas8sL68AqQ",
            "line_1": "375, Av. General Justo, Centro",
            "line_2": "8º andar",
            "zip_code": "20021130",
            "city": "Rio de Janeiro",
            "state": "RJ",
            "country": "BR",
            "status": "active",
            "created_at": "2022-05-03T17:27:55Z",
            "updated_at": "2022-05-03T18:10:58Z"
        },
        "created_at": "2022-05-03T17:27:55Z",
        "updated_at": "2022-07-22T15:50:58Z",
        "phones": {}
    },
    "shipping": {
        "amount": 100,
        "description": "Stark",
        "recipient_name": "Tony Stark",
        "recipient_phone": "24586787867",
        "address": {
            "city": "Malibu",
            "state": "CA",
            "country": "US",
            "zip_code": "90265",
            "line_1": "10880, Malibu Point, Malibu Central"
        }
    },
    "status": "paid",
    "created_at": "2022-08-30T13:27:25Z",
    "updated_at": "2022-08-30T13:27:26Z",
    "closed_at": "2022-08-30T13:27:25Z",
    "location": {
        "latitude": "-22.970722",
        "longitude": "43.182365"
    },
    "charges": [
        {
            "id": "ch_3bLDOGOS1NcaD0KQ",
            "code": "9NX8T3IXK7",
            "amount": 3090,
            "paid_amount": 3090,
            "status": "chargedback", // Novo status Chargeback
            "currency": "BRL",
            "payment_method": "credit_card",
            "paid_at": "2022-08-30T13:27:26Z",
            "created_at": "2022-08-30T13:27:25Z",
            "updated_at": "2022-08-30T13:27:29Z",
            "customer": {
                "id": "cus_Rr1dD3PUdUbyWkOw",
                "name": "Tony Stark",
                "email": "[email protected]",
                "document": "03154435026",
                "document_type": "cpf",
                "type": "individual",
                "delinquent": false,
                "address": {
                    "id": "addr_7xmOnbas8sL68AqQ",
                    "line_1": "375, Av. General Justo, Centro",
                    "line_2": "8º andar",
                    "zip_code": "20021130",
                    "city": "Rio de Janeiro",
                    "state": "RJ",
                    "country": "BR",
                    "status": "active",
                    "created_at": "2022-05-03T17:27:55Z",
                    "updated_at": "2022-05-03T18:10:58Z"
                },
                "created_at": "2022-05-03T17:27:55Z",
                "updated_at": "2022-07-22T15:50:58Z",
                "phones": {}
            },
            "last_transaction": {
                "id": "tran_7xj3zXpf1cKozmWk",
                "transaction_type": "credit_card",
                "gateway_id": "bf59b6c7-cb49-4480-8923-593c4fe5e7f6",
                "amount": 3090,
                "status": "chargedback", // Novo status Chargeback
                "success": true,
                "installments": 1,
                "statement_descriptor": "AVENGERS",
                "acquirer_name": "simulator",
                "acquirer_tid": "39688692167257",
                "acquirer_nsu": "73236",
                "acquirer_auth_code": "27",
                "acquirer_message": "A transação foi contestada",
                "acquirer_return_code": "00",
                "operation_type": "chargeback",
                "card": {
                    "id": "card_DLRKab2IRbtMaqmE",
                    "first_six_digits": "400000",
                    "last_four_digits": "0069",
                    "brand": "Visa",
                    "holder_name": "Tony Stark",
                    "exp_month": 1,
                    "exp_year": 2025,
                    "status": "active",
                    "type": "credit",
                    "created_at": "2022-07-22T15:50:59Z",
                    "updated_at": "2022-07-22T15:50:59Z",
                    "billing_address": {
                        "zip_code": "90265",
                        "city": "Malibu",
                        "state": "CA",
                        "country": "US",
                        "line_1": "10880, Malibu Point, Malibu Central"
                    }
                },
                "created_at": "2022-08-30T13:27:28Z",
                "updated_at": "2022-08-30T13:27:28Z",
                "gateway_response": {},
                "antifraud_response": {},
                "metadata": {}
            },
            "metadata": {
                "meu_campo1": "valor1",
                "meu_campo2": "valor2"
            }
        }
    ],
    "checkouts": [],
    "metadata": {
        "meu_campo1": "valor1",
        "meu_campo2": "valor2"
    }
}

{
    "id": "ch_3bLDOGOS1NcaD0KQ",
    "code": "9NX8T3IXK7",
    "amount": 3090,
    "paid_amount": 3090,
    "status": "chargedback", // Novo status Chargeback
    "currency": "BRL",
    "payment_method": "credit_card",
    "paid_at": "2022-08-30T13:27:26Z",
    "created_at": "2022-08-30T13:27:25Z",
    "updated_at": "2022-08-30T13:27:29Z",
    "order": {
        "id": "or_RM7paKE7FJfZDWPm",
        "code": "9NX8T3IXK7",
        "amount": 3090,
        "closed": true,
        "created_at": "2022-08-30T13:27:25Z",
        "updated_at": "2022-08-30T13:27:26Z",
        "closed_at": "2022-08-30T13:27:25Z",
        "currency": "BRL",
        "status": "paid",
        "customer_id": "cus_Rr1dD3PUdUbyWkOw",
        "metadata": {
            "meu_campo1": "valor1",
            "meu_campo2": "valor2"
        }
    },
    "customer": {
        "id": "cus_Rr1dD3PUdUbyWkOw",
        "name": "Tony Stark",
        "email": "[email protected]",
        "document": "03154435026",
        "document_type": "cpf",
        "type": "individual",
        "delinquent": false,
        "address": {
            "id": "addr_7xmOnbas8sL68AqQ",
            "line_1": "375, Av. General Justo, Centro",
            "line_2": "8º andar",
            "zip_code": "20021130",
            "city": "Rio de Janeiro",
            "state": "RJ",
            "country": "BR",
            "status": "active",
            "created_at": "2022-05-03T17:27:55Z",
            "updated_at": "2022-05-03T18:10:58Z"
        },
        "created_at": "2022-05-03T17:27:55Z",
        "updated_at": "2022-07-22T15:50:58Z",
        "phones": {}
    },
    "last_transaction": {
        "id": "tran_7xj3zXpf1cKozmWk",
        "transaction_type": "credit_card",
        "gateway_id": "bf59b6c7-cb49-4480-8923-593c4fe5e7f6",
        "amount": 3090,
        "status": "chargedback", // Novo status Chargeback
        "success": true,
        "installments": 1,
        "statement_descriptor": "AVENGERS",
        "acquirer_name": "simulator",
        "acquirer_tid": "39688692167257",
        "acquirer_nsu": "73236",
        "acquirer_auth_code": "27",
        "acquirer_message": "A transação foi contestada",
        "acquirer_return_code": "00",
        "operation_type": "chargeback",
        "card": {
            "id": "card_DLRKab2IRbtMaqmE",
            "first_six_digits": "400000",
            "last_four_digits": "0069",
            "brand": "Visa",
            "holder_name": "Tony Stark",
            "exp_month": 1,
            "exp_year": 2025,
            "status": "active",
            "type": "credit",
            "created_at": "2022-07-22T15:50:59Z",
            "updated_at": "2022-07-22T15:50:59Z",
            "billing_address": {
                "zip_code": "90265",
                "city": "Malibu",
                "state": "CA",
                "country": "US",
                "line_1": "10880, Malibu Point, Malibu Central"
            }
        },
        "created_at": "2022-08-30T13:27:28Z",
        "updated_at": "2022-08-30T13:27:28Z",
        "gateway_response": {},
        "antifraud_response": {},
        "metadata": {}
    },
    "metadata": {
        "meu_campo1": "valor1",
        "meu_campo2": "valor2"
    }
}

{
    "id": "hook_XdPmQbO7T5UpZo1A",
    "account": {
        "id": "acc_jab0WOEtkfV30ogJ",
        "name": "Mark 1 + Simulador"
    },
    "type": "charge.chargedback", // Novo webhook referente ao status Chargeback
    "created_at": "2022-08-30T13:29:27Z",
    "data": {
        "id": "ch_w3oN9YVsJbfr7NM1",
        "code": "R7NPFXA3OW-01",
        "amount": 26978,
        "paid_amount": 26978,
        "status": "chargedback", // Novo status Chargeback
        "currency": "BRL",
        "payment_method": "credit_card",
        "due_at": "2022-08-30T23:59:59",
        "paid_at": "2022-08-30T13:29:25",
        "created_at": "2022-08-30T13:29:25",
        "updated_at": "2022-08-30T13:29:27",
        "invoice": {
            "id": "in_mByOgWcvYcoDObNe",
            "code": "NZ3WAG2ILZ",
            "url": "/invoices/in_mByOgWcvYcoDObNe",
            "amount": 26978,
            "status": "failed",
            "payment_method": "credit_card",
            "installments": 3,
            "due_at": "2022-08-30T23:59:59",
            "created_at": "2022-08-30T13:29:25",
            "subscriptionId": "sub_Lm0DbReSoI0nw4eB",
            "metadata": {}
        },
        "customer": {
            "id": "cus_DwWxXKdyuLtw3enN",
            "name": "Tony Stark",
            "email": "[email protected]",
            "document": "28619068040",
            "type": "individual",
            "delinquent": false,
            "address": {
                "id": "addr_KjDlX7rCaSKBVdNQ",
                "line_1": "375, Av. General Justo, Centro",
                "line_2": "8º andar",
                "zip_code": "80070300",
                "city": "Rio de Janeiro",
                "state": "RJ",
                "country": "BR",
                "status": "active",
                "created_at": "2022-05-04T11:52:35",
                "updated_at": "2022-05-04T11:52:35"
            },
            "created_at": "2022-05-04T11:18:41",
            "updated_at": "2022-05-04T11:52:35",
            "phones": {}
        },
        "last_transaction": {
            "id": "tran_1b2yXn7S0QcK6vOJ",
            "transaction_type": "credit_card",
            "gateway_id": "9ab29f2a-80ff-4c49-b731-9f28ce552d16",
            "amount": 26978,
            "status": "chargedback",  // Novo status Chargeback
            "success": true,
            "installments": 3,
            "acquirer_name": "simulator",
            "acquirer_tid": "27624544514169",
            "acquirer_nsu": "60477",
            "acquirer_auth_code": "498",
            "acquirer_message": "A transação foi contestada",
            "acquirer_return_code": "00",
            "operation_type": "chargeback",
            "card": {
                "id": "card_eMDzW6QtNczxX3l6",
                "first_six_digits": "400000",
                "last_four_digits": "0069",
                "brand": "Visa",
                "holder_name": "Tony Stark",
                "exp_month": 1,
                "exp_year": 2030,
                "status": "active",
                "type": "credit",
                "created_at": "2022-08-30T13:29:25",
                "updated_at": "2022-08-30T13:29:25",
                "billing_address": {
                    "zip_code": "20021130",
                    "city": "Rio de Janeiro",
                    "state": "RJ",
                    "country": "BR",
                    "line_1": "375, Av. General Justo, Centro",
                    "line_2": "8º andar"
                }
            },
            "created_at": "2022-08-30T13:29:27",
            "updated_at": "2022-08-30T13:29:27",
            "gateway_response": {},
            "antifraud_response": {},
            "metadata": {}
        },
        "metadata": {
            "id": "my_subscription_id"
        }
    }
}

{
    "id": "sub_Lm0DbReSoI0nw4eB",
    "code": "R7NPFXA3OW",
    "start_at": "2022-08-30T00:00:00Z",
    "interval": "month",
    "interval_count": 3,
    "billing_type": "prepaid",
    "current_cycle": {
        "id": "cycle_kMoBzL5WuyuBOdL6",
        "start_at": "2022-08-30T00:00:00Z",
        "end_at": "2022-11-29T23:59:59Z",
        "billing_at": "2022-08-30T00:00:00Z",
        "status": "billed",
        "cycle": 1
    },
    "next_billing_at": "2022-11-30T00:00:00Z",
    "payment_method": "credit_card",
    "currency": "BRL",
    "installments": 3,
    "minimum_price": 10000,
    "status": "canceled",
    "status_reason": "chargeback",  // Novo status Chargeback
    "created_at": "2022-08-30T13:29:25Z",
    "updated_at": "2022-08-30T13:29:28Z",
    "canceled_at": "2022-08-30T13:29:28Z",
    "customer": {
        "id": "cus_DwWxXKdyuLtw3enN",
        "name": "Tony Stark",
        "email": "[email protected]",
        "document": "28619068040",
        "type": "individual",
        "delinquent": false,
        "created_at": "2022-05-04T11:18:41Z",
        "updated_at": "2022-05-04T11:52:35Z",
        "phones": {}
    },
    "card": {
        "id": "card_eMDzW6QtNczxX3l6",
        "first_six_digits": "400000",
        "last_four_digits": "0069",
        "brand": "Visa",
        "holder_name": "Tony Stark",
        "exp_month": 1,
        "exp_year": 2030,
        "status": "active",
        "type": "credit",
        "created_at": "2022-08-30T13:29:25Z",
        "updated_at": "2022-08-30T13:29:25Z",
        "billing_address": {
            "zip_code": "20021130",
            "city": "Rio de Janeiro",
            "state": "RJ",
            "country": "BR",
            "line_1": "375, Av. General Justo, Centro",
            "line_2": "8º andar"
        }
    },
    "discounts": [
        {
            "id": "dis_DO0j9KptmgSpvVkm",
            "value": 10.00,
            "discount_type": "percentage",
            "cycles": 3,
            "status": "active",
            "created_at": "2022-08-30T13:29:25Z"
        }
    ],
    "increments": [
        {
            "id": "inc_PwJXZQNCkC3QgrZQ",
            "value": 20.00,
            "increment_type": "percentage",
            "cycles": 2,
            "status": "active",
            "created_at": "2022-08-30T13:29:25Z"
        }
    ],
    "items": [
        {
            "id": "si_KW96DVc27S3DbJjw",
            "description": "Musculação",
            "quantity": 1,
            "status": "active",
            "created_at": "2022-08-30T13:29:25Z",
            "updated_at": "2022-08-30T13:29:25Z",
            "pricing_scheme": {
                "price": 18990,
                "scheme_type": "unit"
            }
        },
        {
            "id": "si_dl0pov2UN0HJlyGP",
            "description": "Matrícula",
            "cycles": 1,
            "quantity": 1,
            "status": "active",
            "created_at": "2022-08-30T13:29:25Z",
            "updated_at": "2022-08-30T13:29:25Z",
            "pricing_scheme": {
                "price": 5990,
                "scheme_type": "unit"
            }
        }
    ],
    "metadata": {
        "id": "my_subscription_id"
    }
}

📘
IMPORTANTE: o status novo é chargedback com um "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

Observação: 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, split de pagamentos.

Enquanto 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.

Que data vai ser lançada o novo status?

O novo status chargedback vai ser lançado no dia 12 de Setembro, porém recomendamos fortemente a realização de 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é rejeitá-lo, trazendo problemas operacionais para o seu negócio.
Por exemplo: Não barrar o envio de algum 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 vendas e fechamento de mês.

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 o novo status caso sofra um chargeback.

Você pode optar por não assinar o novo webhook de evento charge.chargedback. Dessa forma, você não irá receber ativamente de nossa API a mudança do status da cobrança.

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ê saberá o motivo do cancelamento da sua assinatura.

📘
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.

Links de ajuda:

Status da cobrança - https://docs.pagar.me/reference#cobran%C3%A7as-1
Webhook - https://docs.pagar.me/reference#eventos-de-webhook-1
Simulador - https://docs.pagar.me/docs/simulador-de-cart%C3%A3o-de-cr%C3%A9dito

Chargeback - Novo status na Cobrança

Inclusão de novo status de chargeback nas cobranças da API v5

📘

O que irá mudar?

Regras do status chargedback

🚧
Pedidos e o Status Chargeback

Fluxo de Assinatura com cobranças em chargeback

Como preparar o meu sistema para receber o novo status

📘

Testando

Perguntas frequentes

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

Que data vai ser lançada o novo status?

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

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

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?

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

📘

Links de ajuda:

Inclusão de novo status de chargeback nas cobranças da API v5

📘

O que irá mudar?

Regras do status chargedback

🚧Pedidos e o Status Chargeback

Fluxo de Assinatura com cobranças em chargeback

Como preparar o meu sistema para receber o novo status

📘

Testando

Perguntas frequentes

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

Que data vai ser lançada o novo status?

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

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

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?

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

📘

Links de ajuda:

🚧
Pedidos e o Status Chargeback