Referência da API

Transferências

Favorecidos e saques com aprovação.

Cadastrar favorecido (mesma titularidade; validação por pessoa com step-up e quarentena)

POST/v1/beneficiariesImplementada

Chave de API (Authorization: Bearer ep_…)· escopo transfers:write· createBeneficiary

Cadastra um favorecido de saque (chave Pix ou conta bancária) da mesma titularidade da conta. O destino é guardado cifrado e entra em quarentena; a validação por uma pessoa, com confirmação reforçada no painel, libera o uso.

Escopo da chave: transfers:write.

Idempotência: exige o header Idempotency-Key.

Headers de createBeneficiary
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 createBeneficiary
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 createBeneficiary
Campo	Tipo	Descrição
`variante 1`		Um dos formatos abaixo.
`kind` obrigatório	"PIX_KEY"
`pixKey` obrigatório	texto	3–140 caracteres
`pixKeyType` obrigatório	"CPF" \| "CNPJ" \| "EMAIL" \| "PHONE" \| "EVP"
`holderTaxId` obrigatório	texto	formato ^([0-9]{11}\|[0-9]{14})$
`holderName` obrigatório	texto	2–150 caracteres
`variante 2`		Um dos formatos abaixo.
`kind` obrigatório	"BANK_ACCOUNT"
`bankCode` obrigatório	texto	formato ^[0-9]{3}$
`agency` obrigatório	texto	formato ^[0-9]{1,5}$
`account` obrigatório	texto	formato ^[0-9]{1,13}$
`accountDigit` obrigatório	texto	formato ^[0-9Xx]{1,2}$
`accountType` obrigatório	"CONTA_CORRENTE" \| "CONTA_POUPANCA"
`holderTaxId` obrigatório	texto	formato ^([0-9]{11}\|[0-9]{14})$
`holderName` obrigatório	texto	2–150 caracteres

Exemplo

curl -X POST "$ECLIPTA_PAY_API/v1/beneficiaries" \
  -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 '{"kind":"PIX_KEY","pixKey":"11222333000181","pixKeyType":"CNPJ","holderTaxId":"11222333000181","holderName":"Loja Órbita Sintética LTDA"}'

Resposta 201: Recurso criado.

Campos da resposta 201 de createBeneficiary
Campo	Tipo	Descrição
`id` obrigatório	Id (texto)	8–160 caracteres · formato ^[A-Za-z0-9_]+$
`versionId` obrigatório	Id (texto) ou nulo
`version` obrigatório	inteiro ou nulo
`kind` obrigatório	"PIX_KEY" \| "BANK_ACCOUNT"
`maskedDestination` obrigatório	texto
`status` obrigatório	"ACTIVE" \| "ARCHIVED"
`versionStatus` obrigatório	"PENDING_VALIDATION" \| "VALIDATED" \| "SUPERSEDED" \| "REJECTED"
`availableFrom` obrigatório	data e hora (ISO 8601) ou nulo	Fim da quarentena de 24 h após a validação.
`usable` obrigatório	booleano
`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 201

{
  "id": "ben_01JDYA51B2C3D4E5F6G7H8J9KE",
  "versionId": "bnv_01JDYA61B2C3D4E5F6G7H8J9KF",
  "version": 1,
  "kind": "PIX_KEY",
  "maskedDestination": "Chave CNPJ ••.•••.333/0001-••",
  "status": "ACTIVE",
  "versionStatus": "PENDING_VALIDATION",
  "availableFrom": null,
  "usable": false,
  "createdAt": "2026-11-13T13:00:00.000Z"
}

Erros

Erros de createBeneficiary
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 favorecidos (destino mascarado)

GET/v1/beneficiariesImplementada

Chave de API (Authorization: Bearer ep_…)· escopo balance:read· listBeneficiaries

Lista os favorecidos com o destino mascarado e a situação da versão atual (pendente de validação, validado ou substituído).

Escopo da chave: balance:read.

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

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

Resposta 200: Sucesso.

Campos da resposta 200 de listBeneficiaries
Campo	Tipo	Descrição
`data` obrigatório	lista de Beneficiary
`data[].id` obrigatório	Id (texto)	8–160 caracteres · formato ^[A-Za-z0-9_]+$
`data[].versionId` obrigatório	Id (texto) ou nulo
`data[].version` obrigatório	inteiro ou nulo
`data[].kind` obrigatório	"PIX_KEY" \| "BANK_ACCOUNT"
`data[].maskedDestination` obrigatório	texto
`data[].status` obrigatório	"ACTIVE" \| "ARCHIVED"
`data[].versionStatus` obrigatório	"PENDING_VALIDATION" \| "VALIDATED" \| "SUPERSEDED" \| "REJECTED"
`data[].availableFrom` obrigatório	data e hora (ISO 8601) ou nulo	Fim da quarentena de 24 h após a validação.
`data[].usable` obrigatório	booleano
`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)))$
`nextCursor` obrigatório	texto ou nulo

