PIX

All PIX endpoints require Authorization: Bearer <token> unless stated otherwise.

Overview

PIX is a real-time payment system available 24/7 across all days of the year. It supports person-to-person (P2P), person-to-business (P2B), and business-to-business (B2B) transfers.

Key Features

Instant settlement: Money transferred in seconds (24/7)
Static keys: CPF, email, phone, random (EVP)
Dynamic QR Codes: One-time QR per transaction with 10-minute expiry
No fees: PIX transfers have zero cost
Reversals: Refunds available within 1 hour of receipt

PIX Key Types

Type	Format	Example	Dynamic	Notes
CPF	11 digits	`48059890093`	No	Individual taxpayer ID
CNPJ	14 digits	`37702652000188`	No	Business taxpayer ID
EMAIL	RFC 5322	`joao@example.com`	No	Email address (stable)
PHONE	+55 + DDD + 9 digits	`+5511999999999`	No	Mobile number (stable)
EVP (Random)	36-char UUID	`550e8400-e29b-41d4-a716-446655440000`	No	Randomly generated (stable)
Dynamic QR Code	EMV/brCode	`00020126580014br...`	Yes	One per transaction, expires in 10 min

POST `/v1/pix/create`

Request Body:

json

{
  "key": "joao@example.com",
  "keyType": "EMAIL",
  "accountId": "30054029183",
  "onBoardingId": "8f92c748-c37c-467d-ac69-6513706d7c60"
}

Field	Type	Required	Description
`key`	string	Yes	PIX key value (format depends on `keyType`)
`keyType`	string	Yes	`CPF`, `CNPJ`, `EMAIL`, `PHONE`, or `EVP`
`accountId`	string	Yes	Account number
`onBoardingId`	string	Yes	Onboarding ID

Example:

bash

curl -X POST https://baas-gtw.axiadigitalsolutions.com/v1/pix/create \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "Content-Type: application/json" \
  -d '{
    "key": "joao@example.com",
    "keyType": "EMAIL",
    "accountId": "30054029183",
    "onBoardingId": "8f92c748-c37c-467d-ac69-6513706d7c60"
  }'

Response 200 OK:

json

{
  "status": "CONFIRMED",
  "data": {
    "pixKeyId": "key_550e8400-e29b-41d4-a716-446655440000",
    "keyType": "EMAIL",
    "keyValue": "joao@example.com",
    "accountId": "30054029183",
    "createdAt": "2024-03-15T10:00:00Z",
    "status": "ACTIVE"
  }
}

Errors:

E00301: Invalid key format (e.g., malformed email, wrong CPF length)
E00302: Key already exists for this account

DELETE `/v1/pix/create`

Remove a registered PIX key.

Request Body:

json

{
  "key": "joao@example.com",
  "keyType": "EMAIL",
  "accountId": "30054029183",
  "onBoardingId": "8f92c748-c37c-467d-ac69-6513706d7c60"
}

Field	Type	Required	Description
`key`	string	Yes	PIX key to remove
`keyType`	string	Yes	`CPF`, `CNPJ`, `EMAIL`, `PHONE`, or `EVP`
`accountId`	string	Yes	Account number
`onBoardingId`	string	Yes	Onboarding ID

Response 200 OK:

json

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

GET `/v1/pix/getKeys`

List all static PIX keys registered for an account.

Query Parameters:

Parameter	Type	Required	Description
`accountId`	string	Yes	Account number
`documentNumber`	string	Yes	CPF or CNPJ

Example:

bash

curl -X GET "https://baas-gtw.axiadigitalsolutions.com/v1/pix/getKeys?accountId=30054029183&documentNumber=48059890093" \
  -H "Authorization: Bearer eyJhbGci..."

Response 200 OK:

json

