Referência da API

Planos

Pix em parcelas e parcelamento mensal no cartão.

Criar Pix em parcelas ou parcelamento mensal no cartão

POST/v1/payment-plansImplementada

Chave de API (Authorization: Bearer ep_…)· escopo plans:write· createPlan

Cria um Pix em parcelas (PIX_SCHEDULE, parcelamento nativo com QR por parcela) ou um parcelamento mensal no cartão (CARD_MONTHLY_PLAN, cobrado pelo agendador da Eclipta Pay). Exige o aceite com o hash do calendário exibido. Não é financiamento: o pedido só é liberado com todas as parcelas pagas. PIX_FINANCED responde CAPABILITY_UNAVAILABLE. Responde 202 com a operação.

Escopo da chave: plans:write.

Idempotência: exige o header Idempotency-Key.

Headers de createPlan
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 createPlan
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 createPlan
Campo	Tipo	Descrição
`orderId` obrigatório	Id (texto)	8–160 caracteres · formato ^[A-Za-z0-9_]+$
`mode` obrigatório	"PIX_SCHEDULE" \| "CARD_MONTHLY_PLAN" \| "PIX_FINANCED"	PIX_FINANCED responde 422 CAPABILITY_UNAVAILABLE (PXP-004).
`count` obrigatório	inteiro	2 a 180
`firstDueDate`	texto	Padrão: hoje no fuso do plano (a primeira parcela é cobrada já). formato ^\d{4}-\d{2}-\d{2}$
`paymentMethodId`	Id (texto)	8–160 caracteres · formato ^[A-Za-z0-9_]+$
`consent` obrigatório	Consent
`consent.termsVersion` obrigatório	texto	1–∞ caracteres
`consent.accepted` obrigatório	true
`consent.displayedScheduleHash` obrigatório	texto	formato ^[a-f0-9]{64}$

Exemplo

curl -X POST "$ECLIPTA_PAY_API/v1/payment-plans" \
  -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 '{"orderId":"ord_01JDY8B1B2C3D4E5F6G7H8J9KB","mode":"PIX_SCHEDULE","count":3,"firstDueDate":"2026-11-20","consent":{"termsVersion":"pix-parcelas-2026-11-14","accepted":true,"displayedScheduleHash":"3b1f6c0e9a2d4b7c8e5f1a0d2c4b6e8f0a1c3e5b7d9f2a4c6e8b0d1f3a5c7e9b"}}'

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

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

Erros

Erros de createPlan
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 planos (filtro por pedido)

GET/v1/payment-plansImplementada

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

Lista os planos da conta, com filtro opcional por pedido (orderId), incluindo o calendário e a situação de cada parcela.

Escopo da chave: payments:read.

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

Parâmetros de listPlans
Parâmetro	Onde	Tipo	Descrição
`cursor`	query	texto	0–200 caracteres
`limit`	query	inteiro	1 a 100 · padrão 20
`orderId`	query	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/payment-plans" \
  -H "Authorization: Bearer $ECLIPTA_PAY_KEY" \
  -H "X-Account-Id: $ECLIPTA_PAY_ACCOUNT"

Resposta 200: Sucesso.

