PIX

Todos os endpoints de PIX exigem Authorization: Bearer <token> e o header x-client-id: <Client_ID> — o tenant id é o mesmo valor do Client_ID do OAuth (veja Autenticação → Tenant ID). Sem ele, as chamadas falham com 400 MISSING_CLIENT_ID.

Visão geral

O PIX é um sistema de pagamentos em tempo real disponível 24/7, todos os dias do ano. Ele atende transferências entre pessoas (P2P), de pessoa para empresa (P2B) e entre empresas (B2B).

Principais características

Liquidação instantânea: dinheiro transferido em segundos (24/7)
Chaves estáticas: CPF, e-mail, telefone, aleatória (EVP)
QR Codes estáticos: QR Code reutilizável para receber pagamentos
Sem tarifas: transferências PIX têm custo zero
Devoluções: disponíveis em até 1 hora após o recebimento

Tipos de chave PIX

Tipo	Formato	Exemplo	Observações
CPF	11 dígitos	`48059890093`	Cadastro de pessoa física
CNPJ	14 dígitos	`37702652000188`	Cadastro de pessoa jurídica
EMAIL	RFC 5322	`[email protected]`	Endereço de e-mail (estável)
PHONE	+55 + DDD + 9 dígitos	`+5511999999999`	Número de celular (estável)
EVP (Aleatória)	UUID de 36 caracteres	`550e8400-e29b-41d4-a716-446655440000`	Gerada aleatoriamente (estável)

POST `/v1/pix/create`

Cadastra uma nova chave PIX estática para uma conta.

Body:

json

{
  "key": "[email protected]",
  "keyType": "EMAIL",
  "accountId": "30054029183",
  "onBoardingId": "48059890093"
}

Campo	Tipo	Obrigatório	Descrição
`key`	string	Sim	Valor da chave PIX (o formato depende do `keyType`)
`keyType`	string	Sim	`CPF`, `CNPJ`, `EMAIL`, `PHONE` ou `EVP`
`accountId`	string	Sim	Número da conta
`onBoardingId`	string	Sim	Onboarding id da conta — recomenda-se o CPF/CNPJ do titular (o id retornado pelo `/create` também funciona; o formato varia por provedor)

Exemplo:

bash

curl -X POST https://baas-gtw.axiadigitalsolutions.com/v1/pix/create \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "x-client-id: <your Client_ID (tenant id)>" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "[email protected]",
    "keyType": "EMAIL",
    "accountId": "30054029183",
    "onBoardingId": "48059890093"
  }'

Response 200 OK:

json

{
  "status": "CONFIRMED",
  "data": {
    "pixKeyId": "key_550e8400-e29b-41d4-a716-446655440000",
    "keyType": "EMAIL",
    "keyValue": "[email protected]",
    "accountId": "30054029183",
    "createdAt": "2024-03-15T10:00:00Z",
    "status": "ACTIVE"
  }
}

Erros: falhas retornam { "message": "..." } com o status HTTP correspondente — causas típicas: formato de chave inválido (e-mail malformado, CPF com tamanho errado) ou chave já cadastrada para esta conta. Consulte Tratamento de Erros.

POST `/v1/pix/exclude`

Remove uma chave PIX cadastrada.

Body:

json

{
  "key": "[email protected]",
  "idAccount": "30054029183",
  "onBoardingId": "48059890093"
}

Campo	Tipo	Obrigatório	Descrição
`key`	string	Sim	Chave PIX a remover
`idAccount`	string	Sim	Número da conta
`onBoardingId`	string	Sim	Onboarding id da conta — recomenda-se o CPF/CNPJ do titular (o id retornado pelo `/create` também funciona; o formato varia por provedor)

Response 200 OK:

json

{
  "status": "CONFIRMED",
  "data": {
    "message": "PIX key removed successfully"
  }
}

GET `/v1/pix/getKeys`

Lista todas as chaves PIX estáticas cadastradas para uma conta.

Query params:

Param	Tipo	Obrigatório	Descrição
`accountId`	string	Sim	Número da conta
`documentNumber`	string	Sim	CPF ou CNPJ

Exemplo:

bash

curl -X GET "https://baas-gtw.axiadigitalsolutions.com/v1/pix/getKeys?accountId=30054029183&documentNumber=48059890093" \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "x-client-id: <your Client_ID (tenant id)>"

Response 200 OK:

json

{
  "status": "CONFIRMED",
  "data": {
    "keys": [
      {
        "key": "[email protected]",
        "keyType": "EMAIL",
        "createdAt": "2026-01-15T10:00:00Z"
      },
      {
        "key": "550e8400-e29b-41d4-a716-446655440000",
        "keyType": "EVP",
        "createdAt": "2026-01-10T08:30:00Z"
      }
    ]
  }
}

