API de Reembolsos

🤖 Explicar com IA

A API de Reembolsos é uma ferramenta que permite às empresas iniciar e gerenciar reembolsos de transações feitas através de seu sistema de processamento de pagamentos. Quando um cliente solicita um reembolso, a API de Reembolsos permite que a empresa processe o reembolso de forma rápida e fácil, sem a necessidade de lidar manualmente com o processo.

Esta API gerencia a comunicação com o processador de pagamentos para garantir que o reembolso seja processado corretamente e em conformidade com as regulamentações relevantes.

Criar um reembolso¶

Endpoint

POST /v1/refunds/

Cria um reembolso para uma cobrança específica. Você pode opcionalmente especificar um valor para reembolsos parciais. Se nenhum valor for fornecido, o valor total da cobrança será reembolsado.

Requisitos

A cobrança deve existir no sistema.
A cobrança não deve ter sido totalmente reembolsada anteriormente.
Para cobranças de produção (live): a cobrança não deve ter sido paga à sua conta ainda.

Campos:

Parâmetro	Descrição	Tipo	Obrigatório
charge_id	O ID da cobrança	string	true
amount	Valor a reembolsar (reembolso parcial). Se omitido, o reembolso total é processado	decimal	false
reason	`duplicate`, `fraudulent` ou `requested_by_customer`	string	true
test	Indica se o reembolso está no modo de teste (true para teste, false para produção).	boolean	false

Solicitação (Reembolso Total):

curl -X POST 'https://api.4geeks.io/v1/refunds/' \
     -u 'sk_test_51O62xYzAbcDef123:' \
     -H 'Content-Type: application/json' \
     -d '{
           "charge_id": "1BSt6hCqnAMAMqhvMGiBxOWe",
           "reason": "requested_by_customer"
         }'

Solicitação (Reembolso Parcial):

curl -X POST 'https://api.4geeks.io/v1/refunds/' \
     -u 'sk_test_51O62xYzAbcDef123:' \
     -H 'Content-Type: application/json' \
     -d '{
           "charge_id": "1BSt6hCqnAMAMqhvMGiBxOWe",
           "amount": 10.50,
           "reason": "requested_by_customer"
         }'

Resposta (Reembolso Total - 201 Created):

{
    "id": "1BiPhgCqnAMsdzqhvCTntF7aD",
    "provider_refund_id": "re_1ABC123XYZ456",
    "charge_id": "1BSt6hCqnAMAMqhvMGiBxOWe",
    "amount": "100.00",
    "currency": "usd",
    "reason": "requested_by_customer",
    "status": "succeeded",
    "test": true,
    "created_at": "2025-12-04T15:30:00Z"
}

Resposta (Reembolso Parcial - 201 Created):

{
    "id": "1BiPhgCqnAMsdzqhvCTntF7aD",
    "provider_refund_id": "re_1ABC123XYZ456",
    "charge_id": "1BSt6hCqnAMAMqhvMGiBxOWe",
    "amount": "10.50",
    "currency": "usd",
    "reason": "requested_by_customer",
    "status": "succeeded",
    "test": true,
    "created_at": "2025-12-04T15:30:00Z"
}

Obter um reembolso¶

Endpoint

GET /v1/refunds/{refund_id}/

Este endpoint retorna um objeto de reembolso específico através do seu ID.

Parâmetros de Caminho (Path Parameters):

Parâmetro	Descrição	Tipo	Obrigatório
refund_id	O ID do reembolso (sem o prefixo ‘re_’)	string	true

Solicitação:

curl -X GET 'https://api.4geeks.io/v1/refunds/1BiPhgCqnAMsdzqhvCTntF7aD/' \
     -u 'sk_test_51O62xYzAbcDef123:'

Resposta (200 OK):

{
    "id": "1BiPhgCqnAMsdzqhvCTntF7aD",
    "provider_refund_id": "re_1ABC123XYZ456",
    "charge_id": "1BSt6hCqnAMAMqhvMGiBxOWe",
    "amount": "10.00",
    "currency": "usd",
    "reason": "duplicate",
    "status": "succeeded",
    "test": true,
    "created_at": "2025-12-04T14:20:00Z"
}

Listar reembolsos¶

Endpoint

GET /v1/refunds/

Este endpoint retorna todos os reembolsos da sua conta. Você pode filtrar por charge_id usando parâmetros de consulta.

Parâmetros de Consulta (Query Parameters):

Parâmetro	Descrição	Tipo	Obrigatório
charge_id	Filtrar reembolsos por um ID de cobrança específico (opcional)	string	false
test	Indica se está filtrando reembolsos do modo de teste	boolean	false

Solicitação (Listar Todos os Reembolsos):

curl -X GET 'https://api.4geeks.io/v1/refunds/' \
     -u 'sk_test_51O62xYzAbcDef123:'

Solicitação (Filtrar por ID de Cobrança):

curl -X GET 'https://api.4geeks.io/v1/refunds/?charge_id=1BSt6hCqnAMAMqhvMGiBxOWe' \
     -u 'sk_test_51O62xYzAbcDef123:'

Resposta (200 OK):

[
    {
        "id": "1BiOrQCqNertMqhvvUMhJajE",
        "provider_refund_id": "re_1XYZ123ABC456",
        "charge_id": "1BSt5sCqnAMAMqhvd871C1Vl",
        "amount": "10.00",
        "currency": "usd",
        "reason": "duplicate",
        "status": "succeeded",
        "test": true,
        "created_at": "2025-12-03T10:15:00Z"
    },
    {
        "id": "1BiPDoCqnNerAMqhvSzxyFXl2",
        "provider_refund_id": "re_2ABC456XYZ789",
        "charge_id": "1BSt5sCqnAMAMqhvd871C1Vl",
        "amount": "40.00",
        "currency": "usd",
        "reason": "fraudulent",
        "status": "succeeded",
        "test": true,
        "created_at": "2025-12-02T16:45:00Z"
    }
]

