Payouts, Settlements & Disputes

Leitura de repasses, liquidações e disputas **sintéticos**.

get /v1/disputes — Listar disputas sintéticas
get /v1/disputes/{id} — Consultar disputa sintética
get /v1/finance/payouts — Histórico de saques
get /v1/payouts — Listar repasses sintéticos
post /v1/payouts — Solicitar saque sintético
get /v1/payouts/{id} — Consultar repasse sintético
get /v1/settlements — Listar liquidações sintéticas
get /v1/settlements/{id} — Consultar liquidação sintética

get/v1/disputes

Listar disputas sintéticas (listDisputes)

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/disputes

Parâmetros

Nome Onde Tipo Detalhes

Nome	Onde	Tipo	Detalhes
`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_`

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

Disputas.

Resposta 200 de listDisputes
Campo	Tipo	Detalhes
`data` obrigatório	Dispute[]

Exemplo de resposta 200 json

{
  "data": [
    {
      "id": "dsp_9e8d7c6b5a4f3e2d1c0b9a8f7e6d5c4b",
      "payment_intent_id": "pi_3b9f0c2d1e4a5b6c7d8e9f0a1b2c3d4e",
      "charge_id": "chg_8a7b6c5d4e3f2a1b0c9d8e7f6a5b4c3d",
      "amount_minor": "9900",
      "currency": "BRL",
      "status": "created",
      "reason_code": "product_not_received",
      "provider_id": "simulator",
      "external_id": "sim_dsp_0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f",
      "provider_status": "needs_response",
      "synthetic_obligation": true,
      "created_at": "2026-11-06T12:00:00.000Z",
      "updated_at": "2026-11-06T12:00:00.000Z",
      "resolved_at": null
    }
  ]
}

Erros

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

get/v1/disputes/{id}

Consultar disputa sintética (getDispute)

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/disputes/{id}

Parâmetros

Nome Onde Tipo Detalhes

Nome	Onde	Tipo	Detalhes
`id`obrigatório	caminho	string	Id da disputa (`dsp_...`). 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 da disputa (dsp_...).

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

Disputa.

Objeto Dispute

Resposta 200 de getDispute
Campo	Tipo	Detalhes
`id` obrigatório	string	Começa com `dsp_`
`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`, `won`, `lost`
`reason_code` obrigatório	string	Valores: `fraudulent`, `product_not_received`, `not_as_described`, `duplicate`, `other`
`provider_id` obrigatório	string
`external_id` obrigatório	string
`provider_status` obrigatório	string
`synthetic_obligation` obrigatório	true
`created_at` obrigatório	string
`updated_at` obrigatório	string
`resolved_at` obrigatório	string \| null

Exemplo de resposta 200 json

{
  "id": "dsp_9e8d7c6b5a4f3e2d1c0b9a8f7e6d5c4b",
  "payment_intent_id": "pi_3b9f0c2d1e4a5b6c7d8e9f0a1b2c3d4e",
  "charge_id": "chg_8a7b6c5d4e3f2a1b0c9d8e7f6a5b4c3d",
  "amount_minor": "9900",
  "currency": "BRL",
  "status": "created",
  "reason_code": "product_not_received",
  "provider_id": "simulator",
  "external_id": "sim_dsp_0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f",
  "provider_status": "needs_response",
  "synthetic_obligation": true,
  "created_at": "2026-11-06T12:00:00.000Z",
  "updated_at": "2026-11-06T12:00:00.000Z",
  "resolved_at": null
}

Erros

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

get/v1/finance/payouts

Histórico de saques (listFinancePayouts)

Saques sintéticos do seller, do mais recente ao mais antigo, com a origem (seller: pedido pelo app; admin: criado pela operação da Wolf) e o estado (created = em processamento, paid, failed).

rate limit: api_authenticated

Autenticação: API key (sk_test_...) ou sessão do app do seller
Escopos: finance:read
URL: https://api.v2.wolfpayteste.online/v1/finance/payouts

Parâmetros

Nome Onde Tipo Detalhes

Nome	Onde	Tipo	Detalhes
`limit`	consulta	integer	de 1 a 100 Padrão: `50`
`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_`

limit

consulta

integer

de 1 a 100

Padrão: 50

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

Saques.

Objeto FinancePayoutList

