Playbook de integração

API do Provedor PIX Idea+Cash

Um manual único para o time técnico e de produto do seu ecommerce, SaaS ou marketplace integrar Pix de ponta a ponta sobre a conta transacional Idea+Cash — com segurança, rastreabilidade e conciliação prontas para produção.

Pré-requisito: Conta Transacional Idea+Cash

O produto é vendido como uma solução de API Pix, mas toda a operação acontece a partir da sua Conta Transacional Idea+Cash. Sem conta ativa e habilitada, não há operação Pix. Entenda em Conta Transacional.

Quem deve ler

Product Owners, líderes de engenharia, desenvolvedores e times de operações que vão avaliar, integrar ou operar a API PIX Idea+Cash.

O que você pode fazer com esta API

Receber por Pix

Gere QR Codes estáticos e dinâmicos (COB), com valor, expiração e metadados por pedido.

Enviar Pix

Pix Out por chave ou por agência/conta, com validação de chave antes da iniciação.

Webhooks em tempo real

Notificações HTTPS de liquidação, devolução e demais eventos — sem polling.

Segurança de PSP

OAuth2 client_credentials, autorização por vínculo de conta e X-Request-ID em toda resposta.

Casos de uso

Ecommerce

Cobrança na finalização de pedido, conciliação por txId e baixa automática via webhook.

Marketplace

Pix Out para sellers e fornecedores por chave Pix ou por agência/conta.

SaaS B2B

Cobranças recorrentes, cash-in de mensalidades e pagamentos automatizados a fornecedores.

Por onde começar

Guia rápido — quickstart de 5 passos, do token à primeira cobrança liquidada.
Onboarding e credenciais — como obter client_id/client_secret e o vínculo de contas.
Autenticação — OAuth2 M2M no realm ideabank-m2m.
Cobrança dinâmica (COB) — o fluxo mais comum de recebimento em ecommerce.
Webhooks — receba a liquidação e dê baixa no pedido.

Base do contrato

Versão: v1.1
Formato: JSON sobre HTTPS
Autenticação: Bearer JWT (OAuth2 client_credentials)
Erros: contrato único ErrorResponse com códigos 401/403/404/409/422/500
Rastreabilidade: header X-Request-ID em toda resposta

Pronto para produção

A API foi validada em controllers e DTOs internos. Toda evolução é registrada no changelog.