Skip to content

API_DOCUMENTATION.md

Latest commit

 

History

History
1153 lines (1011 loc) · 28.6 KB

API_DOCUMENTATION.md

File metadata and controls

1153 lines (1011 loc) · 28.6 KB
Raw

ChainPaye Payment Link API Documentation

Base URL

https://your-api-domain.com/api/v1

Authentication

Currently, all endpoints are public. In production, implement proper authentication and authorization.

CORS (Cross-Origin Resource Sharing)

The API supports cross-origin requests from frontend applications.

CORS Configuration

  • Allowed Origins: Configurable via CORS_ORIGIN environment variable
  • Allowed Methods: GET, POST, PUT, PATCH, DELETE, OPTIONS
  • Credentials: Supported (cookies and authentication headers)
  • Exposed Headers: Rate limit headers are exposed for client monitoring

Development

CORS_ORIGIN=*  # Allows all origins

Production

CORS_ORIGIN=https://chainpaye.com,https://www.chainpaye.com

For detailed CORS configuration, see CORS_CONFIGURATION.md.

Rate Limiting

The API implements comprehensive rate limiting to ensure fair usage and protect against abuse. All requests are subject to rate limits based on IP address and endpoint type.

Rate Limit Headers

All responses include rate limit information in headers:

  • RateLimit-Limit: Maximum number of requests allowed in the window
  • RateLimit-Remaining: Number of requests remaining in the current window
  • RateLimit-Reset: Unix timestamp when the rate limit resets

Rate Limit Configuration

Endpoint Type Limit Window Applies To
Burst Protection 20 1 minute All endpoints
General API 100 15 minutes All endpoints
Payment Link Creation 20 10 minutes POST /payment-links
Payment Access 50 5 minutes GET/POST /payment/:id
Transaction Recording 30 5 minutes POST /transactions
Read Operations 200 15 minutes All GET requests
Sensitive Operations 10 30 minutes PATCH enable/disable

Rate Limit Exceeded Response

When rate limit is exceeded, the API returns HTTP 429:

{
  "success": false,
  "error": "Too many requests",
  "message": "Too many requests from this IP, please try again later.",
  "retryAfter": "15 minutes",
  "timestamp": "2026-02-07T12:00:00.000Z",
  "correlationId": "rate-limit-exceeded"
}

For detailed rate limiting documentation, see RATE_LIMITING.md.

Common Response Format

All API responses follow this standard format:

{
  "success": boolean,
  "data": object | array | null,
  "message": string,
  "error": string | null,
  "timestamp": string (ISO 8601),
  "correlationId": string
}

Error Handling

  • 400 Bad Request: Validation errors, invalid parameters
  • 404 Not Found: Resource not found
  • 429 Too Many Requests: Rate limit exceeded
  • 500 Internal Server Error: Server errors

Health Check & Monitoring

GET /health

Basic API health check.

Response:

{
  "success": true,
  "message": "Payment Link System API is running",
  "timestamp": "2026-02-04T10:00:00.000Z",
  "version": "2.0.0",
  "uptime": 3600,
  "memory": {
    "used": 128,
    "total": 256,
    "rss": 180
  }
}

GET /health/verification

Enhanced verification service health check with detailed metrics.

Response:

{
  "status": "healthy",
  "service": "Enhanced Background Verification v2.0.0",
  "isRunning": true,
  "uptime": "2h 30m",
  "lastRun": "2026-02-04T09:55:00.000Z",
  "lastRunDuration": 1250,
  "statistics": {
    "totalRuns": 48,
    "totalTransactionsProcessed": 156,
    "totalErrors": 2,
    "errorRate": "4.17%",
    "successRate": "95.83%"
  },
  "performance": {
    "memoryUsage": "145MB",
    "avgProcessingTime": 26
  },
  "configuration": {
    "batchSize": 100,
    "cronInterval": "300s",
    "apiDelay": "100ms",
    "maxRetries": 3
  },
  "timestamp": "2026-02-04T10:00:00.000Z"
}

GET /health/database

Database connectivity and performance check.

Response:

{
  "status": "healthy",
  "database": "MongoDB",
  "connectivity": "connected",
  "queryTime": "45ms",
  "statistics": {
    "totalTransactions": 1250,
    "pendingTransactions": 23,
    "completedTransactions": 1227
  },
  "timestamp": "2026-02-04T10:00:00.000Z"
}

GET /health/system

