Referência da API

Checkout

Checkout hospedado e captura de cartão transparente.

Criar sessão de checkout

POST/v1/checkout-sessionsImplementada

Chave de API (Authorization: Bearer ep_…)· escopo checkout:write· createCheckout

Cria a sessão de checkout hospedado (pay.) para um pedido. O link carrega um token de alta entropia; a página usa um token efêmero escopado à sessão, nunca a sua chave de API. Validações: formas de pagamento sem repetição, returnUrl HTTPS, expiração de 10 minutos a 7 dias e itens do pedido somando o total (422 ORDER_ITEMS_TOTAL_MISMATCH). Com notifyPayer (padrão), o pagador recebe o link e os lembretes por e-mail. Expirar é local: só com cancelPendingOnExpiry as cobranças Pix/boleto pendentes recebem pedido de cancelamento. Com subscription, a sessão cria a assinatura e a 1ª cobrança é paga pelo método escolhido.

Escopo da chave: checkout:write.

Idempotência: exige o header Idempotency-Key.

Headers de createCheckout
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 createCheckout
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 createCheckout
Campo	Tipo	Descrição
`orderId` obrigatório	Id (texto)	8–160 caracteres · formato ^[A-Za-z0-9_]+$
`allowedModes` obrigatório	lista de "PIX" \| "BOLETO" \| "CARD_INSTALLMENTS" \| "TWO_CARDS" \| "PIX_SCHEDULE" \| "CARD_MONTHLY_PLAN" \| "PIX_FINANCED"	PIX_FINANCED responde 422 CAPABILITY_UNAVAILABLE (sem provedor de crédito). 1–∞ itens
`returnUrl` obrigatório	texto	HTTPS obrigatório (no Sandbox também http://localhost para desenvolvimento).
`expiresInSeconds`	inteiro	Entre 10 minutos e 7 dias (padrão 1 hora). Expirar é local: não cancela cobranças já emitidas. 600 a 604800
`notifyPayer`	booleano	Envia ao pagador (e-mail do cliente) o link e os lembretes configurados na conta. Padrão: true.
`cancelPendingOnExpiry`	booleano	Política explícita: ao expirar, pede o cancelamento (operação própria) das cobranças Pix/boleto pendentes da sessão. Padrão: false.
`subscription`	CheckoutSubscription	Modo assinatura: a sessão cria a assinatura e a 1ª cobrança é paga pelo método escolhido.
`subscription.cycle` obrigatório	"WEEKLY" \| "BIWEEKLY" \| "MONTHLY" \| "BIMONTHLY" \| "QUARTERLY" \| "SEMIANNUALLY" \| "YEARLY"
`subscription.endDate`	texto	formato ^\d{4}-\d{2}-\d{2}$
`subscription.maxPayments`	inteiro	1 a 1000
`subscription.description`	texto	0–500 caracteres

Exemplo

curl -X POST "$ECLIPTA_PAY_API/v1/checkout-sessions" \
  -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","allowedModes":["PIX","BOLETO","CARD_INSTALLMENTS"],"returnUrl":"https://loja.exemplo.com.br/obrigado","expiresInSeconds":86400,"notifyPayer":true}'

Resposta 201: Recurso criado.

Campos da resposta 201 de createCheckout
Campo	Tipo	Descrição
`id` obrigatório	Id (texto)	8–160 caracteres · formato ^[A-Za-z0-9_]+$
`url` obrigatório	texto
`expiresAt` 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)))$
`orderId` obrigatório	Id (texto)	8–160 caracteres · formato ^[A-Za-z0-9_]+$

Exemplo 201

{
  "id": "chk_01JDY8E1B2C3D4E5F6G7H8J9KE",
  "url": "https://pay.exemplo.test/c/chk_01JDY8E1B2C3D4E5F6G7H8J9KE#t=token-efemero",
  "expiresAt": "2026-11-14T13:00:00.000Z",
  "orderId": "ord_01JDY8B1B2C3D4E5F6G7H8J9KB"
}