Campos da resposta 200 de listPlans
Campo	Tipo	Descrição
`data` obrigatório	lista de Plan
`data[].id` 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[].mode` obrigatório	"PIX_SCHEDULE" \| "CARD_MONTHLY_PLAN"
`data[].status` obrigatório	"PENDING_CONSENT" \| "PENDING_ACTIVATION" \| "ACTIVE" \| "SUSPENDED" \| "CANCELLED" \| "COMPLETED" \| "FAILED"
`data[].totalCents` obrigatório	PositiveCents (texto)	formato ^[1-9][0-9]{0,14}$
`data[].paidCents` obrigatório	Cents (texto)	Só parcelas pagas; futuras são previsão com risco, sem antecipação (PXP-003). formato ^(0\|[1-9][0-9]{0,14})$
`data[].count` obrigatório	inteiro	2 a 9007199254740991
`data[].anchorDay` obrigatório	inteiro	1 a 31
`data[].timezone` obrigatório	texto
`data[].firstDueDate` obrigatório	texto	formato ^\d{4}-\d{2}-\d{2}$
`data[].nextDueDate` obrigatório	texto ou nulo
`data[].termsVersion` obrigatório	texto
`data[].scheduleHash` obrigatório	texto	formato ^[a-f0-9]{64}$
`data[].paymentMethod` obrigatório	objeto ou nulo
`data[].dunningPolicy` obrigatório	objeto ou nulo
`data[].scheduleDivergence` obrigatório	booleano	Datas/valores do provedor diferentes do calendário aceito (BLK-07).
`data[].suspendedReason` obrigatório	texto ou nulo
`data[].cancelledAt` obrigatório	data e hora (ISO 8601) ou nulo
`data[].installments` obrigatório	lista de PlanInstallment
`data[].installments[].id` obrigatório	Id (texto)	8–160 caracteres · formato ^[A-Za-z0-9_]+$
`data[].installments[].index` obrigatório	inteiro	1 a 9007199254740991
`data[].installments[].dueDate` obrigatório	texto	formato ^\d{4}-\d{2}-\d{2}$
`data[].installments[].amountCents` obrigatório	PositiveCents (texto)	formato ^[1-9][0-9]{0,14}$
`data[].installments[].status` obrigatório	"SCHEDULED" \| "IN_PROGRESS" \| "PAID" \| "DECLINED" \| "PAST_DUE" \| "UNKNOWN" \| "WAIVED" \| "CANCELLED"
`data[].installments[].display` obrigatório	objeto
`data[].installments[].display.label` obrigatório	texto
`data[].installments[].display.variant` obrigatório	"info" \| "warn" \| "accent" \| "ok" \| "bad" \| "neutral"
`data[].installments[].paymentId` obrigatório	Id (texto) ou nulo
`data[].installments[].attempts` obrigatório	inteiro	0 a 9007199254740991
`data[].installments[].paidAt` obrigatório	data e hora (ISO 8601) ou nulo
`data[].version` obrigatório	inteiro	1 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)))$
`data[].asOf` 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": [
    {
      "id": "pln_01JDYB41B2C3D4E5F6G7H8J9KD",
      "orderId": "ord_01JDY8B1B2C3D4E5F6G7H8J9KB",
      "mode": "PIX_SCHEDULE",
      "status": "ACTIVE",
      "totalCents": "30000",
      "paidCents": "10000",
      "count": 3,
      "anchorDay": 20,
      "timezone": "America/Sao_Paulo",
      "firstDueDate": "2026-11-20",
      "nextDueDate": "2026-12-20",
      "termsVersion": "pix-parcelas-2026-11-14",
      "scheduleHash": "3b1f6c0e9a2d4b7c8e5f1a0d2c4b6e8f0a1c3e5b7d9f2a4c6e8b0d1f3a5c7e9b",
      "paymentMethod": null,
      "dunningPolicy": null,
      "scheduleDivergence": false,
      "suspendedReason": null,
      "cancelledAt": null,
      "installments": [
        {
          "id": "pli_01JDYB51B2C3D4E5F6G7H8J9KE",
          "index": 1,
          "dueDate": "2026-11-20",
          "amountCents": "10000",
          "status": "PAID",
          "display": {
            "label": "Paga",
            "variant": "ok"
          },
          "paymentId": "pay_01JDY8C1B2C3D4E5F6G7H8J9KC",
          "attempts": 1,
          "paidAt": "2026-11-13T13:00:00.000Z"
        },
        {
          "id": "pli_01JDYB52B2C3D4E5F6G7H8J9KF",
          "index": 2,
          "dueDate": "2026-12-20",
          "amountCents": "10000",
          "status": "SCHEDULED",
          "display": {
            "label": "Agendada",
            "variant": "neutral"
          },
          "paymentId": null,
          "attempts": 0,
          "paidAt": null
        },
        {
          "id": "pli_01JDYB53B2C3D4E5F6G7H8J9KG",
          "index": 3,
          "dueDate": "2027-01-20",
          "amountCents": "10000",
          "status": "SCHEDULED",
          "display": {
            "label": "Agendada",
            "variant": "neutral"
          },
          "paymentId": null,
          "attempts": 0,
          "paidAt": null
        }
      ],
      "version": 3,
      "createdAt": "2026-11-13T13:00:00.000Z",
      "asOf": "2026-11-13T13:00:00.000Z"
    }
  ],
  "nextCursor": null
}

Erros

Erros de listPlans
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 plano

GET/v1/payment-plans/{id}Implementada

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

Consulta um plano: total, valor pago, próxima parcela e situação de cada uma. No cartão mensal, a política de novas tentativas aparece como proposta não aprovada enquanto não houver decisão comercial (BLK-15).

Escopo da chave: payments:read.

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

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

Resposta 200: Sucesso.

Campos da resposta 200 de getPlan
Campo	Tipo	Descrição
`id` obrigatório	Id (texto)	8–160 caracteres · formato ^[A-Za-z0-9_]+$
`orderId` obrigatório	Id (texto)	8–160 caracteres · formato ^[A-Za-z0-9_]+$
`mode` obrigatório	"PIX_SCHEDULE" \| "CARD_MONTHLY_PLAN"
`status` obrigatório	"PENDING_CONSENT" \| "PENDING_ACTIVATION" \| "ACTIVE" \| "SUSPENDED" \| "CANCELLED" \| "COMPLETED" \| "FAILED"
`totalCents` obrigatório	PositiveCents (texto)	formato ^[1-9][0-9]{0,14}$
`paidCents` obrigatório	Cents (texto)	Só parcelas pagas; futuras são previsão com risco, sem antecipação (PXP-003). formato ^(0\|[1-9][0-9]{0,14})$
`count` obrigatório	inteiro	2 a 9007199254740991
`anchorDay` obrigatório	inteiro	1 a 31
`timezone` obrigatório	texto
`firstDueDate` obrigatório	texto	formato ^\d{4}-\d{2}-\d{2}$
`nextDueDate` obrigatório	texto ou nulo
`termsVersion` obrigatório	texto
`scheduleHash` obrigatório	texto	formato ^[a-f0-9]{64}$
`paymentMethod` obrigatório	objeto ou nulo
`dunningPolicy` obrigatório	objeto ou nulo
`scheduleDivergence` obrigatório	booleano	Datas/valores do provedor diferentes do calendário aceito (BLK-07).
`suspendedReason` obrigatório	texto ou nulo
`cancelledAt` obrigatório	data e hora (ISO 8601) ou nulo
`installments` obrigatório	lista de PlanInstallment
`installments[].id` obrigatório	Id (texto)	8–160 caracteres · formato ^[A-Za-z0-9_]+$
`installments[].index` obrigatório	inteiro	1 a 9007199254740991
`installments[].dueDate` obrigatório	texto	formato ^\d{4}-\d{2}-\d{2}$
`installments[].amountCents` obrigatório	PositiveCents (texto)	formato ^[1-9][0-9]{0,14}$
`installments[].status` obrigatório	"SCHEDULED" \| "IN_PROGRESS" \| "PAID" \| "DECLINED" \| "PAST_DUE" \| "UNKNOWN" \| "WAIVED" \| "CANCELLED"
`installments[].display` obrigatório	objeto
`installments[].display.label` obrigatório	texto
`installments[].display.variant` obrigatório	"info" \| "warn" \| "accent" \| "ok" \| "bad" \| "neutral"
`installments[].paymentId` obrigatório	Id (texto) ou nulo
`installments[].attempts` obrigatório	inteiro	0 a 9007199254740991
`installments[].paidAt` obrigatório	data e hora (ISO 8601) ou nulo
`version` obrigatório	inteiro	1 a 9007199254740991
`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)))$
`asOf` 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 200

