> ## 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.

# Carteira Fri (Guatemala)

A Localpayment permite que comerciantes processem pagamentos instantâneos por meio de carteiras digitais, utilizando o sistema WalletFri da Guatemala. Este guia descreve o processo para iniciar pagamentos com o WalletFri através da API da Localpayment, detalhando os parâmetros necessários, o tratamento de respostas e a interpretação de códigos de status para uma integração perfeita com a popular plataforma de carteira digital da Guatemala.

## Antes de começar

Certifique-se de ter:

* [Credenciais de API válidas](https://docs.localpayment.com/pt-br/docs/api-keys-and-environments.md) (token de acesso).

***

## Passo 1. Criar pagamento Wallet Fri

Para gerar uma solicitação de pagamento Wallet Fri, envie uma solicitação `POST` ao endpoint [Criar Payin](https://docs.localpayment.com/pt-br/reference/payins.md) com parâmetros específicos do Wallet Fri.

### Parâmetros-chave da solicitação

A solicitação requer vários objetos-chave específicos para pagamentos do Wallet Fri:

| Objeto | Descrição | Obrigatório |
| - | - | - |
| `paymentMethod.type` | Deve ser `Wallet`. | ✅ |
| `paymentMethod.code` | Deve ser `1880` para o Wallet Fri. | ✅ |
| `payer` | Informações da conta do pagador. | ✅ |
| `merchant` | Detalhes do comerciante/empresa | ✅ |
| `amount` | Valor da transação | ✅ |
| `currency` | Código da moeda da transação | ✅ |
| `country` | Deve ser `GTM` | ✅ |

Veja todos os [parâmetros disponíveis](https://docs.localpayment.com/pt-br/reference/payins.md) na solicitação.

### Exemplo de solicitação

Abaixo está um exemplo usando `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"
}
'
```

***

## Etapa 2. Lidar com a resposta

### Resposta bem-sucedida

Ao criar um pagamento via Wallet Fri, o sistema envia automaticamente uma notificação push para o aplicativo Wallet Fri do cliente. A resposta da API confirma que a solicitação de pagamento foi criada com sucesso e está aguardando autorização do 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 resposta principais

| Parâmetro | Descrição | Caso de uso |
| - | - | - |
| `externalId` | Seu número de referência original. | Conciliação interna e correspondência de pedidos. |
| `status.code` | Estado atual da transação (`100` = `INPROGRESS`) | Determine os próximos passos no fluxo de pagamento. |
| `date.creationDate` | Quando a transação foi criada. | Análise e monitoramento de desempenho. |
| `date.expirationDate` | Carimbo de data/hora ISO que indica quando a autorização expira. | Exibir cronômetro de contagem regressiva e lidar com a lógica de expiração. |

#### Resposta de erro

Quando a criação de uma solicitação Wallet Fri falhar, você receberá informações detalhadas sobre o erro:

```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"
    }
  ]
}
```

***

## Etapa 3. Processo de Autorização do Cliente

1. **Notificação Push**: O cliente recebe a solicitação de pagamento diretamente no aplicativo Wallet Fri.
2. **Notificação do aplicativo**: A solicitação de pagamento aparece como uma notificação push no dispositivo móvel.
3. **Autorização no aplicativo**: O cliente abre o aplicativo Wallet Fri para revisar e autorizar o pagamento.
4. **Verificação de segurança**: O cliente insere um PIN ou realiza a autenticação biométrica.
5. **Confirmação de pagamento**: A transação é processada instantaneamente após a autorização.
6. **Atualização de status**: Seu sistema recebeu um webhook com o status final do pagamento.

***

## Etapa 4. Acompanhe o status da transação

Acompanhe o progresso dos pagamentos do Wallet Fri através destes métodos:

> [card] [Webhooks (Recomendado)](https://docs.localpayment.com/pt-br/docs/webhooks.md)
>
> Receba notificações em tempo real quando o status da transação mudar. Ideal para ambientes de produção.

> [card] [Endpoint da API de Status](https://docs.localpayment.com/pt-br/reference/get-transaction-status.md)
>
> Consultar o status da transação programaticamente. Útil para consultar ou recuperar notificações de webhook perdidas.

> [card] [Visualização do Business Portal](https://docs.localpayment.com/pt-br/docs/dashboard-overview.md)
>
> Interface visual para monitoramento de transações. Ideal para supervisão manual e análise detalhada de transações.

### Códigos de status comuns

A API Localpayment fornece vários códigos de status para indicar o progresso e o resultado do pagamento Wallet Fri.

| Código | Status | Descrição |
| :- | :- | :- |
| `100` | `INPROGRESS` | Solicitação de pagamento criada, notificação enviada. |
| `200` | `Completed` | O Payin foi concluído. |
| `811` | `Rejected` | O valor solicitado é maior ou menor que os valores máximo/mínimo permitidos. |

> [!NOTE]
>
> **Referência completa**
>
> Consulte todos os códigos de status em nossa [Documentação de Status da Transação](https://docs.localpayment.com/pt-br/reference/transaction-status-error-codes).

***

## Testando sua integração

### Ambiente de Sandbox

Use o ambiente de staging para testes:

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

### Cenários de teste do Wallet Fri

Verifique se sua integração lida com esses cenários:

1. **Pagamento bem-sucedido**: O cliente recebe a notificação e autoriza o pagamento.
2. **Autorização expirada**: o cliente não respondeu dentro do prazo estipulado.
3. **Atualizações de status**: gerenciamento de webhooks e consulta de status.

***

## Demonstração

A demonstração a seguir mostra como um cliente paga uma solicitação de pagamento do Wallet Fri no aplicativo, desde a solicitação pendente até o recibo de pagamento.

![Animação passo a passo de um cliente pagando uma solicitação Localpayment no aplicativo Wallet Fri, desde a solicitação pendente até o recibo de pagamento](https://mintcdn.com/localpayment-1fee3d41/-KiHmfqcrFqGOaEH/images/docs/fd9657a09b9e168412b38715918b8a2e5c66580bbf2f478e2a299ec5183ae07d-wallet-fri-demo.gif?s=4fa8a5e0c2a3af1a0df336668d493cc5)

***

## Próximos passos

Após implementar os pagamentos com a Wallet Fri, considere estas funcionalidades adicionais:

> [card] [Reembolsar a transação](https://docs.localpayment.com/pt-br/docs/refund-apm-payment.md)
>
> Caso necessário, você pode reembolsar o pagamento ao cliente. Consulte a documentação para obter detalhes.

> [card] [Analisar detalhes da transação](https://docs.localpayment.com/pt-br/reference/get-transaction-status.md)
>
> Você pode obter informações detalhadas sobre as transações usando a API Localpayment.


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