Referência da API

Disputas

Chargebacks e defesa.

Listar disputas

GET/v1/disputesImplementada

Chave de API (Authorization: Bearer ep_…)· escopo payments:read· listDisputes

Lista as disputas (chargebacks) da conta, com motivo traduzido, valor contestado, prazo para enviar a defesa e situação.

Escopo da chave: payments:read.

Headers de listDisputes
Header	Obrigatório	Descrição
`X-Account-Id`	sim	Conta permitida pelos grants do principal.

Parâmetros de listDisputes
Parâmetro	Onde	Tipo	Descrição
`cursor`	query	texto	0–200 caracteres
`limit`	query	inteiro	1 a 100 · padrão 20
`Eclipta-Pay-Version`	header	"2026-11-13"	Versão de data do contrato. Opcional; a resposta sempre informa a versão usada. Valor desconhecido responde 400 UNSUPPORTED_API_VERSION.

Exemplo

curl -X GET "$ECLIPTA_PAY_API/v1/disputes" \
  -H "Authorization: Bearer $ECLIPTA_PAY_KEY" \
  -H "X-Account-Id: $ECLIPTA_PAY_ACCOUNT"

Resposta 200: Sucesso.

Campos da resposta 200 de listDisputes
Campo	Tipo	Descrição
`data` obrigatório	lista de Dispute
`data[].id` obrigatório	Id (texto)	8–160 caracteres · formato ^[A-Za-z0-9_]+$
`data[].paymentId` obrigatório	Id (texto)	8–160 caracteres · formato ^[A-Za-z0-9_]+$
`data[].status` obrigatório	"OPEN" \| "SUBMITTING" \| "UNDER_REVIEW" \| "AWAITING_REVERSAL" \| "WON" \| "LOST"
`data[].display` obrigatório	objeto
`data[].display.label` obrigatório	texto
`data[].display.variant` obrigatório	"info" \| "warn" \| "accent" \| "ok" \| "bad" \| "neutral"
`data[].reason` obrigatório	texto ou nulo	Enum original do Asaas (ex.: SERVICE_NOT_RECEIVED).
`data[].reasonLabel` obrigatório	texto	Tradução só para exibição.
`data[].providerStatus` obrigatório	texto ou nulo
`data[].amountCents` obrigatório	PositiveCents (texto)	formato ^[1-9][0-9]{0,14}$
`data[].evidenceDueBy` obrigatório	texto ou nulo	deadlineToSendDisputeDocuments do provedor.
`data[].submittedAt` obrigatório	data e hora (ISO 8601) ou nulo
`data[].resolvedAt` obrigatório	data e hora (ISO 8601) ou nulo
`data[].refundOverlap` obrigatório	booleano	Chargeback aberto com estorno em andamento: revisão humana.
`data[].evidence` obrigatório	lista de DisputeEvidence
`data[].evidence[].id` obrigatório	Id (texto)	8–160 caracteres · formato ^[A-Za-z0-9_]+$
`data[].evidence[].contentType` obrigatório	"application/pdf" \| "image/jpeg" \| "image/png"
`data[].evidence[].sizeBytes` obrigatório	inteiro	1 a 10000000
`data[].evidence[].sha256` obrigatório	texto	formato ^[a-f0-9]{64}$
`data[].evidence[].displayName` obrigatório	texto
`data[].evidence[].submittedAt` obrigatório	data e hora (ISO 8601) ou nulo
`data[].evidence[].createdAt` obrigatório	data e hora (ISO 8601)	formato ^(?:(?:\d\d[2468][048]\|\d\d[13579][26]\|\d\d0[48]\|[02468][048]00\|[13579][26]00)-02-29\|\d{4}-(?:(?:0[13578]\|1[02])-(?:0[1-9]\|[12]\d\|3[01])\|(?:0[469]\|11)-(?:0[1-9]\|[12]\d\|30)\|(?:02)-(?:0[1-9]\|1\d\|2[0-8])))T(?:(?:[01]\d\|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z\|([+-](?:[01]\d\|2[0-3]):[0-5]\d)))$
`data[].openedAt` obrigatório	data e hora (ISO 8601)	formato ^(?:(?:\d\d[2468][048]\|\d\d[13579][26]\|\d\d0[48]\|[02468][048]00\|[13579][26]00)-02-29\|\d{4}-(?:(?:0[13578]\|1[02])-(?:0[1-9]\|[12]\d\|3[01])\|(?:0[469]\|11)-(?:0[1-9]\|[12]\d\|30)\|(?:02)-(?:0[1-9]\|1\d\|2[0-8])))T(?:(?:[01]\d\|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z\|([+-](?:[01]\d\|2[0-3]):[0-5]\d)))$
`data[].version` obrigatório	inteiro	1 a 9007199254740991
`nextCursor` obrigatório	texto ou nulo