{
  "id": "pln_01JDYB41B2C3D4E5F6G7H8J9KD",
  "orderId": "ord_01JDY8B1B2C3D4E5F6G7H8J9KB",
  "mode": "PIX_SCHEDULE",
  "status": "ACTIVE",
  "totalCents": "30000",
  "paidCents": "10000",
  "count": 3,
  "anchorDay": 20,
  "timezone": "America/Sao_Paulo",
  "firstDueDate": "2026-11-20",
  "nextDueDate": "2026-12-20",
  "termsVersion": "pix-parcelas-2026-11-14",
  "scheduleHash": "3b1f6c0e9a2d4b7c8e5f1a0d2c4b6e8f0a1c3e5b7d9f2a4c6e8b0d1f3a5c7e9b",
  "paymentMethod": null,
  "dunningPolicy": null,
  "scheduleDivergence": false,
  "suspendedReason": null,
  "cancelledAt": null,
  "installments": [
    {
      "id": "pli_01JDYB51B2C3D4E5F6G7H8J9KE",
      "index": 1,
      "dueDate": "2026-11-20",
      "amountCents": "10000",
      "status": "PAID",
      "display": {
        "label": "Paga",
        "variant": "ok"
      },
      "paymentId": "pay_01JDY8C1B2C3D4E5F6G7H8J9KC",
      "attempts": 1,
      "paidAt": "2026-11-13T13:00:00.000Z"
    },
    {
      "id": "pli_01JDYB52B2C3D4E5F6G7H8J9KF",
      "index": 2,
      "dueDate": "2026-12-20",
      "amountCents": "10000",
      "status": "SCHEDULED",
      "display": {
        "label": "Agendada",
        "variant": "neutral"
      },
      "paymentId": null,
      "attempts": 0,
      "paidAt": null
    },
    {
      "id": "pli_01JDYB53B2C3D4E5F6G7H8J9KG",
      "index": 3,
      "dueDate": "2027-01-20",
      "amountCents": "10000",
      "status": "SCHEDULED",
      "display": {
        "label": "Agendada",
        "variant": "neutral"
      },
      "paymentId": null,
      "attempts": 0,
      "paidAt": null
    }
  ],
  "version": 3,
  "createdAt": "2026-11-13T13:00:00.000Z",
  "asOf": "2026-11-13T13:00:00.000Z"
}

