Referência da API

Cobranças

Cobranças (Pix, boleto e cartão) como intenções assíncronas.

Criar cobrança (intenção assíncrona)

POST/v1/paymentsImplementada

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

Registra a intenção de cobrança e responde 202 com uma Operation. A chamada ao provedor acontece depois, no worker. Acompanhe por GET /v1/operations/{id} ou pelos webhooks; nunca repita a criação com outra Idempotency-Key por causa de demora ou erro de rede.

Escopo da chave: payments:write.

Idempotência: exige o header Idempotency-Key.

Headers de createPayment
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 createPayment
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 createPayment
Campo	Tipo	Descrição
`orderId` obrigatório	Id (texto)	8–160 caracteres · formato ^[A-Za-z0-9_]+$
`method` obrigatório	"PIX" \| "BOLETO" \| "CREDIT_CARD"
`dueDate` obrigatório	texto	formato ^\d{4}-\d{2}-\d{2}$
`paymentMethodId`	Id (texto)	Obrigatório para CREDIT_CARD (handle do card-edge). 8–160 caracteres · formato ^[A-Za-z0-9_]+$
`installments`	inteiro	1 a 21
`splits`	lista de Split	Coprodutores: contas Eclipta Pay aprovadas (recipientId = id da conta). A comissão da plataforma é calculada no servidor. 0–20 itens
`description`	texto	Descrição enviada ao provedor (padrão: a do pedido). 0–500 caracteres

Exemplo

curl -X POST "$ECLIPTA_PAY_API/v1/payments" \
  -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","method":"PIX","dueDate":"2026-11-20"}'

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

Campos da resposta 202 de createPayment
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 createPayment
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 cobranças

GET/v1/paymentsImplementada

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

Lista as cobranças da conta (mais recentes primeiro), com paginação por cursor.

Escopo da chave: payments:read.

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

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

Resposta 200: Sucesso.

Campos da resposta 200 de listPayments
Campo	Tipo	Descrição
`data` obrigatório	lista de Payment
`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[].method` obrigatório	texto
`data[].status` obrigatório	texto	Dimensão cobrança (B docs/05).
`data[].reversalStatus` obrigatório	texto
`data[].reconciliationStatus` obrigatório	texto
`data[].providerStatus` obrigatório	texto ou nulo
`data[].display` obrigatório	objeto
`data[].display.label` obrigatório	texto
`data[].display.variant` obrigatório	"info" \| "warn" \| "accent" \| "ok" \| "bad" \| "neutral"
`data[].amountCents` obrigatório	PositiveCents (texto)	formato ^[1-9][0-9]{0,14}$
`data[].receivedCents` 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[].commissionEstimateCents` obrigatório	Cents (texto)	formato ^(0\|[1-9][0-9]{0,14})$
`data[].providerFeeCents` obrigatório	Cents (texto) ou nulo
`data[].netCents` obrigatório	Cents (texto) ou nulo
`data[].dueDate` obrigatório	texto	formato ^\d{4}-\d{2}-\d{2}$
`data[].installmentCount` obrigatório	inteiro	-9007199254740991 a 9007199254740991
`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)))$
`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[].description` obrigatório	texto ou nulo
`data[].operationStatus` obrigatório	texto ou nulo	Situação da operação de criação (ex.: UNKNOWN enquanto o resultado é confirmado pela referência).
`data[].instructions` obrigatório	PaymentInstructions ou nulo	Pix e boleto: situação do QR/linha digitável. null para cartão.
`data[].fees` obrigatório	PaymentFees
`data[].fees.policyId` obrigatório	texto
`data[].fees.policyVersion` obrigatório	inteiro	1 a 9007199254740991
`data[].fees.commissionMode` obrigatório	"NONE" \| "NET_PERCENT" \| "FIXED"
`data[].fees.estimated` obrigatório	objeto
`data[].fees.estimated.providerFeeCents` obrigatório	Cents (texto)	formato ^(0\|[1-9][0-9]{0,14})$
`data[].fees.estimated.providerFeeSource` obrigatório	"ACCOUNT_FEES" \| "DEFAULT_ESTIMATE"
`data[].fees.estimated.commissionCents` obrigatório	Cents (texto)	formato ^(0\|[1-9][0-9]{0,14})$
`data[].fees.estimated.merchantNetCents` obrigatório	Cents (texto)	formato ^(0\|[1-9][0-9]{0,14})$
`data[].fees.effective` obrigatório	objeto	Valores que o provedor informou (prevalecem sobre a estimativa). null = ainda não informado.
`data[].fees.effective.providerFeeCents` obrigatório	Cents (texto) ou nulo
`data[].fees.effective.netCents` obrigatório	Cents (texto) ou nulo
`data[].fees.effective.commissionCents` obrigatório	Cents (texto) ou nulo
`data[].splits` obrigatório	lista de PaymentSplit
`data[].splits[].kind` obrigatório	"PLATFORM_COMMISSION" \| "COPRODUCER"
`data[].splits[].recipientAccountId` obrigatório	texto ou nulo
`data[].splits[].fixedCents` obrigatório	Cents (texto) ou nulo
`data[].splits[].percentUnits` obrigatório	texto ou nulo	1% = 10000.
`data[].splits[].status` obrigatório	"PENDING" \| "DONE" \| "BLOCKED" \| "CANCELLED" \| "REFUNDED"	BLOCKED: divergência de valor (comissão não reconhecida como liquidada, SPL-002).
`data[].splits[].providerStatus` obrigatório	texto ou nulo	Status cru do provedor, preservado.
`data[].splits[].effectiveCents` obrigatório	Cents (texto) ou nulo
`data[].cancelRequestedAt` obrigatório	data e hora (ISO 8601) ou nulo	Cancelamento pedido; o status final só vem do provedor (PAYMENT_DELETED).
`nextCursor` obrigatório	texto ou nulo

