> ## Documentation Index
> Fetch the complete documentation index at: https://docs.localpayment.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Wallet Fri (Guatemala)

Localpayment permite a los comercios procesar pagos instantáneos con billeteras digitales a través del sistema Wallet Fri de Guatemala. Esta guía describe el proceso para iniciar pagos con Wallet Fri mediante la API de Localpayment, detallando los parámetros necesarios, el manejo de las respuestas y la interpretación de los códigos de estado para una integración perfecta con la popular plataforma de billeteras digitales de Guatemala.

## Antes de comenzar

Asegúrate de tener:

* [Credenciales API](https://docs.localpayment.com/es/docs/api-keys-and-environments.md) válidas (token de acceso).

***

## Paso 1. Crear un pago con Wallet Fri

Para generar una solicitud de pago de Wallet Fri, envía una solicitud `POST` al endpoint [Crear Payin](https://docs.localpayment.com/es/reference/payins.md) con parámetros específicos de Wallet Fri.

### Parámetros clave de la solicitud

La solicitud requiere varios objetos clave específicos para los pagos de Wallet Fri:

| Objeto | Descripción | Requerido |
| - | - | - |
| `paymentMethod.type` | Debe ser `Wallet`. | ✅ |
| `paymentMethod.code` | Debe ser `1880` para Wallet Fri. | ✅ |
| `payer` | Información de la cuenta del pagador. | ✅ |
| `merchant` | Datos del comerciante/negocio | ✅ |
| `amount` | Importe de la transacción | ✅ |
| `currency` | Código de moneda de la transacción | ✅ |
| `country` | Debe ser `GTM` | ✅ |

Consulta todos los [parámetros disponibles](https://docs.localpayment.com/es/reference/payins.md) en la solicitud.

### Ejemplo de solicitud

A continuación se muestra un ejemplo que utiliza `curl`:

```bash curl theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
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",
    "name": "John",
    "lastName": "Doe",
    "document": {
      "type": "CUI",
      "id": "3463426000101"
    },
    "email": "john.doe@example.com",
    "phone": {
      "countryCode": "gt",
      "areaCode": "502",
      "number": "55555555"
    },
    "address": {
      "street": "",
      "city": "",
      "state": "",
      "country": "",
      "comment": ""
    }
  },
  "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"
}
'
```

***

## Paso 2. Gestionar la respuesta

### Respuesta exitosa

Al crear un pago con Wallet Fri, el sistema envía automáticamente una notificación push a la aplicación Wallet Fri del cliente. La respuesta de la API confirma que la solicitud de pago se creó correctamente y está pendiente de autorización por parte del cliente.

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "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": "john.doe@example.com",
    "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": []
}
```

### Campos de respuesta clave

| Parámetro | Descripción | Caso de uso |
| - | - | - |
| `externalId` | Tu número de referencia original. | Conciliación interna y cotejo de pedidos. |
| `status.code` | Estado actual de la transacción (`100` = `INPROGRESS`) | Determinar los siguientes pasos en el flujo de pagos. |
| `date.creationDate` | Cuando se creó la transacción. | Análisis y seguimiento del rendimiento. |
| `date.expirationDate` | Marca de tiempo ISO cuando expira la autorización. | Muestra un temporizador de cuenta regresiva y gestiona la lógica de expiración. |

#### Respuesta de error

Cuando falle la creación de la solicitud de Wallet Fri, recibirás información detallada sobre el error:

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "externalId": "ce0aaa1a-4532-43b9-930a-26e780aba99b",
  "status": {
    "code": "812",
    "description": "REJECTED"
  },
  "errors": [
    {
      "code": "812",
      "detail": "External Id already used - duplication"
    }
  ]
}
```

***

## Paso 3. Proceso de autorización del cliente

1. **Notificación push**: El cliente recibe la solicitud de pago directamente en la aplicación Wallet Fri.
2. **Notificación de la aplicación**: La solicitud de pago aparece como una notificación push en el dispositivo móvil.
3. **Autorización dentro de la aplicación**: El cliente abre la aplicación Wallet Fri para revisar y autorizar el pago.
4. **Verificación de seguridad**: El cliente completa la autenticación mediante PIN o datos biométricos.
5. **Confirmación de pago**: La transacción se procesa instantáneamente tras la autorización.
6. **Actualización de estado**: Tu sistema recibe un webhook con el estado final del pago.

***

## Paso 4. Seguimiento del estado de la transacción

Supervisa el progreso de los pagos de Wallet Fri mediante estos métodos:

> [card] [Webhooks (recomendado)](https://docs.localpayment.com/es/docs/webhooks.md)
>
> Recibe notificaciones en tiempo real cuando cambie el estado de la transacción. Más eficiente para entornos de producción.

> [card] [Endpoint de la API de estado](https://docs.localpayment.com/es/reference/get-transaction-status.md)
>
> Consulta el estado de las transacciones mediante programación. Útil para sondear o recuperar notificaciones de webhook perdidas.

> [card] [Vista del Business Portal](https://docs.localpayment.com/es/docs/dashboard-overview.md)
>
> Interfaz visual para el seguimiento de transacciones. Ideal para la supervisión manual y el análisis detallado de las transacciones.

### Códigos de estado comunes

La API de Localpayment proporciona varios códigos de estado para indicar el progreso y el resultado del pago de Wallet Fri.

| Código | Estado | Descripción |
| :- | :- | :- |
| `100` | `INPROGRESS` | Solicitud de pago creada, notificación enviada. |
| `200` | `Completed` | El payin se ha completado. |
| `811` | `Rejected` | La cantidad solicitada es mayor o menor que los valores máximos/mínimos permitidos. |

> [!NOTE]
>
> **Referencia completa**
>
> Consulta todos los códigos de estado en nuestra [documentación sobre el estado de las transacciones](https://docs.localpayment.com/es/reference/transaction-status-error-codes).

***

## Probando tu integración

### Entorno de pruebas

Utiliza el entorno de prueba para realizar las pruebas:

```
https://api.stage.localpayment.com/api/payin/
```

### Escenarios de prueba de Wallet Fri

Verifica que tu integración gestione estos escenarios:

1. **Pago exitoso**: El cliente recibe la notificación y autoriza el pago.
2. **Autorización caducada**: El cliente no responde dentro del plazo establecido.
3. **Actualizaciones de estado**: Gestión de webhooks y sondeo de estado.

***

## Demo

La siguiente demostración muestra cómo un cliente realiza un pago a través de la aplicación Wallet Fri, desde la solicitud pendiente hasta el recibo de pago.

![Recorrido animado de un cliente que paga una solicitud de Localpayment en la aplicación Wallet Fri, desde la solicitud pendiente hasta el recibo de pago](https://mintcdn.com/localpayment-1fee3d41/-KiHmfqcrFqGOaEH/images/docs/fd9657a09b9e168412b38715918b8a2e5c66580bbf2f478e2a299ec5183ae07d-wallet-fri-demo.gif?s=4fa8a5e0c2a3af1a0df336668d493cc5)

***

## Próximos pasos

Tras implementar los pagos de Wallet Fri, ten en cuenta estas funcionalidades adicionales:

> [card] [Reembolsar la transacción](https://docs.localpayment.com/es/docs/refund-apm-payment.md)
>
> Si es necesario, puedes reembolsar el pago al cliente. Consulta la documentación para obtener más detalles.

> [card] [Revisar los detalles de la transacción](https://docs.localpayment.com/es/reference/get-transaction-status.md)
>
> Puedes recuperar información sobre las transacciones utilizando la API de Localpayment para obtener información detallada.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.