Guias

Cobrança dinâmica (COB)

A COB é a cobrança Pix imediata com valor definido, expiração e metadados por pedido. É o fluxo mais comum de recebimento em ecommerce.

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.

Fluxo geral

Criar a COB no momento do checkout → recebe txId e copyPasteCode.
Exibir o QR / Pix Copia e Cola ao comprador.
Receber webhook PIX_DYNAMIC_PAID quando pago.
Confirmar via GET /integration/v1/pix/cob/{txId} antes de faturar.

Criar cobrança

POST/integration/v1/pix/cob

Campos

Campo	Tipo	Descrição
payer*	object	Dados do pagador (nome, taxIdentifier).
description*	string (140)	Descrição livre exibida no app do banco.
pixKey*	string	Chave Pix da conta beneficiária (CPF/CNPJ, e-mail, telefone E.164 ou EVP).
payment*	object	{ amount: number } — valor em reais.
expiration	integer	Duração em segundos (default 3600).
expirationDate	date-time	Data absoluta de expiração — alternativa a expiration.
txId	string	Opcional. Se omitido, é gerado pela API. Use para conciliação com seu pedido.
remoteId	string	Sua referência interna (ex.: ID do pedido).
accountId	uuid	Necessário quando a credencial atende múltiplas contas.
metadata	object	Metadados livres devolvidos em consultas e webhooks.

curl -X POST https://apiapp.dev.ideabank.com.br/integration/v1/pix/cob \
  -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 '{
    "payer": { "name": "Cliente Exemplo", "taxIdentifier": "12345678909" },
    "description": "Cobrança do pedido 12345",
    "pixKey": "+5511999999999",
    "expiration": 3600,
    "payment": { "amount": 150.00 },
    "remoteId": "pedido-12345"
  }'

Consultar cobrança

GET/integration/v1/pix/cob/{txId}

Use para confirmar o estado antes de faturar/liberar produto.

Atualizar cobrança

PUT/integration/v1/pix/cob

Ajuste valor, descrição ou expiração enquanto a COB não estiver liquidada.

Recriar cobrança

POST/integration/v1/pix/cob/recreate

Gera uma nova COB reaproveitando dados de uma anterior — útil quando a cobrança expirou.

Cancelar cobrança

DELETE/integration/v1/pix/cob/{txId}

Cancelamento vs. expiração