POST `/v1/pix/getAccountInfoByPixKey`

Consulta os dados do titular a partir de uma chave PIX (consulta ao DICT). Retorna o nome do recebedor e os dados da conta.

Body:

json

{
  "key": "[email protected]",
  "payerId": "48059890093",
  "idAccount": "30054029183",
  "onBoardingId": "48059890093",
  "type": "EMAIL"
}

Campo	Tipo	Obrigatório	Descrição
`key`	string	Sim	Chave PIX a consultar
`payerId`	string	Sim	CPF/CNPJ do pagador (somente números)
`idAccount`	string	Sim	Número da conta do pagador
`onBoardingId`	string	Sim	Onboarding id do pagador
`type`	string	Não	Tipo da chave: `CPF`, `CNPJ`, `EMAIL`, `PHONE` ou `EVP`

Response 200 OK:

json

{
  "status": "CONFIRMED",
  "data": {
    "name": "João da Silva",
    "taxId": "48059890093",
    "bank": "30306294",
    "accountType": "CACC"
  }
}

POST `/v1/pix/transfer`

Executa uma transferência PIX usando uma chave estática cadastrada ou os dados da conta.

Headers:

Header	Valor	Obrigatório
`x-client-id`	Seu tenant id — mesmo valor do `Client_ID` do OAuth (detalhes)	Sim
`Idempotency-Key`	UUID v4	Recomendado

Body:

json

{
  "amount": "150.00",
  "debitParty": {
    "taxId": "48059890093",
    "name": "João da Silva",
    "branch": "0001",
    "account": "123456",
    "accountType": "CACC"
  },
  "creditParty": {
    "bank": "30306294",
    "taxId": "48059890093",
    "name": "Maria da Silva",
    "key": "[email protected]",
    "branch": "0001",
    "account": "654321",
    "accountType": "CACC"
  },
  "initiationType": "DICT",
  "remittanceInformation": "Aluguel janeiro",
  "paymentType": "IMMEDIATE",
  "urgency": "HIGH",
  "transactionType": "TRANSFER",
  "userId": "cfd11a01-293d-4573-9d28-2d7261d79aaf",
  "onBoardingId": "48059890093"
}

Campo	Tipo	Obrigatório	Descrição
`amount`	string	Sim	Valor em BRL
`debitParty.taxId`	string	Sim	CPF ou CNPJ do pagador
`debitParty.name`	string	Sim	Nome do pagador
`debitParty.branch`	string	Sim	Agência do pagador
`debitParty.account`	string	Sim	Número da conta do pagador
`debitParty.accountType`	string	Sim	`CACC` (conta corrente) ou `SVGS` (poupança)
`creditParty.bank`	string	Sim	Código ISPB do banco do recebedor
`creditParty.taxId`	string	Sim	CPF ou CNPJ do recebedor
`creditParty.name`	string	Sim	Nome do recebedor
`creditParty.key`	string	Não	Chave PIX do recebedor (e-mail, CPF, telefone, EVP)
`creditParty.branch`	string	Sim	Agência do recebedor
`creditParty.account`	string	Sim	Número da conta do recebedor
`creditParty.accountType`	string	Sim	`CACC` ou `SVGS`
`initiationType`	string	Sim	`DICT` (via chave PIX) ou `MANUAL`
`remittanceInformation`	string	Sim	Descrição (até 140 caracteres)
`paymentType`	string	Sim	`IMMEDIATE` (valor fixo)
`urgency`	string	Sim	`HIGH` ou `NORMAL`
`transactionType`	string	Sim	Tipo da transação (ex.: `TRANSFER`)
`userId`	string	Sim	ID interno do usuário
`onBoardingId`	string	Sim	Onboarding id da conta — recomenda-se o CPF/CNPJ do titular (o id retornado pelo `/create` também funciona; o formato varia por provedor)

Exemplo:

bash

curl -X POST https://baas-gtw.axiadigitalsolutions.com/v1/pix/transfer \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "Content-Type: application/json" \
  -H "x-client-id: <your Client_ID (tenant id)>" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{
    "amount": "150.00",
    "debitParty": {
      "taxId": "48059890093",
      "name": "João da Silva",
      "branch": "0001",
      "account": "123456",
      "accountType": "CACC"
    },
    "creditParty": {
      "bank": "30306294",
      "taxId": "48059890093",
      "name": "Maria da Silva",
      "key": "[email protected]",
      "branch": "0001",
      "account": "654321",
      "accountType": "CACC"
    },
    "initiationType": "DICT",
    "remittanceInformation": "Aluguel janeiro",
    "paymentType": "IMMEDIATE",
    "urgency": "HIGH",
    "transactionType": "TRANSFER",
    "userId": "cfd11a01-293d-4573-9d28-2d7261d79aaf",
    "onBoardingId": "48059890093"
  }'

