Cotizar Conversión

Obtén una cotización de conversión en tiempo real: cuánto paga el cliente frente a cuánto recibes tú, junto con la tasa de Aloha aplicable, antes de crear una solicitud de pago.

Endpoint

POST /v1/conversions/quote

Autenticación

Envía tu API Key en cada solicitud (igual que en los demás endpoints externos). Cualquier API Key válida de tu cuenta funciona; no se requiere ningún ability especial. Usa una de:

Authorization: Bearer <API_KEY> (recomendado)
X-API-KEY: <API_KEY>

Cuerpo de la Solicitud

{
  "amount": 100,
  "source": "CLP",
  "destination": "USD",
  "amount_type": "receive"
}

Parámetros

Parámetro	Tipo	Requerido	Descripción
`amount`	number	Sí	El monto a cotizar (≥ 1). Su moneda depende de `amount_type` — ver Direcciones.
`source`	string	Sí	La moneda del cliente (en la que paga). Una de: `ARS`, `BRL`, `COP`, `CLP`, `MXN`.
`destination`	string	Sí	La moneda de tu billetera (la que recibes), por ejemplo `USD`.
`amount_type`	string	No	`receive` (predeterminado) o `charge`. Determina a qué lado se refiere `amount`.

Direcciones (`amount_type`)

El endpoint es bidireccional. Ambos modos devuelven la misma sell_rate y el mismo par de montos — solo cambia el valor que fijas.

receive (predeterminado) — fijas lo que quieres recibir (amount está en destination). La respuesta te indica source_amount: cuánto debe pagar el cliente.

“Quiero recibir 100 USD — ¿cuántos CLP envía el cliente?”
charge — fijas lo que se cobra al cliente (amount está en source). La respuesta te indica destination_amount: cuánto recibes.

“El cliente enviará 100.000 CLP — ¿cuántos USD recibo?”

Ejemplo de Solicitud

Recibir — solicitas 100 USD, el cliente paga en CLP:

curl -X POST "https://api.alohapay.co/api/external/v1/conversions/quote" \
  -H "Authorization: Bearer tu_api_key_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 100,
    "source": "CLP",
    "destination": "USD",
    "amount_type": "receive"
  }'

const response = await fetch(
  'https://api.alohapay.co/api/external/v1/conversions/quote',
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer tu_api_key_aqui',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      amount: 100,
      source: 'CLP',
      destination: 'USD',
      amount_type: 'receive'
    })
  }
);
const data = await response.json();

console.log('El cliente paga:', data.data.source_amount, data.data.source);

import requests

headers = {
    'Authorization': 'Bearer tu_api_key_aqui',
    'Content-Type': 'application/json'
}

payload = {
    'amount': 100,
    'source': 'CLP',
    'destination': 'USD',
    'amount_type': 'receive'
}

response = requests.post(
    'https://api.alohapay.co/api/external/v1/conversions/quote',
    headers=headers,
    json=payload
)
data = response.json()

print('El cliente paga:', data['data']['source_amount'], data['data']['source'])

<?php
$ch = curl_init();

$payload = json_encode([
    'amount' => 100,
    'source' => 'CLP',
    'destination' => 'USD',
    'amount_type' => 'receive'
]);

curl_setopt_array($ch, [
    CURLOPT_URL => 'https://api.alohapay.co/api/external/v1/conversions/quote',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => $payload,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer tu_api_key_aqui',
        'Content-Type: application/json'
    ]
]);

$response = curl_exec($ch);
$data = json_decode($response, true);

echo 'El cliente paga: ' . $data['data']['source_amount'] . ' ' . $data['data']['source'];

Cobrar — el cliente envía 100.000 CLP, tú recibes USD:

curl -X POST "https://api.alohapay.co/api/external/v1/conversions/quote" \
  -H "Authorization: Bearer tu_api_key_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 100000,
    "source": "CLP",
    "destination": "USD",
    "amount_type": "charge"
  }'

→ destination_amount es el monto en USD que recibes.

Respuesta Exitosa (200 OK)

{
  "success": true,
  "message": "Conversion quote calculated successfully",
  "data": {
    "source": "CLP",
    "destination": "USD",
    "amount_type": "receive",
    "source_amount": 98076,
    "destination_amount": 100,
    "sell_rate": 0.001019617,
    "rate_label": "1 CLP = 0.001019617 USD"
  }
}

Campos de Respuesta

Campo	Tipo	Descripción
`source`	string	Moneda del cliente (en la que paga).
`destination`	string	Moneda de tu billetera (la que recibes).
`amount_type`	string	Dirección usada para la cotización: `receive` o `charge`.
`source_amount`	number	Lo que paga el cliente, en la moneda `source`.
`destination_amount`	number	Lo que recibes, en la moneda `destination`.
`sell_rate`	number	Tasa de Aloha, expresada como `destination` por unidad de `source`: `source_amount = amount ÷ sell_rate` y `destination_amount = source_amount × sell_rate`.
`rate_label`	string	Cadena lista para mostrar, por ejemplo `"1 CLP = 0.001019617 USD"`.

Errores Posibles

Error de Validación (422)

{
  "success": false,
  "code": "VALIDATION_FAILED",
  "message": "Validation failed",
  "errors": {
    "amount": ["The amount field is required."]
  }
}

Par de Monedas No Soportado (422)

{
  "success": false,
  "code": "INVALID_CURRENCY",
  "message": "The currency pair isn't supported for conversion"
}

Tasa No Disponible (500)

{
  "success": false,
  "code": "CONVERSION_QUOTE_ERROR",
  "message": "No rate currently available for the route"
}

Tabla de Errores

Código HTTP	Código de Error	Descripción
401	`missing_api_key`	No se proporcionó API Key.
401	`invalid_api_key`	La API Key es inválida o fue revocada.
422	`VALIDATION_FAILED`	Falta o es inválido `amount`, `source`, `destination` o `amount_type`.
422	`INVALID_CURRENCY`	El par de monedas no está soportado para conversión.
500	`CONVERSION_QUOTE_ERROR`	No hay tasa disponible para la ruta, o un error en el proveedor.