Erros

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

Visão pública da sessão

GET/v1/checkout/sessions/{id}Implementada

Token efêmero da sessão de checkout (usado pela página de pagamento)· getCheckoutSession

Visão pública e redigida da sessão, usada pela página de checkout com o CheckoutToken. Não é chamada pelo servidor do integrador.

Parâmetros de getCheckoutSession
Parâmetro	Onde	Tipo	Descrição
`id` obrigatório	caminho	Id (texto)	8–160 caracteres · formato ^[A-Za-z0-9_]+$

Exemplo

curl -X GET "$ECLIPTA_PAY_API/v1/checkout/sessions/{id}"

Resposta 200: Sucesso.

Campos da resposta 200 de getCheckoutSession
Campo	Tipo	Descrição
`orderId` obrigatório	Id (texto)	8–160 caracteres · formato ^[A-Za-z0-9_]+$
`merchantName` obrigatório	texto
`environment` obrigatório	Environment	Em sandbox a página mostra que nenhum valor real é cobrado.
`returnUrl` obrigatório	texto
`totalCents` obrigatório	PositiveCents (texto)	formato ^[1-9][0-9]{0,14}$
`items` obrigatório	lista de objeto
`items[].name` obrigatório	texto	1–120 caracteres
`items[].quantity` obrigatório	inteiro	1 a 10000
`items[].unitAmountCents` obrigatório	PositiveCents (texto)	formato ^[1-9][0-9]{0,14}$
`allowedModes` obrigatório	lista de texto
`status` obrigatório	texto
`disclosure` obrigatório	texto
`quoteVersion` obrigatório	inteiro	1 a 9007199254740991
`expiresAt` 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)))$
`payment` obrigatório	objeto ou nulo	Última tentativa do pedido. 'Recebido' só após o provedor; callback do navegador não prova pagamento.
`modalities` obrigatório	CheckoutModalities	Só as modalidades liberadas para a conta e oferecidas na sessão.
`modalities.twoCards` obrigatório	objeto ou nulo
`modalities.pixSchedule` obrigatório	objeto ou nulo
`modalities.cardMonthlyPlan` obrigatório	objeto ou nulo
`group` obrigatório	PaymentGroup ou nulo	Pagamento com dois cartões em andamento ou concluído.
`plan` obrigatório	CheckoutPlan ou nulo	Pix em parcelas ou cartão mensal: calendário, parcela atual e progresso.
`merchantLogo` obrigatório	texto ou nulo	Logo do lojista (data: URI de imagem); null = monograma.
`subscription` obrigatório	objeto ou nulo	Modo assinatura: termos e situação da assinatura criada na sessão.
`maxInstallments` obrigatório	inteiro ou nulo	Teto de parcelas no cartão definido pela oferta; null = padrão do checkout.
`offer` obrigatório	objeto ou nulo	Sessão aberta pelo link de uma oferta.

Exemplo 200

{
  "orderId": "ord_01JDY8B1B2C3D4E5F6G7H8J9KB",
  "merchantName": "Loja Exemplo",
  "environment": "sandbox",
  "returnUrl": "https://loja.exemplo.com.br/obrigado",
  "totalCents": "14970",
  "items": [
    {
      "name": "Plano anual",
      "quantity": 1,
      "unitAmountCents": "14970"
    }
  ],
  "allowedModes": [
    "PIX",
    "CARD_INSTALLMENTS"
  ],
  "status": "OPEN",
  "disclosure": "Pagamento processado por instituição parceira.",
  "quoteVersion": 1,
  "expiresAt": "2026-11-14T13:00:00.000Z",
  "asOf": "2026-11-13T13:00:00.000Z",
  "payment": null,
  "modalities": {
    "twoCards": null,
    "pixSchedule": {
      "termsVersion": "pix-parcelas-2026-11-14",
      "counts": [
        2,
        3,
        4,
        6
      ],
      "notice": "Cada parcela precisa ser paga até o vencimento. Não é financiamento."
    },
    "cardMonthlyPlan": null
  },
  "group": null,
  "plan": null,
  "merchantLogo": null,
  "subscription": null,
  "maxInstallments": null,
  "offer": null
}