Erros

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

Trocar cartão do plano

PUT/v1/payment-plans/{id}/payment-methodImplementada

Chave de API (Authorization: Bearer ep_…)· escopo plans:write· replacePlanCard

Troca o cartão do cartão mensal para as próximas cobranças, com novo aceite. Parcelas já pagas não mudam; uma parcela em andamento termina no cartão anterior.

Escopo da chave: plans:write.

Idempotência: exige o header Idempotency-Key.

Headers de replacePlanCard
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 replacePlanCard
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 replacePlanCard
Campo	Tipo	Descrição
`paymentMethodId` obrigatório	Id (texto)	8–160 caracteres · formato ^[A-Za-z0-9_]+$
`consent` obrigatório	Consent
`consent.termsVersion` obrigatório	texto	1–∞ caracteres
`consent.accepted` obrigatório	true
`consent.displayedScheduleHash` obrigatório	texto	formato ^[a-f0-9]{64}$
`expectedVersion` obrigatório	inteiro	1 a 9007199254740991

Exemplo

curl -X PUT "$ECLIPTA_PAY_API/v1/payment-plans/{id}/payment-method" \
  -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 '{"paymentMethodId":"pm_01JDYB61B2C3D4E5F6G7H8J9KF","consent":{"termsVersion":"cartao-mensal-2026-11-14","accepted":true,"displayedScheduleHash":"3b1f6c0e9a2d4b7c8e5f1a0d2c4b6e8f0a1c3e5b7d9f2a4c6e8b0d1f3a5c7e9b"},"expectedVersion":3}'

