Global Payments Pay by Link

This repository provides comprehensive Pay by Link implementations using the Global Payments GP API across six programming languages. Pay by Link allows merchants to create secure payment links that can be shared with customers via email, SMS, or other channels, enabling remote payments without requiring customers to visit a physical location or website.

Available Implementations

• .NET Core - (Preview) - ASP.NET Core web application
• Go - (Preview) - Go HTTP server application
• Java - (Preview) - Jakarta EE servlet-based web application
• Node.js - (Preview) - Express.js web application
• PHP - (Preview) - PHP web application
• Python - (Preview) - Flask web application

Features

Core Pay by Link Functionality

• Payment Link Creation - Generate secure, time-limited payment links
• Multi-Currency Support - EUR, USD, GBP currency support
• Input Validation - Comprehensive validation and sanitization
• Error Handling - Standardized error responses across all languages
• GP API Integration - Direct integration with Global Payments sandbox/production APIs

Implementation Features

• Consistent API - Identical /create-payment-link endpoint across all languages
• Environment Configuration - Secure credential management with .env files
• Responsive Frontend - HTML forms with real-time validation
• Production Ready - Comprehensive error handling and logging
• OWASP Compliant - Input sanitization and security best practices

Quick Start

1. Choose Your Language

Navigate to any implementation directory:

cd nodejs/    # Node.js with Express
cd python/    # Python with Flask
cd php/       # Native PHP
cd java/      # Java with Jakarta EE
cd dotnet/    # .NET Core
cd go/        # Go HTTP server

2. Set Up Environment

Copy the sample environment file and add your GP API credentials:

cp .env.sample .env

Edit .env with your actual GP API credentials:

# GP API App Credentials (required for Pay by Link)
GP_API_APP_ID=your_app_id_here
GP_API_APP_KEY=your_app_key_here

# Environment (sandbox or production)
GP_API_ENVIRONMENT=sandbox

3. Install Dependencies

Node.js:

npm install

Python:

pip install -r requirements.txt

PHP:

composer install

Java:

mvn clean install

Go:

go mod download

.NET:

dotnet restore

4. Run the Server

Node.js:

npm start
# or
node server.js

Python:

python server.py

PHP:

php -S localhost:8000 -t .

Java:

mvn cargo:run

Go:

go run main.go

.NET:

dotnet run

5. Test the Implementation

Visit http://localhost:8000 and create a test payment link:

1. Enter amount in cents (e.g., 1000 = $10.00)
2. Select currency (EUR, USD, GBP)
3. Provide reference, name, and description
4. Click "Create Payment Link"
5. Copy the generated payment link to share with customers

API Endpoints

GET /config

Returns configuration data for client-side use:

{
  "success": true,
  "data": {
    "environment": "sandbox",
    "supportedCurrencies": ["EUR", "USD", "GBP"],
    "supportedPaymentMethods": ["CARD"]
  }
}

POST /create-payment-link

Creates a new payment link. Required fields:

• amount (integer) - Amount in cents
• currency (string) - Currency code (EUR/USD/GBP)
• reference (string) - Merchant reference
• name (string) - Payment name/title
• description (string) - Payment description

Success Response:

{
  "success": true,
  "message": "Payment link created successfully! Link ID: lnk_xxx",
  "data": {
    "paymentLink": "https://pay.sandbox.globalpay.com/link/lnk_xxx",
    "linkId": "lnk_xxx",
    "reference": "ORDER-123",
    "amount": 1000,
    "currency": "USD"
  }
}

Error Response:

{
  "success": false,
  "message": "Payment link creation failed",
  "error": {
    "code": "MISSING_REQUIRED_FIELDS",
    "details": "Missing required fields. Received: amount, currency"
  }
}

Test Cards

Brand	Number	CVV	Expiry
Visa	4263 9826 4026 9299	123	Any future
Mastercard	5425 2334 2424 1200	123	Any future

Pay by Link generates a hosted payment page. Test cards work when completing payment through the generated link in sandbox mode.

Payment Link Configuration

All implementations create payment links with these settings:

