Contexto
Históricamente, cuando los negocios se expandían internacionalmente, mostraban a sus clientes la misma divisa en todas partes, normalmente dólares estadounidenses o, a veces, euros. Los clientes en países con divisas distintas pagaban en USD/EUR y luego soportaban una comisión adicional de conversión por parte de su banco. Esto impacta en la conversión, ya que muchos clientes no saben con exactitud cuánto se les cobrará una vez añadidas esas comisiones.
Plataformas como Stripe permiten ofrecer al cliente precios en su divisa local y convertirlos después a la divisa con la que operamos. Los términos técnicos son presentment currency (en la que paga el cliente) y settlement currency (la que finalmente recibimos). Stripe convierte normalmente entre ambas de forma automática usando tipos mid-market más un pequeño margen.
El reto que esto plantea es saber con exactitud cuánto dinero recibiremos en nuestra divisa "de casa". Los tipos de cambio fluctúan continuamente, así que aunque podamos estimar la conversión, lo más probable es que acabemos con problemas contables por sobre o subestimar el importe que finalmente aterriza en la cuenta bancaria.
La FX Quotes API de Stripe está diseñada para eliminar esa incertidumbre.
Qué es la FX Quotes API
En su forma más sencilla, la API permite solicitar una cotización para convertir de una divisa a otra. Los tipos devueltos están garantizados durante un periodo de tiempo determinado. Podemos asociar esa cotización a un PaymentIntent, a un Transfer o a otro objeto compatible, y Stripe garantiza que la conversión se hará a ese tipo mientras la cotización siga activa.
Es un cambio deliberado de "convertiremos al tipo que haya en el momento del settlement" a "este es el tipo que vamos a usar, punto". Esa previsibilidad es la principal propuesta de valor.
Por qué es útil
Cualquiera que trabaje entre divisas acaba descubriendo lo escurridizos que pueden ser los tipos de cambio. Pequeños movimientos pueden generar ruido en la conciliación, erosionar márgenes o hacer que las transferencias aterricen ligeramente desviadas del importe previsto. Imagine que estima un precio de conversión para un cliente en 94,29 € hoy, pero el tipo se mueve antes del cobro y se le carga 96,02 €. O imagine una connected account que espera 20 € pero recibe 19,85 € tras el settlement. Cada caso parece pequeño por separado, pero a escala genera carga de soporte y fricción de conciliación.
Es un dolor a veces tolerable cuando se trata de convertir nuestros propios ingresos. Lo es mucho menos cuando:
- queremos mostrar al cliente un precio final en su divisa local, o
- operamos una plataforma en la que las connected accounts esperan recibir importes exactos, no aproximados.
La FX Quotes API ofrece una base predecible. En lugar de cruzar los dedos para que la conversión salga bien, sabemos exactamente cómo la gestionará Stripe.
Una nota sobre la direccionalidad
Un detalle importante que despista a mucha gente al empezar con esta API: la conversión de divisas no es simétrica. Si una cotización indica que 2 GBP se convierten en 1 EUR, no podemos invertirla y suponer que 1 EUR equivale a 2 GBP en sentido contrario. El FX real tiene tipos de compra y de venta, y la API de Stripe lo refleja.
Si necesitamos los dos sentidos, pedimos dos cotizaciones. O, más sencillo, solicitemos siempre la cotización en la dirección en la que pensamos usarla.
Ejemplo básico: usar FX Quotes con un PaymentIntent
Una tarea habitual al expandirse internacionalmente es mostrar un precio en la divisa local del cliente, aunque nuestra cuenta de Stripe trabaje por defecto con otra. Supongamos que operamos en GBP pero queremos fijar precios en euros.
Paso 1: solicitar una cotización
curl https://api.stripe.com/v1/fx_quotes \
-u "sk_test_123:" \
-H "Stripe-Version: 2025-08-27.basil; fx_quote_preview=v1" \
-d "to_currency"=gbp \
-d "from_currencies[]"=eur \
-d "lock_duration"=dayEn escenarios de pago, to_currency suele ser la settlement currency de la cuenta de Stripe, mientras que from_currencies[] contiene las divisas en las que pagan los clientes. Tras hacer la petición, recibimos una respuesta con un tipo de conversión bloqueado y el ID de la cotización (fxq_xxxxxx).
{
"id": "fxq_xxx",
"object": "fx_quote",
"lock_duration": "day",
"lock_status": "active",
"rates": {
"eur": {
"exchange_rate": 0.853682,
"rate_details": {
"base_rate": 0.872885,
"duration_premium": 0.002,
"fx_fee_rate": 0.02
}
}
},
"to_currency": "gbp",
"usage": { "type": "payment" }
}El parámetro exchange_rate incluye la comisión de Stripe por proporcionar el FX, mientras que base_rate la excluye. Si queremos que el cliente asuma el coste íntegro de la conversión, dividimos nuestro precio objetivo (100 £) por exchange_rate (0,853682) y le cobraremos 117,14 €. Si nosotros, como negocio, absorbemos el coste del FX, dividimos por base_rate (0,872885) y cobraremos 114,56 €.
| Caso de uso | Valor a usar |
|---|---|
| El cliente asume la comisión de FX de Stripe | exchange_rate |
| Nuestro negocio absorbe la comisión de FX | base_rate |
Paso 2: asociar la cotización a un PaymentIntent
curl https://api.stripe.com/v1/payment_intents \
-u "sk_test_123:" \
-H "Stripe-Version: 2025-08-27.basil; fx_quote_preview=v1" \
-d "amount"=11714 \
-d "currency"=eur \
-d "fx_quote"=fxq_xxxxxxEl PaymentIntent que se le presenta al cliente final por 117,14 € aterrizará, una vez pagado, como 100 £ en nuestra cuenta de Stripe. Hemos eliminado cualquier incertidumbre tanto sobre lo que se cobrará al cliente como sobre lo que recibiremos.
Usar FX Quotes con Stripe Connect
Cuando se trabaja entre fronteras de divisa con Stripe Connect, los desajustes de divisa pueden volverse especialmente dolorosos. Las plataformas pueden operar en una divisa mientras las connected accounts lo hacen en otra, y pequeños movimientos de FX pueden generar mucho ruido operativo.
Hay dos escenarios habituales de FX cuando se usa Connect:
- Application fees: cobramos al cliente final en una divisa, pero la comisión de la plataforma debe recogerse en otra.
- Transferencias entre la plataforma y las connected accounts: puede que necesitemos enviar fondos a una connected account en su divisa local, aunque nuestro saldo esté en otra. La precisión es importante aquí: creadores, restaurantes y comerciantes esperan payouts exactos.
La mecánica para las application fees es la misma que vimos arriba para los PaymentIntents, así que no nos detendremos. El caso más interesante es el de las transferencias, donde la plataforma tiene que mover fondos de su propio saldo a una connected account cruzando divisas.
Ejemplo: garantizar que una connected account reciba exactamente 20 €
Imaginemos que somos una plataforma de delivery con una promoción del 20 % de descuento. Un cliente pide 100 € de comida y paga 80 € a nuestra plataforma. Esos 80 € se liquidan a la plataforma; los 20 € restantes que se le deben al restaurante hay que aportarlos desde el saldo de la propia plataforma. Si la plataforma opera en GBP y el restaurante en EUR, tenemos que transferir exactamente 20 € desde nuestro saldo en GBP.
Solicitar la cotización (en la dirección correcta)
curl https://api.stripe.com/v1/fx_quotes \
-u "sk_test_123:" \
-H "Stripe-Version: 2025-08-27.basil; fx_quote_preview=v1" \
-d to_currency=eur \
-d "from_currencies[]"=gbp \
-d lock_duration=five_minutes \
-d "usage[type]"=transfer \
-d "usage[transfer][destination]"="{{CONNECTED_ACCOUNT_ID}}"Como queremos que la connected account reciba el importe íntegro, la plataforma absorbe la comisión. Usamos base_rate en el cálculo. 20 € ÷ 1,14587 = 17,45 £.
Crear la transferencia usando esa cotización
curl https://api.stripe.com/v1/transfers \
-u "sk_test_123:" \
-H "Stripe-Version: 2025-08-27.basil; fx_quote_preview=v1" \
-d amount=1745 \
-d currency=gbp \
-d destination="{{CONNECTED_ACCOUNT_ID}}" \
-d fx_quote=fxq_xxxStripe deduce 17,45 £ del saldo de la plataforma y garantiza que la connected account reciba exactamente 20 €. Sin sorpresas en la conciliación, sin payouts correctores ni conjeturas.
¿Cuánto tiempo es válida una cotización?
Por defecto, la cotización devuelve el tipo de mercado actual. El parámetro lock_duration controla durante cuánto tiempo es válida: 5 minutos, una hora o un día. Hay duraciones mayores disponibles bajo petición y sujetas a aprobación de Stripe. Stripe cobra una comisión mayor por reservar la cotización: el campo duration_premium incluye este cargo.
La cotización puede expirar incluso dentro de ese plazo. Una cotización extendida para pagos tiene un umbral del 3,5 % y la de transferencias un umbral del 1 %. Si el tipo se mueve fuera del umbral, la cotización se invalida y lock_status pasa a expired. En ese momento se dispara el webhook fx_quote.expired.
La previsibilidad gana a las conjeturas
La conversión de divisas es una de esas cosas que parecen sencillas y, sin embargo, introducen inconsistencias allá donde aparecen. La FX Quotes API de Stripe aporta un nivel muy bienvenido de previsibilidad. En lugar de tratar el FX como un objetivo móvil, lo tratamos como un valor conocido: una cotización con límites, una expiración y un resultado garantizado.
Si fija precios en varias divisas, liquida entre divisas o gestiona una plataforma en la que las transferencias tienen que ser exactas, la FX Quotes API le ofrece una estructura mucho más fiable que confiar en el tipo del momento del cobro.
