Refunds

Reembolsos totais ou parciais de pagamentos capturados.

post /v1/payment-intents/{id}/refunds — Reembolsar PaymentIntent
get /v1/refunds/{id} — Consultar reembolso

post/v1/payment-intents/{id}/refunds

Reembolsar PaymentIntent (createRefund)

Cria um reembolso total ou parcial (amount_minor) de um PaymentIntent succeeded. A soma dos reembolsos nunca excede o capturado. 202 indica resultado desconhecido no provedor, resolvido por reconciliação. Pela sessão do app do seller exige reautenticação recente (até 10 minutos; senão 403 STEP_UP_REQUIRED); API keys são autorizadas só pelo escopo refunds:write.

Idempotency-Key obrigatória rate limit: api_authenticated

Autenticação: API key (sk_test_...) ou sessão do app do seller
Escopos: payments:read,refunds:write
URL: https://api.v2.wolfpayteste.online/v1/payment-intents/{id}/refunds

Parâmetros

Nome Onde Tipo Detalhes

Nome	Onde	Tipo	Detalhes
`id`obrigatório	caminho	string	Id do PaymentIntent (`pi_...`). mínimo 1 caractere(s)
`Idempotency-Key`obrigatório	cabeçalho	string	Chave escolhida pelo cliente (8 a 255 caracteres). Mesma chave + mesmo corpo = mesma resposta; corpo diferente = `409 IDEMPOTENCY_CONFLICT`. Guardada por 24 h. 8 a 255 caracteres
`wolf-organization-id`	cabeçalho	string	Só para sessão do app do seller com mais de uma organização (senão `409 TENANT_SELECTION_REQUIRED`). Ignorado para API keys. Padrão `^org_`

idobrigatório

caminho

string

Id do PaymentIntent (pi_...).

mínimo 1 caractere(s)

Idempotency-Keyobrigatório

cabeçalho

string

Chave escolhida pelo cliente (8 a 255 caracteres). Mesma chave + mesmo corpo = mesma resposta; corpo diferente = 409 IDEMPOTENCY_CONFLICT. Guardada por 24 h.

8 a 255 caracteres

wolf-organization-id

cabeçalho

string

Só para sessão do app do seller com mais de uma organização (senão 409 TENANT_SELECTION_REQUIRED). Ignorado para API keys.

Padrão ^org_

Corpo da requisição

Objeto CreateRefundRequest

Corpo de createRefund
Campo	Tipo	Detalhes
`amount_minor` obrigatório	string	Padrão `^[1-9][0-9]*$`

Exemplo de corpo json

{
  "amount_minor": "4900"
}

Resposta 200

Reembolso concluído.

Objeto Refund

Resposta 200 de createRefund
Campo	Tipo	Detalhes
`id` obrigatório	string	Começa com `rfd_`
`payment_intent_id` obrigatório	string	Começa com `pi_`
`charge_id` obrigatório	string	Começa com `chg_`
`amount_minor` obrigatório	string
`currency` obrigatório	string	Padrão `^[A-Z]{3}$`
`status` obrigatório	string	Valores: `created`, `processing`, `succeeded`, `failed`, `unknown`
`provider_id` obrigatório	string
`external_id` obrigatório	string \| null
`failure_code` obrigatório	string \| null

Exemplo de resposta 200 json

{
  "id": "rfd_1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d",
  "payment_intent_id": "pi_3b9f0c2d1e4a5b6c7d8e9f0a1b2c3d4e",
  "charge_id": "chg_8a7b6c5d4e3f2a1b0c9d8e7f6a5b4c3d",
  "amount_minor": "4900",
  "currency": "BRL",
  "status": "succeeded",
  "provider_id": "simulator",
  "external_id": "sim_ref_4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c",
  "failure_code": null
}

Resposta 202

Reembolso com resultado desconhecido no provedor (em reconciliação).

Objeto Refund

Resposta 202 de createRefund
Campo	Tipo	Detalhes
`id` obrigatório	string	Começa com `rfd_`
`payment_intent_id` obrigatório	string	Começa com `pi_`
`charge_id` obrigatório	string	Começa com `chg_`
`amount_minor` obrigatório	string
`currency` obrigatório	string	Padrão `^[A-Z]{3}$`
`status` obrigatório	string	Valores: `created`, `processing`, `succeeded`, `failed`, `unknown`
`provider_id` obrigatório	string
`external_id` obrigatório	string \| null
`failure_code` obrigatório	string \| null

Erros

400 — IDEMPOTENCY_KEY_REQUIRED,VALIDATION_FAILED
401 — AUTHENTICATION_REQUIRED
403 — FORBIDDEN,STEP_UP_REQUIRED
404 — RESOURCE_NOT_FOUND
409 — IDEMPOTENCY_CONFLICT,INVALID_STATE_TRANSITION,REFUND_EXCEEDS_CAPTURED,REFUND_FAILED,TENANT_SELECTION_REQUIRED
429 — RATE_LIMITED
500 — INTERNAL_ERROR
503 — SERVICE_UNAVAILABLE

get/v1/refunds/{id}

Consultar reembolso (getRefund)

rate limit: api_authenticated

Autenticação: API key (sk_test_...) ou sessão do app do seller
Escopos: payments:read
URL: https://api.v2.wolfpayteste.online/v1/refunds/{id}

Parâmetros

Nome Onde Tipo Detalhes

Nome	Onde	Tipo	Detalhes
`id`obrigatório	caminho	string	Id do reembolso (`rfd_...`). mínimo 1 caractere(s)
`wolf-organization-id`	cabeçalho	string	Só para sessão do app do seller com mais de uma organização (senão `409 TENANT_SELECTION_REQUIRED`). Ignorado para API keys. Padrão `^org_`

idobrigatório

caminho

string

Id do reembolso (rfd_...).

mínimo 1 caractere(s)

wolf-organization-id

cabeçalho

string

Só para sessão do app do seller com mais de uma organização (senão 409 TENANT_SELECTION_REQUIRED). Ignorado para API keys.

Padrão ^org_

Resposta 200

Reembolso.

Objeto Refund

Resposta 200 de getRefund
Campo	Tipo	Detalhes
`id` obrigatório	string	Começa com `rfd_`
`payment_intent_id` obrigatório	string	Começa com `pi_`
`charge_id` obrigatório	string	Começa com `chg_`
`amount_minor` obrigatório	string
`currency` obrigatório	string	Padrão `^[A-Z]{3}$`
`status` obrigatório	string	Valores: `created`, `processing`, `succeeded`, `failed`, `unknown`
`provider_id` obrigatório	string
`external_id` obrigatório	string \| null
`failure_code` obrigatório	string \| null

Exemplo de resposta 200 json

{
  "id": "rfd_1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d",
  "payment_intent_id": "pi_3b9f0c2d1e4a5b6c7d8e9f0a1b2c3d4e",
  "charge_id": "chg_8a7b6c5d4e3f2a1b0c9d8e7f6a5b4c3d",
  "amount_minor": "4900",
  "currency": "BRL",
  "status": "succeeded",
  "provider_id": "simulator",
  "external_id": "sim_ref_4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c",
  "failure_code": null
}

Erros

401 — AUTHENTICATION_REQUIRED
403 — FORBIDDEN
404 — RESOURCE_NOT_FOUND
409 — TENANT_SELECTION_REQUIRED
429 — RATE_LIMITED
500 — INTERNAL_ERROR