Comprehensive system health check with all components.

Response:

{
  "status": "healthy",
  "timestamp": "2026-02-04T10:00:00.000Z",
  "uptime": "7200s",
  "components": {
    "verification": {
      "status": "healthy",
      "isRunning": true,
      "lastRun": "2026-02-04T09:55:00.000Z",
      "totalRuns": 48,
      "errorRate": "4.17%"
    },
    "database": {
      "status": "healthy",
      "queryTime": "45ms",
      "pendingTransactions": 23
    },
    "memory": {
      "status": "healthy",
      "heapUsed": "145MB",
      "heapTotal": "256MB",
      "rss": "180MB"
    }
  },
  "environment": {
    "nodeVersion": "v18.17.0",
    "platform": "linux",
    "pid": 12345,
    "nodeEnv": "production"
  }
}

GET /health/transactions

Transaction statistics and metrics.

Response:

{
  "status": "healthy",
  "timestamp": "2026-02-04T10:00:00.000Z",
  "totals": {
    "all": 1250,
    "pending": 23,
    "completed": 1200,
    "expired": 27
  },
  "recent": {
    "last24Hours": 45,
    "lastHour": 3
  },
  "percentages": {
    "completionRate": "96.00%",
    "pendingRate": "1.84%",
    "expirationRate": "2.16%"
  }
}

Payment Links

POST /payment-links

Create a new payment link.

Request Body:

{
  "merchantId": "string (required, 1-255 chars)",
  "userId": "string (required, 1-255 chars)",
  "name": "string (required, 1-100 chars)",
  "amount": "string (required, decimal as string)",
  "currency": "NGN | USD | GBP | EUR (required)",
  "token": "string (required, 1-100 chars)",
  "selectedCurrency": "string (required, 1-10 chars)",
  "paymentType": "bank | card (required)",
  "description": "string (optional, max 500 chars)",
  "successUrl": "string (optional, max 500 chars)",
  "metadata": "object (optional)"
}

Currency & Payment Type Rules:

  • NGN: Only "paymentType": "bank" allowed
  • USD: Both "bank" and "card" allowed
  • GBP, EUR: only "card" allowed

Example Request:

{
  "merchantId": "merchant-123",
  "userId": "user-456",
  "name": "Tech Solutions Ltd",
  "amount": "250.00",
  "currency": "USD",
  "token": "USDT",
  "selectedCurrency": "USD",
  "paymentType": "card",
  "description": "Professional services payment",
  "successUrl": "https://mysite.com/success"
}

Response (201 Created):

{
  "success": true,
  "data": {
    "id": "507f1f77bcf86cd799439011",
    "merchantId": "merchant-123",
    "userId": "user-456",
    "name": "Tech Solutions Ltd",
    "amount": "250.00",
    "currency": "USD",
    "description": "Professional services payment",
    "isActive": true,
    "address": "0x3c45e44daae997b3ac8644ff3fdd13c120634f10",
    "token": "USDT",
    "selectedCurrency": "USD",
    "paymentType": "card",
    "successUrl": "https://mysite.com/success",
    "linkUrl": "https://chainpaye.com/payment/507f1f77bcf86cd799439011",
    "metadata": {},
    "createdAt": "2026-02-04T10:00:00.000Z",
    "updatedAt": "2026-02-04T10:00:00.000Z"
  },
  "message": "Payment link created successfully",
  "timestamp": "2026-02-04T10:00:00.000Z",
  "correlationId": "abc123-def456"
}

GET /payment-links/:id

Get payment link by ID.

Parameters:

  • id (path): Payment link ID

Response (200 OK):

{
  "success": true,
  "data": {
    "id": "507f1f77bcf86cd799439011",
    "merchantId": "merchant-123",
    "userId": "user-456",
    "name": "Tech Solutions Ltd",
    "amount": "250.00",
    "currency": "USD",
    "description": "Professional services payment",
    "isActive": true,
    "address": "0x3c45e44daae997b3ac8644ff3fdd13c120634f10",
    "token": "USDT",
    "selectedCurrency": "USD",
    "paymentType": "card",
    "successUrl": "https://mysite.com/success",
    "linkUrl": "https://chainpaye.com/payment/507f1f77bcf86cd799439011",
    "metadata": {},
    "createdAt": "2026-02-04T10:00:00.000Z",
    "updatedAt": "2026-02-04T10:00:00.000Z"
  },
  "message": "Payment link retrieved successfully",
  "timestamp": "2026-02-04T10:00:00.000Z",
  "correlationId": "xyz789-abc123"
}