• Type: PAYMENT (single-use payment)
• Usage Mode: SINGLE (one-time use)
• Usage Limit: 1
• Expiration: 10 days from creation
• Channel: CNP (Card Not Present)
• Country: GB (Great Britain)
• Shipping: YES with 0 amount
• Payment Methods: CARD only
• Notifications:
  • Return URL: https://www.example.com/returnUrl
  • Status URL: https://www.example.com/statusUrl
  • Cancel URL: https://www.example.com/returnUrl

Input Validation & Security

Reference Sanitization

All implementations sanitize the reference field using regex pattern [^\w\s\-#] to remove potentially harmful characters, allowing only:

• Word characters (letters, digits, underscore)
• Spaces, hyphens, and hash symbols
• Limited to 100 characters maximum

Field Validation

• Amount: Must be positive integer (cents)
• Currency: Must be one of EUR, USD, GBP
• Name: Trimmed and limited to 100 characters
• Description: Trimmed and limited to 500 characters
• Reference: Sanitized and limited to 100 characters

Error Handling

Standardized error codes across all implementations:

• MISSING_REQUIRED_FIELDS - Required fields missing from request
• INVALID_AMOUNT - Amount is not a positive integer
• TOKEN_GENERATION_ERROR - Failed to generate GP API access token
• API_ERROR - GP API request failed
• INVALID_RESPONSE - Unexpected response format from GP API
• UNKNOWN_ERROR - Unexpected system error

Prerequisites

• Global Payments Account with GP API credentials
• Development Environment for your chosen language
• Package Manager (npm, pip, composer, maven, dotnet, go)
• GP API Credentials:
  • App ID (GP_API_APP_ID)
  • App Key (GP_API_APP_KEY)

Production Deployment

Environment Variables

Set production environment variables:

GP_API_APP_ID=your_production_app_id
GP_API_APP_KEY=your_production_app_key
GP_API_ENVIRONMENT=production

Security Considerations

• Use HTTPS for all production deployments
• Validate inputs on both client and server side
• Log transactions for audit and debugging
• Monitor failed requests for potential issues
• Rate limit the API endpoints
• Secure credential storage using environment variables or secrets management

URL Configuration

Update notification URLs in production:

notifications: {
  return_url: "https://yourdomain.com/payment-return",
  status_url: "https://yourdomain.com/payment-webhook",
  cancel_url: "https://yourdomain.com/payment-cancel"
}

Architecture Notes

Direct API vs SDK

• SDK Implementations: PHP, Java, .NET (use official Global Payments SDKs with PayByLinkService)
• Direct API Implementations: Python, Node.js, Go (use direct HTTP calls to https://apis.sandbox.globalpay.com/ucp/links)
• Consistency: All implementations achieve identical functionality regardless of approach

Technical Implementation Details

SDK Approach (PHP, Java, .NET):

• Uses official Global Payments SDK packages (globalpayments/api, globalpayments-sdk, GlobalPayments.Api)
• SDK handles authentication token generation automatically
• Provides type-safe PayByLinkData objects and PayByLinkService classes
• Built-in error handling with SDK-specific exception types
• Automatic API endpoint routing based on environment configuration

Direct API Approach (Python, Node.js, Go):

• Makes raw HTTP POST requests to Global Payments REST endpoints
• Handles authentication token generation manually
• Constructs JSON payloads directly
• Processes HTTP responses and error handling manually
• Examples: Python (requests), Go (net/http), Node.js (fetch/axios)

Response Format

All implementations return identical JSON response formats to ensure consistent client-side handling across different backend languages.

Error Handling Strategy

Each implementation includes try-catch blocks with specific error categorization, ensuring consistent error reporting and debugging capabilities.

Community

• 🌐 Developer Portal — developer.globalpayments.com
• 💬 Discord — Join the community
• 📋 GitHub Discussions — github.com/orgs/globalpayments/discussions
• 📧 Newsletter — Subscribe
• 💼 LinkedIn — Global Payments for Developers

Have a question or found a bug? Open an issue or reach out at communityexperience@globalpay.com.

License

This project is licensed under the MIT License - see individual implementation directories for specific license details.