Exemplo 200

{
  "data": [
    {
      "id": "ben_01JDYA51B2C3D4E5F6G7H8J9KE",
      "versionId": "bnv_01JDYA61B2C3D4E5F6G7H8J9KF",
      "version": 1,
      "kind": "PIX_KEY",
      "maskedDestination": "Chave CNPJ ••.•••.333/0001-••",
      "status": "ACTIVE",
      "versionStatus": "VALIDATED",
      "availableFrom": "2026-11-14T13:00:00.000Z",
      "usable": true,
      "createdAt": "2026-11-13T13:00:00.000Z"
    }
  ],
  "nextCursor": null
}

Erros

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

Solicitar transferência (reserva saldo e aguarda aprovação no painel)

POST/v1/transfersImplementada

Chave de API (Authorization: Bearer ep_…)· escopo transfers:write· requestTransfer

Solicita uma transferência para um favorecido validado. O valor é reservado do saldo elegível (somente saldo conciliado, nunca estimado) e a transferência aguarda aprovação de outra pessoa no painel. Responde 202 com a transferência.

Escopo da chave: transfers:write.

Idempotência: exige o header Idempotency-Key.

Headers de requestTransfer
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 requestTransfer
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 requestTransfer
Campo	Tipo	Descrição
`beneficiaryVersionId` obrigatório	Id (texto)	8–160 caracteres · formato ^[A-Za-z0-9_]+$
`amountCents` obrigatório	PositiveCents (texto)	formato ^[1-9][0-9]{0,14}$
`description`	texto	0–140 caracteres

Exemplo

curl -X POST "$ECLIPTA_PAY_API/v1/transfers" \
  -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 '{"beneficiaryVersionId":"bnv_01JDYA61B2C3D4E5F6G7H8J9KF","amountCents":"250000","description":"Repasse semanal"}'

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