GET /payment-links

List payment links for a merchant with pagination.

Query Parameters:

  • merchantId (required): Merchant ID to filter by
  • page (optional): Page number (default: 1)
  • limit (optional): Items per page (default: 10, max: 100)
  • sortBy (optional): Field to sort by
  • sortOrder (optional): asc or desc

Example Request:

GET /payment-links?merchantId=merchant-123&page=1&limit=10&sortBy=createdAt&sortOrder=desc

Response (200 OK):

{
  "success": true,
  "data": {
    "paymentLinks": [
      {
        "id": "507f1f77bcf86cd799439011",
        "merchantId": "merchant-123",
        "userId": "user-456",
        "name": "Tech Solutions Ltd",
        "amount": "250.00",
        "currency": "USD",
        "description": "Professional services payment",
        "isActive": true,
        "address": "0x3c45e44daae997b3ac8644ff3fdd13c120634f10",
        "token": "USDT",
        "selectedCurrency": "USD",
        "paymentType": "card",
        "successUrl": "https://mysite.com/success",
        "linkUrl": "https://chainpaye.com/payment/507f1f77bcf86cd799439011",
        "metadata": {},
        "createdAt": "2026-02-04T10:00:00.000Z",
        "updatedAt": "2026-02-04T10:00:00.000Z"
      }
    ],
    "total": 1,
    "page": 1,
    "limit": 10
  },
  "message": "Payment links retrieved successfully",
  "timestamp": "2026-02-04T10:00:00.000Z",
  "correlationId": "list123-def456"
}

PATCH /payment-links/:id/disable

Disable a payment link.

Parameters:

  • id (path): Payment link ID

Request Body (optional):

{
  "reason": "string (optional, max 255 chars)"
}

Response (200 OK):

{
  "success": true,
  "message": "Payment link disabled successfully",
  "timestamp": "2026-02-04T10:00:00.000Z",
  "correlationId": "disable123-def456"
}

PATCH /payment-links/:id/enable

Enable a payment link.

Parameters:

  • id (path): Payment link ID

Request Body (optional):

{
  "reason": "string (optional, max 255 chars)"
}

Response (200 OK):

{
  "success": true,
  "message": "Payment link enabled successfully",
  "timestamp": "2026-02-04T10:00:00.000Z",
  "correlationId": "enable123-def456"
}

GET /payment-links/:id/status

Get payment link status and statistics.

Parameters:

  • id (path): Payment link ID

Response (200 OK):

{
  "success": true,
  "data": {
    "id": "507f1f77bcf86cd799439011",
    "isActive": true,
    "transactionCount": 5,
    "totalAmount": "1250.00",
    "lastTransactionAt": "2026-02-04T09:30:00.000Z"
  },
  "message": "Payment link status retrieved successfully",
  "timestamp": "2026-02-04T10:00:00.000Z",
  "correlationId": "status123-def456"
}

GET /payment-links/:id/verify

Verify payment link and get payment details (public endpoint for verification).

Parameters:

  • id (path): Payment link ID

Response (200 OK):

{
  "success": true,
  "data": {
    "id": "507f1f77bcf86cd799439011",
    "isActive": true,
    "name": "Tech Solutions Ltd",
    "address": "0x3c45e44daae997b3ac8644ff3fdd13c120634f10",
    "token": "USDT",
    "currency": "USD",
    "selectedCurrency": "USD",
    "paymentType": "card",
    "amount": "250.00",
    "description": "Professional services payment",
    "successUrl": "https://mysite.com/success"
  },
  "correlationId": "verify123-def456"
}

POST /payment-links/:id/verify

⚠️ DEPRECATED: This endpoint returns an error message directing to the correct verification endpoint.

Correct Endpoint: Use POST /transactions/:reference/verify instead.

Response (400 Bad Request):

{
  "success": false,
  "message": "Payment verification should be done via the transactions endpoint",
  "correctEndpoint": "POST /api/v1/transactions/{transactionReference}/verify",
  "note": "Use the transaction reference (not payment link ID) with the transactions verify endpoint"
}

POST /payment-links/:id/access

Handle payment link access (when user opens the payment link).

Parameters:

  • id (path): Payment link ID

Request Body (optional):

