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

# 锁定汇率

锁定汇率可让您在执行交易之前保证兑换价格，保护您和您的用户免受报价与执行之间市场波动的影响。

所有三种流程（收款、付款和批量兑换）都遵循相同的两步模式：

1. **获取报价**：调用[货币兑换报价 API](https://docs.localpayment.com/zh/reference/currency-exchange-quote.md)，并指定操作类型（`payin`、`payout` 或 `CurrencyExchange`）。您将收到一个 `exchangeRateToken`，其中包含有保证的汇率和到期时间。
2. **使用令牌**：在您的收款、付款或批量兑换请求中包含 `exchangeRateToken`。API 会自动应用已锁定的汇率。

以下各节以收款为例，但付款和批量兑换的结构类似。

> [!WARNING]
>
> **汇率到期**
>
> 锁定的汇率仅在令牌的 `expirationDate` 之前有保证。如果令牌在您提交交易之前过期，该操作将使用当时的市场汇率。

***

## 为收款报价

当您希望在收取付款之前向用户显示汇率时，请使用此流程。

### 步骤 1：请求报价

**请求**

```bash curl theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
curl --request GET \
     --url 'https://api.stage.localpayment.com/api/fx/currency-exchange/payin?sourceCurrency=ARS&quoteCurrency=USD&accountNumber={{accountNumber}}&quoteAccountNumber={{accountNumber}}' \
     --header 'Authorization: Bearer <your_access_token>' \
     --header 'accept: application/json'
```

**回复**

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "exchangeRateToken": "5c3q89a7-f1bc-4ba5-a3b5-411ba0d144ca",
  "transactionType": "PayIn",
  "accountNumber": "{{accountNumber}}",
  "sourceCurrency": "ARS",
  "creationDate": "2024-12-27T21:33:32.6513692+00:00",
  "expirationDate": "2024-12-28T05:33:32.6513692+00:00",
  "quotes": [
    {
      "paymentMethodCode": "1005",
      "rate": 0.0008369108482392735,
      "quoteCurrency": "USD"
    },
    {
      "paymentMethodCode": "1023",
      "rate": 0.0008369108482392735,
      "quoteCurrency": "USD"
    },
    {
      "paymentMethodCode": "1000",
      "rate": 0.0008369108482392735,
      "quoteCurrency": "USD"
    }
  ]
}
```

### 步骤 2：使用令牌提交收款

**请求**

```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' \
     --data '
{
  "paymentMethod": {
    "type": "CreditCard",
    "code": "1000",
    "flow": "DIRECT"
  },
  "externalId": "4423f38d-cc35-4ca9-8119-b9102059172d",
  "country": "ARG",
  "currency": "ARS",
  "amount": 100,
  "accountNumber": "{{accountNumber}}",
  "conceptCode": "0001",
  "comment": "APPROVED",
  "exchangeRateToken": "5c3q89a7-f1bc-4ba5-a3b5-411ba0d144ca,
  "merchant": {
    "type": "COMPANY",
    "name": "Company",
    "document": {
      "id": "3000091105",
      "type": "CUIT"
    }
  },
  "payer": {
    "type": "INDIVIDUAL",
    "name": "John",
    "lastname": "Doe",
    "document": {
      "id": "37993123",
      "type": "DNI"
    },
    "email": "john.doe@example.com",
    "phone": {
      "countryCode": "1",
      "areaCode": "11",
      "number": "98189123"
    },
    "bank": {
      "account": {
        "type": "C"
      }
    }
  },
  "metaData": {
    "1finalStatus": "APPROVED",
    "2finalStatus": "INPROGRESS"
  },
  "card": {
    "name": "APPRO",
    "number": "4970100000000055",
    "cvv": "123",
    "expirationMonth": "11",
    "expirationYear": "2029",
    "installments": 1,
    "save": false
  }
}
'
```

**回复**

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "transactionType": "PayIn",
  "externalId": "949e5683-4320-4129-bf0a-ea3b027b6cd1",
  "internalId": "22b29c98-92af-44bd-a164-1863ae2f1bb3",
  "paymentMethod": {
    "type": "CreditCard",
    "code": "1000",
    "flow": "DIRECT"
  },
  "country": "ARG",
  "currency": "ARS",
  "amount": 1002,
  "accountNumber": "{{accountNumber}}",
  "confirmed": {
    "currency": "ARS",
    "amount": 1002,
    "fxQuote": 1,
    "exchangeRateToken": null
  },
  "payment": {
    "installment": null,
    "currency": "ARS",
    "fxQuote": 1,
    "financingFee": 0,
    "amount": 1002
  },
  "localTaxes": [],
  "withHoldings": [],
  "fees": {
    "description": "Fee",
    "currency": "ARS",
    "fxSource": 210.8,
    "fxQuote": 1,
    "amount": 13.02,
    "account": "{{accountNumber}}"
  },
  "status": {
    "code": "103",
    "description": "APPROVED",
    "detail": "The payin was confirmed but not credited yet"
  },
  "ticket": null,
  "qr": null,
  "beneficiary": null,
  "merchant": {
    "type": "COMPANY",
    "name": "Company"
  },
  "payer": {
    "type": "INDIVIDUAL",
    "name": "John",
    "lastname": "Doe",
    "document": {
      "id": "37895247",
      "type": "DNI"
    },
    "email": "john.doe@example.com",
    "phone": {
      "countryCode": "1",
      "areaCode": "11",
      "number": "98789632"
    },
    "address": null,
    "birthdate": null,
    "nationality": null
  },
  "intermediaries": [],
  "wireInstructions": null,
  "date": {
    "creationDate": "2024-05-19T19:02:44.018+00:00",
    "processedDate": "2024-05-19T19:02:44.799618",
    "expirationDate": "0001-01-01T00:00:00"
  },
  "card": {
    "token": "N66a0BVHGJY/oCwOyl/CbxIJ5DmCINWeir9PY9gxVGI=",
    "bin": "402670",
    "brand": "VISA",
    "country": "RS",
    "name": "John Doe",
    "last4": "3263",
    "expirationYear": 2029,
    "expirationMonth": 9
  },
  "errors": []
}
```

