Skip to main content

Payment Service API Reference

Base URL​

http://localhost:8001/api/v1

Authentication​

All endpoints require authentication via JWT tokens from the Gateway service.

REST API​

Health Check​

GET /health

Response:

{
  "status": "healthy",
  "database": "connected"
}

Create Payment​

POST /payments
Content-Type: application/json

{
  "amount": 10000,
  "currency": "ZAR",
  "provider": "payfast",
  "customerEmail": "customer@example.com",
  "itemName": "Product Name"
}

Get Payment​

GET /payments/{paymentId}

List Payments​

GET /payments?limit=10&offset=0

Create Subscription​

POST /subscriptions
Content-Type: application/json

{
  "customerId": "customer-123",
  "planId": "plan-premium",
  "provider": "payfast"
}

Cancel Subscription​

DELETE /subscriptions/{subscriptionId}

Create Invoice​

POST /invoices
Content-Type: application/json

{
  "customerId": "customer-123",
  "items": [
    {
      "description": "Product",
      "amount": 10000,
      "quantity": 1
    }
  ]
}

GraphQL API​

Endpoint​

POST /api/graphql

Example Queries​

query GetPayment($id: ID!) {
  payment(id: $id) {
    id
    amount
    currency
    status
    provider
    createdAt
  }
}

mutation CreatePayment($input: CreatePaymentInput!) {
  createPayment(input: $input) {
    id
    status
    paymentUrl
  }
}

Error Responses​

{
  "error": {
    "code": "PAYMENT_FAILED",
    "message": "Payment processing failed",
    "details": {}
  }
}

Payment Providers​

PayFast​

South African payment provider.

Yoco​

South African card payment provider.

Stripe (Future)​

International payment provider support.