Take cards and wallets through one integration.

1. Include the Library

<!-- Include PayGlobe.js in your HTML -->
<script src="https://api.payglobe.it/paymentgw/js/payglobe.js"></script>

2. Initialize with Your API Key

// Initialize PayGlobe with your publishable key
const payglobe = PayGlobe('pk_test_PayGlobe123456789TestPublishable');

3. Create a Payment

// Create a new payment
const payment = await payglobe.payments.create({
    amount: 50.00,
    email: 'customer@example.com', // Customer email for payment receipt
    description: 'Order #12345' // optional
});

console.log('Payment created:', payment.id);

4. Redirect to Checkout

// Option A: Full page redirect
payglobe.redirectToCheckout({
    paymentId: payment.id
});

// Option B: Load in iframe
payglobe.redirectToCheckout({
    paymentId: payment.id,
    element: '#payment-container' // CSS selector for iframe container
});

5. Check Payment Status

// Retrieve payment status
const status = await payglobe.payments.retrieve(payment.id);

console.log('Payment status:', status.status);
console.log('Amount:', status.totalAmount);
console.log('Gateway Payment ID:', status.paymentId);

Complete Example

<!DOCTYPE html>
<html>
<head>
    <title>PayGlobe Checkout</title>
    <script src="https://api.payglobe.it/paymentgw/js/payglobe.js"></script>
</head>
<body>
    <button id="checkout-button">Pay 50.00 EUR</button>
    <div id="payment-container"></div>

    <script>
        const payglobe = PayGlobe('pk_test_PayGlobe123456789TestPublishable');

        document.getElementById('checkout-button').addEventListener('click', async () => {
            try {
                // Create payment
                const payment = await payglobe.payments.create({
                    amount: 50.00,
                    email: 'customer@example.com', // Customer email for receipt
                    description: 'Order #12345'     // Your internal order number
                });

                // Redirect to checkout (in iframe)
                await payglobe.redirectToCheckout({
                    paymentId: payment.id,
                    element: '#payment-container'
                });
            } catch (error) {
                console.error('Payment error:', error);
                alert('Payment failed: ' + error.message);
            }
        });
    </script>
</body>
</html>

• Wrapper API (Recommended)
• Direct API (Advanced)
• Payment Links

POST/api/payment/initiate

{
  "amount": 150.00,
  "orderId": "ORD-1029",
  "description": "Order #1029",
  "email": "buyer@example.com",
  "language": "it"
}

Response:
{
  "transactionId": "af6d4def-ae25-43e0-b4f4-b19d4015b604",
  "status": "IGFS_INPUT_PRESENTED",
  "gateway": "IGFS",
  "checkoutUrl": "https://api.payglobe.it/paymentgw/payment/checkout/af6d4def-...",
  "igfsRedirectUrl": "https://testpaye.netsgroup.com/...",
  "igfsPaymentId": "237840183108800560"
}

GET/api/payment/status/{transactionId}

Response:
{
  "transactionId": "af6d4def-ae25-43e0-b4f4-b19d4015b604",
  "status": "COMPLETED",
  "totalAmount": 150.00,
  "createdAt": "2026-08-25T12:24:11",
  "updatedAt": "2026-08-25T12:29:03",
  "orderId": "ORD-1029",
  "description": "Order #1029"
}

orderId, description and errorMessage appear only when set.
A transaction owned by another merchant returns 404, not 403.

POST/api/payment-links/create

Headers:
  Authorization: Bearer sk_test_YourSecretKey
  Content-Type: application/json

{
  "amount": 50.00,
  "currency": "EUR",
  "description": "Payment for Order #12345",
  "customerEmail": "customer@example.com",
  "customerName": "John Doe",
  "linkType": "LINK",
  "expirationDays": 30
}

Response:
{
  "success": true,
  "transactionId": "LINK_A1B2C3D4E5F67890",
  "linkUrl": "https://api.payglobe.it/paymentgw/payment/checkout/LINK_A1B2C3D4E5F67890",
  "qrcodeUrl": "/api/payment-links/LINK_A1B2C3D4E5F67890/qrcode",
  "amount": 50.00,
  "status": "PENDING",
  "delivered": false,
  "expiresAt": "2025-12-09T12:00:00"
}

<!-- Embed QR Code in HTML -->
<img src="https://api.payglobe.it/paymentgw/api/payment-links/LINK_ABC123/qrcode?size=300"
     alt="Payment QR Code">

<!-- Or use in email template -->
<h2>Invoice Payment</h2>
<p>Scan QR code or click link to pay €50.00</p>
<img src="{{qrcodeUrl}}" alt="QR Code">
<a href="{{linkUrl}}">Pay Now</a>

GET/api/payment-links/{transactionId}