Campos da resposta 202 de requestTransfer
Campo	Tipo	Descrição
`id` obrigatório	Id (texto)	8–160 caracteres · formato ^[A-Za-z0-9_]+$
`status` obrigatório	"AWAITING_APPROVAL" \| "REJECTED" \| "EXPIRED" \| "CANCELLED" \| "APPROVED" \| "SUBMITTED" \| "UNKNOWN" \| "PENDING" \| "BANK_PROCESSING" \| "BLOCKED" \| "DONE" \| "FAILED"
`amountCents` obrigatório	PositiveCents (texto)	formato ^[1-9][0-9]{0,14}$
`feeBufferCents` obrigatório	Cents (texto)	formato ^(0\|[1-9][0-9]{0,14})$
`beneficiaryId` obrigatório	Id (texto)	8–160 caracteres · formato ^[A-Za-z0-9_]+$
`beneficiaryVersionId` obrigatório	Id (texto)	8–160 caracteres · formato ^[A-Za-z0-9_]+$
`maskedDestination` obrigatório	texto
`description` obrigatório	texto ou nulo
`requestedBy` obrigatório	objeto
`requestedBy.type` obrigatório	"USER" \| "API_KEY"
`requestedBy.id` obrigatório	texto
`approval` obrigatório	objeto
`approval.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)))$
`approval.decidedBy` obrigatório	texto ou nulo
`approval.decidedAt` obrigatório	data e hora (ISO 8601) ou nulo
`approval.note` obrigatório	texto ou nulo
`reservation` obrigatório	objeto	UNKNOWN mantém a reserva até evidência conclusiva (OUT-003).
`reservation.state` obrigatório	"HELD" \| "RELEASED" \| "CONSUMED"
`reservation.reflectedInStatement` obrigatório	booleano
`operationId` obrigatório	Id (texto) ou nulo
`operationStatus` obrigatório	texto ou nulo
`providerStatus` obrigatório	texto ou nulo
`failReason` obrigatório	texto ou nulo
`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)))$
`updatedAt` 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": "trf_01JDYA71B2C3D4E5F6G7H8J9KG",
  "status": "AWAITING_APPROVAL",
  "amountCents": "250000",
  "feeBufferCents": "0",
  "beneficiaryId": "ben_01JDYA51B2C3D4E5F6G7H8J9KE",
  "beneficiaryVersionId": "bnv_01JDYA61B2C3D4E5F6G7H8J9KF",
  "maskedDestination": "Chave CNPJ ••.•••.333/0001-••",
  "description": "Repasse semanal",
  "requestedBy": {
    "type": "API_KEY",
    "id": "key_01JDYAA1B2C3D4E5F6G7H8J9KK"
  },
  "approval": {
    "expiresAt": "2026-11-16T13:00:00.000Z",
    "decidedBy": null,
    "decidedAt": null,
    "note": null
  },
  "reservation": {
    "state": "HELD",
    "reflectedInStatement": false
  },
  "operationId": null,
  "operationStatus": null,
  "providerStatus": null,
  "failReason": null,
  "version": 1,
  "createdAt": "2026-11-13T13:00:00.000Z",
  "updatedAt": "2026-11-13T13:00:00.000Z"
}

Erros

Erros de requestTransfer
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 transferências

GET/v1/transfersImplementada

Chave de API (Authorization: Bearer ep_…)· escopo balance:read· listTransfers

Lista as transferências da conta com filtros por situação, com o valor reservado e o vínculo com o provedor quando já enviada.

Escopo da chave: balance:read.

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

