QR (Peru)
Localpayment enables merchants to process instant payments through Peru's interoperable QR payment system. This guide outlines the process for initiating QR-based payments through Localpayment's API, detailing required parameters, handling responses, and interpreting status codes for seamless integration with Peru's unified payment network.
Supported Peruvian Wallets:
- YAPE
- PLIM
- DALE
- LIGO
Before You Begin
Ensure you have:
- Valid API credentials (access token).
- Proper account setup for your target country.
- Understanding of country-specific requirements (see Country Requirements below).
Step 1. Create QR Payment
To generate a QR code for payment collection, send a POST request to the Create Payin endpoint with QR-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 6080 for Peru QR. | ✅ |
sender | Sender information for compliance. | ✅ |
merchant | Merchant/business details. | ✅ |
paymentMethod | Payment method configuration. | ✅ |
amount | Transaction amount. | ✅ |
currency | Transaction currency code. | ✅ |
country | Must be PER. | ✅ |
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": "6080",
"flow": "DIRECT"
},
"currency": "PEN",
"merchant": {
"type": "COMPANY",
"document": {
"id": "12345678",
"type": "DNI"
},
"name": "Company"
},
"payer": {
"type": "INDIVIDUAL",
"document": {
"id": "87654321",
"type": "DNI"
},
"name": "John",
"lastname": "Doe",
"email": "[email protected]",
"userReference": "{{$randomUserName}}"
},
"externalId": "96989760-c262-4607-b99c-dfbf8af42f52",
"country": "PER",
"amount": 1001,
"accountNumber": "068.068.00000011",
"conceptCode": "0001",
"comment": "QR Payment"
}
'Step 2. Handle the Response
Successful Response
A successful QR payment creation includes the QR code data and payment details::
{
"transactionType": "PayIn",
"externalId": "96989760-c262-4607-b99c-dfbf8af42f52",
"internalId": "bd3c82a3-7b97-4e43-bcce-f59eb31ef5ef",
"paymentMethod": {
"type": "BankTransfer",
"code": "6080",
"flow": "DIRECT"
},
"country": "PER",
"currency": "PEN",
"amount": 1001,
"accountNumber": "068.068.00000011",
"confirmed": {
"currency": "PEN",
"fxQuote": 1,
"amount": 1001
},
"payment": {
"currency": "PEN",
"fxQuote": 1,
"financingFee": 0,
"amount": 1001
},
"localTaxes": [],
"withHoldings": [],
"fees": {
"description": "Fee",
"currency": "PEN",
"fxSource": 6.812851,
"fxQuote": 1,
"amount": 1,
"account": "068.068.00000002"
},
"status": {
"code": "100",
"description": "INPROGRESS",
"detail": "The payin is pending the confirmation"
},
"qr": {
"image": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAASwAAAEsAQAAAABRBrPYAAADRUlEQVR4Xu2XbY7bMAxEeQPe/5a8Acs3dBaxdoH2TzsBaiF1Hek5ED9m5I3+k1Fxzvw4HuwYD3aMBzvGgx3jf8MqIjoyMruq5y6LT6QWzFizXHzLiOyoIbMH1ZoXq6ie9dm04Lmt1/UTsFmevTc5DuYnhP4UjL2TWPbepDZI7wdgkAM1WQaf5dSDWvNiU+b6cXxT1gns+IuYBllFwWycuk8UX2tGbHaqG7KaSCXJNZaDqr0Y2wdIbLBWOI0TTiO4sZKKm9wWaNKjfImNxYrNJNDAE0yR38amCejKvw1rloMGaFD8L/YuFYETUw75F9dpJpducstDVmymr5M2VsvF6Tup3YCsWHFWkN0irynV8NxkWw5txuQyazVFAAQip7mHYMCYZvOIBHsBURuQcDdGJoNuhJTTFCPoTy/GKx7+MhrZJgBuqduOlY4zHCbJMiQfWc299P8e0wmWePR26Kyp5vNEXL9jw4oZXWbDQEVDgq6arZg2r2/IebugOEEQkxfbHpxpNSTVVn9S+HovvQVT2TEXVEyW6c9E45tfJ1akkdzSlUEsBIKS7pEasFlsGpEpsjyx8MejQnBjFH4deRKrBLPKe0LRB1bsldGJBQXLAzHq7xZtwCj93HGmBXfYs5rgXnoHpk0jGAJRvWciddytZpwYrajyr6JBCKOurnRieg9GMjCq+2B8aE031myewwKAYBA0qsl3G/RgxfY5LBolA8kNg3DcmKLozSdmGLKYYe6ld2Aa8jx1IjtP9MLNW+k9WJFOAsFjSPDAaFoHixlLmhJ32RPjKr2u+zNWrPakDUqu+aQVetVsxbgiYKymYAYvgqJjvdhan0KA4pM8kvSnGZv/k87EAy/N6OHzaHNgyqgMkGl2/VILGTdjVyB6SVGquRYJvlXBgnH8hyY4Rnjni+tY82O82dGTgWbUooXh6IXPjHFDF8pq1v+Qsm7v+bdguntZjSybcBScFyuOjUsq0nPJZJLbr99wYfr0vq6wb4im7kRkxuTO1Jl19egqmi74CEzbxakLTaOXvNbtGAJWpdWcs39yK7vxYpCw64LklzQTzy0EC7aSIZRELLxBYYbQ76V3YL8dD3aMBzvGgx3jwY7xYMeoX9xXVTGl7tqkAAAAAElFTkSuQmCC",
"expirationDate": "2025-04-21T16:14:26.0596069",
"paymentInstructions": "<b><i>From Yape, Plin or other entity aplications, scan the QR code and complete the payment process</i></b>"
},
"merchant": {
"type": "COMPANY",
"name": "Company ",
"document": {
"id": "12345678",
"type": "DNI"
}
},
"payer": {
"type": "INDIVIDUAL",
"name": "John",
"lastname": "Doe",
"document": {
"id": "87654321",
"type": "DNI"
},
"email": "[email protected]",
"fullName": "John Doe"
},
"date": {
"creationDate": "2024-11-15T17:05:11.772+00:00",
"processedDate": "2024-11-15T17:05:13.656446231",
"expirationDate": "2024-11-15 23:59"
},
"errors": []
}Key Response Fields
| Parameter | Description | Use Case |
|---|---|---|
qr.image | Base64 encoded PNG image of the QR code. | Direct display without additional generation. |
qr.expirationDate | Timestamp when QR becomes invalid. | Display countdown timer and handle expiration logic. |
qr.paymentInstructions | Payment instructions. | Display user-friendly payment guidance. |
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 QR generation fails, you'll receive detailed 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 QR Code and Handle Payment
- QR Display: Present QR code to customer through chosen channel.
- Bank App Scan: Customer scans with any Peruvian bank mobile 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: 200x200 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 QR 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. |
701 | Rejected | Invalid bank account number. |
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 QR scan and payment flow.
- QR Expiration: Handle expired QR codes gracefully.
- Multiple Payment Attempts: Same QR scanned multiple times.
- Failed Transactions: Insufficient funds.
- Status Updates: Webhook handling and status polling.
Next Steps
After implementing QR payments, consider these additional capabilities:
Updated about 17 hours ago