Gestão de Chargebacks

Em casos que haja alguma contestação de alguma cobrança via cartão de crédito, seja ela avulsa ou recorrente, a Celcoin disponibiliza todo o suporte para que você possa gerir esse fluxo, desde o recebimento que alguma cobrança teve contestação até a resolução da mesma.. Abaixo iremos explicar como se integrar com esse módulo do BaaS.

Caso de uso:

Como Fintech quero antecipar meu recebível de cartão de crédito para melhorar meu fluxo de caixa.

Nesse artigo você irá aprender sobre:

Cadastrar webhook para receber eventos de chargebacks
Enviar documentação de defesa dos chargebacks
Desistir da disputa dos chargebacks
Listar Chargebacks

Pré requisitos para implementação:

Possuir uma chave api da Celcoin, para mais informações acessar esse link
Ter familiaridade com apis Rest usando o protocolo OAuth 2.0.
Ter o produto/solução de sub Celcoin contratado, caso queira usar a funcionalidade em ambiente produtivo, por favor entre em contato com a nossa equipe comercial através do e-mail [email protected]. Para dúvidas técnicas, basta entrar em contato com o suporte através do link.

Cadastro de Webhooks

Para receber informações das contestações realizadas pelos clientes, é necessário cadastrar um webhook para receber as atualizações referentes ao chargeback.

Para cadastrar um webhook, é necessário realizar uma chamada na api Cadastrar Webhook Chargeback utilizando o método PUT, onde precisa ser preenchido algumas informações, como URL e o evento relacionado. Os dados necessários estão no quadro "Parâmetros do Body"

Modelo de requisição:

curl --location --request PUT 'https://sandbox.openfinance.celcoin.dev/baas/v1/cash/webhooks' \
--header 'accept: application/json' \
--header 'Authorization: Bearer acess_token' \
--header 'Content-Type: application/json' \
--data-raw '{
    "url": "https://website.com.br/webhook-celcoin-sub",
    "events": [
        "chargeback.update"
    ]
}
'

Parâmetros do Body:

Campo	Descrição	Tipo
url	URL do Webhook.	String (255)
events	Array de eventos a serem ativados. Valores possíveis: chargeback.update Será enviado quando uma abertura de disputa for criada no sistema. Vai conter todos os dados da entidade Chargeback, além de conter alguns dados da entidade Transaction e PaymentBill.	Array String

Campo

Descrição

Tipo

url

URL do Webhook.

String (255)

events

Array de eventos a serem ativados. Valores possíveis:

chargeback.update
Será enviado quando uma abertura de disputa for criada no sistema. Vai conter todos os dados da entidade Chargeback, além de conter alguns dados da entidade Transaction e PaymentBill.

Array String

Modelo de retorno: necessário validar retorno de sucesso

{
    "type": true,
    "confirmHash": "19b3e0a42152d126cbe1512022714a8b",
    "events": [
        "chargeback.update"
    ]
}

Note que essa api é síncrona, sendo assim, a Celcoin irá retornar para você o resultado final da solicitação de cadastro da empresa.

Tabela descritiva dos campos retornados

Campo	Descrição	Tipo
type	Retorna se simulação foi realizada com sucesso. Valores possíveis: True ou False	Bool
confirmHash	Hash de confirmação de segurança do webhook.	String (255)
events	Array de eventos que foram ativados.	Array String

Enviar Documentação de Defesa do Chargeback

Caso você tenha uma contestação em aberto, você pode enviar os documentos de defesa do chargeback.. Para isso, é necessário realizar uma chamada na api Enviar Documentação utilizando o método PUT.

Modelo de request:

curl --location --request PUT 'https://sandbox.openfinance.celcoin.dev/baas/v1/cash/chargebacks/{chargebackGalaxPayId}
--header 'accept: application/json' \
--header 'Authorization: Bearer acess_token' \
--header 'Content-Type: application/json' \
--data-raw '{
    {
    "files": [
        "File 01 encoded in base64",
        "File 02 encoded in base64"
    ]
}
}
'

Modelo de retorno:

{
    "type": true
}

Tabela descritiva dos campos

Campo	Descrição	Tipo
chargebackGalaxPayId	Identificador do chargeback
files	Documentos para contestação de disputa codificados em base64
type	Retorna se simulação foi realizada com sucesso. Valores possíveis: True ou False	Bool

Desistir da Disputa dos Chargeback

Caso queira desistir da disputa do chargeback , você deve realizar uma chamada na API Desistir da Disputa do Chargeback utilizando o método PUT