{
  "payerInfo": {
    "payername": "string (optional)",
    "payeraddress": "string (optional)",
    "payercity": "string (optional)",
    "payerstate": "string (optional)",
    "payercountry": "string (optional)",
    "payerzipcode": "string (optional)",
    "payerphone": "string (optional)"
  }
}

Response (200 OK):

{
  "success": true,
  "data": {
    "id": "507f1f77bcf86cd799439011",
    "amount": "250.00",
    "currency": "USD",
    "selectedCurrency": "USD",
    "description": "Professional services payment",
    "address": "0x3c45e44daae997b3ac8644ff3fdd13c120634f10",
    "token": "USDT",
    "paymentType": "card",
    "successUrl": "https://mysite.com/success",
    "linkUrl": "https://chainpaye.com/payment/507f1f77bcf86cd799439011",
    "toronetReference": "toro_ref_123456",
    "transactionId": "trans_789012",
    "paymentInitialization": {
      "id": "init_345678",
      "status": "SUCCESS",
      "toronetResponse": {
        "success": true,
        "txid": "toro_ref_123456"
      }
    }
  },
  "message": "Payment link accessed and initialized successfully",
  "correlationId": "access123-def456"
}

POST /payment-links/:id

Alternative endpoint for payment link access (same as /access).

Parameters:

  • id (path): Payment link ID

Request/Response: Same as POST /payment-links/:id/access

GET /payment-links/merchant/:merchantId/successful-transactions

Get all successful transactions for a merchant (payment link owner).

Parameters:

  • merchantId (path): Merchant ID

Query Parameters:

  • page (optional): Page number (default: 1)
  • limit (optional): Items per page (default: 20, max: 100)
  • sortBy (optional): Field to sort by (default: paidAt)
  • sortOrder (optional): asc or desc (default: desc)

Example Requests:

GET /payment-links/merchant/merchant-123/successful-transactions
GET /payment-links/merchant/merchant-123/successful-transactions?page=1&limit=10
GET /payment-links/merchant/merchant-123/successful-transactions?sortBy=recordedAt&sortOrder=desc

Response (200 OK):

{
  "success": true,
  "data": {
    "transactions": [
      {
        "id": "trans_789012",
        "paymentLinkId": "507f1f77bcf86cd799439011",
        "reference": "TXN_REF_123",
        "state": "COMPLETED",
        "amount": "250.00",
        "currency": "USD",
        "actualAmountPaid": "250.00",
        "senderName": "John Doe",
        "senderPhone": "+1234567890",
        "payerInfo": {
          "email": "john.doe@example.com",
          "name": "John Doe",
          "phone": "+1234567890"
        },
        "toronetReference": "toro_ref_123456",
        "paidAt": "2026-02-04T09:35:00.000Z",
        "recordedAt": "2026-02-04T09:36:00.000Z",
        "createdAt": "2026-02-04T09:30:00.000Z",
        "updatedAt": "2026-02-04T09:36:00.000Z",
        "paymentInitialization": {
          "id": "init_345678",
          "toronetReference": "toro_ref_123456",
          "status": "SUCCESS",
          "createdAt": "2026-02-04T09:31:00.000Z"
        }
      }
    ],
    "total": 15,
    "page": 1,
    "limit": 20
  },
  "message": "Successful transactions retrieved successfully",
  "timestamp": "2026-02-04T10:00:00.000Z",
  "correlationId": "success123-def456"
}

Notes:

  • Returns only transactions in PAID and COMPLETED states
  • Includes full transaction details with payment information
  • Sorted by payment date (newest first) by default
  • Includes payer information and payment initialization details

GET /payment-links/:linkId/transactions

Get transactions for a specific payment link.

Parameters:

  • linkId (path): Payment link ID

Query Parameters:

  • state (optional): Filter by transaction state (PENDING, INITIALIZED, PAID, COMPLETED, PAYOUT_FAILED)
  • page (optional): Page number (default: 1)
  • limit (optional): Items per page (default: 10, max: 100)
  • sortBy (optional): Field to sort by
  • sortOrder (optional): asc or desc

Example Requests:

GET /payment-links/507f1f77bcf86cd799439011/transactions
GET /payment-links/507f1f77bcf86cd799439011/transactions?state=COMPLETED
GET /payment-links/507f1f77bcf86cd799439011/transactions?state=PENDING&page=1&limit=5
GET /payment-links/507f1f77bcf86cd799439011/transactions?sortBy=paidAt&sortOrder=desc