Resposta 200 de listFinancePayouts
Campo	Tipo	Detalhes
`data` obrigatório	FinancePayout[]

Exemplo de resposta 200 json

{
  "data": [
    {
      "id": "pyo_2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e",
      "amount_minor": "123456",
      "currency": "BRL",
      "status": "paid",
      "origin": "seller",
      "destination_ref": "sim_seller_default",
      "synthetic_obligation": true,
      "created_at": "2026-11-06T12:00:00.000Z",
      "resolved_at": "2026-11-06T12:00:05.000Z"
    }
  ]
}

Erros

400 — VALIDATION_FAILED
401 — AUTHENTICATION_REQUIRED
403 — FORBIDDEN
409 — TENANT_SELECTION_REQUIRED
429 — RATE_LIMITED
500 — INTERNAL_ERROR

get/v1/payouts

Listar repasses sintéticos (listPayouts)

rate limit: api_authenticated

Autenticação: API key (sk_test_...) ou sessão do app do seller
Escopos: finance:read
URL: https://api.v2.wolfpayteste.online/v1/payouts

Parâmetros

Nome Onde Tipo Detalhes

Nome	Onde	Tipo	Detalhes
`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_`

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

Repasses.

Resposta 200 de listPayouts
Campo	Tipo	Detalhes
`data` obrigatório	Payout[]

Exemplo de resposta 200 json

{
  "data": [
    {
      "id": "pyo_2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e",
      "amount_minor": "150000",
      "currency": "BRL",
      "status": "paid",
      "origin": "admin",
      "provider_id": "simulator",
      "provider_request_key": "payout:pyo_2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e",
      "external_id": "sim_pyo_1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a",
      "destination_ref": "sim_conta_principal",
      "provider_status": "paid",
      "synthetic_obligation": true,
      "created_at": "2026-11-06T12:00:00.000Z",
      "updated_at": "2026-11-06T12:00:05.000Z",
      "resolved_at": "2026-11-06T12:00:05.000Z"
    }
  ]
}

Erros

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

post/v1/payouts

Solicitar saque sintético (createSellerPayout)

Saque sintético do saldo disponível (nenhum dinheiro real se move). Só pela sessão humana do app do seller, com papel que tenha payouts:write (OWNER ou ADMIN) e reautenticação recente (até 10 minutos; senão 403 STEP_UP_REQUIRED); API keys recebem 403 nesta versão. Valor em unidades menores: mínimo 1000 (R$ 10,00, senão 409 PAYOUT_BELOW_MINIMUM) e no máximo o saldo disponível (409 PAYOUT_AMOUNT_EXCEEDS_AVAILABLE). Dois pedidos simultâneos com saldo para um só: só um é aceito. O saque nasce created (em processamento) e é resolvido de forma sintética em cerca de 2 minutos (paid), ou marcado como falha pela operação da Wolf. Só existe com a flag SELLER_PAYOUTS_ENABLED ligada no ambiente (senão 404). Repetir a requisição com a mesma Idempotency-Key e o mesmo corpo devolve o mesmo resultado, sem nova cobrança; corpo diferente → 409 IDEMPOTENCY_CONFLICT.

Idempotency-Key obrigatória rate limit: api_authenticated

Autenticação: sessão do app do seller
Escopos: finance:read
URL: https://api.v2.wolfpayteste.online/v1/payouts

Parâmetros

Nome Onde Tipo Detalhes

Nome	Onde	Tipo	Detalhes
`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_`

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 CreateSellerPayoutRequest

Corpo de createSellerPayout
Campo	Tipo	Detalhes
`amount_minor` obrigatório	string	Padrão `^[1-9][0-9]*$`
`currency`	string	Padrão `^[A-Z]{3}$` Padrão: `"BRL"`

Exemplo de corpo json

{
  "amount_minor": "123456",
  "currency": "BRL"
}

Resposta 200

Replay da mesma Idempotency-Key: o mesmo saque, sem novo débito.

Objeto Payout

