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 programmatically using the MONEI Payments API. You can also create and manage payment links manually via your MONEI Dashboard.

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

Before You Begin

• 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 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.