Crear Pago con Tarjeta

Crea un nuevo enlace de pago con tarjeta de crédito o débito.

Endpoint

POST /v1/cards/payment-links

Autenticación

Requiere API Key con el ability card_payment_links:create.

Cuerpo de la Solicitud

{
  "customer_name": "Juan Pérez",
  "customer_email": "juan@ejemplo.com",
  "amount": 100.50,
  "currency": "USD",
  "description": "Factura #1234 - Servicio mensual",
  "redirect_url": "https://tu-servidor.com/pago-exitoso?orderId=1234",
  "custom_message": "¡Gracias por tu pago!"
}

Parámetros

Parámetro	Tipo	Requerido	Descripción
customer_name	string	Sí	Nombre del cliente (máximo 255 caracteres)
customer_email	string	Sí	Email del cliente (formato válido, máximo 255 caracteres)
amount	number	Sí	Monto del pago (mínimo 0.50)
currency	string	Sí	Moneda del pago (3 caracteres). Ver monedas soportadas
description	string	No	Descripción del pago (máximo 500 caracteres)
redirect_url	string	No	URL de redirección después del pago exitoso (máximo 2000 caracteres)
custom_message	string	No	Mensaje personalizado en la página de confirmación (máximo 500 caracteres)

Conversión de Moneda

Si la moneda proporcionada no es USD, el sistema automáticamente convierte el monto a USD utilizando la tasa de cambio actual. La información de la conversión se incluye en la respuesta:

• amount_usd: Monto final en USD
• original_amount: Monto original proporcionado
• original_currency: Moneda original
• exchange_rate: Tasa de cambio aplicada (o null si la moneda es USD)

Comportamiento de redirección

Si proporcionas redirect_url, el cliente será redirigido automáticamente a esa URL después de completar el pago. Si no proporcionas redirect_url pero sí custom_message, se mostrará una página de confirmación con tu mensaje personalizado.

Ejemplo de Solicitud

cURL

curl -X POST "https://api.alohapay.co/api/external/v1/cards/payment-links" \
  -H "X-API-KEY: tu_api_key_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_name": "Juan Pérez",
    "customer_email": "juan@ejemplo.com",
    "amount": 100.50,
    "currency": "USD",
    "description": "Factura #1234 - Servicio mensual",
    "redirect_url": "https://tu-servidor.com/pago-exitoso?orderId=1234"
  }'

JavaScript

const response = await fetch(
  'https://api.alohapay.co/api/external/v1/cards/payment-links',
  {
    method: 'POST',
    headers: {
      'X-API-KEY': 'tu_api_key_aqui',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      customer_name: 'Juan Pérez',
      customer_email: 'juan@ejemplo.com',
      amount: 100.50,
      currency: 'USD',
      description: 'Factura #1234 - Servicio mensual',
      redirect_url: 'https://tu-servidor.com/pago-exitoso?orderId=1234'
    })
  }
);
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 = {
    'customer_name': 'Juan Pérez',
    'customer_email': 'juan@ejemplo.com',
    'amount': 100.50,
    'currency': 'USD',
    'description': 'Factura #1234 - Servicio mensual',
    'redirect_url': 'https://tu-servidor.com/pago-exitoso?orderId=1234'
}

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

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

PHP

<?php
$ch = curl_init();

$payload = json_encode([
    'customer_name' => 'Juan Pérez',
    'customer_email' => 'juan@ejemplo.com',
    'amount' => 100.50,
    'currency' => 'USD',
    'description' => 'Factura #1234 - Servicio mensual',
    'redirect_url' => 'https://tu-servidor.com/pago-exitoso?orderId=1234'
]);

curl_setopt_array($ch, [
    CURLOPT_URL => 'https://api.alohapay.co/api/external/v1/cards/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": "Card payment link created successfully",
  "data": {
    "id": "9d8f7a6b-5c4d-3e2f-1a0b-9c8d7e6f5a4b",
    "url": "https://checkout.alohapay.co/card/9d8f7a6b-5c4d-3e2f-1a0b-9c8d7e6f5a4b",
    "amount_usd": 100.50,
    "original_amount": 100.50,
    "original_currency": "USD",
    "exchange_rate": null,
    "status": "active",
    "created_at": "2026-03-23T10:30:45.000000Z"
  }
}

Ejemplo con conversión de moneda

{
  "success": true,
  "message": "Card payment link created successfully",
  "data": {
    "id": "9d8f7a6b-5c4d-3e2f-1a0b-9c8d7e6f5a4b",
    "url": "https://checkout.alohapay.co/card/9d8f7a6b-5c4d-3e2f-1a0b-9c8d7e6f5a4b",
    "amount_usd": 25.00,
    "original_amount": 100000,
    "original_currency": "COP",
    "exchange_rate": 4000.00,
    "status": "active",
    "created_at": "2026-03-23T10:30:45.000000Z"
  }
}

Campos de Respuesta

Campo	Tipo	Descripción
id	string (UUID)	Identificador único del pago con tarjeta
url	string	URL de checkout para compartir con el cliente
amount_usd	number	Monto final en USD
original_amount	number	Monto original proporcionado en la solicitud
original_currency	string	Moneda original de la solicitud
exchange_rate	number/null	Tasa de cambio aplicada (null si la moneda es USD)
status	string	Estado del enlace: active
created_at	string	Fecha de creación (ISO 8601)

Errores Posibles

Error de Validación (422)

{
  "success": false,
  "code": "VALIDATION_FAILED",
  "message": "Validation failed",
  "errors": {
    "customer_name": ["The customer name field is required."],
    "customer_email": ["The customer email must be a valid email address."],
    "amount": ["The amount must be at least 0.5."],
    "currency": ["The selected currency is invalid."]
  }
}

Pagos con Tarjeta No Habilitados (403)

{
  "success": false,
  "code": "CARD_PAYMENTS_NOT_ENABLED",
  "message": "Card payments are not enabled for this account"
}

Tasa de Cambio No Disponible (422)

{
  "success": false,
  "code": "EXCHANGE_RATE_UNAVAILABLE",
  "message": "Exchange rate not available for this currency"
}

API Key Inválida (401)

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

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 card_payment_links:create
403	CARD_PAYMENTS_NOT_ENABLED	Pagos con tarjeta no habilitados en la cuenta
404	USER_NOT_FOUND	Usuario asociado a la API Key no encontrado
422	VALIDATION_FAILED	Error de validación en los parámetros
422	EXCHANGE_RATE_UNAVAILABLE	Tasa de cambio no disponible para la moneda
429	RATE_LIMIT_EXCEEDED	Límite de solicitudes excedido
500	CARD_PAYMENT_ERROR	Error interno al procesar el pago con tarjeta

Guarda el ID

Almacena el id del pago con tarjeta en tu sistema para poder consultarlo o cancelarlo posteriormente.

Webhook de notificación

Si tienes webhooks configurados, recibirás una notificación automática cuando el pago sea completado o cancelado.