Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/globalpayments-samples/pay-by-link

Pay by Link implementation for Global Payments API Platform. Create secure payment links for remote transactions with multi-currency support.
https://github.com/globalpayments-samples/pay-by-link

api-platform ecommerce global-payments lang-dotnet lang-go lang-java lang-nodejs lang-php lang-python multi-currency pay-by-link payment-links payment-processing remote-payments

Last synced: 1 day ago
JSON representation

Pay by Link implementation for Global Payments API Platform. Create secure payment links for remote transactions with multi-currency support.

Awesome Lists containing this project

README 

          
# 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](./dotnet/) - ([Preview](https://githubbox.com/globalpayments-samples/pay-by-link/tree/main/dotnet)) - ASP.NET Core web application

- [Go](./go/) - ([Preview](https://githubbox.com/globalpayments-samples/pay-by-link/tree/main/go)) - Go HTTP server application

- [Java](./java/) - ([Preview](https://githubbox.com/globalpayments-samples/pay-by-link/tree/main/java)) - Jakarta EE servlet-based web application

- [Node.js](./nodejs/) - ([Preview](https://githubbox.com/globalpayments-samples/pay-by-link/tree/main/nodejs)) - Express.js web application

- [PHP](./php/) - ([Preview](https://githubbox.com/globalpayments-samples/pay-by-link/tree/main/php)) - PHP web application

- [Python](./python/) - ([Preview](https://githubbox.com/globalpayments-samples/pay-by-link/tree/main/python)) - 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



## Payment Flow



Pay by Link is an asynchronous two-stage flow. The merchant creates the link server-side; the customer pays on a GP-hosted page with no merchant frontend involved.



```mermaid

sequenceDiagram

    participant M as Merchant Backend

    participant GP as GP API

    participant C as Customer



    M->>GP: POST /create-payment-link
(amount, currency, reference)

    GP-->>M: { paymentLink: "https://pay.globalpay.com/lnk_xxx" }

    Note over M,C: Merchant shares link via email, SMS, or any channel

    M->>C: Payment link

    C->>GP: Opens payment link

    GP-->>C: Hosted payment page (no merchant frontend)

    C->>GP: Submits card details

    GP-->>C: Payment confirmation

    GP-->>M: Webhook notification (status_url)

```



## Quick Start



### 1. Choose Your Language

Navigate to any implementation directory:

```bash

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:



```bash

cp .env.sample .env

```



Edit `.env` with your actual GP API credentials:



```env

# 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:**

```bash

npm install

```



**Python:**

```bash

pip install -r requirements.txt

```



**PHP:**

```bash

composer install

```



**Java:**

```bash

mvn clean install

```



**Go:**

```bash

go mod download

```



**.NET:**

```bash

dotnet restore

```



### 4. Run the Server



**Node.js:**

```bash

npm start

# or

node server.js

```



**Python:**

```bash

python server.py

```



**PHP:**

```bash

php -S localhost:8000 -t .

```



**Java:**

```bash

mvn cargo:run

```



**Go:**

```bash

go run main.go

```



**.NET:**

```bash

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:



```json

{

  "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:**

```json

{

  "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:**

```json

{

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



```env

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:



```javascript

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](https://developer.globalpayments.com)

- 💬 **Discord** — [Join the community](https://discord.gg/myER9G9qkc)

- 📋 **GitHub Discussions** — [github.com/orgs/globalpayments/discussions](https://github.com/orgs/globalpayments/discussions)

- 📧 **Newsletter** — [Subscribe](https://www.globalpayments.com/en-gb/modals/newsletter)

- 💼 **LinkedIn** — [Global Payments for Developers](https://www.linkedin.com/showcase/global-payments-for-developers/posts/?feedView=all)



Have a question or found a bug? [Open an issue](https://github.com/globalpayments-samples/pay-by-link/issues) or reach out at [communityexperience@globalpay.com](mailto:communityexperience@globalpay.com).



## License



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