# File: docs/payment-buttons.md

---
sidebar_position: 7
---

# Payment Buttons

Integrate hosted payment buttons into your website with just a few lines of code.

## Overview

PaysGator Payment Buttons provide a seamless, secure checkout experience. Instead of building your own checkout forms, you can use our hosted solution that handles payment processing, security, and compliance.

## Quick Start

### 1. Create a Payment Button

Go to **Dashboard → Developers → Payment Buttons** and create a new button. You'll receive a `buttonKey` (Public Key) for the button.

### 2. Add the Script

Include our JavaScript SDK in your HTML page:

```html
<script src="https://paysgator.com/js/paysgator.js"></script>
```

### 3. Add a Payment Button

Use data attributes to quickly add a button:

```html
<button 
    data-paysgator-button="your_button_key"
    data-amount="100.00"
    data-currency="USD"
    data-button-text="Pay Now"
>
    Pay Now
</button>
```

## JavaScript API (More Control)

Initialize programmatically for more control:

```javascript
PaysGator.init({
    buttonKey: 'your_button_key',
    container: '#payment-button',
    amount: 100.00,
    currency: 'USD',
    
    onSuccess: function(result) {
        console.log('Payment successful!', result.transactionId);
    },
    
    onError: function(error) {
        console.error('Payment failed:', error);
    }
});
```

---

> [!NOTE]
> Payment buttons use **Public Keys** (button keys) which are safe to use in client-side code. Your **API Secret Keys** for server-side requests must never be exposed.

# File: docs/authentication.md

---
sidebar_position: 2
---

# Authentication

The PaysGator API uses API Keys for authentication. All requests should include your API Key in the `X-Api-Key` header.

## API Keys

You can find your API keys in the PaysGator Dashboard under the Developers section. There are two types of keys:

- **LIVE Keys**: Used for real transactions.
- **TEST Keys**: Used for testing and integration. No real money is moved.

> [!IMPORTANT]
> Keep your API keys secret. Do not share them or include them in client-side code (frontend).

## How to Authenticate

Include the `X-Api-Key` header in all your API requests.

```http
X-Api-Key: pg_live_your_api_key_here
```

### Example Curl Request

```bash
curl -X GET "https://paysgator.com/api/v1/wallet/balance" \
     -H "X-Api-Key: YOUR_API_KEY"
```

## Error Responses

- **401 Unauthorized**: The API Key is missing or invalid.
- **403 Forbidden**: You do not have permission to access the requested resource (e.g., trying to access a LIVE transaction with a TEST key).

# File: docs/tutorials/python.md

# Paysgator Python SDK

Official Python client for the Paysgator API.

## Installation

```bash
pip install paysgator
```

## Usage

```python
from paysgator import PaysgatorClient

client = PaysgatorClient(api_key="YOUR_API_KEY")

# Create a payment
payment = client.payments.create(
    amount=100.0,
    currency="MZN",
    payment_methods=["MPESA", "CARD"],
    return_url="https://example.com/callback",
    fields=["name", "email"]
)
print(f"Payment Link: {payment.data.checkout_url}")
print(f"Transaction ID: {payment.data.transaction_id}")

# Confirm a payment (Server-side)
confirmation = client.payments.confirm(
    payment_link_id="payment_link_uuid",
    payment_method="MPESA",
    payment_fields={"phoneNumber": "841234567"}
)
print(f"Confirmed Transaction: {confirmation.data.transaction_id}")

# Check Balance
balance = client.wallet.get_balance()
print(f"Balance: {balance.balance} {balance.currency}")
```

# File: docs/tutorials/php.md

# Paysgator PHP Client

A PHP client library for the Paysgator API.

## Installation

Install via Composer:

```bash
composer require paysgator/paysgator-php
```

## Usage

### Configuration

For most requests, you simply need to provide your API Key.

```php
require 'vendor/autoload.php';

use Paysgator\PaysgatorClient;

$client = new PaysgatorClient([
    'api_key' => 'YOUR_API_KEY',
]);
```

### Create Payment

Create a payment transaction.