Exemplo 200

{
  "data": [
    {
      "id": "dsp_01JDYA21B2C3D4E5F6G7H8J9KB",
      "paymentId": "pay_01JDY8C1B2C3D4E5F6G7H8J9KC",
      "status": "OPEN",
      "display": {
        "label": "Disputa aberta",
        "variant": "warn"
      },
      "reason": "MERCHANDISE_NOT_RECEIVED",
      "reasonLabel": "Mercadoria não recebida",
      "providerStatus": "REQUESTED",
      "amountCents": "14970",
      "evidenceDueBy": "2026-11-23",
      "submittedAt": null,
      "resolvedAt": null,
      "refundOverlap": false,
      "evidence": [
        {
          "id": "evd_01JDYA31B2C3D4E5F6G7H8J9KC",
          "contentType": "application/pdf",
          "sizeBytes": 182311,
          "sha256": "9f2c4e0a7b1d3c5e8f6a2b4d6c8e0f1a3b5c7d9e1f2a4b6c8d0e2f4a6b8c0d2e",
          "displayName": "comprovante-entrega.pdf",
          "submittedAt": null,
          "createdAt": "2026-11-13T13:00:00.000Z"
        }
      ],
      "openedAt": "2026-11-13T13:00:00.000Z",
      "version": 1
    }
  ],
  "nextCursor": null
}

Erros

Erros de listDisputes
HTTP	Exemplo de code	Quando
400	`INVALID_REQUEST`	Requisição inválida: fieldErrors aponta cada campo.
401	`INVALID_API_KEY`	Chave de API ausente, inválida, expirada ou revogada.
403	`SCOPE_MISSING`	Escopo ausente, conta não permitida em X-Account-Id, IP fora da lista ou conta suspensa.
429	`TOO_MANY_REQUESTS`	Limite de requisições da chave atingido (rajada de 100 e 6.000 por minuto). Toda resposta traz RateLimit-Limit, RateLimit-Remaining e RateLimit-Reset; o 429 traz Retry-After em segundos. Aguarde e repita com a mesma Idempotency-Key.

Consultar disputa

GET/v1/disputes/{id}Implementada

Chave de API (Authorization: Bearer ep_…)· escopo payments:read· getDispute

Consulta uma disputa: motivo original do provedor e tradução, prazo da defesa, evidências anexadas e desfecho. O histórico da cobrança é preservado.

Escopo da chave: payments:read.

Headers de getDispute
Header	Obrigatório	Descrição
`X-Account-Id`	sim	Conta permitida pelos grants do principal.

Parâmetros de getDispute
Parâmetro	Onde	Tipo	Descrição
`id` obrigatório	caminho	Id (texto)	8–160 caracteres · formato ^[A-Za-z0-9_]+$
`Eclipta-Pay-Version`	header	"2026-11-13"	Versão de data do contrato. Opcional; a resposta sempre informa a versão usada. Valor desconhecido responde 400 UNSUPPORTED_API_VERSION.

Exemplo

curl -X GET "$ECLIPTA_PAY_API/v1/disputes/{id}" \
  -H "Authorization: Bearer $ECLIPTA_PAY_KEY" \
  -H "X-Account-Id: $ECLIPTA_PAY_ACCOUNT"