Resposta 200 de createSellerPayout
Campo	Tipo	Detalhes
`id` obrigatório	string	Começa com `pyo_`
`amount_minor` obrigatório	string
`currency` obrigatório	string	Padrão `^[A-Z]{3}$`
`status` obrigatório	string	Valores: `created`, `paid`, `failed`
`origin` obrigatório	string	Valores: `admin`, `seller`
`provider_id` obrigatório	string
`provider_request_key` obrigatório	string
`external_id` obrigatório	string \| null
`destination_ref` obrigatório	string	Padrão `^sim_[A-Za-z0-9_-]{3,120}$`
`provider_status` obrigatório	string \| null
`synthetic_obligation` obrigatório	true
`created_at` obrigatório	string
`updated_at` obrigatório	string
`resolved_at` obrigatório	string \| null

Exemplo de resposta 200 json

{
  "id": "pyo_2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e",
  "amount_minor": "123456",
  "currency": "BRL",
  "status": "created",
  "origin": "seller",
  "provider_id": "simulator",
  "provider_request_key": "payout:pyo_2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e",
  "external_id": null,
  "destination_ref": "sim_seller_default",
  "provider_status": "created",
  "synthetic_obligation": true,
  "created_at": "2026-11-06T12:00:00.000Z",
  "updated_at": "2026-11-06T12:00:00.000Z",
  "resolved_at": null
}

Resposta 201

Saque criado (em processamento).

Objeto Payout

Resposta 201 de createSellerPayout
Campo	Tipo	Detalhes
`id` obrigatório	string	Começa com `pyo_`
`amount_minor` obrigatório	string
`currency` obrigatório	string	Padrão `^[A-Z]{3}$`
`status` obrigatório	string	Valores: `created`, `paid`, `failed`
`origin` obrigatório	string	Valores: `admin`, `seller`
`provider_id` obrigatório	string
`provider_request_key` obrigatório	string
`external_id` obrigatório	string \| null
`destination_ref` obrigatório	string	Padrão `^sim_[A-Za-z0-9_-]{3,120}$`
`provider_status` obrigatório	string \| null
`synthetic_obligation` obrigatório	true
`created_at` obrigatório	string
`updated_at` obrigatório	string
`resolved_at` obrigatório	string \| null

Exemplo de resposta 201 json

{
  "id": "pyo_2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e",
  "amount_minor": "123456",
  "currency": "BRL",
  "status": "created",
  "origin": "seller",
  "provider_id": "simulator",
  "provider_request_key": "payout:pyo_2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e",
  "external_id": null,
  "destination_ref": "sim_seller_default",
  "provider_status": "created",
  "synthetic_obligation": true,
  "created_at": "2026-11-06T12:00:00.000Z",
  "updated_at": "2026-11-06T12:00:00.000Z",
  "resolved_at": null
}

Erros

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

get/v1/payouts/{id}

Consultar repasse sintético (getPayout)

rate limit: api_authenticated

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

Parâmetros

Nome Onde Tipo Detalhes

Nome	Onde	Tipo	Detalhes
`id`obrigatório	caminho	string	Id do repasse (`pyo_...`). 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 repasse (pyo_...).

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

Repasse.

Objeto Payout

Resposta 200 de getPayout
Campo	Tipo	Detalhes
`id` obrigatório	string	Começa com `pyo_`
`amount_minor` obrigatório	string
`currency` obrigatório	string	Padrão `^[A-Z]{3}$`
`status` obrigatório	string	Valores: `created`, `paid`, `failed`
`origin` obrigatório	string	Valores: `admin`, `seller`
`provider_id` obrigatório	string
`provider_request_key` obrigatório	string
`external_id` obrigatório	string \| null
`destination_ref` obrigatório	string	Padrão `^sim_[A-Za-z0-9_-]{3,120}$`
`provider_status` obrigatório	string \| null
`synthetic_obligation` obrigatório	true
`created_at` obrigatório	string
`updated_at` obrigatório	string
`resolved_at` obrigatório	string \| null

Exemplo de resposta 200 json

{
  "id": "pyo_2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e",
  "amount_minor": "150000",
  "currency": "BRL",
  "status": "paid",
  "origin": "admin",
  "provider_id": "simulator",
  "provider_request_key": "payout:pyo_2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e",
  "external_id": "sim_pyo_1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a",
  "destination_ref": "sim_conta_principal",
  "provider_status": "paid",
  "synthetic_obligation": true,
  "created_at": "2026-11-06T12:00:00.000Z",
  "updated_at": "2026-11-06T12:00:05.000Z",
  "resolved_at": "2026-11-06T12:00:05.000Z"
}

