Pix

Envio e recebimento de pagamentos instantâneos via Pix, gestão de chaves e geração de QR Codes.

Endpoints

Pagamentos Pix

Método	Endpoint	Descrição	Permissão
POST	`/baas/api/v1/pix/payments`	Enviar Pix	`BAAS_PIX_SEND`
GET	`/baas/api/v1/pix/payments`	Listar pagamentos Pix	`BAAS_PIX_READ`
GET	`/baas/api/v1/pix/payments/:id`	Obter pagamento Pix por ID	`BAAS_PIX_READ`
POST	`/baas/api/v1/pix/transfers/:id/refund`	Devolver Pix (total ou parcial)	`BAAS_PIX_REFUND`

Chaves Pix

Método	Endpoint	Descrição	Permissão
POST	`/baas/api/v1/pix/keys`	Registrar chave Pix	`BAAS_PIX_KEYS_CREATE`
GET	`/baas/api/v1/pix/keys`	Listar chaves Pix	`BAAS_PIX_KEYS_READ`
DELETE	`/baas/api/v1/pix/keys/:id`	Excluir chave Pix	`BAAS_PIX_KEYS_DELETE`
POST	`/baas/api/v1/pix/keys/lookup`	Consultar chave no DICT	`BAAS_PIX_KEYS_READ`

QR Code

Método	Endpoint	Descrição	Permissão
POST	`/baas/api/v1/pix/qrcode`	Gerar QR Code	`BAAS_PIX_QRCODE_CREATE`
POST	`/baas/api/v1/pix/qr-codes/decode`	Decodificar QR Code/BRCode	`BAAS_PIX_QRCODE_READ`

Atributos do Pagamento Pix

Campo	Tipo	Descrição
`accountId`	string (UUID)	ID da conta de origem
`amount`	number	Valor do pagamento
`status`	enum	Status: `PENDING`, `PROCESSING`, `COMPLETED`, `FAILED`, `REVERSED`
`recipientKeyType`	enum	Tipo da chave do destinatário
`recipientKeyValue`	string	Valor da chave do destinatário
`description`	string	Descrição do pagamento
`e2eId`	string	ID fim-a-fim (gerado pelo SPI)
`externalRef`	string	Referência no provedor
`failureReason`	string	Motivo da falha
`completedAt`	datetime	Data de conclusão
`createdAt`	datetime	Data de criação
`updatedAt`	datetime	Data da última atualização

Atributos da Chave Pix

Campo	Tipo	Descrição
`accountId`	string (UUID)	ID da conta associada
`keyType`	enum	Tipo: `CPF`, `CNPJ`, `EMAIL`, `PHONE`, `EVP`
`keyValue`	string	Valor da chave
`status`	enum	Status: `ACTIVE`, `PENDING`, `INACTIVE`
`createdAt`	datetime	Data de criação

Enviar Pix

POST /baas/api/v1/pix/payments

Envia um pagamento instantâneo via Pix.

Atributos

Campo	Tipo	Obrigatório	Descrição
`accountId`	string	Sim	ID da conta de origem
`amount`	number	Sim	Valor do pagamento
`recipientKeyType`	enum	Sim	Tipo da chave Pix do destinatário
`recipientKeyValue`	string	Sim	Valor da chave Pix do destinatário
`description`	string	Não	Descrição do pagamento

cURL
JavaScript

curl -X POST 'https://baas.stg.catalisa.app/baas/api/v1/pix/payments' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "data": {
      "type": "pix-payments",
      "attributes": {
        "accountId": "550e8400-e29b-41d4-a716-446655440100",
        "amount": 1500.00,
        "recipientKeyType": "CPF",
        "recipientKeyValue": "12345678901",
        "description": "Pagamento fornecedor"
      }
    }
  }'

const response = await fetch('https://baas.stg.catalisa.app/baas/api/v1/pix/payments', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    data: {
      type: 'pix-payments',
      attributes: {
        accountId: '550e8400-e29b-41d4-a716-446655440100',
        amount: 1500.00,
        recipientKeyType: 'CPF',
        recipientKeyValue: '12345678901',
        description: 'Pagamento fornecedor',
      },
    },
  }),
});

