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

# Fixar uma taxa de câmbio

Fixar uma taxa de câmbio permite garantir o preço da conversão antes de executar uma transação, protegendo você e seus usuários das flutuações do mercado entre a cotação e a execução.

Todos os três fluxos: payins, payout e câmbio em lote: seguem o mesmo padrão de duas etapas:

1. **Obtenha uma cotação**: Chame a [API de cotação de câmbio](https://docs.localpayment.com/pt-br/reference/currency-exchange-quote.md) especificando o tipo de operação (`payin`, `payout` ou `CurrencyExchange`). Você receberá um `exchangeRateToken` com uma taxa garantida e um prazo de validade.
2. **Use o token**: Inclua o `exchangeRateToken` na sua solicitação de payin, payout ou câmbio em lote. A API aplica a taxa fixada automaticamente.

As seções abaixo usam um payin como exemplo, mas a estrutura é semelhante para payouts e câmbio em lote.

> [!WARNING]
>
> **Validade da taxa**
>
> A taxa fixada só é garantida até a `expirationDate` do token. Se o token expirar antes de você enviar a transação, a operação usará a taxa de mercado naquele momento.

***

## Cotar um Payin

Use este fluxo quando quiser mostrar a taxa de câmbio ao seu usuário antes de receber um pagamento.

### Etapa 1: Solicitar uma cotação

**Solicitar**

```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'
```

**Resposta**

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

### Etapa 2: Enviar o payin com o token

**Solicitar**

```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
  }
}
'
```

**Resposta**

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

***

## Mostrar a taxa de câmbio antes do checkout

Se você está criando um checkout e quer exibir a taxa de câmbio ao seu usuário **antes de ele confirmar o pagamento**, este é o fluxo:

1. O usuário seleciona um valor e uma moeda.
2. Seu backend chama a [API de cotação de câmbio](https://docs.localpayment.com/pt-br/reference/currency-exchange-quote.md)  e recebe a taxa no parâmetro `exchangeRateToken`.
3. Seu frontend exibe: "Você pagará 10,000 ARS ≈ 8.37 USD (taxa: 0.000837)"
4. O usuário confirma.
5. Seu backend envia o payin com o `exchangeRateToken`  para aplicar a taxa fixada.

Isso garante que a taxa que seu usuário viu seja a taxa aplicada à transação, desde que você envie antes da `expirationDate` do token.

> [!NOTE]
>
> **Dica de design:**
>
> Exiba a `expirationDate` na sua interface como uma contagem regressiva (por exemplo, *"Taxa válida por 8 horas"*). Isso cria a expectativa correta e reduz chamados de suporte quando uma taxa muda entre sessões.


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