Tratamento de Erros¶

A API retorna códigos de status HTTP padrão para indicar o sucesso ou a falha de uma solicitação. Abaixo estão erros comuns específicos para reembolsos:

400 Bad Request (Solicitação Inválida)¶

Ocorre quando faltam campos obrigatórios na solicitação ou quando ela contém dados inválidos.

Cenários:

Cenário	Mensagem de Erro	Solução
charge_id ausente	`"Charge object doesn't exist."`	Verifique se o charge_id está correto e existe
Reembolso parcial excede o valor da cobrança	`"The amount provided is greater than the amount of the payment."`	Reduza o valor do reembolso para ser menor ou igual à cobrança
Cobrança já totalmente reembolsada	`"Charge requested is already refunded"`	Verifique se a cobrança já não foi reembolsada anteriormente
Campo reason ausente	`"reason field is required"`	Inclua um motivo válido: `duplicate`, `fraudulent` ou `requested_by_customer`

Exemplo de Resposta de Erro:

{
    "code": 400,
    "title": "Refund error",
    "content": "The amount provided is greater than the amount of the payment.",
    "type": "danger"
}

401 Unauthorized (Não Autorizado)¶

Falha na autenticação. A Chave de API é inválida, está ausente ou malformada.

Exemplo:

{
    "detail": "Authentication credentials were not provided."
}

Solução:

Verifique se você incluiu o cabeçalho Authorization: Basic <base64_key> ou usou -u no cURL.
Certifique-se de que sua Chave de API está correta e ativa.
Teste com o Postman para depurar.

404 Not Found (Não Encontrado)¶

A cobrança ou o reembolso solicitado não existe.

Exemplo:

{
    "detail": "Refund doesn't exist in your list."
}

Solução:

Verifique se o charge_id ou refund_id existe.
Verifique se você está usando o formato de ID correto (sem prefixos como ch_ ou re_).
Certifique-se de que a cobrança pertence à sua conta de desenvolvedor.

409 Conflict (Conflito)¶

A cobrança já foi paga à sua conta e não pode ser reembolsada.

Exemplo:

{
    "code": 400,
    "title": "Charge status error",
    "content": "The charge requested is already paid to your account.",
    "type": "danger"
}

Solução:

Reembolsos só são possíveis antes que as cobranças sejam depositadas em sua conta bancária.
Entre em contato com o suporte se precisar de assistência com cobranças já pagas.

Motivos de Reembolso¶

Ao criar um reembolso, você deve especificar um dos seguintes motivos:

Motivo	Caso de Uso
`duplicate`	A cobrança foi duplicada ou processada duas vezes
`fraudulent`	A cobrança foi fraudulenta ou não autorizada
`requested_by_customer`	O cliente solicitou um reembolso

Melhores Práticas¶

Sempre especifique um motivo - Isso ajuda no rastreamento e na resolução de disputas.
Use reembolsos parciais quando possível - Se estiver processando uma correção, use reembolsos parciais em vez de totais.
Processe reembolsos prontamente - Os reembolsos têm maior probabilidade de sucesso se iniciados logo após a cobrança.
Verifique antes de reembolsar - Verifique se a cobrança pertence à sua conta e se ainda não foi paga.
Monitore o status do reembolso - Use o endpoint GET para verificar a conclusão do reembolso.
Trate os erros com elegância - Implemente um tratamento de erros adequado para cenários comuns.

Solução de Problemas¶

Problema: “Charge object doesn’t exist”¶

Causa: O charge_id fornecido não corresponde a nenhuma cobrança no sistema.
Solução:

Verifique o formato do charge_id (remova o prefixo ‘ch_’ se estiver incluído).
Confirme se a cobrança pertence à sua conta de desenvolvedor.
Use a API de Pagamentos para listar todas as cobranças e encontrar o ID correto.

Problema: “Charge requested is already refunded”¶

Causa: Já foi processado um reembolso total para esta cobrança.
Solução:

Verifique se um reembolso já foi criado usando GET /v1/refunds/?charge_id=xxx.
Se você precisar de reembolsos adicionais, processe-os antes do reembolso total inicial.

Problema: “The charge requested is already paid to your account”¶

Causa: A cobrança já foi depositada em sua conta bancária.
Solução:

Reembolsos só podem ser processados antes do repasse (payout).
Entre em contato com o suporte para cobranças que já foram pagas.

FAQ (Perguntas Frequentes)¶

P: Posso reembolsar um valor parcial de uma cobrança?
R: Sim, especifique o parâmetro amount na solicitação. O valor da cobrança será reduzido adequadamente.

P: O que acontece com meu saldo quando faço um reembolso?
R: Seu saldo disponível é ajustado. Para reembolsos totais, toda a cobrança é estornada. Para reembolsos parciais, seu saldo reflete o valor reduzido.

P: Posso cancelar um reembolso?
R: Não, uma vez iniciados, os reembolsos não podem ser cancelados. Planeje cuidadosamente antes de criar um reembolso.

P: Qual é a diferença entre reembolsos totais e parciais?
R: Os reembolsos totais estornam o valor total da cobrança e a marcam como reembolsada. Os reembolsos parciais reduzem o valor da cobrança e a marcam como parcialmente reembolsada.

P: Posso reembolsar uma cobrança várias vezes?
R: Sim, você pode emitir vários reembolsos parciais, desde que o valor total reembolsado não exceda o valor original da cobrança.

Ainda tem dúvidas? Pergunte na comunidade..
Consulte el changelog.