Stater Platform
API Reference

Enviar TEV

POST /v1/tev — transferência interna entre contas da plataforma, liquidação síncrona.

Envia TEV

Transferência interna (TEV) entre contas da plataforma, identificada por agência + número da conta de destino. A liquidação é síncrona: o response já traz o desfecho — kind done (liquidada), rejected (recusada, valor devolvido ao saldo) ou submitted_unknown (indeterminado; a plataforma resolve sozinha).

POST/v1/tev

TEV liquida na hora — diferente do Pix, não há estado PROCESSING quando o response é done. Em rejected (HTTP 422) o valor e a tarifa já voltaram ao saldo; leia reason para o motivo. Em submitted_unknown (HTTP 502) o desfecho é indeterminado no momento — NÃO reenvie com outra Idempotency-Key (risco de duplicar): a plataforma resolve sozinha em minutos; acompanhe via GET /v1/tev/:id ou pelos webhooks tev.out.succeeded / tev.out.failed. Destino inexistente retorna 400; conflito de Idempotency-Key ou externalRef retorna 409. Tarifas: a conta de origem paga a tarifa de envio (tevOut*) e a de destino paga a de recebimento (tevIn*) — veja GET /v1/pix-accounts/:accountId/fees.

Headers

  • AuthorizationObrigatório
    string
    Bearer SUA_API_KEY
  • Idempotency-KeyObrigatório
    string
    UUID para retry seguro — obrigatório. Reenviar com a mesma chave devolve o resultado original, sem transferir duas vezes.
  • Content-TypeObrigatório
    string
    application/json

Body

  • destinationBranchObrigatório
    string
    Agência da conta de destino (com ou sem zeros à esquerda).
  • destinationAccountObrigatório
    string
    Número da conta de destino (com ou sem zeros à esquerda).
  • amountCentsObrigatório
    string | number
    Valor a transferir em centavos.
  • description
    string (≤ 140)
    Descrição livre. Vai para o extrato bancário das duas contas; imutável após o envio.
  • externalRef
    string (≤ 128)
    Referência externa do seu sistema (ex.: ID do pedido). Única por conta de origem.

Exemplo de requisição

bash
curl -X POST https://api.staterpay.io/v1/tev \  -H "Authorization: Bearer SUA_API_KEY" \  -H "Idempotency-Key: 6f3f0c6e-9a1d-4a86-b7a3-0c2f4d6b8e10" \  -H "Content-Type: application/json" \  -d '{    "destinationBranch": "0001",    "destinationAccount": "598375",    "amountCents": "1500",    "description": "Repasse interno pedido #123",    "externalRef": "pedido-2026-0001"  }'

Resposta

  • kind
    "done" | "rejected" | "submitted_unknown"
    Desfecho da transferência. done → HTTP 200; rejected → HTTP 422; submitted_unknown → HTTP 502.
  • tevId
    string
    Identificador da transferência (cuid). Use em GET /v1/tev/:id.
  • status
    "DONE" | "FAILED" | "SUBMITTED_UNKNOWN"
    Estado correspondente ao kind.
  • amountCents
    string
    Valor transferido em centavos (presente quando done).
  • feeCents
    string
    Tarifa de envio debitada da conta de origem (presente quando done).
  • reason
    string
    Motivo da recusa ou da indeterminação (presente quando rejected ou submitted_unknown).
  • providerStatusCode
    number
    Status HTTP retornado pelo provedor (presente quando rejected).
json
{  "kind": "done",  "tevId": "cmoxample0001qkxyztev000",  "status": "DONE",  "amountCents": "1500",  "feeCents": "0"}
URL base:https://api.staterpay.io

Movimento por endToEndId

GET /v1/payouts/end-to-end-id/:endToEndId/movement — movimento contábil pelo endToEndId.

Consultar TEV

GET /v1/tev/:id — consulta a transferência interna pela origem ou pelo destino.

On this page

HeadersBodyExemplo de requisiçãoResposta