```php
$paymentData = [
    'amount' => 100,
    'currency' => 'MZN',
    'payment_methods' => ['MPESA', 'CARD'],
    'returnUrl' => 'https://mysite.com/return',
    'fields' => ['name', 'email']
];

try {
    $result = $client->payments()->create($paymentData);
    echo "Payment Link: " . $result['data']['checkoutUrl'];
    echo "Transaction ID: " . $result['data']['transactionId'];
} catch (\Exception $e) {
    echo "Error: " . $e->getMessage();
}
```

### Confirm Payment

Confirm a payment server-side.

```php
try {
    $confirmation = $client->payments()->confirm([
        'paymentLinkId' => 'payment_uuid',
        'paymentMethod' => 'MPESA',
        'payment_fields' => ['phoneNumber' => '841234567']
    ]);
    print_r($confirmation);
} catch (\Exception $e) {
    echo "Error: " . $e->getMessage();
}
```

### Subscriptions

Manage subscriptions.

```php
// Pause a subscription
$client->subscriptions()->update('sub_123', 'pause');
```

### Transactions

Retrieve transaction details.

```php
$transaction = $client->transactions()->get('txn_123');
print_r($transaction);
```

### Wallet

Check wallet balance.

```php
$balance = $client->wallet()->getBalance();
echo "Balance: " . $balance['balance'] . " " . $balance['currency'];
```

## Support

For issues and support, please contact info@paysgator.com.

# File: docs/tutorials/nodejs.md

# PaysGator Client for Node.js

Official JavaScript/TypeScript client library for the PaysGator API.

## Installation

Install the package using npm:

```bash
npm install paysgator-clientjs
```

## Configuration

Import and configure the client with your credentials:

```javascript
const { PaysGator } = require('paysgator-clientjs');

const client = new PaysGator({
  apiKey: 'YOUR_API_KEY'
});
```

For TypeScript/ES Modules:

```typescript
import { PaysGator } from 'paysgator-clientjs';

const client = new PaysGator({
  apiKey: 'YOUR_API_KEY'
});
```

## Usage

### Create Payment
```javascript
const payment = await client.payments.create({
  amount: 100,
  currency: 'MZN', // or USD, AOA
  payment_methods: ['MPESA', 'CARD'],
  returnUrl: 'https://example.com/callback',
  fields: ['name', 'email']
});

console.log('Payment Link:', payment.data.checkoutUrl);
console.log('Transaction ID:', payment.data.transactionId);
```

### Confirm Payment (Server-side)

```javascript
const confirmation = await client.payments.confirm({
  paymentLinkId: 'payment_link_id',
  paymentMethod: 'MPESA',
  payment_fields: {
      phoneNumber: '841234567' 
  }
});

console.log('Payment Confirmed:', confirmation.data.transactionId);
```

### Check Balance

```javascript
const balance = await client.wallet.getBalance();
console.log('Balance:', balance.balance, balance.currency);
```

### Get Transaction

```javascript
const transaction = await client.transactions.get('transaction_id');
console.log('Transaction Status:', transaction.status);
```

### Manage Subscriptions

```javascript
// Pause a subscription
await client.subscriptions.update('subscription_id', 'pause');
```

## Support

For more information or support, please contact info@paysgator.com.

# File: docs/payment-methods/overview.md

---
sidebar_position: 1
---

# Overview

## Supported Methods

Here is an overview of the payment methods supported by PaysGator, along with their types and specific details.

| Method | Type | Country | Description |
| :--- | :--- | :--- | :--- |
| **BANK CARD** | Confirm, Supports Subscriptions | MZN, AOA, USD, EUR, ZAR | Supports many card networks like VISA, Mastercard, American Express, and more. |
| **EMOLA** | Confirm | MZN | Process payment through Movitel Emola mobile money. Required fields: `phoneNumber` (9 digits starting with 86/87). |
| **MKESH** | Confirm | MZN | Process payment through Tmcel Mkesh mobile money. Required fields: `phoneNumber` (9 digits starting with 82/83). |
| **MPESA MOZAMBIQUE** | Confirm | MZN | Process payment through M-Pesa mobile money. Required fields: `phoneNumber` (9 digits starting with 84/85). |
| **MULTICAIXA EXPRESS** | Confirm | AOA | Confirm payment method from Angolan MULTICAIXA network. required fields: `phoneNumber` (9 digits starting with 92/93/94). |
| **MULTICAIXA REFERENCIA** | Manual | AOA | A Manual payment method from Multicaixa network. Users make a payment externally on the Multicaixa app using the reference and entity provided on the checkout page. |

