Primeiros passos

Antes de começar

Você precisa de uma chave de testes (ep_test_…) com os escopos customers:write, orders:write, payments:write e payments:read, e do identificador da conta (acc_…) que ela pode usar. A chave aparece uma única vez quando é criada: guarde-a num cofre de segredos do seu servidor, nunca no navegador nem no aplicativo.

export ECLIPTA_PAY_API="<endereço da API do ambiente de testes>"
export ECLIPTA_PAY_KEY="ep_test_..."
export ECLIPTA_PAY_ACCOUNT="acc_..."

Fluxo da primeira cobrança

1. Confira a conta e as capacidades. Antes de oferecer um meio de pagamento, consulte o que está habilitado para a conta.

   curl "$ECLIPTA_PAY_API/v1/accounts/capabilities" \
     -H "Authorization: Bearer $ECLIPTA_PAY_KEY" \
     -H "X-Account-Id: $ECLIPTA_PAY_ACCOUNT"

2. Cadastre o cliente pagador. O CPF/CNPJ é cifrado e só volta mascarado. externalReference é o seu identificador do cliente.

   curl -X POST "$ECLIPTA_PAY_API/v1/customers" \
     -H "Authorization: Bearer $ECLIPTA_PAY_KEY" \
     -H "X-Account-Id: $ECLIPTA_PAY_ACCOUNT" \
     -H "Idempotency-Key: cliente-123-cadastro-v1" \
     -H "Content-Type: application/json" \
     -d '{"name":"Maria Sintética","taxId":"52998224725","email":"[email protected]","externalReference":"cliente-123"}'

3. Crie o pedido. O pedido define o total, sempre no servidor. Mesma referência com o mesmo conteúdo devolve o pedido já criado.

   curl -X POST "$ECLIPTA_PAY_API/v1/orders" \
     -H "Authorization: Bearer $ECLIPTA_PAY_KEY" \
     -H "X-Account-Id: $ECLIPTA_PAY_ACCOUNT" \
     -H "Idempotency-Key: pedido-98765-criacao-v1" \
     -H "Content-Type: application/json" \
     -d '{"customerId":"cus_01JDY8A1B2C3D4E5F6G7H8J9KA","externalOrderReference":"pedido-98765","amountCents":"14970","currency":"BRL","description":"Plano anual","fulfillmentPolicy":"ON_FULLY_PAID"}'

4. Peça a cobrança Pix. A resposta é 202 com uma operação: a cobrança é criada no provedor logo depois, de forma assíncrona.

   curl -X POST "$ECLIPTA_PAY_API/v1/payments" \
     -H "Authorization: Bearer $ECLIPTA_PAY_KEY" \
     -H "X-Account-Id: $ECLIPTA_PAY_ACCOUNT" \
     -H "Idempotency-Key: pedido-98765-pix-v1" \
     -H "Content-Type: application/json" \
     -d '{"orderId":"ord_01JDY8B1B2C3D4E5F6G7H8J9KB","method":"PIX","dueDate":"2026-11-20"}'

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

5. Acompanhe a operação. Consulte statusUrl até SUCCEEDED ou FAILED. Em produção prefira os webhooks; a consulta serve para retomar depois de um recarregamento. Veja Operações 202 e UNKNOWN.

   curl "$ECLIPTA_PAY_API/v1/operations/op_..." \
     -H "Authorization: Bearer $ECLIPTA_PAY_KEY" \
     -H "X-Account-Id: $ECLIPTA_PAY_ACCOUNT"

6. Mostre o QR Code. Com a operação concluída, o QR oficial fica em GET /v1/payments/{id}/pix (o resourceId da operação).

   curl "$ECLIPTA_PAY_API/v1/payments/pay_.../pix" \
     -H "Authorization: Bearer $ECLIPTA_PAY_KEY" \
     -H "X-Account-Id: $ECLIPTA_PAY_ACCOUNT"

7. Receba os eventos. Cadastre um endpoint de webhook e libere o produto ao receber order.payment_completed, depois de verificar a assinatura. Veja Webhooks e, para um serviço completo, as integrações de referência.

O mesmo fluxo com o SDK

import { EcliptaPay } from "@eclipta-pay/sdk";

const eclipta = new EcliptaPay({
  apiKey: process.env.ECLIPTA_PAY_KEY!,
  baseUrl: process.env.ECLIPTA_PAY_API!,
  accountId: process.env.ECLIPTA_PAY_ACCOUNT!,
});

const cliente = await eclipta.createCustomer({ name: "Maria Sintética", taxId: "52998224725", externalReference: "cliente-123" });
const pedido = await eclipta.createOrder({ customerId: cliente.id, externalOrderReference: "pedido-98765", amountCents: "14970", currency: "BRL", fulfillmentPolicy: "ON_FULLY_PAID" });
const operacao = await eclipta.createPayment({ orderId: pedido.id, method: "PIX", dueDate: "2026-11-20" });
const final = await eclipta.waitForOperation(operacao);
if (final.status === "SUCCEEDED") {
  const pix = await eclipta.getPixQr(final.resourceId!);
  console.log(pix.payload);
}