Stater Platform

Enviar Pix

POST /accounts/:accountId/pix/payment — etapa 2 do fluxo (efetiva a transferência).

Enviar Pix

Etapa 2 do fluxo de transferência Pix: efetiva o pagamento usando o keyInfoId retornado em /pix/key-info. Retorna imediatamente com status PROCESSING — o endToEndId definitivo só é emitido após a confirmação do provider.

POST/accounts/:accountId/pix/payment

Etapa 2 de 2. Antes desta chamada, sempre faça POST /pix/key-info pra resolver a chave e obter o keyInfoId — não é possível enviar Pix por chave bruta. amount em reais decimal (atenção: diferente da API Pix base, que usa centavos string). PIN incorreto retorna 4xx. saveFavoriteKey=true persiste a chave em /pix/favorites com o saveFavoriteKeyAlias (use o name de key-info se não quiser definir alias). O status final (SUCCEEDED, FAILED, etc.) chega por reconciliação — consulte a transação por id em /accounts/:accountId/transactions ou aguarde callbacks.

Path params

  • accountIdObrigatório
    string (UUID)
    ID da conta que vai enviar o Pix.

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.

Body

  • keyInfoIdObrigatório
    string (UUID)
    ID retornado em key.id de POST /pix/key-info. Vincula o pagamento ao destinatário já confirmado.
  • 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).
  • saveFavoriteKey
    boolean
    Opcional. Se true, salva a chave como favorito da conta após o envio bem-sucedido — aparece em GET /pix/favorites.
  • saveFavoriteKeyAlias
    string
    Opcional. Apelido para exibir junto do favorito (ex.: "Conta do João"). Usado só quando saveFavoriteKey=true.

Exemplo de requisição

curl -X POST https://baas.staterpay.io/accounts/00000000-0000-0000-0000-000000000010/pix/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" \  -d '{    "keyInfoId": "00000000-0000-0000-0000-0000000000d1",    "amount": 0.01,    "pin": "1234"  }'

Resposta

  • transaction
    string (cuid)
    ID da transação registrada na conta. Aparece em /transactions como transactions[].id.
  • payout
    object
    Resumo do payout submetido ao provider.
  • payout.kind
    "submitted"
    Marca a criação como submetida.
  • payout.payoutId
    string (cuid)
    ID do payout no sistema Pix subjacente.
  • payout.status
    "PROCESSING" | "SUCCEEDED" | "FAILED" | "CANCELLED" | "REFUNDED"
    Estado inicial sempre PROCESSING.
  • payout.endToEndId
    string | null
    Sempre null na criação. Preenchido após liquidação no provider.
  • payout.providerTransactionId
    string
    ID da transação no provider Pix subjacente.
json
{  "transaction": "cmoxample0001qkxyzpayout",  "payout": {    "kind": "submitted",    "payoutId": "cmoxample0001qkxyzpayout",    "status": "PROCESSING",    "endToEndId": null,    "providerTransactionId": "00000000"  }}
URL base:https://baas.staterpay.io

Consultar chave Pix

POST /accounts/:accountId/pix/key-info — etapa 1 do fluxo de transferência Pix.

Listar favoritos Pix

GET /accounts/:id/pix/favorites — contatos Pix favoritados com snapshot DICT.

On this page

Path paramsHeadersBodyExemplo de requisiçãoResposta