Wallet Fri (Guatemala)
Localpayment enables merchants to process instant digital wallet payments through Guatemala's Wallet Fri system. This guide outlines the process for initiating Wallet Fri payments through Localpayment's API, detailing required parameters, handling responses, and interpreting status codes for seamless integration with Guatemala's popular digital wallet platform.
Before You Begin
Ensure you have:
- Valid API credentials (access token).
Step 1. Create Wallet Fri Payment
To generate a Wallet Fri payment request, send a POST request to the Create Payin endpoint with Wallet Fri-specific parameters.
Key Request Parameters
The request requires several key objects specific to Wallet Fri payments:
| Object | Description | Required |
|---|---|---|
paymentMethod.type | Must be Wallet. | ✅ |
paymentMethod.code | Must be 1880 for Wallet Fri. | ✅ |
payer | Payer account information. | ✅ |
merchant | Merchant/business details | ✅ |
amount | Transaction amount | ✅ |
currency | Transaction currency code | ✅ |
country | Must be GTM | ✅ |
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 'content-type: application/json' \
--header 'Authorization: Bearer <your_access_token>' \
--data '
{
"paymentMethod": {
"type": "Wallet",
"code": "1880",
"flow": "DIRECT"
},
"currency": "GTQ",
"merchant": {
"type": "COMPANY",
"name": "Company"
},
"payer": {
"type": "INDIVIDUAL",
"document": {
"type": "CUI",
"id": "3463426000101"
},
"phone": {
"countryCode": "gt",
"areaCode": "502",
"number": "55555555"
},
"address": {
"street": "",
"city": "",
"state": "",
"country": "",
"comment": ""
},
"bank": {
"account": {
"type": "C"
}
},
"name": "John",
"lastName": "Doe",
"email": "[email protected]"
},
"commercialData": {
"items": [
{
"id": "1441",
"title": "Playera",
"description": "Playera negra",
"quantity": "1",
"unitPrice": 1
}
]
},
"externalId": "cda5215e-2309-4b6c-b88b-bbce35951795",
"country": "GTM",
"amount": 10,
"accountNumber": "{{YourAccountNumber}}",
"conceptCode": "0001",
"comment": "Acme"
}
'Step 2. Handle the Response
Successful Response
When you create a Wallet Fri payment, the system automatically sends a push notification to the customer's Wallet Fri app. The API response confirms the payment request was successfully created and is pending customer authorization.
{
"transactionType": "PayIn",
"externalId": "cda5215e-2309-4b6c-b88b-bbce35951795",
"internalId": "e6b174f3-ee21-4653-91e7-dea034facdad",
"paymentMethod": {
"type": "Wallet",
"code": "1880",
"flow": "DIRECT"
},
"country": "GTM",
"currency": "GTQ",
"amount": 10,
"accountNumber": "{{YourAccountNumber}}",
"confirmed": {
"currency": "GTQ",
"amount": 10,
"fxQuote": 1
},
"payment": {
"currency": "GTQ",
"fxQuote": 1,
"financingFee": 0,
"amount": 10
},
"localTaxes": [],
"withHoldings": [],
"fees": {
"description": "Fee",
"currency": "GTQ",
"fxSource": 1,
"fxQuote": 1,
"amount": 0,
"account": "{{YourAccountNumber}}"
},
"status": {
"code": "100",
"description": "INPROGRESS",
"detail": "The payin is pending the confirmation"
},
"merchant": {
"type": "COMPANY",
"name": "Company"
},
"payer": {
"type": "INDIVIDUAL",
"name": "John",
"lastname": "Doe",
"document": {
"type": "CUI",
"id": "3463426000101"
},
"email": "[email protected]",
"phone": {
"countryCode": "gt",
"areaCode": "502",
"number": "55555555"
},
"address": {
"street": "",
"city": "",
"state": "",
"country": "",
"comment": ""
}
},
"intermediaries": [],
"date": {
"creationDate": "2025-01-23T14:15:13.368+00:00",
"processedDate": "2025-01-23T14:15:14.6506329",
"expirationDate": "2025-01-30T14:15:13.550683"
},
"errors": []
}Key Response Fields
| Parameter | Description | Use Case |
|---|---|---|
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. |
date.expirationDate | ISO timestamp when authorization expires. | Display countdown timer and handle expiration logic. |
Error Response
When Wallet Fri request creation 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. Customer Authorization Process
- Push Notification: Customer receives payment request directly in Wallet Fri app.
- App Notification: Payment request appears as push notification on mobile device.
- In-App Authorization: Customer opens Wallet Fri app to review and authorize payment.
- Security Verification: Customer completes PIN or biometric authentication.
- Payment Confirmation: Transaction is processed instantly upon authorization.
- Status Update: Your system receives webhook with final payment status.
Step 4. Track Transaction Status
Monitor Wallet Fri 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 Wallet Fri payment.
| Code | Status | Description |
|---|---|---|
100 | INPROGRESS | Payment request created, notification sent. |
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 Wallet Fri Scenarios
Verify your integration handles these scenarios:
- Successful Payment: Customer receives notification and authorizes payment.
- Authorization Expired: Customer doesn't respond within time limit.
- Status Updates: Webhook handling and status polling.
Next Steps
After implementing Wallet Fri payments, consider these additional capabilities:
Updated 3 days ago