Dois cartões, Pix em parcelas e cartão mensal

Como oferecer

Inclua as modalidades em allowedModes da sessão de checkout. Elas dependem das capacidades da conta (TWO_CARDS, PIX_SCHEDULE, CARD_MONTHLY_PLAN em GET /v1/accounts/capabilities); modalidade indisponível faz a criação da sessão responder 422 MODE_NOT_AVAILABLE, sem oferecer ao pagador algo que não será aceito.

const sessao = await eclipta.createCheckout(
  { orderId: pedido.id, allowedModes: ["PIX", "CARD_INSTALLMENTS", "TWO_CARDS", "PIX_SCHEDULE"], returnUrl: "https://loja.exemplo.com.br/obrigado" },
  { idempotencyKey: `pedido-${pedido.id}-checkout-1` },
);

Um pedido tem uma modalidade viva por vez: enquanto um pagamento com dois cartões ou um plano está em andamento, outra cobrança para o mesmo pedido é recusada. Uma tentativa que terminou sem cobrança (cartão recusado, reserva expirando) não bloqueia a próxima. Pix financiado não existe (sem provedor de crédito): PIX_FINANCED responde 422 CAPABILITY_UNAVAILABLE.

Dois cartões

• O pedido precisa de fulfillmentPolicy: "ON_FULLY_PAID" (FULFILLMENT_POLICY_NOT_ALLOWED no contrário). As partes somam exatamente o total, com cartões diferentes; cada parte é à vista (parcelar uma parte depende de homologação do provedor, BLK-05).
• As duas partes são pré-autorizadas e só são capturadas quando ambas forem aprovadas. Se uma for recusada, nada é capturado: a reserva da outra é desfeita pelo emissor no fim da validade da pré-autorização. Se uma captura falhar depois da outra, a parte capturada é estornada (compensação), como operação própria.
• O pedido só conta como pago com o grupo PAID: order.payment_completed sai uma única vez, mesmo com eventos repetidos ou fora de ordem. Resultado incerto bloqueia nova tentativa até a confirmação.

A rota POST /v1/payment-groups existe para quem já tem os dois cartões capturados (pm_…) e o aceite da divisão exibida; o caminho normal é o checkout, que faz as duas capturas no serviço isolado de cartão. Estorno do grupo: POST /v1/payment-groups/{id}/refunds (divisão proporcional entre os cartões).

Pix em parcelas

• O calendário é calculado no servidor (quantidade, datas e valores, com resto na última parcela) e exibido com o aviso de que cada parcela tem QR Code próprio e precisa ser paga. Não é financiamento.
• O aceite leva o scheduleHash do calendário exibido: calendário diferente (SCHEDULE_CHANGED) ou termos antigos (TERMS_CHANGED) são recusados sem criar nada.
• Parcelas pagas aparecem em payment_plan.installment_updated e o pedido fica PARTIALLY_PAID. order.payment_completed só sai com todas as parcelas pagas.
• O Pix em parcelas ainda não pode ser cancelado pela API (PLAN_CANCEL_NOT_SUPPORTED): as parcelas futuras continuam pagáveis no provedor. O suporte do provedor a QR por parcela no Sandbox está em verificação (BLK-07, BLK-20).

{
  "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
}

Parcelamento mensal no cartão

• A primeira parcela é cobrada no checkout; as seguintes, uma por mês, pelo agendador do Eclipta Pay com o cartão autorizado para uso mensal. O plano só fica ACTIVE com a primeira parcela paga.
• O dia do vencimento é preservado (dia 31 vira o último dia dos meses curtos). Uma cobrança com resultado incerto nunca dispara outra: a plataforma confirma pela referência antes de qualquer nova tentativa.
• Recusa: novas tentativas seguem a política exibida em dunningPolicy, hoje uma proposta não aprovada (approved: false, BLK-15). Esgotadas, o plano fica SUSPENDED até a troca do cartão (PUT /v1/payment-plans/{id}/payment-method, com novo aceite).
• POST /v1/payment-plans/{id}/cancel interrompe as parcelas futuras; as já pagas não são estornadas automaticamente.

Rotas

A integração de referência do Órbita oferece dois cartões e Pix em parcelas numa venda de mentoria e mostra o progresso das parcelas sem marcar a venda como ganha antes do total.