Pay by Link

¡Envía a tus clientes un enlace único por email, WhatsApp o SMS para que paguen en línea con un solo clic!

Resumen

Esta guía cubre la integración con la API de Pay by Link: crear enlaces de pago de forma programática y procesar el resultado mediante webhooks.

Para crear y enviar enlaces de pago desde el MONEI Dashboard sin escribir código, consulta Pay by Link en la sección de Pagos. ¿No tienes claro si un enlace de un solo uso es la herramienta adecuada? Compara todas las opciones de QR y enlaces en códigos QR y enlaces de pago.

Pay by Link genera una URL única para un importe de pago específico que dirige al cliente a una página de pago segura alojada por MONEI.

Integración con la API

La siguiente sección explica el flujo de API (implementación en el servidor).

Antes de empezar (API)

Necesitarás una cuenta MONEI y tus claves de API (de prueba o de producción). Encuéntralas en tu MONEI Dashboard.
Usa tus claves en modo de prueba para las pruebas de integración.
Asegúrate de que los métodos de pago relevantes estén habilitados en los ajustes de tu cuenta para la página alojada.
Puedes monitorizar los pagos de prueba en tu MONEI Dashboard → Pagos (asegúrate de que el Modo de prueba esté activo).

Tu clave API está en MONEI Dashboard → Configuración → Acceso a API:

Página Acceso a API en los ajustes del panel de MONEI, con tu ID de cuenta y tu clave API

Pasos de integración

Crear y procesar un pago de Pay by Link mediante la API implica crear un pago en tu servidor, enviar el enlace generado al cliente y procesar el estado final del pago mediante webhooks.

1. Crear el pago (lado del servidor)

Crea un Pago en tu servidor con un importe, una moneda y, opcionalmente, datos del cliente.

cURL
Node.js
PHP
Python

POST https://api.monei.com/v1/payments
curl --request POST 'https://api.monei.com/v1/payments' \
--header 'Authorization: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
  "amount": 110,
  "currency": "EUR",
  "orderId": "14379133960355",
  "description": "Test Shop - #14379133960355",
  "customer": {
    "email": "email@example.com",
    "phone": "+34666555444"
   },
  "callbackUrl": "https://example.com/checkout/callback",
  "completeUrl": "https://example.com/checkout/complete", // Optional: Redirect after payment attempt
  "cancelUrl": "https://example.com/checkout/cancel"     // Optional: Redirect if user cancels
}'

(Reemplaza YOUR_API_KEY con tu clave de API de MONEI real)

server.js
import {Monei} from '@monei-js/node-sdk';

// Replace YOUR_API_KEY with your actual MONEI API key
const monei = new Monei('YOUR_API_KEY');

const payment = await monei.payments.create({
  amount: 110,
  currency: 'EUR',
  orderId: '14379133960355',
  description: 'Test Shop - #14379133960355',
  customer: {
    email: 'email@example.com',
    phone: '+34666555444'
  },
  callbackUrl: 'https://example.com/checkout/callback',
  completeUrl: 'https://example.com/checkout/complete', // Optional
  cancelUrl: 'https://example.com/checkout/cancel' // Optional
});

// You will need the paymentId from the response in the next step
const paymentId = payment.id;

server.php
<?php
require_once 'vendor/autoload.php';

use Monei\Model\CreatePaymentRequest;
use Monei\Model\PaymentCustomer;
use Monei\MoneiClient;

// Replace YOUR_API_KEY with your actual MONEI API key
$monei = new MoneiClient('YOUR_API_KEY');

$payment = $monei->payments->create(
  new CreatePaymentRequest([
    'amount' => 110,
    'currency' => 'EUR',
    'order_id' => '14379133960355',
    'description' => 'Test Shop - #14379133960355',
    'customer' => new PaymentCustomer([
      'email' => 'email@example.com',
      'phone' => '+34666555444'
    ]),
    'callback_url' => 'https://example.com/checkout/callback',
    'complete_url' => 'https://example.com/checkout/complete', // Optional
    'cancel_url' => 'https://example.com/checkout/cancel'     // Optional
  ])
);

// You will need the paymentId from the response in the next step
$paymentId = $payment->getId();
?>

server.py
import Monei
from Monei import CreatePaymentRequest, PaymentCustomer

# Replace YOUR_API_KEY with your actual MONEI API key
monei = Monei.MoneiClient(api_key="YOUR_API_KEY")

payment = monei.payments.create(
    CreatePaymentRequest(
        amount=110,
        currency="EUR",
        order_id="14379133960355",
        description="Test Shop - #14379133960355",
        customer=PaymentCustomer(
          email="email@example.com",
          phone="+34666555444"
        ),
        callback_url="https://example.com/checkout/callback",
        complete_url="https://example.com/checkout/complete", // Optional
        cancel_url="https://example.com/checkout/cancel"     // Optional
    )
)

