Developer Quickstart - Build Your First Payment Integration

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

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

Your keys look like:

Public Key:  op_pub_abc123xyz...
Secret Key:  op_sec_abc123xyz...

Never commit API keys to git. Use environment variables instead.

Step 2: Choose your SDK

PHP
Node.js
cURL

composer require ownpay/php-sdk

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' => '[email protected]',
    'description'  => 'Order #123'
]);

npm install ownpay

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: '[email protected]',
  description: 'Order #123'
});

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": "[email protected]",
    "description": "Order #123"
  }'

Step 3: Create your first payment

After creating a payment, you get back:

{
  "success": true,
  "data": {
    "id": "pay_abc123...",
    "amount": 5000,
    "currency": "USD",
    "status": "pending",
    "checkout_url": "https://yourdomain.com/checkout/pay_abc123",
    "customer_email": "[email protected]"
  }
}

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

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

Verify webhook signatures

PHP:

$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:

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

In your admin panel, go to Gateways
Set the gateway to Test Mode
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 - Complete API reference for PHP
Laravel SDK - Laravel facade, webhooks, and value objects
Full Node.js SDK Guide - Complete API reference for Node.js
Webhook Events - All webhook event types
Build a Plugin - Extend OwnPay with plugins

​Step 1: Generate your API key

​Step 2: Choose your SDK

​Step 3: Create your first payment

​Step 4: Handle webhooks

​Configure your webhook endpoint

​Verify webhook signatures

​Step 5: Test your integration

​Test mode

​API quick reference

​Next steps

Step 1: Generate your API key

Step 2: Choose your SDK

Step 3: Create your first payment

Step 4: Handle webhooks

Configure your webhook endpoint

Verify webhook signatures

Step 5: Test your integration

Test mode

API quick reference

Next steps