Resposta 200: Sucesso.

Campos da resposta 200 de replacePlanCard
Campo	Tipo	Descrição
`id` obrigatório	Id (texto)	8–160 caracteres · formato ^[A-Za-z0-9_]+$
`orderId` obrigatório	Id (texto)	8–160 caracteres · formato ^[A-Za-z0-9_]+$
`mode` obrigatório	"PIX_SCHEDULE" \| "CARD_MONTHLY_PLAN"
`status` obrigatório	"PENDING_CONSENT" \| "PENDING_ACTIVATION" \| "ACTIVE" \| "SUSPENDED" \| "CANCELLED" \| "COMPLETED" \| "FAILED"
`totalCents` obrigatório	PositiveCents (texto)	formato ^[1-9][0-9]{0,14}$
`paidCents` obrigatório	Cents (texto)	Só parcelas pagas; futuras são previsão com risco, sem antecipação (PXP-003). formato ^(0\|[1-9][0-9]{0,14})$
`count` obrigatório	inteiro	2 a 9007199254740991
`anchorDay` obrigatório	inteiro	1 a 31
`timezone` obrigatório	texto
`firstDueDate` obrigatório	texto	formato ^\d{4}-\d{2}-\d{2}$
`nextDueDate` obrigatório	texto ou nulo
`termsVersion` obrigatório	texto
`scheduleHash` obrigatório	texto	formato ^[a-f0-9]{64}$
`paymentMethod` obrigatório	objeto ou nulo
`dunningPolicy` obrigatório	objeto ou nulo
`scheduleDivergence` obrigatório	booleano	Datas/valores do provedor diferentes do calendário aceito (BLK-07).
`suspendedReason` obrigatório	texto ou nulo
`cancelledAt` obrigatório	data e hora (ISO 8601) ou nulo
`installments` obrigatório	lista de PlanInstallment
`installments[].id` obrigatório	Id (texto)	8–160 caracteres · formato ^[A-Za-z0-9_]+$
`installments[].index` obrigatório	inteiro	1 a 9007199254740991
`installments[].dueDate` obrigatório	texto	formato ^\d{4}-\d{2}-\d{2}$
`installments[].amountCents` obrigatório	PositiveCents (texto)	formato ^[1-9][0-9]{0,14}$
`installments[].status` obrigatório	"SCHEDULED" \| "IN_PROGRESS" \| "PAID" \| "DECLINED" \| "PAST_DUE" \| "UNKNOWN" \| "WAIVED" \| "CANCELLED"
`installments[].display` obrigatório	objeto
`installments[].display.label` obrigatório	texto
`installments[].display.variant` obrigatório	"info" \| "warn" \| "accent" \| "ok" \| "bad" \| "neutral"
`installments[].paymentId` obrigatório	Id (texto) ou nulo
`installments[].attempts` obrigatório	inteiro	0 a 9007199254740991
`installments[].paidAt` obrigatório	data e hora (ISO 8601) ou nulo
`version` obrigatório	inteiro	1 a 9007199254740991
`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)))$
`asOf` 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 200

{
  "id": "pln_01JDYB41B2C3D4E5F6G7H8J9KD",
  "orderId": "ord_01JDY8B1B2C3D4E5F6G7H8J9KB",
  "mode": "CARD_MONTHLY_PLAN",
  "status": "ACTIVE",
  "totalCents": "30000",
  "paidCents": "10000",
  "count": 3,
  "anchorDay": 20,
  "timezone": "America/Sao_Paulo",
  "firstDueDate": "2026-11-20",
  "nextDueDate": "2026-12-20",
  "termsVersion": "cartao-mensal-2026-11-14",
  "scheduleHash": "3b1f6c0e9a2d4b7c8e5f1a0d2c4b6e8f0a1c3e5b7d9f2a4c6e8b0d1f3a5c7e9b",
  "paymentMethod": {
    "id": "pm_01JDYB61B2C3D4E5F6G7H8J9KF",
    "brand": "MASTERCARD",
    "last4": "4444"
  },
  "dunningPolicy": {
    "retryOffsetsDays": [
      1,
      3,
      7
    ],
    "basis": "DUE_DATE",
    "approved": false
  },
  "scheduleDivergence": false,
  "suspendedReason": null,
  "cancelledAt": null,
  "installments": [
    {
      "id": "pli_01JDYB51B2C3D4E5F6G7H8J9KE",
      "index": 1,
      "dueDate": "2026-11-20",
      "amountCents": "10000",
      "status": "PAID",
      "display": {
        "label": "Paga",
        "variant": "ok"
      },
      "paymentId": "pay_01JDY8C1B2C3D4E5F6G7H8J9KC",
      "attempts": 1,
      "paidAt": "2026-11-13T13:00:00.000Z"
    },
    {
      "id": "pli_01JDYB52B2C3D4E5F6G7H8J9KF",
      "index": 2,
      "dueDate": "2026-12-20",
      "amountCents": "10000",
      "status": "SCHEDULED",
      "display": {
        "label": "Agendada",
        "variant": "neutral"
      },
      "paymentId": null,
      "attempts": 0,
      "paidAt": null
    },
    {
      "id": "pli_01JDYB53B2C3D4E5F6G7H8J9KG",
      "index": 3,
      "dueDate": "2027-01-20",
      "amountCents": "10000",
      "status": "SCHEDULED",
      "display": {
        "label": "Agendada",
        "variant": "neutral"
      },
      "paymentId": null,
      "attempts": 0,
      "paidAt": null
    }
  ],
  "version": 4,
  "createdAt": "2026-11-13T13:00:00.000Z",
  "asOf": "2026-11-13T13:00:00.000Z"
}

Erros

Erros de replacePlanCard
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 plano (corta despachos futuros)

POST/v1/payment-plans/{id}/cancelImplementada

Chave de API (Authorization: Bearer ep_…)· escopo plans:write· cancelPlan

Cancela o plano: parcelas futuras deixam de ser cobradas. Parcelas pagas não são estornadas automaticamente. No Pix em parcelas, cada parcela em aberto recebe um pedido de cancelamento no provedor (operação própria, confirmada pelo evento de exclusão); até lá ela continua pagável.

Escopo da chave: plans:write.

Idempotência: exige o header Idempotency-Key.

Headers de cancelPlan
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 cancelPlan
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 cancelPlan
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/payment-plans/{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 desistiu das parcelas restantes.","expectedVersion":3}'

Resposta 200: Sucesso.

Campos da resposta 200 de cancelPlan
Campo	Tipo	Descrição
`id` obrigatório	Id (texto)	8–160 caracteres · formato ^[A-Za-z0-9_]+$
`orderId` obrigatório	Id (texto)	8–160 caracteres · formato ^[A-Za-z0-9_]+$
`mode` obrigatório	"PIX_SCHEDULE" \| "CARD_MONTHLY_PLAN"
`status` obrigatório	"PENDING_CONSENT" \| "PENDING_ACTIVATION" \| "ACTIVE" \| "SUSPENDED" \| "CANCELLED" \| "COMPLETED" \| "FAILED"
`totalCents` obrigatório	PositiveCents (texto)	formato ^[1-9][0-9]{0,14}$
`paidCents` obrigatório	Cents (texto)	Só parcelas pagas; futuras são previsão com risco, sem antecipação (PXP-003). formato ^(0\|[1-9][0-9]{0,14})$
`count` obrigatório	inteiro	2 a 9007199254740991
`anchorDay` obrigatório	inteiro	1 a 31
`timezone` obrigatório	texto
`firstDueDate` obrigatório	texto	formato ^\d{4}-\d{2}-\d{2}$
`nextDueDate` obrigatório	texto ou nulo
`termsVersion` obrigatório	texto
`scheduleHash` obrigatório	texto	formato ^[a-f0-9]{64}$
`paymentMethod` obrigatório	objeto ou nulo
`dunningPolicy` obrigatório	objeto ou nulo
`scheduleDivergence` obrigatório	booleano	Datas/valores do provedor diferentes do calendário aceito (BLK-07).
`suspendedReason` obrigatório	texto ou nulo
`cancelledAt` obrigatório	data e hora (ISO 8601) ou nulo
`installments` obrigatório	lista de PlanInstallment
`installments[].id` obrigatório	Id (texto)	8–160 caracteres · formato ^[A-Za-z0-9_]+$
`installments[].index` obrigatório	inteiro	1 a 9007199254740991
`installments[].dueDate` obrigatório	texto	formato ^\d{4}-\d{2}-\d{2}$
`installments[].amountCents` obrigatório	PositiveCents (texto)	formato ^[1-9][0-9]{0,14}$
`installments[].status` obrigatório	"SCHEDULED" \| "IN_PROGRESS" \| "PAID" \| "DECLINED" \| "PAST_DUE" \| "UNKNOWN" \| "WAIVED" \| "CANCELLED"
`installments[].display` obrigatório	objeto
`installments[].display.label` obrigatório	texto
`installments[].display.variant` obrigatório	"info" \| "warn" \| "accent" \| "ok" \| "bad" \| "neutral"
`installments[].paymentId` obrigatório	Id (texto) ou nulo
`installments[].attempts` obrigatório	inteiro	0 a 9007199254740991
`installments[].paidAt` obrigatório	data e hora (ISO 8601) ou nulo
`version` obrigatório	inteiro	1 a 9007199254740991
`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)))$
`asOf` 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 200