Response 200 OK:

json

{
  "status": "CONFIRMED",
  "data": {
    "transactionId": "E384040820262603101234567890",
    "endToEndId": "E384040820262603101234567890",
    "status": "CONFIRMED",
    "createdAt": "2024-03-15T10:30:00Z"
  }
}

Response 202 Accepted (Antifraude):

Pode ser retornado quando a transação exige aprovação manual.

Erros: falhas retornam { "message": "..." } com o status HTTP correspondente — causas típicas: saldo insuficiente, recebedor não encontrado (chave PIX inválida) ou limite de transferência excedido. Consulte Tratamento de Erros.

GET `/v1/pix/check`

Consulta o status de uma transação PIX.

Query params:

Param	Tipo	Obrigatório	Descrição
`codigo`	string	Sim	Código da transação ou endToEndId

Exemplo:

bash

curl -X GET "https://baas-gtw.axiadigitalsolutions.com/v1/pix/check?codigo=E384040820262603101234567890" \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "x-client-id: <your Client_ID (tenant id)>"

Response 200 OK:

json

{
  "status": "CONFIRMED",
  "data": {
    "transactionId": "E384040820262603101234567890",
    "endToEndId": "E384040820262603101234567890",
    "amount": 150.00,
    "status": "CONFIRMED",
    "createdAt": "2024-03-15T10:30:00Z",
    "completedAt": "2024-03-15T10:30:15Z"
  }
}

POST `/v1/pix/createStaticQRCode`

Cria um QR Code PIX estático (reutilizável) para receber múltiplos pagamentos. Sem expiração.

Body:

json

{
  "key": "[email protected]",
  "accountId": "30054029183",
  "amount": 50.00,
  "transactionIdentification": "pedido-12345",
  "additionalInformation": "Pagamento ref. pedido #12345",
  "documentNumber": "48059890093"
}

Campo	Tipo	Obrigatório	Descrição
`key`	string	Sim	Chave PIX que vai receber
`accountId`	string	Sim	Número da conta
`amount`	decimal	Não	Valor fixo (omita ou use `0.00` para valor aberto)
`transactionIdentification`	string	Não	Identificador próprio (até 25 caracteres)
`additionalInformation`	string	Não	Informação adicional visível ao pagador (até 140 caracteres)
`documentNumber`	string	Sim	CPF ou CNPJ do titular da conta (obrigatório no provedor GlobalSCM)

Exemplo:

bash

curl -X POST https://baas-gtw.axiadigitalsolutions.com/v1/pix/createStaticQRCode \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "x-client-id: <your Client_ID (tenant id)>" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "[email protected]",
    "accountId": "30054029183",
    "amount": 50.00,
    "transactionIdentification": "pedido-12345",
    "additionalInformation": "Pagamento ref. pedido #12345",
    "documentNumber": "48059890093"
  }'

Response 200 OK:

json

{
  "status": "CONFIRMED",
  "data": {
    "transactionId": "5b2c1f3a-9d4e-4c2a-8f1b-0a7c6d5e4f3b",
    "emvqrcps": "00020126580014br.gov.bcb.pix0136550e8400-e29b-41d4-a716...",
    "transactionIdentification": "pedido-12345"
  }
}

POST `/v1/pix/getQRCodeDataByEmv`

Interpreta a string EMV de um QR Code PIX para extrair os dados do pagamento, sem executá-lo.

Body:

json

{
  "emv": "00020126580014br.gov.bcb.pix0136550e8400-e29b-41d4-a716-446655440000...",
  "payerId": "48059890093",
  "idAccount": "30054029183"
}

Campo	Tipo	Obrigatório	Descrição
`emv`	string	Sim	Payload EMV/brCode do QR Code
`payerId`	string	Sim	CPF ou CNPJ do pagador
`idAccount`	string	Sim	Número da conta do pagador

Response 200 OK:

json

{
  "status": "CONFIRMED",
  "data": {
    "amount": 199.90,
    "description": "Compra em Loja XYZ",
    "receiverName": "João da Silva",
    "receiverTaxId": "48059890093",
    "bank": "30306294"
  }
}

POST `/v1/pix/pixPayByQRCode`

Executa um pagamento PIX a partir da leitura de um QR Code.