Modelo de requisição:

curl --location --request PUT 'https://sandbox.openfinance.celcoin.dev/baas/v1/cash/chargebacks/lose/{chargebackGalaxPayId}' \

Parâmetros do Body:

Campo	Descrição	Tipo
chargebackGalaxPayId	Identificador do chargeback

Modelo de retorno:

{
    "type": true
}

Tabela descritiva dos campos retornados

Campo	Descrição	Tipo
type	Retorna se simulação foi realizada com sucesso. Valores possíveis: True ou False	Bool

Listar Chargebacks

Caso necessite validar o status dos chargebacks, você deve realizar uma chamada na API Listar Chargebacks utilizando o método GET

Modelo de requisição:

curl --location --request GET 'https://sandbox.openfinance.celcoin.dev/baas/v1/cash/chargebacks' \

Parâmetros do Body:

Campo	Descrição	Tipo
limit	Quantidade de dados retornados	int
startAt	A partir de que posição da query irá pegar os dados	int
status	Status do chargeback. Separe cada valor por vírgula. Valores possíveis: -awaitingDocumentation: A disputa de chargeback está aguardando a documentação ser enviada. -lostDispute: A disputa de chargeback foi perdida. -winsDispute: A disputa de chargeback foi ganha. -inAnalysis: A disputa de chargeback está em análise pelo Galax Pay. -canceledDispute: A disputa de chargeback foi cancelada.	string
process	Número do processo do chargeback. Separe cada valor por vírgula.	string
chargeGalaxPayIds	Charge.galaxPayId. Id da cobrança avulsa no Galax Pay. Separe cada id por vírgula.	string
chargeMyIds	Id da cobrança avulsa no seu sistema. Separe cada id por vírgula.	string
transactionGalaxPayIds	Id da transação no Galax Pay. Separe cada id por vírgula.	string
createdAtFrom	Data de criação inicial do Chargeback	date
createdAtTo	Data de criação final do Chargeback	date
expiryDateFrom	data inicial até o limite de envio de documentação.	date
expiryDateTo	data final até o limite de envio de documentação.	date
sendDocumentFrom	Data inicial que o documento foi enviado.	date
sendDocumentTo	Data final que o documento foi enviado.	date

📘
Note que todos os dados podem ser filtrados

📘
Você pode filtrar todos os dados ou somente o campo que desejar.

Modelo de retorno:

{
    "totalQtdFoundInPage": 1,
    "Chargebacks": [
        {
            "galaxPayId": 47,
            "createdAt": "2023-11-21 15:33:55",
            "expire": "2023-11-25 00:00:00",
            "process": "4913850291284",
            "value": 300,
            "status": "inAnalysis",
            "description": "chargeback description",
            "DocumentsChargeback": {
                "createdAt": "2023-11-22 15:33:55"
            },
            "Transaction": {
                "galaxPayId": 475,
                "myId": "TRANSACTION-MYID-475"
            },
            "PaymentBill": {
                "galaxPayId": 216,
                "myId": "CHARGE-MYID-216"
            }
        }
    ]
}

Tabela descritiva dos campos retornados

Campo	Descrição	Tipo
totalQtdFoundInPage	Quantidade total de registros do retorno da busca na página atual.	int
chargebacks.galaxPayId	Identificador da antecipação	int (11)
chargebacks.createdAt	Data de criação.	date
chargebacks.expire	data até o limite de envio de documentação.	date
chargebacks.process	Número do processo do chargeback. Separe cada valor por vírgula.	string (37)
chargebacks.value	Valor do chargeback.	int
chargebacks.status	Status do chargeback. Separe cada valor por vírgula. Valores possíveis: -awaitingDocumentation: A disputa de chargeback está aguardando a documentação ser enviada. -lostDispute: A disputa de chargeback foi perdida. -winsDispute: A disputa de chargeback foi ganha. -inAnalysis: A disputa de chargeback está em análise pelo Galax Pay. -canceledDispute: A disputa de chargeback foi cancelada.	String (255)
chargebacks.description	Descrição do chargeback.	String (255)
chargebacks.DocumentsChargeback.createdAt	Objeto da documentação de chargeback. Data da Criação	date
chargebacks.transaction.galaxPayId	Identificador da Transação	int (11
chargebacks.transaction.myId	Identificador da transação no seu sistema	String (255)
chargeback.paymentBill.galaxPayId	Identificador da cobrança avulsa	int (11)
chargeback.paymentBill.myId	Identificador da transação no seu sistema	String (255)

Updated 6 days ago