const { data } = await response.json();
console.log(`Pix enviado: ${data.id}`);
console.log(`E2E ID: ${data.attributes.e2eId}`);
console.log(`Status: ${data.attributes.status}`);

Response (201 Created)

{
  "data": {
    "type": "pix-payments",
    "id": "550e8400-e29b-41d4-a716-446655440300",
    "links": {
      "self": "/baas/api/v1/pix/payments/550e8400-e29b-41d4-a716-446655440300"
    },
    "attributes": {
      "accountId": "550e8400-e29b-41d4-a716-446655440100",
      "amount": 1500.00,
      "status": "PROCESSING",
      "recipientKeyType": "CPF",
      "recipientKeyValue": "12345678901",
      "description": "Pagamento fornecedor",
      "e2eId": "E12345678202401151030abcdefghijkl",
      "externalRef": null,
      "failureReason": null,
      "completedAt": null,
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T10:30:00Z"
    }
  },
  "links": {
    "self": "/baas/api/v1/pix/payments/550e8400-e29b-41d4-a716-446655440300"
  }
}

Listar Pagamentos Pix

GET /baas/api/v1/pix/payments

Lista pagamentos Pix com suporte a paginação e filtros.

Query Parameters

Parâmetro	Tipo	Descrição
`page[number]`	integer	Número da página
`page[size]`	integer	Itens por página
`filter[accountId]`	UUID	Filtrar por conta
`filter[status]`	enum	Filtrar por status
`filter[dateFrom]`	date	Data inicial (YYYY-MM-DD)
`filter[dateTo]`	date	Data final (YYYY-MM-DD)

cURL
JavaScript

curl 'https://baas.stg.catalisa.app/baas/api/v1/pix/payments?filter[accountId]=550e8400-e29b-41d4-a716-446655440100&filter[status]=COMPLETED' \
  -H 'Authorization: Bearer SEU_TOKEN'

const params = new URLSearchParams({
  'filter[accountId]': '550e8400-e29b-41d4-a716-446655440100',
  'filter[status]': 'COMPLETED',
});

const response = await fetch(`https://baas.stg.catalisa.app/baas/api/v1/pix/payments?${params}`, {
  headers: {
    'Authorization': `Bearer ${token}`,
  },
});

const { data, meta } = await response.json();
console.log(`Total de pagamentos Pix: ${meta.totalItems}`);

Registrar Chave Pix

POST /baas/api/v1/pix/keys

Registra uma nova chave Pix vinculada a uma conta bancária.

Atributos

Campo	Tipo	Obrigatório	Descrição
`accountId`	string	Sim	ID da conta
`keyType`	enum	Sim	Tipo: `CPF`, `CNPJ`, `EMAIL`, `PHONE`, `EVP`
`keyValue`	string	Condicional	Valor da chave (não necessário para `EVP`)

cURL
JavaScript

curl -X POST 'https://baas.stg.catalisa.app/baas/api/v1/pix/keys' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "data": {
      "type": "pix-keys",
      "attributes": {
        "accountId": "550e8400-e29b-41d4-a716-446655440100",
        "keyType": "EMAIL",
        "keyValue": "financeiro@empresa-abc.com.br"
      }
    }
  }'

const response = await fetch('https://baas.stg.catalisa.app/baas/api/v1/pix/keys', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    data: {
      type: 'pix-keys',
      attributes: {
        accountId: '550e8400-e29b-41d4-a716-446655440100',
        keyType: 'EMAIL',
        keyValue: 'financeiro@empresa-abc.com.br',
      },
    },
  }),
});

const { data } = await response.json();
console.log(`Chave Pix registrada: ${data.id}`);
console.log(`Status: ${data.attributes.status}`);

Response (201 Created)

{
  "data": {
    "type": "pix-keys",
    "id": "550e8400-e29b-41d4-a716-446655440310",
    "links": {
      "self": "/baas/api/v1/pix/keys/550e8400-e29b-41d4-a716-446655440310"
    },
    "attributes": {
      "accountId": "550e8400-e29b-41d4-a716-446655440100",
      "keyType": "EMAIL",
      "keyValue": "financeiro@empresa-abc.com.br",
      "status": "ACTIVE",
      "createdAt": "2024-01-15T10:30:00Z"
    }
  }
}

Listar Chaves Pix

GET /baas/api/v1/pix/keys