Resposta 200: Sucesso.

Campos da resposta 200 de getDispute
Campo	Tipo	Descrição
`id` obrigatório	Id (texto)	8–160 caracteres · formato ^[A-Za-z0-9_]+$
`paymentId` obrigatório	Id (texto)	8–160 caracteres · formato ^[A-Za-z0-9_]+$
`status` obrigatório	"OPEN" \| "SUBMITTING" \| "UNDER_REVIEW" \| "AWAITING_REVERSAL" \| "WON" \| "LOST"
`display` obrigatório	objeto
`display.label` obrigatório	texto
`display.variant` obrigatório	"info" \| "warn" \| "accent" \| "ok" \| "bad" \| "neutral"
`reason` obrigatório	texto ou nulo	Enum original do Asaas (ex.: SERVICE_NOT_RECEIVED).
`reasonLabel` obrigatório	texto	Tradução só para exibição.
`providerStatus` obrigatório	texto ou nulo
`amountCents` obrigatório	PositiveCents (texto)	formato ^[1-9][0-9]{0,14}$
`evidenceDueBy` obrigatório	texto ou nulo	deadlineToSendDisputeDocuments do provedor.
`submittedAt` obrigatório	data e hora (ISO 8601) ou nulo
`resolvedAt` obrigatório	data e hora (ISO 8601) ou nulo
`refundOverlap` obrigatório	booleano	Chargeback aberto com estorno em andamento: revisão humana.
`evidence` obrigatório	lista de DisputeEvidence
`evidence[].id` obrigatório	Id (texto)	8–160 caracteres · formato ^[A-Za-z0-9_]+$
`evidence[].contentType` obrigatório	"application/pdf" \| "image/jpeg" \| "image/png"
`evidence[].sizeBytes` obrigatório	inteiro	1 a 10000000
`evidence[].sha256` obrigatório	texto	formato ^[a-f0-9]{64}$
`evidence[].displayName` obrigatório	texto
`evidence[].submittedAt` obrigatório	data e hora (ISO 8601) ou nulo
`evidence[].createdAt` obrigatório	data e hora (ISO 8601)	formato ^(?:(?:\d\d[2468][048]\|\d\d[13579][26]\|\d\d0[48]\|[02468][048]00\|[13579][26]00)-02-29\|\d{4}-(?:(?:0[13578]\|1[02])-(?:0[1-9]\|[12]\d\|3[01])\|(?:0[469]\|11)-(?:0[1-9]\|[12]\d\|30)\|(?:02)-(?:0[1-9]\|1\d\|2[0-8])))T(?:(?:[01]\d\|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z\|([+-](?:[01]\d\|2[0-3]):[0-5]\d)))$
`openedAt` obrigatório	data e hora (ISO 8601)	formato ^(?:(?:\d\d[2468][048]\|\d\d[13579][26]\|\d\d0[48]\|[02468][048]00\|[13579][26]00)-02-29\|\d{4}-(?:(?:0[13578]\|1[02])-(?:0[1-9]\|[12]\d\|3[01])\|(?:0[469]\|11)-(?:0[1-9]\|[12]\d\|30)\|(?:02)-(?:0[1-9]\|1\d\|2[0-8])))T(?:(?:[01]\d\|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z\|([+-](?:[01]\d\|2[0-3]):[0-5]\d)))$
`version` obrigatório	inteiro	1 a 9007199254740991

Exemplo 200