Parâmetros de listTransfers
Parâmetro	Onde	Tipo	Descrição
`cursor`	query	texto	0–200 caracteres
`limit`	query	inteiro	1 a 100 · padrão 20
`status`	query	"AWAITING_APPROVAL" \| "REJECTED" \| "EXPIRED" \| "CANCELLED" \| "APPROVED" \| "SUBMITTED" \| "UNKNOWN" \| "PENDING" \| "BANK_PROCESSING" \| "BLOCKED" \| "DONE" \| "FAILED"
`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/transfers" \
  -H "Authorization: Bearer $ECLIPTA_PAY_KEY" \
  -H "X-Account-Id: $ECLIPTA_PAY_ACCOUNT"

Resposta 200: Sucesso.

Campos da resposta 200 de listTransfers
Campo	Tipo	Descrição
`data` obrigatório	lista de Transfer
`data[].id` obrigatório	Id (texto)	8–160 caracteres · formato ^[A-Za-z0-9_]+$
`data[].status` obrigatório	"AWAITING_APPROVAL" \| "REJECTED" \| "EXPIRED" \| "CANCELLED" \| "APPROVED" \| "SUBMITTED" \| "UNKNOWN" \| "PENDING" \| "BANK_PROCESSING" \| "BLOCKED" \| "DONE" \| "FAILED"
`data[].amountCents` obrigatório	PositiveCents (texto)	formato ^[1-9][0-9]{0,14}$
`data[].feeBufferCents` obrigatório	Cents (texto)	formato ^(0\|[1-9][0-9]{0,14})$
`data[].beneficiaryId` obrigatório	Id (texto)	8–160 caracteres · formato ^[A-Za-z0-9_]+$
`data[].beneficiaryVersionId` obrigatório	Id (texto)	8–160 caracteres · formato ^[A-Za-z0-9_]+$
`data[].maskedDestination` obrigatório	texto
`data[].description` obrigatório	texto ou nulo
`data[].requestedBy` obrigatório	objeto
`data[].requestedBy.type` obrigatório	"USER" \| "API_KEY"
`data[].requestedBy.id` obrigatório	texto
`data[].approval` obrigatório	objeto
`data[].approval.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)))$
`data[].approval.decidedBy` obrigatório	texto ou nulo
`data[].approval.decidedAt` obrigatório	data e hora (ISO 8601) ou nulo
`data[].approval.note` obrigatório	texto ou nulo
`data[].reservation` obrigatório	objeto	UNKNOWN mantém a reserva até evidência conclusiva (OUT-003).
`data[].reservation.state` obrigatório	"HELD" \| "RELEASED" \| "CONSUMED"
`data[].reservation.reflectedInStatement` obrigatório	booleano
`data[].operationId` obrigatório	Id (texto) ou nulo
`data[].operationStatus` obrigatório	texto ou nulo
`data[].providerStatus` obrigatório	texto ou nulo
`data[].failReason` obrigatório	texto ou nulo
`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[].updatedAt` 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": "trf_01JDYA71B2C3D4E5F6G7H8J9KG",
      "status": "AWAITING_APPROVAL",
      "amountCents": "250000",
      "feeBufferCents": "0",
      "beneficiaryId": "ben_01JDYA51B2C3D4E5F6G7H8J9KE",
      "beneficiaryVersionId": "bnv_01JDYA61B2C3D4E5F6G7H8J9KF",
      "maskedDestination": "Chave CNPJ ••.•••.333/0001-••",
      "description": "Repasse semanal",
      "requestedBy": {
        "type": "API_KEY",
        "id": "key_01JDYAA1B2C3D4E5F6G7H8J9KK"
      },
      "approval": {
        "expiresAt": "2026-11-16T13:00:00.000Z",
        "decidedBy": null,
        "decidedAt": null,
        "note": null
      },
      "reservation": {
        "state": "HELD",
        "reflectedInStatement": false
      },
      "operationId": null,
      "operationStatus": null,
      "providerStatus": null,
      "failReason": null,
      "version": 1,
      "createdAt": "2026-11-13T13:00:00.000Z",
      "updatedAt": "2026-11-13T13:00:00.000Z"
    }
  ],
  "nextCursor": null
}

Erros

Erros de listTransfers
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 transferência

GET/v1/transfers/{id}Implementada

Chave de API (Authorization: Bearer ep_…)· escopo balance:read· getTransfer

Consulta uma transferência: quem pediu, quem decidiu, situação no provedor e se o débito já apareceu no extrato. Resultado incerto aparece como tal até a confirmação.

Escopo da chave: balance:read.

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

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

Resposta 200: Sucesso.

