OVN Pay API Reference

Overview

The OVN Pay API provides programmatic access to payout processing, driver management, and batch operations. This API is used by the OVN ERP integration and driver portal applications.

Base URL

https://api.ovnpays.com

API Version

v1

Authentication

All endpoints require Bearer token authentication using your API key.

Authorization: Bearer psk_your_api_key_here

API Endpoints

GET/api/v1/health

Health Check

Health check endpoint.

Response

{
  "success": true,
  "data": {
    "status": "healthy",
    "version": "1.0.0",
    "timestamp": "2026-01-31T12:00:00Z"
  }
}

GET/api/v1/drivers

List Drivers

List all drivers with pagination.

Query Parameters

Parameter	Type	Default	Description
`page`	`number`	`1`	Page number
`pageSize`	`number`	`50`	Page size (max 100)
`status`	`string`	`-`	Filter by status

Response

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "drv_abc123",
        "ovnDriverId": "OVN-DRIVER-789",
        "name": "John Smith",
        "email": "john@example.com",
        "phone": "+15551234567",
        "status": "active",
        "kycStatus": "verified",
        "totalPaid": 125000,
        "pendingPayouts": 0
      }
    ],
    "total": 142,
    "page": 1,
    "pageSize": 50,
    "hasNextPage": true
  }
}

GET/api/v1/drivers/:id

Get Driver

Get driver by OVN driver ID.

Response

{
  "success": true,
  "data": {
    "id": "drv_abc123",
    "ovnDriverId": "OVN-DRIVER-789",
    "name": "John Smith",
    "email": "john@example.com",
    "phone": "+15551234567",
    "status": "active",
    "kycStatus": "verified"
  }
}

POST/api/v1/drivers

Register Driver

Request Body

{
  "ovnDriverId": "OVN-DRIVER-789",
  "name": "John Smith",
  "email": "john@example.com",
  "phone": "+15551234567"
}

Response

{
  "success": true,
  "data": {
    "id": "drv_abc123",
    "ovnDriverId": "OVN-DRIVER-789",
    "name": "John Smith",
    "status": "invited",
    "kycStatus": "pending"
  }
}

GET/api/v1/drivers/:id/payouts

Get Driver Payouts

Get payouts for a specific driver.

Response

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "pay_xyz",
        "loadId": "L-12345",
        "driverId": "drv_abc123",
        "driverName": "John Smith",
        "amount": 45000,
        "fee": 450,
        "netAmount": 44550,
        "status": "completed",
        "rail": "standard",
        "requestedAt": "2026-01-31T12:00:00Z",
        "completedAt": "2026-02-02T12:00:00Z"
      }
    ],
    "total": 12,
    "page": 1,
    "pageSize": 50
  }
}

POST/api/v1/payouts

Create Payout

Create a payout for a load.

Request Body

{
  "loadId": "L-12345",
  "urgency": "standard"
}

Response

{
  "success": true,
  "data": {
    "id": "pay_xyz",
    "loadId": "L-12345",
    "driverId": "drv_abc123",
    "driverName": "John Smith",
    "amount": 45000,
    "fee": 250,
    "netAmount": 44750,
    "status": "validated",
    "rail": "standard",
    "requestedAt": "2026-01-31T12:00:00Z"
  }
}

POST/api/v1/payouts/instant

Instant Payout

Request instant payout for a load.

Request Body

{
  "loadId": "L-12345",
  "requestedBy": "driver-789"
}

Response

{
  "success": true,
  "data": {
    "id": "pay_xyz",
    "loadId": "L-12345",
    "driverId": "drv_abc123",
    "amount": 45000,
    "fee": 450,
    "netAmount": 44550,
    "status": "processing",
    "rail": "instant",
    "requestedAt": "2026-01-31T12:00:00Z",
    "estimatedSettlement": "~30 seconds"
  }
}

POST/api/v1/payouts/:id/cancel

Cancel Payout

Cancel a pending payout.

Response

{
  "success": true,
  "data": {
    "id": "pay_xyz",
    "status": "canceled",
    "canceledAt": "2026-01-31T12:30:00Z"
  }
}

POST/api/v1/payouts/:id/retry

Retry Payout

Retry a failed payout.

Response

{
  "success": true,
  "data": {
    "id": "pay_xyz",
    "status": "queued",
    "retriedAt": "2026-01-31T12:30:00Z"
  }
}

GET/api/v1/batches

List Batches

List all batches.

Query Parameters

Parameter	Type	Default	Description
`page`	`number`	`1`	Page number
`pageSize`	`number`	`20`	Page size
`status`	`string`	`-`	Filter by status

Response

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "batch_xyz",
        "name": "Weekly Payouts - 2026-01-31",
        "payoutCount": 45,
        "totalAmount": 2025000,
        "totalFees": 11250,
        "netAmount": 2013750,
        "status": "completed",
        "createdAt": "2026-01-31T12:00:00Z",
        "completedAt": "2026-01-31T14:00:00Z"
      }
    ],
    "total": 8,
    "page": 1,
    "pageSize": 20,
    "hasNextPage": false
  }
}

POST/api/v1/batches

Create Batch

Create a batch from load IDs.

Request Body

{
  "name": "Weekly Payouts - 2026-01-31",
  "loadIds": ["L-12345", "L-12346", "L-12347"],
  "scheduledFor": "2026-01-31T17:00:00Z"
}

Response

{
  "success": true,
  "data": {
    "id": "batch_xyz",
    "name": "Weekly Payouts - 2026-01-31",
    "payoutCount": 3,
    "totalAmount": 135000,
    "totalFees": 675,
    "netAmount": 134325,
    "status": "queued",
    "createdAt": "2026-01-31T12:00:00Z"
  }
}

POST/api/v1/batches/:id/release

Release Batch

Release a batch for processing.

Response

{
  "success": true,
  "data": {
    "id": "batch_xyz",
    "status": "processing",
    "releasedAt": "2026-01-31T12:00:00Z"
  }
}

GET/api/v1/balance

Get Balance

Get wallet balance.

Response

{
  "success": true,
  "data": {
    "available": 5000000,
    "pending": 50000,
    "inTransit": 25000,
    "currency": "USD"
  }
}

Error Codes

Code	Status	Description
`VALIDATION_ERROR`	400	Invalid request data
`AUTHENTICATION_ERROR`	401	Invalid API key
`NOT_FOUND`	404	Resource not found
`IDEMPOTENCY_ERROR`	422	Idempotency conflict
`RATE_LIMIT_ERROR`	429	Rate limit exceeded
`INSUFFICIENT_FUNDS`	400	Insufficient wallet balance

SDK Usage

For TypeScript/JavaScript projects, use the @ovn/paystream-client SDK.

Installation

npm install @ovn/paystream-client

Example Usage

import { PaystreamClient } from '@ovn/paystream-client';

const client = new PaystreamClient({
  apiKey: process.env.PAYSTREAM_API_KEY!,
  apiUrl: 'https://api.ovnpays.com/api/v1',
});

// Create a payout
const payout = await client.payouts.create({
  recipientId: 'drv_abc123',
  amount: 45000, // $450.00 in cents
  description: 'Load #L-12345',
  rail: 'standard',
});

// List drivers
const drivers = await client.drivers.list({
  limit: 50,
  status: 'active',
});