Payment Gateway API Documentation

Overview

The Payment Gateway API allows you to process payments, manage transactions, and handle refunds programmatically. This RESTful API uses JSON for request and response payloads.

Base URL: https://api.paymentgateway.com/v1

Authentication: Bearer Token

Getting Started

Prerequisites

Before you begin, ensure you have:

• An active account with Payment Gateway
• API credentials (API Key and Secret)
• Basic understanding of RESTful APIs
• A development environment capable of making HTTPS requests

Quick Start

1. Sign up for an API account
2. Generate your API credentials from the dashboard
3. Make your first API call using the examples below
4. Review the response and error codes

Authentication

All API requests require authentication using Bearer tokens. Include your API key in the Authorization header:

curl -X GET https://api.paymentgateway.com/v1/transactions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Generating an API Key

const response = await fetch('https://api.paymentgateway.com/v1/auth/token', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    client_id: 'your_client_id',
    client_secret: 'your_client_secret'
  })
});

const data = await response.json();
console.log(data.access_token);

Core Endpoints

Create Payment

Process a new payment transaction.

Endpoint: POST /payments

Request Body:

{
  "amount": 5000,
  "currency": "USD",
  "payment_method": "card",
  "customer": {
    "email": "customer@example.com",
    "name": "John Doe"
  },
  "card": {
    "number": "4242424242424242",
    "exp_month": 12,
    "exp_year": 2025,
    "cvc": "123"
  },
  "description": "Order #12345"
}

Response:

{
  "id": "pay_1234567890",
  "status": "succeeded",
  "amount": 5000,
  "currency": "USD",
  "created": 1699564800,
  "customer": {
    "id": "cus_abc123",
    "email": "customer@example.com"
  }
}

List Transactions

Retrieve a paginated list of all transactions.

Endpoint: GET /transactions

Query Parameters:

Example Request:

import requests

url = "https://api.paymentgateway.com/v1/transactions"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
}
params = {
    "limit": 20,
    "status": "succeeded"
}

response = requests.get(url, headers=headers, params=params)
print(response.json())

Refund Payment

Issue a full or partial refund for a completed payment.

Endpoint: POST /payments/{payment_id}/refund

Path Parameters:

• payment_id (string, required): The ID of the payment to refund

Request Body:

{
  "amount": 2500,
  "reason": "customer_request"
}

Data Models

Payment Object

Customer Object

Error Codes

The API uses standard HTTP status codes and returns detailed error messages:

Error Response Format:

{
  "error": {
    "type": "invalid_request_error",
    "code": "amount_too_small",
    "message": "Amount must be at least $0.50 USD",
    "param": "amount"
  }
}

Rate Limiting

API requests are limited to:

• 100 requests per minute for standard accounts
• 500 requests per minute for premium accounts

Rate limit information is included in response headers:

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

Webhooks

Subscribe to events to receive real-time updates about payments and transactions.

Supported Events

• payment.succeeded
• payment.failed
• refund.created
• customer.created

Webhook Payload Example

{
  "id": "evt_1234567890",
  "type": "payment.succeeded",
  "created": 1699564800,
  "data": {
    "object": {
      "id": "pay_1234567890",
      "amount": 5000,
      "currency": "USD",
      "status": "succeeded"
    }
  }
}

Verifying Webhook Signatures

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

SDK Libraries

Official SDKs are available for multiple languages:

• Node.js: npm install paymentgateway-node
• Python: pip install paymentgateway
• Ruby: gem install paymentgateway
• PHP: composer require paymentgateway/paymentgateway-php

Node.js Example

const PaymentGateway = require('paymentgateway-node');
const gateway = new PaymentGateway('YOUR_API_KEY');

async function createPayment() {
  const payment = await gateway.payments.create({
    amount: 5000,
    currency: 'USD',
    payment_method: 'card',
    customer: {
      email: 'customer@example.com'
    }
  });
  
  console.log(payment);
}

Testing

Use these test card numbers in sandbox mode:

Sandbox Base URL: https://sandbox.paymentgateway.com/v1

Architecture Diagram

Figure 1: High-level architecture showing client applications, API gateway, payment processor, and database interactions.

Support

For additional help:

• Documentation: https://docs.paymentgateway.com
• Support Email: support@paymentgateway.com
• Status Page: https://status.paymentgateway.com
• Community Forum: https://community.paymentgateway.com

Changelog

Version 1.2.0 (2024-11-15)

• Added support for Apple Pay and Google Pay
• Improved error messages for declined cards
• New webhook event: customer.updated

Version 1.1.0 (2024-10-01)

• Added refund endpoint
• Increased rate limits for premium accounts
• Bug fixes and performance improvements

Version 1.0.0 (2024-09-01)

• Initial release
• Core payment processing
• Customer management
• Basic webhook support