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.

1. ¿Cómo funciona?

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

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

2. 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 AccessToken.

La respuesta te devuelve la cotización, incluyendo el identificador del quote (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.

2.1. Body request

El siguiente JSON muestra una solicitud de compra de divisas.

{
  "referenceId": "12334567890",
  "fixedSide": "buy",
  "source": {
    "currency": "PEN",
    "accountNumber": "1276543",
    "amount": 
  },
  "target": {
    "currency": "USD",
    "accountNumber": "56473892",
    "amount":1000
  }
}

El siguiente JSON muestra una solicitud de venta de divisas.

{
  "referenceId": "12334567890",
  "fixedSide": "sell",
  "source": {
    "currency": "USD",
    "accountNumber": "1276543",
    "amount":100
  },
  "target": {
    "currency": "PEN",
    "accountNumber": "56473892",
    "amount":
  }
}

2.2. Response

Es la respuesta que puede derivarse de una solicitud de cotización.

{
  "fixedSide": "buy",
  "quoteId": "string",
  "rate": 0,
  "referenceId": "string",
  "source": {
    "accountNumber": "string",
    "amount": 0,
    "currency": "PEN"
  },
  "target": {
    "accountNumber": "string",
    "amount": 100,
    "currency": "USD"
  },
  "validForSeconds": 0,
  "validUntil": "string"
}

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

2.3. Códigos de respuestas

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

Código	Descripción
`200`	Operación realizada con éxito.
`400`	Bad Request: estructura inválida o request mal formado.
`401`	Unauthorized: operación no autorizada, token inválido o expirado.
`422`	Unprocessable Entity: parámetros inválidos o cotización no posible por reglas de negocio.
`500`	Internal Server Error: error interno durante la cotización.

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

3.1.Body request

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

{
  "externalReference":"TRX202605010123",
  "quoteId":"q_20261234_001"
}

3.2. Response

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

{
  "externalReference":"TRX202606010001",
  "orderId":"ord_20261234_0001",
  "quoteId":"q_20260123_001",
  "status":"SUCCESS",
  "message":"FX trade completed and settled",
  "fixedSide":"SELL",
  "sourceCurrency":"CLP",
  "sourceAmount":1000000,
  "targetCurrency":"USD",
  "targetAmount":1049.35,
  "rate":952.97,
  "valueDate":"2026-05-01T10:21:34-05:00",
  "statusInfo": {
    "code":"200",
    "description":"Operación realizada con éxito"
  }
}

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

3.3. Códigos de respuesta

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

Código	Descripción
`200`	Operación recibida/procesada correctamente a nivel API.
`400`	`Bad Request`: estructura inválida o request mal formado.
`401`	`Unauthorized`: operación no autorizada, token inválido o expirado.
`409`	`Conflict`: `externalReference` duplicada o `quoteId` ya utilizado.
`422`	`Unprocessable Entity`: `quoteId` expirado, inválido o no ejecutable.
`500`	`Internal Server Error`: error interno durante el cierre de la orden FX.

3.4. Estados

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

Estatus	Descripción
`processing`	La orden fue aceptada y está siendo procesada.
`pending_manual`	La orden requiere ejecución manual por backoffice/operador.
`success`	La operación FX fue ejecutada y finalizada exitosamente.
`fail`	La operación FX no pudo ejecutarse.

4. Obtén los 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.

4.1. Request/ Path

El siguiente JSON muestra un ejemplo de solicitud al endpoint de Consulta de orden FX.

/fx/orders/{orderId}

4.2. Response

El JSON a continuación, muestra un ejemplo de respuesta del endpoint de Consulta de orden FX.

{
  "orderId":"ord_20260501_0001",
  "externalReference":"TRX202605010001",
  "quoteId":"q_20260323_001",
  "status":"SUCCESS",
  "message":"FX trade completed and settled",
  "fixedSide":"SELL",
  "sourceCurrency":"PEN",
  "sourceAmount":1000000,
  "targetCurrency":"USD",
  "targetAmount":1049.35,
  "rate":952.97,
  "createdTime":"2026-05-01T10:21:34-05:00",
  "statusInfo": {
    "code":"200",
    "description":"Query completed successfully"
  }
}