QR (Peru)

Before You Begin

Ensure you have:

Valid API credentials (access token).

Supported Wallets

Valid API credentials (access token).

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.

🕑
Expiration
By default, a QR Bank Transfer payment order expires 1 day after creation. To customize the expiration period (1-7 days) for your business needs, contact your account manager for configuration.

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.

⚠️
Amount limits for Peru: QR payments require a minimum of 1 PEN and cannot exceed 500 PEN per transaction. Each user has a daily limit of 2000 PEN across all transactions.

Example Request

Below is an example using curl:

curl --request POST \
     --url https://api.stage.localpayment.com/api/payin/ \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'Authorization: Bearer <your_access_token>' \
     --data '
{
    "externalId": "96989760-c262-4607-b99c-dfbf8af42f52",
    "paymentMethod": {
        "type": "Banktransfer",
        "code": "6080",
        "flow": "DIRECT"
    },
    "country": "PER",
    "currency": "PEN",
    "amount": 1001,
    "accountNumber": "{{accountNumber}}",
    "conceptCode": "0001",
    "comment": "QR Payment",
    "merchant": {
        "type": "COMPANY",
        "document": {
            "id": "12345678",
            "type": "DNI"
        },
        "name": "Test Company"
    },
    "payer": {
        "type": "INDIVIDUAL",
        "document": {
            "id": "87654321",
            "type": "DNI"
        },
        "name": "John",
        "lastname": "Doe",
        "email": "[email protected]",
        "userReference": "{{$randomUserName}}"
    }
}
'

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": "96989760-c262-4607-b99c-dfbf8af42f52",
  "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 QR with their 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: 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 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.
`811`	Rejected	Requested amount is higher or lower than allowed max/min values.

🗒️
Complete Reference
View all status codes in our 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.
Status Updates: Webhook handling and status polling.

Next Steps

After implementing QR payments, consider these additional capabilities:

Refund the transaction

If necessary, you can refund the payment to the customer. Refer to the documentation for details.

Review transaction details

You can retrieve transaction information using the Localpayment API for detailed insights.