Erros

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

get/v1/settlements

Listar liquidações sintéticas (listSettlements)

rate limit: api_authenticated

Autenticação: API key (sk_test_...) ou sessão do app do seller
Escopos: finance:read
URL: https://api.v2.wolfpayteste.online/v1/settlements

Parâmetros

Nome Onde Tipo Detalhes

Nome	Onde	Tipo	Detalhes
`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_`

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

Lotes de liquidação.

Resposta 200 de listSettlements
Campo	Tipo	Detalhes
`data` obrigatório	SettlementBatch[]

Exemplo de resposta 200 json

{
  "data": [
    {
      "id": "stb_4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f",
      "provider_id": "simulator",
      "external_id": "sim_lote_2026_11_06",
      "window_start": "2026-11-05T00:00:00.000Z",
      "window_end": "2026-11-06T00:00:00.000Z",
      "status": "completed",
      "origin": "admin",
      "synthetic_obligation": true,
      "created_at": "2026-11-06T12:00:00.000Z",
      "updated_at": "2026-11-06T12:00:05.000Z",
      "finalized_at": "2026-11-06T12:00:05.000Z",
      "lines": [
        {
          "id": "stl_6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b",
          "charge_id": "chg_8a7b6c5d4e3f2a1b0c9d8e7f6a5b4c3d",
          "amount_minor": "9900",
          "fee_minor": "396",
          "currency": "BRL",
          "status": "available",
          "available_minor": "9504",
          "reserve_minor": "0",
          "reconciliation_case_id": null
        }
      ]
    }
  ]
}

Erros

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

get/v1/settlements/{id}

Consultar liquidação sintética (getSettlement)

rate limit: api_authenticated

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

Parâmetros

Nome Onde Tipo Detalhes

Nome	Onde	Tipo	Detalhes
`id`obrigatório	caminho	string	Id do lote (`stb_...`). 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 lote (stb_...).

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

Lote de liquidação.

Objeto SettlementBatch

Resposta 200 de getSettlement
Campo	Tipo	Detalhes
`id` obrigatório	string	Começa com `stb_`
`provider_id` obrigatório	string
`external_id` obrigatório	string
`window_start` obrigatório	string
`window_end` obrigatório	string
`status` obrigatório	string	Valores: `created`, `processing`, `completed`, `requires_review`
`origin` obrigatório	string	Valores: `admin`, `auto`
`synthetic_obligation` obrigatório	true
`created_at` obrigatório	string
`updated_at` obrigatório	string
`finalized_at` obrigatório	string \| null
`lines` obrigatório	object[]
`lines[].id` obrigatório	string	Começa com `stl_`
`lines[].charge_id` obrigatório	string	Começa com `chg_`
`lines[].amount_minor` obrigatório	string
`lines[].fee_minor` obrigatório	string
`lines[].currency` obrigatório	string	Padrão `^[A-Z]{3}$`
`lines[].status` obrigatório	string	Valores: `pending`, `available`, `mismatch`
`lines[].available_minor` obrigatório	string \| null
`lines[].reserve_minor` obrigatório	string \| null
`lines[].reconciliation_case_id` obrigatório	string \| null

Exemplo de resposta 200 json

{
  "id": "stb_4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f",
  "provider_id": "simulator",
  "external_id": "sim_lote_2026_11_06",
  "window_start": "2026-11-05T00:00:00.000Z",
  "window_end": "2026-11-06T00:00:00.000Z",
  "status": "completed",
  "origin": "admin",
  "synthetic_obligation": true,
  "created_at": "2026-11-06T12:00:00.000Z",
  "updated_at": "2026-11-06T12:00:05.000Z",
  "finalized_at": "2026-11-06T12:00:05.000Z",
  "lines": [
    {
      "id": "stl_6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b",
      "charge_id": "chg_8a7b6c5d4e3f2a1b0c9d8e7f6a5b4c3d",
      "amount_minor": "9900",
      "fee_minor": "396",
      "currency": "BRL",
      "status": "available",
      "available_minor": "9504",
      "reserve_minor": "0",
      "reconciliation_case_id": null
    }
  ]
}

Erros

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