Lista as chaves Pix cadastradas.

Query Parameters

Parâmetro	Tipo	Descrição
`filter[accountId]`	UUID	Filtrar por conta
`filter[keyType]`	enum	Filtrar por tipo de chave

cURL
JavaScript

curl 'https://baas.stg.catalisa.app/baas/api/v1/pix/keys?filter[accountId]=550e8400-e29b-41d4-a716-446655440100' \
  -H 'Authorization: Bearer SEU_TOKEN'

const params = new URLSearchParams({
  'filter[accountId]': '550e8400-e29b-41d4-a716-446655440100',
});

const response = await fetch(`https://baas.stg.catalisa.app/baas/api/v1/pix/keys?${params}`, {
  headers: {
    'Authorization': `Bearer ${token}`,
  },
});

const { data } = await response.json();
data.forEach((key) => {
  console.log(`${key.attributes.keyType}: ${key.attributes.keyValue}`);
});

Excluir Chave Pix

DELETE /baas/api/v1/pix/keys/:id

Remove uma chave Pix cadastrada.

cURL
JavaScript

curl -X DELETE 'https://baas.stg.catalisa.app/baas/api/v1/pix/keys/550e8400-e29b-41d4-a716-446655440310' \
  -H 'Authorization: Bearer SEU_TOKEN'

const keyId = '550e8400-e29b-41d4-a716-446655440310';

const response = await fetch(`https://baas.stg.catalisa.app/baas/api/v1/pix/keys/${keyId}`, {
  method: 'DELETE',
  headers: {
    'Authorization': `Bearer ${token}`,
  },
});

if (response.status === 204) {
  console.log('Chave Pix excluída com sucesso');
}

Response (204 No Content)

Sem corpo de resposta.

Gerar QR Code

POST /baas/api/v1/pix/qrcode

Gera um QR Code Pix estático ou dinâmico para recebimento.

Atributos

Campo	Tipo	Obrigatório	Descrição
`accountId`	string	Sim	ID da conta recebedora
`type`	enum	Sim	`STATIC` ou `DYNAMIC`
`amount`	number	Condicional	Valor (obrigatório para `DYNAMIC`)
`description`	string	Não	Descrição do pagamento
`expiresInMinutes`	integer	Não	Expiração em minutos (apenas `DYNAMIC`)

cURL
JavaScript

curl -X POST 'https://baas.stg.catalisa.app/baas/api/v1/pix/qrcode' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "data": {
      "type": "pix-qrcode",
      "attributes": {
        "accountId": "550e8400-e29b-41d4-a716-446655440100",
        "type": "DYNAMIC",
        "amount": 250.00,
        "description": "Pagamento pedido #1234",
        "expiresInMinutes": 30
      }
    }
  }'

const response = await fetch('https://baas.stg.catalisa.app/baas/api/v1/pix/qrcode', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    data: {
      type: 'pix-qrcode',
      attributes: {
        accountId: '550e8400-e29b-41d4-a716-446655440100',
        type: 'DYNAMIC',
        amount: 250.00,
        description: 'Pagamento pedido #1234',
        expiresInMinutes: 30,
      },
    },
  }),
});

const { data } = await response.json();
console.log(`QR Code: ${data.attributes.qrCodeText}`);
console.log(`Imagem (base64): ${data.attributes.qrCodeImage}`);
console.log(`Expira em: ${data.attributes.expiresAt}`);

Response (201 Created)

{
  "data": {
    "type": "pix-qrcode",
    "id": "550e8400-e29b-41d4-a716-446655440320",
    "attributes": {
      "accountId": "550e8400-e29b-41d4-a716-446655440100",
      "type": "DYNAMIC",
      "amount": 250.00,
      "description": "Pagamento pedido #1234",
      "qrCodeText": "00020126580014br.gov.bcb.pix0136550e8400-e29b-41d4-a716-446655440100...",
      "qrCodeImage": "data:image/png;base64,iVBORw0KGgo...",
      "expiresAt": "2024-01-15T11:00:00Z",
      "createdAt": "2024-01-15T10:30:00Z"
    }
  }
}

Devolver Pix (Refund)

POST /baas/api/v1/pix/transfers/:id/refund

