Referência da API

Assinaturas

Recorrência SaaS.

Criar assinatura SaaS

POST/v1/subscriptionsImplementada

Chave de API (Authorization: Bearer ep_…)· escopo subscriptions:write· createSubscription

Cria uma assinatura recorrente do seu cliente sobre a recorrência do provedor. A assinatura é a fonte única das cobranças que gera: cada cobrança é vinculada uma só vez, mesmo com webhook repetido ou fora de ordem. Cartão exige captura pelo card-edge com uso SUBSCRIPTION e consentimento.

Escopo da chave: subscriptions:write.

Idempotência: exige o header Idempotency-Key.

Headers de createSubscription
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 createSubscription
Parâmetro	Onde	Tipo	Descrição
`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 createSubscription
Campo	Tipo	Descrição
`customerId` obrigatório	Id (texto)	8–160 caracteres · formato ^[A-Za-z0-9_]+$
`method`	"CREDIT_CARD" \| "PIX" \| "BOLETO"	padrão "CREDIT_CARD"
`paymentMethodId`	Id (texto)	Obrigatório no cartão: handle do card-edge com uso SUBSCRIPTION. 8–160 caracteres · formato ^[A-Za-z0-9_]+$
`amountCents` obrigatório	PositiveCents (texto)	formato ^[1-9][0-9]{0,14}$
`cycle` obrigatório	"WEEKLY" \| "BIWEEKLY" \| "MONTHLY" \| "BIMONTHLY" \| "QUARTERLY" \| "SEMIANNUALLY" \| "YEARLY"
`nextDueDate` obrigatório	texto	formato ^\d{4}-\d{2}-\d{2}$
`endDate`	texto	formato ^\d{4}-\d{2}-\d{2}$
`maxPayments`	inteiro	1 a 1000
`description`	texto	0–500 caracteres
`externalReference`	texto	1–100 caracteres
`consent`	SubscriptionConsent	Obrigatório no cartão (recorrência autorizada pelo pagador).
`consent.termsVersion` obrigatório	texto	1–∞ caracteres
`consent.accepted` obrigatório	true
`consent.displayedTermsHash` obrigatório	texto	SHA-256 dos termos exibidos (método, valor, ciclo, datas), conferido no servidor. formato ^[a-f0-9]{64}$

Exemplo

curl -X POST "$ECLIPTA_PAY_API/v1/subscriptions" \
  -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 '{"customerId":"cus_01JDY8A1B2C3D4E5F6G7H8J9KA","method":"PIX","amountCents":"9900","cycle":"MONTHLY","nextDueDate":"2026-12-10","description":"Plano Órbita Pro","externalReference":"assinatura-42"}'

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

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

Erros

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

Listar assinaturas (com MRR)

GET/v1/subscriptionsImplementada

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

Lista as assinaturas da conta com situação, próximo vencimento e receita recorrente mensal (MRR) calculada só com assinaturas ativas.

Escopo da chave: payments:read.

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

Parâmetros de listSubscriptions
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/subscriptions" \
  -H "Authorization: Bearer $ECLIPTA_PAY_KEY" \
  -H "X-Account-Id: $ECLIPTA_PAY_ACCOUNT"

Resposta 200: Sucesso.

Campos da resposta 200 de listSubscriptions
Campo	Tipo	Descrição
`data` obrigatório	lista de Subscription
`data[].id` obrigatório	Id (texto)	8–160 caracteres · formato ^[A-Za-z0-9_]+$
`data[].customerId` obrigatório	Id (texto)	8–160 caracteres · formato ^[A-Za-z0-9_]+$
`data[].method` obrigatório	texto
`data[].status` obrigatório	"PENDING" \| "ACTIVE" \| "PAUSED" \| "INACTIVE" \| "EXPIRED" \| "BLOCKED_SPLIT" \| "CANCELLED" \| "FAILED"
`data[].display` obrigatório	objeto
`data[].display.label` obrigatório	texto
`data[].display.variant` obrigatório	"info" \| "warn" \| "accent" \| "ok" \| "bad" \| "neutral"
`data[].amountCents` obrigatório	PositiveCents (texto)	formato ^[1-9][0-9]{0,14}$
`data[].mrrCents` obrigatório	Cents (texto)	Valor normalizado para 30 dias (painel). formato ^(0\|[1-9][0-9]{0,14})$
`data[].cycle` obrigatório	"WEEKLY" \| "BIWEEKLY" \| "MONTHLY" \| "BIMONTHLY" \| "QUARTERLY" \| "SEMIANNUALLY" \| "YEARLY"
`data[].nextDueDate` obrigatório	texto ou nulo
`data[].endDate` obrigatório	texto ou nulo
`data[].maxPayments` obrigatório	inteiro ou nulo
`data[].description` obrigatório	texto ou nulo
`data[].externalReference` obrigatório	texto ou nulo
`data[].operationId` obrigatório	Id (texto)	8–160 caracteres · formato ^[A-Za-z0-9_]+$
`data[].feePolicyVersion` obrigatório	inteiro	Versão congelada no template (SUB-002). -9007199254740991 a 9007199254740991
`data[].templateVersion` obrigatório	inteiro	1 a 9007199254740991
`data[].splitDisabled` obrigatório	booleano
`data[].chargesCount` obrigatório	inteiro	0 a 9007199254740991
`data[].cancelledAt` obrigatório	data e hora (ISO 8601) 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[].version` obrigatório	inteiro	1 a 9007199254740991
`nextCursor` obrigatório	texto ou nulo