Response (200 OK):

{
  "success": true,
  "data": {
    "transactions": [
      {
        "id": "trans_789012",
        "paymentLinkId": "507f1f77bcf86cd799439011",
        "reference": "ref_unique_123",
        "state": "COMPLETED",
        "amount": "250.00",
        "currency": "USD",
        "payerInfo": {
          "email": "user@example.com",
          "phone": "+1234567890"
        },
        "toronetReference": "toro_ref_123456",
        "metadata": {},
        "createdAt": "2026-02-04T09:30:00.000Z",
        "updatedAt": "2026-02-04T09:35:00.000Z"
      }
    ],
    "total": 1,
    "page": 1,
    "limit": 10
  },
  "message": "Transactions retrieved successfully",
  "timestamp": "2026-02-04T10:00:00.000Z",
  "correlationId": "trans123-def456"
}

Transactions

GET /transactions

Get all transactions with optional filtering.

Query Parameters:

  • state (optional): Filter by transaction state (PENDING, INITIALIZED, PAID, COMPLETED, PAYOUT_FAILED)
  • currency (optional): Filter by currency (NGN, USD, GBP, EUR)
  • paymentLinkId (optional): Filter by payment link ID
  • page (optional): Page number (default: 1)
  • limit (optional): Items per page (default: 20, max: 100)
  • sortBy (optional): Field to sort by
  • sortOrder (optional): asc or desc

Example Requests:

GET /transactions
GET /transactions?state=COMPLETED
GET /transactions?state=PENDING&currency=USD
GET /transactions?paymentLinkId=507f1f77bcf86cd799439011
GET /transactions?state=PAID&sortBy=paidAt&sortOrder=desc&page=1&limit=10

Response (200 OK):

{
  "success": true,
  "data": {
    "transactions": [
      {
        "id": "trans_789012",
        "paymentLinkId": "507f1f77bcf86cd799439011",
        "reference": "ref_unique_123",
        "state": "COMPLETED",
        "amount": "250.00",
        "currency": "USD",
        "payerInfo": {
          "email": "user@example.com",
          "phone": "+1234567890"
        },
        "toronetReference": "toro_ref_123456",
        "metadata": {},
        "createdAt": "2026-02-04T09:30:00.000Z",
        "updatedAt": "2026-02-04T09:35:00.000Z"
      }
    ],
    "total": 1,
    "page": 1,
    "limit": 20
  },
  "message": "Transactions retrieved successfully",
  "timestamp": "2026-02-04T10:00:00.000Z",
  "correlationId": "trans123-def456"
}

POST /transactions

Create a new transaction.

Request Body:

{
  "paymentLinkId": "string (required, 1-255 chars)",
  "payerInfo": {
    "email": "string (optional, valid email)",
    "phone": "string (optional)",
    "metadata": "object (optional)"
  },
  "metadata": "object (optional)"
}

Response (201 Created):

{
  "success": true,
  "data": {
    "id": "trans_789012",
    "paymentLinkId": "507f1f77bcf86cd799439011",
    "reference": "ref_unique_123",
    "state": "PENDING",
    "amount": "250.00",
    "currency": "USD",
    "payerInfo": {
      "email": "user@example.com",
      "phone": "+1234567890"
    },
    "toronetReference": null,
    "metadata": {},
    "createdAt": "2026-02-04T09:30:00.000Z",
    "updatedAt": "2026-02-04T09:30:00.000Z"
  },
  "message": "Transaction created successfully",
  "timestamp": "2026-02-04T10:00:00.000Z",
  "correlationId": "create123-def456"
}

GET /transactions/:id

Get transaction by ID.

Parameters:

  • id (path): Transaction ID

Response (200 OK):

{
  "success": true,
  "data": {
    "id": "trans_789012",
    "paymentLinkId": "507f1f77bcf86cd799439011",
    "reference": "ref_unique_123",
    "state": "COMPLETED",
    "amount": "250.00",
    "currency": "USD",
    "payerInfo": {
      "email": "user@example.com",
      "phone": "+1234567890"
    },
    "toronetReference": "toro_ref_123456",
    "metadata": {},
    "createdAt": "2026-02-04T09:30:00.000Z",
    "updatedAt": "2026-02-04T09:35:00.000Z"
  },
  "message": "Transaction retrieved successfully",
  "timestamp": "2026-02-04T10:00:00.000Z",
  "correlationId": "get123-def456"
}

