Payment Gateway API Documentation

Overview

The Payment Gateway API allows you to create, verify, and manage payment transactions securely. All requests must be authenticated using your API key and originate from your registered domain.

Base URL

https://edupay.edumindly.com/api

Authentication

All API requests require authentication using your API key. The API key must be included in the request headers.

Required Headers

X-Payment-Api-Key: your_api_key_here
Content-Type: application/json

Domain Validation

Requests must originate from your registered domain. The Origin header is validated against your brand's configured domain.

Rate Limiting

The API is rate limited to ensure fair usage and system stability.

Current Limits

100 requests per minute per API key

API Endpoints

POST

/payment/instance

Creates a new payment instance and returns an invoice ID and payment URL.

Request Body

{
  "full_name": "John Doe",
  "email": "[email protected]",
  "phone": "+1234567890",
  "amount": 100.50,
  "redirect_url": "https://yourdomain.com/success",
  "return_type": "GET",
  "metadata": {
    "order_id": "ORDER_123",
    "product": "Premium Subscription"
  }
}

Parameters

Field	Type	Required	Description
full_name	string	Yes	Customer's full name
email	string	No	Customer's email address
phone	string	Yes	Customer's phone number
amount	number	Yes	Payment amount
redirect_url	string	No	URL to redirect after payment
return_type	string	No	HTTP method for redirect (GET\|POST)
metadata	object	No	Additional data to store with payment

Success Response (200)

{
  "invoice_id": "INV_20241201_123456",
  "payment_url": "https://yourdomain.com/payment/PAY_20241201_123456"
}

POST

/payment/verify

Retrieves the current status and details of a payment using the invoice ID.

Request Body

{
  "invoice_id": "INV_20241201_123456"
}

Parameters

Field	Type	Required	Description
invoice_id	string	Yes	The invoice ID returned from payment creation

Success Response (200)

{
  "status": true,
  "message": "payment retrieved successfully",
  "data": {
    "id": 1,
    "invoice_id": "INV_20241201_123456",
    "payment_id": "PAY_20241201_123456",
    "full_name": "John Doe",
    "email": "[email protected]",
    "phone": "+1234567890",
    "amount": 100.50,
    "status": "created",
    "redirect_url": "https://yourdomain.com/success",
    "return_type": "GET",
    "metadata": {
      "order_id": "ORDER_123",
      "product": "Premium Subscription"
    },
    "created_at": "2024-12-01T10:30:00Z",
    "updated_at": "2024-12-01T10:30:00Z"
  }
}

POST

/payment/update

Updates the status of an existing payment. Only specific status transitions are allowed.

Request Body

{
  "invoice_id": "INV_20241201_123456",
  "status": "completed"
}

Parameters

Field	Type	Required	Description
invoice_id	string	Yes	The invoice ID to update
status	string	Yes	New status (completed\|failed\|cancelled)

Success Response (200)

{
  "status": true,
  "message": "payment status updated successfully"
}

Error Response (404)

{
  "status": false,
  "message": "invoice not found on this brand"
}

Error Codes

The API uses conventional HTTP response codes to indicate the success or failure of an API request.

Code	Description	Common Causes
200	OK	Request successful
400	Bad Request	Invalid request data or missing required fields
401	Unauthorized	Missing/invalid API key, inactive brand, or domain mismatch
404	Not Found	Invoice not found or doesn't belong to your brand
422	Unprocessable Entity	Validation errors in request data
429	Too Many Requests	Rate limit exceeded (100 requests/minute)
500	Internal Server Error	Server error - contact support if persistent

Common Error Response Format

{
  "message": "Api key is required",
  "errors": {
    "field_name": ["Validation error message"]
  }
}