Headers:
  Authorization: Bearer sk_test_YourSecretKey

Response:
{
  "success": true,
  "transactionId": "LINK_A1B2C3D4E5F67890",
  "status": "PAID",
  "paymentId": "IGFS_PAYMENT_ID",
  "authCode": "123456",
  "paidAt": "2025-11-09T12:30:00",
  "amount": 50.00
}

POST/api/payment-links/{transactionId}/verify

Headers:
  Authorization: Bearer sk_test_YourSecretKey

Description: Refreshes payment status from gateway and updates local database

PayGlobe sends server-to-server webhooks to notify you of payment events using HMAC-SHA256 signatures for security.

Step 1: Configure Webhook in Merchant Dashboard

1. Go to Merchant Login and authenticate with your API key
2. In the Webhook Configuration section, enter your webhook URL (e.g., https://yourdomain.com/api/payment-webhook)
3. Copy the Webhook Secret (shown once, format: whsec_test_abc123...)
4. Save the secret in your backend environment variables

Step 2: Verify HMAC Signature (Java Example)

// Receive webhook
String signature = request.getHeader("X-PayGlobe-Signature");
String rawBody = request.getBody(); // RAW JSON string

// Verify signature with your webhook secret
Mac mac = Mac.getInstance("HmacSHA256");
SecretKeySpec secretKey = new SecretKeySpec(webhookSecret.getBytes(), "HmacSHA256");
mac.init(secretKey);
byte[] hash = mac.doFinal(rawBody.getBytes());
String expectedSignature = Base64.getEncoder().encodeToString(hash);

if (expectedSignature.equals(signature)) {
    // ✅ Webhook authentic - process payment
    PaymentNotification payment = objectMapper.readValue(rawBody, PaymentNotification.class);
    System.out.println("Payment received: " + payment.transactionId);
} else {
    // ❌ Invalid signature - reject
    return Response.status(401).entity("Invalid signature").build();
}

Step 3: Verify HMAC Signature (Node.js Example)

const crypto = require('crypto');

app.post('/api/payment-webhook', express.raw({type: 'application/json'}), (req, res) => {
    const signature = req.headers['x-payglobe-signature'];
    const rawBody = req.body.toString(); // RAW body string

    // Verify signature
    const hmac = crypto.createHmac('sha256', process.env.PAYGLOBE_WEBHOOK_SECRET);
    hmac.update(rawBody);
    const expectedSignature = hmac.digest('base64');

    if (expectedSignature !== signature) {
        return res.status(401).send('Invalid signature');
    }

    // ✅ Webhook verified - process payment
    const payment = JSON.parse(rawBody);
    console.log('Payment received:', payment.transactionId);

    res.status(200).send('OK');
});

Webhook Payload Example:

POSThttps://yourdomain.com/api/payment-webhook

Headers:
  X-PayGlobe-Signature: Kx7j9mP4vR2nQ8sT... (HMAC-SHA256 signature)
  Content-Type: application/json

{
  "transactionId": "TXN_20251107_123456",
  "totalAmount": 150.00,
  "cardAmount": 150.00,
  "voucherAmount": 0.00,
  "paymentMethod": "CARD",
  "status": "SUCCESS",
  "sessionStart": "2025-11-07T10:00:00Z",
  "sessionEnd": "2025-11-07T10:05:23Z",
  "sessionDurationSeconds": 323,
  "vouchersUsed": 0,
  "cardGatewayDetails": {
    "paymentId": "PAY_789",
    "transactionId": "IGFS_123456789",
    "operationType": "CAPTURE",
    "preauthorizedAmount": 150.00,
    "capturedAmount": 150.00,
    "responseCode": "00",
    "responseMessage": "Transaction approved"
  },
  "voucherDetails": null,
  "createdAt": "2025-11-07T10:00:00Z",
  "completedAt": "2025-11-07T10:05:23Z"
}

Note: voucherAmount, vouchersUsed and voucherDetails stay in the payload for backward compatibility, but the meal-voucher connector is closed: they are always 0 / null.

Testing Webhooks:

Use webhook.site or ngrok to test webhook delivery:

1. Go to webhook.site and copy unique URL
2. Configure this URL as webhook in Admin Panel
3. Copy webhook secret shown
4. Make a test payment
5. Verify webhook received with X-PayGlobe-Signature header

Webhook Event Structure:

Payment data is wrapped in an Event object:

{
  "id": "evt_1a2b3c4d5e6f7g8h9i0j",          // Unique event ID (evt_...)
  "object": "event",                         // Always "event"
  "api_version": "2023-10-16",               // API version
  "created": 1699372800,                     // Unix timestamp
  "type": "payment_intent.succeeded",        // Event type
  "livemode": false,                         // Test/live mode
  "pending_webhooks": 0,                     // Delivery queue count
  "data": {
    "object": {
      // Your payment data here (PaymentNotificationDto)
      "transactionId": "TXN_20251107_123456",
      "totalAmount": 150.00,
      "cardAmount": 150.00,
      "voucherAmount": 0.00,                 // always 0: voucher connector closed
      "paymentMethod": "CARD",
      "status": "SUCCESS",
      "cardGatewayDetails": { ... },
      "voucherDetails": null                 // always null
    }
  },
  "request": null                            // Null for automatic events
}

Event Types:

Verifying a Webhook (Node.js):

const crypto = require('crypto');

// express.raw is required: the signature covers the RAW body.
// Any JSON parse-and-reserialize before this point changes the bytes
// and the signature will never match.
app.post('/webhook', express.raw({type: 'application/json'}), (req, res) => {
    const received = req.headers['x-payglobe-signature'];

    const expected = crypto
        .createHmac('sha256', process.env.PAYGLOBE_WEBHOOK_SECRET)  // whsec_...
        .update(req.body)
        .digest('base64');

    const a = Buffer.from(expected);
    const b = Buffer.from(received || '');
    if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) {
        return res.status(400).send('Invalid signature');
    }

    const event = JSON.parse(req.body);

    switch (event.type) {
        case 'payment_intent.succeeded': {
            const payment = event.data.object;
            console.log('Paid:', payment.transactionId, payment.totalAmount);
            console.log('Card:', payment.cardAmount);
            break;
        }
        case 'payment_intent.payment_failed':
            console.log('Failed:', event.data.object.transactionId);
            break;

        case 'payment_intent.processing':
            // Intermediate state - not an outcome. Wait for a later event.
            break;
    }

    // Answer 2xx quickly: we retry 10 times, 5 minutes apart, until you do.
    res.status(200).send('OK');
});

