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",
  "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
`currency`	string	Sí	Moneda del cliente. Valores: `ARS`, `BRL`, `COP`, `CLP`, `MXN`
`description`	string	Sí	Descripción del pago (máximo 255 caracteres)
`amount_type`	string	No	Interpretación del monto. Valores: `receive` (default), `charge`
`webhook_url`	string	No	URL para recibir notificaciones de esta solicitud de pago específica
`success_url`	string	No	URL de redirección después de completar el pago exitosamente

Parámetro `amount_type`

El parámetro amount_type determina cómo se interpreta el monto del pago:

Valor	Descripción
`receive`	El `amount` representa lo que recibirás en tu billetera. El cliente pagará el equivalente en su moneda local. (Default)
`charge`	El `amount` representa lo que cobrarás al cliente en su moneda local. Recibirás el equivalente en tu billetera.

Ejemplos de uso

1. Recibir monto fijo (amount_type: "receive"):

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

→ Recibirás exactamente 100 CLP. El cliente pagará el equivalente en COP (~150,000 COP aproximadamente).

2. Cobrar monto fijo al cliente (amount_type: "charge"):

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

→ El cliente pagará exactamente 150,000 COP. Recibirás el equivalente en CLP (~100 CLP aproximadamente).

Ejemplo de Solicitud

curl -X POST "https://api.alohapay.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"
  }'

const response = await fetch(
  'https://api.alohapay.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);

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.alohapay.co/api/external/v1/payment-links',
    headers=headers,
    json=payload
)
data = response.json()

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

<?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.alohapay.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.alohapay.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"
}

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