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

# Developer Quickstart - Build Your First Payment Integration

> Get started with the OwnPay REST API in five minutes by creating an API key, making your first payment intent, and receiving webhooks.

Integrate the OwnPay API in 5 minutes. Assumes you have an OwnPay instance running and admin access to generate API keys.

## Step 1: Generate your API key

1. Log in to your OwnPay admin panel
2. Go to **Developers > Developer Hub**
3. Click **Generate API Key**
4. Choose **Full Access** (or **Read-Only** for testing)
5. Copy both the **Public Key** and **Secret Key**

Your keys look like:

```text theme={null}
Public Key:  op_pub_abc123xyz...
Secret Key:  op_sec_abc123xyz...
```

<Warning>
  Never commit API keys to git. Use environment variables instead.
</Warning>

## Step 2: Choose your SDK

<Tabs>
  <Tab title="PHP">
    ```bash theme={null}
    composer require ownpay/php-sdk
    ```

    ```php theme={null}
    use OwnPay\SDK\Client;

    $client = new Client(
        publicKey: $_ENV['OWNPAY_PUBLIC_KEY'],
        secretKey: $_ENV['OWNPAY_SECRET_KEY'],
        baseUrl: 'https://yourdomain.com/api/v1'
    );

    $payment = $client->payments()->create([
        'amount'       => 5000,
        'currency'     => 'USD',
        'customer_email' => 'customer@example.com',
        'description'  => 'Order #123'
    ]);
    ```
  </Tab>

  <Tab title="Node.js">
    ```bash theme={null}
    npm install ownpay
    ```

    ```javascript theme={null}
    import OwnPay from 'ownpay';

    const ownpay = new OwnPay({
      publicKey: process.env.OWNPAY_PUBLIC_KEY,
      secretKey: process.env.OWNPAY_SECRET_KEY,
      baseUrl: 'https://yourdomain.com/api/v1'
    });

    const payment = await ownpay.payments.create({
      amount: 5000,
      currency: 'USD',
      customer_email: 'customer@example.com',
      description: 'Order #123'
    });
    ```
  </Tab>

  <Tab title="cURL">
    ```bash theme={null}
    curl -X POST https://yourdomain.com/api/v1/payments \
      -H "Authorization: Bearer op_sec_your_secret_key" \
      -H "Content-Type: application/json" \
      -d '{
        "amount": 5000,
        "currency": "USD",
        "customer_email": "customer@example.com",
        "description": "Order #123"
      }'
    ```
  </Tab>
</Tabs>

## Step 3: Create your first payment

After creating a payment, you get back:

```json theme={null}
{
  "success": true,
  "data": {
    "id": "pay_abc123...",
    "amount": 5000,
    "currency": "USD",
    "status": "pending",
    "checkout_url": "https://yourdomain.com/checkout/pay_abc123",
    "customer_email": "customer@example.com"
  }
}
```

The `checkout_url` is where your customer makes the payment.

## Step 4: Handle webhooks

When your customer completes a payment, OwnPay sends a webhook to your endpoint.

### Configure your webhook endpoint

1. Go to **Developers > Webhook Settings**
2. Enter your endpoint URL: `https://yourapp.com/webhooks/ownpay`
3. Copy the **Webhook Signing Secret**
4. Click **Save**

### Verify webhook signatures

**PHP:**

```php theme={null}
$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_OWNPAY_SIGNATURE'] ?? '';
$secret = $_ENV['OWNPAY_WEBHOOK_SECRET'];

$expectedSignature = hash_hmac('sha256', $payload, $secret);
if (!hash_equals($expectedSignature, $signature)) {
    http_response_code(401);
    exit('Unauthorized');
}

$event = json_decode($payload, true);

if ($event['type'] === 'payment.completed') {
    updateOrder($event['data']['metadata']['order_id'], 'completed');
}

http_response_code(200);
```

**Node.js:**

```javascript theme={null}
import crypto from 'crypto';

app.post('/webhooks/ownpay', express.json(), (req, res) => {
  const payload = JSON.stringify(req.body);
  const signature = req.headers['x-ownpay-signature'];
  const secret = process.env.OWNPAY_WEBHOOK_SECRET;

  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  if (signature !== expectedSignature) {
    return res.status(401).json({ error: 'Unauthorized' });
  }

  const { type, data } = req.body;

  if (type === 'payment.completed') {
    updateOrder(data.id, 'completed');
  }

  res.json({ success: true });
});
```

## Step 5: Test your integration

### Test mode

1. In your admin panel, go to **Gateways**
2. Set the gateway to **Test Mode**
3. Use test card numbers:

| Card Type  | Number              | Outcome |
| ---------- | ------------------- | ------- |
| Visa       | 4111 1111 1111 1111 | Success |
| Mastercard | 5555 5555 5555 4444 | Success |
| Amex       | 3782 822463 10005   | Success |
| Declined   | 4000 0000 0000 0002 | Failure |

## API quick reference

| Endpoint         | Method | Purpose               |
| ---------------- | ------ | --------------------- |
| `/payments`      | POST   | Create a payment      |
| `/payments/{id}` | GET    | Get payment details   |
| `/transactions`  | GET    | List transactions     |
| `/payment-links` | POST   | Create a payment link |

## Next steps

* [Full PHP SDK Guide](/developer/integration/php) - Complete API reference for PHP
* [Laravel SDK](/developer/integration/laravel) - Laravel facade, webhooks, and value objects
* [Full Node.js SDK Guide](/developer/integration/nodejs) - Complete API reference for Node.js
* [Webhook Events](/api/webhooks) - All webhook event types
* [Build a Plugin](/developer/plugin-types/gateway-development) - Extend OwnPay with plugins


## Related topics

- [Node.js SDK - TypeScript-First Payment Integration](/docs/developer/integration/nodejs.md)
- [OwnPay API Overview - REST API for Multi-Brand Payments](/docs/api/overview.md)
- [Quickstart - Get Your Payment Gateway Running in 5 Minutes](/docs/quickstart.md)
- [Install OwnPay on Shared Hosting, VPS, or Docker](/docs/installation.md)
- [AI Tools Overview - Use AI Agents for Payment Development](/docs/developer/ai-overview.md)