Exemplo 200

{
  "data": [
    {
      "id": "pay_01JDY8C1B2C3D4E5F6G7H8J9KC",
      "orderId": "ord_01JDY8B1B2C3D4E5F6G7H8J9KB",
      "method": "PIX",
      "status": "CONFIRMED",
      "reversalStatus": "NONE",
      "reconciliationStatus": "NOT_APPLICABLE",
      "providerStatus": "CONFIRMED",
      "display": {
        "label": "Confirmado · a liberar",
        "variant": "accent"
      },
      "amountCents": "14970",
      "receivedCents": "0",
      "refundedCents": "0",
      "commissionEstimateCents": "299",
      "providerFeeCents": null,
      "netCents": null,
      "dueDate": "2026-11-20",
      "installmentCount": 1,
      "asOf": "2026-11-13T13:00:00.000Z",
      "version": 3,
      "createdAt": "2026-11-13T13:00:00.000Z",
      "description": "Plano anual",
      "operationStatus": "SUCCEEDED",
      "instructions": {
        "status": "READY",
        "attempts": 0,
        "nextRetryAt": null,
        "checkedAt": "2026-11-13T13:00:00.000Z"
      },
      "fees": {
        "policyId": "fee_01JDY8J1B2C3D4E5F6G7H8J9KN",
        "policyVersion": 1,
        "commissionMode": "FIXED",
        "estimated": {
          "providerFeeCents": "199",
          "providerFeeSource": "ACCOUNT_FEES",
          "commissionCents": "299",
          "merchantNetCents": "14472"
        },
        "effective": {
          "providerFeeCents": null,
          "netCents": null,
          "commissionCents": null
        }
      },
      "splits": [
        {
          "kind": "PLATFORM_COMMISSION",
          "recipientAccountId": null,
          "fixedCents": "299",
          "percentUnits": null,
          "status": "PENDING",
          "providerStatus": "PENDING",
          "effectiveCents": null
        }
      ],
      "cancelRequestedAt": null
    }
  ],
  "nextCursor": null
}

Erros

Erros de listPayments
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 cobrança

GET/v1/payments/{id}Implementada

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