{
  "id": "pln_01JDYB41B2C3D4E5F6G7H8J9KD",
  "orderId": "ord_01JDY8B1B2C3D4E5F6G7H8J9KB",
  "mode": "CARD_MONTHLY_PLAN",
  "status": "CANCELLED",
  "totalCents": "30000",
  "paidCents": "10000",
  "count": 3,
  "anchorDay": 20,
  "timezone": "America/Sao_Paulo",
  "firstDueDate": "2026-11-20",
  "nextDueDate": null,
  "termsVersion": "cartao-mensal-2026-11-14",
  "scheduleHash": "3b1f6c0e9a2d4b7c8e5f1a0d2c4b6e8f0a1c3e5b7d9f2a4c6e8b0d1f3a5c7e9b",
  "paymentMethod": {
    "id": "pm_01JDY8G1B2C3D4E5F6G7H8J9KK",
    "brand": "VISA",
    "last4": "1111"
  },
  "dunningPolicy": {
    "retryOffsetsDays": [
      1,
      3,
      7
    ],
    "basis": "DUE_DATE",
    "approved": false
  },
  "scheduleDivergence": false,
  "suspendedReason": null,
  "cancelledAt": "2026-11-13T13:00:00.000Z",
  "installments": [
    {
      "id": "pli_01JDYB51B2C3D4E5F6G7H8J9KE",
      "index": 1,
      "dueDate": "2026-11-20",
      "amountCents": "10000",
      "status": "PAID",
      "display": {
        "label": "Paga",
        "variant": "ok"
      },
      "paymentId": "pay_01JDY8C1B2C3D4E5F6G7H8J9KC",
      "attempts": 1,
      "paidAt": "2026-11-13T13:00:00.000Z"
    },
    {
      "id": "pli_01JDYB52B2C3D4E5F6G7H8J9KF",
      "index": 2,
      "dueDate": "2026-12-20",
      "amountCents": "10000",
      "status": "SCHEDULED",
      "display": {
        "label": "Agendada",
        "variant": "neutral"
      },
      "paymentId": null,
      "attempts": 0,
      "paidAt": null
    },
    {
      "id": "pli_01JDYB53B2C3D4E5F6G7H8J9KG",
      "index": 3,
      "dueDate": "2027-01-20",
      "amountCents": "10000",
      "status": "SCHEDULED",
      "display": {
        "label": "Agendada",
        "variant": "neutral"
      },
      "paymentId": null,
      "attempts": 0,
      "paidAt": null
    }
  ],
  "version": 4,
  "createdAt": "2026-11-13T13:00:00.000Z",
  "asOf": "2026-11-13T13:00:00.000Z"
}

