> ## 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（危地马拉）

Localpayment 使商家能够通过危地马拉的 Wallet Fri 系统处理即时数字钱包支付。本指南概述了通过 Localpayment 的 API 发起 Wallet Fri 支付的流程，详细说明了所需的参数、响应处理以及状态代码解读，从而实现与危地马拉流行的数字钱包平台的无缝集成。

## 开始之前

请确保您已备好：

* 有效的[API 凭证](https://docs.localpayment.com/zh/docs/api-keys-and-environments.md)（访问令牌）。

***

## 步骤 1. 创建 Wallet Fri 付款

要生成 Wallet Fri 付款请求，请向 [Create Payin](https://docs.localpayment.com/zh/reference/payins.md) endpoint 发送带有 Wallet Fri 特定参数的 `POST` 请求。

### 关键请求参数

该请求需要几个 Wallet Fri 支付特有的关键对象：

| 对象 | 描述 | 必需的 |
| - | - | - |
| `paymentMethod.type` | 必须是 `Wallet`。 | ✅ |
| `paymentMethod.code` | Wallet Fri 必须是 `1880`。 | ✅ |
| `payer` | 付款人账户信息。 | ✅ |
| `merchant` | 商家/企业详情 | ✅ |
| `amount` | 交易金额 | ✅ |
| `currency` | 交易货币代码 | ✅ |
| `country` | 必须是 `GTM` | ✅ |

查看请求中所有[可用的参数](https://docs.localpayment.com/zh/reference/payins.md)。

### 示例请求

以下是一个使用 `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"
}
'
```

***

## 步骤 2：处理响应

### 成功响应

当您创建 Wallet Fri 付款时，系统会自动向客户的 Wallet Fri 应用发送推送通知。API 响应确认付款请求已成功创建，并正在等待客户授权。

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

### 关键响应字段

| 参数 | 描述 | 用例 |
| - | - | - |
| `externalId` | 您的原始参考编号。 | 内部核对和订单匹配。 |
| `status.code` | 当前交易状态（`100` = `INPROGRESS`） | 确定付款流程的后续步骤。 |
| `date.creationDate` | 交易创建时。 | 分析和绩效跟踪。 |
| `date.expirationDate` | 授权到期时的 ISO 时间戳。 | 显示倒计时器并处理过期逻辑。 |

#### 错误响应

当 Wallet Fri 创建请求失败时，您将收到详细的错误信息：

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

***

## 步骤 3. 客户授权流程

1. **推送通知**：客户直接在 Wallet Fri 应用中收到付款请求。
2. **应用通知**：支付请求会在移动设备上显示为推送通知。
3. **应用内授权**：客户打开 Wallet Fri 应用查看并授权付款。
4. **安全验证**：客户完成PIN码或生物识别认证。
5. **付款确认**：交易将在获得授权后立即处理。
6. **状态更新**：您的系统已收到包含最终付款状态的 webhook。

***

## 第四步：跟踪交易状态

您可以通过以下方式监控 Wallet Fri 的付款进度：

> [card] [Webhooks（推荐）](https://docs.localpayment.com/zh/docs/webhooks.md)
>
> 交易状态变更时接收实时通知。最适用于生产环境。

> [card] [状态 API endpoint](https://docs.localpayment.com/zh/reference/get-transaction-status.md)
>
> 以编程方式查询事务状态。可用于轮询或恢复丢失的 webhook 通知。

> [card] [Business Portal 视图](https://docs.localpayment.com/zh/docs/dashboard-overview.md)
>
> 用于监控交易的可视化界面。非常适合人工监督和详细的交易分析。

### 常用状态码

Localpayment API 提供各种状态代码来指示 Wallet Fri 付款的进度和结果。

| 代码 | 状态 | 描述 |
| :- | :- | :- |
| `100` | `INPROGRESS` | 付款请求已创建，通知已发送。 |
| `200` | `Completed` | 付款已完成。 |
| `811` | `Rejected` | 请求金额高于或低于允许的最大/最小值。 |

> [!NOTE]
>
> **完整参考**
>
> 请查看我们的[交易状态文档](https://docs.localpayment.com/zh/reference/transaction-status-error-codes)，了解所有状态代码。

***

## 测试您的集成

### 沙盒环境

使用测试环境：

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

### 测试 Wallet Fri 场景

请确认您的集成方案能够处理以下场景：

1. **付款成功**：客户收到通知并授权付款。
2. **授权已过期**：客户未在规定时间内做出响应。
3. **状态更新**：Webhook 处理和状态轮询。

***

## 演示

以下演示展示了客户如何在应用程序中支付 Wallet Fri 付款请求，从待处理的请求到付款收据。

![动画演示客户在 Wallet Fri 应用中支付 Localpayment 请求的过程，从请求待处理到最终收到付款收据](https://mintcdn.com/localpayment-1fee3d41/-KiHmfqcrFqGOaEH/images/docs/fd9657a09b9e168412b38715918b8a2e5c66580bbf2f478e2a299ec5183ae07d-wallet-fri-demo.gif?s=4fa8a5e0c2a3af1a0df336668d493cc5)

***

## 后续步骤

在实施 Wallet Fri 支付功能后，请考虑以下附加功能：

> [card] [退款](https://docs.localpayment.com/zh/docs/refund-apm-payment.md)
>
> 如有必要，您可以将款项退还给客户。详情请参阅相关文档。

> [card] [查看交易详情](https://docs.localpayment.com/zh/reference/get-transaction-status.md)
>
> 您可以使用 Localpayment API 获取交易信息，以获得更详细的分析。


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