Exemplo 200

{
  "data": [
    {
      "id": "sub_01JDYA41B2C3D4E5F6G7H8J9KD",
      "customerId": "cus_01JDY8A1B2C3D4E5F6G7H8J9KA",
      "method": "PIX",
      "status": "ACTIVE",
      "display": {
        "label": "Ativa",
        "variant": "ok"
      },
      "amountCents": "9900",
      "mrrCents": "9900",
      "cycle": "MONTHLY",
      "nextDueDate": "2026-12-10",
      "endDate": null,
      "maxPayments": null,
      "description": "Plano Órbita Pro",
      "externalReference": "assinatura-42",
      "operationId": "op_01JDY8D1B2C3D4E5F6G7H8J9KD",
      "feePolicyVersion": 1,
      "templateVersion": 1,
      "splitDisabled": false,
      "chargesCount": 3,
      "cancelledAt": null,
      "createdAt": "2026-11-13T13:00:00.000Z",
      "version": 4
    }
  ],
  "nextCursor": null
}

Erros

Erros de listSubscriptions
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 assinatura

GET/v1/subscriptions/{id}Implementada

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

Consulta uma assinatura: valor, ciclo, próximo vencimento, método e situação no provedor.

Escopo da chave: payments:read.

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

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

Resposta 200: Sucesso.

Campos da resposta 200 de getSubscription
Campo	Tipo	Descrição
`id` obrigatório	Id (texto)	8–160 caracteres · formato ^[A-Za-z0-9_]+$
`customerId` obrigatório	Id (texto)	8–160 caracteres · formato ^[A-Za-z0-9_]+$
`method` obrigatório	texto
`status` obrigatório	"PENDING" \| "ACTIVE" \| "PAUSED" \| "INACTIVE" \| "EXPIRED" \| "BLOCKED_SPLIT" \| "CANCELLED" \| "FAILED"
`display` obrigatório	objeto
`display.label` obrigatório	texto
`display.variant` obrigatório	"info" \| "warn" \| "accent" \| "ok" \| "bad" \| "neutral"
`amountCents` obrigatório	PositiveCents (texto)	formato ^[1-9][0-9]{0,14}$
`mrrCents` obrigatório	Cents (texto)	Valor normalizado para 30 dias (painel). formato ^(0\|[1-9][0-9]{0,14})$
`cycle` obrigatório	"WEEKLY" \| "BIWEEKLY" \| "MONTHLY" \| "BIMONTHLY" \| "QUARTERLY" \| "SEMIANNUALLY" \| "YEARLY"
`nextDueDate` obrigatório	texto ou nulo
`endDate` obrigatório	texto ou nulo
`maxPayments` obrigatório	inteiro ou nulo
`description` obrigatório	texto ou nulo
`externalReference` obrigatório	texto ou nulo
`operationId` obrigatório	Id (texto)	8–160 caracteres · formato ^[A-Za-z0-9_]+$
`feePolicyVersion` obrigatório	inteiro	Versão congelada no template (SUB-002). -9007199254740991 a 9007199254740991
`templateVersion` obrigatório	inteiro	1 a 9007199254740991
`splitDisabled` obrigatório	booleano
`chargesCount` obrigatório	inteiro	0 a 9007199254740991
`cancelledAt` 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)))$
`version` obrigatório	inteiro	1 a 9007199254740991

