Pay By Link

Send your customers a unique link via email, WhatsApp or SMS to pay online in one click!

Overview

This page explains how to create payment links from the MONEI Dashboard or programmatically using the MONEI Payments API.

Pay By Link generates a unique URL for a specific payment amount that directs the customer to a secure MONEI-hosted payment page.

Create from Dashboard

You can create payment links directly from the MONEI Dashboard without writing any code.

1. Navigate to Payments

Go to MONEI Dashboard → Payments and click the Pay By Link button.

2. Fill in the payment form

Fill in the payment details. Some fields are always required, while others depend on the selected payment methods.

Quick Summary

• Always required: Amount, Allowed payment methods.
• Conditionally required: Customer email and Billing Address (for specific methods).
• Optional: Expiration date, Order ID, customer details, description, store, shipping address.

Field	Status	Notes
Amount	Required	Payment amount in your account currency
Allowed payment methods	Required	At least one method must be selected
Expiration date	Optional	Defaults to 7 days from creation; must be a future date
Order ID	Optional	Alphanumeric identifier, max 40 characters
Customer name	Optional
Customer email	Conditional	Required when Multibanco or MB WAY is selected
Customer phone	Optional
Description	Optional	Custom description attached to the payment
Store	Optional	Only visible if you have multiple stores configured
Billing Address	Conditional	Required when Multibanco or MB WAY is selected
Shipping Address	Optional	Optional, collapsible section

Conditional behavior by payment method

The form adapts automatically based on the selected payment methods.

Billing Address and Customer Email become required when any of these payment methods is selected:

• Multibanco
• MB WAY

Manually capture payment checkbox appears only when all selected payment methods support manual capture:

• Card
• PayPal
• Bizum

If any other method is included (e.g. Multibanco), the manual capture option is hidden.

3. Review and send the payment link

After clicking Create payment, a Send payment request modal appears where you can review the payment details before sending the link to your customer.

From this modal you can configure:

• Delivery channel — Choose how to deliver the link: Email, WhatsApp, SMS, or Payment request.
• Send to — The recipient's email address or phone number, depending on the selected channel.
• Customer language — The language for the payment page and notification (English, Español, Català, Português, Deutsch, Italiano, Français).

The modal also shows:

• A preview of the payment notification with order ID, amount, date, and billing details.
• A Permalink and Get short link option to copy the payment URL directly without sending a notification.

Click Send payment request to deliver the link to the customer through the selected channel.

API Integration

The following section explains the API flow (server-side implementation).

Before You Begin (API)

• You'll need a MONEI account and your API keys (test or live). Find them in your MONEI Dashboard.
• Use your test mode keys for integration testing.
• Ensure relevant payment methods are enabled in your account settings for the hosted page.
• You can monitor test payments in your MONEI Dashboard → Payments (ensure Test Mode is active).

Integration Steps

Creating and processing a Pay By Link payment via API involves creating a payment on your server, sending the generated link to the customer, and processing the final payment status via webhooks.

1. Create Payment (Server-side)

Create a Payment on your server with an amount, currency, and optionally customer details.

cURL

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
}'

(Replace YOUR_API_KEY with your actual MONEI API key)

Node.js

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;

PHP

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();
?>

Python

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

Key Parameters:

• amount positive integer: Amount in the smallest currency unit.
• currency string: Three-letter ISO currency code.
• orderId string: Your unique order identifier.
• customer.email / customer.phone string: At least one is required if you want MONEI to send the link automatically (Step 2).
• callbackUrl string: Your server endpoint for webhook notifications (crucial for final status).
• completeUrl / cancelUrl string (Optional): URLs for redirecting the customer after interaction.

Check all available request parameters.

The response contains the payment.id, needed for the next step.

2. Send Link & Handle Interaction (Server-side / Client-side)

You have two main options to get the link to the customer:

Option A: MONEI Sends the Link (Recommended for Simplicity)

Make a POST request to the /v1/payments/{payment_id}/link endpoint. If you provided customer.email or customer.phone in Step 1, MONEI will automatically send the link via the appropriate channel (email, WhatsApp, or SMS).

cURL

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)
}'

(Replace {payment_id} and YOUR_API_KEY)

Node.js

server.js

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

PHP

server.php

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

Python

server.py

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

Option B: You Send the Link

The Payment object returned in Step 1 contains payment.nextAction.redirectUrl. This is the payment link.

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
  }
}

You can take this redirectUrl and send it to your customer through your own communication channels (email, SMS, in-app message, etc.).

Customer Interaction:

1. The customer clicks the link.
2. They are taken to the secure MONEI payment page.
3. They choose a payment method, enter details, and complete any required authentication (like 3D Secure).
4. After attempting payment or cancelling, they might be redirected to your completeUrl or cancelUrl if you provided them in Step 1.

3. Process Webhook Notification (Server-side)

Regardless of whether the customer is redirected, MONEI sends the final, authoritative payment status via an asynchronous HTTP POST request to the callbackUrl you provided in Step 1. The request body contains the full Payment object in JSON format.

This webhook is the only reliable way to confirm the definitive payment outcome.

Crucially, you must:

1. Verify the MONEI-Signature header included in the request. This confirms the webhook genuinely came from MONEI. See the Verify Signatures guide for implementation details.
2. Return a 200 OK HTTP status code immediately upon receiving the webhook to acknowledge receipt. Any other status code tells MONEI the notification failed.

If MONEI doesn't receive a 200 OK, it will retry sending the webhook.

Once the signature is verified, inspect the status field in the Payment object (SUCCEEDED, FAILED, CANCELED, etc.) to determine whether to fulfill the order or handle the failure.