Referência da API

Estornos

Devoluções limitadas ao valor elegível.

Estornar cobrança (total ou parcial, limitado ao elegível)

POST/v1/payments/{id}/refundsImplementada

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

Pede o estorno total ou parcial de uma cobrança confirmada ou recebida. O valor fica reservado enquanto o estorno está ativo e nunca ultrapassa o elegível, mesmo com pedidos simultâneos. Responde 202 com a operação; o estorno só conta como devolvido quando o provedor conclui (DONE). O dinheiro sai do caixa pelo extrato, não pela resposta.

Escopo da chave: refunds:write.

Idempotência: exige o header Idempotency-Key.

Headers de createRefund
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 createRefund
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 createRefund
Campo	Tipo	Descrição
`amountCents` obrigatório	PositiveCents (texto)	Valor a devolver; limitado ao principal elegível (pago − devolvido − reservado). formato ^[1-9][0-9]{0,14}$
`reason` obrigatório	texto	Motivo interno; não é enviado ao provedor. 10–500 caracteres

Exemplo

curl -X POST "$ECLIPTA_PAY_API/v1/payments/{id}/refunds" \
  -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 '{"amountCents":"4990","reason":"Cliente desistiu da compra dentro do prazo."}'

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

Campos da resposta 202 de createRefund
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": "REFUND_PAYMENT",
  "resourceId": "rfd_01JDYA11B2C3D4E5F6G7H8J9KA",
  "statusUrl": "/v1/operations/op_01JDY8D1B2C3D4E5F6G7H8J9KD",
  "nextAction": "WAIT",
  "createdAt": "2026-11-13T13:00:00.000Z"
}

Erros

Erros de createRefund
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.

Estornos da cobrança (inclui os feitos fora do Eclipta Pay)

GET/v1/payments/{id}/refundsImplementada

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

Lista os estornos da cobrança, inclusive os feitos fora do Eclipta Pay e descobertos na consulta ao provedor, com situação e valor concluído.

Escopo da chave: payments:read.

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

Parâmetros de listPaymentRefunds
Parâmetro	Onde	Tipo	Descrição
`id` obrigatório	caminho	Id (texto)	8–160 caracteres · formato ^[A-Za-z0-9_]+$
`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/payments/{id}/refunds" \
  -H "Authorization: Bearer $ECLIPTA_PAY_KEY" \
  -H "X-Account-Id: $ECLIPTA_PAY_ACCOUNT"

Resposta 200: Sucesso.

Campos da resposta 200 de listPaymentRefunds
Campo	Tipo	Descrição
`data` obrigatório	lista de Refund
`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	"REQUESTED" \| "PENDING" \| "UNKNOWN" \| "MANUAL_REVIEW" \| "DONE" \| "CANCELLED" \| "FAILED"	Só DONE é devolução concluída (REF-002); PENDING/UNKNOWN reservam o valor.
`data[].display` obrigatório	objeto
`data[].display.label` obrigatório	texto
`data[].display.variant` obrigatório	"info" \| "warn" \| "accent" \| "ok" \| "bad" \| "neutral"
`data[].origin` obrigatório	"API" \| "PROVIDER"	PROVIDER: estorno feito fora do Eclipta Pay, descoberto na conciliação.
`data[].scope` obrigatório	"PAYMENT" \| "INSTALLMENT" \| "BANK_SLIP"
`data[].requestedCents` obrigatório	PositiveCents (texto)	formato ^[1-9][0-9]{0,14}$
`data[].completedCents` obrigatório	Cents (texto)	formato ^(0\|[1-9][0-9]{0,14})$
`data[].operationId` obrigatório	Id (texto) ou nulo
`data[].providerStatus` obrigatório	texto ou nulo
`data[].payerActionUrl` obrigatório	texto ou nulo	Boleto: link do provedor para o pagador informar a conta de devolução.
`data[].receiptUrl` obrigatório	texto ou nulo
`data[].failureCode` obrigatório	texto ou nulo
`data[].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[].completedAt` obrigatório	data e hora (ISO 8601) ou nulo
`data[].version` obrigatório	inteiro	1 a 9007199254740991
`nextCursor` obrigatório	texto ou nulo