{
  "id": "dsp_01JDYA21B2C3D4E5F6G7H8J9KB",
  "paymentId": "pay_01JDY8C1B2C3D4E5F6G7H8J9KC",
  "status": "OPEN",
  "display": {
    "label": "Disputa aberta",
    "variant": "warn"
  },
  "reason": "MERCHANDISE_NOT_RECEIVED",
  "reasonLabel": "Mercadoria não recebida",
  "providerStatus": "REQUESTED",
  "amountCents": "14970",
  "evidenceDueBy": "2026-11-23",
  "submittedAt": null,
  "resolvedAt": null,
  "refundOverlap": false,
  "evidence": [
    {
      "id": "evd_01JDYA31B2C3D4E5F6G7H8J9KC",
      "contentType": "application/pdf",
      "sizeBytes": 182311,
      "sha256": "9f2c4e0a7b1d3c5e8f6a2b4d6c8e0f1a3b5c7d9e1f2a4b6c8d0e2f4a6b8c0d2e",
      "displayName": "comprovante-entrega.pdf",
      "submittedAt": null,
      "createdAt": "2026-11-13T13:00:00.000Z"
    }
  ],
  "openedAt": "2026-11-13T13:00:00.000Z",
  "version": 1
}

Erros

Erros de getDispute
HTTP	Exemplo de code	Quando
400	`INVALID_REQUEST`	Requisição inválida: fieldErrors aponta cada campo.
401	`INVALID_API_KEY`	Chave de API ausente, inválida, expirada ou revogada.
403	`SCOPE_MISSING`	Escopo ausente, conta não permitida em X-Account-Id, IP fora da lista ou conta suspensa.
404	`RESOURCE_NOT_FOUND`	Recurso inexistente nesta conta (inclusive recurso de outra conta ou de outro tenant).
429	`TOO_MANY_REQUESTS`	Limite de requisições da chave atingido (rajada de 100 e 6.000 por minuto). Toda resposta traz RateLimit-Limit, RateLimit-Remaining e RateLimit-Reset; o 429 traz Retry-After em segundos. Aguarde e repita com a mesma Idempotency-Key.

Enviar defesa (uma vez)

POST/v1/disputes/{id}/submitImplementada

Chave de API (Authorization: Bearer ep_…)· escopo refunds:write· submitDispute

Envia a defesa com as evidências anexadas, uma única vez por disputa, dentro do prazo do provedor. Responde 202 com a operação.

Escopo da chave: refunds:write.

Idempotência: exige o header Idempotency-Key.

Headers de submitDispute
Header	Obrigatório	Descrição
`X-Account-Id`	sim	Conta permitida pelos grants do principal.
`Idempotency-Key`	sim	Chave única por intenção (16 a 128 caracteres visíveis). Ao refazer a mesma chamada, repita a mesma chave: o resultado gravado é devolvido. Mesma chave com outro conteúdo responde 409 IDEMPOTENCY_CONFLICT.

Parâmetros de submitDispute
Parâmetro	Onde	Tipo	Descrição
`id` obrigatório	caminho	Id (texto)	8–160 caracteres · formato ^[A-Za-z0-9_]+$
`Eclipta-Pay-Version`	header	"2026-11-13"	Versão de data do contrato. Opcional; a resposta sempre informa a versão usada. Valor desconhecido responde 400 UNSUPPORTED_API_VERSION.

Corpo da requisição

Campos do corpo de submitDispute
Campo	Tipo	Descrição
`expectedVersion` obrigatório	inteiro	1 a 9007199254740991

Exemplo

curl -X POST "$ECLIPTA_PAY_API/v1/disputes/{id}/submit" \
  -H "Authorization: Bearer $ECLIPTA_PAY_KEY" \
  -H "X-Account-Id: $ECLIPTA_PAY_ACCOUNT" \
  -H "Idempotency-Key: <uma chave por intenção>" \
  -H "Content-Type: application/json" \
  -d '{"expectedVersion":1}'

Resposta 202: Aceito: a intenção foi registrada; acompanhe o resultado (não é transação concluída).

