Skip to content

Glomopay S2S Integration - Technical Documentation

Overview

Server-to-Server (S2S) integration allows you to collect card details on your platform and process payments through Glomopay's infrastructure. This integration is designed for PCI DSS certified merchants who want to maintain control over the payment experience while leveraging Glomopay's cross-border payment processing capabilities.

Prerequisites

  • PCI DSS Certification: You must be PCI DSS certified to collect and transmit card details
  • Glomopay Account: Active merchant account
  • API Keys: Secret keys for both sandbox (test) and production (live) environments

Environment Configuration

API Endpoint

All API requests use the same base URL for both environments:

https://api.glomopay.com

Authentication

The secret key in your Authorization header determines the environment:

  • Sandbox Key → Creates orders and payments in test mode
  • Production Key → Creates orders and payments in live mode
Authorization: Bearer YOUR_SECRET_KEY

Getting Your API Keys

  1. Navigate to: https://app.glomopay.com/api-keys-and-webhooks/api-keys
  2. Use the toggle to switch between Test Mode and Live Mode
  3. Reveal / Regenerate the API key

For more information: Authentication


Integration Flow

Step 1: Create an order

Before accepting payment, create an order in Glomopay's system.

What is an order? Learn about Orders

API documentation for order: Create Order API

Sample Request:

curl -i -X POST \
  https://api.glomopay.com/api/v1/orders \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "customer_id": "cust_E602dMzgjpDC",
    "document_id": "doc_nYUqLpuYQ0M8",
    "currency": "USD",
    "amount": 1000,
    "purpose_code": "P1401",
    "invoice_number": "RG12FF590",
    "invoice_description": "Payment requested for services provided",
    "invoice_amount": 1000,
    "reference_number": "R0001",
    "product": {
      "name": "ShieldGuard Insurance",
      "description": "Flexible insurance for belongings, travel, and digital assets; easy to manage"
    },
    "notes": {
      "key1": "value1",
      "key2": "value2"
    },
    "payment_methods": [
      "card"
    ]
  }'

Step 2: Initiate Payment with Card Details

Once you have the order, submit card details to initiate payment.

Endpoint:

POST https://api.glomopay.com/api/v1/payments

Request Body:

{
  "order_id": "order_68c00b7btsthf",
  "method": "card",
  "card": {
    "holder_name": "John Doe",
    "number": "4111111111111111",
    "expiry_month": "09",
    "expiry_year": "2030",
    "cvv": "123"
  },
  "callback_url": "https://server.yoursite.com/payment/callback",
  "notes": {
    "internal_ref": "ref_12345"
  }
}

Response:

{
  "payment_id": "payt_691eeb9aV79Uk",
  "status": "pending",
  "next_steps": [
    {
      "action": "redirect",
      "payload": {
        "url": "https://secure.glomopay.com?paymentId=payt_123&authToken=ey...&redirectUrl=encoded_url"
      }
    },
    {
      "action": "poll",
      "payload": {
        "url": "https://api.glomopay.com/api/v1/payments/payt_691eeb9aV79Uk",
        "interval_in_ms": 5000
      }
    }
  ]
}

Step 3: Handle Redirect

The response contains a redirect URL where the user needs to complete authentication (3DS, OTP, etc.).

MethodUse CaseImplementation
New TabWebwindow.open(redirectUrl, '_blank')
Same TabWebwindow.location.href = redirectUrl
WebViewMobile appsOpen URL in native WebView component

Step 4: Handle Callback

After payment processing, Glomopay redirects the user back to your callback_url with query parameters.

Callback URL Format:

https://server.yoursite.com/payment/callback?order_id=order_XXX&payment_id=payt_XXX&status=success&signature=abc123

Query Parameters:

ParameterDescriptionValues
order_idThe order identifierorder_XXX
payment_idThe payment identifierpayt_XXX
statusPayment outcomesuccess, failed
signatureHMAC signature for verificationSHA-256 hash
errorSomething went wrong in the payment journeymessage

Step 5: Verify Signature