## Payment Method Types

### Confirm
These are methods where users do not need to perform additional actions outside the checkout process. Users simply input their payment data (like bank card details or mobile money number), and the payment is processed. The payment may need to be confirmed by the bank or mobile operator (e.g., via an OTP or USSD prompt).

### Manual
For these methods, instead of inputting payment data directly to complete the transaction immediately, users receive payment information (like vouchers or references) to make a payment outside the application.

### Redirect
These payment methods may require the user to be redirected to an external service to confirm and complete the payment.

# File: docs/payment-methods/manual.md

---
sidebar_position: 3
---

# Manual Methods

Manual methods are payment types where, instead of inputting charge data to complete the transaction immediately within the app, users receive payment instructions to perform the payment externally.

## How it Works

1.  **Selection**: The user selects a manual payment method at checkout.
2.  **Instruction Generation**: The system generates specific payment details, such as a reference number, entity code, or voucher.
3.  **External Payment**: The user uses these details to make a payment outside the PaysGator application (e.g., via an ATM, internet banking app, or physical agent).

## Supported Manual Methods

### MULTICAIXA REFERENCIA (AOA)
- **Country**: Angola
- **Description**: A manual payment method from the Multicaixa network.
- **Process**: Users receive a Reference and Entity on the checkout page. They must then use these details to make a "Pagamento por Referência" (Payment by Reference) on the Multicaixa app or ATM.

# File: docs/payment-methods/confirm.md

---
sidebar_position: 2
---

# Confirm Methods

Confirm methods are payment types where users input their charge data (like bank card details, mobile money number, etc.) directly during the checkout process.

## How it Works

1.  **User Input**: The customer provides their payment details on the checkout page.
2.  **Processing**: The payment is processed immediately.
3.  **Confirmation**: The payment may need to be confirmed by the bank or mobile operator (e.g., via an USSD prompt on their phone or an OTP). No additional actions are required from the user outside of this immediate confirmation flow.

## API Usage for Merchants

For **Confirm methods (excluding Cards)**, merchants can process payments directly after creating a payment link. This is done by passing the charge data along with the `paymentLinkId` to the confirm endpoint.

> **Note**: This direct confirmation flow via API is described in the [Payments](../payments) documentation.

### Examples

Here are examples of how to confirm a payment using different clients and methods.

#### Curl

```bash
curl -X POST https://paysgator.com/api/v1/payment/confirm \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "paymentLinkId": "YOUR_PAYMENT_LINK_ID",
    "paymentMethod": "MPESA",
    "payment_fields": {
      "phoneNumber": "841234567"
    }
  }'
```

#### JavaScript (Fetch)

```javascript
const response = await fetch('https://paysgator.com/api/v1/payment/confirm', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    paymentLinkId: 'YOUR_PAYMENT_LINK_ID',
    paymentMethod: 'MPESA',
    payment_fields: {
      phoneNumber: '841234567'
    }
  })
});

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

#### Node.js Client

```javascript
const confirmation = await client.payments.confirm({
  paymentLinkId: 'payment_link_id',
  paymentMethod: 'MPESA',
  payment_fields: {
      phoneNumber: '841234567' 
  }
});