POST /transactions/:id/initialize

Initialize payment for a transaction.

Parameters:

  • id (path): Transaction ID

Response (200 OK):

{
  "success": true,
  "data": {
    "transactionId": "trans_789012",
    "toronetReference": "toro_ref_123456",
    "status": "INITIALIZED"
  },
  "message": "Payment initialized successfully",
  "timestamp": "2026-02-04T10:00:00.000Z",
  "correlationId": "init123-def456"
}

POST /transactions/:id/verify

Start immediate payment verification (3-second checks for 15 minutes, then hourly background checks).

Parameters:

  • id (path): Transaction ID

Headers:

  • admin (required): Toronet admin address
  • adminpwd (required): Toronet admin password

Request Body:

{
  "senderName": "string (required, 1-100 chars)",
  "senderPhone": "string (required, 1-20 chars)",
  "senderEmail": "string (required, valid email)",
  "currency": "NGN | USD | GBP | EUR (required)",
  "txid": "string (required, Toronet transaction reference)",
  "paymentType": "bank | card (required)",
  "amount": "string (required, decimal as string)",
  "successUrl": "string (optional, webhook URL)",
  "paymentLinkId": "string (optional, payment link ID)"
}

Example Request:

{
  "senderName": "John Doe",
  "senderPhone": "+1234567890",
  "senderEmail": "john.doe@example.com",
  "currency": "USD",
  "txid": "toro_ref_123456",
  "paymentType": "card",
  "amount": "250.00",
  "successUrl": "https://merchant.com/webhook",
  "paymentLinkId": "507f1f77bcf86cd799439011"
}

Response (200 OK):

{
  "success": true,
  "message": "Verification started. You will receive an email confirmation when payment is confirmed.",
  "data": {
    "transactionId": "trans_123",
    "email": "john.doe@example.com",
    "verificationPhase": "immediate",
    "checkInterval": "3 seconds",
    "duration": "15 minutes"
  },
  "timestamp": "2026-02-04T10:00:00.000Z",
  "correlationId": "verify123-def456"
}

Verification Process:

  1. Immediate Phase (0-15 minutes): Checks Toronet API every 3 seconds
  2. Background Phase (15 min - 24 hours): Hourly checks via cron job
  3. Expiration (24 hours): Transaction marked as failed, expiration email sent
  4. On Confirmation: Email sent, webhook called, transaction updated to PAID

PATCH /transactions/:id/state

Transition transaction state.

Parameters:

  • id (path): Transaction ID

Request Body:

{
  "newState": "PENDING | INITIALIZED | PAID | COMPLETED | PAYOUT_FAILED",
  "reason": "string (required, 1-255 chars)",
  "metadata": "object (optional)"
}

Response (200 OK):

{
  "success": true,
  "data": {
    "id": "trans_789012",
    "previousState": "INITIALIZED",
    "newState": "PAID",
    "reason": "Payment confirmed by Toronet",
    "transitionedAt": "2026-02-04T09:35:00.000Z"
  },
  "message": "Transaction state updated successfully",
  "timestamp": "2026-02-04T10:00:00.000Z",
  "correlationId": "state123-def456"
}

GET /transactions/:id/state-history

Get transaction state history.

Parameters:

  • id (path): Transaction ID

Response (200 OK):

{
  "success": true,
  "data": {
    "transactionId": "trans_789012",
    "stateHistory": [
      {
        "state": "PENDING",
        "reason": "Transaction created",
        "timestamp": "2026-02-04T09:30:00.000Z"
      },
      {
        "state": "INITIALIZED",
        "reason": "Payment initialized with Toronet",
        "timestamp": "2026-02-04T09:32:00.000Z"
      },
      {
        "state": "PAID",
        "reason": "Payment confirmed by Toronet",
        "timestamp": "2026-02-04T09:35:00.000Z"
      }
    ]
  },
  "message": "State history retrieved successfully",
  "timestamp": "2026-02-04T10:00:00.000Z",
  "correlationId": "history123-def456"
}

GET /transactions/:id/status

Check transaction status with admin credentials.

Parameters:

  • id (path): Transaction ID

Headers:

  • admin (required): Toronet admin address
  • adminpwd (required): Toronet admin password

Response (200 OK):