Erros

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

Confirmar pagamento na sessão

POST/v1/checkout/sessions/{id}/confirmImplementada

Token efêmero da sessão de checkout (usado pela página de pagamento)· confirmCheckout

Confirma a modalidade escolhida na página de checkout. Valor, conta e cliente vêm da sessão no servidor. Responde 202 + Operation.

Idempotência: exige o header Idempotency-Key.

Headers de confirmCheckout
Header	Obrigatório	Descrição
`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 confirmCheckout
Parâmetro	Onde	Tipo	Descrição
`id` obrigatório	caminho	Id (texto)	8–160 caracteres · formato ^[A-Za-z0-9_]+$

Corpo da requisição

Campos do corpo de confirmCheckout
Campo	Tipo	Descrição
`mode` obrigatório	"PIX" \| "BOLETO" \| "CARD_INSTALLMENTS" \| "TWO_CARDS" \| "PIX_SCHEDULE" \| "CARD_MONTHLY_PLAN" \| "PIX_FINANCED"
`paymentMethodId`	Id (texto)	8–160 caracteres · formato ^[A-Za-z0-9_]+$
`installments`	inteiro	1 a 21
`legs`	lista de PaymentLegInput	2–2 itens
`legs[].clientLegReference` obrigatório	texto	1–60 caracteres
`legs[].amountCents` obrigatório	PositiveCents (texto)	formato ^[1-9][0-9]{0,14}$
`legs[].paymentMethodId` obrigatório	Id (texto)	8–160 caracteres · formato ^[A-Za-z0-9_]+$
`legs[].installments` obrigatório	inteiro	1 a 21
`count`	inteiro	2 a 180
`consent`	Consent
`consent.termsVersion` obrigatório	texto	1–∞ caracteres
`consent.accepted` obrigatório	true
`consent.displayedScheduleHash` obrigatório	texto	formato ^[a-f0-9]{64}$
`quoteVersion` obrigatório	inteiro	1 a 9007199254740991
`payer`	objeto
`payer.name` obrigatório	texto	2–150 caracteres
`payer.taxId` obrigatório	texto	formato ^([0-9]{11}\|[0-9]{14})$
`payer.email` obrigatório	texto	formato ^(?:[A-Za-z0-9_'+\-]+\.)[A-Za-z0-9_'+\-][A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$
`subscriptionConsent`	SubscriptionConsent	S8: modo assinatura com cartão. Aceite dos termos exibidos (hash conferido no servidor).
`subscriptionConsent.termsVersion` obrigatório	texto	1–∞ caracteres
`subscriptionConsent.accepted` obrigatório	true
`subscriptionConsent.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/checkout/sessions/{id}/confirm" \
  -H "Idempotency-Key: <uma chave por intenção>" \
  -H "Content-Type: application/json" \
  -d '{"mode":"PIX","quoteVersion":1,"payer":{"name":"Maria Sintética","taxId":"52998224725","email":"[email protected]"}}'

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

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

Erros

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

Contexto efêmero de captura de cartão

POST/v1/checkout/sessions/{id}/capture-sessionsImplementada

Token efêmero da sessão de checkout (usado pela página de pagamento)· createCaptureContext

Emite o contexto efêmero para o formulário de cartão enviar os dados direto ao card-edge. A API pública nunca recebe número nem código de segurança do cartão.

Idempotência: exige o header Idempotency-Key.