console.log('Payment Confirmed:', confirmation.data.transactionId);
```

#### PHP Client

```php
try {
    $confirmation = $client->payments()->confirm([
        'paymentLinkId' => 'payment_uuid',
        'paymentMethod' => 'MPESA',
        'payment_fields' => ['phoneNumber' => '841234567']
    ]);
    print_r($confirmation);
} catch (\Exception $e) {
    echo "Error: " . $e->getMessage();
}
```

#### Python Client

```python
# Confirm a payment (Server-side)
confirmation = client.payments.confirm(
    payment_link_id="payment_link_uuid",
    payment_method="MPESA",
    payment_fields={"phoneNumber": "841234567"}
)
print(f"Confirmed Transaction: {confirmation.data.transaction_id}")
```

## Supported Confirm Methods

### EMOLA (MZN)
- **Description**: Process payment through Movitel Emola mobile money.
- **Required Fields**: `phoneNumber`
- **Format**: A 9-digit number starting with **86** or **87**.

### MKESH (MZN)
- **Description**: Process payment through Tmcel Mkesh mobile money.
- **Required Fields**: `phoneNumber`
- **Format**: A 9-digit number starting with **82** or **83**.

### MPESA MOZAMBIQUE (MZN)
- **Description**: Process payment through M-Pesa mobile money.
- **Required Fields**: `phoneNumber`
- **Format**: A 9-digit number starting with **84** or **85**.

### MULTICAIXA EXPRESS (AOA)
- **Description**: Confirm payment method from the Angolan MULTICAIXA network.
- **Required Fields**: `phoneNumber`
- **Format**: A 9-digit number starting with **92**, **93**, or **94**.

### BANK CARD (MZN, AOA, USD, EUR, ZAR)
- **Description**: Supports many card networks like VISA, Mastercard, American Express, and more.
- **Note**: While classified as a "Confirm" method, card payments follows a strict security flow and generally adhere to specific PCI compliance standards.

# File: docs/payment-methods/redirect.md

---
sidebar_position: 4
---

# Redirect Methods

Redirect methods are payment types that require the user to be redirected to an external service or page to confirm and complete the payment.

## How it Works

1.  **Initiation**: The user selects a redirect payment method at checkout.
2.  **Redirection**: The user is redirected away from the PaysGator checkout page to a third-party secure payment page (e.g., a bank's login page, a wallet service request).
3.  **Confirmation**: The user authenticates and confirms the payment on the external site.
4.  **Return**: After successful (or failed) confirmation, the user is redirected back to the merchant's website.

*Currently, no specific redirect methods are listed in this documentation section, but the architecture supports them.*

# File: docs/payment-methods/currencies.md

---
sidebar_position: 5
---

# Currencies and Countries

PaysGator supports transactions in specific countries and currencies. Below is the list of supported regions and currency codes.

## Supported Countries

| Country | Code |
| :--- | :--- |
| **Angola** | AO |
| **Mozambique** | MZ |

## Supported Currencies

| Currency Name | Code |
| :--- | :--- |
| **Kwanza Angola** | AOA |
| **Metical** | MZN |
| **United States Dollar** | USD |
| **Euro** | EUR |
| **South African Rand** | ZAR |

# File: docs/subscriptions.md

---
sidebar_position: 4
---

# Subscriptions

Manage customer subscriptions.

## Update Subscription

Update the status of an existing subscription. Use this endpoint to cancel, pause, or resume a subscription.

**Endpoint:** `PATCH /subscriptions/{id}`

### Parameters

| Parameter | Type | Description | Required |
| :--- | :--- | :--- | :--- |
| `id` | string | The UUID of the subscription | Yes |

### Request Body

| Field | Type | Description | Required |
| :--- | :--- | :--- | :--- |
| `action` | string | Action to perform: `cancel`, `pause`, or `resume` | Yes |

### Example Request

```json
{
  "action": "cancel"
}
```

### Success Response

```json
{
  "id": "uuid-v4-subscription-id",
  "status": "CANCELED",
  "customerEmail": "customer@example.com",
  "currentPeriodEnd": "2023-11-27T10:00:00Z"
}
```

### Error Responses

- **400 Bad Request**: Invalid action.
- **401 Unauthorized**: Missing or invalid API key.
- **403 Forbidden**: Unauthorized access to this subscription.
- **404 Not Found**: Subscription not found.

# File: docs/wallet.md

---
sidebar_position: 6
---

# Wallet

Manage your wallet and check balances.

## Get Wallet Balance

Retrieve the current balance of your wallet associated with the API key.

**Endpoint:** `GET /wallet/balance`

### Success Response

```json
{
  "walletId": "uuid-v4-wallet-id",
  "currency": "USD",
  "balance": "1000.00",
  "mode": "LIVE"
}
```

### Error Responses

- **401 Unauthorized**: Missing or invalid API key.
- **404 Not Found**: Wallet not found.

# File: docs/webhooks.md

# Webhooks

Listen for real-time events to keep your system in sync with PaysGator.

## Overview

Webhooks allow PaysGator to send real-time notifications to your server when events occur.

## Supported Events

| Event | Description |
| :--- | :--- |
| `payment.success` | Triggered when a payment is successfully completed. |
| `payment.failed` | Triggered when a payment attempt fails. |
| `subscription.created` | Triggered when a new subscription is created. |
| `subscription.deleted` | Triggered when a subscription is canceled. |
| `withdraw.completed` | Triggered when a withdrawal is finished. |
| `withdraw.failed` | Triggered when a withdrawal fails. |

## Webhook Structure

All webhook requests follow this standard envelope:

```json
{
  "event": "payment.success",
  "eventId": "evt_uuid_v4",
  "timestamp": "2023-10-27T10:00:00Z",
  "environment": "production",
  "data": { ... }
}
```

## Security

PaysGator sends a `X-Paysgator-Signature` header with every webhook request. This is an HMAC-SHA256 signature of the request body using your **Webhook Secret**.

## Payload Examples

### Payment Success (`payment.success`)

```json
{
  "event": "payment.success",
  "eventId": "evt_123...",
  "timestamp": "2023-10-27T10:00:00Z",
  "environment": "production",
  "data": {
    "paymentId": "uuid-v4",
    "transactionId": "uuid-v4",
    "subscriptionId": "uuid-v4",
    "service": "paymentLink",
    "companyId": "uuid-v4",
    "amount": 100.00,
    "currency": "USD",
    "status": "SUCCESS",
    "customerEmail": "john@example.com",
    "createdAt": "2023-10-27T10:00:00Z",
    "externalTransactionId": "order_123"
  }
}
```

### Subscription Created (`subscription.created`)

```json
{
  "event": "subscription.created",
  "eventId": "evt_456...",
  "timestamp": "2023-10-27T10:00:00Z",
  "environment": "production",
  "data": {
    "subscriptionId": "uuid-v4",
    "companyId": "uuid-v4",
    "planId": "uuid-v4",
    "customerEmail": "john@example.com",
    "amount": 50.00,
    "currency": "USD",
    "status": "ACTIVE",
    "createdAt": "2023-10-27T10:00:00Z"
  }
}
```

### Withdrawal Completed (`withdraw.completed`)

```json
{
  "event": "withdraw.completed",
  "eventId": "evt_789...",
  "timestamp": "2023-10-27T10:00:00Z",
  "environment": "production",
  "data": {
    "withdrawId": "uuid-v4",
    "companyId": "uuid-v4",
    "amount": 500.00,
    "currency": "USD",
    "status": "SUCCESS",
    "createdAt": "2023-10-27T10:00:00Z"
  }
}
```

## Verifying Signatures

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

<Tabs>
  <TabItem value="nodejs" label="Node.js" default>

```javascript
const crypto = require('crypto');