Always verify the signature on your server to ensure the callback is authentic. The callback URL should point to your server, where you can perform this verification. The necessary information for verification will be sent in the query parameters. The response of this API call should ideally be a redirect to your frontend.

Sample Code:

JavaScript
const express = require('express');
const crypto = require('crypto');
const router = express.Router();

// Your Glomopay secret key (store in environment variables)
const GLOMOPAY_SECRET_KEY = process.env.GLOMOPAY_SECRET_KEY;

/**
 * Generate HMAC SHA256 signature for verification
 */
function generateSignature(orderId, paymentId, status, secret) {
  const data = `${orderId}|${paymentId}|${status}`;
  return crypto.createHmac('sha256', secret).update(data).digest('hex');
}

/**
 * Glomopay Payment Callback Handler
 */
router.get('/payment/callback', (req, res) => {
  // Extract query parameters
  const { order_id, payment_id, status, signature } = req.query;

  // Generate signature for verification
  const calculatedSignature = generateSignature(order_id, payment_id, status, GLOMOPAY_SECRET_KEY);

  // Verify signature
  if (signature !== calculatedSignature) {
    console.error('Signature verification failed');
    return res.redirect(`/payment/error?message=Invalid signature`);
  }

  // Signature is valid - proceed based on payment status
  console.log('Payment verified successfully');

  // Redirect based on payment status
  if (status === 'success') {
    return res.redirect(`/payment/success?order_id=${order_id}&payment_id=${payment_id}`);
  } else if (status === 'failed') {
    return res.redirect(`/payment/failed?order_id=${order_id}`);
  } else {
    return res.redirect(`/payment/error?order_id=${order_id}`);
  }
});

module.exports = router;
PHP
<?php

/**
 * Generate HMAC SHA256 signature for verification
 */
function generateSignature($orderId, $paymentId, $status, $secret) {
    $data = "$orderId|$paymentId|$status";
    return hash_hmac('sha256', $data, $secret);
}

// Verify signature
$calculatedSignature = generateSignature($orderId, $paymentId, $status, $glomopaySecretKey);
if ($signature !== $calculatedSignature) {
    // Signature verification failed
}
Ruby
require 'openssl'

# Generate HMAC SHA256 signature for verification
def generate_signature(order_id, payment_id, status, secret)
  data = "#{order_id}|#{payment_id}|#{status}"
  OpenSSL::HMAC.hexdigest('SHA256', secret, data)
end

# Verify signature
calculated_signature = generate_signature(order_id, payment_id, status, GLOMOPAY_SECRET_KEY)
if signature != calculated_signature
  # Signature verification failed
end
Go
import (
    "crypto/hmac"
    "crypto/sha256"
    "encoding/hex"
    "fmt"
)

// generateSignature creates HMAC SHA256 signature for verification
func generateSignature(orderID, paymentID, status, secret string) string {
    data := fmt.Sprintf("%s|%s|%s", orderID, paymentID, status)

    h := hmac.New(sha256.New, []byte(secret))
    h.Write([]byte(data))

    return hex.EncodeToString(h.Sum(nil))
}

// Verify signature
calculatedSignature := generateSignature(orderID, paymentID, status, glomopaySecretKey)
if calculatedSignature != signature {
    // Signature verification failed
}
Java
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;

public static boolean verifySignature(String orderId, String paymentId, String status,
                                      String signature, String secret) {
    try {
        String data = orderId + "|" + paymentId + "|" + status;
        Mac mac = Mac.getInstance("HmacSHA256");
        mac.init(new SecretKeySpec(secret.getBytes(), "HmacSHA256"));

        byte[] hash = mac.doFinal(data.getBytes());
        StringBuilder hex = new StringBuilder();
        for (byte b : hash) hex.append(String.format("%02x", b));

        return hex.toString().equals(signature);
    } catch (Exception e) {
        return false;
    }
}

Step 6: Handle Webhooks

Webhooks deliver server-to-server notifications about payment events directly to your backend.

For complete webhook implementation details: Webhooks Documentation


Testing

Test Cards

Use these cards in sandbox mode to simulate different scenarios: Test Card Details


For technical support, contact your integration manager or reach out via the merchant dashboard.