Headers de createCaptureContext
Header	Obrigatório	Descrição
`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 createCaptureContext
Parâmetro	Onde	Tipo	Descrição
`id` obrigatório	caminho	Id (texto)	8–160 caracteres · formato ^[A-Za-z0-9_]+$

Corpo da requisição

Campos do corpo de createCaptureContext
Campo	Tipo	Descrição
`legReference`	texto	0–60 caracteres
`usage` obrigatório	"SINGLE" \| "FINITE_MONTHLY" \| "SUBSCRIPTION"
`consent`	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/checkout/sessions/{id}/capture-sessions" \
  -H "Idempotency-Key: <uma chave por intenção>" \
  -H "Content-Type: application/json" \
  -d '{"usage":"SINGLE"}'

Resposta 201: Recurso criado.

Campos da resposta 201 de createCaptureContext
Campo	Tipo	Descrição
`captureSessionId` obrigatório	Id (texto)	8–160 caracteres · formato ^[A-Za-z0-9_]+$
`captureToken` obrigatório	texto	32–∞ caracteres
`expiresAt` 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)))$
`captureUrl` obrigatório	texto

Exemplo 201

{
  "captureSessionId": "cap_01JDY8F1B2C3D4E5F6G7H8J9KJ",
  "captureToken": "cap-token-efemero-com-mais-de-32-caracteres",
  "expiresAt": "2026-11-13T13:15:00.000Z",
  "captureUrl": "https://card.exemplo.test/capture"
}

Erros

Erros de createCaptureContext
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 Pix em parcelas ou cartão mensal para exibir e aceitar

GET/v1/checkout/sessions/{id}/schedule-quoteImplementada

Token efêmero da sessão de checkout (usado pela página de pagamento)· getCheckoutScheduleQuote

Mesmo calendário, para a página de checkout (autenticada pelo token da sessão). O valor vem do pedido no servidor, nunca do navegador.

Parâmetros de getCheckoutScheduleQuote
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}$

Exemplo

curl -X GET "$ECLIPTA_PAY_API/v1/checkout/sessions/{id}/schedule-quote"

Resposta 200: Sucesso.

Campos da resposta 200 de getCheckoutScheduleQuote
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 getCheckoutScheduleQuote
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.

Oferta pública pelo código do link

GET/v1/checkout/offers/{code}Implementada

Sem autenticação· getPublicOffer

Dados públicos da oferta para a página pay./o/<código>: nome e logo da loja, produto, nome, tipo, preço e formas de pagamento. Sem autenticação e com limite por IP. Oferta desativada ou produto arquivado responde 410 OFFER_UNAVAILABLE; código inexistente, 404 OFFER_NOT_FOUND.

Parâmetros de getPublicOffer
Parâmetro	Onde	Tipo	Descrição
`code` obrigatório	caminho	texto	8–40 caracteres · formato ^[a-z0-9]+$

Exemplo

curl -X GET "$ECLIPTA_PAY_API/v1/checkout/offers/{code}"

Resposta 200: Sucesso.

Campos da resposta 200 de getPublicOffer
Campo	Tipo	Descrição
`code` obrigatório	texto
`environment` obrigatório	Environment	Em sandbox a página mostra que nenhum valor real é cobrado.
`merchantName` obrigatório	texto
`merchantLogo` obrigatório	texto ou nulo	Logo do lojista (data: URI de imagem); null = monograma.
`product` obrigatório	objeto
`product.name` obrigatório	texto
`product.description` obrigatório	texto ou nulo
`offer` obrigatório	objeto
`offer.name` obrigatório	texto
`offer.kind` obrigatório	"ONE_TIME" \| "SUBSCRIPTION" \| "PIX_SCHEDULE" \| "CARD_MONTHLY_PLAN"	Pagamento único, assinatura, Pix parcelado ou cartão mensal.
`offer.priceCents` obrigatório	PositiveCents (texto)	formato ^[1-9][0-9]{0,14}$
`offer.methods` obrigatório	lista de texto
`offer.maxInstallments` obrigatório	inteiro ou nulo
`offer.subscriptionCycle` obrigatório	"WEEKLY" \| "BIWEEKLY" \| "MONTHLY" \| "BIMONTHLY" \| "QUARTERLY" \| "SEMIANNUALLY" \| "YEARLY" ou nulo
`disclosure` obrigatório	texto

Exemplo 200

{
  "code": "k7m2xq9prt4hwd",
  "environment": "sandbox",
  "merchantName": "Loja Exemplo",
  "merchantLogo": null,
  "product": {
    "name": "Curso de fotografia",
    "description": "Aulas gravadas e material de apoio."
  },
  "offer": {
    "name": "À vista",
    "kind": "ONE_TIME",
    "priceCents": "29700",
    "methods": [
      "PIX",
      "CARD_INSTALLMENTS"
    ],
    "maxInstallments": 6,
    "subscriptionCycle": null
  },
  "disclosure": "Serviços de pagamento prestados por Asaas Gestão Financeira S.A."
}

Erros

Erros de getPublicOffer
HTTP	Exemplo de code	Quando
400	`INVALID_REQUEST`	Requisição inválida: fieldErrors aponta cada campo.
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.

Abrir o checkout da oferta com os dados do comprador

POST/v1/checkout/offers/{code}/sessionsImplementada

Sem autenticação· startOfferCheckout

Abre o checkout de uma oferta para o comprador: confere nome, CPF ou CNPJ (dígitos verificadores), e-mail e telefone opcional, cria ou reaproveita o cliente da conta (mesmo documento e e-mail), cria o pedido com o preço da oferta e a sessão de checkout. Sem autenticação, com limite por IP e Idempotency-Key obrigatória: repetir o envio devolve a mesma sessão, sem segundo pedido.

Idempotência: exige o header Idempotency-Key.

Headers de startOfferCheckout
Header	Obrigatório	Descrição
`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 startOfferCheckout
Parâmetro	Onde	Tipo	Descrição
`code` obrigatório	caminho	texto	8–40 caracteres · formato ^[a-z0-9]+$

