Crear Solicitud de Pago

Crea una nueva Solicitud de Pago para recibir pagos.

Endpoint

POST /v1/payment-links

Autenticación

Requiere API Key con el ability payment_links:create.

Cuerpo de la Solicitud

{
  "amount": 100.0,
  "currency": "COP",
  "description": "Factura #1234 - Suscripción mensual",
  "amount_type": "receive",
  "customer_paid_fee": false,
  "webhook_url": "https://tu-servidor.com/webhooks/orden/1234",
  "success_url": "https://tu-servidor.com/pago-exitoso"
}

Parámetros

Parámetro	Tipo	Requerido	Descripción
amount	number	Sí	Monto del pago (mínimo 1). La moneda depende de amount_type — ver abajo
currency	string	Sí	Moneda del comprador. Valores: ARS, BRL, COP, CLP, MXN, BOB, USD — USD funciona distinto, ver Pagos en USD
description	string	Sí	Descripción del pago (máximo 255 caracteres)
amount_type	string	No	Interpretación del monto. Valores: receive (default), charge
customer_paid_fee	boolean	No	Si es true, la comisión se suma al monto que paga el comprador. Default: false
source	string	No	Origen de la solicitud. Valores: integration (default), embedded_checkout, woocommerce
close_on_complete	boolean	No	Si es true, el checkout se cierra automáticamente al completar el pago. Default: false
webhook_url	string	No	URL para recibir notificaciones de esta solicitud (máximo 500 caracteres)
success_url	string	No	URL de redirección después de completar el pago exitosamente (máximo 500 caracteres)

Monto y comisión

Dos parámetros determinan cuánto paga el comprador y cuánto recibes tú. Conviene leerlos juntos, porque el resultado depende de la combinación:

• amount_type define en qué moneda está expresado amount y quién absorbe el riesgo cambiario.
• customer_paid_fee define quién paga la comisión de la transacción.

En qué moneda va amount

Valor	amount se expresa en	Riesgo cambiario
receive (default)	La moneda de tu wallet	Lo absorbe la plataforma. El comprador paga el equivalente en su moneda local
charge	La moneda del comprador (currency)	El comprador paga exactamente el monto que indicaste

Moneda del wallet

La moneda del wallet (donde se reciben los fondos) se determina automáticamente desde el wallet virtual configurado en tu cuenta. Con amount_type: "receive", amount se interpreta en esa moneda, no en la que envías en currency.

Con una sola moneda, amount_type no hace nada

amount_type solo cambia algo cuando la moneda del comprador y la de tu wallet son distintas — es decir, cuando hay conversión de por medio. Si coinciden, receive y charge producen exactamente el mismo cobro, porque amount ya está en la única moneda que interviene y no hay riesgo cambiario que asignar.

Esto incluye siempre a currency: "USD", que se cobra y se liquida en USD. En ese caso quien decide cuánto paga el comprador es customer_paid_fee, no amount_type.

Quién paga la comisión

Valor	Descripción
false (default)	La comisión la absorbe el comercio: se descuenta de los fondos que recibes
true	La comisión se suma al monto que paga el comprador

Requiere activación en tu cuenta

customer_paid_fee: true solo tiene efecto si la funcionalidad está habilitada en tu cuenta. Si no lo está, el API acepta el parámetro, responde 201 y la comisión la absorbe el comercio de todos modos — sin error, sin advertencia y sin ningún campo en la respuesta que lo indique.

Confirma con tu contacto de Aloha que la funcionalidad esté activa antes de depender de este flag en producción.

Combinaciones

Esta tabla describe el caso con conversión, que es donde amount_type decide algo. Si el comprador paga en la misma moneda de tu wallet — siempre con currency: "USD" — solo aplican las dos filas de customer_paid_fee, y “equivalente a amount” es simplemente amount.

amount_type	customer_paid_fee	Paga el comprador	Recibes tú
receive	false (default)	Equivalente a amount en su moneda local	amount − comisión
receive	true	Equivalente a amount + comisión	amount completo
charge	false (default)	amount exacto	Equivalente a amount − comisión
charge	true	amount + comisión	Equivalente a amount

Para recibir un neto exacto necesitas customer_paid_fee en true

amount_type: "receive" no garantiza que recibas el amount completo. Lo que garantiza es que amount esté denominado en la moneda de tu wallet y que el riesgo cambiario lo absorba la plataforma — la comisión se sigue descontando.

El único modo de recibir el monto íntegro es customer_paid_fee: true.