```bash curl theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
curl --request POST \
     --url https://api.stage.localpayment.com/api/payout/ \
     --header 'Authorization: Bearer <your_access_token>' \
     --header 'Content-Type: application/json' \
     --data '[{
       "externalId": "3b7e91a0-2c4d-4f83-a1b2-d05143e2238a",
       "country": "ARG",
       "currency": "ARS",
       "amount": 10000,
       "accountNumber": "{{accountNumber}}",
       "exchangeRateToken": "8f2d14b3-c4ea-4912-b7a1-922cd1e255fb",
       "paymentMethod": {
         "type": "BankTransfer",
         "code": "1005",
         "flow": "DIRECT"
       }
     }]'
```

***

## 在结账前显示汇率

如果您正在构建结账流程，并希望在用户**确认付款之前**向其显示汇率，流程如下：

1. 用户选择金额和货币。
2. 您的后端调用[货币兑换报价 API](https://docs.localpayment.com/zh/reference/currency-exchange-quote.md)，并在 `exchangeRateToken` 参数中接收汇率。
3. 您的前端显示：“您将支付 10,000 ARS ≈ 8.37 USD（汇率：0.000837）”
4. 用户确认。
5. 您的后端使用 `exchangeRateToken` 提交收款，以应用锁定的汇率。

只要您在令牌的 `expirationDate` 之前提交，就能保证用户看到的汇率即为应用于该交易的汇率。

> [!NOTE]
>
> **设计提示：**
>
> 在界面中以倒计时形式显示 `expirationDate`（例如 *“汇率有效期为 8 小时”*）。这样可以设定正确的预期，并减少因会话之间汇率变动而产生的支持工单。


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