PIX (Brazil)
Localpayment enables merchants to process instant payments through Brazil's PIX system, the country's revolutionary instant payment platform developed by the Central Bank of Brazil. This guide outlines the process for initiating PIX payments through Localpayment's API, detailing required parameters, handling responses, and interpreting status codes for seamless integration with Brazil's real-time payment infrastructure.
Before You Begin
Ensure you have:
- Valid API credentials(access token).
Step 1. Create PIX Payment
To generate a PIX payment for collection in Brazil, send a POST request to the Create Payin endpoint with PIX-specific parameters.
Key Request Parameters
The request requires several key objects specific to QR payments:
| Object | Description | Required |
|---|---|---|
paymentMethod.type | Must be BankTransfer. | ✅ |
paymentMethod.code | Use 1314 for PIX. | ✅ |
sender | Sender information for compliance. | ✅ |
merchant | Merchant/business details. | ✅ |
paymentMethod | Payment method configuration. | ✅ |
amount | Transaction amount. | ✅ |
currency | Transaction currency code. | ✅ |
country | Must be BRA. | ✅ |
See all available parameters in the request.
Example Request
Below is an example using curl:
curl --request POST \
--url https://api.stage.localpayment.com/api/payin/ \
--header 'accept: application/json' \
--header 'Authorization: Bearer <your_access_token>' \
--header 'content-type: application/json' \
--data '
{
"paymentMethod": {
"type": "BankTransfer",
"code": "1314",
"flow": "DIRECT"
},
"currency": "USD",
"merchant": {
"type": "COMPANY",
"document": {
"type": "",
"id": ""
},
"name": "Company",
"email": ""
},
"payer": {
"type": "INDIVIDUAL",
"document": {
"id": "75.518.609/0001-56",
"type": "CNPJ"
},
"bank": {
"account": {
"type": "C"
}
},
"name": "John",
"lastname": "Doe"
},
"externalId": "3d3b3e1d-c234-4fde-8e87-cd61b7dde3cf",
"country": "BRA",
"amount": 1000,
"accountNumber": "076.840.00000004",
"conceptCode": "0003",
"comment": "Any relevant information related to the transaction"
}
'Step 2. Handle the Response
Successful Response
A successful PIX payment creation includes the PIX code data and payment details:
{
"transactionType": "PayIn",
"externalId": "3d3b3e1d-c234-4fde-8e87-cd61b7dde3cf",
"internalId": "7e57a8ed-7fa4-4264-bcf3-a44d3ff2c132",
"paymentMethod": {
"type": "BankTransfer",
"code": "1314",
"flow": "DIRECT"
},
"country": "BRA",
"currency": "USD",
"amount": 1000,
"accountNumber": "076.840.00000004",
"confirmed": {
"currency": "USD",
"amount": 1000,
"fxQuote": 1,
"exchangeRateToken": null
},
"payment": {
"installment": null,
"currency": "BRL",
"fxQuote": 4.96637604,
"financingFee": 0,
"amount": 4966.38
},
"localTaxes": [],
"withHoldings": [],
"fees": {
"description": "Fee",
"currency": "USD",
"fxSource": 1,
"fxQuote": 1,
"amount": 11,
"account": "076.840.00000004"
},
"status": {
"code": "100",
"description": "INPROGRESS",
"detail": "The payin is pending the confirmation"
},
"ticket": null,
"qr": {
"image": "https://api.stage.localpayment.com/api/images/1314/00020126580014br.gov.bcb.pix013627a44d0a-0736-4bbf-a4a4-6e11063973315204000053039865406150.005802BR5911Telequiet496008Campinas62230519mpqrinter12397252666304FA23",
"code": "00020126580014br.gov.bcb.pix013627a44d0a-0736-4bbf-a4a4-6e11063973315204000053039865406150.005802BR5911Telequiet496008Campinas62230519mpqrinter12397252666304FA23",
"codeBase64": "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",
"expirationDate": "2022-08-13T12:28:09.695-04:00"
},
"beneficiary": null,
"merchant": {
"type": "COMPANY",
"name": "Company",
"document": {
"id": "",
"type": ""
},
"email": "",
"phone": {
"countryCode": "",
"areaCode": "",
"number": ""
},
"address": {
"street": "",
"number": "",
"city": "",
"state": "",
"country": "",
"zipCode": "",
"comment": "Any relevant information related to the transaction"
},
"birthdate": "",
"nationality": ""
},
"payer": {
"type": "INDIVIDUAL",
"name": "John",
"lastname": "Doe",
"document": {
"id": "75.518.609/0001-56",
"type": "CNPJ"
},
"email": "",
"phone": {
"countryCode": "",
"areaCode": "",
"number": ""
},
"address": {
"street": "",
"number": "",
"city": "",
"state": "",
"country": "",
"zipCode": ""
},
"birthdate": "",
"nationality": ""
},
"intermediaries": null,
"wireInstructions": null,
"date": {
"creationDate": "2025-02-19T20:57:50.253+00:00",
"processedDate": "2025-02-19T20:57:50.507088",
"expirationDate": "2025-02-21T20:57:50.507088"
},
"card": null,
"errors": []
} Key Response Fields
| Parameter | Description | Use Case |
|---|---|---|
qr.image | Base64 encoded PNG image of the QR code. | Direct display without additional generation. |
qr.code | Raw PIX payload in EMVCo standard. | Generate scannable QR code for Brazilian banking apps. |
qr.codeBase64 | Alternative base64 encoded QR payload. | Backup for custom QR rendering. |
qr.expirationDate | Timestamp when QR becomes invalid. | Display countdown timer and handle expiration logic. |
externalId | Your original reference number. | Internal reconciliation and order matching. |
status.code | Current transaction state (100 = INPROGRESS) | Determine next steps in payment flow. |
date.creationDate | When transaction was created. | Analytics and performance tracking. |
Error Response
When PIX generation fails for Brazil, you'll receive specific error information:
{
"externalId": "ce0aaa1a-4532-43b9-930a-26e780aba99b",
"status": {
"code": "812",
"description": "REJECTED"
},
"errors": [
{
"code": "812",
"detail": "External Id already used - duplication"
}
]
}Step 3. Display PIX Code and Handle Payment
- PIX Display: Present QR code to customer through chosen channel.
- Bank App Scan: Customer scans QR in their banking app.
- Payment Authorization: Customer confirms payment in their banking environment.
- Real-time Confirmation: Localpayment receives instant payment notification.
- Status Update: Your system receives webhook with payment confirmation.
Best Practices for QR Display
- Minimum display size: 250x250 pixels for mobile scanning.
- Maintain 1:1 aspect ratio without distortion.
- Ensure high contrast (dark on light background).
- Add quiet zone (white border) around QR code.
- Include alt text (e.g. "QR Code Payment").
- Show Clear Payment Instructions.
- Handle Time-to-Live (TTL) and Expiration.
Step 4. Track Transaction Status
Monitor PIX payment progress through these methods:
Webhooks (Recommended)
Receive real-time notifications when transaction status changes. Most efficient for production environments.
Status API Endpoint
Query transaction status programmatically. Useful for polling or recovering lost webhook notifications.
Dashboard View
Visual interface for monitoring transactions. Great for manual oversight and detailed transaction analysis.
Common Status Codes
The Localpayment API provides various status codes to indicate the progress and outcome of the payment in the response.
| Code | Status | Description |
|---|---|---|
103 | APPROVED | The payin was confirmed but not credited yet. |
200 | Completed | The payin was completed. |
811 | Rejected | Requested amount is higher or lower than allowed max/min values. |
Note: For complete status code reference, see the Transaction Status Documentation.
Testing Your Integration
Sandbox Environment
Use the staging environment for testing:
https://api.stage.localpayment.com/api/payin/Test QR Scenarios
Verify your integration handles these scenarios:
- Successful Payment: Complete PIX payment with instant settlement.
- QR Expiration: Handle expired PIX payments gracefully.
- Multiple Payment Attempts: Same QR scanned multiple times.
- Status Updates: Webhook handling and status polling.
Next Steps
After implementing PIX payments, consider these additional capabilities:
Updated 3 days ago