Stater Platform

Enviar TEV

POST /accounts/:accountId/tev/payment — transferência interna com liquidação síncrona.

Enviar TEV

Etapa 2 do fluxo de transferência interna (TEV): envia para outra conta da plataforma, identificada pelo accountNumber confirmado em /tev/beneficiary. A liquidação é síncrona: o response já traz o desfecho (done, rejected ou submitted_unknown).

POST/accounts/:accountId/tev/payment

Etapa 2 de 2 — antes desta chamada, faça POST /tev/beneficiary pra resolver o documento e confirmar visualmente o beneficiário. TEV liquida na hora — sem estado PROCESSING quando o response é done. Em rejected (HTTP 422) o valor já voltou ao saldo; leia tev.reason. Em submitted_unknown (HTTP 502) NÃO reenvie com outra Idempotency-Key: a plataforma resolve sozinha em minutos e o extrato reflete o desfecho. Contas com dupla alçada habilitada recebem HTTP 202 com { approvalRequestId, status, expiresAt } — a TEV executa quando o aprovador autorizar (mesma esteira do Pix). Destino restrito ao mesmo tenant; transferir para a própria conta retorna 400. TEV é interna: nunca cruza bancos externos (use Pix pra isso). No extrato as partes aparecem como "TEV Enviada para/Recebida de <titular>", com nome e documento preenchidos.

Path params

  • accountIdObrigatório
    string (UUID)
    ID da conta que vai enviar a TEV.

Headers

  • AcceptObrigatório
    string
    application/json
  • Content-TypeObrigatório
    string
    application/json
  • AuthorizationObrigatório
    string
    Bearer <token> — JWT de /authenticate.
  • X-Tenant-IdObrigatório
    string (UUID)
    Identificador do tenant.
  • Idempotency-Key
    string (UUID)
    Opcional, recomendado. Reenviar com a mesma chave devolve o resultado original, sem transferir duas vezes. Sem o header, uma chave é gerada a cada chamada.

Body

  • accountNumberObrigatório
    string
    Número da conta beneficiária (mesma plataforma). Use o valor de beneficiary.accounts[].accountNumber retornado em /tev/beneficiary.
  • amountObrigatório
    number
    Valor a transferir em reais (decimal). Ex.: 0.01 = 1 centavo, 100.50 = R$ 100,50.
  • pinObrigatório
    string
    PIN da entidade (4 dígitos numéricos, conforme política do tenant).
  • description
    string (≤ 140)
    Descrição livre. Vai para o extrato bancário das duas contas. Padrão: "Transferência para <nome do beneficiário>".

Exemplo de requisição

bash
curl -X POST https://baas.staterpay.io/accounts/00000000-0000-0000-0000-000000000010/tev/payment \  -H "Accept: application/json" \  -H "Content-Type: application/json" \  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.<payload>.<signature>" \  -H "X-Tenant-Id: 00000000-0000-0000-0000-000000000000" \  -H "Idempotency-Key: 6f3f0c6e-9a1d-4a86-b7a3-0c2f4d6b8e10" \  -d '{    "accountNumber": "1000002",    "amount": 100.50,    "pin": "1234",    "description": "Repasse interno"  }'

Resposta

  • tev
    object
    Desfecho da transferência interna.
  • tev.kind
    "done" | "rejected" | "submitted_unknown"
    done → HTTP 200 (liquidada); rejected → HTTP 422 (valor devolvido ao saldo); submitted_unknown → HTTP 502 (indeterminado; resolve sozinho).
  • tev.tevId
    string (cuid)
    ID da transferência na plataforma.
  • tev.status
    "DONE" | "FAILED" | "SUBMITTED_UNKNOWN"
    Estado correspondente ao kind.
  • tev.amountCents
    string
    Valor transferido em centavos (presente quando done).
  • tev.feeCents
    string
    Tarifa de envio debitada da conta de origem (presente quando done).
  • tev.reason
    string
    Motivo da recusa ou da indeterminação (presente quando rejected ou submitted_unknown).
json
{  "tev": {    "kind": "done",    "tevId": "cmoxample0001qkxyztev000",    "status": "DONE",    "amountCents": "10050",    "feeCents": "0"  }}
URL base:https://baas.staterpay.io

On this page