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

# Cotizar conversión de divisas

Obtén cotizaciones de cambio de divisas en tiempo real con tipos de cambio seguros basados ​​en tokens para tus transacciones internacionales.

La API de cotización de divisas te permite obtener tipos de cambio entre diferentes monedas y recibir un token seguro que fija el tipo de cambio cotizado durante un período determinado. Esto garantiza la consistencia del tipo de cambio para tus transacciones posteriores, a la vez que te protege de la volatilidad del mercado.

## Requisitos previos

Antes de solicitar cotizaciones de cambio de divisas, asegúrate de tener:

* **Credenciales API válidas** con permisos de cambio de divisas.
* **Números de cuenta activos** tanto para la divisa de origen como para la divisa de cotización.

***

## Endpoint de la API

Para cotizar un cambio, envía una solicitud `GET` al endpoint [Obtén una cotización de divisas](https://docs.localpayment.com/es/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}
```

Reemplaza `{type}` con el tipo de transacción que coincida con tu caso de uso:

| `{type}` | Cuándo usar |
| - | - |
| `payin` | Quieres mostrar el tipo de cambio antes de recibir un pago. |
| `payout` | Quieres mostrar el tipo de cambio antes de enviar un pago. |
| `CurrencyExchange` | Deseas mostrar el tipo de cambio antes de enviar una conversión de moneda. |

### Autenticación

Incluye tu token de acceso en los encabezados de la solicitud:

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

### Parámetros clave de la solicitud

| Parámetro | Tipo | Descripción |
| - | - | - |
| `sourceCurrency` | string | Moneda desde la que deseas convertir (por ejemplo, `"ARS"`, `"USDT"`) |
| `quoteCurrency` | string | Moneda a la que deseas convertir (por ejemplo, `"USD"`) |
| `accountNumber` | string | Tu cuenta de Localpayment que contiene la **moneda de origen** (la cuenta que se está debitando). |
| `quoteAccountNumber` | string | Tu cuenta de Localpayment que contiene la **moneda de destino** (la cuenta que recibirá el abono). |

### Ejemplo de solicitud

> [tab] Moneda 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] Moneda estable (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'
> ```

***

## Gestión de respuestas

### Respuesta de éxito

Una solicitud exitosa devuelve información sobre el tipo de cambio con un token seguro:

> [tab] Moneda local (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] Moneda estable (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 respuesta clave

| Campo | Tipo | Descripción |
| - | - | - |
| `exchangeRateToken` | string | Token único para usar en transacciones posteriores |
| `transactionType` | string | Tipo de transacción (PayIn, PayOut) |
| `accountNumber` | string | Cuenta en moneda de origen (la cuenta debitada) |
| `sourceCurrency` | string | Código de la moneda de origen |
| `creationDate` | datetime | Cuándo se creó la cotización |
| `expirationDate` | datetime | Cuando expire la cotización |
| `quotes` | array | Métodos de pago disponibles y sus tarifas |

### Respuestas de error

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

***

## Mejores prácticas

### Seguridad y rendimiento

* Utiliza siempre HTTPS para las solicitudes a la API.
* Guarda los tokens de acceso de forma segura y rótalos periódicamente.
* Supervisa atentamente los tiempos de vencimiento de los tokens.
* Almacena en caché las cotizaciones adecuadamente, pero respeta las fechas de vencimiento.

### Importante: Caducidad del token

Los tokens de tipo de cambio tienen una vigencia limitada. Planifica tu flujo de trabajo para que se complete dentro del plazo de vencimiento. El tipo de cambio cotizado solo está garantizado mientras el token sea válido.

> [!NOTE]
>
> **Consejo profesional**
>
> Diferentes métodos de pago pueden ofrecer distintos tipos de cambio. Revisa todas las opciones disponibles en el arreglo `quotes` para seleccionar el tipo de cambio más favorable para tu caso de uso.

***

## Flujo de trabajo de integración

1. **Obtén una cotización**: Solicita las tasas de cambio para el par de divisas que desees.
2. **Selecciona el método**: Elige el método de pago óptimo entre las opciones disponibles.
3. **Almacena el token**: Guarda el `exchangeRateToken` para tu transacción.
4. **Ejecutar transacción**: Utiliza el token en tu llamada a la API de pago.
5. **Supervisa el vencimiento**: Completa la transacción antes de `expirationDate`.

***

## Próximos pasos

> [card] [Procesamiento de Payins](https://docs.localpayment.com/es/reference/payins.md)
>
> Procesa los pagos utilizando tu moneda convertida.

> [card] [Procesamiento de Payouts](https://docs.localpayment.com/es/reference/create-a-payout.md)
>
> Procesa los pagos utilizando tu moneda convertida.

> [card] [Ejecutar cambio de divisas](https://docs.localpayment.com/es/reference/exchange-bulk.md)
>
> Utiliza tu token de tipo de cambio para realizar la conversión de divisas.

> [!NOTE]
>
> **Consejo profesional**
>
> Prueba tu flujo de trabajo exhaustivamente en nuestro entorno de pruebas. Esto garantiza que tu integración gestione correctamente las fluctuaciones de tarifas, la caducidad de los tokens y los escenarios de error antes de tu lanzamiento.

***

> [!NOTE]
>
> **¿Necesitas ayuda?**
>
> Ponte en contacto con nuestro [equipo de soporte](mailto:support@localpayment.com) si experimentas algún problema o necesitas ayuda con la integración.


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