Campos da resposta 200 de getTransfer
Campo	Tipo	Descrição
`id` obrigatório	Id (texto)	8–160 caracteres · formato ^[A-Za-z0-9_]+$
`status` obrigatório	"AWAITING_APPROVAL" \| "REJECTED" \| "EXPIRED" \| "CANCELLED" \| "APPROVED" \| "SUBMITTED" \| "UNKNOWN" \| "PENDING" \| "BANK_PROCESSING" \| "BLOCKED" \| "DONE" \| "FAILED"
`amountCents` obrigatório	PositiveCents (texto)	formato ^[1-9][0-9]{0,14}$
`feeBufferCents` obrigatório	Cents (texto)	formato ^(0\|[1-9][0-9]{0,14})$
`beneficiaryId` obrigatório	Id (texto)	8–160 caracteres · formato ^[A-Za-z0-9_]+$
`beneficiaryVersionId` obrigatório	Id (texto)	8–160 caracteres · formato ^[A-Za-z0-9_]+$
`maskedDestination` obrigatório	texto
`description` obrigatório	texto ou nulo
`requestedBy` obrigatório	objeto
`requestedBy.type` obrigatório	"USER" \| "API_KEY"
`requestedBy.id` obrigatório	texto
`approval` obrigatório	objeto
`approval.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)))$
`approval.decidedBy` obrigatório	texto ou nulo
`approval.decidedAt` obrigatório	data e hora (ISO 8601) ou nulo
`approval.note` obrigatório	texto ou nulo
`reservation` obrigatório	objeto	UNKNOWN mantém a reserva até evidência conclusiva (OUT-003).
`reservation.state` obrigatório	"HELD" \| "RELEASED" \| "CONSUMED"
`reservation.reflectedInStatement` obrigatório	booleano
`operationId` obrigatório	Id (texto) ou nulo
`operationStatus` obrigatório	texto ou nulo
`providerStatus` obrigatório	texto ou nulo
`failReason` obrigatório	texto ou nulo
`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)))$
`updatedAt` 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": "trf_01JDYA71B2C3D4E5F6G7H8J9KG",
  "status": "AWAITING_APPROVAL",
  "amountCents": "250000",
  "feeBufferCents": "0",
  "beneficiaryId": "ben_01JDYA51B2C3D4E5F6G7H8J9KE",
  "beneficiaryVersionId": "bnv_01JDYA61B2C3D4E5F6G7H8J9KF",
  "maskedDestination": "Chave CNPJ ••.•••.333/0001-••",
  "description": "Repasse semanal",
  "requestedBy": {
    "type": "API_KEY",
    "id": "key_01JDYAA1B2C3D4E5F6G7H8J9KK"
  },
  "approval": {
    "expiresAt": "2026-11-16T13:00:00.000Z",
    "decidedBy": null,
    "decidedAt": null,
    "note": null
  },
  "reservation": {
    "state": "HELD",
    "reflectedInStatement": false
  },
  "operationId": null,
  "operationStatus": null,
  "providerStatus": null,
  "failReason": null,
  "version": 1,
  "createdAt": "2026-11-13T13:00:00.000Z",
  "updatedAt": "2026-11-13T13:00:00.000Z"
}

Erros

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

Consultar favorecido

GET/v1/beneficiaries/{id}Implementada

Chave de API (Authorization: Bearer ep_…)· escopo balance:read· getBeneficiary

Consulta um favorecido e a versão vigente do destino (mascarado). Alterar o destino cria uma nova versão, que exige nova validação.

Escopo da chave: balance:read.

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

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

Resposta 200: Sucesso.

Campos da resposta 200 de getBeneficiary
Campo	Tipo	Descrição
`id` obrigatório	Id (texto)	8–160 caracteres · formato ^[A-Za-z0-9_]+$
`versionId` obrigatório	Id (texto) ou nulo
`version` obrigatório	inteiro ou nulo
`kind` obrigatório	"PIX_KEY" \| "BANK_ACCOUNT"
`maskedDestination` obrigatório	texto
`status` obrigatório	"ACTIVE" \| "ARCHIVED"
`versionStatus` obrigatório	"PENDING_VALIDATION" \| "VALIDATED" \| "SUPERSEDED" \| "REJECTED"
`availableFrom` obrigatório	data e hora (ISO 8601) ou nulo	Fim da quarentena de 24 h após a validação.
`usable` obrigatório	booleano
`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 200

{
  "id": "ben_01JDYA51B2C3D4E5F6G7H8J9KE",
  "versionId": "bnv_01JDYA61B2C3D4E5F6G7H8J9KF",
  "version": 1,
  "kind": "PIX_KEY",
  "maskedDestination": "Chave CNPJ ••.•••.333/0001-••",
  "status": "ACTIVE",
  "versionStatus": "VALIDATED",
  "availableFrom": "2026-11-14T13:00:00.000Z",
  "usable": true,
  "createdAt": "2026-11-13T13:00:00.000Z"
}

Erros

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