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

Drivers

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
  }
}

Payouts

POST/api/v1/payouts

Create Payout

Create a payout for a driver.

Request Body

{
  "driverId": "drv_abc123",
  "amount": 45000,
  "urgency": "standard",
  "description": "Payment for load #L-12345"
}

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 driver.

Request Body

{
  "driverId": "drv_abc123",
  "amount": 45000,
  "requestedBy": "driver-789"
}

Response

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

GET/api/v1/payouts

List Payouts

List all payouts with optional filters.

Query Parameters

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

Response

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

GET/api/v1/payouts/:id

Get Payout

Get payout details.

Response

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

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

Batches

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
  }
}

GET/api/v1/batches/:id

Get Batch

Get batch details with payouts.

Response

{
  "success": true,
  "data": {
    "id": "batch_xyz",
    "name": "Weekly Payouts - 2026-01-31",
    "payoutCount": 3,
    "totalAmount": 135000,
    "totalFees": 675,
    "netAmount": 134325,
    "status": "completed",
    "createdAt": "2026-01-31T12:00:00Z",
    "completedAt": "2026-01-31T14:30:00Z",
    "payouts": [
      {
        "id": "pay_xyz",
        "driverId": "drv_001",
        "driverName": "John Smith",
        "amount": 45000,
        "status": "completed"
      }
    ]
  }
}

POST/api/v1/batches

Create Batch

Create a batch of payouts. The system accepts direct payout items with driver IDs and amounts.

Request Body

{
  "name": "Weekly Payouts - 2026-01-31",
  "urgency": "standard",
  "payouts": [
    {
      "amount": 45000,
      "driverId": "drv_abc123",
      "loadId": "L-12345",
      "description": "Load #12345"
    },
    {
      "amount": 50000,
      "driverId": "drv_def456",
      "loadId": "L-12346",
      "description": "Load #12346"
    },
    {
      "amount": 40000,
      "driverId": "drv_ghi789",
      "description": "Bonus payment"
    }
  ],
  "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"
  }
}

POST/api/v1/batches/:id/run

Run Batch

Process a scheduled batch immediately, regardless of its scheduled time.

Response

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

Balance

GET/api/v1/balance

Get Balance

Get wallet balance.

Response

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

Bulk Operations

Bulk operations allow you to process multiple items in a single request. All bulk operations return a result with success/failure counts and individual item results.

Max 100 items

All bulk operations accept up to 100 items per request

Partial success

Individual item failures don't abort the entire operation

Detailed results

Get status and error info for each item processed

POST/api/v1/drivers/bulk

Bulk Register Drivers

Request Body

{
  "drivers": [
    {
      "ovnDriverId": "OVN-DRIVER-789",
      "name": "John Smith",
      "email": "john@example.com",
      "phone": "+15551234567"
    },
    {
      "ovnDriverId": "OVN-DRIVER-790",
      "name": "Jane Doe",
      "email": "jane@example.com",
      "phone": "+15551234568"
    }
  ]
}

Response

{
  "success": true,
  "data": {
    "succeeded": 2,
    "failed": 0,
    "total": 2,
    "results": [
      {
        "item": {
          "id": "drv_abc123",
          "ovnDriverId": "OVN-DRIVER-789",
          "name": "John Smith",
          "status": "invited"
        },
        "status": "success"
      },
      {
        "item": {
          "id": "drv_def456",
          "ovnDriverId": "OVN-DRIVER-790",
          "name": "Jane Doe",
          "status": "invited"
        },
        "status": "success"
      }
    ]
  }
}

POST/api/v1/payouts/bulk

Bulk Create Payouts

Bulk create multiple payouts. Maximum 100 payouts per request.

Request Body

{
  "urgency": "standard",
  "payouts": [
    {
      "amount": 45000,
      "driverId": "drv_abc123",
      "loadId": "L-12345",
      "description": "Load #12345"
    },
    {
      "amount": 50000,
      "driverId": "drv_def456",
      "loadId": "L-12346",
      "description": "Load #12346"
    },
    {
      "amount": 40000,
      "driverId": "drv_ghi789",
      "description": "Bonus payment"
    }
  ]
}

Response

{
  "success": true,
  "data": {
    "succeeded": 3,
    "failed": 0,
    "total": 3,
    "results": [
      {
        "item": {
          "id": "pay_xyz",
          "driverId": "drv_abc123",
          "amount": 45000,
          "status": "validated"
        },
        "status": "success"
      },
      {
        "item": {
          "id": "pay_def456",
          "driverId": "drv_def456",
          "amount": 50000,
          "status": "validated"
        },
        "status": "success"
      },
      {
        "item": {
          "id": "pay_ghi789",
          "driverId": "drv_ghi789",
          "amount": 40000,
          "status": "validated"
        },
        "status": "success"
      }
    ]
  }
}

POST/api/v1/payouts/bulk/cancel

Bulk Cancel Payouts

Cancel multiple pending payouts at once. Maximum 100 payouts per request.

Request Body

{
  "payoutIds": ["pay_xyz", "pay_abc", "pay_def"]
}

Response

{
  "success": true,
  "data": {
    "succeeded": 3,
    "failed": 0,
    "total": 3,
    "results": [
      {
        "item": {
          "id": "pay_xyz",
          "status": "canceled"
        },
        "status": "success"
      }
    ]
  }
}

POST/api/v1/payouts/bulk/retry

Bulk Retry Payouts

Retry multiple failed payouts at once. Maximum 100 payouts per request.

Request Body

{
  "payoutIds": ["pay_xyz", "pay_abc", "pay_def"]
}

Response

{
  "success": true,
  "data": {
    "succeeded": 2,
    "failed": 1,
    "total": 3,
    "results": [
      {
        "item": {
          "id": "pay_xyz",
          "status": "queued"
        },
        "status": "success"
      },
      {
        "item": {
          "id": "pay_abc",
          "status": "queued"
        },
        "status": "success"
      },
      {
        "item": {
          "id": "pay_def",
          "status": "failed"
        },
        "status": "error",
        "error": "Insufficient funds"
      }
    ]
  }
}

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',
});

// Create a batch
const batch = await client.batches.create({
  name: 'Weekly Payouts',
  payments: [
    {
      recipientId: 'drv_001',
      amount: 50000,
      description: 'Load #1001',
    },
  ],
});