{
  "status": "CONFIRMED",
  "data": {
    "keys": [
      {
        "key": "joao@example.com",
        "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`

Look up account holder information by a PIX key (DICT lookup). Returns recipient name and account details.

Request Body:

json

{
  "key": "joao@example.com",
  "keyType": "EMAIL",
  "payerId": "48059890093",
  "accountId": "30054029183",
  "onBoardingId": "8f92c748-c37c-467d-ac69-6513706d7c60"
}

Field	Type	Required	Description
`key`	string	Yes	PIX key to look up
`keyType`	string	Yes	Key type: `CPF`, `CNPJ`, `EMAIL`, `PHONE`, or `EVP`
`payerId`	string	Yes	Payer's CPF/CNPJ
`accountId`	string	Yes	Payer's account number
`onBoardingId`	string	Yes	Payer's onboarding ID

Response 200 OK:

json

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

POST `/v1/pix/transfer`

Execute a PIX transfer using a registered static key or account details.

Headers:

Header	Value	Required
`x-client-id`	Your tenant ID	Yes
`Idempotency-Key`	UUID v4	Recommended

Request 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": "maria@example.com",
    "branch": "0001",
    "account": "654321",
    "accountType": "CACC"
  },
  "initiationType": "DICT",
  "remittanceInformation": "Aluguel janeiro",
  "paymentType": "IMMEDIATE",
  "urgency": "HIGH",
  "userId": "cfd11a01-293d-4573-9d28-2d7261d79aaf",
  "onBoardingId": "8f92c748-c37c-467d-ac69-6513706d7c60"
}

Field	Type	Required	Description
`amount`	decimal	Yes	Amount in BRL (no decimals limit)
`debitParty.taxId`	string	Yes	Payer CPF or CNPJ
`debitParty.name`	string	Yes	Payer name
`debitParty.branch`	string	Yes	Payer bank branch code
`debitParty.account`	string	Yes	Payer account number
`debitParty.accountType`	string	Yes	`CACC` (checking) or `SVGS` (savings)
`creditParty.bank`	string	Yes	Recipient bank ISPB code
`creditParty.taxId`	string	Yes	Recipient CPF or CNPJ
`creditParty.name`	string	Yes	Recipient name
`creditParty.key`	string	No	Recipient PIX key (email, CPF, phone, EVP)
`creditParty.branch`	string	Yes	Recipient bank branch code
`creditParty.account`	string	Yes	Recipient account number
`creditParty.accountType`	string	Yes	`CACC` or `SVGS`
`initiationType`	string	Yes	`DICT` (via PIX key) or `MANUAL`
`remittanceInformation`	string	No	Description (max 140 chars)
`paymentType`	string	Yes	`IMMEDIATE` (fixed value)
`urgency`	string	Yes	`HIGH` or `NORMAL`
`userId`	string	Yes	Internal user ID
`onBoardingId`	string	Yes	Onboarding ID

Example:

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-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": "maria@example.com",
      "branch": "0001",
      "account": "654321",
      "accountType": "CACC"
    },
    "initiationType": "DICT",
    "remittanceInformation": "Aluguel janeiro",
    "paymentType": "IMMEDIATE",
    "urgency": "HIGH",
    "userId": "cfd11a01-293d-4573-9d28-2d7261d79aaf",
    "onBoardingId": "8f92c748-c37c-467d-ac69-6513706d7c60"
  }'

Response 200 OK:

json

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

Response 202 Accepted (Antifraud):

May return if transaction requires manual approval.

Errors:

E00303: Insufficient balance
E00304: Receiver not found (invalid PIX key)
E00305: PIX limit exceeded (daily limit)

GET `/v1/pix/check`

Check the status of a PIX transaction.

Query Parameters:

Parameter	Type	Required	Description
`codigo`	string	Yes	Transaction code or endToEndId

Example:

bash