{
  "success": true,
  "data": {
    "transactionId": "trans_123",
    "reference": "TXN_REF_123",
    "state": "PAID",
    "amount": "250.00",
    "currency": "USD",
    "paidAt": "2026-02-04T09:35:00.000Z",
    "senderName": "John Doe",
    "senderPhone": "+1234567890",
    "senderEmail": "john.doe@example.com",
    "toronetReference": "toro_ref_123456",
    "verificationStartedAt": "2026-02-04T09:30:00.000Z",
    "lastVerificationCheck": "2026-02-04T09:35:00.000Z",
    "expiresAt": "2026-02-05T09:30:00.000Z",
    "createdAt": "2026-02-04T09:30:00.000Z",
    "updatedAt": "2026-02-04T09:35:00.000Z"
  },
  "message": "Transaction status retrieved successfully",
  "timestamp": "2026-02-04T10:00:00.000Z",
  "correlationId": "status123-def456"
}

POST /record-transaction/:transactionId

Record transaction completion (standalone endpoint).

Parameters:

  • transactionId (path): Transaction ID

Request Body:

{
  "amount": "string (required, decimal as string)",
  "currency": "NGN | USD | GBP | EUR (required)",
  "senderName": "string (required, 1-100 chars)",
  "senderPhone": "string (required, 1-20 chars)",
  "senderEmail": "string (optional, valid email)",
  "paidAt": "string (required, ISO 8601 datetime)"
}

Example Request:

{
  "amount": "250.00",
  "currency": "USD",
  "senderName": "John Doe",
  "senderPhone": "+1234567890",
  "senderEmail": "john.doe@example.com",
  "paidAt": "2026-02-04T09:35:00.000Z"
}

Response (200 OK):

{
  "success": true,
  "data": {
    "transactionId": "trans_789012",
    "state": "PAID",
    "recordedAmount": "250.00",
    "recordedCurrency": "USD",
    "senderName": "John Doe",
    "senderPhone": "+1234567890",
    "paidAt": "2026-02-04T09:35:00.000Z",
    "recordedAt": "2026-02-04T10:00:00.000Z"
  },
  "message": "Transaction recorded successfully",
  "timestamp": "2026-02-04T10:00:00.000Z",
  "correlationId": "record123-def456"
}

ChainPaye Direct Access

These endpoints handle direct access to payment links via the ChainPaye URL format.

GET /:id

Handle direct ChainPaye link access (GET request).

Parameters:

  • id (path): Payment link ID

Response: Same as POST /payment-links/:id/access

POST /:id

Handle direct ChainPaye link access (POST request).

Parameters:

  • id (path): Payment link ID

Request/Response: Same as POST /payment-links/:id/access

Error Responses

Validation Error (400)

{
  "success": false,
  "error": "Validation failed",
  "message": "Body: Currency must be one of: NGN, USD, GBP, EUR",
  "timestamp": "2026-02-04T10:00:00.000Z",
  "correlationId": "error123-def456"
}

Not Found Error (404)

{
  "success": false,
  "error": "Payment link not found",
  "message": "Payment link not found",
  "timestamp": "2026-02-04T10:00:00.000Z",
  "correlationId": "error123-def456"
}

Server Error (500)

{
  "success": false,
  "error": "Internal server error",
  "message": "An unexpected error occurred",
  "timestamp": "2026-02-04T10:00:00.000Z",
  "correlationId": "error123-def456"
}

Rate Limiting

Currently not implemented. Consider implementing rate limiting in production.

CORS

Configure CORS headers appropriately for your frontend domains in production.

Security Considerations

  • Implement proper authentication and authorization
  • Use HTTPS in production
  • Validate and sanitize all inputs
  • Implement request rate limiting
  • Add proper logging and monitoring
  • Use environment variables for sensitive configuration

Pagination

All list endpoints support pagination with these query parameters:

  • page: Page number (starts from 1)
  • limit: Items per page (max 100)
  • sortBy: Field to sort by
  • sortOrder: asc or desc

Correlation IDs

All responses include a correlationId for request tracking and debugging.

Supported Currencies

  • NGN: Nigerian Naira (bank transfers only)
  • USD: US Dollar (card payments and bank transfers)
  • GBP: British Pound (card payments and bank transfers)
  • EUR: Euro (card payments and bank transfers)

Transaction States

  • PENDING: Initial state
  • INITIALIZED: Payment initialized with Toronet
  • PAID: Payment confirmed
  • COMPLETED: Transaction completed successfully
  • PAYOUT_FAILED: Payout failed (requires retry)