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

# Cotação de Conversão de Moedas

Obtenha cotações de câmbio em tempo real com taxas seguras baseadas em tokens para suas transações internacionais.

A API de Cotação de Câmbio permite obter taxas de câmbio entre diferentes moedas e receber um token seguro que fixa a taxa cotada por um período específico. Isso garante a consistência da taxa para suas transações subsequentes, além de proteger contra a volatilidade do mercado.

## Pré-requisitos

Antes de solicitar cotações de câmbio, certifique-se de ter:

* **Credenciais de API válidas** com permissões para conversão de moeda.
* **Números de contas ativas** para as moedas de origem e de cotação.

***

## Endpoint da API

Para cotar um câmbio, envie uma solicitação `GET` para o endpoint [Obtenha uma cotação de câmbio](https://docs.localpayment.com/pt-br/reference/currency-exchange-quote.md).

### Endpoint

```http theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
GET https://api.stage.localpayment.com/api/fx/currency-exchange/{type}
```

Substitua `{type}` pelo tipo de transação que melhor se adequa ao seu caso de uso:

| `{type}` | Quando usar |
| - | - |
| `payin` | Você deseja exibir a taxa de câmbio antes de receber um pagamento |
| `payout` | Você deseja exibir a taxa de câmbio antes de enviar um pagamento |
| `CurrencyExchange` | Você deseja exibir a taxa de câmbio antes de enviar uma conversão de moeda. |

### Autenticação

Inclua seu token de acesso nos cabeçalhos da solicitação:

```http theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
Authorization: Bearer <your_access_token>
```

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

| Parâmetro | Tipo | Descrição |
| - | - | - |
| `sourceCurrency` | string | Moeda da qual você deseja converter (por exemplo, `"ARS"`, `"USDT"`) |
| `quoteCurrency` | string | Moeda para a qual você deseja converter (por exemplo, `"USD"`) |
| `accountNumber` | string | Sua conta Localpayment que contém a **moeda de origem** (a conta que está sendo debitada) |
| `quoteAccountNumber` | string | Sua conta Localpayment que possui a **moeda de destino** (a conta a ser creditada) |

### Exemplo de solicitação

> [tab] Moeda local (Payin)
>
> ```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={{sourceAccountNumber}}&quoteAccountNumber={{quoteAccountNumber}}' \
>      --header 'Authorization: Bearer <your_access_token>' \
>      --header 'accept: application/json'
> ```

> [tab] Stablecoin (USDC / USDT)
>
> ```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/CurrencyExchange?sourceCurrency=USDT&quoteCurrency=USD&accountNumber={{sourceAccountNumber}}&quoteAccountNumber={{quoteAccountNumber}}' \
>      --header 'Authorization: Bearer <your_access_token>' \
>      --header 'accept: application/json'
> ```

***

## Tratamento de Respostas

### Resposta bem-sucedida

Uma solicitação bem-sucedida retorna informações sobre a taxa de câmbio com um token seguro:

> [tab] Local currency (PayIn)
>
> ```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
> {
>   "exchangeRateToken": "5c3q89a7-f1bc-4ba5-a3b5-411ba0d144ca",
>   "transactionType": "PayIn",
>   "accountNumber": "{{sourceAccountNumber}}",
>   "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"
>     }
>   ]
> }
> ```

> [tab] Stablecoin (USDC / USDT)
>
> ```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
> {
>   "accountNumber": "{{sourceAccountNumber}}",
>   "creationDate": "2026-01-15T21:03:06.2722727Z",
>   "exchangeRateToken": "b4eb8276-8edc-43e6-937d-97ecd98ea902",
>   "expirationDate": "2026-01-15T21:14:06.2722727Z",
>   "quotes": [
>     {
>       "paymentMethodCode": null,
>       "quoteAccountNumber": "{{quoteAccountNumber}}",
>       "quoteCurrency": "USD",
>       "rate": 1
>     }
>   ],
>   "sourceCurrency": "USDT",
>   "transactionType": "CurrencyExchange"
> }
> ```

#### Campos de resposta principais

| Campo | Tipo | Descrição |
| - | - | - |
| `exchangeRateToken` | string | Token único para usar em transações subsequentes |
| `transactionType` | string | Tipo de transação (PayIn, PayOut) |
| `accountNumber` | string | Conta na moeda de origem (a conta debitada) |
| `sourceCurrency` | string | Código da moeda de origem |
| `creationDate` | datetime | Quando a cotação foi criada |
| `expirationDate` | datetime | Quando a cotação expira |
| `quotes` | array | Métodos de pagamento disponíveis e suas taxas |

### Respostas de erro

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "detail": "You do not have permission to perform this action."
}
```

***

## Melhores práticas

### Segurança e desempenho

* Utilize sempre HTTPS para solicitações de API.
* Armazene os tokens de acesso em local seguro e alterne-os regularmente.
* Monitore atentamente os prazos de expiração dos tokens.
* Armazene as cotações em cache adequadamente, mas respeite as datas de expiração.

### Importante: Expiração do token

Os tokens de taxa de câmbio têm um prazo de validade limitado. Planeje seu fluxo de trabalho de transação para que seja concluído dentro do período de expiração. A taxa cotada é garantida apenas enquanto o token estiver válido.

> [!NOTE]
>
> **Dica profissional**
>
> Diferentes métodos de pagamento podem oferecer taxas de câmbio diferentes. Analise todas as opções disponíveis no array `quotes` para selecionar a taxa mais favorável ao seu caso de uso.

***

## Fluxo de trabalho de integração

1. **Solicite uma cotação**: peça taxas de câmbio para o par de moedas desejado.
2. **Selecione o método**: escolha o método de pagamento mais adequado entre as cotações.
3. **Armazene o token**: salve o `exchangeRateToken` para a sua transação.
4. **Execute a transação**: utilize o token na sua chamada à API de pagamento.
5. **Monitore a validade**: conclua a transação antes do `expirationDate`.

***

## Próximos passos

> [card] [Processamento de Payins](https://docs.localpayment.com/pt-br/reference/payins.md)
>
> Processe os Payins usando a moeda convertida.

> [card] [Processamento de Payouts](https://docs.localpayment.com/pt-br/reference/create-a-payout.md)
>
> Processe os Payouts usando a moeda convertida.

> [card] [Executar Câmbio de Moedas](https://docs.localpayment.com/pt-br/reference/exchange-bulk.md)
>
> Utilize seu token de taxa de câmbio para realizar a conversão de moeda.

> [!NOTE]
>
> **Dica profissional**
>
> Teste seu fluxo de trabalho minuciosamente em nosso ambiente de sandbox. Isso garante que sua integração lide corretamente com flutuações de taxas, expiração de tokens e cenários de erro antes de entrar em produção.

***

> [!NOTE]
>
> **Precisa de ajuda?**
>
> Entre em contato com nossa [equipe de suporte](mailto:support@localpayment.com) caso encontre algum problema ou precise de ajuda com a integração.


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