Ejemplos de uso

Los cuatro ejemplos asumen un wallet en CLP y un comprador que paga en COP.

1. receive con el default (customer_paid_fee: false):

{
  "amount": 100,
  "currency": "COP",
  "description": "Reserva de hotel",
  "amount_type": "receive"
}

→ El comprador paga el equivalente a 100 CLP en COP (~150,000 COP). Tú recibes 100 CLP menos la comisión.

2. receive con customer_paid_fee: true:

{
  "amount": 100,
  "currency": "COP",
  "description": "Reserva de hotel",
  "amount_type": "receive",
  "customer_paid_fee": true
}

→ El comprador paga ~150,000 COP más la comisión. Tú recibes los 100 CLP completos.

3. charge con el default (customer_paid_fee: false):

{
  "amount": 150000,
  "currency": "COP",
  "description": "Reserva de hotel",
  "amount_type": "charge"
}

→ El comprador paga exactamente 150,000 COP. Tú recibes el equivalente (~100 CLP) menos la comisión.

4. charge con customer_paid_fee: true:

{
  "amount": 150000,
  "currency": "COP",
  "description": "Reserva de hotel",
  "amount_type": "charge",
  "customer_paid_fee": true
}

→ Si la comisión es de 3,000 COP, el comprador paga 153,000 COP. Tú recibes el equivalente a 150,000 COP.

El monto cobrado excede el monto enviado

Al combinar amount_type: "charge" con customer_paid_fee: true, el comprador paga más que el amount que enviaste, porque la comisión se suma por encima. Si necesitas que el comprador vea un monto exacto, usa customer_paid_fee: false.

Pagos en USD

currency: "USD" cobra por débito bancario en Estados Unidos, no por los métodos locales del resto de monedas. El cuerpo de la solicitud es el mismo — no hay ningún campo nuevo:

{
  "amount": 100,
  "currency": "USD",
  "description": "Invoice #1234"
}

La moneda del wallet la determina currency: pidiendo USD, los fondos se liquidan en tu USD Bank Account. No tienes que elegir proveedor ni wallet en ningún momento.

Requiere activación en tu cuenta

Los pagos en USD requieren una habilitación previa. Si tu cuenta no la tiene, la solicitud responde 422 USD_ACCOUNT_NOT_ENABLED y no se crea nada:

{
  "success": false,
  "code": "USD_ACCOUNT_NOT_ENABLED",
  "message": "USD payment links are not enabled for this account."
}

Es el mismo error tanto si nunca activaste los pagos en USD como si la activación está a medio camino. Habla con tu contacto de Aloha: no se resuelve desde el API.

El ciclo es distinto: no es inmediato

Un débito bancario tarda días hábiles en liquidarse. Eso cambia dos cosas que probablemente ya tengas implementadas para las monedas locales:

	Monedas locales	USD
Estados posibles	active → completed	active → in_transit → completed, y returned
Cuándo llega payment.completed	Al momento de pagar	Al liquidar el débito, días después

• in_transit significa que el comprador ya autorizó el cobro y el débito está en camino. No es un fallo ni un pago confirmado: aún no hay dinero acreditado.
• returned significa que el banco del comprador revirtió el débito después de haberse liquidado. Es el único estado en el que un pago que ya diste por bueno deja de serlo.

returned no tiene webhook: solo se detecta consultando

No existe un evento de webhook para la reversión. Ya recibiste payment.completed cuando el débito liquidó, y esa notificación no se desdice sola. La única forma de enterarte es consultar GET /v1/payment-links/{id} y ver status: "returned".

Si liberas mercancía o servicio automáticamente al recibir payment.completed, vale la pena volver a consultar el estado de las solicitudes en USD durante unos días antes de dar la venta por cerrada.

Revisa cómo interpreta tu integración los estados que no conoce

Si tu código trata cualquier estado distinto de completed como un fallo, un pago en USD perfectamente sano se leerá como rechazado durante los días que pasa en in_transit. Trata los estados desconocidos como “todavía no resuelto”, nunca como error.

Webhook URL

El campo webhook_url te permite recibir notificaciones específicas para esta solicitud de pago. Si también tienes un webhook global configurado, recibirás la notificación en ambos endpoints. Consulta la documentación de webhooks para más detalles.

Success URL