Verifying a Webhook (Python):

import hashlib, hmac, base64, json

@app.route('/webhook', methods=['POST'])
def webhook():
    # get_data() gives the RAW body. The signature covers those exact bytes.
    payload = request.get_data()
    received = request.headers.get('X-PayGlobe-Signature', '')

    expected = base64.b64encode(
        hmac.new(WEBHOOK_SECRET.encode(), payload, hashlib.sha256).digest()
    ).decode()

    if not hmac.compare_digest(expected, received):
        return 'Invalid signature', 400

    event = json.loads(payload)

    if event['type'] == 'payment_intent.succeeded':
        payment = event['data']['object']
        print(f"Paid: {payment['transactionId']} {payment['totalAmount']}")
        print(f"Card: {payment['cardAmount']}")

    elif event['type'] == 'payment_intent.payment_failed':
        print(f"Failed: {event['data']['object']['transactionId']}")

    elif event['type'] == 'payment_intent.processing':
        pass  # intermediate state, not an outcome

    return '', 200

PayGlobe Advantages Over Stripe:

How It Works:

1. Contact PayGlobe to open a merchant account
2. Provide your business details and integration requirements
3. PayGlobe configures all payment gateway credentials (IGFS, Stripe, PayPal, etc.) on your behalf
4. Receive your API keys:
   • pk_test_... - Publishable key (safe for frontend)
   • sk_test_... - Secret key (backend only)
5. Configure your webhook via Merchant Dashboard (self-service)
6. Start accepting payments using our APIs

Authentication with API Keys

How to Authenticate

Include API key in Authorization header:

Authorization: Bearer pk_test_PayGlobe123456789TestPublishable

Example with JavaScript:

const response = await fetch('https://api.payglobe.it/paymentgw/api/payment/initiate', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'Authorization': 'Bearer pk_test_PayGlobe123456789TestPublishable'
    },
    body: JSON.stringify({
        amount: 150.00,
        email: 'customer@example.com',
        description: 'Order #12345'
    })
});

Example with cURL:

curl -X POST https://api.payglobe.it/paymentgw/api/payment/initiate \
  -H "Authorization: Bearer pk_test_PayGlobe123456789TestPublishable" \
  -H "Content-Type: application/json" \
  -d '{"amount": 150.00, "email": "customer@example.com", "description": "Order #12345"}'

Production Environment

Refunds & Storni (Reversals)

1. Full Refund (Storno Totale)

Refund the entire payment amount:

Endpoint: POST /api/payment/refund/{transactionId}

Headers:
Authorization: Bearer sk_test_YourSecretKeyHere    ← Secret Key required!
Content-Type: application/json

Request Body:
{
  "reason": "Customer requested refund"
}

Example with cURL:
curl -X POST https://api.payglobe.it/paymentgw/api/payment/refund/abc123 \
  -H "Authorization: Bearer sk_test_YourSecretKeyHere" \
  -H "Content-Type: application/json" \
  -d '{"reason": "Customer requested refund"}'

