Referência da API

Dois cartões

Pagamento dividido em dois cartões.

Pagamento com dois cartões

POST/v1/payment-groupsImplementada

Chave de API (Authorization: Bearer ep_…)· escopo payments:write· createTwoCardGroup

Paga um pedido com dois cartões. As duas partes são pré-autorizadas e só são capturadas quando ambas forem aprovadas; se uma falhar, a outra é compensada por estorno, sem cobrança dupla. O pedido só é liberado com o grupo pago. Responde 202 com a operação.

Escopo da chave: payments:write.

Idempotência: exige o header Idempotency-Key.

Headers de createTwoCardGroup
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 createTwoCardGroup
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 createTwoCardGroup
Campo	Tipo	Descrição
`orderId` obrigatório	Id (texto)	8–160 caracteres · formato ^[A-Za-z0-9_]+$
`legs` obrigatório	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
`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-groups" \
  -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","legs":[{"clientLegReference":"cartao-1","amountCents":"30000","paymentMethodId":"pm_01JDY8G1B2C3D4E5F6G7H8J9KK","installments":1},{"clientLegReference":"cartao-2","amountCents":"20000","paymentMethodId":"pm_01JDYB61B2C3D4E5F6G7H8J9KF","installments":1}],"consent":{"termsVersion":"dois-cartoes-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 createTwoCardGroup
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": "AUTHORIZE_GROUP_LEG",
  "resourceId": "grp_01JDYB11B2C3D4E5F6G7H8J9KA",
  "statusUrl": "/v1/operations/op_01JDY8D1B2C3D4E5F6G7H8J9KD",
  "nextAction": "WAIT",
  "createdAt": "2026-11-13T13:00:00.000Z"
}

Erros

Erros de createTwoCardGroup
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 grupos de dois cartões (filtro por pedido)

GET/v1/payment-groupsImplementada

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

Lista os grupos de dois cartões da conta, com filtro opcional por pedido (orderId).

Escopo da chave: payments:read.

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

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

Resposta 200: Sucesso.

Campos da resposta 200 de listGroups
Campo	Tipo	Descrição
`data` obrigatório	lista de PaymentGroup
`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[].status` obrigatório	"DRAFT" \| "AUTHORIZING" \| "AUTHORIZED" \| "CAPTURING" \| "PAID" \| "UNKNOWN" \| "PARTIALLY_CAPTURED" \| "COMPENSATING" \| "COMPENSATED" \| "FAILED" \| "MANUAL_REVIEW"
`data[].outcome` obrigatório	"PROCESSING" \| "UNCERTAIN" \| "PAID" \| "NOT_COMPLETED_RELEASING" \| "NOT_COMPLETED_REFUNDING" \| "NOT_COMPLETED" \| "MANUAL_REVIEW"	Resumo para o pagador/lojista. Autorização nunca libera entrega (TWO-002).
`data[].expectedTotalCents` obrigatório	PositiveCents (texto)	formato ^[1-9][0-9]{0,14}$
`data[].confirmedCents` obrigatório	Cents (texto)	formato ^(0\|[1-9][0-9]{0,14})$
`data[].refundedCents` obrigatório	Cents (texto)	formato ^(0\|[1-9][0-9]{0,14})$
`data[].fulfillmentEligible` obrigatório	booleano	Só com as duas partes confirmadas (ON_FULLY_PAID obrigatório).
`data[].legs` obrigatório	lista de PaymentLeg	2–2 itens
`data[].legs[].id` obrigatório	Id (texto)	8–160 caracteres · formato ^[A-Za-z0-9_]+$
`data[].legs[].index` obrigatório	inteiro	1 a 2
`data[].legs[].clientLegReference` obrigatório	texto
`data[].legs[].amountCents` obrigatório	PositiveCents (texto)	formato ^[1-9][0-9]{0,14}$
`data[].legs[].confirmedCents` obrigatório	Cents (texto)	Capturado e confirmado pelo provedor. formato ^(0\|[1-9][0-9]{0,14})$
`data[].legs[].refundedCents` obrigatório	Cents (texto)	formato ^(0\|[1-9][0-9]{0,14})$
`data[].legs[].installmentCount` obrigatório	inteiro	1 a 9007199254740991
`data[].legs[].status` obrigatório	"PENDING" \| "AUTHORIZING" \| "AUTHORIZED" \| "DECLINED" \| "AUTH_UNKNOWN" \| "CAPTURING" \| "CAPTURED" \| "CAPTURE_FAILED" \| "CAPTURE_UNKNOWN" \| "RELEASE_PENDING" \| "RELEASED" \| "REFUNDING" \| "REFUNDED" \| "MANUAL_REVIEW"
`data[].legs[].display` obrigatório	objeto
`data[].legs[].display.label` obrigatório	texto
`data[].legs[].display.variant` obrigatório	"info" \| "warn" \| "accent" \| "ok" \| "bad" \| "neutral"
`data[].legs[].paymentId` obrigatório	Id (texto) ou nulo
`data[].legs[].brand` obrigatório	texto ou nulo
`data[].legs[].last4` obrigatório	texto ou nulo
`data[].legs[].reservationExpiresAt` obrigatório	data e hora (ISO 8601) ou nulo	Fim da validade documentada da reserva (pré-autorização).
`data[].legs[].challengeUrl` obrigatório	texto ou nulo	Desafio 3DS do emissor desta parte (só enquanto autoriza). Não prova pagamento.
`data[].refunds` obrigatório	lista de GroupRefund
`data[].refunds[].id` obrigatório	Id (texto)	8–160 caracteres · formato ^[A-Za-z0-9_]+$
`data[].refunds[].kind` obrigatório	"COMPENSATION" \| "MERCHANT_REFUND"
`data[].refunds[].status` obrigatório	texto
`data[].refunds[].requestedCents` obrigatório	PositiveCents (texto)	formato ^[1-9][0-9]{0,14}$
`data[].refunds[].confirmedCents` obrigatório	Cents (texto)	formato ^(0\|[1-9][0-9]{0,14})$
`data[].refunds[].allocations` obrigatório	lista de objeto
`data[].refunds[].allocations[].legId` obrigatório	Id (texto)	8–160 caracteres · formato ^[A-Za-z0-9_]+$
`data[].refunds[].allocations[].requestedCents` obrigatório	PositiveCents (texto)	formato ^[1-9][0-9]{0,14}$
`data[].refunds[].allocations[].confirmedCents` obrigatório	Cents (texto)	formato ^(0\|[1-9][0-9]{0,14})$
`data[].refunds[].allocations[].status` obrigatório	texto
`data[].refunds[].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
`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": "grp_01JDYB11B2C3D4E5F6G7H8J9KA",
      "orderId": "ord_01JDY8B1B2C3D4E5F6G7H8J9KB",
      "status": "PAID",
      "outcome": "PAID",
      "expectedTotalCents": "50000",
      "confirmedCents": "50000",
      "refundedCents": "0",
      "fulfillmentEligible": true,
      "legs": [
        {
          "id": "leg_01JDYB21B2C3D4E5F6G7H8J9KB",
          "index": 1,
          "clientLegReference": "cartao-1",
          "amountCents": "30000",
          "confirmedCents": "30000",
          "refundedCents": "0",
          "installmentCount": 1,
          "status": "CAPTURED",
          "display": {
            "label": "Capturado",
            "variant": "ok"
          },
          "paymentId": "pay_01JDY8C1B2C3D4E5F6G7H8J9KC",
          "brand": "VISA",
          "last4": "1111",
          "reservationExpiresAt": null,
          "challengeUrl": null
        },
        {
          "id": "leg_01JDYB31B2C3D4E5F6G7H8J9KC",
          "index": 2,
          "clientLegReference": "cartao-2",
          "amountCents": "20000",
          "confirmedCents": "20000",
          "refundedCents": "0",
          "installmentCount": 1,
          "status": "CAPTURED",
          "display": {
            "label": "Capturado",
            "variant": "ok"
          },
          "paymentId": "pay_01JDYB71B2C3D4E5F6G7H8J9KH",
          "brand": "MASTERCARD",
          "last4": "4444",
          "reservationExpiresAt": null,
          "challengeUrl": null
        }
      ],
      "refunds": [],
      "version": 6,
      "createdAt": "2026-11-13T13:00:00.000Z",
      "asOf": "2026-11-13T13:00:00.000Z"
    }
  ],
  "nextCursor": null
}

Erros

Erros de listGroups
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 grupo

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

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

Consulta o grupo: situação de cada cartão (autorizado, capturado, compensado), total confirmado e se o pedido já pode ser entregue. Parte incerta aparece como incerta até a confirmação.

Escopo da chave: payments:read.

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

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

Resposta 200: Sucesso.

Campos da resposta 200 de getGroup
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_]+$
`status` obrigatório	"DRAFT" \| "AUTHORIZING" \| "AUTHORIZED" \| "CAPTURING" \| "PAID" \| "UNKNOWN" \| "PARTIALLY_CAPTURED" \| "COMPENSATING" \| "COMPENSATED" \| "FAILED" \| "MANUAL_REVIEW"
`outcome` obrigatório	"PROCESSING" \| "UNCERTAIN" \| "PAID" \| "NOT_COMPLETED_RELEASING" \| "NOT_COMPLETED_REFUNDING" \| "NOT_COMPLETED" \| "MANUAL_REVIEW"	Resumo para o pagador/lojista. Autorização nunca libera entrega (TWO-002).
`expectedTotalCents` obrigatório	PositiveCents (texto)	formato ^[1-9][0-9]{0,14}$
`confirmedCents` obrigatório	Cents (texto)	formato ^(0\|[1-9][0-9]{0,14})$
`refundedCents` obrigatório	Cents (texto)	formato ^(0\|[1-9][0-9]{0,14})$
`fulfillmentEligible` obrigatório	booleano	Só com as duas partes confirmadas (ON_FULLY_PAID obrigatório).
`legs` obrigatório	lista de PaymentLeg	2–2 itens
`legs[].id` obrigatório	Id (texto)	8–160 caracteres · formato ^[A-Za-z0-9_]+$
`legs[].index` obrigatório	inteiro	1 a 2
`legs[].clientLegReference` obrigatório	texto
`legs[].amountCents` obrigatório	PositiveCents (texto)	formato ^[1-9][0-9]{0,14}$
`legs[].confirmedCents` obrigatório	Cents (texto)	Capturado e confirmado pelo provedor. formato ^(0\|[1-9][0-9]{0,14})$
`legs[].refundedCents` obrigatório	Cents (texto)	formato ^(0\|[1-9][0-9]{0,14})$
`legs[].installmentCount` obrigatório	inteiro	1 a 9007199254740991
`legs[].status` obrigatório	"PENDING" \| "AUTHORIZING" \| "AUTHORIZED" \| "DECLINED" \| "AUTH_UNKNOWN" \| "CAPTURING" \| "CAPTURED" \| "CAPTURE_FAILED" \| "CAPTURE_UNKNOWN" \| "RELEASE_PENDING" \| "RELEASED" \| "REFUNDING" \| "REFUNDED" \| "MANUAL_REVIEW"
`legs[].display` obrigatório	objeto
`legs[].display.label` obrigatório	texto
`legs[].display.variant` obrigatório	"info" \| "warn" \| "accent" \| "ok" \| "bad" \| "neutral"
`legs[].paymentId` obrigatório	Id (texto) ou nulo
`legs[].brand` obrigatório	texto ou nulo
`legs[].last4` obrigatório	texto ou nulo
`legs[].reservationExpiresAt` obrigatório	data e hora (ISO 8601) ou nulo	Fim da validade documentada da reserva (pré-autorização).
`legs[].challengeUrl` obrigatório	texto ou nulo	Desafio 3DS do emissor desta parte (só enquanto autoriza). Não prova pagamento.
`refunds` obrigatório	lista de GroupRefund
`refunds[].id` obrigatório	Id (texto)	8–160 caracteres · formato ^[A-Za-z0-9_]+$
`refunds[].kind` obrigatório	"COMPENSATION" \| "MERCHANT_REFUND"
`refunds[].status` obrigatório	texto
`refunds[].requestedCents` obrigatório	PositiveCents (texto)	formato ^[1-9][0-9]{0,14}$
`refunds[].confirmedCents` obrigatório	Cents (texto)	formato ^(0\|[1-9][0-9]{0,14})$
`refunds[].allocations` obrigatório	lista de objeto
`refunds[].allocations[].legId` obrigatório	Id (texto)	8–160 caracteres · formato ^[A-Za-z0-9_]+$
`refunds[].allocations[].requestedCents` obrigatório	PositiveCents (texto)	formato ^[1-9][0-9]{0,14}$
`refunds[].allocations[].confirmedCents` obrigatório	Cents (texto)	formato ^(0\|[1-9][0-9]{0,14})$
`refunds[].allocations[].status` obrigatório	texto
`refunds[].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
`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": "grp_01JDYB11B2C3D4E5F6G7H8J9KA",
  "orderId": "ord_01JDY8B1B2C3D4E5F6G7H8J9KB",
  "status": "PAID",
  "outcome": "PAID",
  "expectedTotalCents": "50000",
  "confirmedCents": "50000",
  "refundedCents": "0",
  "fulfillmentEligible": true,
  "legs": [
    {
      "id": "leg_01JDYB21B2C3D4E5F6G7H8J9KB",
      "index": 1,
      "clientLegReference": "cartao-1",
      "amountCents": "30000",
      "confirmedCents": "30000",
      "refundedCents": "0",
      "installmentCount": 1,
      "status": "CAPTURED",
      "display": {
        "label": "Capturado",
        "variant": "ok"
      },
      "paymentId": "pay_01JDY8C1B2C3D4E5F6G7H8J9KC",
      "brand": "VISA",
      "last4": "1111",
      "reservationExpiresAt": null,
      "challengeUrl": null
    },
    {
      "id": "leg_01JDYB31B2C3D4E5F6G7H8J9KC",
      "index": 2,
      "clientLegReference": "cartao-2",
      "amountCents": "20000",
      "confirmedCents": "20000",
      "refundedCents": "0",
      "installmentCount": 1,
      "status": "CAPTURED",
      "display": {
        "label": "Capturado",
        "variant": "ok"
      },
      "paymentId": "pay_01JDYB71B2C3D4E5F6G7H8J9KH",
      "brand": "MASTERCARD",
      "last4": "4444",
      "reservationExpiresAt": null,
      "challengeUrl": null
    }
  ],
  "refunds": [],
  "version": 6,
  "createdAt": "2026-11-13T13:00:00.000Z",
  "asOf": "2026-11-13T13:00:00.000Z"
}

Erros

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

Estornar grupo (alocação proporcional)

POST/v1/payment-groups/{id}/refundsImplementada

Chave de API (Authorization: Bearer ep_…)· escopo refunds:write· refundGroup

Estorna um valor do grupo com alocação proporcional entre os dois cartões, gravada antes do envio e imutável. Responde 202 com a operação.

Escopo da chave: refunds:write.

Idempotência: exige o header Idempotency-Key.

Headers de refundGroup
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 refundGroup
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 refundGroup
Campo	Tipo	Descrição
`amountCents` obrigatório	PositiveCents (texto)	Valor a devolver; limitado ao principal elegível (pago − devolvido − reservado). formato ^[1-9][0-9]{0,14}$
`reason` obrigatório	texto	Motivo interno; não é enviado ao provedor. 10–500 caracteres

Exemplo

curl -X POST "$ECLIPTA_PAY_API/v1/payment-groups/{id}/refunds" \
  -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":"10000","reason":"Devolução parcial combinada com o cliente."}'

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

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

Erros

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

Todas as rotas