// You will need the paymentId from the response in the next step
payment_id = payment.id

Parámetros principales:

amount positive integer: Importe en la .
currency string: Código de moneda ISO de tres letras.
orderId string: Tu identificador de pedido único.
customer.email / customer.phone string: Al menos uno es obligatorio si quieres que MONEI envíe el enlace automáticamente (Paso 2).
callbackUrl string: Tu endpoint de servidor para las notificaciones de webhook (imprescindible para el estado final).
completeUrl / cancelUrl string (Opcional): URLs para redirigir al cliente tras la interacción.

Consulta todos los parámetros de la solicitud disponibles.

La respuesta contiene el payment.id, necesario para el siguiente paso.

2. Enviar el enlace y gestionar la interacción (servidor / cliente)

Tienes dos opciones principales para hacer llegar el enlace al cliente:

Opción A: MONEI envía el enlace (recomendado por su sencillez)

Realiza una solicitud POST al endpoint /v1/payments/{payment_id}/link. Si proporcionaste customer.email o customer.phone en el Paso 1, MONEI enviará automáticamente el enlace a través del canal correspondiente (email, WhatsApp o SMS).

cURL
Node.js
PHP
Python

POST https://api.monei.com/v1/payments/{payment_id}/link
curl --request POST 'https://api.monei.com/v1/payments/{payment_id}/link' \
--header 'Authorization: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
  "language": "es", // Optional: Set language for email/SMS template
  "channel": "email" // Optional: Force channel (email, whatsapp, sms)
}'

(Reemplaza {payment_id} y YOUR_API_KEY)

server.js
// Assumes paymentId is obtained from the previous step
await monei.payments.sendLink(paymentId, {
  language: 'es', // Optional
  channel: 'email' // Optional
});

server.php
<?php
// Assumes $paymentId is obtained from the previous step
$monei->payments->sendLink($paymentId, [
  'language' => 'es', // Optional
  'channel' => 'email' // Optional
]);
?>

server.py
# Assumes payment_id is obtained from the previous step
monei.payments.sendLink(payment_id, language='es', channel='email') # Optional params

Opción B: Tú envías el enlace

El objeto Payment devuelto en el Paso 1 contiene payment.nextAction.redirectUrl. Este es el enlace de pago.

Example Partial Response from Step 1
{
  "id": "af6029f80f5fc73a8ad2753eea0b1be0",
  // ... other fields ...
  "nextAction": {
    "type": "CONFIRM",
    "mustRedirect": true,
    "redirectUrl": "https://secure.monei.com/payments/af6029f80f5fc73a8ad2753eea0b1be0" // <-- This is the Pay by Link URL
  }
}

Puedes tomar este redirectUrl y enviárselo a tu cliente a través de tus propios canales de comunicación (email, SMS, mensaje en la app, etc.).

Interacción del cliente:

El cliente hace clic en el enlace.
Es redirigido a la página de pago segura de MONEI.
Elige un método de pago, introduce los datos y completa cualquier autenticación requerida (como 3D Secure).
Tras intentar el pago o cancelarlo, puede ser redirigido a tu completeUrl o cancelUrl si las proporcionaste en el Paso 1.

3. Procesar la notificación de webhook (lado del servidor)

Independientemente de si el cliente es redirigido, MONEI envía el estado final y autoritativo del pago mediante una solicitud HTTP POST asíncrona a la callbackUrl que proporcionaste en el Paso 1. El cuerpo de la solicitud contiene el objeto Payment completo en formato JSON.

Este webhook es la única forma fiable de confirmar el resultado definitivo del pago.

Es imprescindible que:

Verifiques la cabecera MONEI-Signature incluida en la solicitud. Esto confirma que el webhook proviene realmente de MONEI. Consulta la guía de verificación de firmas para los detalles de implementación.
Devuelvas un código de estado HTTP 200 OK inmediatamente al recibir el webhook para confirmar la recepción. Cualquier otro código de estado indica a MONEI que la notificación ha fallado.

Si MONEI no recibe un 200 OK, reintentará el envío del webhook.

Una vez verificada la firma, inspecciona el campo status en el objeto Payment (SUCCEEDED, FAILED, CANCELED, etc.) para determinar si debes completar el pedido o gestionar el fallo.

¿Te ha resultado útil esta página?

Resumen​

Integración con la API​

Antes de empezar (API)​

Pasos de integración​

1. Crear el pago (lado del servidor)​

2. Enviar el enlace y gestionar la interacción (servidor / cliente)​

3. Procesar la notificación de webhook (lado del servidor)​