El campo success_url te permite definir una URL de redirección personalizada. Una vez que el cliente complete el pago exitosamente, el checkout redirigirá automáticamente al cliente a la URL especificada después de 20 segundos. Además, el botón “Volver al inicio” estará disponible para que el cliente pueda redirigirse de forma manual en cualquier momento. Si no se proporciona, el botón redirigirá al sitio web configurado en el merchant.

Ejemplo de Solicitud

cURL

curl -X POST "https://api.aloha.co/api/external/v1/payment-links" \
  -H "X-API-KEY: tu_api_key_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 100.00,
    "currency": "COP",
    "description": "Factura #1234 - Suscripción mensual",
    "amount_type": "receive",
    "success_url": "https://tu-servidor.com/pago-exitoso"
  }'

JavaScript

const response = await fetch(
  'https://api.aloha.co/api/external/v1/payment-links',
  {
    method: 'POST',
    headers: {
      'X-API-KEY': 'tu_api_key_aqui',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      amount: 100.00,
      currency: 'COP',
      description: 'Factura #1234 - Suscripción mensual',
      amount_type: 'receive',
      success_url: 'https://tu-servidor.com/pago-exitoso'
    })
  }
);
const data = await response.json();

console.log('Payment Link URL:', data.data.url);

Python

import requests

headers = {
    'X-API-KEY': 'tu_api_key_aqui',
    'Content-Type': 'application/json'
}

payload = {
    'amount': 100.00,
    'currency': 'COP',
    'description': 'Factura #1234 - Suscripción mensual',
    'amount_type': 'receive',
    'success_url': 'https://tu-servidor.com/pago-exitoso'
}

response = requests.post(
    'https://api.aloha.co/api/external/v1/payment-links',
    headers=headers,
    json=payload
)
data = response.json()

print('Payment Link URL:', data['data']['url'])

PHP

<?php
$ch = curl_init();

$payload = json_encode([
    'amount' => 100.00,
    'currency' => 'COP',
    'description' => 'Factura #1234 - Suscripción mensual',
    'amount_type' => 'receive',
    'success_url' => 'https://tu-servidor.com/pago-exitoso'
]);

curl_setopt_array($ch, [
    CURLOPT_URL => 'https://api.aloha.co/api/external/v1/payment-links',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => $payload,
    CURLOPT_HTTPHEADER => [
        'X-API-KEY: tu_api_key_aqui',
        'Content-Type: application/json'
    ]
]);

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

echo 'Payment Link URL: ' . $data['data']['url'];

Respuesta Exitosa (201 Created)

{
  "success": true,
  "message": "Payment link created successfully",
  "data": {
    "id": "9d8f7a6b-5c4d-3e2f-1a0b-9c8d7e6f5a4b",
    "url": "https://checkout.aloha.co/s/9d8f7a6b-5c4d-3e2f-1a0b-9c8d7e6f5a4b",
    "expires_at": "2025-12-10T10:30:00.000000Z"
  }
}

Campos de Respuesta

Campo	Tipo	Descripción
id	string (UUID)	Identificador único de la Solicitud de Pago
url	string	URL del checkout para compartir con el cliente
expires_at	string	Fecha de expiración (ISO 8601)

Errores Posibles

Error de Validación (422)

{
  "success": false,
  "code": "VALIDATION_FAILED",
  "message": "Validation failed",
  "errors": {
    "amount": ["The amount field is required."],
    "currency": ["The currency must be 3 characters."],
    "description": ["The description field is required."]
  }
}

API Key Inválida (401)

{
  "success": false,
  "code": "INVALID_API_KEY",
  "message": "Invalid API key configuration"
}

Wallet No Encontrado (422)

{
  "success": false,
  "code": "WALLET_NOT_FOUND",
  "message": "No virtual wallet configured for this account"
}

Pagos en USD No Habilitados (422)

{
  "success": false,
  "code": "USD_ACCOUNT_NOT_ENABLED",
  "message": "USD payment links are not enabled for this account."
}

Tabla de Errores

Código HTTP	Código de Error	Descripción
401	INVALID_API_KEY	API Key inválida o expirada
401	missing_api_key	No se proporcionó API Key
403	insufficient_scope	La API Key no tiene el ability payment_links:create
422	VALIDATION_FAILED	Error de validación en los parámetros
422	WALLET_NOT_FOUND	No hay wallet virtual configurado
422	USD_ACCOUNT_NOT_ENABLED	Se pidió currency: "USD" y la cuenta no tiene los pagos en USD habilitados

Guarda el ID

Almacena el id de la solicitud de pago en tu sistema para poder consultarla o cancelarla posteriormente.