Corpo da requisição

Campos do corpo de startOfferCheckout
Campo	Tipo	Descrição
`name` obrigatório	texto	2–150 caracteres
`taxId` obrigatório	texto	CPF ou CNPJ, só números (dígitos verificadores conferidos). formato ^([0-9]{11}\|[0-9]{14})$
`email` obrigatório	texto	0–254 caracteres · formato ^(?:[A-Za-z0-9_'+\-]+\.)[A-Za-z0-9_'+\-][A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$
`phone`	texto	Com DDD, só números. formato ^[0-9]{10,11}$

Exemplo

curl -X POST "$ECLIPTA_PAY_API/v1/checkout/offers/{code}/sessions" \
  -H "Idempotency-Key: <uma chave por intenção>" \
  -H "Content-Type: application/json" \
  -d '{"name":"Maria Sintética","taxId":"52998224725","email":"[email protected]","phone":"11987654321"}'

Resposta 201: Recurso criado.

Campos da resposta 201 de startOfferCheckout
Campo	Tipo	Descrição
`checkoutSessionId` obrigatório	Id (texto)	8–160 caracteres · formato ^[A-Za-z0-9_]+$
`url` obrigatório	texto	Sessão de checkout com o token no fragmento (#t=…): mostrado só ao comprador.
`expiresAt` 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

{
  "checkoutSessionId": "chk_01JDY8E1B2C3D4E5F6G7H8J9KE",
  "url": "https://pay.exemplo.test/c/chk_01JDY8E1B2C3D4E5F6G7H8J9KE#t=token-efemero",
  "expiresAt": "2026-11-14T13:00:00.000Z"
}

Erros

Erros de startOfferCheckout
HTTP	Exemplo de code	Quando
400	`INVALID_REQUEST`	Requisição inválida: fieldErrors aponta cada campo.
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