Cobrança em quatro dimensões (cobrança, reversão, conciliação e situação do provedor). CONFIRMED significa a liberar, não saldo disponível.

Escopo da chave: payments:read.

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

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

Resposta 200: Sucesso.

Campos da resposta 200 de getPayment
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_]+$
`method` obrigatório	texto
`status` obrigatório	texto	Dimensão cobrança (B docs/05).
`reversalStatus` obrigatório	texto
`reconciliationStatus` obrigatório	texto
`providerStatus` obrigatório	texto ou nulo
`display` obrigatório	objeto
`display.label` obrigatório	texto
`display.variant` obrigatório	"info" \| "warn" \| "accent" \| "ok" \| "bad" \| "neutral"
`amountCents` obrigatório	PositiveCents (texto)	formato ^[1-9][0-9]{0,14}$
`receivedCents` 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})$
`commissionEstimateCents` obrigatório	Cents (texto)	formato ^(0\|[1-9][0-9]{0,14})$
`providerFeeCents` obrigatório	Cents (texto) ou nulo
`netCents` obrigatório	Cents (texto) ou nulo
`dueDate` obrigatório	texto	formato ^\d{4}-\d{2}-\d{2}$
`installmentCount` obrigatório	inteiro	-9007199254740991 a 9007199254740991
`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)))$
`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)))$
`description` obrigatório	texto ou nulo
`operationStatus` obrigatório	texto ou nulo	Situação da operação de criação (ex.: UNKNOWN enquanto o resultado é confirmado pela referência).
`instructions` obrigatório	PaymentInstructions ou nulo	Pix e boleto: situação do QR/linha digitável. null para cartão.
`fees` obrigatório	PaymentFees
`fees.policyId` obrigatório	texto
`fees.policyVersion` obrigatório	inteiro	1 a 9007199254740991
`fees.commissionMode` obrigatório	"NONE" \| "NET_PERCENT" \| "FIXED"
`fees.estimated` obrigatório	objeto
`fees.estimated.providerFeeCents` obrigatório	Cents (texto)	formato ^(0\|[1-9][0-9]{0,14})$
`fees.estimated.providerFeeSource` obrigatório	"ACCOUNT_FEES" \| "DEFAULT_ESTIMATE"
`fees.estimated.commissionCents` obrigatório	Cents (texto)	formato ^(0\|[1-9][0-9]{0,14})$
`fees.estimated.merchantNetCents` obrigatório	Cents (texto)	formato ^(0\|[1-9][0-9]{0,14})$
`fees.effective` obrigatório	objeto	Valores que o provedor informou (prevalecem sobre a estimativa). null = ainda não informado.
`fees.effective.providerFeeCents` obrigatório	Cents (texto) ou nulo
`fees.effective.netCents` obrigatório	Cents (texto) ou nulo
`fees.effective.commissionCents` obrigatório	Cents (texto) ou nulo
`splits` obrigatório	lista de PaymentSplit
`splits[].kind` obrigatório	"PLATFORM_COMMISSION" \| "COPRODUCER"
`splits[].recipientAccountId` obrigatório	texto ou nulo
`splits[].fixedCents` obrigatório	Cents (texto) ou nulo
`splits[].percentUnits` obrigatório	texto ou nulo	1% = 10000.
`splits[].status` obrigatório	"PENDING" \| "DONE" \| "BLOCKED" \| "CANCELLED" \| "REFUNDED"	BLOCKED: divergência de valor (comissão não reconhecida como liquidada, SPL-002).
`splits[].providerStatus` obrigatório	texto ou nulo	Status cru do provedor, preservado.
`splits[].effectiveCents` obrigatório	Cents (texto) ou nulo
`cancelRequestedAt` obrigatório	data e hora (ISO 8601) ou nulo	Cancelamento pedido; o status final só vem do provedor (PAYMENT_DELETED).

Exemplo 200