Headers:

Header	Valor	Obrigatório
`x-client-id`	Seu tenant id — mesmo valor do `Client_ID` do OAuth (detalhes)	Sim
`Idempotency-Key`	UUID v4	Recomendado

Body:

json

{
  "emv": "00020126580014br.gov.bcb.pix...",
  "payerId": "48059890093",
  "idAccount": "30054029183",
  "userId": "cfd11a01-293d-4573-9d28-2d7261d79aaf",
  "amount": 50.00
}

Campo	Tipo	Obrigatório	Descrição
`emv`	string	Sim	Payload EMV/brCode do QR Code
`payerId`	string	Sim	CPF ou CNPJ do pagador
`idAccount`	string	Sim	Número da conta do pagador
`userId`	string	Sim	ID interno do usuário
`amount`	decimal	Sim	Valor do pagamento (BRL)

Exemplo:

bash

curl -X POST https://baas-gtw.axiadigitalsolutions.com/v1/pix/pixPayByQRCode \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "Content-Type: application/json" \
  -H "x-client-id: <your Client_ID (tenant id)>" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{
    "emv": "00020126580014br.gov.bcb.pix...",
    "payerId": "48059890093",
    "idAccount": "30054029183",
    "userId": "cfd11a01-293d-4573-9d28-2d7261d79aaf",
    "amount": 50.00
  }'

Response 200 OK:

json

{
  "status": "CONFIRMED",
  "data": {
    "transactionId": "E384040820262603101234567890",
    "endToEndId": "E384040820262603101234567890",
    "amount": 50.00,
    "status": "CONFIRMED",
    "createdAt": "2024-03-15T10:35:00Z"
  }
}

Erros: falhas retornam { "message": "..." } com o status HTTP correspondente — causas típicas: string EMV inválida ou malformada, saldo insuficiente. Consulte Tratamento de Erros.

Webhook: pix-payment-in

Disparado quando um pagamento PIX é recebido (creditado na conta).

Payload:

json

{
  "eventType": "pix-payment-in",
  "timestamp": "2024-03-15T10:30:00Z",
  "data": {
    "transactionId": "E384040820262603101234567890",
    "endToEndId": "E384040820262603101234567890",
    "amount": 100.50,
    "debitParty": {
      "name": "João da Silva",
      "taxId": "48059890093"
    },
    "creditParty": {
      "name": "Maria da Silva",
      "taxId": "48059890093",
      "accountId": "30054029183"
    },
    "description": "Aluguel janeiro"
  }
}

Campo	Tipo	Descrição
`eventType`	string	Sempre `pix-payment-in`
`timestamp`	ISO-8601	Momento em que o pagamento foi recebido
`data.transactionId`	string	ID da transação original
`data.endToEndId`	string	ID end-to-end (para conciliação)
`data.amount`	decimal	Valor recebido em BRL
`data.debitParty`	object	Dados do pagador
`data.creditParty`	object	Dados do recebedor (a sua conta)
`data.description`	string	Descrição/mensagem do pagamento

Casos de uso:

Atualizar o saldo em tempo real
Registrar os recebimentos PIX
Disparar a liberação do pedido ou a conciliação do pagamento da fatura

Webhook: pix-reversal-in

Disparado quando uma devolução de PIX é processada (dinheiro devolvido ao pagador original).

Payload:

json

{
  "eventType": "pix-reversal-in",
  "timestamp": "2024-03-15T10:35:00Z",
  "data": {
    "reversalId": "R384040820262603101234567890",
    "originalTransactionId": "E384040820262603101234567890",
    "amount": 100.50,
    "reason": "FRAUD",
    "description": "Reversal due to fraud report"
  }
}

POST `/v1/pix/reverse`

Solicita a devolução de um PIX em até 1 hora após o recebimento.

Body:

json

{
  "transactionId": "E384040820262603101234567890",
  "endToEndId": "E384040820262603101234567890",
  "amount": 100.50,
  "reason": "REFUND",
  "reversalDescription": "Duplo pagamento",
  "documentNumber": "48059890093"
}

Campo	Tipo	Obrigatório	Descrição
`transactionId`	string	Sim	ID da transação original a devolver
`endToEndId`	string	Sim	ID end-to-end do PIX original
`amount`	decimal	Sim	Valor da devolução (BRL); pode ser parcial
`reason`	string	Sim	`FRAUD`, `OPERATIONAL_FLAW` ou `REFUND`
`reversalDescription`	string	Não	Explicação legível (até 140 caracteres)
`documentNumber`	string	Não	CPF ou CNPJ do titular da conta

Exemplo:

bash