Campos da resposta 202 de submitDispute
Campo	Tipo	Descrição
`id` obrigatório	Id (texto)	8–160 caracteres · formato ^[A-Za-z0-9_]+$
`status` obrigatório	"ACCEPTED" \| "DISPATCHING" \| "UNKNOWN" \| "SUCCEEDED" \| "FAILED" \| "MANUAL_REVIEW"
`kind` obrigatório	texto
`resourceId`	Id (texto)	8–160 caracteres · formato ^[A-Za-z0-9_]+$
`statusUrl` obrigatório	texto
`nextAction` obrigatório	"WAIT" \| "UPDATE_PAYMENT_METHOD" \| "COMPLETE_3DS" \| "CONTACT_SUPPORT" \| "NONE"
`challengeUrl`	texto	Somente URL obtida do provedor e validada.
`error`	Error
`error.code` obrigatório	texto	Código estável em UPPER_SNAKE.
`error.message` obrigatório	texto
`error.requestId` obrigatório	texto
`error.fieldErrors`	lista de objeto
`error.fieldErrors[].field` obrigatório	texto
`error.fieldErrors[].code` obrigatório	texto
`createdAt` obrigatório	data e hora (ISO 8601)	formato ^(?:(?:\d\d[2468][048]\|\d\d[13579][26]\|\d\d0[48]\|[02468][048]00\|[13579][26]00)-02-29\|\d{4}-(?:(?:0[13578]\|1[02])-(?:0[1-9]\|[12]\d\|3[01])\|(?:0[469]\|11)-(?:0[1-9]\|[12]\d\|30)\|(?:02)-(?:0[1-9]\|1\d\|2[0-8])))T(?:(?:[01]\d\|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z\|([+-](?:[01]\d\|2[0-3]):[0-5]\d)))$

Exemplo 202

{
  "id": "op_01JDY8D1B2C3D4E5F6G7H8J9KD",
  "status": "ACCEPTED",
  "kind": "SUBMIT_DISPUTE",
  "resourceId": "dsp_01JDYA21B2C3D4E5F6G7H8J9KB",
  "statusUrl": "/v1/operations/op_01JDY8D1B2C3D4E5F6G7H8J9KD",
  "nextAction": "WAIT",
  "createdAt": "2026-11-13T13:00:00.000Z"
}

Erros

Erros de submitDispute
HTTP	Exemplo de code	Quando
400	`INVALID_REQUEST`	Requisição inválida: fieldErrors aponta cada campo.
401	`INVALID_API_KEY`	Chave de API ausente, inválida, expirada ou revogada.
403	`SCOPE_MISSING`	Escopo ausente, conta não permitida em X-Account-Id, IP fora da lista ou conta suspensa.
404	`RESOURCE_NOT_FOUND`	Recurso inexistente nesta conta (inclusive recurso de outra conta ou de outro tenant).
409	`IDEMPOTENCY_CONFLICT`	Conflito de idempotência (IDEMPOTENCY_CONFLICT), requisição em andamento com a mesma chave (REQUEST_IN_PROGRESS) ou estado do recurso.
422	`CAPABILITY_UNAVAILABLE`	Regra de negócio ou capacidade indisponível para a conta.
429	`TOO_MANY_REQUESTS`	Limite de requisições da chave atingido (rajada de 100 e 6.000 por minuto). Toda resposta traz RateLimit-Limit, RateLimit-Remaining e RateLimit-Reset; o 429 traz Retry-After em segundos. Aguarde e repita com a mesma Idempotency-Key.

Anexar evidência (PDF, JPG ou PNG até 10 MB; corpo binário, nome em X-File-Name)

POST/v1/disputes/{id}/evidenceImplementada

Chave de API (Authorization: Bearer ep_…)· escopo refunds:write· uploadDisputeEvidence

Anexa um arquivo de evidência à disputa (PDF, JPG ou PNG até 10 MB) com o corpo binário e o nome em X-File-Name. O arquivo fica cifrado em armazenamento privado da conta; arquivos repetidos são reconhecidos pelo conteúdo.

Escopo da chave: refunds:write.

Idempotência: exige o header Idempotency-Key.

Headers de uploadDisputeEvidence
Header	Obrigatório	Descrição
`X-Account-Id`	sim	Conta permitida pelos grants do principal.
`Idempotency-Key`	sim	Chave única por intenção (16 a 128 caracteres visíveis). Ao refazer a mesma chamada, repita a mesma chave: o resultado gravado é devolvido. Mesma chave com outro conteúdo responde 409 IDEMPOTENCY_CONFLICT.