{
  "id": "pay_01JDY8C1B2C3D4E5F6G7H8J9KC",
  "orderId": "ord_01JDY8B1B2C3D4E5F6G7H8J9KB",
  "method": "PIX",
  "status": "CONFIRMED",
  "reversalStatus": "NONE",
  "reconciliationStatus": "NOT_APPLICABLE",
  "providerStatus": "CONFIRMED",
  "display": {
    "label": "Confirmado · a liberar",
    "variant": "accent"
  },
  "amountCents": "14970",
  "receivedCents": "0",
  "refundedCents": "0",
  "commissionEstimateCents": "299",
  "providerFeeCents": null,
  "netCents": null,
  "dueDate": "2026-11-20",
  "installmentCount": 1,
  "asOf": "2026-11-13T13:00:00.000Z",
  "version": 3,
  "createdAt": "2026-11-13T13:00:00.000Z",
  "description": "Plano anual",
  "operationStatus": "SUCCEEDED",
  "instructions": {
    "status": "READY",
    "attempts": 0,
    "nextRetryAt": null,
    "checkedAt": "2026-11-13T13:00:00.000Z"
  },
  "fees": {
    "policyId": "fee_01JDY8J1B2C3D4E5F6G7H8J9KN",
    "policyVersion": 1,
    "commissionMode": "FIXED",
    "estimated": {
      "providerFeeCents": "199",
      "providerFeeSource": "ACCOUNT_FEES",
      "commissionCents": "299",
      "merchantNetCents": "14472"
    },
    "effective": {
      "providerFeeCents": null,
      "netCents": null,
      "commissionCents": null
    }
  },
  "splits": [
    {
      "kind": "PLATFORM_COMMISSION",
      "recipientAccountId": null,
      "fixedCents": "299",
      "percentUnits": null,
      "status": "PENDING",
      "providerStatus": "PENDING",
      "effectiveCents": null
    }
  ],
  "cancelRequestedAt": null
}

Erros

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

Alterar valor, vencimento ou descrição de cobrança pendente (intenção assíncrona)

PATCH/v1/payments/{id}Implementada

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

Altera valor, vencimento e/ou descrição de uma cobrança Pix ou boleto aguardando pagamento ou vencida. Responde 202 com uma Operation; a cobrança só muda depois que o provedor confirmar. A taxa é recalculada com a política da intenção e o split só é reenviado se mudar (nunca é apagado por omissão). Um novo QR Code/linha digitável é gerado. Valor só muda em pedido com esta cobrança apenas (o total do pedido acompanha). Use expectedVersion da última leitura.

Escopo da chave: payments:write.

Idempotência: exige o header Idempotency-Key.

Headers de updatePayment
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 updatePayment
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 updatePayment
Campo	Tipo	Descrição
`amountCents`	PositiveCents (texto)	Só em pedido com esta cobrança apenas; o total do pedido acompanha. formato ^[1-9][0-9]{0,14}$
`dueDate`	texto	formato ^\d{4}-\d{2}-\d{2}$
`description`	texto	0–500 caracteres
`expectedVersion` obrigatório	inteiro	1 a 9007199254740991

Exemplo

curl -X PATCH "$ECLIPTA_PAY_API/v1/payments/{id}" \
  -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":"15990","dueDate":"2026-11-30","expectedVersion":3}'

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

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

Erros

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

QR Code Pix da cobrança

GET/v1/payments/{id}/pixImplementada

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

QR Code oficial do Pix depois que a operação de criação concluir. Enquanto ele é gerado responde 409 PAYMENT_NOT_READY; se a leitura no provedor falhar repetidamente responde 409 PAYMENT_INSTRUCTIONS_UNAVAILABLE (a cobrança continua válida e a plataforma tenta de novo sozinha; veja instructions na cobrança).

Escopo da chave: payments:read.

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

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

Resposta 200: Sucesso.

Campos da resposta 200 de getPixQr
Campo	Tipo	Descrição
`paymentId` obrigatório	Id (texto)	8–160 caracteres · formato ^[A-Za-z0-9_]+$
`encodedImage` obrigatório	texto
`payload` obrigatório	texto
`expiresAt` obrigatório	texto