curl -X POST https://baas-gtw.axiadigitalsolutions.com/v1/pix/reverse \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "x-client-id: <your Client_ID (tenant id)>" \
  -H "Content-Type: application/json" \
  -d '{
    "transactionId": "E384040820262603101234567890",
    "endToEndId": "E384040820262603101234567890",
    "amount": 100.50,
    "reason": "REFUND",
    "reversalDescription": "Duplo pagamento",
    "documentNumber": "48059890093"
  }'

Response 200 OK:

json

{
  "status": "CONFIRMED",
  "data": {
    "reversalId": "R384040820262603101234567890",
    "originalTransactionId": "E384040820262603101234567890",
    "amount": 100.50,
    "status": "PROCESSING"
  }
}

Limitações:

Janela de 1 hora: a devolução precisa ser feita em até 1 hora após o recebimento
Consentimento do recebedor: o recebedor precisa aceitar a devolução (automático em falhas operacionais)
Devolução parcial: é possível devolver menos que o valor original

Erros: falhas retornam { "message": "..." } com o status HTTP correspondente — causas típicas: janela de devolução expirada (> 1 hora), recebedor recusou a devolução ou valor maior que o da transação original. Consulte Tratamento de Erros.

Fluxo completo: receber pagamento via QR Code estático

Passo 1: criar o QR Code estático

typescript

const qrRes = await fetch('/v1/pix/createStaticQRCode', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    key: '[email protected]',
    accountId: '30054029183',
    amount: 199.90,
    transactionIdentification: 'pedido-12345',
    additionalInformation: 'Compra - Pedido #12345',
    documentNumber: '48059890093'
  })
});
const { data } = await qrRes.json();
// data.transactionId, data.emvqrcps, data.transactionIdentification disponíveis

Passo 2: exibir o QR Code ao cliente

Renderize o payload emvqrcps (brCode) como um QR Code para o cliente escanear.

Passo 3: escutar o webhook (pagamento recebido)

Quando o cliente escaneia e paga, o webhook chega:

typescript

// POST vindo do provedor de pagamento
{
  "eventType": "pix-payment-in",
  "data": {
    "transactionId": "E384040820262603101234567890",
    "amount": 199.90,
    "debitParty": { "name": "...", "taxId": "..." }
  }
}

// O seu serviço recebe o evento
console.log(`Payment received: R$ ${event.data.amount}`);
updateOrderStatus(event.data.transactionId, 'PAID');
sendConfirmationEmail(customer);

Passo 4: (opcional) acompanhar o status

typescript

const statusRes = await fetch(
  `/v1/pix/check?codigo=${transactionId}`,
  { headers: { 'Authorization': `Bearer ${token}` } }
);
const status = await statusRes.json();
console.log(status.data.status); // "CONFIRMED"

Limites e timeouts

Limite	Valor	Observações
Valor máximo por transação	Sem limite (BCB)	Sujeito ao limite diário da conta
Limite diário	Configurável por conta	Fale com o suporte para ajustar
Tarifas do PIX	Zero	(Determinado pelo BCB)
Janela de devolução	1 hora	Após o recebimento (não negociável)
Timeout da transferência	30 segundos	Pode retornar 202 se houver análise antifraude
QR Code estático	Sem expiração	Reutilizável indefinidamente

PIX ​

Visão geral ​

Principais características ​

Tipos de chave PIX ​

POST /v1/pix/create ​

POST /v1/pix/exclude ​

GET /v1/pix/getKeys ​

POST /v1/pix/getAccountInfoByPixKey ​

POST /v1/pix/transfer ​

GET /v1/pix/check ​

POST /v1/pix/createStaticQRCode ​

POST /v1/pix/getQRCodeDataByEmv ​

POST /v1/pix/pixPayByQRCode ​

Webhook: pix-payment-in ​

Webhook: pix-reversal-in ​

POST /v1/pix/reverse ​

Fluxo completo: receber pagamento via QR Code estático ​

Limites e timeouts ​

PIX

Visão geral

Principais características

Tipos de chave PIX

POST `/v1/pix/create`

POST `/v1/pix/exclude`

GET `/v1/pix/getKeys`

POST `/v1/pix/getAccountInfoByPixKey`

POST `/v1/pix/transfer`

GET `/v1/pix/check`

POST `/v1/pix/createStaticQRCode`

POST `/v1/pix/getQRCodeDataByEmv`

POST `/v1/pix/pixPayByQRCode`

Webhook: pix-payment-in

Webhook: pix-reversal-in

POST `/v1/pix/reverse`

Fluxo completo: receber pagamento via QR Code estático

Limites e timeouts