Exemplo 200

{
  "id": "sub_01JDYA41B2C3D4E5F6G7H8J9KD",
  "customerId": "cus_01JDY8A1B2C3D4E5F6G7H8J9KA",
  "method": "PIX",
  "status": "ACTIVE",
  "display": {
    "label": "Ativa",
    "variant": "ok"
  },
  "amountCents": "9900",
  "mrrCents": "9900",
  "cycle": "MONTHLY",
  "nextDueDate": "2026-12-10",
  "endDate": null,
  "maxPayments": null,
  "description": "Plano Órbita Pro",
  "externalReference": "assinatura-42",
  "operationId": "op_01JDY8D1B2C3D4E5F6G7H8J9KD",
  "feePolicyVersion": 1,
  "templateVersion": 1,
  "splitDisabled": false,
  "chargesCount": 3,
  "cancelledAt": null,
  "createdAt": "2026-11-13T13:00:00.000Z",
  "version": 4
}

Erros

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

Alterar valor, ciclo ou vencimento (só cobranças futuras)

PATCH/v1/subscriptions/{id}Implementada

Chave de API (Authorization: Bearer ep_…)· escopo subscriptions:write· updateSubscription

Altera valor, ciclo ou próximo vencimento. A mudança vale só para cobranças futuras; as já geradas não mudam. Responde 202 com a operação.

Escopo da chave: subscriptions:write.

Idempotência: exige o header Idempotency-Key.

Headers de updateSubscription
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 updateSubscription
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 updateSubscription
Campo	Tipo	Descrição
`amountCents`	PositiveCents (texto)	formato ^[1-9][0-9]{0,14}$
`cycle`	"WEEKLY" \| "BIWEEKLY" \| "MONTHLY" \| "BIMONTHLY" \| "QUARTERLY" \| "SEMIANNUALLY" \| "YEARLY"
`nextDueDate`	texto	formato ^\d{4}-\d{2}-\d{2}$
`description`	texto ou nulo
`refreshFeePolicy`	booleano	Aplica a política de tarifa vigente às próximas cobranças (auditado; as já geradas não mudam).
`expectedVersion` obrigatório	inteiro	1 a 9007199254740991

Exemplo

curl -X PATCH "$ECLIPTA_PAY_API/v1/subscriptions/{id}" \
  -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":"11900","expectedVersion":4}'

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

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

Erros

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

Cancelar assinatura

POST/v1/subscriptions/{id}/cancelImplementada

Chave de API (Authorization: Bearer ep_…)· escopo subscriptions:write· cancelSubscription

Cancela a assinatura no provedor. Cobranças já geradas não são canceladas automaticamente. Responde 202 com a operação.

Escopo da chave: subscriptions:write.

Idempotência: exige o header Idempotency-Key.

Headers de cancelSubscription
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 cancelSubscription
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 cancelSubscription
Campo	Tipo	Descrição
`reason` obrigatório	texto	10–500 caracteres
`expectedVersion` obrigatório	inteiro	1 a 9007199254740991