Parâmetros de uploadDisputeEvidence
Parâmetro	Onde	Tipo	Descrição
`id` obrigatório	caminho	Id (texto)	8–160 caracteres · formato ^[A-Za-z0-9_]+$
`Eclipta-Pay-Version`	header	"2026-11-13"	Versão de data do contrato. Opcional; a resposta sempre informa a versão usada. Valor desconhecido responde 400 UNSUPPORTED_API_VERSION.

Exemplo

curl -X POST "$ECLIPTA_PAY_API/v1/disputes/{id}/evidence" \
  -H "Authorization: Bearer $ECLIPTA_PAY_KEY" \
  -H "X-Account-Id: $ECLIPTA_PAY_ACCOUNT" \
  -H "Idempotency-Key: <uma chave por intenção>" \
  -H "Content-Type: application/json" \
  -d '{}'

Resposta 201: Recurso criado.

Campos da resposta 201 de uploadDisputeEvidence
Campo	Tipo	Descrição
`id` obrigatório	Id (texto)	8–160 caracteres · formato ^[A-Za-z0-9_]+$
`contentType` obrigatório	"application/pdf" \| "image/jpeg" \| "image/png"
`sizeBytes` obrigatório	inteiro	1 a 10000000
`sha256` obrigatório	texto	formato ^[a-f0-9]{64}$
`displayName` obrigatório	texto
`submittedAt` obrigatório	data e hora (ISO 8601) ou nulo
`createdAt` obrigatório	data e hora (ISO 8601)	formato ^(?:(?:\d\d[2468][048]\|\d\d[13579][26]\|\d\d0[48]\|[02468][048]00\|[13579][26]00)-02-29\|\d{4}-(?:(?:0[13578]\|1[02])-(?:0[1-9]\|[12]\d\|3[01])\|(?:0[469]\|11)-(?:0[1-9]\|[12]\d\|30)\|(?:02)-(?:0[1-9]\|1\d\|2[0-8])))T(?:(?:[01]\d\|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z\|([+-](?:[01]\d\|2[0-3]):[0-5]\d)))$

Exemplo 201

{
  "id": "evd_01JDYA31B2C3D4E5F6G7H8J9KC",
  "contentType": "application/pdf",
  "sizeBytes": 182311,
  "sha256": "9f2c4e0a7b1d3c5e8f6a2b4d6c8e0f1a3b5c7d9e1f2a4b6c8d0e2f4a6b8c0d2e",
  "displayName": "comprovante-entrega.pdf",
  "submittedAt": null,
  "createdAt": "2026-11-13T13:00:00.000Z"
}

Erros

Erros de uploadDisputeEvidence
HTTP	Exemplo de code	Quando
400	`INVALID_REQUEST`	Requisição inválida: fieldErrors aponta cada campo.
401	`INVALID_API_KEY`	Chave de API ausente, inválida, expirada ou revogada.
403	`SCOPE_MISSING`	Escopo ausente, conta não permitida em X-Account-Id, IP fora da lista ou conta suspensa.
404	`RESOURCE_NOT_FOUND`	Recurso inexistente nesta conta (inclusive recurso de outra conta ou de outro tenant).
409	`IDEMPOTENCY_CONFLICT`	Conflito de idempotência (IDEMPOTENCY_CONFLICT), requisição em andamento com a mesma chave (REQUEST_IN_PROGRESS) ou estado do recurso.
422	`CAPABILITY_UNAVAILABLE`	Regra de negócio ou capacidade indisponível para a conta.
429	`TOO_MANY_REQUESTS`	Limite de requisições da chave atingido (rajada de 100 e 6.000 por minuto). Toda resposta traz RateLimit-Limit, RateLimit-Remaining e RateLimit-Reset; o 429 traz Retry-After em segundos. Aguarde e repita com a mesma Idempotency-Key.

Todas as rotas