Guias

Pix Out

Envie Pix a partir da chave do beneficiário ou informando agência, conta e ISPB. Escolha o modo conforme o dado disponível.

Referência de conta e headers

Toda request sobre uma conta identifica a conta por header: envie account-id (o accountId recebido no onboarding), wallet-id ou tax-identifier — precedência wallet-id > tax-identifier > account-id. Some a isso Authorization e tenantid; em DEV, também hostdevelop: apiapp.dev.ideabank.com.br. Sem nenhum header de conta a API responde 422 (account, wallet or tax-identifier header is required); se a integração não estiver vinculada à conta, 403.

Pix Out por chave

Envie um Pix para qualquer chave (CPF/CNPJ, e-mail, telefone ou EVP) usando um único endpoint. Valide a chave antes para garantir a titularidade.

Fluxo recomendado

Validar a chave — confirme o titular no DICT e exiba o nome ao seu operador antes da confirmação.
Enviar o Pix Out.
Persistir o endToEndId retornado e o seu remoteId.
Consultar por endToEndId em caso de dúvida sobre o estado.

POST/integration/v1/pix/transfers

Campos principais

Campo	Tipo	Descrição
transaction.remoteId*	uuid	Sua chave de idempotência (obrigatória).
transaction.amount*	number	Valor em reais.
transaction.pixInfo.key*	string	Chave do beneficiário.
transaction.pixInfo.keyType	int	1=CPF/CNPJ, 2=EMAIL, 3=PHONE, 4=EVP. Recomendado informar.
transaction.reason	string	Descrição / motivo, exibido no extrato.
verify.type	string	Ex.: 'ALLOW' — política de verificação prévia da chave.

curl -X POST https://apiapp.dev.ideabank.com.br/integration/v1/pix/transfers \
  -H "Authorization: Bearer $TOKEN" \
  -H "tenantid: $TENANT_ID" -H "account-id: $ACCOUNT_ID" -H "hostdevelop: apiapp.dev.ideabank.com.br" -H "Content-Type: application/json" \
  -d '{
    "verify": { "type": "ALLOW" },
    "transaction": {
      "remoteId": "11111111-2222-3333-4444-555555555555",
      "amount": 125.45,
      "reason": "Transferência Pix para fornecedor",
      "pixInfo": {
        "key": "+5511999999999",
        "keyType": 3
      }
    }
  }'

Idempotência é obrigatória

Use um remoteId (UUID) único por tentativa lógica de pagamento. Em caso de timeout na rede, repita a chamada com o mesmo remoteId — a API devolve o resultado da execução anterior em vez de duplicar o Pix.

Pix Out por agência/conta

Use quando o beneficiário não possui chave Pix e precisa receber por dados bancários (agência, conta e ISPB). É o mesmo endpoint do Pix Out por chave — troque pixInfo por pixAgencyInfo no payload.

POST/integration/v1/pix/transfers

curl -X POST https://apiapp.dev.ideabank.com.br/integration/v1/pix/transfers \
  -H "Authorization: Bearer $TOKEN" \
  -H "tenantid: $TENANT_ID" -H "account-id: $ACCOUNT_ID" -H "hostdevelop: apiapp.dev.ideabank.com.br" -H "Content-Type: application/json" \
  -d '{
    "transaction": {
      "remoteId": "11111111-2222-3333-4444-555555555555",
      "amount": 300.00,
      "reason": "Pagamento NF 998",
      "pixAgencyInfo": {
        "branch": "0001",
        "account": "123456789",
        "ispb": "12345678",
        "name": "Fornecedor Exemplo LTDA",
        "taxIdentifier": "12345678000195",
        "accountType": "CACC"
      }
    }
  }'

Contrato exato dos campos

Os nomes de campos internos de source e destinations seguem os DTOs internos e podem variar por perfil de conta. Consulte a especificação Swagger para o payload exato provisionado no seu ambiente.