QR (Peru)

QR code payments offer a fast, secure, and contactless method for customers to complete transactions using their mobile devices. By scanning a QR code, customers can easily initiate payments through their preferred banking or digital wallet apps, eliminating the need for physical cards or cash.

Upon generating a payment order, its status is set to INPROGRESS. It will remain in this status until the payment is successfully completed by the customer, manually canceled by you, or expires.

By default, QR payment orders are valid for 1 day. You have the flexibility to adjust this validity period to any duration between 1 and 7 days from the time of creation.

How It Works

The process of executing a payin via QR code through Localpayment involves the following steps:

Customer Initiates Payment: Your customer selects the QR payment option within your application's checkout flow.
Payment Request: Your application securely gathers the necessary payment details and submits them to Localpayment's API to initiate the transaction.
Provide Instructions: Localpayment returns a response containing the qr object, which includes the payment information and instructions. In case of an error, a message detailing the issue is provided.
Payment Execution: The customer completes the payment by scanning the displayed QR code using their banking or digital wallet app.
Notification: Once the payment is made, the merchant is notified, and the order is processed.

Availability

QR payments are currently supported in Peru through the following digital wallets:

Yape
Plim
Dale

Before a payment request

Before initiating a bank transfer request, ensure you have completed the following:

Generate an Access Token (Required): A valid access token is required to authenticate your API requests. Refer to the Generate an Access Token documentation for detailed instructions.
Get Available Payment Methods (Required): You must obtain a list of available payment methods configured for your Localpayment account. This list provides the necessary payment method codes. See the Get Available Payment Methods documentation for more details.
Get National Holidays (Optional): You can optionally retrieve information about national holidays in the relevant country. This information can be useful for anticipating potential delays in bank processing. See the Get National Holidays documentation for more information.
Generate Currency Exchange Quote (Optional): If you need to process payments in a different currency than your Localpayment account's currency, you can use this step to obtain a currency exchange quote. Refer to the Generate Currency Exchange Quote documentation for details.

Generate a QR Code

To generate a QR code for payment, it is essential to accurately collect and securely transmit all required payer information. This ensures the payment process is successful and compliant.

Payer Information:
- Full name
- Country-specific identification document
Transaction Details:
- Payment amount
- Currency (local or foreign)
- Merchant reference ID
Additional Requirements:
- Merchant-specific metadata (if applicable)

To initiate a QR payment, you must send a POST request to the Create Payin endpoint. In the request payload, set the payment method type to BankTransfer.

⚠️
QR payments have a minimum amount of 1 PEN and a maximum of 500 PEN per transaction. A daily limit of 2000 PEN applies per user.

Request Example

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"
      },
      "externalId": "{{externalId}}",
      "country": "PER",
      "currency": "PEN",
      "amount": 300.00,
      "accountNumber": "{{yourAccountNumber}}",
      "conceptCode": "0001",
      "comment": "",
      "merchant": {
        "type": "COMPANY",
        "name": "Name"
      },
      "payer": {
        "type": "INDIVIDUAL",
        "name": "John",
        "lastName": "Doe",
        "document": {
          "type": "DNI",
          "id": "12345678"
        },
        "email": "[email protected]"
      },
      "commercialData": {
        "items": [
          {
            "id": "001",
            "title": "test",
            "description": "test",
            "quantity": "6",
            "unitPrice": 50
          }
        ]
      }
    }'

Parameters

