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.

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

Create Subscription

Initiates a new subscription in PAUSED state and returns a checkout URL.

• URL: /subscription/create
• Method: POST
• Request Body:

Field	Type	Required	Description
planId	string	Yes	ID of the subscription plan.
customerEmail	string	Yes	Email address of the customer.
customerName	string	No	Name of the customer.
metadata	object	No	Additional metadata.

• Response (200 OK):
  • success: true
  • data:
    • subscriptionId: UUID
    • checkoutUrl: Payment page URL
    • status: PAUSED

Get Subscription

Retrieves details of a specific subscription.

• URL: /subscription/{id}
• Method: GET
• Parameters:
  • id (path): Subscription UUID
• Response (200 OK):
  • success: true
  • data:
    • id: UUID
    • planId: UUID
    • customerEmail: string
    • status: ACTIVE, CANCELED, PAST_DUE, PAUSED
    • currentPeriodStart: ISO date
    • currentPeriodEnd: ISO date
    • createdAt: ISO date

List Subscriptions

Lists all subscriptions for the company.

• URL: /subscriptions
• Method: GET
• Parameters (Query):
  • customerEmail: (Optional) Filter by customer email.
  • status: (Optional) Filter by status.
  • planId: (Optional) Filter by plan ID.
• Response (200 OK):
  • success: true
  • data: Array of Subscription objects.

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:

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