app.post('/webhooks', (req, res) => {
  const signature = req.headers['x-paysgator-signature'];
  const payload = JSON.stringify(req.body);
  const secret = process.env.PAYSGATOR_WEBHOOK_SECRET;

  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  if (signature === expectedSignature) {
    const webhook = req.body;
    if (webhook.event === 'payment.success') {
      console.log('Payment success:', webhook.data.transactionId);
    }
  }

  res.status(200).send('OK');
});
```

  </TabItem>
</Tabs>

# File: docs/payments.md

---
sidebar_position: 3
---

# Payments

Create and manage payment transactions using the PaysGator API.

## Create Payment

Creates a new payment transaction and generates a checkout link for the customer.

**Endpoint:** `POST /payment/create`

### Request Body

| Field | Type | Description | Required |
| :--- | :--- | :--- | :--- |
| `amount` | number | The amount to charge (e.g., `100.00`) | Yes |
| `currency` | string | ISO 4217 Currency code (e.g., `USD`, `MZN`) | Yes |
| `externalTransactionId` | string | Your internal reference ID for the order | No |
| `payment_methods` | array | Allowed payment methods (e.g., `["MPESA", "CARD"]`) | No |
| `fields` | array | Fields to collect from customer (e.g., `["name", "email"]`) | No |
| `returnUrl` | string | URL to redirect the customer after payment | No |
| `metadata` | object | Additional custom data attached to the transaction | No |

### Example Request

```json
{
  "amount": 100.00,
  "currency": "USD",
  "externalTransactionId": "order_12345",
  "payment_methods": ["MPESA", "CARD"],
  "fields": ["name", "email"],
  "returnUrl": "https://example.com/success",
  "metadata": {
    "title": "Premium Subscription",
    "description": "Monthly premium plan"
  }
}
```

### Success Response

```json
{
  "success": true,
  "data": {
    "paymentlinkId": "uuid-v4-payment-link-id",
    "checkoutUrl": "https://paysgator.com/checkout/uuid-v4",
    "transactionId": "uuid-v4-transaction-id"
  }
}
```

---

## Confirm Payment

Confirms a payment directly if you are collecting payment details on your own checkout page.

**Endpoint:** `POST /payment/confirm`

### Request Body

| Field | Type | Description | Required |
| :--- | :--- | :--- | :--- |
| `paymentLinkId` | string | The ID of the payment link to confirm | Yes |
| `paymentMethod` | string | The payment method to use (e.g., `MPESA`) | Yes |
| `payment_fields` | object | Method-specific fields (e.g., `phoneNumber`) | No |
| `customer` | object | Customer details (`name`, `email`, `phone`, etc.) | No |

### Example Request

```json
{
  "paymentLinkId": "uuid-v4-payment-link-id",
  "paymentMethod": "MPESA",
  "payment_fields": {
    "phoneNumber": "841234567"
  },
  "customer": {
    "name": "John Doe",
    "email": "john@example.com"
  }
}
```

### Success Response

```json
{
  "success": true,
  "data": {
    "transactionId": "uuid-v4-transaction-id",
    "fee": 2.50,
    "netAmount": 97.50
  }
}