Realiza a devolução total ou parcial de um pagamento Pix recebido. A devolução pode ser solicitada em até 90 dias após o recebimento do Pix original.

Atributos

Campo	Tipo	Obrigatório	Descrição
`amount`	number	Não	Valor da devolução (se omitido, devolução total)
`reason`	string	Não	Motivo da devolução

Devolução parcial

É possível realizar múltiplas devoluções parciais para o mesmo Pix, desde que a soma total não ultrapasse o valor original recebido.

cURL
JavaScript

curl -X POST 'https://baas.stg.catalisa.app/baas/api/v1/pix/transfers/550e8400-e29b-41d4-a716-446655440300/refund' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "data": {
      "type": "pix-refunds",
      "attributes": {
        "amount": 500.00,
        "reason": "Produto devolvido pelo cliente"
      }
    }
  }'

const transferId = '550e8400-e29b-41d4-a716-446655440300';

const response = await fetch(`https://baas.stg.catalisa.app/baas/api/v1/pix/transfers/${transferId}/refund`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    data: {
      type: 'pix-refunds',
      attributes: {
        amount: 500.00,
        reason: 'Produto devolvido pelo cliente',
      },
    },
  }),
});

const { data } = await response.json();
console.log(`Devolução criada: ${data.id}`);
console.log(`Valor devolvido: R$ ${data.attributes.amount.toFixed(2)}`);
console.log(`Status: ${data.attributes.status}`);

Response (201 Created)

{
  "data": {
    "type": "pix-refunds",
    "id": "550e8400-e29b-41d4-a716-446655440350",
    "attributes": {
      "transferId": "550e8400-e29b-41d4-a716-446655440300",
      "amount": 500.00,
      "status": "PROCESSING",
      "reason": "Produto devolvido pelo cliente",
      "e2eId": "D12345678202401151030abcdefghijkl",
      "createdAt": "2024-01-15T14:00:00Z",
      "updatedAt": "2024-01-15T14:00:00Z"
    }
  }
}

Consultar Chave no DICT (Lookup)

POST /baas/api/v1/pix/keys/lookup

Consulta informações de uma chave Pix no Diretório de Identificadores de Contas Transacionais (DICT) do Banco Central. Permite validar se a chave existe e obter os dados do recebedor antes de efetuar um pagamento.

Atributos

Campo	Tipo	Obrigatório	Descrição
`keyType`	enum	Sim	Tipo da chave: `CPF`, `CNPJ`, `EMAIL`, `PHONE`, `EVP`
`keyValue`	string	Sim	Valor da chave Pix

cURL
JavaScript

curl -X POST 'https://baas.stg.catalisa.app/baas/api/v1/pix/keys/lookup' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "data": {
      "type": "pix-key-lookup",
      "attributes": {
        "keyType": "CPF",
        "keyValue": "12345678901"
      }
    }
  }'

const response = await fetch('https://baas.stg.catalisa.app/baas/api/v1/pix/keys/lookup', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    data: {
      type: 'pix-key-lookup',
      attributes: {
        keyType: 'CPF',
        keyValue: '12345678901',
      },
    },
  }),
});

const { data } = await response.json();
console.log(`Titular: ${data.attributes.owner.name}`);
console.log(`Banco: ${data.attributes.account.bankName}`);
console.log(`Agência: ${data.attributes.account.branch}`);
console.log(`Conta: ${data.attributes.account.accountNumber}`);

Response (200 OK)

{
  "data": {
    "type": "pix-key-lookup",
    "attributes": {
      "keyType": "CPF",
      "keyValue": "12345678901",
      "owner": {
        "name": "João Silva",
        "document": "***456789**",
        "documentType": "CPF"
      },
      "account": {
        "bankCode": "260",
        "bankName": "Nu Pagamentos",
        "branch": "0001",
        "accountNumber": "98765-4",
        "accountType": "CHECKING"
      },
      "createdAt": "2023-06-15T10:30:00Z"
    }
  }
}

Dados mascarados

Por questões de segurança e conformidade com o Banco Central, o CPF/CNPJ do titular é retornado parcialmente mascarado na consulta DICT.

Decodificar QR Code / BRCode

POST /baas/api/v1/pix/qr-codes/decode