Response (Success):
{
  "success": true,
  "transactionId": "abc123",
  "refundAmount": 150.00,
  "status": "REFUNDED",
  "refundedAt": "2025-11-05T20:15:00Z"
}

2. Partial Refund (Storno Parziale)

Refund only a portion of the payment:

Endpoint: POST /api/payment/refund/{transactionId}

Headers:
Authorization: Bearer sk_test_YourSecretKeyHere    ← Secret Key required!
Content-Type: application/json

Request Body:
{
  "amount": 50.00,
  "reason": "Partial refund for damaged item"
}

Example with Node.js:
const response = await fetch(
  `https://api.payglobe.it/paymentgw/api/payment/refund/${transactionId}`,
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.PAYGLOBE_SECRET_KEY}`,  // sk_test_...
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      amount: 50.00,
      reason: 'Partial refund for damaged item'
    })
  }
);

const refund = await response.json();
console.log('Refund processed:', refund);

Response (Success):
{
  "success": true,
  "transactionId": "abc123",
  "refundAmount": 50.00,
  "remainingAmount": 100.00,
  "status": "PARTIALLY_REFUNDED",
  "refundedAt": "2025-11-05T20:15:00Z"
}

3. Check What Was Refunded

There is no refund-history endpoint. The refund response already carries the totals, and the transaction status reflects them afterwards:

The refund response already tells you:
{
  "refundedNow": 50.00,
  "refundedTotal": 50.00,
  "remainingRefundable": 100.00,
  "status": "PARTIAL_REFUNDED"
}

Afterwards, re-read the transaction:
curl https://api.payglobe.it/paymentgw/api/payment/status/abc123 \
  -H "Authorization: Bearer sk_test_YourSecretKeyHere"

status becomes REFUNDED or PARTIAL_REFUNDED.

Backend Implementation Example (Node.js/Express)

// Store secret key in environment variable
const PAYGLOBE_SECRET_KEY = process.env.PAYGLOBE_SECRET_KEY;  // sk_test_...

// Refund endpoint on your server
app.post('/admin/refund/:transactionId', async (req, res) => {
  try {
    const { transactionId } = req.params;
    const { amount, reason } = req.body;

    // Call PayGlobe API with SECRET KEY
    const response = await fetch(
      `https://api.payglobe.it/paymentgw/api/payment/refund/${transactionId}`,
      {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${PAYGLOBE_SECRET_KEY}`,  // SECRET!
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({ amount, reason })
      }
    );

    const refund = await response.json();

    if (refund.success) {
      // Log the refund in your database
      await logRefund(transactionId, refund);
      res.json({ success: true, refund });
    } else {
      res.status(400).json({ error: refund.message });
    }
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
});

Summary: Which Key to Use?

Frontend (JavaScript - Publishable Key):
const payglobe = PayGlobe('pk_test_...');  ✅ Public, safe to expose
await payglobe.payments.create({
    amount: 100,
    email: 'customer@example.com',  // Customer email for receipt
    description: 'Order #12345'      // Your internal order number
});

Backend (Server - Secret Key):
const secretKey = process.env.PAYGLOBE_SECRET_KEY;  ✅ Private, server-only
Authorization: Bearer sk_test_...

Operations Requiring Secret Key:
- POST /api/payment/refund/{id}         → Full or partial refund
- POST /api/payment/capture/{id}        → Manual capture (full or partial)
- POST /api/payment/void/{id}           → Void preauthorization (release hold)
- Webhook signature validation          → Verify HMAC

A publishable key on these endpoints is rejected with HTTP 403.
Refund history is not exposed as a separate endpoint: the refund response
returns refundedTotal and remainingRefundable, and GET /api/payment/status/{id}
reports the current state.

Connect an AI assistant to your PayGlobe account and let it read your transactions, build payment links, or issue refunds — with only the permissions you grant and a spending limit you set. PayGlobe exposes a Model Context Protocol (MCP) server, so any MCP client can talk to it.

Agents get their own credential, never your secret key

An agent authenticates with an agent key (ak_live_… / ak_test_…), issued from AI Agents in your dashboard. You have one secret key, and it is the one your server integrations use. Handing it to an assistant would mean that revoking the assistant forces you to rotate the key that everything else depends on — so in practice you would never revoke it.

An agent key is separate by design: revoking one agent changes nothing else.

Permissions

Grant the narrowest set that does the job. Read-only agents cannot move money no matter what happens to them.

Spending limits are mandatory, not optional

Grant refunds:write or captures:write and you must set a maximum per operation; a daily maximum is also available. Both are enforced on every single call, before anything reaches the payment provider.

What an agent can never do

Agent access is allow-listed: a route is unavailable to an agent unless it has been explicitly opened. Some operations are never delegable, whatever permissions you grant, because they have no remedy after the fact:

• rotate or read your API keys
• change your two-factor setup
• change your payment provider credentials or your webhook URL
• take a payment over the phone (MO/TO)
• list, save or delete your customers’ stored cards — charging one is possible with stored_cards:charge, but reading the card list never is
• create another agent — otherwise revoking one would close nothing

Expiry, revocation, audit

• Every agent key expires, at most 90 days out. Credentials that never expire are the ones that get forgotten in someone else’s configuration.
• Revocation takes effect on the agent’s next call, and it also kills any OAuth token issued for that agent.
• Every call is logged — allowed and refused, with the operation, the amount and the outcome. Refusals are the interesting half: an agent repeatedly asking for permissions it does not have is the sign that something is manipulating it.

What the assistant can do

Ten tools, each tied to a permission. An assistant sees only the ones your grant covers — if you grant read access, the refund tool does not appear at all.

Letting an agent buy: orders, and what it may buy

An agent can charge a card your customer has already saved — a reorder, a refill, a standing arrangement — without anyone at a screen. Two things make that safe enough to offer, and both are worth understanding before you grant it.

1. You create the order. The agent only confirms it.

The agent does not tell PayGlobe how much to charge. You do, with your secret key, before the agent acts:

POST /api/agent-orders          Authorization: Bearer sk_live_...
{
  "customerId": "cust_42",
  "amount": 24.90,
  "category": "groceries",
  "description": "Weekly coffee refill",
  "expiresInMinutes": 60
}
→ { "orderRef": "aord_Xk3p...", "status": "OPEN", "expiresAt": "..." }

The agent then settles it, and states no amount at all:

POST /api/token-payment/pay     Authorization: Bearer ak_live_...
{ "cardId": 7, "customerId": "cust_42", "agentOrderRef": "aord_Xk3p..." }

• Agents cannot create orders. /api/agent-orders is closed to them, whatever permissions you grant — otherwise an agent would be writing its own permission slip.
• One order, one payment. Two concurrent attempts on the same order: one wins, the other gets 409. If the card is declined the order reopens by itself.
• Orders are short-lived — 60 minutes by default, 24 hours at most. An order holds a price, so it must not outlive it.
• If the agent does send an amount, it must match the order exactly. A mismatch is refused rather than silently overridden: it means the agent thinks it is buying something else.

2. Limits per merchandise category

On top of the per-operation and daily ceilings, you can say what the agent is allowed to buy, in your own category words:

Two more rules worth knowing: a category limit can only tighten the agent’s ceilings, never widen them (that is checked when you issue the credential, not when the money moves); and the category on the order is matched against your rules exactly, so a typo does not nearly match — it falls through to *, or it is refused.

What this is, and what it is not

Reading what comes back

Every transaction carries three fields that exist so a machine reads it correctly:

• status is the raw gateway code — there are 77 of them, composed per provider.
• statusFamily is the translation: COMPLETED, AUTHORIZED (funds held), PENDING, FAILED, CANCELLED, REFUNDED, DISPUTED. Read this one.
• isTerminal says whether it can still change, so an assistant knows whether checking again later is worth anything.

Dates are ISO 8601 with offset. Amounts are decimal EUR.

Connect an MCP client

The MCP endpoint is POST https://api.payglobe.it/paymentgw/mcp. For Claude Desktop, add this to claude_desktop_config.json and restart the app:

{
  "mcpServers": {
    "payglobe": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://api.payglobe.it/paymentgw/mcp",
               "--header", "Authorization: Bearer ak_live_YOUR_AGENT_KEY"]
    }
  }
}

Your assistant sees only the tools your permissions allow. Grant read-only access and the refund tool does not appear at all — so the assistant will not attempt it and will not ask you to enable it.

Third-party agents: OAuth 2.1

If the agent is operated by someone else, they should not hold a key of yours at all. PayGlobe is an OAuth 2.1 authorization server: the application registers itself, you approve it on a consent screen where you pick the permissions and the limits, and it receives a token instead of a key.

GET  /.well-known/oauth-protected-resource   discovery for the MCP server
GET  /.well-known/oauth-authorization-server metadata (RFC 8414)
POST /oauth/register                         dynamic client registration (RFC 7591)
GET  /oauth/authorize                        consent screen
POST /oauth/token                            authorization_code + PKCE (S256), refresh_token
POST /oauth/revoke                           revocation (RFC 7009)

Most MCP clients discover all of this on their own: an unauthenticated call to the MCP endpoint answers 401 with a WWW-Authenticate header pointing at the metadata.

Errors you should handle

Every refusal carries retryable, and it is derived from the error code rather than guessed. An ambiguous error sends an agent into a loop, and a loop against a payment gateway costs real money.

How Disputes Work

Dispute API Endpoints

1. List Disputes

GET/api/merchant/disputes

Headers:
Authorization: Bearer sk_test_YourSecretKey

Query Parameters:
  ?status=OPEN           - Filter by status (OPEN, UNDER_REVIEW, WON, LOST, EXPIRED)
  ?startDate=2025-01-01  - Filter from date
  ?endDate=2025-12-31    - Filter to date
  ?page=0                - Page number (0-indexed)
  ?size=20               - Page size

Response:
{
  "disputes": [
    {
      "disputeId": "dp_1abc123def456",
      "originalTransactionId": "TXN_20251107_123456",
      "amountDisputed": 50.00,
      "currency": "EUR",
      "reasonCode": "FRAUDULENT",
      "reasonDescription": "Customer claims unauthorized charge",
      "status": "OPEN",
      "pspSource": "IGFS",
      "responseDeadline": "2025-12-15T23:59:59Z",
      "daysUntilDeadline": 12,
      "isUrgent": false,
      "createdAt": "2025-12-01T10:30:00Z"
    }
  ],
  "currentPage": 0,
  "totalPages": 1,
  "totalItems": 1
}

2. Get Dispute Statistics

GET/api/merchant/disputes/stats

Headers:
Authorization: Bearer sk_test_YourSecretKey

Response:
{
  "open": 3,
  "underReview": 1,
  "won": 5,
  "lost": 2,
  "totalAtRisk": 150.00,
  "totalLost": 75.00
}

3. Respond to Dispute

POST/api/merchant/disputes/{disputeId}/respond

Headers:
Authorization: Bearer sk_test_YourSecretKey
Content-Type: application/json

Request Body:
{
  "response": "This transaction was legitimate. Customer placed order on 2025-11-01 and received delivery confirmation on 2025-11-03. Attached: order receipt, shipping tracking, delivery signature."
}

Response:
{
  "success": true,
  "disputeId": "dp_1abc123def456",
  "status": "UNDER_REVIEW",
  "message": "Response submitted successfully"
}

Dispute Status Values

Dispute Reason Codes

Webhook: Receive Dispute Updates

When a dispute status changes, PayGlobe sends a webhook to your configured URL:

POSThttps://your-server.com/webhook/payglobe

Event Type: charge.dispute.created | charge.dispute.updated | charge.dispute.closed

Payload:
{
  "id": "evt_dispute_123",
  "type": "charge.dispute.created",
  "created": 1701432000,
  "data": {
    "object": {
      "disputeId": "dp_1abc123def456",
      "originalTransactionId": "TXN_20251107_123456",
      "amountDisputed": 50.00,
      "status": "OPEN",
      "reasonCode": "FRAUDULENT",
      "responseDeadline": "2025-12-15T23:59:59Z"
    }
  }
}

Save customer cards for one-click payments and recurring billing. Supports both IGFS and Shift4 gateways.

1. List Saved Cards

Get all saved cards for a customer:

GET/api/token-payment/cards?customerId={customerId}

Headers:
Authorization: Bearer sk_test_YourSecretKey

Response:
{
  "success": true,
  "customerId": "cust_123",
  "cards": [
    {
      "id": 1,
      "alias": "VISA ****4242",
      "brand": "VISA",
      "last4": "4242",
      "expiry": "12/26",
      "gateway": "IGFS",
      "isDefault": true,
      "lastUsedAt": "2025-12-08T10:00:00",
      "usageCount": 5
    }
  ],
  "count": 1
}

2. Pay with Saved Card (One-Click)

Charge a saved card without requiring customer to re-enter details:

POST/api/token-payment/pay

Headers:
Authorization: Bearer sk_test_YourSecretKey
Content-Type: application/json

Request Body:
{
  "cardId": 1,
  "amount": 50.00,
  "customerId": "cust_123",
  "customerEmail": "customer@example.com",
  "description": "Subscription renewal"
}

Response (Success):
{
  "success": true,
  "transactionId": "TKN_ABC123DEF456",
  "paymentId": "IGFS_PAY_789",
  "gateway": "IGFS",
  "status": "COMPLETED",
  "cardAlias": "VISA ****4242",
  "amount": 50.00
}

Response (Failed):
{
  "success": false,
  "transactionId": "TKN_ABC123DEF456",
  "status": "FAILED",
  "error": "Card declined"
}

3. Save Card from Transaction

After a successful payment with tokenization enabled, save the card:

POST/api/token-payment/save-card

Headers:
Authorization: Bearer sk_test_YourSecretKey
Content-Type: application/json

Request Body:
{
  "transactionId": "TXN_20251208_123456",
  "customerId": "cust_123",
  "gateway": "IGFS"
}

Response:
{
  "success": true,
  "cardId": 1,
  "alias": "VISA ****4242",
  "brand": "VISA",
  "last4": "4242",
  "isDefault": true
}

4. Set Default Card

POST/api/token-payment/cards/{cardId}/set-default?customerId={customerId}

Headers:
Authorization: Bearer sk_test_YourSecretKey

Response:
{
  "success": true,
  "cardId": 1,
  "alias": "VISA ****4242",
  "isDefault": true
}

5. Delete Saved Card

DELETE/api/token-payment/cards/{cardId}

Headers:
Authorization: Bearer sk_test_YourSecretKey

Response:
{
  "success": true,
  "message": "Card deleted successfully"
}

Integration Flow

First Payment (with tokenization):
1. Create payment with paymentMode = SALE_WITH_TOKENIZATION
2. Customer completes payment on gateway page
3. Gateway returns card token
4. Call POST /api/token-payment/save-card to store card
5. Card is now available for future payments

Subsequent Payments (one-click):
1. Call GET /api/token-payment/cards to get customer's cards
2. Display saved cards to customer
3. Customer selects a card
4. Call POST /api/token-payment/pay with cardId
5. Payment is processed server-to-server (no redirect)

If you integrate directly against IGFS (N&TS/Nexi PGW REST), you can move onto PayGlobe by repointing three configuration values. The adapter speaks the native IGFS wire protocol on the inbound side and routes to PayGlobe behind it. This is the IGFS counterpart of Mandala, our Stripe-compatible adapter.

What changes on your side

Everything else is byte-identical: same paths, same txHead/txReq/txRes JSON, same HTTP-Signature (draft-cavage, HMAC-SHA256), resultCode: "IGFS_000" on success, amounts in cents. The context path stays /MONEYNET_CG_SERVICES because the signature covers (request-target) — only the host moves.

Operations

Signature — unchanged

Keep computing the signature exactly as you do today: same scheme, same algorithm, same libraries. We do not restate the specification here — it is in your N&TS documentation. Only two practical notes about pointing it at us:

• The Host header you send and the host value you sign must be the same string, and both must be api.payglobe.it. Derive the host from the Base URL rather than configuring it separately — a leftover host from the previous endpoint is by far the most common cause of a 401.
• The signature keyId must equal the merId in the request body; a mismatch is rejected.

Full walkthrough, architecture and migration steps: igfs-adapter.html. For credentials, contact support@payglobe.it.

Netflix-style recurring billing with shareable subscribe links, dunning/retry policies, custom checkout fields, and merchant-side reference tracking. Manage everything from /paymentgw/merchant-dashboard.html → tab Subscriptions.

Plans

A plan defines what you sell on a recurring basis: price, billing interval, optional trial, fees, retry policy, custom checkout fields. Plans are merchant-scoped and identified by a plan_code (lowercase, underscores).

POST /api/subscriptions/plans
Authorization: Bearer sk_test_...
Content-Type: application/json

{
  "code": "plan_premium_monthly",
  "name": "Premium Monthly",
  "description": "Full premium access",
  "price": 9.99,
  "currency": "EUR",
  "interval": "MONTH",
  "intervalCount": 1,
  "setupFee": 0,
  "cancelFee": 0,
  "cancelFeeMinCycles": 0,
  "duration": "INFINITE",            // INFINITE | FIXED_CYCLES | FIXED_DATE
  "durationCycles": 0,
  "durationAfter": "END",            // END | RENEW | SWITCH
  "durationDate": null,
  "trial": false,
  "trialDays": 0,
  "trialRequireCard": false,
  "retry": "DEFAULT",                // DEFAULT | CUSTOM (with retryPolicy nested)
  "proration": "PRORATE",
  "tax": "EXCLUSIVE",
  "customFields": [
    { "key": "order_number", "label": "Order number", "type": "text", "required": true, "primary": true }
  ]
}

Customer onboarding link (the share URL)

Each plan has a public landing page. Generate the URL from the dashboard Share button on a plan card (which auto-fills the publishable key), or build it manually:

GET https://api.payglobe.it/paymentgw/subscribe.html?plan={plan_code}
              &pk={publishable_key}          // required: pk_test_... or pk_live_... (safe to expose)
              &ref={your_internal_id}        // optional, becomes merchantReference
              &customer={customer_email}     // optional, pre-fills the form

The landing page calls two public endpoints that authenticate via the publishable key:

• GET /api/public/subscriptions/plans/{code}?pk=... — returns plan info (no internal fields)
• POST /api/public/subscriptions?pk=... — creates the subscription with paymentMethod.source=CHARGE_NOW only; returns checkoutUrl for the IGFS-hosted card capture

The customer:

1. Sees the plan summary (price, trial if any, fees if any)
2. Fills email + name + any plan custom fields
3. Enters card details (tokenized via PayGlobe.js / IGFS / Shift4 — same flow as one-shot payments)
4. Subscribes → receives a confirmation email + access to the customer portal

Identifying the customer in your system: merchantReference

You have two ways to tag a subscription with your internal ID. Both populate merchantReference on the subscription record and in every webhook:

/subscribe.html?plan=plan_premium_monthly
   &ref=ORDER-12345
   &customer=customer@example.com

Webhook payload (subscription.created)

When a customer subscribes, your webhookUrl receives a signed POST (see Webhook Notifications section above). Subscription events:

POST {merchant.webhookUrl}
X-PayGlobe-Signature: {HMAC-SHA256 of body using your webhookSecret}
Content-Type: application/json

{
  "event": "subscription.created",
  "subscriptionId": "sub_a1b2c3d4",
  "planCode": "plan_premium_monthly",
  "merchantReference": "ORDER-12345",       // from ?ref= or primary custom field
  "customFields": {
    "order_number": "ORDER-12345"
  },
  "customer": {
    "email": "customer@example.com",
    "name": "Mario Rossi"
  },
  "card": { "brand": "VISA", "last4": "4242", "expiry": "12/27" },
  "status": "ACTIVE",                       // or TRIALING
  "nextBilling": "2026-06-08",
  "amount": 9.99,
  "currency": "EUR",
  "createdAt": "2026-05-08T10:23:45Z"
}

Other subscription events you can subscribe to:

• subscription.created
• subscription.activated (after trial)
• subscription.renewed (each successful charge)
• subscription.payment_failed (each retry attempt)
• subscription.past_due (entered dunning)
• subscription.recovered (back to ACTIVE after retry)
• subscription.canceled (by customer or after final retry per policy)
• subscription.paused / subscription.resumed
• subscription.ended (reached end of fixed duration)

Token sources for recurring charges

A subscription needs a card token that supports MIT (Merchant Initiated Transactions). PayGlobe accepts three sources:

POST /api/subscriptions/import-token
Authorization: Bearer sk_test_...
Content-Type: application/json

{
  "token": "tok_pos_xxxxxxxxxx",
  "gateway": "IGFS",                  // IGFS | SHIFT4
  "customer": { "email": "...", "name": "..." },
  "planCode": "plan_premium_monthly",
  "merchantReference": "ORDER-12345",
  "customFields": { "order_number": "ORDER-12345" }
}

Lifecycle & status transitions

TRIALING ─(trial ends, charge ok)─→ ACTIVE
ACTIVE   ─(charge fails)──────────→ PAST_DUE
PAST_DUE ─(retry succeeds)────────→ ACTIVE
PAST_DUE ─(all retries fail)──────→ {policy.after: CANCELED | PAUSED | UNPAID}
ACTIVE   ─(merchant pauses)───────→ PAUSED
PAUSED   ─(merchant resumes)──────→ ACTIVE
ACTIVE   ─(merchant or cust. cancels)→ CANCELED
ACTIVE   ─(reaches FIXED_CYCLES end)─→ ENDED | renew | switch (per plan.durationAfter)

Retry policy (dunning)

Define when failed charges are retried. Per-merchant default + optional per-plan override.

{
  "max": 4,                    // max attempts after the original failure
  "schedule": [1, 3, 5, 7],    // days after failure for attempts 1..N
  "after": "CANCEL",           // CANCEL | PAUSE | MARK_UNPAID
  "emails": true,              // send dunning emails to customer
  "webhook": false             // also fire webhook on each retry
}

Endpoints overview

Renewal & retry engine

Two background jobs run on a configurable cadence (defaults: renewal every 10 min, retry every 15 min, offset by 5):

• Renewal cycle — picks every ACTIVE/TRIALING sub whose nextBillingAt is in the past, charges it via IgfsService.initSaleWithToken (server-to-server, no 3DS, ~1 sec). On success: advances the period, increments cyclesCompleted, fires subscription.renewed. On failure: opens a SubscriptionInvoice, transitions to PAST_DUE, schedules the first retry per policy.
• Retry cycle — for PAST_DUE subs whose nextRetryAt is due, replays the open invoice. Each attempt is recorded in subscription_retry_attempts. After policy.max failures, applies policy.after (CANCEL / PAUSE / MARK_UNPAID) and fires the matching webhook.

Cron strings are tunable via payglobe.subscriptions.renewal-cron / payglobe.subscriptions.retry-cron in application.properties. Set payglobe.subscriptions.scheduler.enabled=false to disable both.

See SUBSCRIPTIONS.md in the project root for the full design doc with examples in Node, PHP, and Python.