# File: docs/transactions.md

---
sidebar_position: 5
---

# Transactions

Retrieve and manage transaction details.

## Get Transaction

Retrieves the details of a specific transaction by its ID.

**Endpoint:** `GET /transactions/{id}`

### Parameters

| Parameter | Type | Description | Required |
| :--- | :--- | :--- | :--- |
| `id` | string | The UUID of the transaction | Yes |

### Success Response

```json
{
  "id": "txn_abcdef",
  "amount": 500,
  "currency": "USD",
  "status": "completed",
  "method": "CARD",
  "description": "Payment for Invoice #123",
  "createdAt": "2023-11-15T10:00:00Z",
  "mode": "LIVE"
}
```

### Error Responses

- **401 Unauthorized**: Missing or invalid token.
- **404 Not Found**: Transaction ID not found.

# File: docs/index.md

---
title: Paysgator implementation guide
---

# PaysGator API Documentation

Welcome! Explore our guides and API reference to integrate PaysGator into your application.

## Quick Links

- [Authentication](./authentication)
- [Payments](./payments)
- [Subscriptions](./subscriptions)
- [Webhooks](./webhooks)
# File: docs/api-reference.md

---
sidebar_position: 6
---

# API Reference

Welcome to the PaysGator API Reference. This documentation provides detailed information about our API endpoints, request structures, and response formats.

## Base URL

All API requests should be made to the following base URL:

```
https://paysgator.com/api/v1
```

## Authentication

The API uses API Key authentication. Include your key in the `X-Api-Key` header of every request. You can use **LIVE** or **TEST** keys to control the transaction mode.

```http
X-Api-Key: YOUR_API_KEY
```

## Endpoints

### Payments

#### Create Payment

Creates a payment transaction with an associated payment link.

- **URL**: `/payment/create`
- **Method**: `POST`
- **Request Body**:

| Field | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| `amount` | number | Yes | Payment amount (e.g., `100.00`). |
| `currency` | string | Yes | ISO 4217 Currency code (e.g., `USD`, `MZN`). |
| `payment_methods` | array | No | List of allowed payment methods (e.g., `["MPESA", "CARD"]`). |
| `returnUrl` | string | No | URL to redirect after payment. |
| `fields` | array | No | Fields to collect from customer (`name`, `email`, `phone`, `address`). |
| `externalTransactionId` | string | No | Your external reference ID. |
| `metadata` | object | No | Additional metadata. |