Exemplo 200

{
  "paymentId": "pay_01JDY8C1B2C3D4E5F6G7H8J9KC",
  "encodedImage": "iVBORw0KGgo...",
  "payload": "00020126580014br.gov.bcb.pix...",
  "expiresAt": "2026-11-20 23:59:59"
}

Erros

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

Boleto da cobrança

GET/v1/payments/{id}/boletoImplementada

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

Linha digitável e PDF do boleto. Enquanto são gerados responde 409 PAYMENT_NOT_READY; se a leitura no provedor falhar repetidamente, 409 PAYMENT_INSTRUCTIONS_UNAVAILABLE (a cobrança continua válida).

Escopo da chave: payments:read.

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

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

Resposta 200: Sucesso.

Campos da resposta 200 de getBoleto
Campo	Tipo	Descrição
`paymentId` obrigatório	Id (texto)	8–160 caracteres · formato ^[A-Za-z0-9_]+$
`url` obrigatório	texto ou nulo
`identificationField` obrigatório	texto ou nulo

Exemplo 200

{
  "paymentId": "pay_01JDY8C1B2C3D4E5F6G7H8J9KC",
  "url": "https://www.asaas.com/b/pdf/exemplo",
  "identificationField": "00190000090281913600900006400003599990000014970"
}

Erros

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

Cancelar cobrança no provedor (operação própria, ADR-0010)

POST/v1/payments/{id}/cancelImplementada

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

Pede o cancelamento da cobrança Pix ou boleto no provedor (operação própria, CANCEL_PAYMENT). Responde 202; o status final CANCELLED só chega com a confirmação do provedor. Até lá a cobrança continua pagável e um pagamento que chegar antes é reconhecido normalmente. Cartão não se cancela: use o estorno.

Escopo da chave: payments:write.

Idempotência: exige o header Idempotency-Key.

Headers de cancelPayment
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 cancelPayment
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 cancelPayment
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/payments/{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":"Pedido desistido pelo cliente","expectedVersion":3}'

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

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

Erros

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

Parcelas do parcelamento no cartão (status cru de cada parcela)

GET/v1/payments/{id}/parcelsImplementada

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

Parcelas de um parcelamento no cartão (installments ≥ 2): o provedor cria uma cobrança por parcela; aqui ficam o valor, o vencimento e o status cru de cada uma. O pedido continua avaliado pelo parcelamento inteiro.

Escopo da chave: payments:read.

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

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

Resposta 200: Sucesso.

Campos da resposta 200 de listPaymentParcels
Campo	Tipo	Descrição
`paymentId` obrigatório	Id (texto)	8–160 caracteres · formato ^[A-Za-z0-9_]+$
`installmentCount` obrigatório	inteiro	1 a 9007199254740991
`data` obrigatório	lista de objeto
`data[].installmentNumber` obrigatório	inteiro	1 a 21
`data[].amountCents` obrigatório	PositiveCents (texto)	formato ^[1-9][0-9]{0,14}$
`data[].dueDate` obrigatório	texto	formato ^\d{4}-\d{2}-\d{2}$
`data[].providerStatus` obrigatório	texto
`data[].netCents` obrigatório	Cents (texto) ou nulo

Exemplo 200

{
  "paymentId": "pay_01JDY8C1B2C3D4E5F6G7H8J9KC",
  "installmentCount": 3,
  "data": [
    {
      "installmentNumber": 1,
      "amountCents": "4990",
      "dueDate": "2026-11-13",
      "providerStatus": "CONFIRMED",
      "netCents": "4792"
    },
    {
      "installmentNumber": 2,
      "amountCents": "4990",
      "dueDate": "2026-12-13",
      "providerStatus": "CONFIRMED",
      "netCents": "4792"
    },
    {
      "installmentNumber": 3,
      "amountCents": "4990",
      "dueDate": "2027-01-13",
      "providerStatus": "CONFIRMED",
      "netCents": "4792"
    }
  ]
}

Erros

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