Erros

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

Calendário de um plano para o pedido (exibir e colher o aceite)

GET/v1/orders/{id}/schedule-quoteImplementada

Chave de API (Authorization: Bearer ep_…)· escopo orders:read· quoteOrderSchedule

Calcula no servidor o calendário de um Pix em parcelas ou de um cartão mensal para o pedido, com o texto que deve ser exibido ao pagador e o scheduleHash. Para criar o plano, envie esse hash no aceite: calendário diferente do exibido é recusado.

Escopo da chave: orders:read.

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

Parâmetros de quoteOrderSchedule
Parâmetro	Onde	Tipo	Descrição
`id` obrigatório	caminho	Id (texto)	8–160 caracteres · formato ^[A-Za-z0-9_]+$
`mode` obrigatório	query	"PIX_SCHEDULE" \| "CARD_MONTHLY_PLAN" \| "PIX_FINANCED"
`count` obrigatório	query	inteiro	2 a 180
`firstDueDate`	query	texto	formato ^\d{4}-\d{2}-\d{2}$
`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/orders/{id}/schedule-quote" \
  -H "Authorization: Bearer $ECLIPTA_PAY_KEY" \
  -H "X-Account-Id: $ECLIPTA_PAY_ACCOUNT"

Resposta 200: Sucesso.

Campos da resposta 200 de quoteOrderSchedule
Campo	Tipo	Descrição
`mode` obrigatório	"PIX_SCHEDULE" \| "CARD_MONTHLY_PLAN"
`count` obrigatório	inteiro	2 a 9007199254740991
`totalCents` obrigatório	PositiveCents (texto)	formato ^[1-9][0-9]{0,14}$
`firstDueDate` obrigatório	texto	formato ^\d{4}-\d{2}-\d{2}$
`anchorDay` obrigatório	inteiro	1 a 31
`timezone` obrigatório	texto
`termsVersion` obrigatório	texto
`installments` obrigatório	lista de objeto
`installments[].index` obrigatório	inteiro	1 a 9007199254740991
`installments[].dueDate` obrigatório	texto	formato ^\d{4}-\d{2}-\d{2}$
`installments[].amountCents` obrigatório	PositiveCents (texto)	formato ^[1-9][0-9]{0,14}$
`scheduleHash` obrigatório	texto	sha256 do calendário canônico (modo, total, parcelas). formato ^[a-f0-9]{64}$
`notice` obrigatório	texto
`dunningPolicy` obrigatório	objeto ou nulo

Exemplo 200

{
  "mode": "PIX_SCHEDULE",
  "count": 3,
  "totalCents": "30000",
  "firstDueDate": "2026-11-20",
  "anchorDay": 20,
  "timezone": "America/Sao_Paulo",
  "termsVersion": "pix-parcelas-2026-11-14",
  "installments": [
    {
      "index": 1,
      "dueDate": "2026-11-20",
      "amountCents": "10000"
    },
    {
      "index": 2,
      "dueDate": "2026-12-20",
      "amountCents": "10000"
    },
    {
      "index": 3,
      "dueDate": "2027-01-20",
      "amountCents": "10000"
    }
  ],
  "scheduleHash": "3b1f6c0e9a2d4b7c8e5f1a0d2c4b6e8f0a1c3e5b7d9f2a4c6e8b0d1f3a5c7e9b",
  "notice": "Cada parcela precisa ser paga até o vencimento. Não é financiamento: o pedido é liberado quando todas forem pagas.",
  "dunningPolicy": null
}

Erros

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