- **Response (200 OK)**:
    - `success`: `true`
    - `data`:
        - `paymentlinkId`: UUID
        - `checkoutUrl`: Payment page URL
        - `transactionId`: UUID

#### Confirm Payment

Confirms a payment directly from a payment link (for "Confirm" type methods).

- **URL**: `/payment/confirm`
- **Method**: `POST`
- **Request Body**:

| Field | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| `paymentLinkId` | string | Yes | The ID of the payment link. |
| `paymentMethod` | string | Yes | The method to use (e.g., `MPESA`). |
| `payment_fields` | object | No | Method-specific fields (e.g., `{ "phoneNumber": "..." }`). |
| `customer` | object | No | Customer info (`name`, `email`, `phone`, `address`, `country`). |

- **Response (200 OK)**:
    - `success`: `true`
    - `data`:
        - `transactionId`: UUID
        - `fee`: Transaction fee
        - `netAmount`: Net amount

### Wallet

#### Get Wallet Balance

Retrieves the balance for the wallet associated with the API key.

- **URL**: `/wallet/balance`
- **Method**: `GET`
- **Response (200 OK)**:
    - `walletId`: UUID
    - `currency`: Currency code
    - `balance`: Balance string
    - `mode`: `LIVE` or `TEST`

### Transactions

#### Get Transaction

Retrieves details of a specific transaction.

- **URL**: `/transactions/{id}`
- **Method**: `GET`
- **Parameters**:
    - `id` (path): Transaction UUID
- **Response (200 OK)**:
    - `id`: UUID
    - `amount`: number
    - `currency`: string
    - `status`: `PENDING`, `SUCCESS`, `FAILED`, `REFUNDED`
    - `method`: payment method used
    - `createdAt`: ISO date
    - `mode`: `LIVE` or `TEST`

### Subscriptions

#### Update Subscription

Updates a subscription status (cancel, pause, resume).

- **URL**: `/subscriptions/{id}`
- **Method**: `PATCH`
- **Parameters**:
    - `id` (path): Subscription UUID
- **Request Body**:

| Field | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| `action` | string | Yes | One of: `cancel`, `pause`, `resume`. |

- **Response (200 OK)**:
    - `id`: UUID
    - `status`: `ACTIVE`, `CANCELED`, `PAST_DUE`, `PAUSED`
    - `currentPeriodEnd`: ISO date

## Errors

The API uses standard HTTP status codes to indicate success or failure. Error responses follow this format:

```json
{
  "error": {
    "message": "Human-readable error message",
    "code": "MACHINE_READABLE_CODE"
  }
}
```

**Common Error Codes**:
- `UNAUTHORIZED`
- `NOT_FOUND`
- `MISSING_FIELDS`
- `WALLET_NOT_FOUND`
- `CURRENCY_MISMATCH`
- `PAYMENT_FAILED`
- `INTERNAL_ERROR`

# File: docs/intro.md

---
sidebar_position: 1
---

# Introduction

Welcome to the PaysGator API documentation. PaysGator is a powerful payment gateway that allows you to accept payments, manage subscriptions, and handle transactions with ease.

## Getting Started

To start using the PaysGator API, you'll need an API key. You can generate one in the [PaysGator Dashboard](https://paysgator.com/dashboard/developers).

### Base URL

All API requests should be made to the following base URL:

```
https://paysgator.com/api/v1
```

### Authentication

The API uses API Key authentication. Include your key in the `X-Api-Key` header of every request.

```http
X-Api-Key: YOUR_API_KEY
```

## Key Features

- **Payments**: Create payment links and confirm charges directly.
- **Subscriptions**: Manage recurring billing and customer plans.
- **Wallet**: Check your balance and manage funds across multiple currencies.
- **Webhooks**: Receive real-time notifications for important events.

---

## Next Steps

- [Setup Authentication](./authentication)
- [Create your first Payment](./payments)
- [Learn about Webhooks](./webhooks)

See the [Authentication](./authentication) section for more details.