Cambio de divisas (FX)

La función de cambio de divisas permite a los comercios internacionales recibir fondos en moneda local y convertir esos fondos a USD en la plataforma de ProntoPaga.

¿Cómo funciona?

A continuación, te mostramos el flujo de cambio de divisas en una transacción.

1. Cotiza FX. El comercio inicia una cotización de FX a través de la API.
2. Confirma la orden de compra FX. El comercio confirma la orden de compra.
3. Respuesta de orden de compra FX. ProntoPaga confirma la tasa y ejecuta la compra.

Solicita una cotización FX

Este endpoint te permite solicitar una cotización FX, indicando el sentido de fijación del monto (fixedSide) y los datos mínimos para cotizar un cambio entre una moneda origen y una moneda destino.

Para hacer una llamada al endpoint debes autenticarte mediante un access token. La respuesta te devuelve la cotización, incluyendo el identificador de la cotización (quoteId), la tasa final y la vigencia de la cotización, para que decidas si confirmas o no la operación FX dentro del tiempo permitido.

Body de la solicitud

El siguiente JSON muestra una solicitud de compra de divisas:

{
  "fixedSide": "buy",
  "source": {
    "accountNumber": "987654321",
    "amount": 1000,
    "currency": "PEN"
  },
  "target": {
    "accountNumber": "9876543201",
    "amount": 295,
    "currency": "USD"
  }
}

El siguiente JSON muestra una solicitud de venta de divisas:

{
  "fixedSide": "sell",
  "source": {
    "accountNumber": "987654321",
    "amount": 1000,
    "currency": "PEN"
  },
  "target": {
    "accountNumber": "9876543201",
    "amount": 295,
    "currency": "USD"
  }
}

Respuesta

A continuación, se muestra la respuesta que puede derivarse de una solicitud de cotización:

{
  "fixedSide": "buy",
  "quoteId": "q_20261234_001",
  "rate": 3,
  "source": {
    "accountNumber": "987654321",
    "amount": 1000,
    "currency": "PEN"
  },
  "target": {
    "accountNumber": "9876543201",
    "amount": 295,
    "currency": "USD"
  },
  "validForSeconds": 60,
  "validUntil": "2026-05-01T10:21:34-05:00"
}

📘

Ten en cuenta que

El quoteId generado podrá ser posteriormente referenciado por una orden FX.

🚧

Tiempo de respuesta

El campo validForSeconds debe devolver inicialmente el valor 60 segundos.

Códigos de respuestas

A continuación te mostramos los códigos de respuesta derivados del endpoint de Solicita una cotización FX:

Cierre de cotización

Este endpoint te permite, como cliente de Virtual Accounts + FX, confirmar una operación FX previamente cotizada, enviando una referencia única de transacción y el quoteId vigente.

Para hacer una llamada a este endpoint debes autenticarte mediante un accessToken.

Body de la solicitud

El siguiente JSON muestra un ejemplo de solicitud de orden de compra.

{
  "quoteId": "q_20261234_001",
  "referenceId": "1234567898765432"
}

Respuesta

El siguiente JSON muestra una respuesta exitosa a la solicitud de orden de compra.

{
  "fixedSide": "buy",
  "orderId": "ord_20261234_0001",
  "quoteId": "q_20260123_001",
  "rate": 3,
  "referenceId": "1234567898765432",
  "source": {
    "accountNumber": "987654321",
    "amount": 1000,
    "currency": "PEN"
  },
  "status": "SUCCESS",
  "target": {
    "accountNumber": "9876543201",
    "amount": 295,
    "currency": "USD"
  },
  "valueDate": "2026-05-01T10:21:34-05:00"
}

🚧

Parámetro quoteId

Si el quoteId expiró o no es válido, se rechaza la operación y se debe cotizar nuevamente.

Códigos de respuesta

A continuación te mostramos los códigos de respuesta derivados del endpoint de Cierre de cotización FX.

Estados

Estos son los posibles estados derivados del endpoint de Cierre de cotización FX.

Detalles de un cierre

Este endpoint permite consultar el estado actual y detalle de una orden FX ya registrada, usando el parámetro orderId. Para hacer una llamada a este endpoint debes autenticarte mediante un accessToken.

Respuesta

El JSON a continuación, muestra un ejemplo de respuesta del endpoint:

{
  "createdTime": "T10:21:34-05:00",
  "fixedSide": "buy",
  "message": "FX trade completed and settled",
  "orderId": "ord_20260501_0001",
  "quoteId": "q_20260323_001",
  "rate": 3,
  "referenceId": "TRX202605010001",
  "sourceAmount": 1000,
  "sourceCurrency": "PEN",
  "status": "processing",
  "targetAmount": 295,
  "targetCurrency": "USD"
}

Detalles de un cierre por referenceId

Este endpoint permite consultar el estado actual y detalle de una orden FX ya registrada, usando el parámetro referenceId. Para hacer una llamada a este endpoint debes autenticarte mediante un accessToken.

Respuesta

El JSON a continuación, muestra un ejemplo de respuesta del endpoint:

{
  "createdTime": "T10:21:34-05:00",
  "fixedSide": "buy",
  "message": "FX trade completed and settled",
  "orderId": "ord_20260501_0001",
  "quoteId": "q_20260323_001",
  "rate": 3,
  "referenceId": "TRX202605010001",
  "sourceAmount": 1000,
  "sourceCurrency": "PEN",
  "status": "processing",
  "targetAmount": 295,
  "targetCurrency": "USD"
}