Decodifica um QR Code Pix (BRCode) e retorna as informações do pagamento, incluindo dados do recebedor, valor e chave Pix. Útil para validar e exibir os dados ao usuário antes de confirmar o pagamento.

Atributos

Campo	Tipo	Obrigatório	Descrição
`qrCodeText`	string	Sim	Texto do QR Code Pix (payload BRCode)

cURL
JavaScript

curl -X POST 'https://baas.stg.catalisa.app/baas/api/v1/pix/qr-codes/decode' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "data": {
      "type": "pix-qrcode-decode",
      "attributes": {
        "qrCodeText": "00020126580014br.gov.bcb.pix0136550e8400-e29b-41d4-a716-446655440100..."
      }
    }
  }'

const response = await fetch('https://baas.stg.catalisa.app/baas/api/v1/pix/qr-codes/decode', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    data: {
      type: 'pix-qrcode-decode',
      attributes: {
        qrCodeText: '00020126580014br.gov.bcb.pix0136550e8400-e29b-41d4-a716-446655440100...',
      },
    },
  }),
});

const { data } = await response.json();
console.log(`Tipo: ${data.attributes.type}`);
console.log(`Valor: R$ ${data.attributes.amount?.toFixed(2) || 'Livre'}`);
console.log(`Recebedor: ${data.attributes.recipient.name}`);
console.log(`Chave: ${data.attributes.keyValue}`);

Response (200 OK)

{
  "data": {
    "type": "pix-qrcode-decode",
    "attributes": {
      "type": "DYNAMIC",
      "keyType": "EVP",
      "keyValue": "550e8400-e29b-41d4-a716-446655440100",
      "amount": 250.00,
      "description": "Pagamento pedido #1234",
      "recipient": {
        "name": "Empresa ABC Ltda",
        "document": "12.345.678/0001-90",
        "documentType": "CNPJ",
        "bankName": "Banco Principal",
        "bankCode": "001"
      },
      "expiresAt": "2024-01-15T11:00:00Z",
      "createdAt": "2024-01-15T10:30:00Z"
    }
  }
}

Erros Comuns

Código	Erro	Descrição
400	`VALIDATION`	Dados inválidos (chave, valor, tipo, etc.)
400	`INSUFFICIENT_BALANCE`	Saldo insuficiente para envio
404	`NOT_FOUND`	Conta, chave ou pagamento não encontrado
404	`KEY_NOT_FOUND`	Chave Pix não encontrada no DICT
409	`CONFLICT`	Chave Pix já registrada em outra conta
409	`CONFLICT`	Conta não está ativa
409	`REFUND_EXCEEDED`	Valor de devolução excede o valor original
422	`UNPROCESSABLE`	Chave Pix do destinatário inválida ou inexistente
422	`INVALID_QRCODE`	QR Code Pix inválido ou expirado

Endpoints​

Pagamentos Pix​

Chaves Pix​

QR Code​

Atributos do Pagamento Pix​

Atributos da Chave Pix​

Enviar Pix​

Atributos​

Response (201 Created)​

Listar Pagamentos Pix​

Query Parameters​

Registrar Chave Pix​

Atributos​

Response (201 Created)​

Listar Chaves Pix​

Query Parameters​

Excluir Chave Pix​

Response (204 No Content)​

Gerar QR Code​

Atributos​

Response (201 Created)​

Devolver Pix (Refund)​

Atributos​

Response (201 Created)​

Consultar Chave no DICT (Lookup)​

Atributos​

Response (200 OK)​

Decodificar QR Code / BRCode​

Atributos​

Response (200 OK)​

Erros Comuns​

Endpoints

Pagamentos Pix

Chaves Pix

QR Code

Atributos do Pagamento Pix

Atributos da Chave Pix

Enviar Pix

Atributos

Response (201 Created)

Listar Pagamentos Pix

Query Parameters

Registrar Chave Pix

Atributos

Response (201 Created)

Listar Chaves Pix

Query Parameters

Excluir Chave Pix

Response (204 No Content)

Gerar QR Code

Atributos

Response (201 Created)

Devolver Pix (Refund)

Atributos

Response (201 Created)

Consultar Chave no DICT (Lookup)

Atributos

Response (200 OK)

Decodificar QR Code / BRCode

Atributos

Response (200 OK)

Erros Comuns