curl -X GET "https://baas-gtw.axiadigitalsolutions.com/v1/pix/check?codigo=E384040820262603101234567890" \
  -H "Authorization: Bearer eyJhbGci..."

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`

Create a static (reusable) PIX QR Code for receiving multiple payments. No expiry.

Request Body:

json

{
  "key": "joao@example.com",
  "keyType": "EMAIL",
  "accountId": "30054029183",
  "amount": 50.00,
  "transactionIdentification": "pedido-12345",
  "additionalInformation": "Pagamento ref. pedido #12345",
  "documentNumber": "48059890093"
}

Field	Type	Required	Description
`key`	string	Yes	PIX key to receive on
`keyType`	string	Yes	Key type: `CPF`, `CNPJ`, `EMAIL`, `PHONE`, or `EVP`
`accountId`	string	Yes	Account number
`amount`	decimal	No	Fixed amount (omit for open amount)
`transactionIdentification`	string	No	Custom identifier (max 25 chars)
`additionalInformation`	string	No	Additional info visible to payer (max 140 chars)
`documentNumber`	string	Yes	Account holder CPF or CNPJ

Example:

bash

curl -X POST https://baas-gtw.axiadigitalsolutions.com/v1/pix/createStaticQRCode \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "Content-Type: application/json" \
  -d '{
    "key": "joao@example.com",
    "keyType": "EMAIL",
    "accountId": "30054029183",
    "amount": 50.00,
    "transactionIdentification": "pedido-12345",
    "additionalInformation": "Pagamento ref. pedido #12345",
    "documentNumber": "48059890093"
  }'

Response 200 OK:

json

{
  "status": "CONFIRMED",
  "data": {
    "qrCodeId": "qr_550e8400-e29b-41d4-a716-446655440000",
    "emv": "00020126580014br.gov.bcb.pix0136550e8400-e29b-41d4-a716...",
    "url": "https://api.axia.com/qrcode/550e8400-e29b-41d4-a716-446655440000.png",
    "expiresAt": null,
    "amount": 50.00
  }
}

POST `/v1/pix/qrcode/dynamic`

Generate a dynamic PIX QR Code unique per transaction. Expires in 10 minutes. Ideal for e-commerce, point-of-sale, and invoicing.

Request Body:

json

{
  "accountId": "30054029183",
  "amount": 199.90,
  "description": "Compra em Loja XYZ",
  "expiresIn": 600
}

Field	Type	Required	Description
`accountId`	string	Yes	Account number
`amount`	decimal	Yes	Payment amount in BRL
`description`	string	No	Payment description (max 140 chars)
`expiresIn`	integer	No	Expiration time in seconds (default: 600 = 10 min; max: 3600)

Example:

bash

curl -X POST https://baas-gtw.axiadigitalsolutions.com/v1/pix/qrcode/dynamic \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "30054029183",
    "amount": 199.90,
    "description": "Compra em Loja XYZ",
    "expiresIn": 600
  }'

Response 200 OK:

json

{
  "status": "CONFIRMED",
  "data": {
    "qrCodeId": "qr_550e8400-e29b-41d4-a716-446655440000",
    "brCode": "00020126580014br.gov.bcb.pix0136550e8400-e29b-41d4-a716-446655440000...",
    "url": "https://api.axia.com/qrcode/550e8400-e29b-41d4-a716-446655440000.png",
    "expiresAt": "2024-03-15T10:40:00Z",
    "amount": 199.90
  }
}

Notes:

Dynamic QR codes are single-use (unless received by multiple payers within expiry)
After expiry, payer cannot scan or pay via this QR code
Static QR codes (above) have no expiry and are ideal for recurring receipts

POST `/v1/pix/getQRCodeDataByEmv`

Parse a PIX QR Code EMV string to extract payment information without executing payment.

Request Body:

json

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

Field	Type	Required	Description
`emv`	string	Yes	QR Code EMV/brCode payload string
`payerId`	string	Yes	Payer's CPF or CNPJ
`accountId`	string	Yes	Payer's account number

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`

Execute a PIX payment by scanning and paying a QR Code (static or dynamic).

Headers:

Header	Value	Required
`x-client-id`	Your tenant ID	Yes
`Idempotency-Key`	UUID v4	Recommended

Request Body:

json

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

Field	Type	Required	Description
`emv`	string	Yes	QR Code EMV/brCode payload
`payerId`	string	Yes	Payer's CPF or CNPJ
`accountId`	string	Yes	Payer's account number
`userId`	string	Yes	Internal user ID
`amount`	decimal	Yes	Payment amount (BRL)

Example:

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-tenant-id" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{
    "emv": "00020126580014br.gov.bcb.pix...",
    "payerId": "48059890093",
    "accountId": "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"
  }
}

Errors:

E00306: QR code expired (dynamic only)
E00307: Invalid or malformed EMV string
E00303: Insufficient balance

Webhook: pix-payment-in

Fired when a PIX payment is received (credited to account).

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"
  }
}

Field	Type	Description
`eventType`	string	Always `pix-payment-in`
`timestamp`	ISO-8601	When payment was received
`data.transactionId`	string	Original transaction ID
`data.endToEndId`	string	End-to-end ID (for reconciliation)
`data.amount`	decimal	Amount received in BRL
`data.debitParty`	object	Sender info
`data.creditParty`	object	Receiver info (your account)
`data.description`	string	Payment description/memo

Use Case:

Update balance in real-time
Log incoming PIX receipts
Trigger order fulfillment or invoice payment reconciliation

