> ## Documentation Index
> Fetch the complete documentation index at: https://ownpay.org/docs/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> OwnPay is licensed under AGPL-3.0 and is completely free - no licensing fees.
> Production docs URL: https://ownpay.org/docs - append .md to any page URL for clean markdown.
> OwnPay requires PHP 8.3+, MySQL/MariaDB, and Redis.
> MCP server available at https://ownpay.org/docs/mcp for programmatic documentation queries.
> Use root-relative links (e.g. /quickstart) for internal navigation - do NOT include /docs prefix.
> Plugin development: consult /developer/plugin-types/ pages for correct interfaces and manifests.

# REST API Integration - Endpoints, Auth, and Examples

> Reference for integrating with the OwnPay Merchant REST API, covering authentication, endpoints, request examples, and response schemas for developers.

The OwnPay Merchant API lets you programmatically initiate payments, query transactions, issue refunds, manage customers, and manage API keys.

> Full interactive reference: [docs.ownpay.org](https://docs.ownpay.org)

## Base URL

The API is served from your brand's own custom domain:

```text theme={null}
https://{your_brand_domain}/api/v1
```

Every brand gets its own isolated API endpoint.

## Authentication

All endpoints require a **Bearer API key** in the `Authorization` header:

```http theme={null}
Authorization: Bearer op.xxxxxxxxxxxxx
```

API keys carry scopes - `read`, `write`, and `admin`.

**Get your API key:** Admin Panel > Developer Hub > API Keys > Generate

<Warning>
  API keys are shown **once** at creation. Store them in a secrets manager immediately.
</Warning>

## Response format

All responses are JSON:

```json theme={null}
{
  "success": true,
  "data": { ... }
}
```

Error responses:

```json theme={null}
{
  "success": false,
  "error": "amount must be a positive number",
  "errors": [
    {
      "code": "INVALID_AMOUNT",
      "message": "amount must be a positive number",
      "field": "amount"
    }
  ]
}
```

## HTTP status codes

| Code | Meaning                               |
| ---- | ------------------------------------- |
| 200  | OK                                    |
| 201  | Created                               |
| 400  | Bad request / business rule violation |
| 401  | Missing or invalid API key            |
| 403  | Insufficient scope / permission       |
| 404  | Resource not found                    |
| 409  | Conflict (e.g., duplicate email)      |
| 422  | Validation failure                    |
| 500  | Server error                          |

## Endpoints

### Health check

```http theme={null}
GET /health
```

Returns system status. No authentication required.

### Payments

#### Initiate payment intent

```http theme={null}
POST /payments
```

| Field            | Type         | Required | Description                               |
| ---------------- | ------------ | -------- | ----------------------------------------- |
| `amount`         | string       | Yes      | Positive numeric string, 2 decimal places |
| `currency`       | string       | Yes      | ISO 4217 code                             |
| `callback_url`   | string (URI) | No       | Webhook URL for payment completion        |
| `redirect_url`   | string (URI) | No       | Where to send customer after success      |
| `cancel_url`     | string (URI) | No       | Where to send customer if cancelled       |
| `customer_email` | string       | No       | Customer email                            |
| `customer_name`  | string       | No       | Customer full name                        |
| `reference`      | string       | No       | Your internal order/invoice ID            |
| `gateway`        | string       | No       | Route to a specific gateway slug          |
| `metadata`       | object       | No       | Arbitrary key-value map                   |

#### Retrieve payment details

```http theme={null}
GET /payments/{payment_id}
```

### Transactions

#### List transactions

```http theme={null}
GET /transactions?page=1&per_page=25&status=completed&from=2026-06-01&to=2026-06-30
```

#### Retrieve transaction

```http theme={null}
GET /transactions/{trx_id}
```

### Refunds

#### List refunds

```http theme={null}
GET /refunds
```

#### Request refund

```http theme={null}
POST /refunds
```

| Field    | Type   | Required | Description                           |
| -------- | ------ | -------- | ------------------------------------- |
| `trx_id` | string | Yes      | OwnPay transaction reference          |
| `amount` | string | No       | Partial refund amount (omit for full) |
| `reason` | string | No       | Reason for the refund                 |

### Customers

#### List customers

```http theme={null}
GET /customers?page=1&per_page=25
```

#### Create customer

```http theme={null}
POST /customers
```

| Field   | Type   | Required | Description              |
| ------- | ------ | -------- | ------------------------ |
| `name`  | string | Yes      | Customer full name       |
| `email` | string | No       | Must be unique per brand |
| `phone` | string | No       | Customer phone number    |

#### Retrieve customer

```http theme={null}
GET /customers/{identifier}
```

Looks up by email address or phone number (URL-encoded).

### API keys

> Requires `write` + `admin` scopes

#### List API keys

```http theme={null}
GET /api-keys
```

#### Generate API key

```http theme={null}
POST /api-keys
```

| Field    | Type      | Description                                                   |
| -------- | --------- | ------------------------------------------------------------- |
| `name`   | string    | Friendly label for the key                                    |
| `scopes` | string\[] | `["read"]`, `["read","write"]`, or `["read","write","admin"]` |

#### Revoke API key

```http theme={null}
DELETE /api-keys/{id}
```

### Webhooks

#### Dispatch test webhook

```http theme={null}
POST /webhooks/tests
```

#### Webhook delivery log

```http theme={null}
GET /webhooks/deliveries
```

## Quick reference

| Endpoint                   | Description        | Scope             |
| -------------------------- | ------------------ | ----------------- |
| `GET /health`              | System health      | None              |
| `POST /payments`           | Initiate payment   | `write`           |
| `GET /payments/{id}`       | Payment details    | `read`            |
| `GET /transactions`        | List transactions  | `read`            |
| `GET /transactions/{id}`   | Single transaction | `read`            |
| `GET /refunds`             | List refunds       | `read`            |
| `POST /refunds`            | Request refund     | `write`           |
| `GET /customers`           | List customers     | `read`            |
| `POST /customers`          | Create customer    | `write`           |
| `GET /customers/{id}`      | Customer details   | `read`            |
| `GET /api-keys`            | List keys          | `write` + `admin` |
| `POST /api-keys`           | Generate key       | `write` + `admin` |
| `DELETE /api-keys/{id}`    | Revoke key         | `write` + `admin` |
| `POST /webhooks/tests`     | Test webhook       | `write`           |
| `GET /webhooks/deliveries` | Delivery log       | `read`            |

## See Also

* [PHP SDK Integration](/developer/integration/php)
* [Node.js SDK Integration](/developer/integration/nodejs)
* [WordPress WooCommerce](/developer/integration/woocommerce)
* [Webhooks Setup](/api/webhooks)


## Related topics

- [OwnPay API Overview - REST API for Multi-Brand Payments](/docs/api/overview.md)
- [Node.js SDK - TypeScript-First Payment Integration](/docs/developer/integration/nodejs.md)
- [Developer Quickstart - Build Your First Payment Integration](/docs/developer/quickstart.md)
- [Webhook Delivery Log](/docs/api-reference/webhook-delivery-log.md)
- [Submit Device Heartbeat](/docs/api-reference/submit-device-heartbeat.md)