This payment solution is only available in Guatemala
What is Fri?
Fri (previously known as Soyfri) is a digital wallet and payment platform in Guatemala that facilitates quick and secure transactions, including payments via QR codes. It allows users to link their bank accounts or cooperatives to perform various financial operations directly from their mobile devices.
QR payments in Guatemala offer a fast, secure, and efficient way for customers using the Fri wallet to pay directly from their linked bank accounts. Merchants can generate dynamic QR codes via API and share them with customers, who scan the code using the Fri app to complete the transaction. Fri acts as a payment intermediary, enabling real-time processing of payments through the user's associated bank.
Note: A unique dynamic QR code is generated for each request. This means that every time you create a new payment request, a different QR code will be issued, ensuring secure and traceable transactions.
Who Can Pay
Wallets that support QR payment: Fri and Micoope
Eligible users:
Individuals (personas físicas)
Legal entities (personas jurídicas)
Foreign users and companies with a Guatemalan phone number
Each QR code is valid for 24 hours from the time of creation.
Note: Once a payment is completed, the QR code does not expire immediately. This means multiple payments can be made using the same code until it expires after 24 hours. An update is currently in development to automatically expire the QR code after a successful payment.
Amount Limits
To ensure security and regulatory compliance, Fri imposes the following transaction limits:
Minimum Amount per Transaction:1 GTQ
Maximum Daily Limit per User:10,000 GTQ
⚠️ Please note: The maximum limit applies on a per-user basis and resets every 24 hours. If a user attempts to exceed this limit, the transaction will be declined.
These limits are enforced directly by Fri and cannot be overridden at the API level. Merchants should validate the payment amount before generating the QR to avoid user-facing errors.
Payment Notification
Once a payment is completed using the Fri QR, a real-time webhook is sent to the merchant's configured endpoint. This webhook serves as the primary method to confirm successful transactions and should be used to update your internal systems accordingly.
Key characteristics:
Instant delivery: Webhook is triggered immediately after the transaction is completed.
Includes full transaction data: Amount, status, payment method, timestamps, and other relevant metadata.
Secure and reliable: Use the webhook payload to verify the authenticity of the payment.
No sensitive payer info: For security reasons, only the payer's phone number is included. Name, ID, or account number are not shared.
Generate a QR
POST https://api.stage.localpayment.com/api/payin
Headers
Name
Type
Description
Authorization*
string
Mandatory. JWT token in format Bearer eyJ0... . For more information about authentication, please refer to Authentication
Request Body
Name
Type
Description
paymentMethod*
OBJECT
Mandatory. Payment method details
paymentMethod.type*
string
Mandatory.wallet
paymentMethod.code*
string
Mandatory. Select among the codes available in each country here NOTE: payment method code might affect the collection currency in bimonetary countries. For more info, see the side note on currency field.
paymentMethod.flow*
string
Mandatory. The payment Method data is collected through an additional form or plugin (REDIRECT). Currently, only REDIRECT flow is allowed.
externalId*
string
Mandatory. An ID that is meaningful to you and your system. It must be unique and alphanumeric, no characters allowed.
Mandatory. Amount to charge to your end user. For GTQ, use 2 decimal places separated by a dot.
currency*
string
Mandatory. The currency in which the amount is expressed. It could be A) the local currency of the selected country or B) the account's currency. If A), the amount will be charged to the customer's cash payment method. If B) and it differs from the local currency, the amount specified will be credited to your account and Localpayment will perform a Foreign Exchange operation to collect the amount expressed in local currency. In bimonetary countries, paymentMethod.code resolves possible ambiguity: the payment will be executed in the currency of that specific payment method network. e.i.: SPID (USD); SPEI (MXN)
accountNumber*
string
Mandatory. Your Localpayment account number in which the amount will be credited.
conceptCode*
string
Mandatory. Choose the suitable concept code from our Concept Code List. Based on our experience, the most usual are 0039 (remittances) and 0040 (corporate payments).
comment
string
Optional. A comment related to the transaction. It should be something meaningful to your business.
merchant*
OBJECT
Mandatory. Party Object.
type*
string
Mandatory. Possible values: COMPANY
merchant.name*
string
merchant.name
payer*
OBJECT
Mandatory. Party Object. Information related to the payer.
type*
string
Mandatory. Possible values: COMPANY, INDIVIDUAL
name*
string
Mandatory. Individual first name / company name
lastName
string
Mandatory for individuals / Ignored for companies.
Mandatory. Identity document Id. Usually numbers or combination of numbers and letters.
userReference
string
Optional. Username or id in your platform.
email
string
Mandatory
phone
OBJECT
Optional. Party Object. Contact phone number
phone.countryCode
string
Optional. Possible values: gt
phone.areaCode
string
Optional. Country Area Code
phone.number
string
Optional. Phone number
birthdate
string
Optional. Individual birthdate / company incorporation date. ISO 8601 format (YYYY-MM-DD)
nationality
string
Optional
address
OBJECT
Optional. Party Object. Contact address
address.street
string
Optional
address.number
string
Optional
address.city
string
Optional
address.state
string
Optional
address.country
string
Optional
address.comment
string
Optional. Additional info, such as floor or apartment number.
intermediaries
array
Optional. Array of Party objects. It represents others parties in the payment chain because of the end user is not your direct customer. Take into account the array sequence: your client should be the first element, the client of your client should be the second and so on, until there are no more intermediaries.
commercialData
OBJECT
Mandatory. Party Object. Extra information related to the goods or services traded.
item.id
string
Mandatory. Item ID
items.quantity
number
Mandatory. Item quantity
items.description
string
Mandatory. Item description
item.title
string
Mandatory. Item title
item.unitPrice
number
Mandatory.Unit price
Request Example
Response Example
To complete the payment you must scan the QR in the Fri application, where you are previously registered as a user.
QR image
When your system successfully requests a QR payment, Localpayment's API will return an object named "qr" within the response. This object contains all the necessary information for you to display the QR code to your customer and guide them through the payment process.
The "qr" object has the following key properties:
image: This property holds the QR code image data in Base64 encoded format. The value will typically start with data:image/png;base64, followed by a long string of characters. To display the QR code to your customer, your system will need to decode this Base64 string to render the actual image.
expirationDate: This indicates the exact date and time (in UTC) when the generated QR code will expire. As previously noted, QR codes for Fri payments are valid for 24 hours from their creation.
paymentInstructions: This property provides clear, user-friendly instructions on how the customer should complete the payment using the QR code. You should display these instructions prominently to guide your customers.