Webhook: pix-reversal-in

Fired when a PIX reversal is processed (money returned to original sender).

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`

Request a PIX reversal (refund) within 1 hour of receipt.

Request Body:

json

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

Field	Type	Required	Description
`transactionId`	string	Yes	Original transaction ID to reverse
`endToEndId`	string	Yes	End-to-end ID from original PIX
`amount`	decimal	Yes	Reversal amount (BRL); can be partial
`reason`	string	Yes	`FRAUD`, `OPERATIONAL_FLAW`, or `REFUND`
`reversalDescription`	string	No	Human-readable explanation (max 140 chars)
`documentNumber`	string	No	Account holder CPF or CNPJ

Example:

bash

curl -X POST https://baas-gtw.axiadigitalsolutions.com/v1/pix/reverse \
  -H "Authorization: Bearer eyJhbGci..." \
  -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"
  }
}

Limitations:

1-hour window: Must reverse within 1 hour of receipt
Receiver consent: Receiver must accept reversal (automatic for operational errors)
Partial reversal: Can reverse less than original amount

Errors:

E00308: Reversal window expired (> 1 hour)
E00309: Receiver declined reversal (manual intervention needed)
E00310: Amount exceeds original transaction

Complete Flow: Receive Payment via Dynamic QR

Step 1: Generate Dynamic QR Code

typescript

const qrRes = await fetch('/v1/pix/qrcode/dynamic', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    accountId: '30054029183',
    amount: 199.90,
    description: 'Compra - Pedido #12345'
  })
});
const { data } = await qrRes.json();
// data.brCode, data.url, data.expiresAt available

Step 2: Display QR Code to Customer

html

<img [src]="qrCodeData.url" alt="PIX QR Code">
<p>Expira em: {{ qrCodeData.expiresAt | date:'HH:mm:ss' }}</p>

Step 3: Listen for Webhook (Payment Received)

When customer scans and pays, webhook arrives:

typescript

// POST from payment provider
{
  "eventType": "pix-payment-in",
  "data": {
    "transactionId": "E384040820262603101234567890",
    "amount": 199.90,
    "debitParty": { "name": "...", "taxId": "..." }
  }
}

// Your service receives it
console.log(`Payment received: R$ ${event.data.amount}`);
updateOrderStatus(event.data.transactionId, 'PAID');
sendConfirmationEmail(customer);

Step 4: (Optional) Track 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"

Limits & Timeouts

Limit	Value	Notes
Max amount per transaction	No limit (BCB)	Subject to account daily limit
Daily limit	Configurable per account	Contact support to adjust
PIX fees	Zero	(Mandated by BCB)
Dynamic QR expiry	10 minutes (default)	Up to 1 hour configurable
Reversal window	1 hour	After receipt (non-negotiable)
Transfer timeout	30 seconds	May return 202 if antifraud review required
Static QR Code	No expiry	Reusable indefinitely

PIX ​

Overview ​

Key Features ​

PIX Key Types ​

POST /v1/pix/create ​

DELETE /v1/pix/create ​

GET /v1/pix/getKeys ​

POST /v1/pix/getAccountInfoByPixKey ​

POST /v1/pix/transfer ​

GET /v1/pix/check ​

POST /v1/pix/createStaticQRCode ​

POST /v1/pix/qrcode/dynamic ​

POST /v1/pix/getQRCodeDataByEmv ​

POST /v1/pix/pixPayByQRCode ​

Webhook: pix-payment-in ​

Webhook: pix-reversal-in ​

POST /v1/pix/reverse ​

Complete Flow: Receive Payment via Dynamic QR ​

Limits & Timeouts ​

PIX

Overview

Key Features

PIX Key Types

POST `/v1/pix/create`

DELETE `/v1/pix/create`

GET `/v1/pix/getKeys`

POST `/v1/pix/getAccountInfoByPixKey`

POST `/v1/pix/transfer`

GET `/v1/pix/check`

POST `/v1/pix/createStaticQRCode`

POST `/v1/pix/qrcode/dynamic`

POST `/v1/pix/getQRCodeDataByEmv`

POST `/v1/pix/pixPayByQRCode`

Webhook: pix-payment-in

Webhook: pix-reversal-in

POST `/v1/pix/reverse`

Complete Flow: Receive Payment via Dynamic QR

Limits & Timeouts