GSM Pay API

Base URL

All API endpoints are relative to this base URL:

https://gsmpay.world/api

Authentication

All API requests require authentication using your API key. Include it in the request headers:

X-API-Key: your_api_key_here

Parameter	Type	Description
X-API-Key	string	Your unique API key provided by GSM Pay

Create Payment

Initialize a new payment request. This endpoint creates a payment transaction and returns a payment URL.

Request Headers

Header	Value	Description
Content-Type	application/json	Must be set to application/json
X-API-Key	your_api_key	Your authentication key

Request Body Parameters

Parameter	Type	Required	Description
amount	number	Required	Payment amount (minimum: 1)
customer_name	string	Required	Full name of the customer
customer_email	string	Required	Valid email address for payment confirmation
additional_id	string	Optional	Your internal order/reference ID (max 50 chars)

Example Request

curl -X POST https://gsmpay.world/api/payment/create \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key_here" \
  -d '{
    "amount": 100.00,
    "customer_name": "John Doe",
    "customer_email": "john.doe@example.com",
    "additional_id": "ORDER-2024-00123"
  }'

Success Response (200 OK)

{
  "status": "success",
  "message": "Payment created successfully",
  "data": {
    "payment_id": "PAY_8f7d3a1e2b4c5d6e",
    "payment_url": "https://gsmpay.world/pay/PAY_8f7d3a1e2b4c5d6e",
    "amount": 100.00,
    "currency": "USD",
    "expires_at": "2024-01-20T15:30:00Z",
    "additional_id": "ORDER-2024-00123"
  }
}

Error Response (400 Bad Request)

{
  "status": "error",
  "message": "Validation failed",
  "errors": {
    "amount": "Amount must be at least 1",
    "customer_email": "Invalid email format"
  }
}

Check Payment Status

Query the status of an existing payment transaction.

Request Body Parameters

Parameter	Type	Required	Description
altid	string	Required	Your additional_id from the create payment request

Example Request

curl -X POST https://gsmpay.world/api/payment/ascertain \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key_here" \
  -d '{
    "altid": "ORDER-2024-00123"
  }'

Success Response

{
  "status": "completed",
  "amount": 100.00,
  "reference_id": "ORDER-2024-00123",
  "payment_method": "credit_card",
  "paid_at": "2024-01-20T14:35:22Z",
  "transaction_id": "TXN_8f7d3a1e2b4c5d6e"
}

Payment Statuses

The following status values are used throughout the API:

Status	Description	Webhook Sent
pending	Awaiting customer payment	No
processing	Verifying payment with provider	No
completed	Payment successful	Yes
failed	Payment failed or expired	Yes (if payment was attempted)

Webhooks

GSM Pay can send real-time notifications to your server when payment statuses change.

Webhook Payload Example (POST)

{
  "event": "payment.completed",
  "data": {
    "payment_id": "PAY_8f7d3a1e2b4c5d6e",
    "additional_id": "ORDER-2024-00123",
    "amount": 100.00,
    "status": "completed",
    "paid_at": "2024-01-20T14:35:22Z"
  },
  "timestamp": "2024-01-20T14:35:23Z"
}

Webhook Events

Event	Description
payment.completed	Payment successfully completed
payment.failed	Payment failed or expired
payment.processing	Payment is being processed

Error Codes

HTTP Status	Error Code	Description
400	VALIDATION_ERROR	Invalid request parameters
401	UNAUTHORIZED	Missing or invalid API key
403	FORBIDDEN	API key doesn't have permission
404	NOT_FOUND	Payment not found
429	RATE_LIMITED	Too many requests
500	SERVER_ERROR	Internal server error

Integration Examples

PHP

<?php
$apiKey = 'your_api_key_here';
$baseUrl = 'https://gsmpay.world/api';

function createPayment($amount, $customerName, $customerEmail, $additionalId = null) {
    global $apiKey, $baseUrl;
    
    $data = [
        'amount' => $amount,
        'customer_name' => $customerName,
        'customer_email' => $customerEmail
    ];
    
    if ($additionalId) {
        $data['additional_id'] = $additionalId;
    }
    
    $ch = curl_init($baseUrl . '/payment/create');
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'Content-Type: application/json',
        'X-API-Key: ' . $apiKey
    ]);
    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_TIMEOUT, 30);
    
    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);
    
    if ($httpCode === 200) {
        return json_decode($response, true);
    }
    
    return false;
}

// Example usage
$result = createPayment(100.00, 'John Doe', 'john@example.com', 'ORDER-123');
if ($result && $result['status'] === 'success') {
    header('Location: ' . $result['data']['payment_url']);
    exit;
}
?>

JavaScript (Node.js)

const axios = require('axios');

const API_KEY = 'your_api_key_here';
const BASE_URL = 'https://gsmpay.world/api';

async function createPayment(paymentData) {
    try {
        const response = await axios.post(`${BASE_URL}/payment/create`, {
            amount: paymentData.amount,
            customer_name: paymentData.customerName,
            customer_email: paymentData.customerEmail,
            additional_id: paymentData.orderId
        }, {
            headers: {
                'Content-Type': 'application/json',
                'X-API-Key': API_KEY
            }
        });
        
        return response.data;
    } catch (error) {
        console.error('Payment creation failed:', error.response?.data || error.message);
        throw error;
    }
}

// Example usage
createPayment({
    amount: 100.00,
    customerName: 'John Doe',
    customerEmail: 'john@example.com',
    orderId: 'ORDER-123'
}).then(result => {
    if (result.status === 'success') {
        console.log('Payment URL:', result.data.payment_url);
    }
});

Python

import requests
import json

API_KEY = 'your_api_key_here'
BASE_URL = 'https://gsmpay.world/api'

def create_payment(amount, customer_name, customer_email, additional_id=None):
    headers = {
        'Content-Type': 'application/json',
        'X-API-Key': API_KEY
    }
    
    data = {
        'amount': amount,
        'customer_name': customer_name,
        'customer_email': customer_email
    }
    
    if additional_id:
        data['additional_id'] = additional_id
    
    response = requests.post(
        f'{BASE_URL}/payment/create',
        headers=headers,
        json=data
    )
    
    return response.json()

# Example usage
result = create_payment(100.00, 'John Doe', 'john@example.com', 'ORDER-123')
if result.get('status') == 'success':
    print(f"Payment URL: {result['data']['payment_url']}")

Best Practices

• Idempotency: Use the additional_id field to prevent duplicate payments.
• Error Handling: Always implement proper error handling for API calls.
• Webhook Verification: Verify webhook signatures to ensure they come from GSM Pay.
• Rate Limiting: Implement exponential backoff for retries when rate limited.
• Timeouts: Set appropriate timeout values for API calls (recommended: 30 seconds).

Rate Limits

Endpoint	Limit	Window
/payment/create	100 requests	per minute
/payment/ascertain	300 requests	per minute

Rate limit headers are included in all responses:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1642694400

Support & Contact

Need help with integration? Contact our support team: