Payment Gateway - Partner Integration Guide

// 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();
}

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

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": 100.00,
  "voucherAmount": 50.00,
  "paymentMethod": "CARD_AND_VOUCHER",
  "status": "SUCCESS",
  "sessionStart": "2025-11-07T10:00:00Z",
  "sessionEnd": "2025-11-07T10:05:23Z",
  "sessionDurationSeconds": 323,
  "vouchersUsed": 1,
  "cardGatewayDetails": {
    "paymentId": "PAY_789",
    "transactionId": "IGFS_123456789",
    "operationType": "CAPTURE",
    "preauthorizedAmount": 150.00,
    "capturedAmount": 100.00,
    "responseCode": "00",
    "responseMessage": "Transaction approved"
  },
  "voucherDetails": {
    "serialNumber": "2189CA1L7823",
    "operationNumber": "OP123456",
    "spentAmount": 50.00,
    "responseCode": "000",
    "responseMessage": "Transaction OK"
  },
  "createdAt": "2025-11-07T10:00:00Z",
  "completedAt": "2025-11-07T10:05:23Z"
}

{
  "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": 100.00,
      "voucherAmount": 50.00,
      "paymentMethod": "CARD_AND_VOUCHER",
      "status": "SUCCESS",
      "cardGatewayDetails": { ... },
      "voucherDetails": { ... }
    }
  },
  "request": null                            // Null for automatic events
}

const stripe = require('stripe');

app.post('/webhook', express.raw({type: 'application/json'}), (req, res) => {
    const sig = req.headers['stripe-signature'] || req.headers['x-payglobe-signature'];

    let event;
    try {
        // Works with Stripe's constructEvent method!
        event = stripe.webhooks.constructEvent(
            req.body,
            sig,
            process.env.WEBHOOK_SECRET  // whsec_test_...
        );
    } catch (err) {
        return res.status(400).send(`Webhook Error: ${err.message}`);
    }

    // Handle event types
    switch (event.type) {
        case 'payment_intent.succeeded':
            const payment = event.data.object;
            console.log('Payment succeeded:', payment.transactionId);
            console.log('Card amount:', payment.cardAmount);
            console.log('Voucher amount:', payment.voucherAmount);
            break;

        case 'payment_intent.payment_failed':
            console.log('Payment failed:', event.data.object);
            break;

        case 'charge.refunded':
            const refund = event.data.object;
            console.log('Refund processed:', refund.transactionId);
            console.log('Refund amount:', refund.refundAmount);
            break;

        case 'checkout.session.completed':
            console.log('Checkout completed:', event.data.object);
            break;

        default:
            console.log(`Unhandled event type: ${event.type}`);
    }

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

import stripe

@app.route('/webhook', methods=['POST'])
def webhook():
    payload = request.get_data()
    sig_header = request.headers.get('Stripe-Signature') or \
                 request.headers.get('X-PayGlobe-Signature')

    try:
        # Works with Stripe's construct_event method!
        event = stripe.Webhook.construct_event(
            payload, sig_header, webhook_secret
        )
    except ValueError as e:
        return 'Invalid payload', 400
    except stripe.error.SignatureVerificationError as e:
        return 'Invalid signature', 400

    # Handle event
    if event['type'] == 'payment_intent.succeeded':
        payment = event['data']['object']
        print(f"Payment succeeded: {payment['transactionId']}")
        print(f"Card: {payment['cardAmount']}, Voucher: {payment['voucherAmount']}")

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

    elif event['type'] == 'charge.refunded':
        refund = event['data']['object']
        print(f"Refund processed: {refund['transactionId']}")
        print(f"Refund amount: {refund.get('refundAmount', 0)}")

    elif event['type'] == 'checkout.session.completed':
        print(f"Checkout completed: {event['data']['object']}")

    return '', 200

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

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

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

Endpoint: GET /api/payment/refunds/{transactionId}

Headers:
Authorization: Bearer sk_test_YourSecretKeyHere    ← Secret Key required!

Example:
curl https://api.payglobe.it/paymentgw/api/payment/refunds/abc123 \
  -H "Authorization: Bearer sk_test_YourSecretKeyHere"

Response:
{
  "transactionId": "abc123",
  "originalAmount": 150.00,
  "totalRefunded": 50.00,
  "remainingAmount": 100.00,
  "refunds": [
    {
      "refundId": "ref_xyz789",
      "amount": 50.00,
      "reason": "Partial refund for damaged item",
      "status": "SUCCESS",
      "createdAt": "2025-11-05T20:15:00Z"
    }
  ]
}

// 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 });
  }
});

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.

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
}

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
}

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

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

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
}

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

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
}

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
}

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

Headers:
Authorization: Bearer sk_test_YourSecretKey

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

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)