paymentMethod: Object with payment method information.
paymentMethod.type: Payment method type. Send BankTransfer for QR payments.
paymentMethod.code: Payment method code (e.g. 6080).
paymentMethod.flow: Set as DIRECT.
externalId: A unique identifier generated by your system to track the transaction (alphanumeric and hyphens). We recommend using UUID4 to ensure uniqueness (e.g. 40bac59a-0381-4cc0-a6a5-33418d84c2e4).
country: Set the country from which the operation is made. ISO 3166-1 alpha-3 (e.g. PER).
currency: The currency of the amount can be the local currency (charged directly) or the account's currency (triggering a Foreign Exchange operation), with paymentMethod.code resolving ambiguity in bicurrency countries. E.g. PEN.
amount: Transaction amount (e.g. 1000).
accountNumber: The Localpayment account number where the specified amount will be credited.
conceptCode: Operation concept code (e.g. 0001 for Corporate Payments).
merchant: Information about the merchant initiating the transaction.
merchant.type: Merchant type (e.g. COMPANY).
merchant.name: Merchant name.
payer: Object with information about the payer making the transaction.
payer.type: Payer type (e.g. INDIVIDUAL).
payer.name: Payer name.
payer.lastname: Payer last name.
payer.document: Payer documentation information.
payer.document.type: The type of identity document, such as a National Identity Number, Social Security Number, or Driver's License, depending on the country of issuance.
payer.document.id: Identity document number (usually a number). This must be a valid number according to the rules for the specific document type.
payer.email: Payer email.
commercialData: Object with commercial details about the transaction.
commercialData.items: Array of items included in the transaction.
commercialData.items.id: A unique identifier for the item.
commercialData.items.quantity: The quantity of this item purchased.
commercialData.items.description: A description of the item.
commercialData.items.title: The title or name of the item.
commercialData.items.unitPrice: The price per unit of the item.

See all available parameters in the request.

Successful response example

If the request to create a QR payment is successful, the API will return a 200 OK response. The response body will include the qr object, which contains all the necessary information for your customer to complete the payment:

{
    "transactionType": "PayIn",
    "externalId": "{{externalId}}",
    "internalId": "{{internalId}}",
    "paymentMethod": {
        "type": "BankTransfer",
        "code": "6080",
        "flow": "DIRECT"
    },
    "country": "PER",
    "currency": "PEN",
    "amount": 300.00,
    "accountNumber": "{{yourAccountNumber}}",
    "confirmed": {
        "currency": "PEN",
        "amount": 300.00,
        "fxQuote": 0.00
    },
    "payment": {
        "currency": "PEN",
        "fxQuote": 0.00,
        "financingFee": 0.00,
        "amount": 300.00
    },
    "localTaxes": [],
    "withHoldings": [],
    "fees": {},
    "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": "LocalPayment"
    },
    "payer": {
        "type": "INDIVIDUAL",
        "name": "Name",
        "lastname": "Lastname",
        "document": {
            "type": "DNI",
            "id": "12345678"
        },
        "email": [email protected]"
    },
    "date": {
        "creationDate": "2025-04-14T16:14:25.517+00:00",
        "processedDate": "2025-04-14T16:14:28.1901483",
        "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>",
    "errors": []
}

Key Fields in the Response

The response includes essential fields that provide details about the transaction. These include:

externalId: A unique identifier for the transaction in your system. It will be used to perform other operations such as obtaining transaction information.
internalId: A unique identifier for the transaction in Localpayment’s system.
status: Object with information about the status of the transaction.
status.code: The status code (e.g., 100 for INPROGRESS).
date: Timestamps for when the transaction was created and processed.
qr: Object containing the generated QR code information.
qr.image: The QR code itself, provided in a Base64 encoded string. Your application will typically render this as an image for the customer to scan.
qr.expirationDate: The date and time when the QR code and payment instructions will expire. Ensure your application clearly communicates this to the customer.
qr.paymentInstructions: A set of clear, step-by-step instructions on how your customer should complete the payment using the generated QR code.

For a complete list of status codes and their meanings, please refer to the Transaction Status documentation.

Localpayment also sends webhooks to your application to notify you of changes in the transaction status. For more information on webhooks, please refer to the Webhooks documentation.

QR Code Generation

After a successful QR payment request, the API returns a qr object containing all the necessary information to generate and display the QR code. This data allows you to seamlessly render the QR code on your checkout page and guide the customer through the payment process.

QR Code Example

How to Pay

To complete the payment, the customer must scan the QR code using their preferred mobile wallet application (e.g., Yape, Plin, or other supported apps). Once the payment is successfully processed, Localpayment will automatically send a webhook notification to your application with the updated transaction status. This ensures real-time tracking and confirmation of the payment.

Next Steps

After a QR payment is processed, you may need to perform additional actions, such as:

Refund the transaction: If necessary, you can refund the payment to the customer. Refer to the Refunds documentation for details.
Handle chargebacks: In case of a dispute, you may need to handle chargebacks. Refer to the Chargebacks documentation for information on this process.
Review transaction details: You can retrieve transaction information using the Localpayment API. See the Transaction Information documentation for details.