Exemplo 200

{
  "data": [
    {
      "id": "rfd_01JDYA11B2C3D4E5F6G7H8J9KA",
      "paymentId": "pay_01JDY8C1B2C3D4E5F6G7H8J9KC",
      "status": "PENDING",
      "display": {
        "label": "Estorno em andamento",
        "variant": "info"
      },
      "origin": "API",
      "scope": "PAYMENT",
      "requestedCents": "4990",
      "completedCents": "0",
      "operationId": "op_01JDY8D1B2C3D4E5F6G7H8J9KD",
      "providerStatus": "PENDING",
      "payerActionUrl": null,
      "receiptUrl": null,
      "failureCode": null,
      "createdAt": "2026-11-13T13:00:00.000Z",
      "completedAt": null,
      "version": 2
    }
  ],
  "nextCursor": null
}

Erros

Erros de listPaymentRefunds
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.

Consultar estorno

GET/v1/refunds/{id}Implementada

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

Consulta um estorno: valor pedido e concluído, situação no provedor, comprovante quando houver e, para boleto, o link em que o pagador informa os dados bancários.

Escopo da chave: payments:read.

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

Parâmetros de getRefund
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/refunds/{id}" \
  -H "Authorization: Bearer $ECLIPTA_PAY_KEY" \
  -H "X-Account-Id: $ECLIPTA_PAY_ACCOUNT"

Resposta 200: Sucesso.

Campos da resposta 200 de getRefund
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	"REQUESTED" \| "PENDING" \| "UNKNOWN" \| "MANUAL_REVIEW" \| "DONE" \| "CANCELLED" \| "FAILED"	Só DONE é devolução concluída (REF-002); PENDING/UNKNOWN reservam o valor.
`display` obrigatório	objeto
`display.label` obrigatório	texto
`display.variant` obrigatório	"info" \| "warn" \| "accent" \| "ok" \| "bad" \| "neutral"
`origin` obrigatório	"API" \| "PROVIDER"	PROVIDER: estorno feito fora do Eclipta Pay, descoberto na conciliação.
`scope` obrigatório	"PAYMENT" \| "INSTALLMENT" \| "BANK_SLIP"
`requestedCents` obrigatório	PositiveCents (texto)	formato ^[1-9][0-9]{0,14}$
`completedCents` obrigatório	Cents (texto)	formato ^(0\|[1-9][0-9]{0,14})$
`operationId` obrigatório	Id (texto) ou nulo
`providerStatus` obrigatório	texto ou nulo
`payerActionUrl` obrigatório	texto ou nulo	Boleto: link do provedor para o pagador informar a conta de devolução.
`receiptUrl` obrigatório	texto ou nulo
`failureCode` obrigatório	texto 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)))$
`completedAt` obrigatório	data e hora (ISO 8601) ou nulo
`version` obrigatório	inteiro	1 a 9007199254740991

Exemplo 200

{
  "id": "rfd_01JDYA11B2C3D4E5F6G7H8J9KA",
  "paymentId": "pay_01JDY8C1B2C3D4E5F6G7H8J9KC",
  "status": "PENDING",
  "display": {
    "label": "Estorno em andamento",
    "variant": "info"
  },
  "origin": "API",
  "scope": "PAYMENT",
  "requestedCents": "4990",
  "completedCents": "0",
  "operationId": "op_01JDY8D1B2C3D4E5F6G7H8J9KD",
  "providerStatus": "PENDING",
  "payerActionUrl": null,
  "receiptUrl": null,
  "failureCode": null,
  "createdAt": "2026-11-13T13:00:00.000Z",
  "completedAt": null,
  "version": 2
}

Erros

Erros de getRefund
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.

Todas as rotas