PIX Payments

Learn how to integrate PIX payments - Brazil's instant payment system.

💡 What is PIX?

PIX is Brazil's instant payment system that allows real-time transfers 24/7. It's fast, secure, and widely adopted across Brazil.

⚡

Instant

Transfers in seconds

🕒

24/7

Available all day

🔒

Secure

Bank-grade security

Operations

The Velora API supports two main PIX operations:

💰

CASH_IN:Receive PIX deposits into your wallet. Generates a QR code and copy-paste code for your customers to pay.

📤

CASH_OUT:Send PIX transfers from your wallet to any PIX key (CPF, CNPJ, email, phone, or random key).

💰 Cash In - PIX Deposit

Request Example

Create a PIX deposit transaction to receive money into your wallet:

POST /wallet/cash-in?clientId=your_client_id
Content-Type: application/json
Authorization: Bearer your_access_token

{
  "value": 5000,
  "callbackUrl": "https://your-app.com/callback",
  "invoiceDescription": "Deposit for order #12345",
  "payer": {
    "name": "João Silva",
    "email": "joao@example.com",
    "document": "12345678901",
    "phone": "+5511999999999"
  },
  "metadata": {
    "orderId": "12345",
    "product": "Premium Plan"
  },
  "externalReference": "ABC123",
  "expireInMinutes": 60
}

Note: The value must be in cents (e.g., 5000 = R$ 50.00) with a minimum of 100 cents (R$ 1.00).

Request Fields

valuerequiredinteger

Amount in cents (minimum: 100 cents = R$ 1.00)

callbackUrlrequiredstring

URL to receive transaction status updates

payerrequiredobject

Payer information (name required, email/document/phone optional)

name (required string)

email (optional string)

document (optional string)

phone (optional string)

invoiceDescriptionoptionalstring

Description for the invoice

metadataoptionalobject

Custom JSON data to be returned in callback

externalReferenceoptionalstring

Your internal reference ID

expireInMinutesoptionalinteger

Expiration time in minutes (default: 60, minimum: 1)

Response Example

{
  "success": true,
  "messageError": null,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "description": "Deposit for order #12345",
    "operation": "CASH_IN",
    "status": "PENDING",
    "value": 5000,
    "clientFee": 50,
    "providerFee": 25,
    "externalReference": "ABC123",
    "callbackUrl": "https://your-app.com/callback",
    "providerInternalId": "pix_123456",
    "providerInternalCopyPaste": "00020126580014br.gov.bcb.pix...",
    "providerInternalQrcode": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
    "pixMetadata": {},
    "createdAt": "2024-01-15T10:00:00Z",
    "updatedAt": "2024-01-15T10:00:00Z",
    "expiresAt": "2024-01-15T11:00:00Z"
  }
}

📤 Cash Out - PIX Transfer

Request Example

Create a PIX transfer to send money from your wallet to another PIX key:

POST /wallet/cash-out?clientId=your_client_id
Content-Type: application/json
Authorization: Bearer your_access_token

{
  "value": 5000,
  "callbackUrl": "https://your-app.com/callback",
  "pixDestinyKey": "12345678901",
  "document": "12345678901",
  "beneficiary": {
    "name": "Maria Santos",
    "email": "maria@example.com",
    "document": "98765432100",
    "phone": "+5511988888888"
  },
  "metadata": {
    "withdrawalId": "WD789",
    "reason": "Withdrawal"
  },
  "externalReference": "XYZ789"
}

Note: The value must be in cents with a minimum of 5 cents (R$ 0.05). The pixDestinyKey can be a CPF, CNPJ, email, phone, or random key.

Request Fields

valuerequiredinteger

Amount in cents (minimum: 5 cents = R$ 0.05)

callbackUrlrequiredstring

URL to receive transaction status updates

pixDestinyKeyrequiredstring

PIX key of the recipient (CPF, CNPJ, email, phone, or random key)

documentoptionalstring

Document identifier (CPF/CNPJ)

beneficiaryoptionalobject

Beneficiary information (all fields optional)

name (optional string)

email (optional string)

document (optional string)

phone (optional string)

metadataoptionalobject

Custom JSON data to be returned in callback

externalReferenceoptionalstring

Your internal reference ID

Response Example

{
  "success": true,
  "messageError": null,
  "data": {
    "id": "660e8400-e29b-41d4-a716-446655440001",
    "description": "PIX Transfer",
    "operation": "CASH_OUT",
    "status": "PENDING",
    "value": 5000,
    "clientFee": 50,
    "providerFee": 25,
    "externalReference": "XYZ789",
    "callbackUrl": "https://your-app.com/callback",
    "providerInternalId": "pix_789012",
    "pixMetadata": {},
    "createdAt": "2024-01-15T10:00:00Z",
    "updatedAt": "2024-01-15T10:00:00Z"
  }
}

📊 Transaction Statuses

PENDINGTransaction created, waiting for completion

SUCCEEDTransaction successfully completed

FAILEDTransaction failed or was rejected

MEDTransaction under mediation or review

REFUNDEDTransaction was refunded to the payer

EXPIREDTransaction expired without completion

📱 QR Code Integration (Cash In Only)

Display Options for PIX Deposit

After creating a cash-in transaction, you'll receive both a QR code image and a copy-paste code:

QR Code Image

Use the base64-encoded QR code image directly in your app:

<img 
  src={transaction.data.providerInternalQrcode} 
  alt="PIX QR Code"
  width="200"
  height="200"
/>

PIX Copy & Paste Code

Let users copy the PIX code manually:

<input 
  type="text" 
  value={transaction.data.providerInternalCopyPaste}
  readOnly
  className="pix-code-input"
/>
<button onClick={() => 
  copyToClipboard(transaction.data.providerInternalCopyPaste)
}>
  Copy PIX Code
</button>

🔔 Callbacks

Receive real-time notifications when transaction status changes. When you create a cash-in or cash-out transaction, you provide a callbackUrl. We'll send a POST request to that URL when the transaction status updates:

POST https://your-app.com/callback
Content-Type: application/json

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "description": "Deposit for order #12345",
  "operation": "CASH_IN",
  "status": "SUCCEED",
  "value": 5000,
  "clientFee": 50,
  "providerFee": 25,
  "externalReference": "ABC123",
  "callbackUrl": "https://your-app.com/callback",
  "providerInternalId": "pix_123456",
  "pixMetadata": {},
  "createdAt": "2024-01-15T10:00:00Z",
  "updatedAt": "2024-01-15T10:05:00Z",
  "expiresAt": "2024-01-15T11:00:00Z"
}

Important: Your callback endpoint must return a 2xx status code to acknowledge receipt. We'll retry failed callbacks up to 3 times.