Exemplo

curl -X POST "$ECLIPTA_PAY_API/v1/subscriptions/{id}/cancel" \
  -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 '{"reason":"Cliente encerrou o contrato.","expectedVersion":4}'

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

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

Erros

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

Pausar (para de gerar cobranças; existentes mantidas)

POST/v1/subscriptions/{id}/pauseImplementada

Chave de API (Authorization: Bearer ep_…)· escopo subscriptions:write· pauseSubscription

Pausa a assinatura: novas cobranças deixam de ser geradas e as existentes continuam valendo. Responde 202 com a operação.

Escopo da chave: subscriptions:write.

Idempotência: exige o header Idempotency-Key.

Headers de pauseSubscription
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 pauseSubscription
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 pauseSubscription
Campo	Tipo	Descrição
`reason` obrigatório	texto	10–500 caracteres
`expectedVersion` obrigatório	inteiro	1 a 9007199254740991

Exemplo

curl -X POST "$ECLIPTA_PAY_API/v1/subscriptions/{id}/pause" \
  -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 '{"reason":"Cliente pediu pausa de dois meses.","expectedVersion":4}'

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

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

Erros

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

Retomar com novo vencimento

POST/v1/subscriptions/{id}/resumeImplementada

Chave de API (Authorization: Bearer ep_…)· escopo subscriptions:write· resumeSubscription

Retoma uma assinatura pausada a partir de um novo vencimento. Responde 202 com a operação.

Escopo da chave: subscriptions:write.

Idempotência: exige o header Idempotency-Key.

Headers de resumeSubscription
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 resumeSubscription
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 resumeSubscription
Campo	Tipo	Descrição
`nextDueDate` obrigatório	texto	formato ^\d{4}-\d{2}-\d{2}$
`expectedVersion` obrigatório	inteiro	1 a 9007199254740991

Exemplo

curl -X POST "$ECLIPTA_PAY_API/v1/subscriptions/{id}/resume" \
  -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 '{"nextDueDate":"2027-02-10","expectedVersion":5}'

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

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

Erros

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

Cobranças geradas pela assinatura

GET/v1/subscriptions/{id}/paymentsImplementada

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

Lista as cobranças geradas pela assinatura, na ordem de vencimento.

Escopo da chave: payments:read.

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

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

Resposta 200: Sucesso.

Campos da resposta 200 de listSubscriptionPayments
Campo	Tipo	Descrição
`data` obrigatório	lista de SubscriptionCharge
`data[].paymentId` obrigatório	Id (texto)	8–160 caracteres · formato ^[A-Za-z0-9_]+$
`data[].orderId` obrigatório	Id (texto)	8–160 caracteres · formato ^[A-Za-z0-9_]+$
`data[].status` obrigatório	texto
`data[].reversalStatus` obrigatório	texto
`data[].amountCents` obrigatório	PositiveCents (texto)	formato ^[1-9][0-9]{0,14}$
`data[].dueDate` obrigatório	texto	formato ^\d{4}-\d{2}-\d{2}$
`data[].feePolicyVersion` obrigatório	inteiro	-9007199254740991 a 9007199254740991
`data[].templateVersion` obrigatório	inteiro	-9007199254740991 a 9007199254740991
`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)))$
`nextCursor` obrigatório	texto ou nulo

Exemplo 200

{
  "data": [
    {
      "paymentId": "pay_01JDY8C1B2C3D4E5F6G7H8J9KC",
      "orderId": "ord_01JDY8B1B2C3D4E5F6G7H8J9KB",
      "status": "RECEIVED",
      "reversalStatus": "NONE",
      "amountCents": "9900",
      "dueDate": "2026-11-10",
      "feePolicyVersion": 1,
      "templateVersion": 1,
      "createdAt": "2026-11-13T13:00:00.000Z"
    }
  ],
  "nextCursor": null
}

Erros

Erros de listSubscriptionPayments
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